skill-writing-plans

Create zero-context implementation plans with bite-sized tasks — use for multi-step feature planning

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):

Good (Single Action)	Bad (Multiple Actions)
"Write the failing test"	"Write tests and implement"
"Run test to verify it fails"	"Make it work"
"Implement minimal code to pass"	"Add the feature"
"Commit with message"	"Finish the feature"

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

Mistake	Fix
"Add the validation"	Show exact code
"Update the tests"	Show exact test code
"In the config file"	`config/app.config.ts` line 23
"Run the tests"	`npm test path/to/specific.spec.ts`
Large tasks (30+ min)	Break into 2-5 min steps
No verification	Add "Run X, expect Y"

When to Create Plans

Scenario	Use Plan?
Multi-step feature (3+ tasks)	Yes
Simple bug fix (1 task)	No, just do it
Uncertain scope	Yes (clarifies thinking)
Delegation to subagent	Yes (zero-context execution)
Complex refactoring	Yes
Config change	No

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.

Repository: nyldn/claude-octopus
Path: skills/skill-writing-plans/SKILL.md
Commit: 9f39f0c

Last updated: 2 days ago
First committed: 3 months ago

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.