plan

Files (3)

• README.md
• SKILL.md
• reviewer-prompt.md · references/

SKILL.md (first lines)

# Plan

Turn an approved SpecScore Feature (or Idea) into a lint-clean, ordered task list.

## Hard Gate

<HARD-GATE>
Do NOT invoke `specstudio:implement`, `writing-plans`, `frontend-design`, `mcp-builder`, or ANY implementation skill until ALL of the following are true:
  1. The Plan artifact exists at `spec/plans/<slug>.md` and contains at least one `### Task N: <name>` task inside the `## Tasks` section.
  2. Every acceptance criterion in the source Feature is either covered by ≥1 task (via the task's `**Verifies:**` line) OR explicitly listed under `## Deferred AC Coverage` with a concrete one-sentence reason. *(Skip in Idea-sourced mode — there are no ACs.)*
  3. `specscore spec lint` passes.
  4. The plan-document reviewer subagent returned `Approved`.
  5. The user has explicitly approved the written Plan.

The only skill invoked after `specstudio:plan` is `specstudio:implement` (or — while `implement` is unshipped — a hand-back to the user with that recommendation).
</HARD-GATE>

## When to Use

- A SpecScore Feature is `**Status:** Approved` and the user is ready to decompose it into work.
- A SpecScore Idea is `**Status:** Approved` and the user wants to plan directly from it without a Feature.
- The event `feature.approved` has fired and the user has confirmed they want to plan.
- The user wants to revise an existing approved Plan (revise-in-place by default).

**Refuse and redirect when:**

- The source Feature is `Draft` or `In Review` → tell the user to run `specstudio:specify` to approve the Feature first. Do **not** plan against unapproved specs.
- The source Idea is `Draft` or `In Review` → tell the user to approve the Idea first. Do **not** plan against unapproved Ideas.
- The request spans two or more Features → say so and offer to write two separate Plans.
- The user asks for a DAG / parallel-branch plan → linear-only is the MVP; offer a linearized best-effort order or defer.

## Pre-Flight

1. **Source artifact check.** Resolve the input to one of:
   - **Feature-sourced (default):** a path `spec/features/<feature-slug>/README.md`. Confirm `**Status:**` is one of `{Approved, Implementing, Stable}`. If not, stop and recommend `specstudio:specify`.
   - **Idea-sourced:** a path `spec/ideas/<slug>.md`. Confirm `**Status:** Approved`. If not, stop and tell the user to approve the Idea first. When an Idea is the source, enter **Idea-sourced mode** — the remaining steps note where behavior differs.
2. **Parse AC list.** *(Skip in Idea-sourced mode — Ideas have no formal ACs; proceed to step 3.)* Read the source Feature's `## Acceptance Criteria` section. Build the full list of AC slugs — each `### AC: <slug>` heading or each inline `Scenario:` AC block with an explicit `verifies REQ:<slug>` reference. This list is the AC-coverage contract; every entry must be accounted for in the final Plan.
3. **Slug derivation.** Default Plan slug = source Feature slug. If the user explicitly asks for an alternative breakdown ("a spike plan", "a stable plan"), use `<feature-slug>-<variant>` (single segment, lowercase, hyphen-separated, URL-safe). Refuse chained-variant suffixes.
4. **Existing-plan check.** If `spec/plans/<slug>.md` already exists, ask the user: revise in place (default), supersede with a new plan that invalidates the prior task list, or pick a different variant suffix.
5. **Single-source scope.** If the user's intent references work in more than one Feature or Idea, stop and offer to write two Plans.

## Checklist

Create a task for each and complete in order:

1. **Pre-flight** (steps above).
2. **Convergent task-breakdown dialogue.** In Feature-sourced mode: walk the AC list with the user. For each AC, decide: dedicated task / bundled into a multi-AC task / deferred to `## Deferred AC Coverage` with a reason. In Idea-sourced mode: walk the Idea's goals and scope with the user, decomposing into concrete tasks without AC mapping. Keep the conversation tight — batched questions, multiple-choice where possible.
3. **Order tasks linearly 1..N.** Respect inferable dependencies (an AC whose precondition is established by another AC's task). No gaps, no DAG, no parallel branches in the MVP.
4. **Create the Plan artifact** — run `specscore plan new <slug>` with its source flag (the required-CLI creation path; see `## Artifact Creation`), then FILL the scaffolded sections via `Edit`.
5. **Directory + index** — `specscore plan new` creates `spec/plans/` and its `README.md` index if absent. Tell the user the directory is being bootstrapped.
6. **Checkpoint manifest** — add all created or edited Plan paths and CLI-reported touched paths to the publication manifest.
7. **Lint** — `specscore spec lint`. On failure, run `specscore spec lint --fix` exactly once and re-lint; on persistent failure, surface violations with rule IDs and stop.
8. **Inline self-review** — placeholders, empty `**Verifies:**` lines, AC IDs that look misspelled vs the source Feature, task-name vs `**Verifies:**` contradictions.
9. **Status: Draft → In Review.**
10. **Dispatch the baseline reviewer subagent** — see [reviewer-prompt.md](references/reviewer-prompt.md). Must return `Approved` before user review.
11. **Dispatch additional registered reviewers** (if any) from `specscore.yaml`'s `reviewers:` extension key. AND composition — every reviewer must return `Approved`.
12. **Publish + emit `plan.drafted`** after all reviewers Approved + lint passes: apply [publication-policy.md](../shared/publication-policy.md) for `plan.drafted`, then emit the event with `publication_result`.
13. **User review gate** — present the Plan with the summary of deferred ACs (if any) and explicitly ask for approval.
14. **On user approval** — status In Review → Approved, re-run lint, apply publication policy for `plan.approved`, then emit `plan.approved` with `publication_result`.
15. **Transition to `specstudio:implement`** — or, while `implement` is unshipped, hand back with the recommendation that the user implement task-by-task using a general-purpose skill.
16. **Throughout** — watch for sidekick ideas. When an out-of-scope improvement surfaces (e.g., a Feature change), invoke `specstudio:sidekick` with a one-liner, acknowledge in one line, and return to the current checklist step immediately. Do not derail.

## Artifact Layout

Plans are **single files**, not directories. Unlike Features, a Plan has no `_tests/` or `assets/` siblings in the MVP.

```
spec/plans/
├── README.md                # Plans index
└── <slug>.md                # The Plan artifact (single file per plan)
```

The skill carries **no embedded schema** — `specscore plan new` is the single source of truth for the Plan's structure (title prefix, body metadata, the `## Summary` / `## Approach` / `## Tasks` / `## Deferred AC Coverage` / `## Open Questions` sections, and the adherence footer). For a read-only spec reference, see [`https://specscore.md/plan-specification`](https://specscore.md/plan-specification) — never fetch it to write the file; the CLI scaffold produces the canonical structure.

## Artifact Creation

**Creation is required-CLI.** `specscore plan new <slug>` is the ONLY way to create the Plan artifact — it produces a lint-clean skeleton by construction and bootstraps `spec/plans/` and its `README.md` index for you. There is **no direct-write fallback**: the CLI scaffold is the single source of truth for the Plan's structure. This follows the Required-CLI Artifact Creation policy — see the **Creation-class row** in [`../shared/cli-detection.md`](../shared/cli-detection.md).

### Step 1 — Run the creation call and branch on exit status

Do **not** run a standalone `command -v` probe. Invoke `specscore plan new <slug>` with **exactly one** source flag — `--feature <feature-slug>` (default) or `--idea <idea-slug>` — and branch on its exit status per the **Creation-class row** in [`../shared/cli-detection.md`](../shared/cli-detection.md) (which carries the per-outcome rationale): **`0`** → scaffold written, continue to Step 2; **`127`** → install message (`/specscore:install`), then **install-then-retry**; **exit `8`** → **upgrade-then-retry**, naming the missing `plan new` subcommand; **any other non-zero** → surface verbatim, **never** a direct-write fallback.

### Step 2 — Fill the scaffolded sections

With the lint-clean skeleton in place, FILL its sections via `Edit`: the `## Summary`, the `## Approach`, each `### Task N` entry with its `**Verifies:** <feature-slug>#ac:<ac-slug>` line (Feature-sourced) or `**Source:** idea:<slug>` line (Idea-sourced), the `## Deferred AC Coverage` section (Feature-sourced only; omit when no ACs are deferred), and `## Open Questions`. Preserve the scaffold's lint-clean structure — never replace it with a hand-authored layout.

**Idea-sourced differences:** `**Source:** idea:<slug>` replaces `**Source Feature:**` in body metadata. Tasks use `**Source:** idea:<slug>` instead of `**Verifies:**`. The `## Deferred AC Coverage` section is omitted (there are no ACs to defer).

**Schema notes:**

- The canonical id is the file slug; there is no separate `id` field.
- **Feature-sourced plans:** `**Source Feature:**` is **required** and MUST resolve to an existing Feature at `spec/features/<feature-slug>/README.md` with `**Status:**` in `{Approved, Implementing, Stable}`.
- **Idea-sourced plans:** `**Source:** idea:<slug>` is **required** and MUST resolve to an existing Idea at `spec/ideas/<slug>.md` with `**Status:** Approved`.
- `**Supersedes:**` MUST be present with value `—` when empty.
- Tasks are numbered linearly starting from 1 with no gaps.
- **Feature-sourced:** every task MUST have a `**Verifies:**` line listing ≥1 AC ID from the source Feature. AC IDs use the form `<feature-slug>#ac:<ac-slug>` so they are unambiguous when planning across Features in the future.
- **Idea-sourced:** every task MUST have a `**Source:** idea:<slug>` line referencing the source Idea. No AC IDs are required.

## AC Coverage Contract

The defining discipline of `plan`: **every AC in the source Feature is accounted for, exactly once.** Either:

1. Listed in at least one task's `**Verifies:**` line, OR
2. Listed under `## Deferred AC Coverage` with a one-sentence reason that names *why* and *when* (e.g., "Deferred to v2; waits on the third-party SDK release"; "Out of MVP scope; covered by the follow-on `<slug>` plan").

**Lint enforces this as `P-001`** (hard rule, not advisory). The reviewer subagent enforces it semantically (catches stale AC references, vague defer-reasons, AC-wrapper tasks).

Silent omission of an AC is a contract violation.

**Idea-sourced exemption:** When a Plan is sourced from an Idea (`**Source:** idea:<slug>`), the AC coverage contract does not apply — there are no ACs to enforce coverage against. Lint rule `P-001` does not fire for Idea-sourced plans. All other lint rules and gates still apply.

## Task Format

Each task MUST have:

1. A `### Task N: <task-name>` heading (numbered linearly).
2. **Feature-sourced:** a `**Verifies:** <feature-slug>#ac:<ac-slug>, …` line listing one or more AC IDs from the source Feature. **Idea-sourced:** a `**Source:** idea:<slug>` line referencing the source Idea.
3. A 1–3 sentence prose description.

From specscore/specstudio-skills, MIT.

More from specscore/specstudio-skills