writing-plans

# Writing Plans Skill

> **Core Principle**: Exact code in plan, not descriptions of code.

## Plan Structure

Every plan MUST follow this format:

### Header (Required)

```markdown
# Feature: [Name]

> Execute with: `orchestration` skill → `executor` subagent

**Goal**: [Single sentence describing what will be built]

**Architecture**: [2-3 sentences on how it fits into existing system]

**Stack**: [Technologies/frameworks involved]
```

---

## Task Format (Required)

Each task MUST include ALL of:

### 1. File References (Exact Paths)

```markdown
## Task N: [Descriptive Name]

**Files**:
- Create: `src/components/LoginForm.tsx`
- Modify: `src/pages/auth.tsx`
- Test: `tests/LoginForm.test.tsx`
```

### 2. Steps with Complete Code

```markdown
**Steps**:

1. Write failing test:
   ```typescript
   import { render, screen } from '@testing-library/react';
   import { LoginForm } from '../src/components/LoginForm';

   test('renders email input', () => {
     render(<LoginForm />);
     expect(screen.getByLabelText('Email')).toBeInTheDocument();
   });
   ```

2. Run test:
   ```bash
   npm test -- LoginForm.test.tsx
   ```
   Expected output:
   ```
   FAIL  tests/LoginForm.test.tsx
   ✕ renders email input
   Cannot find module '../src/components/LoginForm'
   ```

3. Implement:
   ```typescript
   export function LoginForm() {
     return (
       <form>
         <label htmlFor="email">Email</label>
         <input id="email" type="email" />
       </form>
     );
   }
   ```

4. Run test:
   ```bash
   npm test -- LoginForm.test.tsx
   ```
   Expected output:
   ```
   PASS  tests/LoginForm.test.tsx
   ✓ renders email input (42ms)
   ```

5. Commit:
   ```bash
   git add src/components/LoginForm.tsx tests/LoginForm.test.tsx
   git commit -m "feat(auth): add LoginForm component with email input"
   ```
```

---

## Forbidden Language

These phrases are NOT ALLOWED in plans:

| Forbidden | Why | Write Instead |
|-----------|-----|---------------|
| "Add validation