plan

Files (6)

• SKILL.md
• architecture.md · roles/
• instructions.md · roles/
• project.md · roles/
• roadmap.md · roles/
• verification.md · roles/

SKILL.md (first lines)

# fsad-harness:plan — Large-Initiative Planning Agent

Follow these phases in order. Show each artifact to the user for approval before moving to the
next phase. Never generate all five documents unattended — each phase checkpoints.

## Asking the user

This rule covers every question this skill asks the user: a confirmation, a choice, a missing value, a numbered decision list, or a stop-and-ask. It applies even where a later step says "ask the user" or "ask exactly once". The user may watch the decisions pane rather than the chat, so a question that only goes to chat can go unanswered.

- **When `mcp__decision-tracker__decision` is in your tool list** (loaded, or named as a deferred tool; load a deferred one with `ToolSearch` first), log each question before you ask it:
  1. Call it with `action: "open"`, the question (ending in `?`), and `options` when the answers are a closed set. Set `required: false` when the work can go on without an answer. A numbered list of questions opens one decision per item. Keep each returned `id`.
  2. Ask the question in chat as this skill says. The open call does not replace the chat question.
  3. When the user answers, in chat or as a `Decision Dn: <answer>` message from the plugin, call the tool with `action: "close"`, the `id` and the answer.
  4. When the change the answer asked for is in place, call it with `action: "implement"`, the `id` and a `path:line`.
- **When the tool is absent**, ask in chat only.
- An `AskUserQuestion` call is logged on its own. Do not open it again.
- This rule changes where a question is logged. It does not change when this skill asks, or how many times.

## Role files

This skill uses five specialist role briefs loaded from `roles/`:
- `project.md` — drafts the initiative's Project Overview
- `architecture.md` — drafts the Architecture document
- `instructions.md` — drafts the Standing Instructions
- `roadmap.md` — drafts the Roadmap
- `verification.md` — drafts the Verification Plan

**If any role file is missing:** stop immediately and tell the user: *"`roles/{file}.md` is missing — this skill needs its role-brief files to run. Reinstall the `fsad-harness` plugin, then re-run this command."* Do not improvise a persona for a missing role file.

## Phase 0 — Context (mandatory, not skippable)

Invoke the `fsad-harness:set-context` skill now (as a subskill — see its own SKILL.md for its invocation
model: it runs inline, not as a fire-and-forget subagent). **If a target repo path was supplied
as this skill's second argument, pass it through as `set-context`'s explicit path argument** so
it resolves the target from that path rather than the current working directory; otherwise
`set-context` defaults to the current working directory per its own Step 1. This produces
`context.md` and, as part of its Step 3, asks the user for the initiative's slug/name.

Once the slug is known, resolve the output directory: `planning/plan/<slug>/` in the target repo
(from `context.md`'s Target repo answer). The slug transform is deterministic and fixed:
lowercase the initiative name, replace every run of non-alphanumeric characters with a single
hyphen, then trim any leading or trailing hyphen (e.g. "Auth Service Refactor!" →
`auth-service-refactor`) — no hash suffix or other uniquifier is ever appended, so the same name
always resolves to the same directory.

**If `planning/plan/<slug>/` already exists**, ask the user how to proceed: overwrite, resume, or
choose a different slug. Never write over it silently.

**"Choose a different slug" is a narrow re-ask, not a full `set-context` re-invocation:** ask only
the slug question again and re-resolve the output path. Do not re-run `set-context`'s graphify
build, manual sweep, or its other targeted questions (scope/constraints/stakeholders/versioning)
— the user already answered those.

If the directory doesn't exist yet, create it and move `context.md` into it if `set-context` wrote
it to a scratch location.

## Phase 1 — `project.md`

Read `roles/project.md` for the full brief. Dispatch one `Agent` **with
`name: "plan-project-<slug>"`** (so it stays addressable via `SendMessage` for Phase 4.5), giving
it the role brief and the path to `context.md`. Wait for it to finish before showing the draft.

Show the draft path to the user: *"`project.md` written. Review it and tell me what to change, or
say 'approved' to move to the Architecture and Instructions phase."*

Do not proceed until the user approves.

## Phase 2 — `architecture.md` and `instructions.md` (parallel)

Read both `roles/architecture.md` and
`roles/instructions.md`. Dispatch **two `Agent` calls in a single message**
— both depend only on `project.md` and `context.md`, not on each other, so they run concurrently:
- `name: "plan-architecture-<slug>"`, given the architecture role brief, `context.md`, and
  `project.md`.
- `name: "plan-instructions-<slug>"`, given the instructions role brief, `context.md`, and
  `project.md`.

Wait for both to finish before showing either draft.

Show both draft paths to the user: *"`architecture.md` and `instructions.md` written. Review them
and tell me what to change, or say 'approved' to move to the Roadmap phase."*

Do not proceed until the user approves.

## Phase 3 — `roadmap.md`

Read `roles/roadmap.md`. Dispatch one `Agent` (no `name:` needed — nothing
resumes this one later) with the role brief, `context.md`, `project.md`, and the finished
`architecture.md`. This phase is sequential — it depends on `architecture.md`'s target layout to
define phases and a dependency graph, so it does not start until Phase 2 is fully approved.

Show the draft path to the user: *"`roadmap.md` written. Review it and tell me what to change, or
say 'approved' to move to the Verification phase."*

Do not proceed until the user approves.

## Phase 4 — `verification.md`

Read `roles/verification.md`. Dispatch one `Agent` (no `name:` needed) with
the role brief, `context.md`, `project.md`, `architecture.md`, and the finished `roadmap.md`. This
phase is sequential — it depends on `roadmap.md`'s phase list to produce per-phase checklists, so
it does not start until Phase 3 is approved.

Show the draft path to the user: *"`verification.md` written. Review it and tell me what to
change, or say 'approved' to move to the reconciliation pass."*

Do not proceed until the user approves.

## Phase 4.5 — Reconciliation pass

Re-open `project.md`, `architecture.md`, and `instructions.md` and backfill cross-references to
`roadmap.md`/`verification.md` sections now that they exist — all three documents were drafted
before Phase 3/4 and have the same forward-reference gap (`project.md`'s own phase-reference
skeleton and done-when checklist, not just architecture/instructions).

**Resume the same named specialist agents that drafted each document** — not fresh agents, and not
this orchestrating thread — via `SendMessage`:

1. `SendMessage` to `plan-project-<slug>`, adding the finished `roadmap.md` and `verification.md`

From tbeack/fsad_playbook, MIT.

More from tbeack/fsad_playbook