Planning

Transform an approved spec into a step-by-step implementation plan that an engineer with zero project context can follow.

Announce at start: "Generating implementation plan using arsyn:planning."

Save to: docs/arsyn/plans/YYYY-MM-DD-<feature-name>.md (user preference overrides)

Scope Gate

If the spec covers multiple independent subsystems, it should have been split during ideation. If it was not, recommend separate plans — one per subsystem. Each plan must produce working, testable software on its own.

File Map

Before defining tasks, enumerate every file that will be created or modified and its responsibility. This locks in decomposition decisions.

• One clear responsibility per file. Prefer focused files over large ones.
• Files that change together live together. Split by responsibility, not by layer.
• Follow existing codebase patterns. If a file you are modifying has grown unwieldy, include a split in the plan.

Task Granularity

Each step is a single action (2-5 minutes):

Plan Header

Every plan starts with:

# [Feature] Implementation Plan

> **For agents:** Use arsyn:orchestrating (preferred) or arsyn:executing to run this plan. Steps use `- [ ]` checkboxes.

**Goal:** [One sentence]

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

**Tech Stack:** [Key technologies]

---

Task Format

### Task N: [Name] `[CONFIDENCE: HIGH|MEDIUM|LOW]`

**Files:**
- Create: `src/exact/path.py`
- Modify: `src/existing/file.py:40-55`
- Test: `tests/exact/test_path.py`

- [ ] **N.1 Write failing test**

```python
def test_behavior():
    assert function(input) == expected
```

- [ ] **N.2 Confirm failure**

Run: `pytest tests/path/test.py::test_behavior -v`
Expect: FAIL — `NameError: function not defined`

- [ ] **N.3 Implement**

```python
def function(input):
    return expected
```

- [ ] **N.4 Confirm pass**

Run: `pytest tests/path/test.py::test_behavior -v`
Expect: PASS

- [ ] **N.5 Commit**

```bash
git add src/exact/path.py tests/exact/test_path.py
git commit -m "feat: add behavior"
```

Review Loop

1. Dispatch plan-document-reviewer subagent (see references/plan-document-reviewer-prompt.md) with crafted context — never raw session history. Provide plan path and spec path.
2. Issues found: fix and re-dispatch.
3. Approved: proceed to handoff.
4. If loop exceeds 3 iterations, surface to user.

Reviewers are advisory. Explain disagreements if you believe feedback is wrong.

Execution Handoff

After saving and committing the plan:

"Plan saved to docs/arsyn/plans/<filename>.md. Two execution modes:

1. Orchestrated (recommended) — Fresh subagent per task with review between tasks.

2. Inline — Execute tasks sequentially in this session with checkpoint reviews.

Which approach?"

• Orchestrated: invoke arsyn:orchestrating
• Inline: invoke arsyn:executing

Gotchas

• Vague steps — "Add validation" is not a step. Every step contains complete, copy-pasteable code or an exact command with expected output.
• Oversized tasks — If a task takes longer than 5 minutes, split it.
• Missing verification commands — Every "confirm" step needs the exact command and expected result.
• Fabricated paths — Verify file paths against the actual project tree before writing them into the plan.
• Implementation before tests — Every feature task starts with a failing test.
• Missing commit steps — Each red-green cycle ends with a commit.
• Assumed context — Plans must be self-contained. Do not write "follow the existing pattern" — show the pattern.