Skill Writing Plans

Host: Codex CLI — This skill was designed for Claude Code and adapted for Codex. Cross-reference commands use installed skill names in Codex rather than /octo:* slash commands. Use the active Codex shell and subagent tools. Do not claim a provider, model, or host subagent is available until the current session exposes it. For host tool equivalents, see skills/blocks/codex-host-adapter.md.

Writing Plans

MANDATORY COMPLIANCE — DO NOT SKIP

When this skill is invoked, you MUST produce a full implementation plan following the structure below. You are PROHIBITED from:

• Skipping the plan and jumping straight to implementation
• Producing a vague outline instead of the zero-context plan format
• Deciding the task is "simple enough" to not need a plan
• Omitting file paths, complete code, test instructions, or verification steps

The user asked for a plan, not an implementation. Write the plan first.

Your first output line MUST be: 🐙 **CLAUDE OCTOPUS ACTIVATED** - Implementation Planning

Overview

Write comprehensive implementation plans assuming the engineer has zero context for the codebase and questionable taste.

Document everything: which files to touch, complete code, how to test, how to verify.

Principles: DRY. YAGNI. TDD. Frequent commits.

Plan Document Structure

Header (Required)

# [Feature Name] Implementation Plan

**Goal:** [One sentence describing what this builds]

**Architecture:** [2-3 sentences about approach]

**Tech Stack:** [Key technologies/libraries]

**Estimated Time:** [X tasks × 5 min = Y minutes]


## Prerequisites

- [ ] [Any setup needed before starting]
- [ ] [Dependencies to install]
- [ ] [Files that must exist]

Task Granularity

Each task is ONE action (2-5 minutes):

Task Template

### Task N: [Component Name]

**Files:**
- Create: `exact/path/to/new-file.ts`
- Modify: `exact/path/to/existing.ts` (lines 45-67)
- Test: `tests/exact/path/to/test.spec.ts`

**Step 1: Write failing test**

```typescript
// tests/exact/path/to/test.spec.ts
describe('ComponentName', () => {
  it('should do specific thing', () => {
    const result = functionName(input);
    expect(result).toBe(expected);
  });
});

Step 2: Run test to verify it fails

npm test tests/exact/path/to/test.spec.ts

Expected output:

FAIL: expected 'expected' but got undefined

Step 3: Implement minimal code

// exact/path/to/new-file.ts
export function functionName(input: InputType): OutputType {
  // Minimal implementation
  return expected;
}

Step 4: Run test to verify it passes

npm test tests/exact/path/to/test.spec.ts

Expected output:

PASS: 1/1 tests passed

Step 5: Commit

git add tests/exact/path/to/test.spec.ts exact/path/to/new-file.ts
git commit -m "feat(component): add specific functionality"

## Example: Complete Task

```markdown
### Task 3: Add Email Validation

**Files:**
- Create: `src/validators/email.ts`
- Test: `tests/validators/email.spec.ts`

**Step 1: Write failing test**

```typescript
// tests/validators/email.spec.ts
import { validateEmail } from '../src/validators/email';

describe('validateEmail', () => {
  it('returns error for empty email', () => {
    const result = validateEmail('');
    expect(result).toEqual({ valid: false, error: 'Email required' });
  });

  it('returns error for invalid format', () => {
    const result = validateEmail('not-an-email');
    expect(result).toEqual({ valid: false, error: 'Invalid email format' });
  });

  it('returns valid for correct email', () => {
    const result = validateEmail('user@example.com');
    expect(result).toEqual({ valid: true });
  });
});

Step 2: Run test to verify it fails

npm test tests/validators/email.spec.ts

Expected: Cannot find module '../src/validators/email'

Step 3: Implement minimal code

// src/validators/email.ts
interface ValidationResult {
  valid: boolean;
  error?: string;
}

export function validateEmail(email: string): ValidationResult {
  if (!email || !email.trim()) {
    return { valid: false, error: 'Email required' };
  }

  const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
  if (!emailRegex.test(email)) {
    return { valid: false, error: 'Invalid email format' };
  }

  return { valid: true };
}

Step 4: Run test to verify it passes

npm test tests/validators/email.spec.ts

Expected: PASS: 3/3 tests passed

Step 5: Commit

git add src/validators/email.ts tests/validators/email.spec.ts
git commit -m "feat(validators): add email validation with tests"

## Integration with Claude Octopus

### Using Octopus for Plan Execution

After creating a plan, offer execution options:

```markdown
## Execution Options

**1. Sequential (this session)**
Execute tasks one by one with verification between each.

**2. Parallel (octopus tangle)**
Use Claude Octopus to parallelize independent tasks:
```bash
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh tangle "Execute implementation plan for [feature]"

3. Full workflow (octopus embrace) Research → Define → Implement → Deliver:

${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh embrace "Implement [feature] per plan"

### Plan Storage (Claude Code v2.1.10)

Claude Octopus uses session-aware plan storage. Plans are automatically saved to:

~/.claude-octopus/plans/${CLAUDE_SESSION_ID}/YYYY-MM-DD-feature-name.md

This integrates with Claude Code's `plansDirectory` setting. To customize:

```json
// settings.json
{
  "plansDirectory": "~/.claude-octopus/plans"
}

For project-local plans, save to docs/plans/:

mkdir -p docs/plans
# docs/plans/2026-01-17-user-authentication.md

Checklist for Good Plans

• Each task is 2-5 minutes (single action)
• Exact file paths (not "in the utils folder")
• Complete code (not "add validation logic")
• Exact commands with expected output
• TDD: test before implementation
• Commit after each task

Common Mistakes

When to Create Plans

Related Skills

• test-driven-development - Each task follows TDD cycle
• verification-before-completion - Verify each step
• finishing-branch - After all tasks complete

The Bottom Line

Plan exists → Engineer with zero context can execute
Otherwise → Not a complete plan

Exact paths. Complete code. Verification steps. No assumptions.