planning

Files (2)

• SKILL.md
• plan-document-reviewer-prompt.md · references/

SKILL.md (first lines)

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

| Step | Example |
|------|---------|
| Write failing test | `test_user_creates_account` |
| Run test, confirm failure | `pytest ... -v` -> FAIL |
| Implement minimal code | function body |
| Run test, confirm pass | `pytest ... -v` -> PASS |
| Commit | `git commit -m "feat: ..."` |

## Plan Header

Every plan starts with:

```markdown
# [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

````markdown
### 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.

From renathoaz/arsyn, MIT.

More from renathoaz/arsyn