@juancr11/sibu 0.1.0

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@juancr11/sibu",
+  "version": "0.1.0",
+  "description": "CLI for setting up a local AI-augmented development workflow.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/juank11memphis/ai-augmented-workflow.git"
+  },
+  "homepage": "https://github.com/juank11memphis/ai-augmented-workflow#readme",
+  "bugs": {
+    "url": "https://github.com/juank11memphis/ai-augmented-workflow/issues"
+  },
+  "bin": {
+    "sibu": "./bin/sibu.js"
+  },
+  "files": [
+    "bin/sibu.js",
+    "bin/entrypoints/",
+    "bin/features/",
+    "bin/shared/",
+    "!bin/**/*.test.js",
+    "!bin/echo.js",
+    "templates/",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc && chmod +x bin/sibu.js",
+    "check": "tsc --noEmit",
+    "verify": "pnpm build && pnpm check && pnpm test",
+    "dev:link": "pnpm install && pnpm build && pnpm link --global",
+    "dev:unlink": "pnpm unlink --global sibu",
+    "prepack": "pnpm run build",
+    "smoke:init": "node ./bin/sibu.js init",
+    "test": "pnpm build && node --test bin/shared/catalog.test.js bin/shared/npm-version.test.js bin/shared/prompts.test.js bin/shared/workflow-targets.test.js bin/shared/workflow-mutation-readiness.test.js bin/features/doctor-project/handler.test.js bin/features/use-skill/handler.test.js bin/features/stop-managing-file/handler.test.js",
+    "validate:packed-runtime": "node ./scripts/validate-packed-cli-runtime.mjs",
+    "validate:doctor-version-advisory": "pnpm build && node ./scripts/validate-doctor-version-advisory.mjs",
+    "validate:post-update-doctor-drift": "pnpm build && node ./scripts/validate-post-update-doctor-drift.mjs",
+    "validate:release": "pnpm verify && npm pack && pnpm run validate:packed-runtime && pnpm run validate:doctor-version-advisory && pnpm run validate:post-update-doctor-drift"
+  },
+  "keywords": [
+    "ai",
+    "agents",
+    "workflow",
+    "cli"
+  ],
+  "license": "UNLICENSED",
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.0",
+    "@types/react": "^19.2.14",
+    "typescript": "^6.0.2"
+  },
+  "packageManager": "pnpm@10.28.2",
+  "dependencies": {
+    "@clack/prompts": "^1.2.0",
+    "chalk": "^5.6.2",
+    "commander": "^14.0.3",
+    "gradient-string": "^3.0.0",
+    "ink": "^7.0.0",
+    "react": "^19.2.5"
+  },
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/templates/.codex/config.toml

@@ -0,0 +1 @@
+model_instructions_file = "../AGENTS.md"

package/templates/AGENTS.md

@@ -0,0 +1,60 @@
+# AGENTS.md
+
+## Project overview
+
+{{PROJECT_OVERVIEW}}
+
+## Security and safety
+
+- Do not commit secrets, credentials, tokens, or other sensitive data.
+- Avoid destructive operations unless the user explicitly requests them or confirms the plan.
+- Keep changes focused on the requested scope; do not introduce unrelated refactors or enhancements.
+- If an implementation becomes materially more complex or risky than expected, stop and ask for explicit approval before continuing.
+
+## Agent-specific instructions
+
+- Before any task that requires code changes, propose a brief plan and wait for user confirmation once per requested task.
+- After confirmation, proceed with all agreed in-scope changes without re-asking.
+- Ask again only if the scope changes materially, the approach becomes materially more complex or risky, or the user explicitly asks to review before continuing.
+- Use Conventional Commits 1.0.0 for commit messages.
+
+## Communication style
+
+- Keep responses as short as practical while still being clear and useful.
+- Prefer concise, pragmatic answers over long explanations.
+- Ask focused questions when needed; otherwise make reasonable assumptions and proceed.
+- If the user wants more detail, they can ask follow-up questions.
+
+## Skill routing
+
+- For any code-writing task, use `clean-code`.
+- For requests to create, revise, or clarify a product vision, product strategy narrative, product north star, positioning, product principles, product voice, target user definition, product boundaries, or success signals, use `product-vision-writer`.
+- For requests to create, revise, or clarify a business-level feature brief, feature definition, feature scope, MVP feature boundaries, business acceptance criteria, or product-level feature rationale, use `feature-brief-writer`.
+- For requests to create, revise, or clarify a technical design, implementation-oriented design doc, architecture approach, technical tradeoffs, technical risks, or implementation plan for an approved feature, use `technical-design-writer`.
+- For requests to create Epics, User Stories, Scrum planning artifacts, backlog slices, or delivery plans from an approved feature brief and technical design, use `scrum-master-planner`.
+- For requests to turn a specific User Story into an implementation checklist, coding plan, step-by-step execution plan, or baby-step plan, use `ai-implementation-planner`.
+- For requests to implement, execute, continue, or work through an existing story implementation plan under `docs/features/<feature-slug>/epics/<epic-slug>/stories/<order>-<story-slug>.impl_plan/`, use `ai-implementation-plan-executor`.
+{{OPTIONAL_SKILL_ROUTING}}
+
+## Sibu maintenance
+
+This repository uses Sibu to manage AI workflow setup.
+
+- `sibu init` is a one-time bootstrap command for adopting Sibu in a project. It creates the initial agent support files, keeps existing files unchanged, and creates `.sibu/state.json` metadata. Do not rerun `sibu init` to apply updates to an existing Sibu project.
+- `sibu doctor` is the read-only health check for this workflow. It inspects whether Sibu-managed files are missing, modified, unrecorded, or generated from older templates.
+- `sibu sync` is the post-init workflow maintenance command. It reviews template updates interactively, repairs missing managed files, adopts newly added managed templates, protects local edits from automatic overwrites, and lets the user apply safe updates, mark customized files as reviewed, write side templates, stop managing a file, or skip for later.
+
+At the start of each session in this repository, run `sibu doctor` once before making changes or giving workflow guidance. Treat it as a read-only preflight check. Do not rerun it before every follow-up in the same session unless workflow-managed files changed, the user asks, or you need to verify Sibu state after applying updates.
+
+After `sibu doctor` finishes, guide the user based on the outcome:
+
+- If the workflow is healthy, mention that the Sibu check passed and proceed with the requested work.
+- If `.sibu/state.json` is missing because the project has not been initialized, tell the user to run `sibu init` once before continuing.
+- If managed workflow files are missing, unrecorded, modified, or generated from older templates, tell the user to run `sibu sync` to review and repair them.
+- If `sibu doctor` cannot run because Sibu is unavailable, tell the user how to install or run Sibu for this project before relying on template status.
+
+Sibu records managed workflow file metadata in `.sibu/state.json`, including template versions, file hashes, selected agent support, and whether files are `managed`, `customized`, or `unmanaged`.
+
+If `.sibu/state.json` is missing because Sibu has not been adopted in the project, ask the user to run `sibu init` once.
+If workflow files may be missing, modified, unrecorded, or drifted from the recorded Sibu state, ask the user to run `sibu doctor` first.
+If `sibu doctor` reports missing managed files, unrecorded expected files, local edits, or older templates, ask the user to run `sibu sync`.

package/templates/CLAUDE.md

@@ -0,0 +1,5 @@
+# CLAUDE.md
+
+Follow the project instructions in `AGENTS.md`.
+
+`AGENTS.md` is the source of truth for project overview, safety rules, and agent-specific workflow instructions.

package/templates/GEMINI.md

@@ -0,0 +1,5 @@
+# GEMINI.md
+
+Follow the project instructions in `AGENTS.md`.
+
+`AGENTS.md` is the source of truth for project overview, safety rules, and agent-specific workflow instructions.

package/templates/manifest.json

@@ -0,0 +1,129 @@
+{
+  "templateVersion": "42",
+  "templates": {
+    "AGENTS.md": {
+      "version": "18",
+      "description": "Project-level agent instructions and Sibu maintenance guidance.",
+      "changes": [
+        "Renames the workflow maintenance commands and state path from Echo to Sibu so generated guidance matches the new product name."
+      ]
+    },
+    ".codex/config.toml": {
+      "version": "1",
+      "description": "Codex configuration pointing to AGENTS.md.",
+      "changes": [
+        "Configures Codex to use the root AGENTS.md instructions file."
+      ]
+    },
+    "GEMINI.md": {
+      "version": "1",
+      "description": "Gemini instructions delegating to AGENTS.md.",
+      "changes": [
+        "Delegates Gemini project instructions to AGENTS.md as the source of truth."
+      ]
+    },
+    "CLAUDE.md": {
+      "version": "1",
+      "description": "Claude instructions delegating to AGENTS.md.",
+      "changes": [
+        "Delegates Claude project instructions to AGENTS.md as the source of truth."
+      ]
+    },
+    "skills/clean-code/SKILL.md": {
+      "version": "4",
+      "description": "Mandatory clean-code skill installed once at the shared .agents/skills workspace path.",
+      "changes": [
+        "Installs the clean-code skill once at .agents/skills/clean-code/SKILL.md for any selected agent instead of duplicating per-agent copies.",
+        "Uses the shared .agents/skills workspace path to test common skill discovery across Codex, Gemini, and Claude."
+      ]
+    },
+    "skills/product-vision-writer/SKILL.md": {
+      "version": "3",
+      "description": "Mandatory product vision writer skill installed once at the shared .agents/skills workspace path.",
+      "changes": [
+        "Changes product vision discovery to ask one question at a time so users can shape the vision through a focused interview instead of answering a large batch up front."
+      ]
+    },
+    "skills/feature-brief-writer/SKILL.md": {
+      "version": "2",
+      "description": "Mandatory feature brief writer skill installed once at the shared .agents/skills workspace path.",
+      "changes": [
+        "Clarifies that agents must not draft feature briefs from vague feature requests and should ask one focused discovery question at a time until the feature intent is clear.",
+        "Adds minimum context guidance so feature briefs are written only after the feature intent, target user or scenario, desired outcome, and rough MVP boundary are clear."
+      ]
+    },
+    "skills/technical-design-writer/SKILL.md": {
+      "version": "8",
+      "description": "Mandatory technical design writer skill installed once at the shared .agents/skills workspace path.",
+      "changes": [
+        "Updates the technical design examples to refer to the Sibu command names instead of the old Echo branding."
+      ]
+    },
+    "skills/typescript/SKILL.md": {
+      "version": "1",
+      "description": "Selectable TypeScript skill installed when TypeScript language support is selected.",
+      "changes": [
+        "Adds an optional TypeScript skill for projects that use .ts or .tsx files."
+      ]
+    },
+    "skills/golang/SKILL.md": {
+      "version": "1",
+      "description": "Selectable Go skill installed when Go language support is selected.",
+      "changes": [
+        "Adds an optional Go skill with concise, Effective Go–style guidance for .go files, package APIs, interfaces, errors, receivers, concurrency, and tests."
+      ]
+    },
+    "skills/architecture/ddd-hexagonal/SKILL.md": {
+      "version": "1",
+      "description": "Selectable back-end architecture skill for DDD and Hexagonal Architecture.",
+      "changes": [
+        "Adds an optional DDD + Hexagonal Architecture skill for projects that want opinionated back-end architecture guidance."
+      ]
+    },
+    "skills/architecture/command-pattern/SKILL.md": {
+      "version": "2",
+      "description": "Selectable architecture skill for command-oriented vertical slices using Command Pattern, Hexagonal Architecture, and DDD principles.",
+      "changes": [
+        "Reframes Command Pattern guidance around command-oriented vertical slices, feature-local ports, thin entrypoints, and infrastructure adapters."
+      ]
+    },
+    "skills/nextjs/SKILL.md": {
+      "version": "1",
+      "description": "Selectable framework skill for Next.js App Router and framework-specific behavior.",
+      "changes": [
+        "Adds an optional Next.js skill for projects that use App Router pages, layouts, route handlers, metadata, and Server/Client Component boundaries."
+      ]
+    },
+    "skills/react/SKILL.md": {
+      "version": "1",
+      "description": "Selectable React skill for component design, props, state ownership, and presentational boundaries.",
+      "changes": [
+        "Adds an optional React skill for projects that create or change React components, props, state ownership, or presentational and data-owning boundaries."
+      ]
+    },
+    "skills/scrum-master-planner/SKILL.md": {
+      "version": "2",
+      "description": "Mandatory Scrum planner skill for creating pragmatic Epics and User Stories from approved feature and technical design docs.",
+      "changes": [
+        "Moves Scrum User Stories into an Epic-local stories/ folder.",
+        "Adds two-digit execution-order filename prefixes for User Stories, with shared numbers indicating parallelizable work."
+      ]
+    },
+    "skills/ai-implementation-planner/SKILL.md": {
+      "version": "4",
+      "description": "Mandatory AI implementation planner skill for turning one approved User Story into small, story-local implementation step files.",
+      "changes": [
+        "Changes AI implementation planner step files to use lowercase .md extensions.",
+        "Updates the step-file format to use Markdown headings for Step, Goal, Scope, Files, and Done when sections."
+      ]
+    },
+    "skills/ai-implementation-plan-executor/SKILL.md": {
+      "version": "3",
+      "description": "Mandatory AI implementation plan executor skill for implementing existing story implementation plans one reviewed step at a time.",
+      "changes": [
+        "Changes implementation plan executor review status to record the current Git user in the Approved by field.",
+        "Keeps the approved-step commit gate before moving to the next implementation step."
+      ]
+    }
+  }
+}

package/templates/skills/ai-implementation-plan-executor/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: ai-implementation-plan-executor
+description: Execute an existing ai-implementation-planner story implementation plan one ordered step at a time. Use when asked to implement, execute, continue, or work through a story implementation plan under docs/features/<feature-slug>/epics/<epic-slug>/stories/<order>-<story-slug>.impl_plan/.
+---
+
+# AI Implementation Plan Executor
+
+## Purpose
+
+Execute one existing story implementation plan, one ordered step file at a time, with human review between steps.
+
+This skill owns implementation execution from an existing `.impl_plan/` folder. It does not create implementation plans, change story scope, or skip user review gates.
+
+## Required source context
+
+The user must provide or clearly identify exactly one User Story or implementation plan folder:
+
+```txt
+docs/features/<feature-slug>/epics/<epic-slug>/stories/<order>-<story-slug>.md
+```
+
+or:
+
+```txt
+docs/features/<feature-slug>/epics/<epic-slug>/stories/<order>-<story-slug>.impl_plan/
+```
+
+Before implementing any step, read:
+
+```txt
+docs/features/<feature-slug>/epics/<epic-slug>/stories/<order>-<story-slug>.md
+docs/features/<feature-slug>/epics/<epic-slug>/stories/<order>-<story-slug>.impl_plan/*.md
+docs/features/<feature-slug>/epics/<epic-slug>/epic_brief.md
+docs/features/<feature-slug>/feature_brief.md
+docs/features/<feature-slug>/technical_design.md
+```
+
+Also read `docs/product-vision.md` when product fit, target user, scope boundaries, or success signals are ambiguous.
+
+Before changing code, read and apply the implementation skills required by the plan and repository routing:
+
+- always read and apply `clean-code`
+- read and apply architecture skills when relevant, such as `command-pattern` or `ddd-hexagonal`
+- read and apply language skills when relevant, such as `typescript`
+- read and apply framework skills when relevant, such as `react` or `nextjs`
+
+Inspect existing code, tests, scripts, and docs only as needed for the current step.
+
+## Hard start rule
+
+If the `.impl_plan/` folder does not exist, is empty, or has no ordered `.md` step files:
+
+1. Stop.
+2. Tell the user the implementation plan is missing.
+3. Instruct the user to use `ai-implementation-planner` to create the implementation plan first.
+4. Do not infer steps from the story or technical design.
+
+If required source context is missing:
+
+1. Stop.
+2. Say which file is missing.
+3. Ask the user to create or restore the missing artifact first.
+4. Do not invent implementation scope from partial context.
+
+## Step execution model
+
+Work on exactly one step at a time.
+
+A step file is considered approved only when it contains this section:
+
+```md
+## Review status
+
+- Status: approved
+```
+
+When starting or resuming a plan:
+
+1. Read all step files in filename order.
+2. Identify the first step file that is not approved.
+3. Implement only that step.
+4. Run the validation named in that step when practical.
+5. Report what changed, validation results, and any risks.
+6. Stop and wait for explicit user confirmation before moving to the next step.
+
+Do not begin the next step in the same response unless the user has already explicitly approved the current step in this turn.
+
+## User review gate
+
+After implementing a step, say that the step is ready for review and that you are waiting for confirmation before continuing.
+
+If the user asks questions or requests changes, stay on the same step until those changes are complete.
+
+When the user explicitly approves the current step, update that step file by adding or updating:
+
+```md
+## Review status
+
+- Status: approved
+- Approved by: <current git user>
+- Approved at: <ISO-8601 timestamp>
+```
+
+Before writing the approval marker, identify the current Git user with `git config user.name`; if it is unavailable, use `git config user.email`. Use that value for `Approved by`. After writing the approval marker, commit all changes for the approved step before continuing. Use a Conventional Commits 1.0.0 message that describes the completed step. If the commit fails, stop and report the failure instead of continuing.
+
+Then continue with the next unapproved step only after the approval marker is written and the approved step changes are committed.
+
+If the user asks to continue without clearly approving the current step, ask for explicit approval before marking it approved, committing, or moving on.
+
+## Implementation rules
+
+Do:
+
+- preserve the source story scope and acceptance criteria
+- follow the current step file exactly unless it conflicts with source context
+- keep changes focused on the current step's `## Scope` and `## Files`
+- use existing project patterns and the relevant skills
+- run focused validation for the current step when possible
+- stop and ask if the step is ambiguous, missing required files, or conflicts with the technical design
+
+Do not:
+
+- create a missing plan from scratch
+- implement multiple unapproved steps in one pass
+- mark a step approved before the user explicitly approves it
+- add product scope absent from the story, Epic, feature brief, technical design, or step file
+- continue past a failed validation without reporting it and asking how to proceed
+- leave approved step changes uncommitted before moving to the next step
+
+## Final response behavior after each step
+
+After implementing one step, briefly report:
+
+- current step file path
+- summary of changes made
+- validation run and result
+- any risks, blockers, or follow-up questions
+- that you are waiting for user approval before marking the step approved, committing it, and continuing to the next step

package/templates/skills/ai-implementation-planner/SKILL.md

@@ -0,0 +1,213 @@
+---
+name: ai-implementation-planner
+description: Turn one approved User Story Markdown file into LLM-sized implementation step files. Use when asked to create an implementation plan, coding checklist, step-by-step execution plan, or baby-step plan for completing a specific User Story from docs/features/<feature-slug>/epics/<epic-slug>/stories/.
+---
+
+# AI Implementation Planner
+
+## Purpose
+
+Turn one approved User Story into a set of concrete Markdown step files an AI coding agent can execute to complete the story safely and completely.
+
+This skill owns implementation planning for one story at a time. It does not own product scope, technical design decisions, Scrum planning, or code implementation.
+
+## Required input
+
+The user must provide or clearly identify exactly one User Story file:
+
+```txt
+docs/features/<feature-slug>/epics/<epic-slug>/stories/<order>-<story-slug>.md
+```
+
+Do not create an implementation plan from a vague request, Epic brief, feature brief, or technical design alone.
+
+## Required source context
+
+Before planning, read:
+
+```txt
+docs/features/<feature-slug>/epics/<epic-slug>/stories/<order>-<story-slug>.md
+docs/features/<feature-slug>/epics/<epic-slug>/epic_brief.md
+docs/features/<feature-slug>/feature_brief.md
+docs/features/<feature-slug>/technical_design.md
+```
+
+Also read `docs/product-vision.md` when product fit, target user, scope boundaries, or success signals are ambiguous.
+
+Before writing the step files, read and apply the required planning skills as source context:
+
+- always read and apply `clean-code`
+- read and apply the selected architecture skill when relevant, such as `command-pattern` or `ddd-hexagonal`
+- read and apply language skills when relevant, such as `typescript`
+- read and apply framework skills when relevant, such as `react` or `nextjs`
+
+Use those skills to shape implementation steps. Do not copy their full guidance into the step files.
+
+Inspect existing code, tests, scripts, and docs only as much as needed to make the step files concrete. Avoid broad codebase analysis.
+
+## Hard start rule
+
+If the User Story file is missing or unclear:
+
+1. Stop.
+2. Ask the user for the exact User Story file path.
+3. Do not infer the story from nearby files.
+
+If any required source context file is missing:
+
+1. Stop.
+2. Say which file is missing.
+3. Ask the user to create or restore the missing artifact first.
+4. Do not invent implementation scope from partial context.
+
+## Output location
+
+Write one Markdown file per implementation step under a story-local implementation plan folder:
+
+```txt
+docs/features/<feature_slug>/epics/<epic_slug>/stories/<order>-<story_slug>.impl_plan/<step_order>-<step_slug>.md
+```
+
+Use the source story filename, without its `.md` extension, as the implementation plan folder name plus `.impl_plan`.
+
+Examples:
+
+```txt
+stories/01-resolve-a-selectable-skill-by-name.md
+stories/01-resolve-a-selectable-skill-by-name.impl_plan/01-add-skill-resolution-domain-step.md
+stories/01-resolve-a-selectable-skill-by-name.impl_plan/02-wire-skill-resolution-command-step.md
+```
+
+File naming rules:
+
+- use two-digit step order prefixes (`01`, `02`, `03`) unless the repository uses another explicit convention
+- use lowercase kebab-case step slugs
+- keep each step file focused on exactly one executable implementation step
+- use the lowercase `.md` extension exactly as shown
+- if the correct story slug, step order, or step slug is unclear, stop and ask before writing files
+
+## Planning rules
+
+Create pragmatic implementation step files, not a second technical design.
+
+Each step file must be a concrete implementation step, not a discovery, scope-confirmation, or generic review step. The skill performs source reading and targeted inspection before writing the step files; each step tells the AI what to change, where to change it, how to implement it at a high level, and how to know that step is done.
+
+Do:
+
+- preserve the User Story scope and acceptance criteria
+- sequence concrete implementation, test, validation, and cleanup steps across separate step files
+- map acceptance criteria to one or more step files
+- call out dependencies, sequencing constraints, and risk checkpoints
+- include test, build, lint, or manual validation commands when known
+- include a stop-and-ask condition when the implementation would exceed the technical design
+
+Do not:
+
+- write or modify production code
+- add product scope absent from the story, Epic, feature brief, or technical design
+- duplicate the full technical design
+- include prerequisite reading, scope confirmation, or repository inspection as step files
+- create task noise such as “review the code” without a specific implementation or validation purpose
+- prescribe architecture that conflicts with the selected architecture skill or technical design
+
+## Workflow
+
+### 1. Read and bound the story
+
+Identify:
+
+- story title and source path
+- target user or contributor
+- desired outcome
+- in-scope work
+- out-of-scope boundaries
+- acceptance criteria
+- validation expectations
+
+If the story lacks testable acceptance criteria, stop and ask for the User Story to be clarified.
+
+### 2. Read feature and technical context
+
+From the Epic and feature brief, identify delivery boundaries and user value.
+
+From the technical design, identify:
+
+- intended implementation approach
+- affected commands, modules, files, adapters, docs, or tests
+- known risks or unresolved decisions
+- expected validation commands or checks
+
+### 3. Inspect the repository narrowly
+
+Inspect only the files and commands needed to make the checklist actionable. Useful targets include:
+
+- existing feature folders or handlers related to the story
+- entrypoints or command wiring mentioned by the technical design
+- tests covering similar behavior
+- package scripts, build commands, or validation commands
+- docs that must be updated by the story
+
+### 4. Write the implementation step files
+
+Create one `.md` file per step in the story-local `.impl_plan` folder. Use this structure for every step file:
+
+```md
+# Step: <Imperative step title>
+
+## Goal
+
+<One short paragraph describing the implementation outcome for this step.>
+
+## Scope
+
+- <Specific in-scope action or boundary>
+- <Specific in-scope action or boundary>
+- Do not <explicit out-of-scope boundary when useful>
+
+## Files
+
+- <path/to/file.ext>
+- <path/to/test_file.ext>
+
+## Done when
+
+- <Specific observable completion condition>
+- <Acceptance criterion or technical requirement covered by this step is satisfied>
+- <Relevant compile, test, lint, build, or manual validation passes>
+```
+
+Step-file requirements:
+
+- the first line must be `# Step: <Imperative step title>`
+- use exactly these Markdown section headings: `## Goal`, `## Scope`, `## Files`, `## Done when`
+- keep each step small enough for one AI coding pass
+- name every known file, module, command, or artifact to change or validate
+- include explicit out-of-scope boundaries in `Scope` when they prevent scope creep
+- include validation commands in `Done when` when known
+- ensure the full set of step files covers every acceptance criterion
+
+If something required for a concrete step is unclear or missing, do not assume. Stop and ask before proceeding.
+
+### 5. Check plan quality
+
+Before finishing, verify:
+
+- the step files are for exactly one User Story
+- every acceptance criterion maps to at least one step file
+- every step file names the file, module, command, or artifact to change when known
+- every step file explains the high-level implementation goal and scope
+- every step file has clear done conditions
+- validation is explicit enough to prove the story is complete
+- the step files do not add scope beyond the source artifacts
+- architecture and code-quality steps align with the relevant skills
+
+## Final response behavior
+
+After writing the files, briefly report:
+
+- the implementation plan folder path
+- the step file paths created
+- the source User Story path
+- any risks or stop conditions captured in the step files
+
+Do not paste the full step files unless the user asks to review them inline.