One prompt

Install

Paste it into your coding agent at the root of the project. It writes the SPEC-SS workflow into CLAUDE.md or AGENTS.md, replacing any workflow already there.

With the recommended tools

Set up the SPEC-SS development workflow in this project.

1. Find the agent instructions file this project uses: CLAUDE.md or AGENTS.md at the repository root. If both exist, use the one that already describes how the project works. If neither exists, create CLAUDE.md at the repository root.
2. If that file already describes a development workflow (how a task goes from idea to merged code: phases, process, "how we work"), replace that section with the section below. Do not keep both workflows. Leave unrelated sections (commands, architecture, code style) as they are.
3. If the file has no workflow section, add the section below after the project overview.
4. In the "S: Ship" phase, name the project's real test, lint, type-check and build commands (from package.json, a Makefile or the equivalent).
5. Make sure the recommended tools are installed. In Claude Code they install with:

   claude plugin marketplace add anthropics/claude-plugins-official
   claude plugin install superpowers@claude-plugins-official
   claude plugin install mattpocock-skills@claude-plugins-official
   claude plugin marketplace add fredsvanelli/skills
   claude plugin install pmkit@fredsvanelli
   claude plugin install runbooks@fredsvanelli
   claude plugin install utils@fredsvanelli

   If you cannot install one, keep its name in the section and tell me which one is missing.
6. Show me the diff of the instructions file when you are done.

Section to write:

## Development Workflow: SPEC-SS

Every task goes through six phases, in order: **S**pecify, **P**lan, **E**xecute, **C**heck, **S**ecure, **S**hip. SPEC builds the change; SS guards it and delivers it. A phase starts only when the one before it is done.

Every tool named in this section is a recommendation, not a requirement. Any plugin, skill or prompt that does the same job can replace it; when one is swapped, update its name here.

Rules for every phase:

- Use `superpowers:systematic-debugging` for any bug or failing test, before proposing a fix.
- Use `superpowers:verification-before-completion` before claiming any phase is done: run the check and read its output first.
- Planning alone does not authorize implementation. Follow the execution scope the user asks for.

### S: Specify (before any code is written)

1. **The issue.** Context, scope and acceptance criteria come from the issue, read through pmkit (`/pmkit:issues:work <id>`). Issues live in `.issues/`, or in the tracker pmkit is configured for.
2. **Q&A session.** `/grill-with-docs` and `superpowers:brainstorming` sharpen the issue against the PRD and the domain glossary (`GLOSSARY.md`). Answer factual questions from the code instead of asking the user.
3. **Terms and decisions recorded.** When a new term or a hard-to-reverse decision comes up, record it with `domain-modeling`: terms in `GLOSSARY.md`, decisions as ADRs in `docs/adr/`.
4. **Output: a written design doc** in `docs/superpowers/specs/YYYY-MM-DD-<slug>-design.md`. The user approves it before planning starts.

### P: Plan

`superpowers:writing-plans` turns the approved design into a plan in `docs/superpowers/plans/YYYY-MM-DD-<slug>.md`, the design's file name without `-design`. Execution follows the plan.

### E: Execute (TDD)

Implementation follows test-driven development (`superpowers:test-driven-development`): a failing test first, then the code that makes it pass. The execution skill depends on the size of the task:

- Small tasks: `superpowers:executing-plans`, a single agent running the tasks in sequence.
- Medium and larger tasks: `superpowers:subagent-driven-development`, an orchestrator dispatching one subagent per task.

### C: Check

Every user flow the work changes is validated by its runbook in `docs/runbooks/` (runbooks plugin). Create the runbook of a new flow with `/runbooks:create`, or update the existing one with `/runbooks:update`. Before calling the work done, run `/runbooks:list --affected`, then `/runbooks:run --affected`. Each runbook is verified by an E2E test script: Vitest for API flows, Playwright for web app flows. A failing runbook means the work is not done.

### S: Secure

Before each pull request, run `/utils:review-work` on the branch. It checks the branch against 12 criteria: spec match, scope and size, readability and conventions, tech debt, unit tests, E2E tests, security, cyclomatic complexity, error handling and edge cases, performance, backward compatibility and documentation. Fix its findings, or report the ones left open, before shipping.

### S: Ship

Ship with `superpowers:finishing-a-development-branch`, only when every check passes: tests, lint, type check and build. Open the pull request, then monitor CI (for example with `gh pr checks`). Never merge before every check is green, and never merge without explicit user authorization.

Replace each <YOUR_...> placeholder first

Set up the SPEC-SS development workflow in this project.

Before sending this prompt, replace every <YOUR_...> placeholder with the tool you use for that job: a plugin, a skill, a slash command or a prompt. If any placeholder is still in this text when you read it, ask me for it before writing anything.

1. Find the agent instructions file this project uses: CLAUDE.md or AGENTS.md at the repository root. If both exist, use the one that already describes how the project works. If neither exists, create CLAUDE.md at the repository root.
2. If that file already describes a development workflow (how a task goes from idea to merged code: phases, process, "how we work"), replace that section with the section below. Do not keep both workflows. Leave unrelated sections (commands, architecture, code style) as they are.
3. If the file has no workflow section, add the section below after the project overview.
4. In the "S: Ship" phase, name the project's real test, lint, type-check and build commands (from package.json, a Makefile or the equivalent).
5. Check that every tool named below is available in this environment. Keep its name in the section either way, and tell me which ones are missing.
6. Show me the diff of the instructions file when you are done.

Section to write:

## Development Workflow: SPEC-SS

Every task goes through six phases, in order: **S**pecify, **P**lan, **E**xecute, **C**heck, **S**ecure, **S**hip. SPEC builds the change; SS guards it and delivers it. A phase starts only when the one before it is done.

Every tool named in this section is a recommendation, not a requirement. Any plugin, skill or prompt that does the same job can replace it; when one is swapped, update its name here.

Rules for every phase:

- Use <YOUR_DEBUGGING_SKILL> for any bug or failing test, before proposing a fix.
- Use <YOUR_VERIFICATION_SKILL> before claiming any phase is done: run the check and read its output first.
- Planning alone does not authorize implementation. Follow the execution scope the user asks for.

### S: Specify (before any code is written)

1. **The issue.** Context, scope and acceptance criteria come from the issue, read through <YOUR_ISSUE_TRACKER_TOOL>.
2. **Q&A session.** <YOUR_GRILLING_SKILL> and <YOUR_BRAINSTORMING_SKILL> sharpen the issue against the PRD and the domain glossary (`GLOSSARY.md`). Answer factual questions from the code instead of asking the user.
3. **Terms and decisions recorded.** When a new term or a hard-to-reverse decision comes up, record it with <YOUR_DOMAIN_DOCS_SKILL>: terms in `GLOSSARY.md`, decisions as ADRs in `docs/adr/`.
4. **Output: a written design doc** in `docs/specs/YYYY-MM-DD-<slug>-design.md`. The user approves it before planning starts.

### P: Plan

<YOUR_PLANNING_SKILL> turns the approved design into a plan in `docs/plans/YYYY-MM-DD-<slug>.md`, the design's file name without `-design`. Execution follows the plan.

### E: Execute (TDD)

Implementation follows test-driven development (<YOUR_TDD_SKILL>): a failing test first, then the code that makes it pass. The execution skill depends on the size of the task:

- Small tasks: <YOUR_SINGLE_AGENT_EXECUTION_SKILL>, a single agent running the tasks in sequence.
- Medium and larger tasks: <YOUR_MULTI_AGENT_EXECUTION_SKILL>, an orchestrator dispatching one subagent per task.

### C: Check

Every user flow the work changes is validated by its runbook in `docs/runbooks/` (<YOUR_FLOW_VALIDATION_TOOL>). Create the runbook of a new flow, or update the existing one. Before calling the work done, run the runbooks of every flow the work touched. Each runbook is verified by an E2E test script: <YOUR_API_TEST_RUNNER> for API flows, <YOUR_WEB_E2E_TEST_RUNNER> for web app flows. A failing runbook means the work is not done.

### S: Secure

Before each pull request, run <YOUR_CODE_REVIEW_TOOL> on the branch. It checks the branch against 12 criteria: spec match, scope and size, readability and conventions, tech debt, unit tests, E2E tests, security, cyclomatic complexity, error handling and edge cases, performance, backward compatibility and documentation. Fix its findings, or report the ones left open, before shipping.

### S: Ship

Ship with <YOUR_SHIPPING_SKILL>, only when every check passes: tests, lint, type check and build. Open the pull request, then monitor CI (for example with `gh pr checks`). Never merge before every check is green, and never merge without explicit user authorization.