Claude Code helper for SPECLAN - manage project specifications as interlinked markdown files

version
0.5.0
GitHub stars
8

Install

/plugin install speclan@digital-dividend-marketplace

Run it inside Claude Code after adding the marketplace with /plugin marketplace add thlandgraf/cc-marketplace.

Contents

Discovered from source

Skills 10

SPECLAN Ask

Answer questions about SPECLAN specifications holistically. A spec rarely lives on its own — its ancestors, siblings, contributing goal, child entities, change requests, and implementation status all matter. The goal is to give the user a comprehensive, contextual answer — not just dump a single file.

Core Principle: Context Over Content

Do not just read and parrot a single file. Instead, build a contextual picture:

  1. The entity itself — frontmatter + body summary
  2. Upward — parent feature, contributing goal(s)
  3. Downward — child requirements, nested features
  4. Sideways — sibling requirements/features at the same level
  5. Change history — active change requests on this entity
  6. Status context — what the status means for editability and next steps

Workflow

1. Locate the Speclan Root

Use the detection script to find the speclan directory:

SPECLAN_ROOT=$(node "${CLAUDE_PLUGIN_ROOT}/skills/speclan-format/scripts/detect-speclan.mjs")

If no speclan root is found, inform the user that no SPECLAN project was detected.

2. Identify What the User Is Asking About

Parse the user's question to determine:

  • By ID — F-0471, R-0311, G-001, CR-0012 → locate directly via query script
  • By name/slug — "alien grid movement", "core gameplay" → search filenames and titles
  • By type — "all features", "approved requirements" → use query with filters
  • By relationship — "children of F-0471", "what contributes to G-001" → use parent filtering
  • By status — "what's in development", "approved specs" → use status filtering

3. Gather the Entity

Use the query script for discovery:

node "${CLAUDE_PLUGIN_ROOT}/skills/speclan-query/scripts/query.mjs" \
  --type all --full "$SPECLAN_ROOT"

For targeted lookups, filter by type and optionally parent:

node "${CLAUDE_PLUGIN_ROOT}/skills/speclan-query/scripts/query.mjs" \
  --type feature --filter-status approved "$SPECLAN_ROOT"

Then read the entity's markdown file for full content.

4. Build Contextual Picture

For every entity found, gather its context using the relationship exploration procedure in references/context-gathering.md. This is the core of the skill — it turns a flat file read into a rich, interconnected answer.

5. Compose the Answer

Structure the response based on what the user asked:

Single Entity Question ("tell me about F-0471")

Present in this order:

  1. Identity — ID, title, type, status, owner
  2. Status meaning — editable/locked/frozen, what transitions are possible (consult speclan-format skill for lifecycle rules)
  3. Goal alignment — which goal(s) this contributes to, with goal titles
  4. Parent context — if requirement: the parent feature; if nested feature: the parent feature
  5. Body summary — concise summary of the spec content (description, acceptance criteria, key points)
  6. Children — list child requirements or sub-features with their statuses
  7. Siblings — other entities at the same level (fellow requirements under same feature, fellow features under same goal)
  8. Change requests — any active CRs on this entity or its children
  9. Cross-references — any tags that connect to other entities, any mentions in other specs
Status/Filter Question ("what's approved", "show in-development features")

Present as a structured table:

IDTitleTypeParentOwner

Group by goal or parent feature for readability.

Relationship Question ("children of F-0471", "what contributes to G-001")

Present the relationship tree, showing status badges:

G-001 Core Game Experience [released]
  F-0471 Core Gameplay [in-development]
    R-0311 Lateral March Edge Reversal [approved]
    R-0312 Descent After Reversal [in-development]
    ...

6. Add Actionable Context

Based on status and relationships, suggest relevant next steps:

  • draft entities → "Ready for review when content is complete"
  • approved entities → "Ready for implementation. Use /speclan:plan-manual to create an implementation plan"
  • in-development with all children done → "Consider moving to under-test"
  • Entity with active CRs → "Has N pending change request(s) — review before proceeding"
  • Orphan entities (no goal link) → "Not linked to any goal — consider adding goal alignment"

Status Badge Reference

Use these inline badges for compact status display:

StatusBadge
draft[draft]
review[review]
approved[approved]
in-development[in-dev]
under-test[testing]
released[released]
deprecated[deprecated]

Important Boundaries

This skill is read-only — it answers questions but doesn't modify specs. If the user wants to change something, point them to the appropriate command or skill (e.g., implement-manual for implementation, or direct editing for draft-status specs). This separation matters because answering questions and making changes are different intents, and accidental modifications while exploring can be disruptive.

Extract entity IDs from filenames/dirnames rather than frontmatter — the filename pattern {PREFIX}-{ID}-{slug} is the authoritative source of truth across all SPECLAN tools.

The hierarchy flows Goal → Feature → Requirement, with features nesting under other features. Requirements are always leaf nodes. When locked entities (in-development, under-test, released) come up, mention that changes require a Change Request — this is often the most actionable piece of context for the user.

Additional Resources

Reference Files

  • references/context-gathering.md — detailed procedure for building the contextual picture around any entity, including upward/downward/sideways/CR exploration steps

Leveraged Skills

This skill builds on knowledge from:

  • speclan-format (${CLAUDE_PLUGIN_ROOT}/skills/speclan-format/SKILL.md) — entity hierarchy, status lifecycle, field definitions, validation rules
  • speclan-query (${CLAUDE_PLUGIN_ROOT}/skills/speclan-query/SKILL.md) — fast entity discovery and filtering via scripts/query.mjs

SPECLAN Tree Checker

Scans a speclan/ tree and reports every consistency violation — file structure, YAML frontmatter, ID format & uniqueness, directory/naming rules, entity placement, and cross-reference integrity. Each issue names the rule broken, explains it in one line, and gives a fix hint.

The heavy lifting is a zero-dependency Node.js script (check-tree.mjs) — no jq/js-yaml/external tools. It is the primary agent path; there is no GUI.

Run (agent path)

Script location

${CLAUDE_PLUGIN_ROOT}/skills/check-speclan-tree/scripts/check-tree.mjs

Command line

node "${CLAUDE_PLUGIN_ROOT}/skills/check-speclan-tree/scripts/check-tree.mjs" [OPTIONS] [speclan-dir]

Options:

  • --json — machine-readable report instead of grouped text
  • --strict — treat warnings as failures (exit 1 on any warning)
  • --fix — auto-fix safe, unambiguous issues in place, then report what was fixed and what remains (see Auto-fix)
  • -h, --help — usage

Arguments:

  • speclan-dir — path to the speclan directory. If omitted, the script auto-detects it (walks up looking for speclan/, specs/speclan/, …), else falls back to ./speclan.

Exit codes: 0 = clean (no errors; and no warnings under --strict), 1 = issues found or usage error.

Example — a clean tree

node "${CLAUDE_PLUGIN_ROOT}/skills/check-speclan-tree/scripts/check-tree.mjs" speclan
✓ No issues found — checked 4 entities.

Example — a tree with problems (grouped text, default)

speclan/features/F-2000-mismatch-dir/F-2000-wrong-name.md
  ✖ SPEC011 dir-file-name-mismatch  directory "F-2000-mismatch-dir/" contains "F-2000-wrong-name.md" — directory name and entity filename must match
      hint: rename the file to "F-2000-mismatch-dir.md" (or rename the directory to "F-2000-wrong-name/")

speclan/features/F-4000-dup-a/F-4000-dup-a.md
  ✖ SPEC010 duplicate-id  ID F-4000 is used by 2 entities: features/F-4000-dup-a, features/F-4000-dup-b
      hint: IDs must be unique across the whole tree — regenerate one with the speclan-id-generator skill

speclan/features/F-6000-many-issues/F-6000-many-issues.md
  ✖ SPEC005 invalid-id-format  id "F-50" does not match the feature format /^F-\d{4}$/
      hint: use F-#### (zero-padded)
  ✖ SPEC006 id-filename-mismatch  frontmatter id "F-6999" ≠ filename id "F-6000"
      hint: the filename is the source of truth — set id: F-6000, or rename the file/dir to match "F-6999"
  ⚠ SPEC014 h1-title-mismatch  body does not start with an H1 heading matching the title "Many Issues"
      hint: make the first non-empty body line "# Many Issues"

Summary: 11 errors, 2 warnings across 8 files (8 checked)  →  FAIL

JSON report (for tooling / CI)

node "${CLAUDE_PLUGIN_ROOT}/skills/check-speclan-tree/scripts/check-tree.mjs" --json speclan
{
  "ok": false,
  "summary": { "errors": 11, "warnings": 2, "filesChecked": 8, "entityCount": 9 },
  "issues": [
    {
      "rule": "SPEC011",
      "name": "dir-file-name-mismatch",
      "severity": "error",
      "file": "speclan/features/F-2000-mismatch-dir/F-2000-wrong-name.md",
      "message": "directory \"F-2000-mismatch-dir/\" contains \"F-2000-wrong-name.md\" — directory name and entity filename must match",
      "hint": "rename the file to \"F-2000-mismatch-dir.md\" (or rename the directory to \"F-2000-wrong-name/\")"
    }
  ]
}

Extract just the failing rules:

node "${CLAUDE_PLUGIN_ROOT}/skills/check-speclan-tree/scripts/check-tree.mjs" --json speclan \
  | grep -oE '"rule": "[^"]+"' | sort | uniq -c | sort -rn

Gate warnings too

node "${CLAUDE_PLUGIN_ROOT}/skills/check-speclan-tree/scripts/check-tree.mjs" --strict speclan

Auto-fix (--fix)

Rewrites the safe, unambiguous issues in place (frontmatter only — no file moves, no body edits), then reports what was fixed and what still needs a human. Changes are reversible via git diff / git checkout.

node "${CLAUDE_PLUGIN_ROOT}/skills/check-speclan-tree/scripts/check-tree.mjs" --fix speclan
speclan/features/F-6000-many-issues/F-6000-many-issues.md
  ✔ SPEC006 id-filename-mismatch (fixed)  frontmatter id "F-6999" ≠ filename id "F-6000"
  ✔ SPEC009 updated-before-created (fixed)  updated (2026-04-01) is earlier than created (2026-05-01)
  ✖ SPEC002 missing-required-field  required field "owner" is missing or empty
      hint: add "owner:" to the frontmatter with a non-empty value

Fixed 2 issues. Summary: 9 errors, 2 warnings remaining across 8 files (8 checked)  →  FAIL

What --fix repairs (only these — everything else needs judgment and is left as a reported issue):

RuleFix applied
SPEC004 invalid-statusMigrate a retired legacy status: pending → draft, merged → under-test, closed → deprecated. Other invalid statuses are left reported.
SPEC006 id-filename-mismatchSet frontmatter id to the filename ID (the filename is authoritative)
SPEC008 invalid-timestampReformat to canonical ISO only for numeric-but-malformed dates (2026/01/05 → 2026-01-05, 2026-01-06 09:30 → 2026-01-06T09:30:00Z). Uses string manipulation only — never shifts the calendar day. Free-form dates (e.g. January 6, 2026) are left untouched and still reported.
SPEC009 updated-before-createdClamp updated to created

--fix is idempotent (a second run fixes nothing) and combines with --json (each fixed issue gets "fixed": true; the summary gains a fixed count). It exits 0 only if no issues remain after fixing.

What it checks

Each issue carries a stable SPEC### code. Errors fail the run; warnings only fail under --strict.

CodeSeverityRule
SPEC001errorFile has no --- … --- YAML frontmatter block
SPEC002errorMissing/empty required field (id, type, title, status, owner, created, updated)
SPEC003errortype not one of goal, feature, requirement, changeRequest, template (accepts the change-request alias)
SPEC004errorstatus not in the lifecycle draft, review, approved, in-development, under-test, released, deprecated (same set for all entities incl. CRs); or invalid CR changeType
SPEC005errorid fails its format: G-### (3 digits), F/R-####, CR-#### (4 digits), Template = UUID v4
SPEC006errorFrontmatter id ≠ ID parsed from the filename (filename is the source of truth)
SPEC007errorDeclared type prefix ≠ id prefix (e.g. type: goal with an F- id)
SPEC008errorcreated/updated not valid ISO-8601
SPEC009errorupdated is an earlier calendar day than created
SPEC010errorDuplicate ID across the whole tree
SPEC011errorDirectory-based entity: directory name ≠ contained .md filename
SPEC012errorMisplaced entity (requirement not under requirements/, CR not under change-requests/, goal not in goals/, child feature under the wrong folder)
SPEC021errorEntity directory has no matching .md file (empty/missing entity file)
SPEC015errorBroken reference: goals/feature/parentId/contributors points at a non-existent ID (or wrong type)
SPEC016errorCR parentType ≠ the actual type of parentId's target
SPEC017errorCR missing a required field (parentId, parentType, changeType)
SPEC013warnFilename slug ≠ kebab-case of title (truncation- and stopword-tolerant)
SPEC014warnBody's first non-empty line is not # {title} (H1 must match the title, no prose before it)
SPEC018warnRelative […](../x.md) link in the body doesn't resolve on disk
SPEC019warnOne-directional link (e.g. goal lists a feature as contributor but the feature's goals omits it)
SPEC020warnStray .md inside an entity subtree that isn't a valid entity file
SPEC022warnFeature has no goals (sub-features may inherit via their parent)

SPEC004 (legacy statuses only), SPEC006, SPEC008, SPEC009 can be repaired automatically with --fix.

Skipped (not scanned): templates/, artifacts/, _archived/, .local/, dot-directories, and root docs (mission.md, vision.md, AGENTS.md, CLAUDE.md, README.md).

Gotchas

These are calibrated against real speclan trees — the checker deliberately does not flag them:

  • Truncated slugs are fine. F-3683-security-and-authenticati/ matching its own .md is valid even though the slug is cut mid-word; SPEC011 only fires on a true dir≠file mismatch, and SPEC013 treats the slug as a prefix of the title.
  • type: change-request (kebab) is accepted alongside changeRequest — it is the dominant on-disk spelling and a documented tooling alias.
  • A requirement's parent is structural. feature: in requirement frontmatter is optional (the …/F-####/requirements/ directory is authoritative). When present, it must resolve and agree with that directory (else a SPEC019 warning), but its absence is never an error.
  • CR narrative lives in the body, so description/changes are not required frontmatter — only parentId, parentType, changeType are.
  • Date-only vs timestamp on the same day (updated: 2026-05-21 after created: 2026-05-21T08:…Z) is not a SPEC009 hit — comparison is by calendar day when either value is date-only.

Warnings can be voluminous on a large, evolving tree (slug/title drift, missing goals). That is expected — filter by severity: "error" in --json mode, or run without --strict to keep the exit code driven by errors only.

Troubleshooting

SymptomCause / fix
ERROR: SPECLAN directory not foundPass the path explicitly: check-tree.mjs path/to/speclan. Auto-detect needs a speclan/ (or specs/speclan/, .speclan/) with a features/ or goals/ child at or above the cwd.
Exit 1 but only warnings listedYou passed --strict. Drop it to let errors alone drive the exit code.
A real entity is reported SPEC020 stray-fileIts filename doesn't match <ID>-<slug>.md (G/F/R/CR), or it sits loose inside an entity directory. Rename it or move it under artifacts/.
SPEC021 on a directory you expected to be an entityThe directory has no <dirname>.md inside it — create the entity file or remove the empty directory.

Related skills

  • speclan-format — the authoritative rule definitions this checker enforces.
  • speclan-id-generator — regenerate a colliding or malformed ID.
  • speclan-query — list/filter entities (this checker reuses the same filename-is-truth and tree-walk conventions).

SPECLAN Grill

Interview the user relentlessly about the target specification(s) until you reach a shared understanding. Walk down each branch of the spec tree — the feature, its requirements, its linked goals — resolving dependencies between decisions one by one. For each question, provide your recommended answer.

Ask the questions one at a time, waiting for the user's response before continuing. A barrage of ten questions gets ten shallow answers; one pointed question with a recommendation gets a real decision.

If a question can be answered by exploring the codebase or the other specs, explore instead of asking. The user's time is for judgment calls, not for facts you can look up.

Session Language

The user may request the interview in another language via --language <lang> (e.g. --language de, --language german) or by asking in conversation. In that case, conduct the entire dialogue — questions, recommended answers, scenario probes, the "apply or note?" prompts, and the end-of-session summary — in that language.

Resolve the session language in this order:

  1. An explicit --language on the current invocation
  2. The language most recently set via --language (or requested in conversation) earlier in this session — once a user chooses a language, a later /speclan:grill without the flag continues in it rather than snapping back to English mid-conversation
  3. English

The specs themselves stay English, always. SPECLAN files are the canonical artifact shared across the team and tooling; the interview language is a convenience for the person being grilled. So any text written to a spec file — sharpened wording, new requirements, change requests, frontmatter — is English, regardless of session language. When proposing a spec edit during a non-English session, show the English wording that will be written, embedded in the foreign-language question (e.g. ask in German, quote the proposed English requirement text verbatim).

The session has three duties, and every question should serve at least one of them:

  1. Reduce ambiguities — wording that two readers would implement differently must be narrowed until only one reading survives.
  2. Clarify contradictions — where two specs, or a spec and the code, or the user's stated intent and the written spec disagree, force a decision about which is right and record it.
  3. Close definition gaps — concepts the spec relies on but never defines, edge cases it is silent about, promises in user stories that no requirement covers, and open questions the spec itself records (Open Questions sections, TBD, TODO).

The purpose is to catch these problems while they are cheap: a vague requirement costs one edit today and a rework cycle after implementation. Specs in draft and review are where grilling pays off most — that's the last gate before approved turns words into work.

Selecting the Target

1. Locate the speclan root

SPECLAN_ROOT=$(node "${CLAUDE_PLUGIN_ROOT}/skills/speclan-format/scripts/detect-speclan.mjs")

This sets $SPECLAN_ROOT. If no speclan root is found, inform the user that no SPECLAN project was detected and stop.

2. Resolve what to grill

  • Explicit entity ID (e.g. F-1049, R-2046) — grill that entity together with its children (requirements under a feature, nested features), its linked goals, and any active change requests. Locate it via the query script:

    node "${CLAUDE_PLUGIN_ROOT}/skills/speclan-query/scripts/query.mjs" \
      --type all --filter-id F-1049 --full "$SPECLAN_ROOT"
    
  • No ID, but the session already has a topic — if the conversation has been about a particular feature or area, locate the matching spec by exploring $SPECLAN_ROOT (query script plus grep over titles and slugs), then confirm the match with the user before starting: "You've been working on the export pipeline — shall I grill you on F-1203 Export Pipeline?"

  • No ID, no topic — list the specs that benefit most from grilling: those in draft or review status.

    node "${CLAUDE_PLUGIN_ROOT}/skills/speclan-query/scripts/query.mjs" \
      --type all --full "$SPECLAN_ROOT"
    

    Filter the JSON for draft and review, present the candidates, and let the user pick.

3. Build the holistic picture before the first question

A spec is never just its file — read the tree under $SPECLAN_ROOT as a chain of thought running from the root to the target: goal → root feature → subfeature → requirement → change request. Each level is a refinement of the one above: the goal states why, the feature what, the requirement precisely what, and change requests how it evolved. Walk the target's full ancestor chain plus its children and judge every step: does each level still follow from its parent? A requirement that doesn't serve its feature, or a subfeature that has drifted from the root feature's intent, is a break in the chain of thought — prime grilling material.

Then traverse the reference graph. The relative markdown links inside spec bodies are named relationships (depends on, owned by, conflicts with, refines), and they carry the holistic view that the directory tree alone cannot. Follow them in both directions:

  • Outgoing — read every spec the target links to. The sentence around the link states what the relationship claims; the linked spec tells you whether that claim still holds. A stale claim is a contradiction waiting to be clarified.
  • Incoming — find the specs that link to the target, e.g. grep -rn "R-2046" "$SPECLAN_ROOT" --include="*.md". Whoever references the target relies on it; a change agreed during grilling may break those expectations, so bring the referencing specs into the interview before applying the change.

While reading, also collect every open question the specs already contain — Open Questions sections, TBD, TODO, FIXME, "to be decided/defined/clarified", or sentences ending in ?:

grep -rniE 'open question|TBD|TODO|FIXME|to be (decided|defined|clarified)' "$SPECLAN_ROOT" --include="*.md"

These go on the session's question list before anything you infer yourself (see "Clear the spec's own open questions" below).

Also check the backlog from earlier sessions: if $SPECLAN_ROOT/artifacts/open-questions.md exists, entries concerning the target (or its chain) join the question list first — a previous grilling already established these are unresolved, so the new session resumes them instead of rediscovering them (see "The Open-Questions Backlog" below).

This mirrors the ask skill's context-gathering procedure (references/context-gathering.md) — reuse it. Grounded questions ("R-2046 says 'fast' — but the chain above it, F-1049 and G-292, promises sub-second lookups, and R-3105 links here as its latency baseline; is 'fast' the same budget?") are worth far more than generic checklist questions. Never grill from a single file read; grill from the chain and the graph.

During the Session

Each category below serves one of the three duties — ambiguity, contradiction, or definition gap — and catches a distinct failure mode. Mix them as the material demands — don't run them as a fixed checklist.

Sharpen fuzzy language

Vague or unverifiable phrasing ("fast", "user-friendly", "should handle errors gracefully", "supports large files") cannot be implemented or tested consistently — every reader fills the gap differently. When you find such phrasing, propose precise, testable wording: "R-2046 says 'responds quickly' — I'd recommend 'responds within 500ms at p95'. Does that match your intent?"

Challenge terminology consistency

When a term in one spec conflicts with how another spec or the code uses it, call it out immediately with both references: "F-1049 calls them 'customers' but R-2031 and src/models/user.ts say 'accounts' — are these the same concept? Which term is canonical?" Inconsistent vocabulary in specs becomes inconsistent vocabulary in code.

Demand definitions for load-bearing terms

When a spec leans on a concept it never defines — "active subscription", "stale record", "primary contact" — every reader invents their own definition, and the gaps surface as bugs. Ask for the definition with a recommended one: "R-2046 hinges on 'active pet' — I'd define it as 'status is not deceased or transferred'. Correct?" Once resolved, write the definition into the spec where the term carries the most weight, so it travels with the requirement that depends on it.

Probe with concrete scenarios

Invent specific edge-case scenarios that force the user to be precise about boundaries: empty states, concurrent actions, failure modes, permission boundaries, scale limits. "A user deletes a pet while a health check on that pet is still running — what does R-2046 say should happen? It currently says nothing. I'd recommend the check is cancelled and logged."

Cross-reference specs against each other

Both the hierarchy chain and the inline link graph make claims that must hold up:

  • Does each requirement actually serve its parent feature, or has it drifted? Read the whole chain root-feature → subfeature → requirement: every step must follow from the one above.
  • Does the feature deliver on the goals it lists in goals:?
  • Does the user story promise something no requirement covers? Gaps here are missing requirements.
  • Does this feature's scope overlap a sibling feature's? Overlaps become ownership disputes at implementation time.
  • Do the inline links still tell the truth? A sentence like "follows the state machine defined in [R-2031 …]" is a claim about R-2031 — if R-2031 has since changed, the claim is now a contradiction to clarify.

Cross-reference with code

When the user states how something works or should work, check whether existing code agrees before accepting the statement. Surface contradictions with file references: "You said partial cancellation is possible, but src/orders/cancel.ts:42 cancels the entire order — which is right, and should the spec or the code change?"

Clear the spec's own open questions

Open questions written into a spec are the author asking to be grilled — they outrank anything you infer yourself, so handle them first. For each one, bring it to the user with a recommended answer like any other question. When it is resolved and the user applies the decision, replace the question in the spec with the answer — an answered question left standing as TBD misleads every future reader into reopening it. If the user cannot answer yet, leave the question in place but sharpen it: record what was discussed, what the options are, and what information is missing to decide — and log it in the open-questions backlog (see "The Open-Questions Backlog" below) so the next session picks it up.

Test acceptance-criteria completeness

Every requirement must be verifiable — that is what review-manual will eventually check it against. For each requirement ask yourself, and if unclear ask the user: "How would a reviewer prove this is done?" If there is no answer, the requirement needs acceptance criteria before it deserves approved.

Capturing Decisions — Ask Per Finding

When a question is resolved, do not silently edit the spec and do not let the decision evaporate into the chat log. Ask the user right then, for that finding: apply the sharpened wording to the spec now, or just note it for the end-of-session summary?

When the user chooses to apply:

  • Editable specs (draft, review, approved) — edit the file directly. Follow the rules from the speclan-format skill: keep the H1 matching the title field, update the updated: timestamp, preserve all frontmatter fields.
  • Locked specs (in-development, under-test, released) — never edit directly; the guard-locked-specs hook will block it, and rightly so. Offer to file a Change Request instead, created per the speclan-format layout ({parent}/change-requests/CR-####-slug.md).
  • The finding touches both an editable and a locked spec (e.g. a draft requirement contradicts a released one) — prefer resolving it in the editable spec, if that resolution is meaningful. A locked spec describes work in flight or shipped reality, and a Change Request carries real process cost; aligning the draft with reality is usually the cheaper and correct fix. But don't contort an editable spec just to dodge a CR: when the grilling established that the locked spec itself is wrong — reality must change — the CR is the honest outcome. Recommend the direction, and let the user decide.
  • A missing requirement was revealed — offer to create it as a new draft requirement under the feature.

Minting IDs: whenever grilling creates a new SPECLAN entity of any kind — Change Request, Requirement, Feature, Goal — the ID MUST come from the speclan-id-generator skill (invoke it as /speclan:speclan-id-generator). Never invent an ID, count up from the highest existing one, or copy-and-modify another spec's ID: hand-rolled IDs collide silently across branches and sessions, and since the filename is the source of truth in SPECLAN, a collision corrupts two specs at once. The generator is the single authority for collision-free IDs.

Write inferred relationships as inline links

Grilling constantly surfaces relationships between specs — "this depends on R-2031", "this only covers what F-1200 doesn't", "this conflicts with G-087". When such a relationship is confirmed and the edit is applied, capture it inline in the prose, at the point where the relationship matters, as a relative markdown link whose surrounding sentence names the relationship:

Cancellation follows the state machine defined in
[R-2031 Order Cancellation](../R-2031-order-cancellation/R-2031-order-cancellation.md);
this requirement only adds the partial-refund case.

Vaccination records are out of scope here — they are owned by
[F-1200 Pet Health](../../F-1200-pet-health/F-1200-pet-health.md).

Do not collect these into a "Related" or "References" section. A bare link list says that two specs are connected but loses why — and the why is exactly what the grilling session just established. Inline placement keeps the relationship readable in context and survives later edits to the rest of the file.

Compute the relative path from the linking file's own location, following the directory-based storage layout from speclan-format (e.g. requirement → sibling requirement is ../R-XXXX-slug/R-XXXX-slug.md; requirement → its feature's sibling feature is ../../../F-XXXX-slug/F-XXXX-slug.md; anything → goal is <up to speclan root>/goals/G-XXX-slug.md). Verify the target file exists before writing the link — a broken relative link is worse than no link.

Keep a running tally of findings throughout the session. End with a short summary:

## Grill Session Summary — F-1049 Pet Management

**Applied to specs:**
- R-2046: "responds quickly" → "responds within 500ms at p95"

**Filed:**
- CR-0812 on R-2031 (locked): clarify cancellation semantics
- R-4102 (new, draft): pet deletion during active health check

**Noted, not applied:**
- F-1049 scope overlap with F-1200 around vaccination records — revisit when F-1200 leaves draft

**Deferred to backlog:**
- R-2046: behaviour of running health checks on pet deletion — waiting on ops input

The Open-Questions Backlog

Grill sessions get aborted and questions get deferred — the user runs out of time, or an answer needs input from someone not in the room. Those unresolved questions must not evaporate with the session: maintain them in $SPECLAN_ROOT/artifacts/open-questions.md.

Writing. When the session ends (or is aborted) with questions still open — asked but deferred, or queued but never reached — append one entry per question. Create the file (and the artifacts/ directory) lazily, only when there is something to write. Entries are in English, like the specs. Format:

# Open Questions

Maintained by grill sessions. Each entry is an unresolved question from an
aborted or deferred grilling. Remove an entry once it is clarified.

## R-2046 — What happens to running health checks when a pet is deleted?
- **Spec:** [R-2046 Health Check](../features/F-1049-pet-management/requirements/R-2046-health-check/R-2046-health-check.md)
- **Raised:** 2026-06-10
- **Blocked on:** ops input about cancellation semantics
- **Recommended answer:** cancel and log
- **Options discussed:** cancel-and-log vs. let-finish-and-discard

The Spec link is relative from artifacts/ — the same inline-link discipline as everywhere else. Capture the recommendation and the options discussed so the next session (possibly months later, possibly a different person) resumes the thought instead of restarting it.

Reading. Every session checks this file during picture-building; entries touching the target join the question list first.

Removing. The moment a backlogged question is clarified — in a grill session or because the user resolves it any other way and tells you — delete its entry. A backlog that keeps answered questions stops being trusted, and an untrusted backlog is dead. If the last entry goes, delete the file; an empty backlog is noise in artifacts/. Note that resolving a backlog entry usually pairs with a spec edit (the answer lands in the spec; the question leaves the backlog).

Leveraged Skills

This skill builds on:

  • speclan-format (${CLAUDE_PLUGIN_ROOT}/skills/speclan-format/SKILL.md) — file structure, status lifecycle, edit constraints, frontmatter fields
  • speclan-query (${CLAUDE_PLUGIN_ROOT}/skills/speclan-query/SKILL.md) — entity discovery and filtering via scripts/query.mjs
  • speclan-id-generator (${CLAUDE_PLUGIN_ROOT}/skills/speclan-id-generator/SKILL.md) — the mandatory, sole source of IDs for every entity grill creates (invoke as /speclan:speclan-id-generator)
  • ask (${CLAUDE_PLUGIN_ROOT}/skills/ask/SKILL.md) — the context-gathering procedure (references/context-gathering.md) for building the picture around an entity

SPECLAN Implement Manual

Pick up a manual implementation plan file and implement the next actionable item. The plan file is a pure data checklist — this skill carries the procedural knowledge for how to implement each item.

Checkbox States

Plan files use four checkbox states to track progress:

CheckboxStateMeaning
[ ]PendingNot yet started
[~]In developmentImplementation in progress
[?]In reviewImplementation finished, awaiting review
[x]DoneReviewed and accepted

Plan File Structure

The plan file has a three-level hierarchy:

- [ ] [F-XXXX] Feature Title                               ← Level 1
  - [F-XXXX](path/to/feature-spec.md)                      ← SPEC PATH (extract from parentheses)
  - [ ] [R-AAAA] Requirement Title                          ← Level 2
    - [R-AAAA](path/to/requirement-spec.md)                 ← SPEC PATH
  - [ ] [R-BBBB] Requirement Title                          ← Level 2
    - [R-BBBB](path/to/requirement-spec.md)                 ← SPEC PATH
    - [ ] [CR-0088] CR Title — CHANGE REQUEST: ...          ← Level 3
      - [CR-0088](path/to/change-request-spec.md)           ← SPEC PATH
- [x] [F-YYYY] Already Implemented Feature                  ← pre-checked
  - [F-YYYY](path/to/feature-spec.md)
  - [x] [R-CCCC] Already Done Requirement                   ← pre-checked
    - [R-CCCC](path/to/requirement-spec.md)
  - [ ] [CR-0042] New Change Request — CHANGE REQUEST: ...  ← pending
    - [CR-0042](path/to/change-request-spec.md)

Each checkbox line has a markdown link sub-bullet below it containing the spec file path inside the (...) parentheses. These paths are the primary data for reading spec files.

(See also: the plan-manual skill's references/plan-file-format.md for the canonical format spec.)

Workflow Overview

IMPORTANT: Always use EnterPlanMode at the start. All steps below run in plan mode — research, parse, and build the implementation plan for user approval before executing.

  1. Find plan files
  2. Select plan file (ask if multiple, recommend latest)
  3. Parse plan and find next actionable item (or exit if done)
  4. Mark items [~] + set spec status to in-development
  5. Ask user for implementation instructions
  6. Execute implementation
  7. Set spec status to under-test
  8. Mark items [?] in plan file

Step 1: Find Plan Files

SPECLAN_DIR="./speclan"
PLANS_DIR="$SPECLAN_DIR/.local/plans"
ls "$PLANS_DIR"/*.plan.md 2>/dev/null

If no plan files found, report:

No manual implementation plans found.

Run the plan-manual skill first to create a plan from approved requirements.

Step 2: Select Plan File

If only one plan file exists, use it automatically.

If multiple plan files exist, present them to the user using AskUserQuestion. Sort by filename (which contains the timestamp) and recommend the latest one.

Step 3: Parse Plan and Find Next Actionable Item

Read the selected plan file. Parse the checkbox hierarchy:

  1. Identify all features (level 1) by [F-XXXX] pattern
  2. For each feature, identify its children (requirements [R-XXXX] and change requests [CR-XXXX])
  3. Note the spec file paths in the markdown link sub-bullets (read in Step 6)

Find the first actionable item using this priority:

  1. Resume [~]: Find the first [~] checkbox in document order. A [~] item has a partial implementation in the codebase — search for existing code before continuing.
    • If it is a feature (level 1): Resume in Mode A — the feature and all its children (whether [~] or still [ ]).
    • If it is a requirement or CR under an [x] feature: Resume in Mode B — just that individual item.
  2. Feature [ ]: A feature where the feature itself is [ ] — implement in Mode A (the whole feature with all [ ] children together)
  3. Late-added [ ]: A [ ] requirement or CR whose parent feature is [x] — implement in Mode B (first [ ] child in document order, one per invocation)

Items marked [?] (in-review) or [x] (done) are skipped.

If no [~] or [ ] items exist, report completion and ask whether to remove the plan file using AskUserQuestion:

All items in this plan are complete. Nothing left to implement.

Plan file: {filename}

Delete the plan file?

If the user agrees, delete the plan file. Then STOP.

Implementation Modes

Mode A — Full Feature: Feature checkbox is [ ]. Read the feature spec + ALL child requirement/CR specs. Implement everything together as one unit.

Mode B — Individual Item: Feature checkbox is [x] but has [ ] children (new requirements or CRs approved after the feature was implemented). Implement the first [ ] child in document order as a single work unit. Subsequent children are picked up in future invocations.

Step 4: Mark as In-Development

Update the plan file checkboxes from [ ] to [~]:

Mode A: Mark the feature AND all its [ ] children as [~]. Mode B: Mark only the individual [ ] item as [~].

Also set status: in-development in the SPECLAN spec file frontmatter for all items being marked [~].

(If resuming a [~] item, the marks and statuses are already correct — no change needed.)

Step 5: Ask for Implementation Instructions

Display the next work unit and ask using AskUserQuestion:

Mode A — Full Feature:

## Next: [F-XXXX] Feature Title

Requirements:
- [R-AAAA] Req Title
- [R-BBBB] Req Title

What implementation instructions do you have?

Provide context about:
- Where to implement (files, modules, components)
- Technical approach preferences
- Constraints or existing patterns to follow

Mode B — Individual Item (Requirement):

## Next: [R-XXXX] Requirement Title

Parent feature: [F-YYYY] Feature Title

What implementation instructions do you have?

Mode B — Individual Item (Change Request):

## Next: [CR-XXXX] CR Title

CHANGE REQUEST — this modifies existing implementation.
Parent: [F-YYYY] Feature Title / [R-ZZZZ] Requirement Title

What implementation instructions do you have?

The user provides free-text instructions, or "none" to proceed without additional instructions.

Step 6: Execute Implementation

Read Spec Files

The plan file contains spec file paths in markdown link sub-bullets directly below each checkbox line. For example:

  - [ ] [R-0266] Bottom-Up Layered Layout
    - [R-0266](speclan/features/F-0297-.../R-0266-bottom-up-layered-layout.md)

Extract the path from inside the parentheses (...) of each link sub-bullet. Then read each spec file.

Mode A — Full Feature: Read ALL of these spec files:

  1. The feature spec (from the feature's link sub-bullet)
  2. Every child requirement spec (from each requirement's link sub-bullet)
  3. Every child CR spec (from each CR's link sub-bullet)

Mode B — Individual Item: Read BOTH of these:

  1. The individual item's spec (from its link sub-bullet)
  2. The parent feature's spec (from the feature's link sub-bullet, for context)

Do NOT skip any spec files. Every spec contains acceptance criteria and technical details essential for correct implementation.

Discover Specification Context

After reading the item specs, discover and read the broader context to understand the system being built:

Ancestors — walk up the directory tree from each spec file path. Each parent directory matching F-XXXX-* or R-XXXX-* is an ancestor entity. Find and read its spec file (the *.md file with the same name as the directory). For example, given:

speclan/features/F-8512-speclannet/F-0212-online-help/F-1680-speclan-plugin/F-1680-speclan-plugin.md

The ancestors are F-8512 (speclannet) and F-0212 (online-help) — read both specs to understand what system this feature belongs to and what "online-help" means in context.

References — scan each spec body for markdown links to other specs (e.g., [R-1496](../R-1496-hover-tooltips/R-1496-hover-tooltips.md)). Read referenced specs to understand cross-cutting concerns, dependencies, and related functionality that the implementation must integrate with.

Implement

Build a step-by-step implementation plan.

For requirements: Build new functionality as described in the spec.

For change requests: The CR spec references the entity it modifies (via feature: or requirement: frontmatter). Read the parent entity's spec to understand the original design. Search the codebase for the existing implementation of that functionality. Alter the existing code as described in the CR spec — do NOT rebuild from scratch.

Combine spec content with user's instructions from Step 5.

Step 7: Update Spec Statuses to Under-Test

After implementation is complete, update the SPECLAN spec file frontmatter:

Mode A: Set status: under-test in the feature spec AND all implemented requirement/CR specs. Mode B: Set status: under-test in the individual item's spec only.

Step 8: Mark as In-Review

Update the plan file checkboxes from [~] to [?]:

Mode A: Mark the feature AND all its children as [?]. Mode B: Mark only the individual item as [?].

Report completion:

Implemented {item description} — now in review.

Progress: {reviewed+done}/{total} items complete.
Remaining: {pending} items pending.

Run implement-manual again to continue.

Error Handling

ScenarioAction
No plan files foundReport error, suggest running plan-manual first
Plan file has no actionable itemsReport all complete or in review
Spec file not found at pathReport error, skip to next actionable item
Plan file parse errorReport error with details

Notes

  • Implements ONE work unit per invocation (full feature or individual item)
  • Run repeatedly to work through the plan
  • Works with plan files created by the plan-manual skill
  • Progress is tracked via checkbox states: [ ] → [~] → [?] → [x]
  • The plan file serves as a persistent audit trail across sessions
  • [x] marking (done) is done by the user after review, not by this skill

SPECLAN Plan Manual

Generate a plan file listing all approved SPECLAN features, requirements, and change requests as an ordered hierarchical checklist. The plan file is written to speclan/.local/plans/ as an audit trail and implementation checklist.

The plan file is pure data — no embedded operational prompts. The implement-manual skill carries the procedural knowledge.

Workflow Overview

  1. Detect speclan directory
  2. Query approved specifications (features, requirements, change requests)
  3. Group children by parent, determine pre-check status
  4. Determine implementation order
  5. Create plan file
  6. Validate plan file
  7. Present summary to user

Step 1: Detect Speclan Directory

Locate the speclan directory in the project. Check for speclan/ in the project root (look for speclan/features/ or speclan/goals/ subdirectories). If not found, report error and stop.

SPECLAN_DIR="./speclan"

Step 2: Query Specifications

MANDATORY: Use the query script for querying. Do NOT manually glob or grep to discover approved specs.

Run these Bash commands to get all approved specs as JSON:

QUERY="${CLAUDE_PLUGIN_ROOT}/skills/speclan-query/scripts/query.mjs"

# Get all approved specs
APPROVED_FEATURES=$(node "$QUERY" --type feature --filter-status approved --full "$SPECLAN_DIR")
APPROVED_REQS=$(node "$QUERY" --type requirement --filter-status approved --full "$SPECLAN_DIR")
APPROVED_CRS=$(node "$QUERY" --type change-request --filter-status approved --full "$SPECLAN_DIR")

The output is JSON arrays with id, slug, type, path, title, status fields per entity.

If all three arrays are empty ([]), report:

No approved specifications found in speclan/.

To approve specs for implementation, set their status to "approved":
  status: approved

Step 3: Build Hierarchy

Build a tree containing only approved items and their ancestor chain. Items that are neither approved nor ancestors of approved items are excluded from the plan.

3a: Approved Items

All items from APPROVED_FEATURES, APPROVED_REQS, and APPROVED_CRS are the actionable items — they appear as [ ] in the plan.

3b: Resolve Parent Chains

For each approved requirement and change request, resolve its full parent chain up to the feature level by reading the spec files directly.

Approved requirements — read the spec → extract the feature: frontmatter field → note the parent feature. Read the parent feature spec to get its title and status.

Approved change requests — read the spec → extract parentId and parentType frontmatter fields:

  • If parentType: requirement → the CR nests under that requirement at level 3. Navigate to the parent requirement spec (two directory levels up from change-requests/) to get the requirement's title, status, and feature: field. Both the requirement and the feature are ancestors.
  • If parentType: feature → the CR nests directly under the feature at level 2. Read the feature spec.

To find a parent spec from a CR path: The parent directory is two levels up from the CR file (above change-requests/):

CR path:   speclan/.../requirements/R-YYYY-.../change-requests/CR-ZZZZ-slug.md
Parent:    speclan/.../requirements/R-YYYY-.../R-YYYY-*.md

3c: Assemble the Tree

CRITICAL: The checkbox is determined by the spec's status: field, NOT by whether the item was in the query results.

For each item in the tree, assign the checkbox by reading its spec status:

  1. status: approved → [ ] (pending implementation)
  2. Any other status (in-development, under-test, released) → [x] (already past planning)

Only items with status: approved get [ ]. Ancestors resolved in Step 3b are NOT approved — they MUST be [x].

Do NOT include sibling items that have no approved descendants.

Example

Given: F-8152 (released), R-5847 (released), CR-2630 (approved):

- [x] [F-8152] Change Request Boxes   ← released, ancestor → [x]
  - [x] [R-5847] Merge CR into Spec   ← released, ancestor → [x]
    - [ ] [CR-2630] Also for under-test — CHANGE REQUEST: find and alter existing implementation

F-8152 and R-5847 are [x] because their status is NOT approved. Only CR-2630 is [ ] because its status IS approved. Never mark a non-approved spec as [ ].

Step 3b: Determine Implementation Order

Use the implementation-order agent (Task tool, subagent_type: speclan:implementation-order) to determine optimal order.

Feature ordering — if there are 2 or more features:

Determine implementation order for features:
- F-XXXX
- F-YYYY
[list all feature IDs from Step 3]

SPECLAN directory: {SPECLAN_DIR}

If there is only 1 feature, no feature ordering needed.

Requirement ordering — for each feature with 2 or more requirements:

Determine implementation order for requirements:
- R-AAAA
- R-BBBB
- R-CCCC
[list all requirement IDs for this feature]

Parent feature: F-XXXX
SPECLAN directory: {SPECLAN_DIR}

Use the returned order to sequence items within each feature in the plan file.

Step 4: Create Plan File

Ensure the output directory exists:

mkdir -p "$SPECLAN_DIR/.local/plans"

Filename

speclan/.local/plans/{slug}.{YYYY-MM-DDTHH-MM}.plan.md

Characterize the plan's scope in exactly three hyphenated words as the slug. The slug should capture what the plan is about at a glance.

Examples: svg-graph-rendering, auth-flow-rework, news-help-assistant, table-export-fix

Plan File Format

Read the reference file at references/plan-file-format.md for the complete template, formatting rules, and concrete examples.

CRITICAL: Follow the template in the reference file EXACTLY. Do NOT add operational prompts, code blocks, or your own wording. The plan file is a pure checklist.

Step 5: Validate Plan File

Do NOT just re-read the plan file. The plan file is the output being validated — it cannot validate itself. Instead, open each referenced spec file and compare its status: field against the checkbox in the plan.

For each checkbox line in the plan:

  1. Extract the entity ID (e.g., F-6089, R-5847, CR-2630)
  2. Extract the spec file path from the (...) parentheses in the link sub-bullet below it
  3. Read that spec file using the Read tool — do NOT rely on any cached or in-memory data from earlier steps
  4. Extract the status: value from the spec's YAML frontmatter
  5. Compare: status: approved → checkbox MUST be [ ], any other status → checkbox MUST be [x]

If any mismatch is found, fix it immediately by editing the plan file. Then report the corrections:

Validation: fixed {count} checkbox(es):
- {ID}: status is {status}, changed [ ] → [x]

If all checkboxes are correct, proceed silently.

Step 6: Present Summary

After the plan file is validated, display a summary:

## Manual Implementation Plan Created

Plan file: speclan/.local/plans/{filename}

{feature-count} features, {requirement-count} requirements, {cr-count} change requests.
{pending-count} items pending implementation.

Run the `implement-manual` skill to start implementing.

Error Handling

ScenarioAction
No speclan directoryReport error, stop
No approved specs (all three arrays empty)Report message with guidance to approve specs
Query script not foundFall back to manual grep: grep -rl "^status: approved" speclan/features/
Parent feature not foundWarn, list item without feature context

Notes

  • This skill only creates the plan file — it does not start implementation
  • For automated batch implementation, use the /speclan:implement command instead
  • The plan file at speclan/.local/plans/ serves as an audit trail and implementation reference
  • The .local/ directory is typically gitignored and holds per-user state
  • The implement-manual skill uses checkbox states ([ ] → [~] → [?] → [x]) to track progress

SPECLAN Review Manual

Pick up a manual implementation plan file and review ALL in-review items at once. Read every [?] item's spec, verify the implementation satisfies acceptance criteria, and assess code quality via two parallel subagents.

CRITICAL CONSTRAINTS:

  • NEVER edit spec files. Do NOT use Edit or Write tools on any file inside speclan/ except speclan/.local/plans/*.plan.md. No status changes (do NOT set status to "accepted", "released", or anything else), no acceptance criteria updates, no frontmatter changes. Spec files are input only — read them, never modify them. Spec statuses stay as under-test.
  • Only the plan file is modified — the sole Edit operation in this entire skill is changing [?] → [x] checkboxes in the *.plan.md file after user approval. No other file is written to.
  • Review ALL [?] items in one invocation. Do NOT review one item at a time.

Plan File Structure

The plan file has a three-level hierarchy:

- [?] [F-XXXX] Feature Title                               ← Level 1
  - [F-XXXX](path/to/feature-spec.md)                      ← SPEC PATH (extract from parentheses)
  - [?] [R-AAAA] Requirement Title                          ← Level 2
    - [R-AAAA](path/to/requirement-spec.md)                 ← SPEC PATH
  - [?] [R-BBBB] Requirement Title                          ← Level 2
    - [R-BBBB](path/to/requirement-spec.md)                 ← SPEC PATH
    - [?] [CR-0088] CR Title — CHANGE REQUEST: ...          ← Level 3
      - [CR-0088](path/to/change-request-spec.md)           ← SPEC PATH

Each checkbox line has a markdown link sub-bullet below it containing the spec file path inside the (...) parentheses.

(See also: the plan-manual skill's references/plan-file-format.md for the canonical format spec.)

Workflow Overview

IMPORTANT: Always use EnterPlanMode at Step 4. Steps 4–7 run in plan mode — research and build the review plan for user approval before executing.

  1. Find plan files
  2. Select plan file (ask if multiple, recommend latest)
  3. Parse plan, collect ALL [?] items (or exit if none/done)
  4. Enter plan mode
  5. Read ALL spec files for every [?] item
  6. Identify implementation files (scope the review)
  7. Build review plan for user approval
  8. Execute review (spec compliance + code quality subagents)
  9. Present combined review report
  10. User decision (accept or defer)
  11. Apply transitions (if accepting)
  12. Report completion

Step 1: Find Plan Files

SPECLAN_DIR="./speclan"
PLANS_DIR="$SPECLAN_DIR/.local/plans"
ls "$PLANS_DIR"/*.plan.md 2>/dev/null

If no plan files found, report:

No manual implementation plans found.

Run the plan-manual skill first to create a plan from approved requirements.

Step 2: Select Plan File

If only one plan file exists, use it automatically.

If multiple plan files exist, present them to the user using AskUserQuestion. Sort by filename (which contains the timestamp) and recommend the latest one.

Step 3: Parse Plan and Collect ALL [?] Items

Read the selected plan file. Parse the checkbox hierarchy and collect every [?] item into a flat list:

  1. Identify all features (level 1) by [F-XXXX] pattern
  2. For each feature, identify its children (requirements [R-XXXX] and change requests [CR-XXXX])
  3. Collect every item with a [?] checkbox into the review scope — this includes features themselves, not just their children. A [?] feature is a reviewable item just like a [?] requirement.
  4. Note the spec file paths in the markdown link sub-bullets (read in Step 5)

Example: Given this plan:

- [?] [F-0297] SVG Rendering          ← counted as [?] item #1
  - [x] [R-0266] Layout               ← skipped (already [x])
  - [?] [R-0754] Arrow Connections     ← counted as [?] item #2
  - [?] [R-1496] Hover Tooltips       ← counted as [?] item #3
  - [?] [R-1635] Package Delivery     ← counted as [?] item #4

The review scope is 4 items: F-0297, R-0754, R-1496, R-1635. Read all 4 specs, verify all 4, mark all 4 as [x].

If no [?] items exist:

  • If [ ] or [~] items remain, report: "Items are still in progress. Nothing ready for review yet." Then STOP.
  • If all items are [x], report completion and ask whether to delete the plan file using AskUserQuestion:
All items in this plan have been reviewed and accepted.

Plan file: {filename}

Delete the plan file?

If the user agrees, delete the plan file. Then STOP.

Step 4: Enter Plan Mode

Use EnterPlanMode. All subsequent steps (5–7) run in plan mode to research and build the review plan before execution.

Step 5: Read ALL Spec Files

For every [?] item collected in Step 3, extract the spec file path from inside the parentheses (...) of its markdown link sub-bullet. For example:

  - [?] [R-0266] Bottom-Up Layered Layout
    - [R-0266](speclan/features/F-0297-.../R-0266-bottom-up-layered-layout.md)

Read every spec file. Do NOT skip any.

From each spec, extract all acceptance criteria — the - [ ] Given...When...Then... lines. These are the verification targets for Step 8.

Discover Specification Context

After reading the item specs, discover and read the broader context to understand the system being reviewed:

Ancestors — walk up the directory tree from each spec file path. Each parent directory matching F-XXXX-* or R-XXXX-* is an ancestor entity. Find and read its spec file (the *.md file with the same name as the directory). For example, given:

speclan/features/F-8512-speclannet/F-0212-online-help/F-1680-speclan-plugin/F-1680-speclan-plugin.md

The ancestors are F-8512 (speclannet) and F-0212 (online-help) — read both specs to understand the broader system context.

References — scan each spec body for markdown links to other specs (e.g., [R-1496](../R-1496-hover-tooltips/R-1496-hover-tooltips.md)). Read referenced specs to understand cross-cutting concerns and dependencies relevant to the review.

Step 6: Identify Implementation Files

Determine which source files to review across the entire scope. Use two strategies:

Strategy 1 — Git-based discovery:

Extract the updated date from spec YAML frontmatter and find changed files:

SINCE_DATE=$(grep -m1 '^updated:' path/to/spec.md | awk -F"'" '{print $2}')
git log --since="$SINCE_DATE" --diff-filter=ACMR --name-only --pretty=format:"" | sort -u

Strategy 2 — Spec-guided search: Extract key terms from spec titles, scope sections, and acceptance criteria. Use grep/glob to find relevant source files.

Combine results from both strategies into a single implementation file list covering the full review scope.

Step 7: Build Review Plan

Present the review plan for user approval:

## Review Plan

### Items to Review ({count} specs)

- [F-XXXX] Feature Title
- [R-AAAA] Requirement Title ({n} acceptance criteria)
- [R-BBBB] Requirement Title ({n} acceptance criteria)
- [CR-CCCC] CR Title ({n} acceptance criteria)

### Implementation Files ({count} files)

- src/...
- src/...

### Total: {total} acceptance criteria to verify

Proceed with review?

Exit plan mode after user approves.

Step 8: Execute Review

Spec Compliance (primary, blocking)

Verify every acceptance criterion collected in Step 5 — across ALL [?] specs. For each criterion:

  1. Parse the Given/When/Then statement to understand what must be true
  2. Search the implementation files for code that satisfies the criterion
  3. Assess whether the implementation fulfills the criterion
  4. Record verdict: PASS / FAIL / PARTIAL with evidence (file:line references)

For change requests: Verify the alteration was applied correctly — check that the original behavior was changed as specified, not just that new code exists.

Code Quality (secondary, advisory)

Launch two subagents in parallel via the Task tool. Invoke both Task tool calls in the same response block so they execute concurrently:

Subagent 1 — Code Hygiene:

Task tool, subagent_type: speclan:code-hygiene-reviewer

Review code hygiene for implementation of [F-XXXX] [Feature Title]:

Implementation files:
- {list all files from Step 6}

Report findings categorized as Critical/Major/Minor with file:line evidence.

Subagent 2 — Architecture:

Task tool, subagent_type: speclan:architecture-reviewer

Review architecture for implementation of [F-XXXX] [Feature Title]:

Implementation files:
- {list all files from Step 6}

Context: {brief description of what was implemented}

Report findings categorized as Critical/Major/Minor with file:line evidence.

Step 9: Present Combined Review Report

## Review Report

### Spec Compliance

#### [R-AAAA] Requirement Title
| # | Acceptance Criterion (short) | Verdict | Evidence |
|---|------------------------------|---------|----------|
| 1 | Given X, When Y, Then Z      | PASS    | file.ts:45 |
| 2 | Given A, When B, Then C      | FAIL    | Not found |

#### [R-BBBB] Requirement Title
| # | Acceptance Criterion (short) | Verdict | Evidence |
|---|------------------------------|---------|----------|
| 1 | Given D, When E, Then F      | PASS    | file.ts:23 |

(one section per requirement/CR)

**Overall: {pass_count}/{total} criteria passed.**

### Code Hygiene (Advisory)

{hygiene subagent findings — Critical/Major/Minor}

### Architecture (Advisory)

{architecture subagent findings — Critical/Major/Minor}

Step 10: User Decision

If all criteria PASS and no critical code quality findings:

Ask via AskUserQuestion to confirm acceptance:

All {total} acceptance criteria passed. Accept and mark as done?

If any criteria FAIL or PARTIAL:

Present findings and recommend immediate fixes:

{fail_count} acceptance criteria need attention.

Recommend fixing these issues now. After fixing, confirm to accept.
Otherwise, leave in review and re-run review-manual later.

Wait for the user. The user may:

  • Fix the issues and confirm → proceed to accept
  • Say "accept anyway" → proceed to accept
  • Decline → leave [?], no state changes, STOP

Step 11: Apply Transitions

After the user confirms, edit the plan file only — change [?] to [x] for every item collected in Step 3 (features, requirements, CRs).

"Accept" means marking plan checkboxes [x]. It does NOT mean changing spec statuses.

FORBIDDEN: Do NOT use Edit or Write on ANY file inside speclan/ except speclan/.local/plans/*.plan.md. Do NOT change any spec status: field. Do NOT set statuses to "accepted", "released", or any other value. Spec statuses remain under-test — human testing happens separately.

Step 12: Report Completion

If all items in the plan are now [x], offer to delete the plan file:

All {total} items reviewed and accepted.

Plan file: {filename}

Delete the plan file?

Otherwise report progress:

Reviewed and accepted {count} items.

Progress: {done}/{total} items complete.
Remaining: {pending} pending, {in_progress} in progress.

Error Handling

ScenarioAction
No plan files foundReport error, suggest running plan-manual first
No [?] items (but [ ]/[~] exist)Report items still in progress
All items [x]Report done, offer to delete plan file
Spec file not found at pathReport error, continue with remaining specs
Implementation files not foundAsk user to provide file paths manually
Subagent failurePresent spec compliance results alone, note code quality review incomplete
Plan file parse errorReport error with details

Notes

  • Reviews ALL [?] items in one invocation — no re-run needed
  • Works with plan files created by the plan-manual skill
  • NEVER edit spec files — do not use Edit or Write on any speclan/ file
  • Spec compliance is blocking; code quality findings are advisory
  • The accept/defer decision is always with the user

SPECLAN Format Knowledge

THIS IS FOUNDATIONAL CONTEXT. Apply these rules to ALL speclan file operations.

SPECLAN (Specification as a Living Language) manages project specifications as interlinked markdown files with YAML frontmatter in a hierarchical directory structure.

Quick Reference (CRITICAL)

Filename IS the Source of Truth

The directory/filename pattern {PREFIX}-{ID}-{slug} is authoritative:

F-1049-pet-management/F-1049-pet-management.md
│  │    │              └─ File MUST match directory name
│  │    └─ Kebab-case slug from title
│  └─ 4-digit numeric ID (randomly generated)
└─ Entity prefix (F=Feature, R=Requirement, etc.)

Extract ID from filename, NOT frontmatter for indexing and collision checks.

Entity Prefixes

EntityPrefixDigitsExampleStorage
GoalG-3G-292goals/G-292-slug.md (flat)
FeatureF-4F-1049features/F-1049-slug/F-1049-slug.md (dir)
RequirementR-4R-2046features/.../requirements/R-2046-slug/R-2046-slug.md (dir)
Change RequestCR-4CR-0731{parent}/change-requests/CR-0731-slug.md (flat)

Status Determines Editability

Editable (direct edit OK)Locked (needs Change Request)
draft, review, approvedin-development, under-test, released, deprecated

Directory Structure

SPECLAN specifications live in ${PROJECT}/speclan/:

speclan/
├── goals/                    # G-### Business goals (flat)
├── features/                 # F-#### Feature hierarchy
│   └── F-1049-pet-management/
│       ├── F-1049-pet-management.md      # Feature file matches directory
│       ├── requirements/                  # Requirements as directories
│       │   ├── R-2046-health-check/
│       │   │   ├── R-2046-health-check.md
│       │   │   └── change-requests/       # CRs for this requirement
│       │   └── R-3272-status-tracking/
│       │       └── R-3272-status-tracking.md
│       ├── change-requests/               # CRs for this feature
│       │   └── CR-0731-add-feature.md
│       └── F-1200-pet-health/             # Child feature (nested)
│           └── F-1200-pet-health.md
├── templates/                # Templates (UUID in frontmatter, slug filename)
│   ├── features/
│   └── requirements/
└── change-requests/          # Root-level change requests

Key structural rules:

  • Features and Requirements use directory-based storage - directory name must match contained markdown filename
  • Requirements are nested inside their parent feature's requirements/ directory as subdirectories
  • Child features are subdirectories of parent features
  • Change requests live in change-requests/ adjacent to the entity they modify (features OR requirements)

Entity Hierarchy

Goal (G-###)
  └── Feature (F-####)  [forms hierarchical tree via directories]
        └── Requirement (R-####)

Additional entities:

  • Template (UUID v4) - Reusable spec templates
  • ChangeRequest (CR-####) - Modifications to released entities

ID Format Conventions

EntityFormatExampleStorage Location
GoalG-###G-292goals/ (flat files)
FeatureF-####F-1049features/ (hierarchical directories)
RequirementR-####R-2046features/{feature}/requirements/ (directories)
ChangeRequestCR-####CR-0731{entity}/change-requests/ (flat files)
TemplateUUID v4bf5cb38b-...templates/{type}/ (flat files)

ID Generation: All numeric IDs are randomly generated with collision detection (not sequential). Always check existing IDs before creating new ones.

ID-Based Ordering: IDs determine artifact priority/order numerically:

  • Lower IDs = Higher priority (processed/displayed first)
  • Higher IDs = Lower priority (processed/displayed later)
  • Example: F-1049 has higher priority than F-2847
  • This ordering applies within the same entity type (features sorted among features, requirements among requirements, etc.)

File Naming Convention

Files follow pattern: <ID>-kebab-case-title.md

Examples:

  • G-292-comprehensive-pet-retail-operations.md (flat file in goals/)
  • F-1049-pet-management/F-1049-pet-management.md (directory-based)
  • R-2046-health-check/R-2046-health-check.md (directory-based)

Directory-based entities (Features, Requirements):

  • Directory name must match the contained markdown filename
  • Example: F-1049-pet-management/F-1049-pet-management.md
  • Example: R-2046-health-check/R-2046-health-check.md

Template filenames use kebab-case slugs (UUID stored in frontmatter only):

  • basic-feature.md
  • functional-requirement.md

Markdown File Format

Every spec file has YAML frontmatter followed by markdown content. The body MUST start with an H1 heading (# Title) matching the title field from the frontmatter:

---
id: F-1049
type: feature
title: Pet Management
status: draft
owner: Store Manager
created: "2025-12-29T09:53:49.355Z"
updated: "2025-12-29T10:31:04.445Z"
goals:
  - G-292
  - G-087
---

# Pet Management              ← REQUIRED: H1 must match frontmatter title

## Overview
Brief description of what this feature does and why it exists.

## User Story
As a **Store Manager**, I want **comprehensive tools** so that **I can track pets**.

## Scope
- Pet Tracking
- Status Management
- Health Records

Structural rules:

  • First line after frontmatter MUST be # {title} (H1 heading)
  • Subsequent sections use ## Heading (H2) and below
  • No content before the H1 heading

Common YAML Frontmatter Fields

All entities share:

id: <entity-id>           # Required
type: <entity-type>       # Required: goal|feature|requirement|template|changeRequest
title: <string>           # Required
status: <status>          # Required: draft|review|approved|in-development|under-test|released|deprecated
owner: <string>           # Required
created: <ISO-8601>       # Required
updated: <ISO-8601>       # Required
tags: [<string>, ...]     # Optional

Entity-specific fields - See references/entity-fields.md for complete reference.

Status Lifecycle

Entities follow a 7-stage lifecycle:

draft → review → approved → in-development → under-test → released → deprecated
StatusEditableDescription
draftYesInitial creation, work in progress
reviewYesReady for review
approvedYesApproved, ready for development
in-developmentNoCurrently being implemented
under-testNoImplementation complete, testing
releasedNoDeployed to production
deprecatedNoNo longer active (terminal state)

Read-only statuses: Entities in in-development, under-test, released, or deprecated are locked. Direct edits are not allowed - changes require a Change Request (CR-####).

Validation Rules

For complete validation rules including ID format regex, directory naming enforcement, parent-child relationship validation, status lifecycle rules, and entity-specific field validation, consult references/validation-rules.md.

Linking Between Specs

YAML Frontmatter References

# Goal references features
contributors:
  - F-1049
  - F-2247

# Feature references goals
goals:
  - G-292
  - G-087

# Requirement references parent feature
feature: F-1009

Markdown Cross-References

Use relative paths in markdown content:

## Related
### Goals
- [Animal Welfare Compliance](../goals/G-087-animal-welfare-compliance.md)

### Features
- [Pet Status Lifecycle](../F-1807-pet-status-lifecycle/F-1807-pet-status-lifecycle.md)

Working with SPECLAN Files

Detecting SPECLAN Directory

To find the speclan directory in a project:

  1. Check common locations: speclan/, specs/speclan/, .speclan/, .specs/speclan/ — any of these may be a symlink (e.g. a repo-root speclan symlink into a spec submodule)
  2. Look for characteristic subdirectories: features/ and/or goals/ (requirements never appear top-level; young projects may lack goals/)
  3. Verify markdown files with SPECLAN YAML frontmatter

Reading Specifications

When reading a spec file:

  1. Parse YAML frontmatter for metadata
  2. Extract entity relationships from frontmatter fields
  3. Parse markdown content for documentation

Creating New Specifications

To create a new spec:

  1. Check for user templates FIRST:

    speclan/templates/<entity-type>/
    
    • speclan/templates/features/ for feature templates
    • speclan/templates/requirements/ for requirement templates

    Read available templates and choose the best fit. Templates contain the user's preferred structure.

  2. Generate a unique ID using the speclan-id-generator:

    SCRIPT="${CLAUDE_PLUGIN_ROOT}/skills/speclan-id-generator/scripts/generate-id.mjs"
    
    # Generate a feature ID (collision-free, end-biased)
    node "$SCRIPT" --type feature --speclan-root speclan --raw
    
    # Generate a child feature ID under a parent
    node "$SCRIPT" --type feature --parent F-1049 --speclan-root speclan --raw
    
    # Generate a requirement ID under a feature
    node "$SCRIPT" --type requirement --parent F-1049 --speclan-root speclan --raw
    
  3. Create file in correct location:

    For Goals: speclan/goals/G-###-slug.md (flat file)

    For Features: Create directory AND file with matching name:

    speclan/features/F-####-slug/F-####-slug.md
    

    For Requirements: Create directory inside parent feature's requirements/:

    speclan/features/F-####-parent/requirements/R-####-slug/R-####-slug.md
    

    For Child Features: Nest inside parent feature directory:

    speclan/features/F-####-parent/F-####-child/F-####-child.md
    
  4. Write frontmatter and content:

    • Use template if found, otherwise use default structure
    • Set all required fields (id, type, title, status, owner, created, updated)
    • For requirements, set feature: F-#### to link to parent
  5. Update related entities to establish bidirectional links

Updating Specifications

When modifying a spec:

  1. Update the updated timestamp
  2. Maintain bidirectional links (if adding feature to goal, add goal to feature)
  3. Follow status transition rules

Writing Guidelines

For guidance on writing effective specifications, consult references/writing-guide.md.

Key principles:

  • Write user-focused, implementation-agnostic specifications
  • Include clear acceptance criteria as checkbox lists in requirements (Given/When/Then logic)
  • Maintain traceability between entities
  • Use consistent terminology

Additional Resources

Reference Files

  • references/entity-fields.md - Complete YAML field reference for all entity types
  • references/writing-guide.md - Best practices for writing specifications

Related Skills

  • speclan-id-generator - Generate collision-free unique IDs for SPECLAN entities

Utility Scripts

  • scripts/detect-speclan.mjs - Detect speclan directory in a project (SPECLAN_ROOT=$(node scripts/detect-speclan.mjs))

SPECLAN ID Generator

Generate unique, collision-free IDs for SPECLAN entities with parent-aware end-biased ordering and automatic collision detection.

Why Use This Skill

  • Collision-free: Scans existing speclan directory and retries on collision
  • Entity-aware: Correct format for each entity type (goals: 3-digit, others: 4-digit)
  • Parent-aware: --parent flag generates IDs biased after existing siblings, preserving natural ordering
  • Batch generation: Generate multiple IDs in a single call with internal deduplication

Entity ID Formats

Entity TypePrefixDigitsRangeExample
goalG-3000-999G-142
featureF-40000-9999F-1847
requirementR-40000-9999R-3928
change-requestCR-40000-9999CR-7291

ID-Based Ordering: Lower IDs = higher priority. The --parent flag generates IDs that come after existing siblings, maintaining natural creation order within a hierarchy.

Primary CLI: generate-id.mjs (Node.js)

Script Location

${CLAUDE_PLUGIN_ROOT}/skills/speclan-id-generator/scripts/generate-id.mjs

Command Line

node generate-id.mjs --type <entityType> [--parent <id>] [--count <n>] [--speclan-root <path>]

Flags:

  • --type <type> - Required. One of: goal, feature, requirement, changeRequest (or change-request)
  • --parent <id> - Optional. Parent entity ID for end-biased generation. The parent must exist on disk.
  • --count <n> - Optional. Number of IDs to generate (default: 1, max: 100)
  • --speclan-root <path> - Optional. Path to speclan directory (auto-detected if omitted)

Output: JSON to stdout:

{"ok":true,"data":{"type":"feature","ids":["F-1847","F-2934"]}}

Error output: JSON to stdout with exit code 1:

{"ok":false,"error":"PARENT_NOT_FOUND","message":"Parent entity not found: F-9999","context":{"parentId":"F-9999"}}

Examples

SCRIPT="${CLAUDE_PLUGIN_ROOT}/skills/speclan-id-generator/scripts/generate-id.mjs"

# Generate a single feature ID
node "$SCRIPT" --type feature --speclan-root /path/to/speclan
# {"ok":true,"data":{"type":"feature","ids":["F-1847"]}}

# Generate 3 feature IDs
node "$SCRIPT" --type feature --count 3 --speclan-root /path/to/speclan
# {"ok":true,"data":{"type":"feature","ids":["F-1847","F-2934","F-5621"]}}

# Generate child feature IDs under a parent (end-biased after siblings)
node "$SCRIPT" --type feature --parent F-1847 --count 2 --speclan-root /path/to/speclan
# {"ok":true,"data":{"type":"feature","ids":["F-3012","F-3498"]}}

# Generate requirement IDs under a child feature
node "$SCRIPT" --type requirement --parent F-3012 --count 4 --speclan-root /path/to/speclan
# {"ok":true,"data":{"type":"requirement","ids":["R-4521","R-4832","R-5293","R-5647"]}}

Parsing Output

# Print IDs one per line with --raw (no JSON parsing needed)
node "$SCRIPT" --type feature --count 3 --speclan-root "$SPECLAN_DIR" --raw
# F-1847
# F-2934
# F-5621

End-Biased Generation (--parent)

When --parent is specified, the generator:

  1. Finds the parent entity on disk by scanning the speclan directory
  2. Reads existing sibling entities in the parent's directory
  3. Finds the highest sibling ID numerically
  4. Generates a new ID an arbitrary gap above that highest sibling — a random gap in the range of 50 (uniform 5–95, e.g. R-0013 → somewhere in R-0018…R-0108). The gap guarantees IDs are never near-consecutive and leaves free slots between entries for later mid-priority inserts
  5. If the candidate slot is taken, chains another random gap on top of it; batch generation (--count) chains the same way, so every ID in a batch keeps an arbitrary gap to the previous one. Once the end-biased walk would run past the end of the range (G-999 / F-9999 / …), it falls back to a completely random, collision-checked ID drawn from anywhere in the allowed range

Valid parent relationships:

  • --type feature --parent F-XXXX → child feature under parent feature
  • --type requirement --parent F-XXXX → requirement under feature
  • --type changeRequest --parent F-XXXX → CR under feature
  • --type changeRequest --parent R-XXXX → CR under requirement
  • --type changeRequest --parent G-XXX → CR under goal

Important: The parent entity must exist on disk before using --parent. For hierarchical creation (like from-speckit conversion), write parent files first, then generate child IDs.

Error Handling

Exit CodeMeaning
0Success - JSON/ID printed to stdout
1Error - JSON/message printed to stdout/stderr

Common errors:

  • MISSING_TYPE — --type flag not provided
  • INVALID_TYPE — Unknown entity type
  • PARENT_NOT_FOUND — --parent ID not found on disk
  • INVALID_PARENT — Parent type not valid for the requested entity type
  • ID_GENERATION_FAILED — ID space exhausted or collision loop

SPECLAN Query

Fast, flexible querying of SPECLAN entities with JSON output. Query by type, filter by status or parent, with optional full metadata extraction.

Why Use This Skill

  • Fast: Filename-based parsing without reading files (unless filters require it)
  • Reliable: Uses {PREFIX}-{ID}-{slug} naming pattern as source of truth
  • Flexible: Query any entity type, filter by status/parent
  • Structured: Clean JSON output for programmatic consumption
  • Portable: Plain Node.js script — no jq, awk, or other external tools required

Entity Types

TypePrefixPatternLocation
goalG-G-###-*.mdgoals/
featureF-F-####-*.mdfeatures/ (recursive)
requirementR-R-####-*.mdfeatures/.../requirements/
change-requestCR-CR-####-*.mdAnywhere in change-requests/

Usage

Script Location

${CLAUDE_PLUGIN_ROOT}/skills/speclan-query/scripts/query.mjs

Command Line

node query.mjs [OPTIONS] [speclan-dir]

Options:

  • -t, --type TYPE - Entity type to query (required)
  • -s, --filter-status STATUS - Filter by status (draft|review|approved|in-development|under-test|released|deprecated)
  • -p, --parent ID - Filter by parent ID (e.g., F-1234)
  • -f, --full - Include title and status in output (reads frontmatter)
  • -h, --help - Show usage

Arguments:

  • speclan-dir - Path to speclan directory (default: ./speclan)

Output:

  • JSON array to stdout
  • Errors to stderr
  • Exit code: 0 = success, 1 = error

Examples

List all features (fast - filename only)

node query.mjs --type feature speclan

Output:

[
  {"id":"F-1049","slug":"pet-management","type":"feature","path":"speclan/features/F-1049-pet-management/F-1049-pet-management.md"},
  {"id":"F-2847","slug":"user-auth","type":"feature","path":"speclan/features/F-2847-user-auth/F-2847-user-auth.md"}
]

List features with full details

node query.mjs --type feature --full speclan

Output:

[
  {"id":"F-1049","slug":"pet-management","type":"feature","path":"...","title":"Pet Management","status":"draft"},
  {"id":"F-2847","slug":"user-auth","type":"feature","path":"...","title":"User Authentication","status":"approved"}
]

Filter by status

node query.mjs --type feature --filter-status approved speclan

Find requirements for a feature

node query.mjs --type requirement --parent F-1049 speclan

Find change-requests for a requirement

node query.mjs --type change-request --parent R-2046 speclan

Combine filters

node query.mjs --type requirement --parent F-1049 --filter-status approved --full speclan

Query all entity types

node query.mjs --type all speclan

Query Modes

Fast Mode (Default)

Only parses filenames, no file content read:

  • Extracts ID and slug from filename pattern
  • Infers type from ID prefix
  • Fastest for simple listing

Activated when: No --full, --filter-status, or --parent flags

Full Mode (Frontmatter Read)

Reads YAML frontmatter when needed:

  • Extract title, status from frontmatter
  • Required for filtering or full output

Activated when: --full, --filter-status, or --parent specified

JSON Output Schema

Minimal (fast mode)

{
  "id": "F-1049",
  "slug": "pet-management",
  "type": "feature",
  "path": "speclan/features/F-1049-pet-management/F-1049-pet-management.md"
}

Full (with --full flag)

{
  "id": "F-1049",
  "slug": "pet-management",
  "type": "feature",
  "path": "speclan/...",
  "title": "Pet Management",
  "status": "draft"
}

Parent Filtering

The --parent flag checks multiple locations:

  1. Structural parent - ID appears in file path (e.g., F-1049-slug/requirements/R-2046-slug/)
  2. Frontmatter fields - feature:, requirement:, parentId:
  3. Array fields - Goals array (- G-123)

Integration Examples

In sync-from-session Command

# Index existing features
FEATURES_JSON=$(node "${CLAUDE_PLUGIN_ROOT}/skills/speclan-query/scripts/query.mjs" --type feature --full speclan)

# Check if feature exists
if echo "$FEATURES_JSON" | grep -q '"id":"F-1049"'; then
  echo "Feature exists"
fi

# Get editable features (not locked)
EDITABLE=$(node "${CLAUDE_PLUGIN_ROOT}/skills/speclan-query/scripts/query.mjs" --type feature --filter-status draft speclan)

Extract specific fields with grep

# Get all feature IDs
node query.mjs --type feature speclan | grep -oE '"id":"[^"]+"' | cut -d'"' -f4

# Get all paths
node query.mjs --type feature speclan | grep -oE '"path":"[^"]+"' | cut -d'"' -f4

# Count entities
node query.mjs --type requirement speclan | grep -c '"id"'

Process each entity

node query.mjs --type feature --full speclan | grep -oE '"id":"[^"]+"' | cut -d'"' -f4 | while read -r fid; do
  echo "Processing feature: $fid"
  req_count=$(node query.mjs --type requirement --parent "$fid" speclan | grep -c '"id"' || echo 0)
  echo "  Requirements: $req_count"
done

Status Reference

For the full status lifecycle and editability rules, consult the speclan-format skill. Key point: statuses draft, review, approved are editable; in-development, under-test, released require Change Requests; deprecated is permanently frozen.

Error Handling

ScenarioBehavior
Missing speclan dirError message, exit 1
Invalid entity typeError message, exit 1
No matches foundEmpty JSON array [], exit 0
Malformed filenameSkipped silently
Template filesSkipped automatically
Archived filesSkipped automatically

Performance Notes

  • Fast mode: ~50ms for 100 features (filename parsing only)
  • Full mode: ~500ms for 100 features (frontmatter reads)
  • No caching between queries
  • No depth limits on recursive search
  • Files in /templates/ and /_archived/ are excluded

Sync Specs from Session

Analyze the current session context to identify implemented features, compare with existing SPECLAN specifications, and create or update specs based on user confirmation.

Core Principle: Implementation-Agnostic Specs

SPECS MUST NEVER CONTAIN IMPLEMENTATION OR ARCHITECTURE DETAILS. This skill analyzes code changes internally to understand WHAT was built, but specs describe only user-facing capabilities and business value. Never include file paths, code references, library names, technical approaches, architectural decisions, design patterns, or any implementation-specific information in generated specs.

When to Use

  • After completing implementation work and wanting to document it
  • When user asks to sync or update specs based on recent work
  • To capture newly implemented functionality in SPECLAN format

Workflow Overview

1. Analyze Session → 2. Scan Speclan → 3. Compare & Diff → 4. Ask User → 5. Apply Changes

Step 1: Analyze Session Context

Review the conversation history to identify:

1.1 Code Changes Made (Internal Analysis)

Look for patterns indicating implementation (for internal matching only - these details are NOT included in specs):

  • Files created or modified (Write/Edit tool usage)
  • Functions, classes, or components added
  • API endpoints implemented
  • Database schema changes
  • Configuration updates

Purpose: Use these implementation signals to identify WHAT was built, then translate into user-facing capability descriptions for specs.

1.2 Extract Feature Information

For each identified change, extract:

feature_candidate:
  title: "<descriptive name>"
  description: "<what it does for users and why it matters>"
  _code_paths: ["<files involved>"]  # INTERNAL USE ONLY - for matching, never included in specs
  type: "new" | "enhancement" | "bugfix"
  scope: "feature" | "requirement" | "both"
  _status_evidence:                  # INTERNAL USE ONLY - for status determination
    code_exists: none | partial | complete
    has_tests: true | false
    tests_pass: true | false | unknown
    human_verified: true | false | unknown

Note: _code_paths and _status_evidence are used internally. They are NEVER written to spec files.

1.2a Determine Status for Each Feature

A session is usually work in progress: some things were only discussed, some were half-built, some are finished but nobody has actually confirmed they work. The status you write must describe that reality, so a reader can tell at a glance what still needs doing. Don't reach for a single status for the whole sync — decide per entity, from evidence.

The three statuses this sync produces:

StatusMeansUse when
draftNothing was implemented — only the specification existsThe capability was designed, discussed, or planned in the session, but no code was written for it
in-developmentPartly implemented, not finishedSome of the described behavior works; parts are missing, stubbed, or marked TODO
under-testFully implemented; verification may still be outstandingEvery described behavior is built, but it has not been confirmed working by a human

review, approved, released, and deprecated are not outcomes of a sync — they represent human judgments (a spec was reviewed, a release shipped) that this skill has no evidence for.

How to gather evidence:

  1. Look at what the session actually changed — was code written for this capability at all, or was it only talked about?
  2. Check for gaps in the implementation: TODO/FIXME markers, stubs, unhandled branches, functions that were planned but never written
  3. Search for test files covering the implementation (*.test.*, *.spec.* in the same area) and check the session history — did tests run, and did they pass?
  4. When torn between two statuses, pick the less complete one. Under-claiming costs a second look; over-claiming means finished-looking work silently ships unbuilt.

Note the consequence of this choice: draft stays editable, while in-development and under-test lock the entity so later corrections need a Change Request. That is another reason not to inflate status.

The determined status applies to new features, new requirements, and new change requests created by this sync.

1.2b Set Acceptance Criteria Checkbox States

Status alone is coarse — it says "partly done" without saying which parts. The acceptance criteria carry that detail, so set each checkbox from the same evidence rather than leaving them all open:

StateMeaning here
[ ]Open — no implementation covers this criterion yet
[~]In progress — code implements this, but nobody has verified it holds
[x]Done — verified, by a human or by a test that was run and passed

Reserve [x] for criteria you actually saw confirmed in the session. Implemented-but-unverified is the common case in a sync and belongs in [~]: it signals "this should work, go check it" instead of falsely claiming it's been accepted.

This follows from the status: a draft entity has all criteria [ ]; an in-development entity has a mix of [~] and [ ]; an under-test entity has every criterion at [~] or [x] (nothing open, since all described behavior is built). If you find yourself writing an open criterion under under-test, the status is wrong — drop it to in-development.

1.3 Categorize Changes

Group related changes into logical features:

  • Multiple file changes for one feature = single feature
  • Independent changes = separate features
  • Small fixes to existing features = requirement updates

Step 2: Scan Speclan Directory

2.1 Detect Speclan Location

# Check common locations
if [ -d "speclan" ]; then
  SPECLAN_DIR="speclan"
elif [ -d "specs/speclan" ]; then
  SPECLAN_DIR="specs/speclan"
else
  # No speclan directory - all features are new
  SPECLAN_DIR=""
fi

2.2 Index Existing Specs

If speclan directory exists, build an index:

# List all features
find "$SPECLAN_DIR/features" -name "F-*.md" -type f 2>/dev/null

# Extract titles and paths
for f in $(find "$SPECLAN_DIR/features" -name "F-*.md" -type f); do
  id=$(grep "^id:" "$f" | head -1 | cut -d: -f2 | tr -d ' ')
  title=$(grep "^title:" "$f" | head -1 | cut -d: -f2-)
  echo "$id|$title|$f"
done

2.3 Build Existing Spec Map

Create a mapping of:

  • Feature ID → Title → File path (spec file location, not code)
  • Feature ID → Status (for edit rules)
  • Feature ID → Key capabilities (for semantic matching)

Note: Use titles and capability descriptions for matching, not code paths. Well-formed specs should not contain implementation or architecture references.

Step 3: Compare and Generate Diff

3.1 Match Session Work to Existing Specs

For each feature candidate from session:

  1. Title similarity check: Compare with existing feature titles
  2. Capability overlap: Check if the described functionality matches existing features
  3. Description similarity: Semantic comparison of purpose and user-facing behavior

Note: Matching is based on functional capabilities and user outcomes, not on code paths, implementation details, or architectural decisions.

3.2 Classify Each Change

Session FeatureExisting SpecClassification
New capabilityNo matchCREATE new feature
Related capabilityMatch found, status editableUPDATE existing feature
Related capabilityMatch found, status lockedCHANGE_REQUEST needed
EnhancementPartial matchADD_REQUIREMENT to feature

3.3 Prepare Change Summary

Build a structured summary:

# NOTE: _code_paths are INTERNAL ONLY for matching - never written to specs
changes:
  create:
    - title: "User Authentication"
      description: "Secure login with automatic session refresh"
      _code_paths: ["src/auth/", "src/middleware/auth.ts"]  # internal matching only

  update:
    - id: "F-1142"
      title: "Pet Management"
      changes: "Added bulk import capability for pet records"
      _code_paths: ["src/pets/import.ts"]  # internal matching only

  change_requests:
    - parent_id: "F-1089"
      title: "Add Export Feature"
      reason: "Feature is in-development status"

  requirements:
    - feature_id: "F-1142"
      title: "Validate CSV format on import"
      _code_paths: ["src/pets/validators/csv.ts"]  # internal matching only

Step 4: Ask User for Confirmation

Present the identified changes to the user using AskUserQuestion or direct prompting.

4.1 Summary Format

## Identified Changes from Session

Based on our session, I identified the following potential spec updates:

### New Features to Create
1. **User Authentication** - Secure login with automatic session refresh
   - Proposed status: `under-test` (built this session, not yet verified)
2. **Password Reset** - Self-service recovery for forgotten passwords
   - Proposed status: `draft` (discussed only, nothing built)

### Existing Features to Update
1. **F-1142 Pet Management** - Add bulk import capability for pet records
   - Current status: draft (editable)

### Change Requests Needed
1. **F-1089 Data Export** - Feature is locked (in-development)
   - Proposed: Add export option for user data

### New Requirements
1. For **F-1142**: Validate file format on import

IMPORTANT: Keep descriptions implementation-agnostic (see references/implementation-agnostic-guidelines.md).

Show the proposed status for every item. The user knows things you can't infer from the transcript — that a feature was hand-tested, or that a "finished" module is still missing a case — and surfacing your reasoning lets them correct it before the status locks the entity.

4.2 Ask for User Selection

Use AskUserQuestion to let user choose:

questions:
  - question: "Which changes would you like to apply to specs?"
    header: "Apply"
    multiSelect: true
    options:
      - label: "Create: User Authentication"
        description: "New feature for secure login with session refresh"
      - label: "Update: F-1142 Pet Management"
        description: "Add bulk import capability to existing feature"
      - label: "CR for F-1089: Data Export"
        description: "Create change request for locked feature"
      - label: "Requirement for F-1142"
        description: "Add file format validation requirement"

4.3 Handle User Response

  • Selected items: Proceed to create/update
  • "Other" response: User may provide custom instructions
  • No selection: Skip spec updates

Step 5: Apply Changes

5.1 Generate IDs

For new entities, generate collision-free IDs:

SCRIPT="${CLAUDE_PLUGIN_ROOT}/skills/speclan-id-generator/scripts/generate-id.mjs"

# Generate a feature ID
FEATURE_ID=$(node "$SCRIPT" --type feature --speclan-root "$SPECLAN_DIR" --raw)

# Generate a requirement ID under a parent feature
REQ_ID=$(node "$SCRIPT" --type requirement --parent "$FEATURE_ID" --speclan-root "$SPECLAN_DIR" --raw)

5.2 Create New Features

For each new feature:

  1. Create directory structure:

    mkdir -p "$SPECLAN_DIR/features/F-####-slug"
    mkdir -p "$SPECLAN_DIR/features/F-####-slug/requirements"
    
  2. Write feature file with YAML frontmatter:

    ---
    id: F-####
    type: feature
    title: <Title>
    status: <determined in Step 1.2a — draft, in-development, or under-test>
    owner: <from session or "Developer">
    created: "<ISO-8601>"
    updated: "<ISO-8601>"
    goals: []
    ---
    
    # <Title>
    
    ## Overview
    <Description from session analysis - focus on WHAT and WHY, not HOW>
    
    ## Scope
    <Bullet points of functionality - user-facing capabilities, not code details>
    

Specs must be 100% implementation and architecture agnostic. For the complete DO/DON'T list with examples, consult references/implementation-agnostic-guidelines.md.

5.3 Update Existing Features

For features with editable status (draft, review, approved):

  1. Read current file
  2. Update relevant sections:
    • Add new scope items (user-facing capabilities only)
    • Update description if needed (keep implementation-agnostic)
  3. Advance status and criteria to match the evidence — a draft spec whose behavior the session actually built is no longer a draft. Re-run the Step 1.2a judgment against the spec as it now reads, and move any acceptance criteria the session implemented from [ ] to [~] (or [x] if verified). Leave the status alone when the session only reworded or extended the spec without building anything.
  4. Update updated timestamp
  5. Write file back

Remember: Never add implementation details, architecture decisions, code references, or technical approaches to existing specs.

5.4 Create Change Requests

For locked entities (features or requirements in-development, under-test, released):

  1. Generate CR ID:

    CR_ID=$(node "$SCRIPT" --type change-request --speclan-root "$SPECLAN_DIR" --raw)
    
  2. Create CR file:

    ---
    id: CR-####
    type: changeRequest
    title: <Change title>
    status: <determined in Step 1.2a — draft, in-development, or under-test>
    owner: Developer
    created: "<ISO-8601>"
    updated: "<ISO-8601>"
    parentId: <F-#### or R-####>
    parentType: <feature or requirement>
    changeType: enhancement
    description: <Brief description - user-facing, no implementation details>
    changes: |
      <Detailed change narrative - describe WHAT changes for users, not HOW it's implemented>
    ---
    

    Note: Change request descriptions must also be implementation-agnostic (see guidelines).

  3. Place in correct location (adjacent to target entity):

    # For features:
    speclan/features/F-####-slug/change-requests/CR-####-slug.md
    
    # For requirements:
    speclan/features/.../requirements/R-####-slug/change-requests/CR-####-slug.md
    

5.5 Create New Requirements

For requirements under existing features:

  1. Generate requirement ID
  2. Create requirement directory structure:
    mkdir -p "speclan/features/F-####-parent/requirements/R-####-slug"
    
  3. Write requirement file:
    speclan/features/F-####-parent/requirements/R-####-slug/R-####-slug.md
    
    Give it a status from Step 1.2a, and write its Acceptance Criteria checkboxes at the states determined in Step 1.2b — [~] for criteria the code covers but nobody has confirmed, [ ] for ones nothing implements yet:
    ## Acceptance Criteria
    
    - [~] Given a file is uploaded, when the format is invalid, then the upload is rejected with an explanation
    - [ ] Given a file exceeds the size limit, when it is uploaded, then the user is told before processing starts
    
  4. Update parent feature's updated timestamp

Step 6: Report Results

After applying changes, report:

## Spec Sync Complete

### Created
- F-#### User Authentication (speclan/features/F-####-user-authentication/)
- R-#### CSV Validation (speclan/features/F-1142-pet-management/requirements/R-####-csv-validation/)

### Updated
- F-1142 Pet Management - added bulk import scope

### Change Requests Created
- CR-#### for F-1089 Data Export (speclan/features/F-1089-.../change-requests/)
- CR-#### for R-#### (speclan/.../requirements/R-####-.../change-requests/)

### Next Steps
- Review created specs for accuracy
- Assign goals to new features
- Process pending change requests

Edge Cases

No Speclan Directory

If speclan/ doesn't exist:

  1. Ask user if they want to initialize it
  2. If yes, create basic structure:
    mkdir -p speclan/goals speclan/features speclan/templates
    
  3. Proceed with creating new features

No Identifiable Features

If session has no clear feature work:

  • Report: "No significant feature implementations detected in this session"
  • Offer to manually describe what to document

Ambiguous Matches

When a session feature could match multiple existing specs:

  • Present options to user
  • Let them choose the correct match or create new

Integration with Other Skills

SPECLAN Format

Reference for proper file structure and frontmatter fields.

SPECLAN ID Generator

Use for collision-free ID generation.

Spec Converter

If user also has speckit, consider syncing there too.

Commands 13

SPECLAN Ask Command

Explicit entry point for the speclan:ask skill. Load the skill and answer the user's question.

Invocation

/speclan:ask F-0471
/speclan:ask what's approved
/speclan:ask children of G-001
/speclan:ask where do we set specs status

Scope Constraint

When invoked via this command, all exploration stays within the project's speclan/ directory. Do not search application source code, configuration files, or any files outside $SPECLAN_ROOT. Every answer comes from spec files (frontmatter and markdown bodies), the SPECLAN format rules, and the status lifecycle — not from grepping the broader codebase.

When the user asks questions like "where do we set status" or "how does X work", they are asking about the spec ecosystem — answer from the spec data and SPECLAN conventions, not from implementation code.

Procedure

  1. Detect the speclan root using SPECLAN_ROOT=$(node "${CLAUDE_PLUGIN_ROOT}/skills/speclan-format/scripts/detect-speclan.mjs")
  2. Load the speclan:ask skill (${CLAUDE_PLUGIN_ROOT}/skills/ask/SKILL.md)
  3. Use the argument as the user's question
  4. Follow the skill's workflow, restricting all file reads, Glob, and Grep to paths within $SPECLAN_ROOT

SPECLAN From-BMAD Command

Convert BMAD-METHOD planning artifacts (PRD, Epics, Architecture) to SPECLAN hierarchical format.

Prerequisites

This command requires understanding of both formats:

BMAD Format (source):

  • Planning artifacts in _bmad-output/planning-artifacts/
  • PRD with Functional Requirements grouped by Capability Area (FR#: [Actor] can [capability])
  • Optional: Epics document with User Stories and BDD Acceptance Criteria
  • Optional: Architecture Decision Document with NFRs
  • YAML frontmatter with workflowType, stepsCompleted, inputDocuments

SPECLAN Format (target):

  • Located in speclan/ directory
  • Entity hierarchy: Goal -> Feature -> Child Feature -> Requirement
  • YAML frontmatter with proper IDs (G-###, F-####, R-####)
  • Directory-based storage with change-requests/ subdirectories

Instructions

1. Check BMAD Installation

Verify BMAD is installed and has planning artifacts:

# Check for BMAD installation directory and config
ls _bmad/bmm/config.yaml 2>/dev/null
# Check for planning artifacts output
ls _bmad-output/planning-artifacts/ 2>/dev/null

If _bmad/ does not exist:

Error: No BMAD installation found.

Expected: _bmad/ directory with bmm/config.yaml

Install BMAD first: npx bmad-method install
Then create planning artifacts using BMAD workflows.

If _bmad/ exists but _bmad-output/planning-artifacts/ does not:

Error: No BMAD planning artifacts found.

Expected: _bmad-output/planning-artifacts/ with PRD.md

Create planning artifacts using BMAD workflows:
  /bmad-bmm-create-prd

2. Locate BMAD Artifacts

Locate BMAD planning artifacts in order of priority. Use Glob to find them:

  • Primary: PRD document — glob _bmad-output/planning-artifacts/**/[Pp][Rr][Dd]*.md
  • Secondary: Epics document — glob _bmad-output/planning-artifacts/**/[Ee]pic*.md
  • Tertiary: Architecture document — glob _bmad-output/planning-artifacts/**/[Aa]rchitect*.md

If argument provided, use that directory instead of _bmad-output/planning-artifacts/.

PRD is required. If no PRD found:

Error: No PRD document found in BMAD planning artifacts.

Expected: _bmad-output/planning-artifacts/PRD.md (or similar)

Create a PRD first using BMAD:
  /bmad-bmm-create-prd

3. Parse BMAD PRD

Read the PRD document and extract structured content:

3a. Detect BMAD PRD format:

  • Check for ## Functional Requirements section
  • Check for FR pattern lines (e.g., FR1:, FR2:, - FR1:)
  • Check for YAML frontmatter with workflowType: 'prd'

3b. Extract Executive Summary:

  • Find ## Executive Summary section
  • Extract product vision, target users, problem statement
  • Find ### What Makes This Special subsection if present
  • This becomes vision.md and mission.md content

3c. Extract Success Criteria:

  • Find ## Success Criteria section
  • Parse whatever ### subsections exist — common ones include ### User Success, ### Business Success, ### Technical Success, ### Measurable Outcomes, but not all PRDs have every subsection. Parse all found subsections.
  • ### Measurable Outcomes may use either bullet list or table format (| Metric | Target | Timeframe |). Parse both formats.
  • Each subsection with measurable outcomes becomes a Goal. If a subsection is absent, skip it — do not synthesize missing categories.

3d. Extract Product Scope:

  • BMAD PRDs may contain both ## Product Scope (brief feature list by phase) and ## Project Scoping & Phased Development (detailed phased breakdown with descriptions). Check for both sections.
  • If both exist, prefer ## Project Scoping & Phased Development as the authoritative source — it typically contains richer phase descriptions and feature groupings. Use ## Product Scope only as a fallback.
  • Parse MVP, Growth, Vision phase boundaries from ### MVP (Phase 1) / ### Post-MVP (Phase 2) / ### Vision (Phase 3) subsections (or similar heading patterns).
  • Extract feature lists per phase for scope tagging

3e. Extract Functional Requirements:

  • Find ## Functional Requirements section
  • Parse capability area headers (### Capability Area Name)
  • Extract individual FRs within each area
  • FR format: FR#: [Actor] can [capability] [context/constraint] or - FR#: description
  • Each capability area becomes a Parent Feature
  • Each FR becomes a Requirement under its capability area's Feature
  • Detect developer-infrastructure FRs: FRs where the actor is "Project" or "Build system" (not "System", "Player", or "User") typically describe developer tooling — code organization, linting, test coverage, type checking, naming conventions, architectural boundaries. These are NOT user-facing capabilities. Flag them for reclassification as NFRs under a "Code Quality" category (see step 6).

3f. Extract Non-Functional Requirements:

  • Find ## Non-Functional Requirements section
  • Parse category headers: ### Performance, ### Security, ### Scalability, ### Accessibility, ### Integration
  • Each NFR category with requirements becomes a Feature tagged nfr
  • Individual NFR items become Requirements

3g. Extract User Journeys (optional):

  • Find ## User Journeys section
  • Parse journey narratives per user type
  • Store as context in parent feature descriptions

3h. Extract Project-Type Requirements:

  • Grep the PRD for project-type-specific sections: ## CLI Tool Requirements, ## Web App Requirements, ## API Requirements, ## Mobile App Requirements.
  • These sections contain additional requirements specific to the project type (e.g., CLI command structure, terminal compatibility, responsive design needs).
  • When a project-type section is found, it MUST produce a dedicated parent feature (e.g., "CLI Tool Constraints", "Web App Constraints") tagged with the project type (e.g., cli-tool) and scope-mvp. This feature uses flat structure (requirements directly under parent, requirements: field required).
  • Parse individual requirements from the section. Each testable requirement becomes a SPECLAN requirement under the project-type parent feature.
  • If the section contains only design guidelines (not individually testable), store the entire section as the parent feature's body content — but still create the parent feature as a container.
  • Do NOT silently skip this step. If a project-type section exists in the PRD but produces zero entities, report it in the output summary as a warning.

4. Parse BMAD Epics (if available)

If an epics document is found:

4a. Parse FR Coverage Map (authoritative FR-to-Epic mapping):

  • Find ### FR Coverage Map section in the epics document. This section maps each FR to its Epic, e.g.:
    - FR1: Epic 2 — Alien grid rendering
    - FR2: Epic 3 — Player movement system
    
  • Parse every line matching pattern FR\d+:\s+Epic\s+(\d+) to build an FR-to-Epic lookup table.
  • This is the authoritative source for which FRs belong to which Epic. Do NOT rely on name-matching between PRD capability area headers and epic titles — they frequently cross boundaries (e.g., an FR under "Game Rendering" in the PRD may be mapped to "Epic 5: Physics System" in the coverage map).
  • If no FR Coverage Map section exists, fall back to name-matching between capability areas and epic titles.

4b. Parse Requirements Inventory (optional):

  • Find ### Requirements Inventory or ## Requirements Inventory section.
  • This section lists all requirement types: #### Functional Requirements (FR), #### Non-Functional Requirements (NFR), #### Additional Requirements (AR), #### UX Requirements (UX).
  • Use this as a cross-reference to verify all requirements are captured.

4c. Extract Epic structure:

  • Parse ## Epic N: Title sections
  • Extract epic goal descriptions
  • Parse ### Story N.M: Title subsections

4d. Extract User Stories:

  • Parse story format: As a [user_type], I want [capability], So that [value_benefit]
  • Extract BDD Acceptance Criteria: Given/When/Then/And blocks

4e. Extract Additional Requirements (AR# and UX#):

  • Find ### Additional Requirements section within the epics document.
  • Parse #### Architecture-Derived (AR) subsection for AR# entries (e.g., AR1: Description).
  • Parse #### UX-Derived (UX) subsection for UX# entries (e.g., UX1: Description).
  • These requirements are not present in the PRD — they are generated during epic breakdown and represent architecture-driven and UX-driven additions.
  • Each AR# and UX# becomes a SPECLAN Requirement. Assign them to the most relevant parent feature based on their description context. If an AR/UX entry references a specific epic, use the FR Coverage Map logic to place it under that epic's feature.
  • Strip AR#/UX# prefixes just like FR# prefixes — SPECLAN entities have their own identity.

4f. Merge with PRD data:

  • Use the FR Coverage Map (from step 4a) to assign each FR to its Epic. Each Epic becomes a Parent Feature; FRs assigned to that Epic become Requirements under it.
  • If the FR Coverage Map assigns FRs from multiple PRD capability areas to the same Epic, merge them — the Epic grouping takes precedence over PRD capability area grouping when epics are available.
  • Epic stories become Child Features under the matching Parent Feature.
  • Story acceptance criteria become Requirement acceptance criteria.
  • If an epic has no PRD match (e.g., infrastructure-only epic), create a new Parent Feature from the epic.
  • FRs not covered by the FR Coverage Map become Requirements under their original PRD capability area feature.

5. Parse BMAD Architecture (if available)

If an architecture document is found:

5a. Extract additional NFRs:

  • Parse ## Core Architectural Decisions for decision-derived requirements
  • Parse NFR-related sections for measurable criteria not in the PRD

5b. Extract project context:

  • Note technology stack and patterns for tag context (do NOT embed implementation details in specs)

6. Map to SPECLAN Entities

Build the entity tree before generating files:

Parent Features (from PRD Capability Areas + Epic alignment):

  • One parent feature per capability area
  • Title from capability area header (cleaned, no "Capability Area" prefix)
  • Tags: scope-mvp, scope-growth, or scope-vision based on Product Scope section
  • If epics provide richer structure, prefer epic-derived titles

Child Features (from Epic Stories, if epics available):

  • One child feature per story within an epic
  • User story format preserved in body
  • Tags inherit from parent + story-specific priority if present

Requirements (from individual FRs, AR#s, and UX#s):

  • One requirement per FR, AR, or UX entry
  • Title: descriptive language from FR/AR/UX (strip all prefixes: FR#:, AR#:, UX#:, strip actor prefix for title)
  • Body: full text plus acceptance criteria if available
  • Acceptance criteria in Given/When/Then checkbox format

NFR Features (from Non-Functional Requirements):

  • One parent feature per NFR category, tagged nfr
  • NFR features are flat -- requirements are placed directly under the parent feature (no child features)
  • The parent feature MUST include a requirements: field listing all requirement IDs
  • Deduplication with functional requirements: When an NFR describes the same behavior as an existing functional requirement (e.g., "clean terminal exit" appears as both FR53 and NFR7), the NFR requirement body should cross-reference the functional requirement rather than duplicating acceptance criteria. Use: Enforces quality attribute for the behavior specified in R-XXXX. followed by the NFR-specific measurable threshold (e.g., "under all exit conditions including SIGTERM, SIGINT, and uncaught exceptions").

Developer-Infrastructure FR Reclassification:

  • FRs flagged in step 3e as developer-infrastructure (actor is "Project" or "Build system") MUST be reclassified as NFRs under a "Code Quality" parent feature tagged nfr.
  • Common patterns to reclassify: code organization standards, linting/formatting enforcement, type checking, test coverage requirements, naming conventions, architectural boundary enforcement, build configuration, module system configuration.
  • These describe project quality attributes, not user-testable capabilities. In a PRD they would be NFRs; in SPECLAN they belong under an NFR feature.
  • When reclassifying, rewrite the requirement title to describe a measurable quality attribute (e.g., "Enforce code linting standards" → "Zero linting violations in continuous integration").

CRITICAL RULES:

  1. DO NOT add back-references. No ## Source sections linking to BMAD files.

  2. All generated entities get status: review -- converted specs need review, not initial drafts.

  3. Every file body MUST start with # Title -- H1 heading matching the frontmatter title field. No content before it. Subsequent sections use ## Heading (H2) and below.

  4. Directory and file names must be clean -- Names must match pattern {PREFIX}-{digits}-{kebab-slug}. No curly braces, spaces, quotes, or other special characters.

  5. DO NOT carry over BMAD identifiers into SPECLAN specs. No FR1, FR2, NFR-1, Epic 1, Story 1.2 references. SPECLAN entities have their own identity. Describe requirements in plain language.

  6. DO NOT create template directories. The command generates goals/ and features/ trees only.

  7. Requirements use directory-based storage -- Each requirement is a directory containing its .md file: requirements/R-ZZZZ-slug/R-ZZZZ-slug.md. NEVER store requirements as flat files.

  8. IDs MUST be globally unique -- Generate -> write -> generate -> write, one batch at a time. The ID generator detects collisions only against files already on disk.

  9. Implementation-agnostic specs -- Strip technology names, architecture patterns, file paths, library references, and design decisions. SPECLAN specs describe WHAT, never HOW. This applies to ALL entities including goals, success indicators, acceptance criteria, feature Key Entities sections, and NFR requirement bodies.

    Generalization principle: The categories and examples below are representative, not exhaustive. Any term describing HOW the system is built internally — data structures, code organization, architecture decisions, internal protocols, design patterns, timing mechanisms — rather than WHAT the user experiences or WHAT quality is achieved must be rewritten to capability language.

    • Strip technology names: specific runtimes, frameworks, build tools, test frameworks, linters, libraries, specific file paths. Replace with generic terms: "target runtime version", "type-safe language", "package manager".
    • Strip architecture patterns: state machine, event bus, game loop, immutable state, pure function, side effects, data model(s), emit and subscribe, and any similar terms describing internal system structure or code organization.
    • Strip implementation verbs: "implement X" → just "X"; "define [internal structure]" → "represent [entities] with [attributes]"; "manage [internal mechanism]" → describe the user-visible outcome.
    • Strip data format specifics: JSON file, YAML file, SQLite → "local file", "persistent storage".
    • Strip implementation-specific conventions: Do not dictate coding conventions (e.g., kebab-case, PascalCase). Describe the quality attribute instead: "all identifiers follow a consistent, documented naming scheme".
    • Replace with capability language — examples:
      • "state machine" → "manage transitions between [phases/states]"
      • "event bus" / "emit and subscribe" → "trigger [action] in response to [events]"
      • "immutable state" / "pure function" → "consistent [state] across [cycles]" or "independently testable with no external dependencies"
      • "data model(s)" → "represent [entities] with [attributes]"
    • Code Quality NFRs are not exempt: Architecture language in Code Quality requirements must also be rewritten to describe the quality outcome, not the implementation technique.
    • Allowed: Domain-specific standards that ARE the requirement (e.g., "ANSI colors", "Unicode block elements", "UTF-8", "raw mode", "cursor") — these describe WHAT, not HOW
  10. No empty child features -- Every child feature MUST have at least one requirement. If a BMAD story has no FRs/ARs/UXs assigned via the FR Coverage Map, either: (a) decompose the story's scope items into individual requirements, or (b) merge the story into a sibling child feature. Never create a child feature with requirements: [].

7. Identify Feature Groupings

Before generating files, finalize the feature hierarchy:

If only PRD available (no epics):

  • Each capability area = one Parent Feature
  • All FRs within a capability area become direct Requirements (flat, no child features)
  • Parent feature MUST include requirements: field listing all requirement IDs
  • NFR categories = additional Parent Features tagged nfr (flat, with requirements: field)
  • Project-type features (from step 3h) = additional Parent Features (flat, with requirements: field)

If PRD + Epics available:

  • Use FR Coverage Map to determine Parent Feature grouping: each Epic = one Parent Feature, with FRs assigned per the coverage map (NOT per PRD capability area)
  • Stories within the epic = Child Features under the parent
  • FRs assigned to that epic (via coverage map) = Requirements distributed among child features or directly under the parent
  • AR# and UX# additional requirements = Requirements assigned to the most relevant parent feature
  • FRs not in the coverage map = Requirements under their original PRD capability area feature
  • NFR categories = additional Parent Features tagged nfr (flat structure — requirements directly under parent, no child features, requirements: field required)
  • Project-type features (from step 3h) = additional Parent Features (flat structure, requirements: field required)

Flat vs. hierarchical: Any parent feature without child features (NFR, project-type, PRD-only capability areas) MUST include a requirements: field in its frontmatter. This ensures requirements are discoverable by metadata, not just filesystem traversal.

8. Generate Entity IDs (Phased)

Generate IDs using the speclan-id-generator JS CLI. IDs are generated in phases because --parent requires the parent entity to exist on disk.

SCRIPT="${CLAUDE_PLUGIN_ROOT}/skills/speclan-id-generator/scripts/generate-id.mjs"

Phase A -- Parent feature IDs (no --parent, generated in two batches for sort ordering):

A1 — FR features first (lower IDs):

# Generate IDs for user-facing (non-NFR, non-project-type) parent features FIRST
node "$SCRIPT" --type feature --count <num-capability-area-features> --speclan-root <speclan-dir>
# Output: {"ok":true,"data":{"type":"feature","ids":["F-1234","F-5678",...]}}

Add --raw to get the IDs one per line instead of JSON. Write FR parent feature files to disk immediately.

A2 — NFR + project-type features second (higher IDs):

# Generate IDs for NFR and project-type parent features AFTER FR features are on disk
node "$SCRIPT" --type feature --count <num-nfr+project-type-features> --speclan-root <speclan-dir>

Write NFR/project-type parent feature files to disk immediately.

Why two batches: The ID generator assigns sequential IDs from the next available range. By generating FR features first, they get lower IDs. NFR features get higher IDs. This means ls and sort-by-ID naturally show user-facing features before quality attributes — matching how users think about specifications.

Phase B -- Child feature IDs (with --parent, after parent files exist):

# For each parent feature that has epic stories:
node "$SCRIPT" --type feature --parent F-1234 --count <num-stories> --speclan-root <speclan-dir>

Write child feature files to disk immediately after each parent's children are generated.

Phase C -- Requirement IDs (with --parent, one feature at a time):

# For EACH feature (parent or child) that has requirements:
#   1. Generate requirement IDs for this feature
node "$SCRIPT" --type requirement --parent F-YYYY --count <num-reqs> --speclan-root <speclan-dir>
#   2. Write all requirement files for this feature to disk
#   3. THEN move to the next feature

CRITICAL: Generate and write requirements one feature at a time. The ID generator detects collisions only against files already on disk.

Phase D -- Goal IDs (after all features exist):

node "$SCRIPT" --type goal --count <num-goals> --speclan-root <speclan-dir>

IMPORTANT: The pattern at every level is: generate IDs -> write files to disk -> generate next batch. Never batch ID generation across multiple parents without writing intermediate results.

9. Determine Owner

Get the git identity for the owner field on all generated entities:

OWNER=$(git config user.name)

If git user.name is not set, prompt the user for an owner value. Never leave owner empty.

10. Generate SPECLAN Files

Write files top-down: all parent features first (Phase A IDs), then child features (Phase B IDs), then requirements (Phase C IDs). Each level must be on disk before generating the next level's IDs with --parent.

Parent Feature (one per Capability Area / NFR Category)
---
id: F-XXXX
type: feature
title: [from capability area header, cleaned]
status: review
owner: [OWNER from git config]
created: [current date]
updated: [current date]
goals: []  # Updated in Goal Creation step
tags: [scope-mvp]  # or scope-growth, scope-vision based on PRD scope section
source: "bmad:epic-N"  # or "bmad:capability-area-slug" if no epics
---

For NFR features (flat structure — requirements directly under parent, no child features):

tags: [nfr, scope-mvp]
requirements: [R-XXXX, R-XXXX, ...]  # REQUIRED for NFR features — lists all direct requirements

Directory layout:

speclan/features/F-XXXX-slug/
├── F-XXXX-slug.md              <- parent feature file
├── F-YYYY-child-1/             <- child feature (sibling of parent .md)
│   ├── F-YYYY-child-1.md
│   └── requirements/
│       └── R-ZZZZ-req/
│           └── R-ZZZZ-req.md
└── F-YYYY-child-2/             <- another child feature
    └── ...

IMPORTANT: Child feature directories are SIBLINGS of the parent .md file, NOT nested inside a subdirectory named after the parent.

Body content: Must start with # Title. Then: Overview (from PRD context), Scope (In/Out), Key Entities, Success Criteria (as checkboxes).

Child Feature (one per Epic Story, if epics available)
---
id: F-YYYY
type: feature
title: [from story title, descriptive]
status: review
owner: [OWNER from git config]
created: [current date]
updated: [current date]
goals: []  # Updated in Goal Creation step
requirements: [R-XXXX, R-XXXX, ...]
tags: [scope-mvp]
source: "bmad:story-N.M"  # e.g., "bmad:story-3.2"
---

Directory: speclan/features/F-XXXX-parent/F-YYYY-child/ Body content: Must start with # Title. Then: User Story (As a... I want... so that...), Scope, Business Context.

Requirement (one per FR)
---
id: R-ZZZZ
type: requirement
title: [descriptive title from FR -- no FR numbers, no actor prefix]
status: review
owner: [OWNER from git config]
created: [current date]
updated: [current date]
feature: F-YYYY
source: "bmad:FR23"  # or "bmad:AR5", "bmad:UX3" for additional requirements
---

Directory: Under parent or child feature: requirements/R-ZZZZ-slug/R-ZZZZ-slug.md

Requirements use directory-based storage (directory name matches file name):

CORRECT:  requirements/R-ZZZZ-slug/R-ZZZZ-slug.md
WRONG:    requirements/R-ZZZZ-slug.md  <- flat file, NEVER do this

Body content: Must start with # Title. Then: Description (plain language, implementation-agnostic), Acceptance Criteria (Given/When/Then checkboxes). If the original BMAD FR had acceptance criteria or the matching epic story had BDD criteria, convert them to:

## Acceptance Criteria

- [ ] **Given** [precondition]; **When** [action]; **Then** [expected outcome]

CRITICAL: Single-line format. Each acceptance criterion MUST be a single - [ ] line with Given/When/Then separated by semicolons. Multi-line format breaks markdown checkbox rendering — the When/Then become orphaned paragraphs outside the checkbox.

11. Create Goals

After all features and requirements are generated, analyze the full set of features and synthesize Goals from PRD Success Criteria:

  1. Map Success Criteria to Goals:

    • ### User Success subsection -> one Goal focused on user outcomes
    • ### Business Success subsection -> one Goal focused on business metrics
    • ### Technical Success subsection -> one Goal focused on technical quality
    • If subsections have distinct measurable outcomes, create separate Goals per outcome cluster
  2. Create one Goal per theme:

---
id: G-XXX
type: goal
title: [from success criteria theme]
status: review
owner: [OWNER from git config]
created: [current date]
updated: [current date]
contributors:
  - F-XXXX
  - F-YYYY
source: "bmad:success-criteria:user"  # or :business, :technical
---

Body content: Must start with # Title. Then: Overview (what this goal achieves and why), Success Indicators (measurable outcomes from PRD success criteria), Contributing Features (linked list).

  1. Assign contributing features -- Map each parent feature to the Goal(s) it most contributes to. Each parent feature should have at least one Goal. A feature can contribute to multiple Goals.

  2. Update feature goals: arrays -- Set goals: [G-XXX] on each parent feature and propagate to its children.

  3. Create speclan/goals/ directory and write goal files as flat files: G-XXX-slug.md.

12. Create Vision and Mission

After the full specification tree is generated (features, requirements, AND goals), create Vision and Mission files.

Vision (speclan/vision.md):

# Vision

[From PRD Executive Summary vision statement. One paragraph: the aspirational future state the product enables. Forward-looking, inspirational. Implementation-agnostic.]

Mission (speclan/mission.md):

# Mission

[From PRD Executive Summary problem/solution statement. One paragraph: what the product does, for whom, and how it delivers value. Present-tense, concrete. Implementation-agnostic.]

13. Cross-Link Entities

After the full specification tree exists on disk, scan all generated files and insert inline relative markdown links wherever one spec's prose mentions functionality defined in another spec.

Step 1 — Goal contributing-features links (mandatory):

Goal files have a contributors: frontmatter field listing feature IDs. For each goal, generate a "Contributing Features" section in the body with mandatory links to every contributing feature. Do NOT rely on text matching for these — generate them directly from the contributors array:

## Contributing Features

- [Core Gameplay](../features/F-0471-core-gameplay/F-0471-core-gameplay.md) — alien grid, player controls, scoring
- [Audio Engine](../features/F-0180-audio-engine/F-0180-audio-engine.md) — synthesized march bassline and effects

Every feature ID in contributors MUST have a working markdown link. Since goals live in speclan/goals/, the path is always ../features/F-XXXX-slug/F-XXXX-slug.md.

Step 2 — Build entity index:

Collect all generated entities into a lookup table:

{ title (lowercase) → relative file path from speclan/ }
{ slug keywords → relative file path from speclan/ }

For each entity, index:

  • Full title (e.g., "Destructible Shields")
  • Significant title fragments (e.g., "shield erosion", "alien grid", "march bassline")
  • Slug keywords from the directory name (e.g., F-0384-destructible-shields → "destructible shields", "shields")
  • Do NOT index generic words ("Core", "System", "Management")

Step 3 — Scan and link:

For each generated .md file (except goals — already handled in step 1), scan the body content only (below the closing --- of frontmatter):

  • Match mentions of other entities' titles or key phrases (case-insensitive)
  • Replace the first occurrence in each file with a relative markdown link
  • Compute the relative path from the current file's directory to the target file

Priority scan sections (most likely to contain cross-references):

  1. Out of Scope — explicitly names what other features handle
  2. Overview / Business Context — often references related capabilities
  3. In Scope — may mention adjacent feature boundaries
  4. Success Criteria — may reference related quality attributes
  5. Acceptance Criteria in requirements — may reference related features

Example — in F-0024-core-gameplay.md:

# Before:
- Shield rendering and erosion (covered by Destructible Shields)

# After:
- Shield rendering and erosion (covered by [Destructible Shields](../F-0414-destructible-shields/F-0414-destructible-shields.md))

Rules:

  • First mention only — link the first occurrence per target per file, not every mention
  • No self-links — never link an entity to its own file
  • Body only — never modify frontmatter or the # Title H1 heading
  • Don't nest links — skip text already inside a markdown link [...](...)
  • Relative paths from the file's own directory — compute the correct ../ depth from the linking file to the target file. Child features need ../../F-XXXX-sibling/.... Never use paths relative to speclan/ root — always relative to the file doing the linking.
  • Parent ↔ child links — parent feature bodies that mention child features should link to them, and vice versa
  • Cross-feature links — Out of Scope, Overview, Business Context, and In Scope sections are all prime link targets
  • Scan ALL files — do not skip any generated file. Every parent feature, child feature, and requirement must be scanned. Partial cross-linking (linking only a few features) defeats the purpose.

Step 4 — Verify:

  • Spot-check 3-5 files to confirm links resolve correctly
  • Verify goal links — open each goal file and confirm EVERY contributor has a working markdown link starting with ../features/
  • Verify cross-feature links — confirm at least half of parent features have at least one cross-link to another feature
  • Confirm no links appear inside frontmatter
  • Confirm no self-links

14. Output Summary

## Conversion Complete

Converted BMAD planning artifacts to SPECLAN hierarchical format.

### Source Documents
- PRD: [path]
- Epics: [path or "not found"]
- Architecture: [path or "not found"]

### Created Entities
| Type | Count |
|------|-------|
| Goals | X |
| Parent Features | Y |
| Child Features | Z |
| Requirements | W |

### Structure
speclan/
├── vision.md
├── mission.md
├── goals/
│   └── G-XXX-strategic-theme.md
└── features/
    └── F-XXXX-capability-area/
        ├── F-XXXX-capability-area.md
        ├── F-YYYY-story-1/
        │   ├── F-YYYY-story-1.md
        │   └── requirements/
        │       └── R-ZZZZ-description/
        │           └── R-ZZZZ-description.md
        └── F-YYYY-story-2/
            └── ...

### Next Steps
1. Review converted specifications: check entity titles and descriptions
2. Review goal groupings and adjust if needed
3. Adjust feature hierarchy if needed
4. Approve specs ready for development: change status to `approved`

### View Your Specs
Install the SPECLAN VS Code extension for the best viewing experience:
https://marketplace.visualstudio.com/items?itemName=DigitalDividend.speclan-vscode-extension

More info: https://speclan.net

Re-Import (Incremental Conversion)

When speclan/features/ already contains entities, the command operates in re-import mode. Re-import respects the SPECLAN status lifecycle — editable specs are updated in place, locked specs get change requests.

Step 1: Build Provenance Index

Grep speclan/ for entities with source: "bmad: in their YAML frontmatter. Build a lookup table:

{ source-identifier → file-path, current-status }

For example:

bmad:FR23 → speclan/features/F-1234-rendering/requirements/R-5678-grid-display/R-5678-grid-display.md, status: in-development
bmad:epic-3 → speclan/features/F-1234-rendering/F-1234-rendering.md, status: review

If no source: fields are found but entities exist, warn the user that provenance tracking is not available and ask whether to proceed with a full re-import (skip/overwrite) or cancel.

Step 2: Match and Decide

For each incoming BMAD element, look up its source identifier in the provenance index:

Existing StatusAction
Not foundCreate new entity (normal first-run flow with source: field)
draft / review / approvedUpdate in place — overwrite body content, update updated: timestamp. Preserve id, status, owner, created.
in-development / under-test / releasedCreate Change Request — generate a CR-#### in the entity's change-requests/ directory with changeType: enhancement, description summarizing what changed, and changes containing the updated content.
deprecatedSkip — log a warning, do not touch the entity.

Change Request generation for locked entities:

---
id: CR-XXXX
type: changeRequest
title: "Re-import update: [brief description of change]"
status: draft
owner: [OWNER from git config]
created: [current date]
updated: [current date]
parentId: [locked entity ID, e.g., R-5678]
parentType: [requirement or feature]
changeType: enhancement
description: "Updated content from BMAD re-import. Source: [bmad identifier]"
changes: |
  [Full updated content from the BMAD source, ready to be applied
  when the change request is approved and released.]
---

Generate CR IDs using the speclan-id-generator:

node "$SCRIPT" --type change-request --count 1 --speclan-root <speclan-dir>

Step 3: Detect Orphans

After processing all incoming BMAD elements, check for SPECLAN entities with source: "bmad:*" that were NOT matched by any incoming element. These are orphans — entities that existed in the previous BMAD version but are no longer present.

List orphans for user attention:

### Orphaned Entities (removed from BMAD source)
| Entity | Source | Status | Path |
|--------|--------|--------|------|
| R-5678 | bmad:FR42 | review | speclan/features/.../R-5678-slug.md |

These entities have source references to BMAD elements that no longer exist.
Options: keep as-is, deprecate, or delete manually.

Do NOT auto-delete orphans.

Step 4: Re-Import Summary

Include re-import statistics in the output summary:

### Re-Import Stats
| Action | Count |
|--------|-------|
| Created (new) | X |
| Updated (editable) | Y |
| Change Requests (locked) | Z |
| Skipped (deprecated) | W |
| Orphaned (removed from source) | V |

Error Handling

If PRD has no Functional Requirements section:

Error: PRD does not contain a Functional Requirements section.

Expected: ## Functional Requirements
With subsections: ### Capability Area Name
And FR lines: FR1: [Actor] can [capability]

The PRD may be incomplete. Create or complete the PRD using:
  /bmad-bmm-create-prd
  /bmad-bmm-edit-prd

If PRD format is unrecognized:

Warning: PRD format does not match BMAD standard.

Missing: [list of missing sections]
Found: [list of found sections]

Attempting best-effort conversion from available content...

SPECLAN From-Speckit Command

Convert speckit phase-based specifications to SPECLAN hierarchical format.

Prerequisites

This command requires understanding of both formats:

Speckit Format (source):

  • Located in specs/ directory
  • Numbered directories: ###-phase-name/
  • spec.md with bold markdown metadata
  • User stories with priorities (P1-P4), optionally grouped into PART sections
  • Functional requirements (FR-###)
  • Success criteria (SC-###)

SPECLAN Format (target):

  • Located in speclan/ directory
  • Entity hierarchy: Goal → Feature → Child Feature → Requirement
  • YAML frontmatter with proper IDs (G-###, F-####, R-####)
  • Directory-based storage with change-requests/ subdirectories

Instructions

1. Check Plugin Dependency

Verify speckit plugin is installed. If not:

Error: speckit plugin is not installed.

The /speclan:from-speckit command requires speckit for full functionality.
Install speckit plugin to enable this command.

Proceeding with manual conversion...

2. Locate Speckit Specs

Find speckit specifications:

  • Default: specs/ in project root
  • Or use provided directory argument
  • Look for numbered directories with spec.md files

3. Parse Speckit Format

For each spec.md file, extract:

Metadata:

  • Feature Branch name
  • Created date
  • Status
  • Input source

Content:

  • User stories (with priorities P1-P4)
  • PART sections (if present)
  • Functional requirements (FR-###)
  • Success criteria (SC-###)
  • Acceptance scenarios (Given/When/Then)
  • Key entities and business rules
  • Assumptions and constraints

4. Map to SPECLAN Entities

Convert speckit elements to a 3-level hierarchy:

Speckit ElementSPECLAN Entity
Phase (###-name)Parent Feature (F-####)
User Story / PART sectionChild Feature (F-####), nested under parent
Functional Requirement (FR-###)Requirement (R-####), under the child feature
Success Criterion (SC-###)Success criteria in parent feature body
Priority (P1-P4)priority-p# tag on child feature and its requirements
Acceptance Scenario (Given/When/Then)Acceptance criteria in requirement body

CRITICAL RULES:

  1. DO NOT add back-references. No ## Source sections linking to speckit files.

  2. All generated entities get status: review — converted specs are ready for review, not initial drafts.

  3. Every file body MUST start with # Title — H1 heading matching the frontmatter title field. No content before it. Subsequent sections use ## Heading (H2) and below.

  4. Directory and file names must be clean — Names must match pattern {PREFIX}-{digits}-{kebab-slug}. No curly braces, spaces, quotes, or other special characters.

  5. DO NOT carry over speckit identifiers into SPECLAN specs. No FR-###, SC-###, US-N, or PART A/B/C references. SPECLAN entities have their own identity. Describe functional requirements in plain language as numbered items instead.

  6. DO NOT create template directories. The command generates goals/ and features/ trees only.

  7. Requirements use directory-based storage — Each requirement is a directory containing its .md file: requirements/R-ZZZZ-slug/R-ZZZZ-slug.md. NEVER store requirements as flat files like requirements/R-ZZZZ-slug.md.

  8. IDs MUST be globally unique — Never generate IDs for multiple child features in a single batch without writing the previous batch's files to disk first. The ID generator's collision detection only works against files already on disk. Generate → write → generate → write, one child feature at a time.

  9. Implementation-agnostic specs — Strip technology names, file paths, library references, and architecture decisions. SPECLAN specs describe WHAT, never HOW. This applies to ALL entities including goals and success indicators.

    • Strip: specific runtime names, framework names, package managers, library names, specific file paths
    • Replace with generic terms: "target runtime" (not a specific version), "package manager" (not a specific tool)
    • Allowed: Domain-specific standards that ARE the requirement (e.g., "ANSI colors", "Unicode block elements")
  10. No empty child features — Every child feature MUST have at least one requirement. If a speckit user story or PART section has no FRs, either: (a) decompose the scope items into individual requirements, or (b) merge into a sibling child feature. Never create a child feature with requirements: [].

5. Identify Child Feature Groupings

Before generating files, analyze each spec.md to identify child feature boundaries:

Pattern A: PART sections (e.g., "PART A: Product Separation", "PART B: Contact Roles")

  • Each PART becomes one child feature
  • User stories within the PART contribute to the child feature's description
  • FRs within the PART become requirements under that child feature

Pattern B: User stories without PARTs (e.g., US1-US7 at top level)

  • Group user stories by functional domain (authentication, data management, workflow, etc.)
  • Each group becomes one child feature
  • Aim for 3-7 child features per parent (not 1:1 user story to feature)
  • When in doubt, group by P1/P2/P3 priority tiers

6. Generate Entity IDs (Phased)

Generate IDs using the speclan-id-generator JS CLI. IDs are generated in phases because --parent requires the parent entity to exist on disk.

SCRIPT="${CLAUDE_PLUGIN_ROOT}/skills/speclan-id-generator/scripts/generate-id.mjs"

Phase A — Parent feature IDs (no --parent, generated first):

node "$SCRIPT" --type feature --count <num-phases> --speclan-root <speclan-dir>
# Output: {"ok":true,"data":{"type":"feature","ids":["F-1234","F-5678",...]}}

Add --raw to get the IDs one per line instead of JSON. Write parent feature files to disk immediately.

Phase B — Child feature IDs (with --parent, after parent files exist):

# For each parent feature:
node "$SCRIPT" --type feature --parent F-1234 --count <num-children> --speclan-root <speclan-dir>

The --parent flag generates IDs end-biased after existing siblings, preserving natural ordering within the parent. Write child feature files to disk immediately.

Phase C — Requirement IDs (with --parent, one child feature at a time):

# For EACH child feature individually:
#   1. Generate requirement IDs for this child feature
node "$SCRIPT" --type requirement --parent F-YYYY --count <num-reqs> --speclan-root <speclan-dir>
#   2. Write all requirement files for this child feature to disk
#   3. THEN move to the next child feature

CRITICAL: Generate and write requirements one child feature at a time. The ID generator detects collisions only against files already on disk. If you generate requirement IDs for multiple child features before writing any to disk, you WILL get duplicate IDs.

Phase D — Goal IDs (after all features exist, step 10):

node "$SCRIPT" --type goal --count <num-goals> --speclan-root <speclan-dir>

IMPORTANT: The pattern at every level is: generate IDs → write files to disk → generate next batch. Never batch ID generation across multiple parents without writing intermediate results.

7. Determine Owner

Get the git identity for the owner field on all generated entities:

OWNER=$(git config user.name)

If git user.name is not set, prompt the user for an owner value. Never leave owner empty.

8. Generate SPECLAN Files

Write files top-down: all parent features first (Phase A IDs), then child features (Phase B IDs), then requirements (Phase C IDs). Each level must be on disk before generating the next level's IDs with --parent.

Parent Feature (one per speckit phase)
---
id: F-XXXX
type: feature
title: [from speckit Feature Branch name]
status: review
owner: [OWNER from git config]
created: [from speckit created date]
updated: [current date]
goals: []  # Updated in Goal Creation step
depends-on: [F-XXXX]  # Previous phase's parent feature (omit for first phase)
tags: [phase-N]
source: "speckit:001-phase-name"  # speckit phase directory name
---

Directory layout:

speclan/features/F-XXXX-slug/
├── F-XXXX-slug.md              ← parent feature file
├── F-YYYY-child-1/             ← child feature (sibling of parent .md)
│   ├── F-YYYY-child-1.md
│   └── requirements/
│       └── R-ZZZZ-req/
│           └── R-ZZZZ-req.md
└── F-YYYY-child-2/             ← another child feature
    └── ...

IMPORTANT: Child feature directories are SIBLINGS of the parent .md file, NOT nested inside a subdirectory named after the parent.

Anti-pattern (WRONG — double-nesting):

F-XXXX-slug/F-XXXX-slug/F-YYYY-child/  ← NEVER do this

Body content: Must start with # Title. Then: Overview, Scope (In/Out), Key Entities, Success Criteria (as checkboxes).

Child Feature (one per User Story group or PART section)
---
id: F-YYYY
type: feature
title: [from User Story title or PART name]
status: review
owner: [OWNER from git config]
created: [from speckit created date]
updated: [current date]
goals: []  # Updated in Goal Creation step
requirements: [R-XXXX, R-XXXX, ...]
tags: [priority-p1]
source: "speckit:001-phase-name:part-a"  # or :us1-us3 for story groups
---

Directory: speclan/features/F-XXXX-parent/F-YYYY-child/ Body content: Must start with # Title. Then: User Story (As a... I want... so that...), Scope, Business Context.

Requirement (one per FR or logical FR group)
---
id: R-ZZZZ
type: requirement
title: [descriptive title — no speckit FR numbers]
status: review
owner: [OWNER from git config]
created: [current]
updated: [current]
feature: F-YYYY
source: "speckit:001-phase-name:FR-001"  # speckit phase + FR number
---

Directory: speclan/features/F-XXXX-parent/F-YYYY-child/requirements/R-ZZZZ-slug/R-ZZZZ-slug.md

Requirements use directory-based storage (directory name matches file name):

CORRECT:  requirements/R-ZZZZ-slug/R-ZZZZ-slug.md
WRONG:    requirements/R-ZZZZ-slug.md  ← flat file, NEVER do this

Body content: Must start with # Title. Then: Description (plain language, no FR-### references), Acceptance Criteria (Given/When/Then checkboxes). Each acceptance criterion MUST be a single - [ ] line with Given/When/Then separated by semicolons (e.g., - [ ] **Given** X; **When** Y; **Then** Z). Multi-line format breaks markdown checkbox rendering.

9. Capture Phase Dependencies

Speckit phases build sequentially (001 → 002 → 003...).

For each parent feature derived from phase N > 1:

  • Add depends-on: field listing the parent feature ID of phase N-1
  • If a phase explicitly references entities from a non-adjacent phase, add that dependency too
# Parent feature for Phase 003
depends-on:
  - F-XXXX  # Phase 002 parent feature ID

10. Create Goals

After all features and requirements are generated, analyze the full set of parent features and synthesize Goals:

  1. Group parent features by strategic theme — Look for natural business domains across the phases (e.g., "Installation Workflow Management", "Multi-Tenant Platform", "Energy Analysis").

  2. Create one Goal per theme:

---
id: G-XXX
type: goal
title: [strategic theme name]
status: review
owner: [OWNER from git config]
created: [current date]
updated: [current date]
contributors:
  - F-XXXX
  - F-YYYY
source: "speckit:goal-theme-slug"  # synthesized goal provenance
---

Body content: Must start with # Title. Then: Overview (1-2 paragraphs on what this goal achieves and why), Success Indicators (measurable outcomes derived from contributing features' success criteria), Contributing Features (linked list).

  1. Update feature goals: arrays — Set goals: [G-XXX] on each parent feature and its children.

  2. Create speclan/goals/ directory and write goal files as flat files: G-XXX-slug.md.

11. Create Vision and Mission

After the full specification tree is generated (features, requirements, AND goals), create Vision and Mission files that synthesize the overall product direction. These are created LAST because the full picture is needed.

Vision (speclan/vision.md):

# Vision

[One paragraph: the aspirational future state the product enables.
Derived from the full set of goals and features. Forward-looking, inspirational.]

Mission (speclan/mission.md):

# Mission

[One paragraph: what the product does, for whom, and how it delivers value.
Derived from the scope sections across all parent features. Present-tense, concrete.]

12. Cross-Link Entities

After the full specification tree exists on disk, scan all generated files and insert inline relative markdown links wherever one spec's prose mentions functionality defined in another spec.

Step 1 — Build entity index:

Collect all generated entities into a lookup table:

{ title (lowercase) → relative file path from speclan/ }
{ slug keywords → relative file path from speclan/ }

For each entity, index:

  • Full title (e.g., "Contact Roles")
  • Significant title fragments (e.g., "product separation", "billing workflow")
  • Do NOT index generic words ("Core", "System", "Management")

Step 2 — Scan and link:

For each generated .md file, scan the body content only (below the closing --- of frontmatter):

  • Match mentions of other entities' titles or key phrases (case-insensitive)
  • Replace the first occurrence in each file with a relative markdown link
  • Compute the relative path from the current file's directory to the target file

Rules:

  • First mention only — link the first occurrence per target per file, not every mention
  • No self-links — never link an entity to its own file
  • Body only — never modify frontmatter or the # Title H1 heading
  • Don't nest links — skip text already inside a markdown link [...](...)
  • Relative paths — always use relative paths, never absolute
  • Parent ↔ child links — parent feature bodies that mention child features should link to them, and vice versa
  • Goal ↔ feature links — goal "Contributing Features" lists should link to the feature files
  • Cross-feature links — "Out of Scope" sections that reference other features are prime link targets

Step 3 — Verify:

  • Spot-check 3-5 files to confirm links resolve correctly
  • Confirm no links appear inside frontmatter
  • Confirm no self-links

13. Output Summary

## Conversion Complete

Converted [X] speckit phases to SPECLAN hierarchical format.

### Created Entities
| Type | Count |
|------|-------|
| Goals | X |
| Parent Features | Y |
| Child Features | Z |
| Requirements | W |

### Structure
speclan/
├── vision.md
├── mission.md
├── goals/
│   └── G-XXX-strategic-theme.md
└── features/
    └── F-XXXX-phase-name/
        ├── F-XXXX-phase-name.md
        ├── F-YYYY-child-feature-1/
        │   ├── F-YYYY-child-feature-1.md
        │   └── requirements/
        │       └── R-ZZZZ-description/
        │           └── R-ZZZZ-description.md
        └── F-YYYY-child-feature-2/
            └── ...

### Next Steps
1. Review converted specifications
2. Review goal groupings and adjust if needed
3. Adjust child feature groupings if needed

Re-Import (Incremental Conversion)

When speclan/features/ already contains entities, the command operates in re-import mode. Re-import respects the SPECLAN status lifecycle — editable specs are updated in place, locked specs get change requests.

Step 1: Build Provenance Index

Grep speclan/ for entities with source: "speckit: in their YAML frontmatter. Build a lookup table:

{ source-identifier → file-path, current-status }

If no source: fields are found but entities exist, warn the user that provenance tracking is not available and ask whether to proceed with a full re-import (skip/overwrite) or cancel.

Step 2: Match and Decide

For each incoming speckit element, look up its source identifier in the provenance index:

Existing StatusAction
Not foundCreate new entity (normal first-run flow with source: field)
draft / review / approvedUpdate in place — overwrite body content, update updated: timestamp. Preserve id, status, owner, created.
in-development / under-test / releasedCreate Change Request — generate a CR-#### in the entity's change-requests/ directory with changeType: enhancement, containing the updated content from speckit.
deprecatedSkip — log a warning, do not touch the entity.

Step 3: Detect Orphans

After processing all incoming speckit elements, check for SPECLAN entities with source: "speckit:*" that were NOT matched. List orphans for user attention. Do NOT auto-delete.

Step 4: Re-Import Summary

### Re-Import Stats
| Action | Count |
|--------|-------|
| Created (new) | X |
| Updated (editable) | Y |
| Change Requests (locked) | Z |
| Skipped (deprecated) | W |
| Orphaned (removed from source) | V |

Error Handling

If speckit directory not found:

Error: No speckit specifications found.

Expected location: specs/
Expected format: ###-phase-name/spec.md

Verify speckit specs exist before running this command.

SPECLAN Grill Command

Explicit entry point for the SPECLAN Grill skill. Load the skill and run a grilling session on the target spec(s).

Invocation

/speclan:grill F-1049
/speclan:grill R-2046
/speclan:grill export pipeline
/speclan:grill F-1049 --language de
/speclan:grill --language french
/speclan:grill

Procedure

  1. Detect the speclan root using SPECLAN_ROOT=$(node "${CLAUDE_PLUGIN_ROOT}/skills/speclan-format/scripts/detect-speclan.mjs")
  2. Load the grill skill (${CLAUDE_PLUGIN_ROOT}/skills/grill/SKILL.md)
  3. Parse the arguments:
    • --language <lang> (language code or name) → conduct the whole interview in that language; spec files are still written in English (see the skill's Session Language section). When omitted, reuse the language last set via --language (or requested in conversation) earlier in this session; otherwise default to English
    • An entity ID (G-###, F-####, R-####) → grill that entity and its children
    • A topic string → locate the matching spec by exploring $SPECLAN_ROOT, confirm with the user
    • Empty target → prefer the topic already being worked on in this session; otherwise offer specs in draft/review status
  4. Follow the skill's workflow: one question at a time with a recommended answer, and after each resolved finding ask whether to apply it to the spec or note it for the summary

Sequential Implementation Strategy

Implement a custom planfile's items one by one in dependency order. Each item follows a strict cycle: read spec, implement with logging, write tests, verify, mark done. At feature boundaries, run a broader milestone review.

Custom planfiles contain standalone requirements and change requests not nested under a pending feature. Handle both nested and standalone items.

Phase 0: Orient

0a. Read the Planfile

Parse the planfile to understand the full scope:

  • [~] items — resume these first (partial work from a prior session)
  • [ ] items — pending work
  • [?] items — needs review: read the spec's acceptance criteria, verify the implementation against them, fix any gaps found, then mark [x]
  • [x] items — done, skip

Distinguish item types — this determines the implementation approach:

  • Features (F-) and Requirements (R-) — new functionality to build
  • Change Requests (CR-) — existing implementation must be found and altered, not built from scratch. CR lines in the planfile are annotated with CHANGE REQUEST: find and alter existing implementation

Count the totals and report the current state to the user.

0b. Resume Check

Priority order for picking up work:

  1. [?] items first — review them: verify implementation against spec acceptance criteria, fix gaps, then mark [x]
  2. [~] items next — resume partial implementation from a prior session
  3. [ ] items last — new work, proceed to ordering (Step 0c)

If [?] or [~] items exist, skip ordering — handle them first, then return to determine order for remaining [ ] items.

0c. Determine Implementation Order

Analyze dependencies between all [ ] items. For each one, read its spec and look for:

  1. Parent-child — directory nesting and feature: / parentId: frontmatter fields. Parents before children.
  2. Cross-references — markdown links or phrases like "depends on R-XXXX", "requires R-XXXX", "after R-XXXX" in the spec body.
  3. Logical sequencing — foundations before consumers (types before services, contracts before implementations, providers before consumers).

For 3+ features, use the implementation-order agent (subagent_type: speclan:implementation-order) to determine feature order.

For standalone items (R-/CR- not under a pending feature), sequence them after their parent feature's other children, or by dependency if no parent is pending.

0d. Record Implementation Order

Write the determined order somewhere recoverable for the next session — a comment block at the top of the planfile. Keep it to a numbered list with rationale. This is purely for cross-session continuity of the ordering decision.


Phase 1: Per-Item Implementation Cycle

For each item in the determined order, run this cycle. Complete one item fully before starting the next.

Step 1 — Read the Specification

Extract the spec path from the planfile link sub-bullet (path inside parentheses):

- [ ] [R-0548] Title
  - [R-0548](speclan/.../R-0548-slug/R-0548-slug.md)

Read the spec file thoroughly — scope, acceptance criteria, business rules.

Then discover context:

Ancestors — walk up the directory tree from the spec path. Each parent directory matching F-XXXX-* or R-XXXX-* is an ancestor entity. Read its spec (the .md with the same name as the directory) to understand what system this item belongs to and what concepts mean in context.

References — scan the spec body for markdown links to other specs ([R-1496](../R-1496-.../R-1496-....md)). Read referenced specs to understand cross-cutting concerns, dependencies, and integration points the implementation must respect.

Prior work — check for CLAUDE.md files in the code areas you're about to touch. They contain architecture decisions, contracts, and gotchas captured during earlier implementation steps. This is especially important when resuming in a new session.

Step 2 — Mark In-Progress

Edit the planfile: change [ ] to [~] for this item.

If the spec has a status: frontmatter field, set it to in-development. This status update is the only edit allowed on spec files — never change spec content (titles, descriptions, acceptance criteria, scope).

Step 3 — Implement

Build the implementation based on the spec's scope and acceptance criteria. "Implement" means writing or changing source code in the codebase — never editing spec files in speclan/. Specs are input (what to build), not output (what to change).

For requirements and features — build new functionality as described; the requirements belong to a feature so understand its context.

For change requests (lines annotated CHANGE REQUEST: find and alter existing implementation) — a CR describes changes to existing code, not changes to specs. The workflow is:

  1. Read the CR spec to understand what needs to change
  2. Read the parent entity's spec to understand the original design
  3. Search the codebase for the existing code that implements the parent entity
  4. Alter that code as the CR describes — do not rebuild from scratch
  5. Leave all spec files (speclan/**) untouched — the CR spec stays as-is, the parent spec stays as-is

Logging and tracing — add structured logging at meaningful boundaries:

  • Service entry/exit with operation name and key parameters
  • External API calls (provider, endpoint, request shape, response status)
  • Error paths with enough context to diagnose without reproducing (what failed, what was the input, what was expected)
  • Use the project's existing logging framework and conventions
  • The goal: when something breaks at 3 AM, the logs tell you what happened, in your code and at external providers, without requiring a debugger

Follow conventions — match the project's existing patterns for file organization, naming, error handling, and module structure.

Step 4 — Write Tests

Create tests for all source code produced in Step 3:

  • Unit tests for business logic and pure functions
  • Integration tests for service boundaries, external interactions, and anything the spec's acceptance criteria describe as observable behavior
  • Map acceptance criteria (Given...When...Then) directly to test cases where possible
  • Match the project's testing framework and conventions

Run the tests. Fix failures before proceeding.

Step 5 — Verify Against Spec

Walk through each acceptance criterion in the spec:

  • For each Given...When...Then, confirm the implementation and tests cover it
  • For each scope item, confirm it exists in the code
  • For change requests, confirm the existing code behavior was changed as the CR describes (not just new code added alongside, and not the spec altered)

If gaps exist, fix them in the source code and re-run tests.

Step 6 — Mark for Review

Edit the planfile: change [~] to [?] for this item.

If the spec has a status: frontmatter field, set it to under-test.

Step 7 — Capture Concepts in CLAUDE.md (near the code)

As implementation produces code, concepts emerge — design patterns, invariants, integration contracts, non-obvious gotchas. When a concept is worth remembering, create or update a CLAUDE.md file closest to the code the concept belongs to.

  • If you created src/providers/local/, and the local provider has a retry contract that callers must understand, put it in src/providers/local/CLAUDE.md
  • If you established a pattern across all providers in src/providers/, put it in src/providers/CLAUDE.md
  • If a gotcha applies project-wide, put it in the project root CLAUDE.md

What to capture:

  • Architecture decisions ("chose X over Y because...")
  • Contracts and invariants ("all providers must implement probe() — callers rely on it for availability checks")
  • Non-obvious behavior ("API returns 200 with error in body, must check .error field")
  • Integration points ("exports RunnerConfig — consumed by the CI integration module")

What NOT to capture: routine implementation facts derivable from reading the code. Only write what saves a future reader (human or AI) from having to reverse-engineer intent.

Step 8 — Report Progress

Completed: [ID] Title — now in review.
Progress: {done}/{total} items.
Next: [ID] Title

Phase 2: Milestone Review

Trigger a milestone review when one of these occurs:

  • Feature complete — all children of a feature are [?] or [x]
  • Logical group complete — a cluster of related standalone items is done (e.g., all "provider foundation" requirements)

Review checklist:

  1. Integration — do the implemented pieces work together? Check data flow across module boundaries. Run any existing integration or e2e tests.
  2. Logging coverage — can you trace a request end-to-end through the implemented feature using only the logs? If not, add the missing log points.
  3. Test coverage — do tests cover all acceptance criteria from the specs? Any untested paths?
  4. Spec compliance — re-read the feature spec (if applicable) and confirm the overall intent is met, not just individual requirement checkboxes.

Fix findings immediately. Update CLAUDE.md with corrections.

For standalone items without a feature grouping, run a lighter review after each item: spec compliance + tests pass.


Phase 3: Wrap Up

When all planfile items are [x]:

  1. Update CLAUDE.md plan section with final status
  2. Report completion:
## Plan Complete

Plan: {filename}
Items implemented: {count}
Items ready for review: {review_count}

Run review to verify implementations against specs.

Cross-Session Continuity

These plans often span multiple Claude Code sessions. Two things carry state across sessions:

  1. Planfile checkboxes — [~] marks where to resume, [?]/[x] marks what's done
  2. CLAUDE.md files near the code — capture the concepts, decisions, and contracts that emerged during implementation

When resuming in a new session:

  1. Read the planfile — find the first [~] (resume implementation) or [?] (needs review) or [ ] (next) item
  2. Read CLAUDE.md files in the areas you'll be working in — recover architecture decisions, patterns, and gotchas from prior sessions
  3. Continue from where the prior session left off

When ending a session mid-plan:

The current item should be either [~] (in progress, will resume) or [?] (needs review, will resume) or [ ] (next item starts fresh). Ensure any concepts worth remembering are captured in the appropriate CLAUDE.md before ending.

SPECLAN Implement Manual Command

Pick up a manual implementation plan and implement the next actionable item.

Instructions

Apply the implement-manual skill to find the next actionable item and implement it.

Arguments

  • [plan-file] - Optional path to a specific plan file. If omitted, searches speclan/.local/plans/ for *.plan.md files.

Example

# Implement next item (auto-detect plan file)
/speclan:implement-manual

# Use a specific plan file
/speclan:implement-manual speclan/.local/plans/export-to-document.2026-02-04T15-44.plan.md

SPECLAN Plan Manual Command

Generate a checklist-based implementation plan from approved features, requirements, and change requests.

Instructions

CRITICAL: Follow these steps in exact order. Do NOT skip ahead or explore the speclan directory manually.

Step 1: Query for approved specs FIRST

Before doing anything else, run the query script to check if approved specs exist:

SPECLAN_DIR="${1:-./speclan}"
QUERY="${CLAUDE_PLUGIN_ROOT}/skills/speclan-query/scripts/query.mjs"

APPROVED_FEATURES=$(node "$QUERY" --type feature --filter-status approved --full "$SPECLAN_DIR")
APPROVED_REQS=$(node "$QUERY" --type requirement --filter-status approved --full "$SPECLAN_DIR")
APPROVED_CRS=$(node "$QUERY" --type change-request --filter-status approved --full "$SPECLAN_DIR")

echo "=== Approved Features ==="
echo "$APPROVED_FEATURES"
echo "=== Approved Requirements ==="
echo "$APPROVED_REQS"
echo "=== Approved Change Requests ==="
echo "$APPROVED_CRS"

Step 2: Stop if nothing is approved

If all three JSON arrays are empty ([]), report and STOP:

No approved specifications found in speclan/.

To approve specs for implementation, set their status to "approved":
  status: approved

Do NOT proceed further. Do NOT launch agents, create files, or explore the speclan directory.

Step 3: Create the plan file

Only if Step 1 returned non-empty results, apply the plan-manual skill to create the plan file.

The plan file MUST be written to this exact path:

{SPECLAN_DIR}/.local/plans/{slug}.{YYYY-MM-DDTHH-MM}.plan.md

Create the directory first: mkdir -p "{SPECLAN_DIR}/.local/plans"

Do NOT write the plan file anywhere else. Do NOT name it PLAN.md or any other name.

The plan-manual skill defines the exact file format — follow it precisely.

Arguments

  • [path] - Optional path to speclan directory (default: ./speclan)

SPECLAN Review Manual Command

Review all in-review items from a manual implementation plan.

FORBIDDEN: Do NOT use Edit or Write on any file inside speclan/ except speclan/.local/plans/*.plan.md. Spec files are read-only. Do NOT change any spec status: field. The only Edit allowed is [?] → [x] in the plan file.

Instructions

Apply the review-manual skill to review all [?] items and verify their implementations against their specs.

Arguments

  • [plan-file] - Optional path to a specific plan file. If omitted, searches speclan/.local/plans/ for *.plan.md files.

Example

# Review next item (auto-detect plan file)
/speclan:review-manual

# Use a specific plan file
/speclan:review-manual speclan/.local/plans/export-to-document.2026-02-04T15-44.plan.md

SPECLAN Status Command

Display comprehensive status information about the SPECLAN project.

Instructions

When invoked, perform these checks and display results in table format:

1. Detect SPECLAN Directory

Search for speclan directory starting from provided path or current working directory:

  • Check common locations: speclan/, specs/speclan/, .speclan/, .specs/speclan/ (any of these may be a symlink, e.g. into a spec submodule)
  • Verify characteristic subdirectories: features/ and/or goals/

If not found, display error with setup instructions.

2. Check Plugin Dependencies

Check if optional plugins/tools are installed:

  • speckit - Required for /speclan:from-speckit and /speclan:to-speckit
  • feature-dev - Required for /speclan:implement
  • BMAD-METHOD - Check for _bmad/ directory and _bmad/bmm/config.yaml. Required for /speclan:from-bmad, /speclan:to-bmad, and /speclan:to-bmad-prd. Also check if _bmad-output/planning-artifacts/ contains a PRD.

Display installation status for each.

3. Count Specifications by Type

Count spec files in each category:

EntityDirectoryPattern
Goalsgoals/G-*.md
Featuresfeatures/F-*.md (recursive)
Requirementsrequirements/ or within featuresR-*.md
Templatestemplates/*.md

4. Analyze Status Distribution

Parse YAML frontmatter to count specs by status:

  • draft
  • review
  • approved
  • in-development
  • under-test
  • released
  • deprecated

5. Check Coverage

Calculate coverage metrics:

  • Features with at least one requirement
  • Approved features ready for implementation

6. Display Results

Present as formatted tables:

## SPECLAN Project Status

**Directory:** /path/to/speclan

### Specification Counts
| Entity | Count |
|--------|-------|
| Goals | X |
| Features | X |
| ... | ... |

### Status Distribution
| Status | Count |
|--------|-------|
| approved | X |
| draft | X |
| ... | ... |

### Plugin Dependencies
| Plugin | Status | Required For |
|--------|--------|--------------|
| speckit | Installed/Missing | from-speckit, to-speckit |
| feature-dev | Installed/Missing | implement |
| BMAD-METHOD | Installed/Missing | from-bmad, to-bmad, to-bmad-prd |

### Coverage
| Metric | Value |
|--------|-------|
| Features with requirements | X% |
| Approved features | X |

Error Handling

If SPECLAN directory not found:

Error: No SPECLAN directory found in this project.

To set up SPECLAN, create:
  speclan/
  ├── goals/
  ├── features/
  └── requirements/

If plugin missing and user tries dependent command, show:

Error: [plugin] plugin is not installed.

Install with: [installation instructions]

7. Check Rules Setup

Check if a SPECLAN rules file exists in .claude/rules/:

ls .claude/rules/speclan*.md 2>/dev/null

If missing, show:

### Rules Setup

No SPECLAN rules file found in .claude/rules/.

For path-restricted format guidance, add a speclan.md rule file to .claude/rules/
with paths: ["speclan/**/*.md"] frontmatter. See https://github.com/user/speclan for the standard template.

SPECLAN Sync from Session

Analyze the current session to identify implemented features and sync them to SPECLAN specifications.

Core Philosophy: Implementation Reveals Specification Gaps

Specifications written before implementation are incomplete by nature. Real implementation work exposes:

  • Missing requirements - Edge cases, error handling, validation rules discovered during coding
  • Implicit assumptions - Behaviors that were obvious to implement but never documented
  • Integration points - Dependencies and interactions only visible when building
  • User experience details - UI flows, feedback mechanisms, accessibility considerations

This command treats implementation as the source of truth. When code does something useful that isn't in the spec, the spec is incomplete - not the code.

When to Add Requirements

Add new requirements when implementation reveals:

Implementation PatternLikely Missing Requirement
Error handling/validationInput validation rules, error messages
Retry logic, timeoutsReliability/resilience requirements
Caching, optimizationPerformance requirements
Logging, metricsObservability requirements
Permission checksAuthorization requirements
Edge case handlingBoundary condition requirements
Default valuesConfiguration/defaults requirements
User feedback (toasts, spinners)UX feedback requirements

Instructions

1. Parse Arguments

Flags:

  • --dry-run - Show what would be created/updated without making changes

User Hints (optional free-form text): After flags, the user may provide guidance to help focus the analysis:

/speclan:sync focus on the auth changes, don't miss the token refresh logic
/speclan:sync --dry-run look at src/api/ folder, we added new endpoints
/speclan:sync important: the rate limiting feature, also check the middleware

Hint Categories:

Hint TypeKeywordsPurpose
Focus areas"focus on", "look at", "check"Direct attention to specific code/features
Must-include"don't miss", "important", "make sure"Ensure specific items are captured
Exclusions"ignore", "skip", "not relevant"Avoid false positives
Context"we added", "new feature", "bugfix for"Clarify intent of changes

2. Process User Hints

If hints provided, extract and categorize:

user_guidance:
  focus_areas:
    - "auth changes"
    - "src/api/ folder"
  must_include:
    - "token refresh logic"
    - "rate limiting feature"
  exclusions: []
  context:
    - "new endpoints added"
    - "middleware changes"

Use this guidance to:

  1. Prioritize - Analyze focus areas first and more thoroughly
  2. Validate - Cross-check must-include items are captured in results
  3. Filter - Skip excluded areas during analysis
  4. Interpret - Use context to better understand change intent

3. Load Skill Knowledge

Apply the Sync Specs from Session skill for detailed workflow guidance.

4. Analyze Session Context

Review the conversation history to identify implementation work:

4.1 Scan for Code Changes

Look for evidence of implementation:

  • File writes/edits: Write and Edit tool usage
  • New functions/classes: Code patterns added
  • API endpoints: Routes, handlers, controllers
  • Data models: Schema changes, type definitions
  • Tests added: Test files created or modified
4.2 Extract Feature Candidates

For each identified change, determine:

  • Title: Descriptive name for the feature
  • Description: What it does and why
  • Code paths: Files involved (internal use for matching — never written to specs)
  • Type: new feature, enhancement, or bugfix
  • Status: determined from implementation evidence (see 4.2a)
4.2a Determine Status

Since sync-from-session runs after vibe coding, the code already exists. The spec status must reflect where the implementation actually is — never draft or approved (those are pre-implementation states).

Tests exist?Tests pass?Code complete?Status
YesYesYesunder-test
YesSome fail—in-development
No—Yesin-development
——Partialin-development

Search for test files (*.test.*, *.spec.*) matching the implementation, check session history for test runs, and look for TODO/FIXME markers. Default to in-development when uncertain.

4.3 Infer Requirements from Implementation

Critical step: Analyze implemented code to discover undocumented requirements:

For each code change, ask:
1. What user-visible behavior does this enable?
2. What edge cases does this handle?
3. What validation/error handling was added?
4. What performance/reliability concerns does this address?
5. What dependencies or integrations does this require?

Example inference:

Code: if (retries > 3) throw new Error('Max retries exceeded')
Inferred requirement: "System shall retry failed operations up to 3 times before failing"

Code: toast.success('Changes saved')
Inferred requirement: "System shall provide visual feedback when changes are saved"

Code: if (!user.hasPermission('admin')) return 403
Inferred requirement: "Only administrators can access this functionality"
4.4 Group Related Changes

Consolidate related changes:

  • Multiple files for one feature = single feature entry
  • Independent changes = separate feature entries

5. Detect Speclan Directory

# Find speclan directory
if [ -d "speclan/features" ]; then
  echo "Found: speclan/"
elif [ -d "specs/speclan/features" ]; then
  echo "Found: specs/speclan/"
else
  echo "No speclan directory found"
fi

If no speclan directory exists, ask user if they want to initialize one.

6. Index Existing Specs

If speclan exists, use the SPECLAN Query skill to build an index:

# List all features with full metadata (JSON output)
node "${CLAUDE_PLUGIN_ROOT}/skills/speclan-query/scripts/query.mjs" --type feature --full speclan

# List requirements for a specific feature
node "${CLAUDE_PLUGIN_ROOT}/skills/speclan-query/scripts/query.mjs" --type requirement --parent F-1234 --full speclan

# Filter by status (e.g., find editable features)
node "${CLAUDE_PLUGIN_ROOT}/skills/speclan-query/scripts/query.mjs" --type feature --filter-status draft --full speclan

Output format (JSON):

[
  {"id":"F-1234","slug":"my-feature","type":"feature","path":"speclan/features/F-1234-my-feature/F-1234-my-feature.md","title":"My Feature","status":"draft"}
]

Use this to:

  1. Find features that match session work
  2. Determine if features are editable or locked
  3. Identify where to add new requirements

7. Compare and Classify Changes

For each feature candidate from session analysis:

Match ResultClassificationAction
No match in speclanCREATENew feature spec
Matches existing, status editableUPDATEModify existing spec
Matches existing, status lockedCHANGE_REQUESTCreate CR
Implementation detail of existing featureADD_REQUIREMENTNew requirement

Editable statuses: draft, review, approved Locked statuses: in-development, under-test, released, deprecated

7.1 Prioritize Requirement Discovery

Most syncs should produce new requirements, not just feature updates.

When analyzing implementation against existing specs:

  1. Read the existing feature spec thoroughly
  2. Compare each implemented behavior against documented scope
  3. For each undocumented behavior, create a requirement
Existing spec says: "Users can save their preferences"
Implementation adds: retry logic, validation, success toast, error handling

→ Add requirements:
  - R-####: "Preference saves shall retry up to 3 times on failure"
  - R-####: "Invalid preference values shall show validation error"
  - R-####: "Successful save shall display confirmation message"
  - R-####: "Failed save shall display actionable error message"

Rule of thumb: If you wrote more than 20 lines of code for a feature, there's probably at least one missing requirement.

8. Present Changes to User

Show identified changes and ask for confirmation:

## Session Analysis Results

Based on this session, I identified:

### New Features (CREATE)
1. **[Title]** - [Description]
   - Determined status: [in-development | under-test] — [reason]

### Updates to Existing Features (UPDATE)
1. **[F-####] [Title]** - [What changed]
   - Current status: [status] (editable)

### Change Requests Needed (LOCKED)
1. **[F-####] [Title]** - Cannot edit directly
   - Status: [status] (locked)
   - Proposed change: [description]

### New Requirements
1. For **[F-####]**: [Requirement title]

Use AskUserQuestion:

questions:
  - question: "Which changes should I apply to SPECLAN specs?"
    header: "Apply"
    multiSelect: true
    options:
      - label: "Create: [Feature Title]"
        description: "New feature spec"
      - label: "Update: F-#### [Title]"
        description: "Add [change] to existing feature"
      # ... additional options

9. Handle Dry Run

If --dry-run flag provided:

  • Show all changes that would be made
  • Do NOT write any files
  • Report: "Dry run complete. No changes made."

10. Apply Selected Changes

For each user-selected change:

ID Generation (MUST USE)

DO NOT create your own ID generator. Use this collision-safe algorithm:

# Generate unique Feature ID (4-digit, F-1000 to F-9999)
generate_feature_id() {
  local speclan_dir="${1:-speclan}"
  for attempt in $(seq 1 100); do
    local num=$((RANDOM % 9000 + 1000))
    local id="F-${num}"
    if [ ! -d "$speclan_dir" ] || \
       (! find "$speclan_dir" -name "${id}-*" 2>/dev/null | grep -q . && \
        ! grep -r "^id: ${id}$" "$speclan_dir" 2>/dev/null | grep -q .); then
      echo "$id"
      return 0
    fi
  done
  echo "ERROR: Could not generate unique ID" >&2
  return 1
}

# Generate unique Requirement ID (4-digit, R-1000 to R-9999)
generate_requirement_id() {
  local speclan_dir="${1:-speclan}"
  for attempt in $(seq 1 100); do
    local num=$((RANDOM % 9000 + 1000))
    local id="R-${num}"
    if [ ! -d "$speclan_dir" ] || \
       (! find "$speclan_dir" -name "${id}-*" 2>/dev/null | grep -q . && \
        ! grep -r "^id: ${id}$" "$speclan_dir" 2>/dev/null | grep -q .); then
      echo "$id"
      return 0
    fi
  done
  echo "ERROR: Could not generate unique ID" >&2
  return 1
}

# Generate unique Change Request ID (4-digit, CR-1000 to CR-9999)
generate_cr_id() {
  local speclan_dir="${1:-speclan}"
  for attempt in $(seq 1 100); do
    local num=$((RANDOM % 9000 + 1000))
    local id="CR-${num}"
    if [ ! -d "$speclan_dir" ] || \
       (! find "$speclan_dir" -name "${id}-*" 2>/dev/null | grep -q . && \
        ! grep -r "^id: ${id}$" "$speclan_dir" 2>/dev/null | grep -q .); then
      echo "$id"
      return 0
    fi
  done
  echo "ERROR: Could not generate unique ID" >&2
  return 1
}
10.1 Create New Features
  1. Generate feature ID and get owner:

    FEATURE_ID=$(generate_feature_id speclan)
    OWNER=$(git config --get user.email)
    
  2. Create directory and file:

    SLUG=$(echo "[title]" | tr '[:upper:]' '[:lower:]' | tr ' ' '-' | tr -cd 'a-z0-9-')
    mkdir -p "speclan/features/${FEATURE_ID}-${SLUG}/requirements"
    
  3. Write feature spec with frontmatter:

    ---
    id: [FEATURE_ID]
    type: feature
    title: [Title]
    status: [determined in step 4.2a — in-development or under-test]
    owner: [OWNER from git config --get user.email]
    created: "[ISO-8601]"
    updated: "[ISO-8601]"
    goals: []
    ---
    
    # [Title]
    
    ## Overview
    [Description - focus on WHAT and WHY, not HOW]
    
    ## Scope
    - [User-facing functionality points]
    

IMPORTANT: Specs must be implementation-agnostic. Do NOT include:

  • Code paths, file names, or technical locations
  • Implementation details or internal architecture
  • Code fragments or snippets

Focus on WHAT the feature does for users, not HOW it's built.

10.2 Update Existing Features
  1. Read current feature file
  2. Update relevant sections (scope, implementation notes)
  3. Update updated timestamp
  4. Write file back
10.3 Create Change Requests

For locked features or requirements:

  1. Generate CR ID:

    CR_ID=$(generate_cr_id speclan)
    
  2. Create CR in entity's change-requests directory:

    # For features:
    mkdir -p "speclan/features/[feature-dir]/change-requests"
    
    # For requirements:
    mkdir -p "speclan/features/.../requirements/[requirement-dir]/change-requests"
    
  3. Write CR file with proper frontmatter (parentType: feature or requirement)

10.4 Create New Requirements
  1. Generate requirement ID:
    REQ_ID=$(generate_requirement_id speclan)
    SLUG=$(echo "[title]" | tr '[:upper:]' '[:lower:]' | tr ' ' '-' | tr -cd 'a-z0-9-')
    
  2. Create requirement directory:
    mkdir -p "speclan/features/[feature-dir]/requirements/${REQ_ID}-${SLUG}"
    
  3. Write requirement file to directory:
    speclan/features/[feature-dir]/requirements/${REQ_ID}-${SLUG}/${REQ_ID}-${SLUG}.md
    
  4. Update parent feature's updated timestamp

11. Report Results

## Sync Complete

### Created
- F-#### [Title] → speclan/features/F-####-slug/
- R-#### [Title] → speclan/features/F-####/requirements/R-####-slug/

### Updated
- F-#### [Title] - added [changes]

### Change Requests
- CR-#### for F-#### → speclan/features/F-####/change-requests/
- CR-#### for R-#### → speclan/.../requirements/R-####/change-requests/

### Skipped
- [Any items user didn't select]

### Next Steps
- Review created specs for accuracy
- Assign goals to new features
- Process pending change requests
- Run /speclan:status to verify structure

Examples

# Sync session work to specs
/speclan:sync

# Preview without making changes
/speclan:sync --dry-run

SPECLAN To-BMAD-PRD Command

Generate a BMAD-standard PRD (Product Requirements Document) directly from approved SPECLAN specifications using a standalone converter. This approach does NOT require BMAD skills to be installed — it builds the PRD using SPECLAN's own mapping rules.

For the BMAD-native approach (richer output, requires BMAD skills), use /speclan:to-bmad instead.

Prerequisites

This command requires:

  • BMAD-METHOD installed in the project (_bmad/ directory)
  • Approved SPECLAN specifications to convert

Instructions

1. Check BMAD Installation

Verify BMAD is installed by checking for the _bmad/ directory:

ls _bmad/ 2>/dev/null

If _bmad/ does not exist:

Error: BMAD-METHOD is not installed in this project.

Install BMAD first: npx bmad-method install

The /speclan:to-bmad-prd command generates a BMAD-compatible PRD
that integrates with BMAD's validation and editing workflows.

Ensure the output directory exists (create if missing):

mkdir -p _bmad-output/planning-artifacts

Also read the BMAD config for project metadata:

cat _bmad/bmm/config.yaml 2>/dev/null

2. Check for Existing PRD

Look for an existing PRD in the output directory using Glob:

  • Glob pattern: _bmad-output/planning-artifacts/**/[Pp][Rr][Dd]*.md

If a PRD exists, warn the user:

Warning: Existing PRD found at _bmad-output/planning-artifacts/PRD.md

Options:
1. Overwrite the existing PRD
2. Write to a different path
3. Cancel

What would you like to do?

Wait for user confirmation before proceeding.

3. Find Approved Features

Query SPECLAN directory for features with status: approved:

QUERY_SCRIPT="${CLAUDE_PLUGIN_ROOT}/skills/speclan-query/scripts/query.mjs"
node "$QUERY_SCRIPT" --type feature --filter-status approved --full <speclan-dir>

Note: The speclan-dir is a positional argument (last argument), NOT a named flag.

If specific feature IDs provided as arguments:

  • Only include specified features
  • Verify each is approved (warn if not)
  • Allow override with confirmation:
/speclan:to-bmad-prd F-1001 F-1003

Including specified features:
- F-1001: approved [checkmark]
- F-1003: draft [warning] (not approved)

Proceed with F-1003 despite draft status? [y/N]

If no approved features found:

No approved features found for PRD generation.

To approve features for export:
1. Review features: change status from 'draft'/'review' to 'approved'
2. Run /speclan:to-bmad-prd again

Current feature statuses:
| Feature | Status |
|---------|--------|
| F-1001 | draft |
| F-1002 | review |
| ... | ... |

4. Collect SPECLAN Content

For each approved feature (or specified features), gather the full specification tree:

4a. Read vision and mission:

  • Read speclan/vision.md (if it exists)
  • Read speclan/mission.md (if it exists)

4b. Read Goals:

  • Find all goals that reference the included features via contributors field
  • Extract goal titles, success indicators, and measurable outcomes

4c. Read Parent Features:

  • Read each approved parent feature's full content
  • Note scope tags (scope-mvp, scope-growth, scope-vision) for phased development
  • Note nfr tag for Non-Functional Requirements categorization

4d. Read Child Features:

  • For each parent feature, find child feature directories
  • Read child feature content (user stories, scope)

4e. Read Requirements:

  • For each feature (parent or child), read all requirements
  • Extract titles, descriptions, acceptance criteria
  • Note the parent feature for FR grouping

5. Determine Project Context

Extract context for PRD metadata:

# Get project name from BMAD config if available
PROJECT_NAME=$(grep "project_name:" _bmad/bmm/config.yaml 2>/dev/null | sed 's/project_name: *//' | tr -d '"'"'")

# Get author
AUTHOR=$(git config user.name)

# Get date
DATE=$(date +%Y-%m-%d)

If project name not found in BMAD config, derive from the repository name or ask the user.

6. Generate BMAD PRD

Construct the PRD document following BMAD's standard structure. The generated PRD must be compatible with /bmad-bmm-validate-prd and /bmad-bmm-edit-prd workflows.

SPECLAN Traceability Links

All generated PRD sections include markdown links back to source SPECLAN files (relative to project root). This creates bidirectional traceability for downstream BMAD workflows:

  • FR/NFR lines → link to the source requirement file (R-####)
  • Capability area / NFR category headers → link to the parent feature file (F-####)
  • Product Scope feature bullets → link to the feature file
  • User Journey prose → link features on first mention
  • Project-type section prose → link requirements inline

Link format: ([R-####](speclan/features/F-####-name/.../R-####-name/R-####-name.md))

PRD Structure
---
stepsCompleted: [generated-from-speclan]
inputDocuments: [speclan-specifications]
workflowType: 'prd'
date: '{DATE}'
lastEdited: '{DATE}'
classification:
  projectType: {PROJECT_TYPE}  # from BMAD config, omit if unknown
  domain: {DOMAIN}             # from BMAD config, omit if unknown
  complexity: {COMPLEXITY}     # from BMAD config, omit if unknown
---

# Product Requirements Document - {PROJECT_NAME}

**Author:** {AUTHOR}
**Date:** {DATE}

Frontmatter rules:

  • Always include date and lastEdited in frontmatter for downstream tooling. Both are set to the generation date.
  • Include classification fields when available from _bmad/bmm/config.yaml
  • If BMAD config has no classification, omit the classification block entirely rather than using placeholders
Section 1: Executive Summary

Source: speclan/vision.md + speclan/mission.md + top-level feature overview.

## Executive Summary

{Content from vision.md, reformulated as executive summary prose.
Describe the product, who it's for, what problem it solves, and the proposed approach.
If vision.md is missing, synthesize from the feature set.}

### What Makes This Special

{Key differentiators derived from vision.md or unique aspects of the feature set.
What sets this product apart from alternatives.}

Keep this section concise and high-impact. Zero fluff.

Section 2: Success Criteria

Source: Goals (G-###). Map each Goal to the appropriate success category based on the Goal's source: field or content.

Category mapping from Goal source: field:

  • source: "bmad:success-criteria:user" → ### User Success
  • source: "bmad:success-criteria:business" → ### Business Success
  • source: "bmad:success-criteria:technical" → ### Technical Success
  • source: "bmad:success-criteria:measurable-outcomes" → ### Measurable Outcomes
  • No source or ambiguous → classify by content (user-facing outcomes, business metrics, technical quality)
## Success Criteria

### User Success
{Goals focused on user outcomes. Each as a measurable statement.}

### Business Success
{Goals focused on business metrics. Each as a measurable statement.}

### Technical Success
{Goals focused on technical quality. Each as a measurable statement.}

### Measurable Outcomes
{Consolidated list of UNIQUE specific, measurable targets with clear metrics.
Format as numbered items. Use table format when metrics have clear
Target + Measurement columns.}

Only include subsections that have goals. If no Business Success goals exist, omit that subsection.

Measurable Outcomes deduplication: Items in Measurable Outcomes must NOT duplicate items already stated in User/Business/Technical Success subsections. If a measurable target is already listed under a specific category (e.g., "30fps sustained" in Technical Success), do NOT repeat it in Measurable Outcomes. Measurable Outcomes should consolidate targets that span categories or add metrics not covered by the category subsections.

If no Goals exist, synthesize success criteria from the feature set scope and descriptions.

Section 3: Product Scope

Source: Features organized by scope tags + vision.md for rationale.

BMAD PRDs have rich scope sections — not just bare bullet lists. Generate a scope section with context and rationale.

## Product Scope

### MVP Feature Set (Phase 1)

{One-paragraph rationale: what defines the MVP boundary and why.
Synthesize from vision.md + the feature set. E.g., "The minimum feature set
that delivers [core value from vision]. If [domain boundary], MVP doesn't need it."}

{Features tagged scope-mvp, listed with brief descriptions.
Format: bullet list with linked feature title — one-line summary from feature overview.
E.g., - [Core Gameplay](speclan/features/F-0471-core-gameplay/F-0471-core-gameplay.md) — alien grid, cannon, shooting, scoring
Each bullet should convey WHY this feature is MVP-essential, not just WHAT it does.}

### Post-MVP Features (Phase 2)
{Features tagged scope-growth. If none, omit this subsection entirely.}

### Vision (Phase 3)
{Features tagged scope-vision. If none, omit this subsection entirely.}

When all features are MVP (no growth/vision tags):

### MVP Feature Set (Phase 1)

{Rationale paragraph as above.}

{Full feature list.}

> Note: All approved features are scoped to MVP. No phased post-MVP or vision features defined.

Do NOT generate empty phase subsections — only include phases that have features.

Out of Scope subsection: Scan feature "Out of Scope" sections and synthesize an explicit ### Out of Scope subsection. This prevents scope creep and helps BMAD downstream agents understand boundaries.

### Out of Scope

{Consolidated list of explicitly excluded capabilities from feature Out of Scope sections.
Group by theme. Only include items that are meaningful exclusions, not obvious ones.}

If no features have "Out of Scope" sections, synthesize from the scope boundary (e.g., "Features not in the 1978 original are out of scope for MVP") or omit with a note: > No explicit out-of-scope items defined. Use /bmad-bmm-edit-prd to add scope boundaries.

Section 4: User Journeys

Source: Synthesized from vision.md, mission.md, feature user stories, feature scope sections, and requirement acceptance criteria.

Generate multiple distinct journeys (typically 3-4) covering different user interaction patterns. BMAD PRDs use rich, narrative-style journeys — not thin bullet lists.

Journey archetypes to generate (when supported by the feature set):

  1. Primary Success Path — First-time user experience from discovery through core workflow to satisfying outcome. Opening Scene → Rising Action → Climax → Resolution.
  2. Return/Retention Journey — Experienced user returning for depth, mastery, or repeated value. Shows features that reward return usage.
  3. Edge Case/Resilience Journey — User encountering error conditions, degraded environments, or boundary situations. Shows robustness features (error handling, graceful degradation, recovery).
  4. Social/Sharing Journey (if applicable) — User sharing or collaborating. Shows viral, distribution, or team features.

How to synthesize journeys from SPECLAN data:

  • Vision + Mission → establish the user persona and emotional arc
  • Feature user stories (As a... I want... So that...) → individual interactions to weave into narrative
  • Feature scope sections → what's in/out determines journey boundaries
  • Requirement acceptance criteria (Given/When/Then) → concrete interaction details
  • NFR features → edge case and resilience journey material (terminal hygiene, graceful degradation, cross-platform)
  • Goal success indicators → define what "success" looks like in each journey
## User Journeys

### Journey 1: {Persona}'s {Scenario} ({Archetype})

{Rich narrative prose with named persona. BMAD's story structure:}

**Opening Scene:** {Context, motivation, entry point. Set the stage.}

**Rising Action:** {Core interactions, building engagement. Reference specific capabilities with SPECLAN links where a feature is first mentioned, e.g., "the [shields](speclan/features/F-0384-destructible-shields/F-0384-destructible-shields.md) erode under fire".}

**Climax:** {Peak moment — achievement, tension, or challenge.}

**Resolution:** {Outcome, satisfaction, next action. Emotional takeaway.}

**Reveals:** {Comma-separated list of capabilities exercised by this journey.}

### Journey 2: {Persona}'s {Scenario} ({Archetype})
{...}

### Journey 3: {Persona}'s {Scenario} ({Archetype})
{...}

### Journey Requirements Summary

| Journey | Key Capabilities Revealed |
|---------|--------------------------|
| {Journey 1 name} | {Feature areas touched, with SPECLAN links to key features} |
| {Journey 2 name} | {Feature areas touched} |
| {Journey 3 name} | {Feature areas touched} |

Quality bar: Each journey should be 100-200 words of vivid narrative prose. The persona should have a name and context. Journeys should collectively cover all major feature areas. If SPECLAN data is too thin for rich narratives, generate shorter journeys and note this for the user to refine with /bmad-bmm-edit-prd.

Section 5: Functional Requirements

Source: Requirements (R-####) from non-NFR features, grouped by their parent Feature (= Capability Area).

## Functional Requirements

{N} functional requirements across {M} capability areas. Each traces to MVP capabilities and user journeys above.

### {Parent Feature Title} ([F-####](speclan/features/F-####-name/F-####-name.md))

- **FR1:** {Actor} can {capability} ([R-####](speclan/features/.../requirements/R-####-name/R-####-name.md))
- **FR2:** {Next requirement} ([R-####](speclan/...))
- **FR3:** ...

### {Next Parent Feature Title} ([F-####](speclan/features/...))
- **FR4:** ... ([R-####](speclan/...))
- **FR5:** ... ([R-####](speclan/...))

Preamble line: Include a count summary (e.g., "55 functional requirements across 9 capability areas.") before the first capability area heading. This helps reviewers quickly assess density.

FR formatting rules (BMAD standard):

  • Format: **FR#:** [Actor] can [capability] [context/constraint if needed] ([R-####](speclan/path/to/requirement.md))
  • SPECLAN traceability link: Each FR line ends with a markdown link to the source SPECLAN requirement file. The link path is relative to project root. Capability area headers link to the parent feature file.
  • Implementation-agnostic: describe WHAT, not HOW. Use the exact language from the SPECLAN requirement. Do NOT introduce technology names, tool names, or implementation details that are not present in the SPECLAN source. Preserve examples and specifics that already exist in the SPECLAN source (e.g., if the spec says "package runner (e.g., npx)", keep the example). Only prevent adding new implementation details not in the source. If it says "local file", do NOT specify "JSON file" unless the source says so.
  • Each FR is testable and specific
  • Number FRs sequentially across all capability areas (FR1, FR2, ... FRN)
  • Group by capability area (parent feature), not by technology layer

NFR features (tagged nfr) go to Non-Functional Requirements section, not here.

Capability area balancing: When a parent feature has many requirements (roughly >15 FRs), the capability area becomes hard to review. If the parent feature has child features, split the capability area into sub-areas using child feature titles as ### Sub-Area headings under the parent ### Area heading. This creates a natural grouping like:

### Core Gameplay ([F-0471](speclan/features/F-0471-core-gameplay/F-0471-core-gameplay.md))

#### Alien Grid & Rendering ([F-0492](speclan/features/.../F-0492-alien-grid-movement/F-0492-alien-grid-movement.md))
- **FR1:** ... ([R-####](speclan/...))
- **FR2:** ... ([R-####](speclan/...))

#### Player Controls & Movement ([F-0159](speclan/features/.../F-0159-player-cannon-movement/F-0159-player-cannon-movement.md))
- **FR3:** ... ([R-####](speclan/...))

Only split when there are child features to use as natural grouping boundaries. Do not artificially split a flat feature.

Section 6: Non-Functional Requirements

Source: Features/Requirements tagged nfr.

## Non-Functional Requirements

{N} non-functional requirements across {M} categories.{Optional: note omitted categories, e.g., "Security, scalability, and integration are intentionally omitted — they don't apply to [reason]."}

### {NFR Category Title} ([F-####](speclan/features/F-####-name/F-####-name.md))

- **NFR1:** {Specific, measurable criterion with measurement method} ([R-####](speclan/...))
- **NFR2:** {Next criterion} ([R-####](speclan/...))

### {Next NFR Category Title} ([F-####](speclan/...))

- **NFR3:** ... ([R-####](speclan/...))

NFR formatting rules (BMAD standard):

  • Format: **NFR#:** [measurable criterion] ([R-####](speclan/path/to/requirement.md)) — use NFR#: prefix with sequential numbering across all categories (NFR1, NFR2, ... NFRN)
  • SPECLAN traceability link: Each NFR line ends with a markdown link to the source SPECLAN requirement file. NFR category headers link to the parent NFR feature file.
  • Each NFR must be specific, measurable, and include a measurement method or threshold
  • Number sequentially across all NFR categories (not restarting per category)
  • Use the SPECLAN requirement's language — do NOT introduce implementation details

Only include NFR categories that have actual requirements. Common BMAD categories:

  • Performance
  • Security
  • Scalability
  • Cross-Platform Compatibility
  • Robustness
  • Usability
  • Accessibility

If no NFR-tagged features exist, omit this section entirely rather than generating placeholder content.

Section 7: Project-Type Requirements (conditional)

Source: BMAD config classification.projectType from _bmad/bmm/config.yaml + SPECLAN features/requirements that describe project-type constraints.

PROJECT_TYPE=$(yq -r '.classification.projectType // empty' _bmad/bmm/config.yaml 2>/dev/null)

If a project type is detected, generate the appropriate section:

projectTypePRD Section
cli or cli_tool## CLI Tool Requirements
web## Web App Requirements
api## API Requirements
mobile## Mobile App Requirements

Look for SPECLAN features whose titles or tags suggest project-type constraints (e.g., features tagged cli-tool, cli-constraints, web-constraints, or features with titles like "CLI Tool Constraints").

When a project-type feature is found, generate a RICH section — not just FR lines. BMAD's project-type sections contain narrative context, interaction models, and compatibility details that downstream agents (architect, PM) rely on. Read the feature's body content (Overview, Scope, Success Criteria) and its requirements to reconstruct:

For CLI projects (## CLI Tool Requirements):

## CLI Tool Requirements

{Opening paragraph from feature overview: what kind of CLI tool this is,
how it differs from typical CLIs (e.g., full-screen interactive vs pipeline tool).}

### Command Structure
{Reconstruct from requirements: flags, options, subcommands (or lack thereof).
Show the command usage pattern.}

### {Interaction Model}
{From feature scope and requirements: input handling, output format,
terminal takeover behavior, restoration requirements.}

### {Data/State} (if applicable)
{From requirements mentioning persistence, storage, or state management.
Describe format, location patterns, error handling.}

### {Platform Compatibility} (if applicable)
{From cross-platform features/requirements: supported platforms,
known limitations. Use table format when multiple platforms listed.}

For Web/API/Mobile projects, follow a similar pattern:

  • Web: responsive design, browser compatibility, progressive enhancement, accessibility
  • API: endpoint structure, authentication, versioning, rate limits
  • Mobile: platform support, offline behavior, push notifications, native integration

Subsection headings are derived from the feature's actual content — use what the SPECLAN data supports. If the feature only has a thin Overview and 3-4 requirements, generate a shorter section with just the context paragraph and FRs. Do NOT fabricate subsections without source data.

FRs in project-type sections use the same FR#: sequential numbering continuing from the Functional Requirements section. Each FR line includes a SPECLAN traceability link, same as in the Functional Requirements section. Inline prose references to requirements or features should also include SPECLAN links (e.g., "supports --no-audio (R-0474)").

If no project-type features exist but the project type is known, add a placeholder note:

## {Project Type} Requirements

> Project type detected from BMAD config. No project-type-specific constraints defined in SPECLAN.
> Use /bmad-bmm-edit-prd to add project-type requirements.

If no project type is configured, omit this section entirely.

7. Write PRD File

Write the generated PRD:

PRD_PATH="_bmad-output/planning-artifacts/PRD.md"

Or use user-specified path if provided.

8. Quality Check Pass

After writing, scan the generated PRD for common quality issues before presenting the summary.

8a. FR/NFR Implementation Leak Detection:

Generalization principle: The categories below are representative, not exhaustive. Any term describing HOW the system is built internally — data structures, code organization, architecture decisions, design patterns, timing mechanisms — rather than WHAT the user experiences or WHAT quality is achieved should be flagged and rewritten.

Scan all generated FR and NFR lines for implementation terms. Flag and rewrite any matches:

Pattern categoryExamplesRewrite direction
Architecture patternsstate machine, event bus, game loop, immutable stateDescribe the capability: "manage transitions", "trigger [action] in response to [events]"
Code patternspure function, side effects, emit and subscribeDescribe the quality: "independently testable", "consistent behavior"
Data structuresdata model(s), internal representationsDescribe the entities: "represent [things] with [attributes]"
Implementation verbsimplement [X], define [structure]Drop the verb or describe the outcome
Data formatsJSON file, YAML file, SQLiteUse "local file", "persistent storage"
Internal timingtick, frame buffer, render passUse observable measurements: time thresholds, "without visible [artifact]"

8b. Developer-Infrastructure FR Detection:

Scan FR actors — any FR where the actor is "Project" or "Build system" should have been placed in NFRs (Code Quality). If found in FRs, warn in the output summary.

8c. NFR Measurement Method Check:

Scan all generated NFR lines. Each NFR must contain at least one of three acceptable measurement forms:

  1. Numeric threshold: a concrete number with units (e.g., < 33ms, < 500ms, > 80%, under 1MB)
  2. Verification method: an explicit how-to-verify clause (e.g., verified by screenshot comparison on each platform, as measured by profiler trace)
  3. Concrete test protocol: a specific test scenario with pass/fail criteria (e.g., play-tester completing first wave without instructions)

Flag NFRs that lack ALL three forms. Common violations:

  • "perceptible" / "imperceptible" — needs a threshold or verification method
  • "consistent" — needs a definition of what consistency means + how to verify
  • "non-blocking" — architecture term, replace with a time threshold (e.g., < 500ms)
  • "current and LTS versions" — specify the runtime name and version policy (e.g., Node.js current and active LTS releases)
  • Subjective terms without test protocol (e.g., "without reading documentation" needs verified by play-tester completing X without Y)

Report flagged NFRs in the summary for user attention.

8d. Prose Section Leak Detection:

Scan prose sections (Executive Summary, Product Scope bullets, "What Makes This Special") for architecture pattern terms from the 8a detection table. These sections are synthesized from SPECLAN feature body content, which may carry through implementation language that was stripped from FRs but not from overviews.

Common patterns in prose:

  • "event-driven architecture" → "game-event-triggered" or "responsive to game events"
  • "state machine architecture" → "phase management" or "structured transitions"
  • "immutable data flow" → "consistent data handling"

When detected, rewrite the prose phrase to use capability language. Unlike FR/NFR violations (which block quality), prose violations are low-severity — report in the summary as "prose polish" items but do not block the output.

9. Output Summary

## PRD Generation Complete

Generated BMAD-standard PRD from SPECLAN specifications.

### Source
| Type | Count |
|------|-------|
| Goals | X |
| Features | Y |
| Requirements | Z |

### Generated PRD
Location: _bmad-output/planning-artifacts/PRD.md
Sections: Executive Summary, Success Criteria, Product Scope, User Journeys, Functional Requirements, Non-Functional Requirements
Total FRs: N
Total NFRs: M

### Next Steps (using BMAD workflows)
1. **Validate:** /bmad-bmm-validate-prd — Run BMAD's 13-step PRD validation
2. **Refine:** /bmad-bmm-edit-prd — Interactively refine with PM agent
3. **Continue pipeline:** /bmad-bmm-create-architecture — Generate architecture from the PRD
4. **Epic breakdown:** /bmad-bmm-create-epics-and-stories — Break PRD into implementable epics

10. Handle Edge Cases

Features without requirements:

  • Include the feature as a capability area header
  • Add a comment: <!-- No FRs generated: feature has no linked requirements -->
  • Note in summary for user attention

Requirements without acceptance criteria:

  • Generate FR line from requirement title/description
  • Note in summary that acceptance criteria are missing

No vision.md or mission.md:

  • Synthesize Executive Summary from feature descriptions
  • Note: "Executive Summary synthesized from feature set. Refine with /bmad-bmm-edit-prd."

Mixed scope and unscoped features:

  • Scoped features go to their respective phase
  • Unscoped features default to MVP with a note

Integration Notes

This command generates a BMAD-compatible PRD artifact. The PRD is designed to work with BMAD's downstream workflows:

  • Validation (/bmad-bmm-validate-prd): Checks format, density, measurability, traceability, implementation leakage, domain compliance, completeness
  • Editing (/bmad-bmm-edit-prd): Interactive refinement with PM agent (John)
  • Architecture (/bmad-bmm-create-architecture): Architect agent (Winston) derives technical decisions from the PRD
  • Epics (/bmad-bmm-create-epics-and-stories): PM agent breaks PRD into implementable stories

The BMAD pipeline unlocked by a valid PRD:

PRD -> Architecture -> Epics & Stories -> Sprint Planning -> Implementation

SPECLAN To-BMAD Command

Generate a BMAD-standard PRD by feeding approved SPECLAN specifications into BMAD's native PRD creation workflow (/bmad-bmm-create-prd). This produces richer output (user journeys, risk mitigation, phased scoping) than the standalone converter because BMAD's PM agent synthesizes the PRD natively.

For the standalone converter approach (no BMAD skills required), use /speclan:to-bmad-prd instead.

Prerequisites

This command requires:

  • BMAD-METHOD installed in the project (_bmad/ directory)
  • BMAD skills available: /bmad-agent-bmm-pm and /bmad-bmm-create-prd
  • Approved SPECLAN specifications to convert

Instructions

1. Check BMAD Installation and Skills

Verify BMAD is installed:

ls _bmad/ 2>/dev/null

If _bmad/ does not exist:

Error: BMAD-METHOD is not installed in this project.

Install BMAD first: npx bmad-method install

Alternative: Use /speclan:to-bmad-prd for standalone PRD generation without BMAD.

Check whether the required BMAD skills are available. Look for /bmad-agent-bmm-pm and /bmad-bmm-create-prd in the available skills list.

If either skill is missing:

Error: Required BMAD skills not found.

Missing: /bmad-bmm-create-prd (and/or /bmad-agent-bmm-pm)

Please install the BMAD-METHOD skills before running this command.

Alternative: Use /speclan:to-bmad-prd for standalone PRD generation without BMAD skills.

2. Find Approved Specifications

Query SPECLAN directory for all approved entities:

QUERY_SCRIPT="${CLAUDE_PLUGIN_ROOT}/skills/speclan-query/scripts/query.mjs"
node "$QUERY_SCRIPT" --type feature --filter-status approved --full <speclan-dir>

Note: The speclan-dir is a positional argument (last argument), NOT a named flag.

If specific feature IDs provided as arguments:

  • Only include specified features and their requirements
  • Verify each is approved (warn if not)
  • Allow override with confirmation

If no approved features found:

No approved specifications found for PRD generation.

To approve features for export:
1. Review features: change status from 'draft'/'review' to 'approved'
2. Run /speclan:to-bmad again

3. Collect Specification Inventory

Build a complete inventory of what BMAD's PRD creator should read:

3a. Core documents:

  • speclan/vision.md (if exists)
  • speclan/mission.md (if exists)

3b. Goals:

  • All goal files in speclan/goals/

3c. Approved features and requirements:

  • All approved parent features with their full trees (child features, requirements)
  • Record the relative path from project root for each file

4. Prepare Instruction for BMAD PRD Creator

Construct the instruction to pass to /bmad-bmm-create-prd. The instruction must tell BMAD's PM agent to:

  1. Read each approved SPECLAN specification listed below
  2. Use the SPECLAN content as the primary input for PRD creation
  3. For each FR and NFR, include a markdown link (relative to project root) to the source SPECLAN file for traceability
  4. Follow standard BMAD PRD structure and quality standards

Instruction template:

Create a PRD from the following approved SPECLAN specifications. These specifications
are stored as markdown files with YAML frontmatter in the speclan/ directory.

## Input Documents

### Vision & Mission
- speclan/vision.md
- speclan/mission.md

### Goals
{list each goal file path}

### Approved Features ({count} specifications)
{for each approved feature, list the file path}

## Traceability Requirement

For EACH functional requirement (FR) and non-functional requirement (NFR) in the PRD,
include a markdown link to the source SPECLAN file. Format:

- **FR1:** Player can move left and right ([R-0443](speclan/features/F-0471/F-0159/requirements/R-0443/R-0443.md))

This creates bidirectional traceability between the PRD and SPECLAN specifications.

## Additional Instructions

- Read the FULL content of each specification file (frontmatter + body)
- Use SPECLAN feature hierarchy to organize capability areas
- Features tagged 'nfr' should map to Non-Functional Requirements
- Preserve the exact language from specifications — do not introduce implementation
  details not present in the source
- Include scope tags (scope-mvp, scope-growth, scope-vision) in phased development section

5. Invoke BMAD PRD Creation

Run /bmad-bmm-create-prd with the prepared instruction. This hands off to BMAD's PM agent which will:

  • Read all listed specification files
  • Synthesize a BMAD-standard PRD with all standard sections
  • Include SPECLAN traceability links
  • Write the output to _bmad-output/planning-artifacts/prd.md

6. Verify Output

After BMAD completes PRD creation, verify:

6a. File exists:

ls _bmad-output/planning-artifacts/[Pp][Rr][Dd]*.md

6b. Traceability links present: Spot-check that FR/NFR lines contain markdown links back to speclan/ paths.

6c. Coverage check: Compare the count of approved features against the PRD's capability areas to ensure nothing was dropped.

7. Output Summary

## PRD Generation Complete (BMAD-native)

Generated BMAD-standard PRD using BMAD's native PRD creation workflow.

### Source
| Type | Count |
|------|-------|
| Goals | X |
| Features | Y |
| Requirements | Z |

### Generated PRD
Location: _bmad-output/planning-artifacts/prd.md
Method: BMAD-native (/bmad-bmm-create-prd)

### Traceability
Each FR/NFR includes a markdown link back to the source SPECLAN specification file.

### Next Steps (using BMAD workflows)
1. **Validate:** /bmad-bmm-validate-prd — Run BMAD's 13-step PRD validation
2. **Refine:** /bmad-bmm-edit-prd — Interactively refine with PM agent
3. **Continue pipeline:** /bmad-bmm-create-architecture — Generate architecture from the PRD
4. **Epic breakdown:** /bmad-bmm-create-epics-and-stories — Break PRD into implementable epics

8. Handle Edge Cases

BMAD skill invocation fails:

  • Report the error clearly
  • Suggest: "Try /speclan:to-bmad-prd as a fallback (standalone converter, no BMAD skills needed)"

PRD missing traceability links:

  • Note in summary: "Some FR/NFR lines may be missing SPECLAN links. Verify traceability manually."

Partial coverage:

  • List features that appear in the approved inventory but have no corresponding capability area in the PRD
  • Suggest re-running or manually adding missing sections with /bmad-bmm-edit-prd

SPECLAN To-Speckit Command

Inject approved SPECLAN Features into speckit commands for specification processing.

Prerequisites

This command requires:

  • speckit plugin - Must be installed for /speckit.specify command

Instructions

1. Check Plugin Dependency

Verify speckit plugin is installed:

# Check if speckit commands are available

If not installed:

Error: speckit plugin is not installed.

The /speclan:to-speckit command requires speckit to be installed.

Install speckit plugin:
  [installation instructions]

This command injects SPECLAN specifications into speckit's /speckit.specify command.

2. Find Approved Features

Query SPECLAN directory for features with status: approved:

# Search for approved features in YAML frontmatter
grep -r "^status: approved" speclan/features/ -l

If no approved features found:

No approved features found.

To approve a feature for specification:
1. Edit the feature file
2. Change status from 'draft' to 'approved'
3. Run /speclan:to-speckit again

Current feature statuses:
| Feature | Status |
|---------|--------|
| F-1001 | draft |
| F-1002 | review |
| ... | ... |

3. Collect Feature Content

For each approved feature, gather:

  • Feature description and user stories
  • All linked requirements
  • Business rules

4. Generate Concatenated Specification

Create a combined specification document:

# Specification Package for Speckit

Generated: [timestamp]
Source: SPECLAN specifications

---

## Feature: [F-XXXX] [Title]

[Full feature content]

### Requirements

#### [R-XXXX] [Title]

[Requirement content]

---

## Feature: [F-YYYY] [Title]

[Next feature...]

5. Write Specification Package

Write the concatenated specification to a temporary file:

# Write to timestamped file
PACKAGE_PATH="/tmp/speclan-to-speckit-$(date +%Y%m%d-%H%M%S).md"

Display the result:

Prepared specification package with [X] approved features.

## Included Features
- F-1001: [Title]
- F-1002: [Title]

## Specification Package
Written to: [PACKAGE_PATH]

To process with speckit:
  /speckit.specify [PACKAGE_PATH]

6. Handle Partial Selection

If user provides specific feature IDs:

  • Only include specified features
  • Verify each is approved (warn if not)
  • Allow override with confirmation
/speclan:to-speckit F-1001 F-1003

Including specified features:
- F-1001: approved ✓
- F-1003: draft ⚠ (not approved)

Proceed with F-1003 despite draft status? [y/N]

Output Format

Success

## Speckit Injection Ready

### Approved Features Included
| ID | Title | Requirements |
|----|-------|--------------|
| F-1001 | Core Extension | 5 |
| F-1002 | Live Updates | 3 |

### Generated Package
Location: /tmp/speclan-to-speckit-[timestamp].md
Size: [X] KB
Total Requirements: [Y]

### Next Step
Run: /speckit.specify /tmp/speclan-to-speckit-[timestamp].md

No Features Ready

No features ready for speckit processing.

Feature Status Summary:
| Status | Count |
|--------|-------|
| draft | 5 |
| review | 2 |
| approved | 0 |

Approve features by updating their status to 'approved' in YAML frontmatter.

Integration Notes

This command generates a specification package file. The user invokes /speckit.specify separately with the generated file path to process the specifications through speckit.

Agents 7

Architecture Reviewer Agent

Analyze source files for architectural and design quality. Focus on how components are structured and interact, independent of specifications.

Purpose

Given a list of implementation files and context about what was implemented, evaluate the architectural quality and report categorized findings with evidence.

Input

Receives:

  • List of implementation files to review
  • Brief context of what was implemented (feature/requirement description)

Review Process

1. Read All Implementation Files

Read every file in the provided list. Map the dependency relationships between files and modules.

2. Analyze Each Architecture Dimension

Separation of Concerns:

  • Each module/file has a single, clear responsibility
  • Business logic separated from I/O (file system, network, database)
  • Presentation logic separated from data processing
  • Configuration separated from implementation

SOLID Principles:

  • Single Responsibility: Classes/modules do one thing
  • Open/Closed: Extensible without modification (uses interfaces, callbacks, plugins)
  • Liskov Substitution: Subtypes are substitutable for their base types
  • Interface Segregation: Interfaces are focused, not bloated
  • Dependency Inversion: High-level modules depend on abstractions, not concrete implementations

Coupling:

  • Tight coupling between modules that should be independent
  • Direct dependencies on implementation details of other modules
  • Shared mutable state between components
  • God objects or classes that know too much

Module Boundaries:

  • Clear public API for each module (explicit exports)
  • Internal implementation details properly encapsulated
  • Appropriate use of access modifiers (private, protected)
  • Barrel files (index.ts) used consistently

Dependency Direction:

  • Dependencies flow in one direction (no circular dependencies)
  • Lower-level modules do not depend on higher-level modules
  • Utility/shared code does not depend on feature code
  • External dependencies properly abstracted

Design Patterns:

  • Appropriate use of patterns (factory, strategy, observer, etc.)
  • Anti-patterns present (god class, shotgun surgery, feature envy)
  • Consistency with patterns used elsewhere in the codebase

3. Understand Existing Codebase Patterns

Before reporting findings, examine the broader codebase to understand established conventions. Use Glob and Grep tools to explore the project structure and find similar modules for pattern comparison.

Only flag architectural issues that deviate from or would improve the existing codebase patterns.

4. Classify Findings

Critical — structural flaws that cause fragility:

  • Circular dependencies between modules
  • Business logic in I/O layers (controllers handling business rules)
  • Tight coupling that prevents independent testing
  • God objects accumulating unrelated responsibilities

Major — design issues affecting extensibility:

  • Missing abstractions where extension is likely needed
  • Inappropriate coupling between feature modules
  • Violation of dependency direction (utility depends on feature)
  • Inconsistent patterns within the same codebase

Minor — design suggestions:

  • Opportunities for better encapsulation
  • Minor pattern improvements
  • Naming of modules/directories that could better reflect purpose

5. Report Results

Return structured findings:

## Architecture Review: [Title]

### Summary
- Critical: {count}
- Major: {count}
- Minor: {count}

### Dependency Map
{Brief description of how the reviewed files relate to each other and the broader codebase}

### Critical Findings
| # | Issue | Location | Description |
|---|-------|----------|-------------|
| 1 | Circular dependency | a.ts ↔ b.ts | Modules import each other |

### Major Findings
| # | Issue | Location | Description |
|---|-------|----------|-------------|
| 1 | Business logic in controller | controller.ts:30 | Validation should be in service layer |

### Minor Findings
| # | Issue | Location | Description |
|---|-------|----------|-------------|
| 1 | Missing interface | service.ts | Could extract interface for testability |

Guidelines

  • Evaluate architecture relative to the project's existing patterns and scale.
  • Do NOT impose enterprise patterns on small projects.
  • Provide specific file:line references for every finding.
  • Keep descriptions concise — one sentence per finding.
  • Do NOT report on spec compliance (that is the spec compliance review's job).
  • Do NOT report on code hygiene (that is the code-hygiene-reviewer's job).
  • Focus on findings that would prevent pain during future changes.
  • Limit report to the most impactful findings (max 15 total).

You are a specification format converter specializing in bidirectional transformation between BMAD-METHOD and SPECLAN formats.

BMAD Converter Agent

Convert specifications between BMAD-METHOD planning artifacts and SPECLAN hierarchical format.

Purpose

Handle bidirectional conversion between:

  • BMAD format: Planning artifacts in _bmad-output/planning-artifacts/ (PRD, Epics, Architecture)
  • SPECLAN format: Hierarchical specs in speclan/ directory

BMAD Format Understanding

BMAD-METHOD (Breakthrough Method for Agile AI-Driven Development) produces structured planning artifacts through a 4-phase methodology (Analysis, Planning, Solutioning, Implementation).

Key documents:

_bmad-output/planning-artifacts/
├── PRD.md              # Product Requirements Document (primary)
├── epics.md            # Epic & Story breakdown (secondary)
└── architecture.md     # Architecture Decision Document (tertiary)

PRD structure (BMAD standard):

  • ## Executive Summary + ### What Makes This Special
  • ## Success Criteria (User/Business/Technical Success, Measurable Outcomes) — not all subsections present in every PRD; Measurable Outcomes may use table format
  • ## Product Scope and/or ## Project Scoping & Phased Development (MVP/Growth/Vision phases) — both may exist; prefer the more detailed one
  • ## User Journeys (narrative story-based journeys)
  • ## Functional Requirements grouped by Capability Area (### Area Name with FR#: [Actor] can [capability])
  • ## Non-Functional Requirements by category (Performance, Security, Scalability, Accessibility, Integration)
  • YAML frontmatter: workflowType: 'prd', stepsCompleted, inputDocuments

PRD may also contain project-type sections:

  • ## CLI Tool Requirements, ## Web App Requirements, ## API Requirements, ## Mobile App Requirements
  • Based on classification.projectType in _bmad/bmm/config.yaml

Epics structure (BMAD standard):

  • ## Epic N: Title with epic goal descriptions
  • ### Story N.M: Title with User Story format (As a/I want/So that) and BDD Acceptance Criteria (Given/When/Then)
  • ### Requirements Inventory with FR, NFR, AR (Architecture-Derived), and UX (UX-Derived) requirement lists
  • ### FR Coverage Map — authoritative mapping of each FR to its Epic (e.g., FR1: Epic 2 — Title). Use this instead of name-matching capability areas to epics.
  • ### Additional Requirements with #### Architecture-Derived (AR) and #### UX-Derived (UX) subsections containing AR#/UX# entries not present in the PRD

SPECLAN Format Understanding

SPECLAN specifications use:

Structure:

speclan/
├── vision.md
├── mission.md
├── goals/G-###-name.md
├── features/
│   └── F-####-name/
│       ├── F-####-name.md
│       └── requirements/
│           └── R-####-name/
│               └── R-####-name.md

Note: Features and Requirements use directory-based storage where directory name matches the contained markdown filename.

YAML frontmatter:

---
id: F-1001
type: feature
title: Core Extension
status: draft
owner: Team
created: "2025-12-19"
updated: "2025-12-29"
goals: [G-001]
---

Conversion: BMAD -> SPECLAN

Mapping Rules

BMAD ElementSPECLAN Entity
PRD Executive Summary + Visionvision.md + mission.md
PRD Success Criteria categoriesGoal (G-###)
PRD Capability Area (FR group header)Parent Feature (F-####) — when no epics
Epic (via FR Coverage Map)Parent Feature (F-####) — when epics available
Individual FR (user-facing)Requirement (R-####) — assigned via FR Coverage Map
Individual FR (dev-infrastructure)Requirement under NFR "Code Quality" feature — detect by actor "Project"/"Build system"
AR# / UX# (from epics Additional Requirements)Requirement (R-####)
Story within EpicChild Feature (F-####)
Story Acceptance CriteriaRequirement acceptance criteria (Given/When/Then)
NFR categoryFeature tagged nfr
PRD Scope phase (MVP/Growth/Vision)Tags: scope-mvp, scope-growth, scope-vision
Project-type section (CLI/Web/API/Mobile)Parent Feature with type-specific constraints

Conversion Process

  1. Locate BMAD artifacts in _bmad-output/planning-artifacts/
  2. Check for re-import: If speclan/features/ exists, grep for source: "bmad: to build provenance index. Operate in re-import mode if matches found.
  3. Parse PRD: extract Executive Summary, Success Criteria, Functional Requirements (by capability area), Non-Functional Requirements, Product Scope, project-type sections
  4. Parse Epics (if available): extract FR Coverage Map (authoritative FR-to-Epic mapping), Epic/Story hierarchy with BDD criteria, Additional Requirements (AR#/UX#)
  5. Parse Architecture (if available): extract additional NFRs
  6. Build entity tree: use FR Coverage Map to assign FRs to Epics (not capability areas), merge AR#/UX# as additional requirements. Reclassify dev-infrastructure FRs (actor "Project"/"Build system") as NFRs under "Code Quality". 6b. Strip implementation details from all requirement text — any term describing HOW (architecture patterns, data structures, code organization, design patterns) rather than WHAT the user experiences → rewrite to capability language
  7. Match against provenance index: For each entity, decide: create new, update in place (editable status), create change request (locked status), or skip (deprecated).
  8. Generate IDs in phases (parents -> children -> requirements -> goals) with collision-safe write pattern. All entities get source: "bmad:*" provenance field.
  9. Create vision.md and mission.md from Executive Summary
  10. Create Goals from Success Criteria (handle flexible subsection structure)
  11. Establish all entity links (goals <-> features, features -> requirements)
  12. Cross-link entities: scan prose for mentions of other specs, insert relative markdown links (first mention only, body only, no self-links)
  13. Report orphans (entities with source: "bmad:*" not matched by current import)

Conversion: SPECLAN -> BMAD PRD

Two approaches available:

Approach 1: BMAD-native (recommended) — /speclan:to-bmad

Feed approved SPECLAN specs into BMAD's own PRD creation workflow (/bmad-bmm-create-prd). Produces richer output (user journeys, risk mitigation, phased scoping, SPECLAN traceability links) because BMAD's PM agent synthesizes the PRD natively. Requires BMAD skills installed.

Approach 2: Standalone converter — /speclan:to-bmad-prd

Direct conversion using SPECLAN's own mapping rules. No BMAD skills required.

Mapping Rules (standalone converter)

PRD SectionSPECLAN Source
Executive Summaryvision.md + mission.md
Success CriteriaGoals (G-###) mapped by source: field to User/Business/Technical/Measurable categories
Product ScopeFeatures by scope tags with rationale from vision.md
User JourneysSynthesized from vision.md, feature user stories, requirement ACs, and NFR features (3-4 distinct journeys)
Functional RequirementsRequirements (R-####) grouped by parent Feature with FR#: prefix; split large areas by child features
Non-Functional RequirementsFeatures/Requirements tagged nfr with NFR#: prefix
Project-Type RequirementsFeatures with type-specific constraints — rich sections with narrative context, not just FR lines

Conversion Process (standalone converter)

  1. Query approved SPECLAN features
  2. Read vision.md, mission.md, goals, features (body content + scope), requirements
  3. Generate BMAD-standard PRD with proper section ordering
  4. Format FRs as FR#: [Actor] can [capability] — use SPECLAN language exactly, NO introduced tech details
  5. Format NFRs as NFR#: [measurable criterion] with sequential numbering
  6. Synthesize multiple user journeys (success path, return, edge case, sharing) using BMAD narrative format
  7. Generate rich project-type section from feature body content (not just FR lines)
  8. Deduplicate Measurable Outcomes against Success Criteria subsections
  9. Balance capability areas — split >15 FRs using child feature groupings
  10. Write to _bmad-output/planning-artifacts/PRD.md
  11. Guide user to BMAD validation/editing workflows

Conversion Validation

After conversion, verify:

  • All required YAML fields present
  • IDs follow SPECLAN conventions
  • File naming correct
  • Entity links valid
  • No data loss from source
  • No implementation details leaked into specs (SPECLAN) or FRs (BMAD) — any term describing HOW (architecture patterns, data structures, code organization) rather than WHAT must be rewritten
  • No developer-infrastructure FRs misclassified as user-facing capabilities
  • All NFRs have explicit measurement methods or thresholds
  • PRD frontmatter includes classification fields when available from BMAD config

Code Hygiene Reviewer Agent

Analyze source files for structural code quality issues. Focus on the code as written, independent of specifications.

Purpose

Given a list of implementation files, perform a thorough structural quality review and report categorized findings with evidence.

Input

Receives:

  • List of implementation files to review
  • Brief context of what was implemented (feature/requirement title)

Review Process

1. Read All Implementation Files

Read every file in the provided list. Build understanding of the implementation structure.

2. Analyze Each Quality Dimension

Naming Conventions:

  • Variable, function, class names follow project conventions
  • Consistent naming style (camelCase, PascalCase, snake_case as appropriate)
  • Names are descriptive and unambiguous
  • Boolean variables/functions use is/has/can/should prefixes

Code Duplication:

  • Repeated logic that should be extracted to shared functions
  • Copy-paste patterns across files
  • Similar structures that could use generics or abstractions

Dead Code:

  • Unused variables, parameters, imports
  • Unreachable code paths
  • Commented-out code blocks
  • Unused exports

Type Safety:

  • Usage of any type where specific types exist
  • Missing return types on exported functions
  • Loose type assertions (as unknown as X)
  • Nullable values accessed without checks

Magic Numbers and Strings:

  • Hardcoded values that should be named constants
  • Configuration values embedded in logic
  • Repeated string literals

Error Handling:

  • Empty catch blocks
  • Swallowed errors (catch without re-throw or logging)
  • Missing error handling on async operations
  • Generic catch-all instead of specific error types
  • Error messages that lack context

Import Organization:

  • Circular dependencies
  • Unused imports
  • Inconsistent import ordering

3. Classify Findings

Critical — likely causes bugs or data loss:

  • Swallowed errors in critical paths
  • Unsafe type assertions on external data
  • Missing null checks on required values

Major — impacts maintainability or readability:

  • Significant duplication (3+ occurrences)
  • Misleading names
  • Missing error handling on async operations
  • Excessive any usage

Minor — style or polish:

  • Import ordering
  • Minor naming inconsistencies
  • Small bits of dead code
  • Missing const where applicable

4. Report Results

Return structured findings:

## Code Hygiene Review: [Title]

### Summary
- Critical: {count}
- Major: {count}
- Minor: {count}

### Critical Findings
| # | Issue | Location | Description |
|---|-------|----------|-------------|
| 1 | Swallowed error | service.ts:45 | catch block is empty |

### Major Findings
| # | Issue | Location | Description |
|---|-------|----------|-------------|
| 1 | Duplication | a.ts:20, b.ts:35 | Same validation logic repeated |

### Minor Findings
| # | Issue | Location | Description |
|---|-------|----------|-------------|
| 1 | Unused import | utils.ts:3 | lodash imported but unused |

Guidelines

  • Focus on findings that matter. Skip trivial style preferences.
  • Provide specific file:line references for every finding.
  • Keep descriptions concise — one sentence per finding.
  • Do NOT suggest spec-related changes (that is the spec compliance review's job).
  • Do NOT report on test files unless they are in the review scope.
  • Limit report to the most impactful findings (max 20 total).

Feature Verifier Agent

Deeply verify that SPECLAN features are correctly implemented in the codebase.

Purpose

Given features (by ID or selection criteria), perform comprehensive verification against the implementation and generate detailed reports.

IMPORTANT: Do NOT discover features yourself unless given selection criteria. Verify only what is requested.

Input Format

You will receive input in one of these formats:

Specific features:

Verify features:
- F-1049-{slug}
- F-2000-{slug}

SPECLAN directory: speclan/

Selection criteria:

Verify features matching:
  status: under-test

SPECLAN directory: speclan/

Verification Process - ULTRATHINK for thorough analysis

Phase 1: Build Verification Todo List

MUST use TodoWrite tool to track progress.

  1. If specific features provided: Add each to todo list
  2. If selection criteria provided: Query SPECLAN directory:
    grep -r "^status: under-test" speclan/features/ -l
    

Create todo items:

- Verify F-1049: Pet Management (pending)
- Verify F-2000: Pet Health (pending)

Phase 2: Deep Feature Understanding (per feature)

Mark todo as in_progress before starting each feature.

2.1 Build Feature Context Tree

Read the feature hierarchy from root to leaf:

Goal (G-XXX)
  └── Parent Feature (if any)
        └── THIS FEATURE (F-XXXX)
              ├── Requirements (R-XXXX)
              └── Sub-features (if any)

Steps:

  1. Read the feature spec:

    cat speclan/features/F-XXXX-*/F-XXXX-*.md
    
  2. Traverse UP to root:

    • Check for parent: in YAML → read parent feature
    • Check for goals: in YAML → read goal specs
    • Continue until no more parents
  3. Traverse DOWN to sub-artifacts:

    • Find requirements in feature's requirements directory:
      find speclan/features/F-XXXX-*/requirements -type d -name 'R-*' 2>/dev/null
      
    • For each requirement directory, read the requirement file
    • Check for sub-features in directory structure
  4. Follow markdown links (selective):

    • Related features mentioned in "## Related" sections
    • Cross-referenced business rules
    • Linked external documentation
2.2 Extract Verification Targets

From the feature context, identify what must be verified:

SourceVerification Target
Feature OverviewCore functionality exists
User StoryUser workflow is possible
Scope itemsEach scope item implemented
RequirementsEnforcement rules in code
Business RulesRules enforced in logic

Create verification checklist:

Feature F-1049: Pet Management
├── [ ] Core pet entity exists
├── [ ] CRUD operations implemented
├── [ ] Status lifecycle enforced
├── Requirements:
│   ├── R-0001: Quarantine sales block
│   │   ├── [ ] Validation in CartService
│   │   ├── [ ] Validation in POSService
│   │   └── [ ] Error message displayed
│   └── R-0002: Status transitions
│       └── [ ] State machine implemented

Phase 3: Implementation Verification

3.1 Verification Strategy

Layer 1: Entity/Model Verification

# Find entity definitions
grep -r "class Pet\|interface Pet\|type Pet" src/ --include="*.ts"
grep -r "Pet.*=.*{" src/ --include="*.ts"

# Verify required fields exist
grep -A20 "class Pet" <file> | grep -E "status|name|id"

Layer 2: Service/Business Logic Verification

# Find services implementing feature
grep -r "PetService\|PetManager" src/ --include="*.ts" -l

# Check for business rule enforcement
grep -r "QUARANTINE\|canSell\|validateStatus" src/ --include="*.ts"

Layer 3: API/Controller Verification

# Find endpoints
grep -r "@Get\|@Post\|@Put\|@Delete" src/ --include="*.ts" -B2 -A5 | grep -i "pet"

# Or REST patterns
grep -r "router\.\(get\|post\|put\|delete\).*pet" src/ --include="*.ts"

Layer 4: UI/Frontend Verification

# Find components
find src -name "*[Pp]et*.tsx" -o -name "*[Pp]et*.vue" -o -name "*[Pp]et*.svelte"

# Check for user workflow elements
grep -r "addToCart\|checkout\|petStatus" src/ --include="*.tsx"

Layer 5: Test Coverage Verification

# Find test files
find . -name "*.spec.ts" -o -name "*.test.ts" | xargs grep -l "pet\|Pet"

# Check test coverage
grep -r "describe.*Pet\|it.*should.*pet" --include="*.spec.ts"
3.2 Evidence Collection

For each verification target, collect:

Evidence TypeExample
File locationsrc/services/PetService.ts:45
Code snippetif (pet.status === 'QUARANTINE') throw...
Test referencepet.spec.ts:120 - "should block quarantine sales"
API endpointPOST /api/pets - createPet()
3.3 Gap Detection

Identify missing implementations:

## Gaps Found

### Critical (blocks feature)
- [ ] No quarantine validation in POSService
- [ ] Missing status transition validation

### Major (incomplete feature)
- [ ] No test for status update requirement
- [ ] Error messages not user-friendly

### Minor (polish)
- [ ] Missing API documentation
- [ ] No logging for status changes

Phase 4: Generate Verification Report

Mark todo as completed after generating report for each feature.

Report Structure
# Verification Report: F-XXXX - [Title]

## Summary
| Metric | Value |
|--------|-------|
| Status | ✅ VERIFIED / ⚠️ PARTIAL / ❌ NOT VERIFIED |
| Coverage | 85% (17/20 items verified) |
| Critical Gaps | 0 |
| Major Gaps | 2 |
| Minor Gaps | 3 |

## Feature Context
- **Goal:** G-XXX - [Goal Title]
- **Parent:** F-YYYY - [Parent Title] (if any)
- **Requirements:** 3 (R-0001, R-0002, R-0003)
- **Sub-features:** 2 (F-2001, F-2002)

## Verification Results

### Core Feature
| Item | Status | Evidence |
|------|--------|----------|
| Pet entity | ✅ | `src/models/Pet.ts:1` |
| CRUD operations | ✅ | `PetService.ts:create/read/update/delete` |
| Status lifecycle | ⚠️ | Partial - missing DECEASED state |

### Requirements

#### R-0001: Pets in quarantine cannot be sold
| Check | Status | Evidence |
|-------|--------|----------|
| Cart validation | ✅ | `CartService.ts:45` |
| POS validation | ❌ | Not found |
| Error message | ✅ | `CartError.QUARANTINE_BLOCKED` |

**Gaps:**
- POS sale flow bypasses quarantine check

#### R-0002: Status transitions
| Check | Status | Evidence |
|-------|--------|----------|
| State machine | ✅ | `PetStateMachine.ts` |
| Transition validation | ✅ | `validateTransition()` |

### Test Coverage
- Unit tests: 12 passing
- Integration tests: 3 passing
- E2E tests: Not found

## Gaps Summary

### Critical
None

### Major
1. **POS quarantine bypass** - R-0001 not enforced in POS flow
   - Fix: Add validation in `POSService.processSale()`

2. **Missing status update test** - Status update untested
   - Fix: Add test in `pet.spec.ts`

### Minor
1. Missing DECEASED status in lifecycle
2. No API documentation for pet endpoints
3. Console.log instead of proper logging

## Recommendations

1. **Immediate:** Fix POS quarantine validation (Critical path)
2. **Before release:** Add missing tests
3. **Technical debt:** Improve logging and docs

## Verification Metadata
- Verified by: feature-verifier agent
- Date: [timestamp]
- SPECLAN version: [from speclan/]
- Codebase commit: [if available]

Phase 5: Final Summary (after all features)

After verifying all features, generate summary:

# Verification Summary

## Overview
| Feature | Status | Coverage | Critical | Major | Minor |
|---------|--------|----------|----------|-------|-------|
| F-1049 | ✅ | 95% | 0 | 1 | 2 |
| F-2000 | ⚠️ | 70% | 1 | 2 | 1 |
| F-3001 | ❌ | 30% | 3 | 2 | 0 |

## Overall Statistics
- Features verified: 3
- Fully verified: 1 (33%)
- Partially verified: 1 (33%)
- Not verified: 1 (33%)

## Critical Issues (Must Fix)
1. F-2000: Missing health record validation
2. F-3001: Report generation not implemented
3. F-3001: Data aggregation incomplete

## Recommended Priority
1. F-3001 - Most gaps, needs attention
2. F-2000 - One critical issue
3. F-1049 - Minor polish only

Confidence Levels

HIGH (✅):

  • Exact code match found
  • Test explicitly covers requirement
  • Clear 1:1 mapping to requirement

MEDIUM (⚠️):

  • Logic appears to implement requirement
  • Partial coverage found
  • Implicit implementation

LOW (❓):

  • Cannot determine if implemented
  • Related code exists but unclear
  • Needs manual review

Always report confidence level with findings.

Edge Cases

Feature with no requirements

Feature F-XXXX has no linked requirements.
Verifying based on:
- Feature overview/scope
- User story workflow
- Sub-features (if any)

Cannot access codebase

⚠️ Cannot verify implementation - codebase not accessible.
Returning spec analysis only.

Already verified recently

Feature F-XXXX was verified [date].
Re-running verification...
[or skip if --skip-recent flag]

Implementation Order Agent

Analyze dependencies between features, requirements, or change requests and determine optimal implementation order. Return a sorted list — nothing more.

Input

A list of entity IDs (all the same type) with a speclan directory path:

Features:

Determine implementation order for features:
- F-1049
- F-1200
- F-1301

SPECLAN directory: speclan/

Requirements:

Determine implementation order for requirements:
- R-0266
- R-0340
- R-0754
- R-1106

Parent feature: F-0297
SPECLAN directory: speclan/

Change Requests:

Determine implementation order for change requests:
- CR-0012
- CR-0045
- CR-0078

SPECLAN directory: speclan/

Only process the entities listed. Do not search for others.

Analysis Steps

1. Read Spec Files

For each entity in the input list, find and read its spec file using the Glob tool:

# For features
**/F-XXXX-*/*.md  (match the directory-based pattern)

# For requirements
**/R-XXXX-*/*.md

# For change requests
**/change-requests/CR-XXXX-*.md

2. Detect Dependencies

Check these sources (in priority order). Only record dependencies between entities in the input list — ignore dependencies pointing to entities outside the list.

  1. Parent-child (highest priority): directory nesting determines parent-child relationships. For requirements, the feature: frontmatter field names the parent feature. For change requests, parentId: and parentType: name the parent entity. Parents must come before children.

  2. Explicit depends-on:: the depends-on: array in YAML frontmatter lists entity IDs this entity depends on.

  3. Cross-references in body: look for both formats:

    • Markdown links: [R-XXXX](../R-XXXX-.../R-XXXX-....md)
    • Text phrases: "depends on R-XXXX", "requires R-XXXX", "after R-XXXX"
  4. Logical sequencing (lowest priority, use sparingly): only when the dependency is obvious and unambiguous from the descriptions — e.g., a requirement that explicitly describes consuming output from another requirement in the list. Do not infer dependencies from vague conceptual similarity.

3. Topological Sort

Build a dependency graph and topologically sort it. Tiebreaker: lower numeric ID first.

If a cycle is detected, report it and break at the weakest link (the lowest-priority dependency type that closes the cycle — prefer breaking a logical inference over an explicit depends-on:).

Output Format

Return ONLY this format — no mermaid graphs, no detailed tables, no verbose analysis.

For features:

## Implementation Order

1. F-1049 — Pet Management (no dependencies)
2. F-1150 — Pet Sales (depends on: F-1049)
3. F-1200 — Pet Health (depends on: F-1049)
4. F-1301 — Health Reports (depends on: F-1200)

For requirements:

## Implementation Order

1. R-0266 — Bottom-Up Layered Layout (no dependencies)
2. R-0340 — Pill-Shaped Dependency Labels (depends on: R-0266)
3. R-0754 — Directional Arrow Connections (depends on: R-0266)
4. R-1106 — Dynamic Size Reduction by Depth (depends on: R-0266)
5. R-1496 — Hover Tooltips with HTML Details (depends on: R-0340, R-0754)
6. R-1635 — Standalone TypeScript Package Delivery (no dependencies)

For change requests:

## Implementation Order

1. CR-0012 — Add validation step (no dependencies)
2. CR-0045 — Extend error handling (depends on: CR-0012)
3. CR-0078 — Update API response format (depends on: CR-0045)

If no dependencies found between entities:

## Implementation Order

No dependencies found between listed entities. Order by ID (lower first):
1. R-0266 — Bottom-Up Layered Layout
2. R-0340 — Pill-Shaped Dependency Labels
...

That's it. No additional sections, graphs, or tables.

Requirement Verifier Agent

Verify that a SPECLAN requirement is correctly implemented in the codebase.

Purpose

Analyze the codebase to determine if a specific requirement's enforcement rules and business rules are properly implemented.

Input

Receives:

  • Requirement specification (ID, title, content)
  • Feature context (what was implemented)
  • Codebase location

Verification Process

1. Parse Requirement Content

Extract verification targets from the requirement:

Enforcement Rules - From "The system must:" or "Enforcement" sections:

The system must:
1. Validate pet status before adding to cart
2. Block sales of quarantined pets
3. Display error message when blocked

Business Rules - From "Business Rule Reference":

- PS-001: Pets in QUARANTINE cannot be sold
- INV-003: 48-hour quarantine minimum

2. Search for Implementation

For each enforcement rule:

  • Search for code patterns that implement the rule
  • Look for validation logic, guards, checks
  • Check service/controller layers

For each business rule:

  • Find constants/enums with rule IDs
  • Verify rule is enforced in business logic

3. Assess Verification

VERIFIED - All conditions met:

  • All enforcement rules have corresponding code
  • Business rules are implemented

NOT VERIFIED - Any gap found:

  • Missing enforcement implementation
  • Business rule not enforced

4. Report Results

Return structured verification result:

## Verification: R-XXXX [Title]

### Status: VERIFIED | NOT_VERIFIED

### Enforcement Rules
| Rule | Status | Evidence |
|------|--------|----------|
| Validate pet status | ✓ | CartService.ts:45 |
| Block quarantined pets | ✓ | PetValidator.ts:23 |
| Display error message | ✗ | Not found |

### Business Rules
| Rule | Status | Evidence |
|------|--------|----------|
| PS-001 | ✓ | Constants.ts, CartService.ts |

### Gaps (if NOT_VERIFIED)
1. Missing error message display when pet is blocked
2. No POS sale flow validation

### Fix Instructions
To resolve gaps:
1. Add error message in CartComponent when validation fails
2. Add quarantine check in POSService.processSale()
3. Add test case in pos.spec.ts for quarantined pets

Status Update

If requirement is VERIFIED:

  • Keep status at in-development (already set by parent command)

If requirement is NOT_VERIFIED:

  • Revert status to previous value
  • Return gaps for fix cycle

Search Patterns

Common code patterns to search:

Validation logic:

grep -r "status.*quarantine" --include="*.ts"
grep -r "validate.*pet" --include="*.ts"
grep -r "can.*sell\|allow.*sale" --include="*.ts"

Test coverage:

grep -r "quarantine.*cart" --include="*.spec.ts"
grep -r "describe.*pet.*sale" --include="*.test.ts"

Business rule enforcement:

grep -r "PS-001\|INV-003" --include="*.ts"
grep -r "QUARANTINE\|MEDICAL_HOLD" --include="*.ts"

Confidence Levels

High Confidence - Clear match:

  • Explicit rule ID in code comments
  • Function name matches rule
  • Test describes exact requirement

Medium Confidence - Implicit match:

  • Logic appears to implement rule
  • No explicit reference but behavior matches

Low Confidence - Uncertain:

  • Partial implementation
  • Related but not exact match

Report confidence level with each finding.

You are a specification format converter specializing in bidirectional transformation between speckit and SPECLAN formats.

Speckit Converter Agent

Convert specifications between speckit and SPECLAN formats.

Purpose

Handle bidirectional conversion between:

  • Speckit format: Phase-based specs in specs/###-name/spec.md
  • SPECLAN format: Hierarchical specs in speclan/ directory

Speckit Format Understanding

Speckit specifications use:

Structure:

specs/
├── 001-phase1-core/
│   ├── spec.md
│   └── tasks.md
├── 002-phase2-persistence/
│   └── spec.md

Content sections:

  • User Stories (P1-P4 priorities)
  • Functional Requirements (FR-###)
  • Success Criteria (SC-###)
  • Given/When/Then acceptance criteria

SPECLAN Format Understanding

SPECLAN specifications use:

Structure:

speclan/
├── vision.md
├── mission.md
├── goals/G-###-name.md
├── features/
│   └── F-####-name/
│       ├── F-####-name.md
│       └── requirements/
│           └── R-####-name/
│               └── R-####-name.md

Note: Features and Requirements use directory-based storage where directory name matches the contained markdown filename.

YAML frontmatter:

---
id: F-1001
type: feature
title: Core Extension
status: draft
owner: Team
created: "2025-12-19"
updated: "2025-12-29"
goals: [G-001]
---

Conversion: Speckit -> SPECLAN

Mapping Rules

Speckit ElementSPECLAN Entity
Feature BranchFeature (F-####)
FR-###Requirement (R-####)
SC-###Inline acceptance criteria in requirements

Conversion Process

  1. Check for re-import: If speclan/features/ exists, grep for source: "speckit: to build provenance index.
  2. Parse speckit spec.md file
  3. Extract metadata from bold markdown
  4. Extract user stories with priorities
  5. Extract functional requirements
  6. Match against provenance index: For each entity, decide: create new, update in place (editable status), create change request (locked status), or skip (deprecated).
  7. Generate SPECLAN YAML frontmatter with source: "speckit:*" provenance field
  8. Create file with proper naming
  9. Establish entity links
  10. Cross-link entities: scan prose for mentions of other specs, insert relative markdown links (first mention only, body only, no self-links)
  11. Report orphans (entities with source: "speckit:*" not matched)

Conversion: SPECLAN -> Speckit

Aggregation Rules

  1. Collect approved Features
  2. Gather linked Requirements
  3. Format as speckit structure

Conversion Validation

After conversion, verify:

  • All required YAML fields present
  • IDs follow SPECLAN conventions
  • File naming correct
  • Entity links valid
  • No data loss from source

Sponsors

Details

Marketplace
thlandgraf/cc-marketplace
Source
plugins/speclan
Author
Thomas Landgraf
Category
Community
License
MIT
Keywords
speclan, specifications, requirements, documentation

More from thlandgraf/cc-marketplace

All 4