/silver <anything> as your workflow composer — it reads your intent, classifies the task, and routes to the right SB, GSD, and plugin path.How the Workflow Loop Works
The Silver Bullet software engineering workflow is a composed path with three recurring sections:
- Project initialization — runs once per project to produce requirements and a roadmap
- Per-phase loop — repeats for every phase in the roadmap (Steps 3–12)
- Finalization, deployment, and release — runs once after all phases are complete
Within the per-phase loop, every phase follows the same sequence: Discuss → Quality Gates → Plan → Execute → Verify → Code Review. The order is a hard constraint enforced by hooks — you cannot start Planning before Quality Gates passes.
/gsd:next at any point. GSD reads the current state from .planning/ and tells you exactly which step to do next.Step 0: Session Mode
Every session begins by loading the SB contract, project context, session state, and mode. Interactive is the default; autonomous mode can proceed through known decisions while still obeying gates.
The host runtime asks: "Run interactively or autonomously?" Your answer is written to ~/.claude/.silver-bullet/mode and read by hooks throughout the session.
In Autonomous mode, you can also pre-answer common decision points before work begins — mode preference, worktree preference, agent team isolation, and other workflow choices. These are read from the session log and applied automatically without interrupting the flow.
Project Initialization
Runs once per project. Skip entirely if .planning/PROJECT.md already exists.
Decide whether to use a git worktree for this task. Recommended for large features that benefit from isolation. Creates a separate working copy of the repo where changes can't interfere with main.
Kicks off with clarifying questions, ecosystem research, requirements scoping, and roadmap generation. This is where you define what you're building and how it's broken into phases.
Per-Phase Loop
Repeat Steps 3–12 for each phase in .planning/ROADMAP.md. All phases must complete before moving to Finalization.
Captures implementation decisions, gray areas, and preferences for this specific phase before any planning begins. The host runtime asks targeted questions about this phase — not the whole project.
Conditional Sub-Steps at Discuss
Depending on what this phase involves, additional skills may be required before moving to Quality Gates:
- New architectural decision: Write an ADR inline (title, status, context, decision, consequences)
- New service or major component:
/system-design - UI work:
/design-system+/ux-copy+/accessibility-review(WCAG 2.1 AA — required when UI work is present)
If any design sub-steps apply, the host runtime may ask once before beginning them whether to use the host's deeper reasoning tier for design output or continue with the current session model.
All relevant Silver Bullet quality dimensions are evaluated against the current design: modularity, reusability, scalability, security, reliability, usability, testability, extensibility, and AI/LLM safety where applicable. All relevant dimensions must pass. is a hard stop.
GSD researches the implementation space, then creates a detailed task-level plan. The quality gate report feeds in as hard requirements. After the plan is written, the runtime cross-references installed skills against the plan content to flag any skill gaps.
Wave-based parallel execution. GSD splits the plan into waves of independent tasks, dispatches each task as a separate agent in an isolated worktree, then runs a merge gate after each wave before the next begins. Before writing implementation code: invoke tdd (required) — red-green-refactor discipline per task. One atomic commit per task.
superpowers:subagent-driven-development here. GSD's wave-based execution is the only valid execution mechanism. It tracks commits, enforces atomic changes, and feeds into the verification step.Goal-backward verification against requirements and UAT. Asks: "Does what was built actually achieve the phase goal?" — not just "did all tasks complete?" If verification fails: invoke /silver:forensics or /gsd:debug depending on whether the failure is workflow/session-level or an active bug. If root cause is implementation, re-run execute/verify only. If root cause is design or plan, return to discussion/planning.
Frames review scope and dispatches superpowers:code-reviewer only when the active SB workflow selects that helper discipline. This helper does not replace GSD's authoritative code-review artifact.
Produces the authoritative REVIEW.md through GSD reviewer agents. Distinct from GSD's goal verification — this reviews the code itself, not whether it achieves the goal.
Triages all feedback from Step 9. Each item is explicitly accepted or rejected with reasoning. Accepted items become the input for post-review execution (Steps 11–12).
Only runs if items were accepted in Step 10. Otherwise, loop back to Step 3 for the next phase.
Creates a plan to address the accepted review items. Same planning rigor as Step 5.
Implements the review-driven plan with atomic commits. Same execution model as Step 6.
Finalization
Runs once after all phases in the roadmap are complete.
Define the test strategy: test pyramid structure, coverage goals, test classification (unit/integration/E2E), and tooling decisions. This is a design document, not test execution.
Runs configured verify commands or stack defaults and writes the freshness marker consumed by SB hooks. This is the test-execution gate; it complements the testing strategy document instead of replacing it.
Invoke /tech-debt to identify, categorize, and prioritize technical debt introduced or surfaced during this work. Appends structured items to docs/tech-debt.md using the format: | Item | Severity | Effort | Phase introduced |. Creates the file if needed.
Update or create project documentation according to the SB doc scheme: README, docs/PRD-Overview.md when applicable, docs/ARCHITECTURE.md, docs/TESTING.md, docs/internal/CICD.md when relevant, docs/doc-scheme.md/json, task doc checklist, docs/CHANGELOG.md, and monthly knowledge/lessons files. README must be updated before release can proceed. Also required: complete the session log file (path stored at ~/.claude/.silver-bullet/session-log-path) — fill in Task, Approach, Files changed, Skills invoked, Agent Teams dispatched, Autonomous decisions, Outcome, Knowledge and lessons additions, and runtime/cost note when available. If the path file is missing, create docs/sessions/<today>-manual.md from the session log template.
Branch rebase, cleanup, and merge preparation. Ensures the branch is ready to ship: rebased on main, no merge conflicts, commits squashed if needed. Skipped automatically when working directly on main/master.
Deployment
Runs the artifact review framework as a pre-deployment gate for applicable planning artifacts: SPEC, DESIGN, REQUIREMENTS, ROADMAP, CONTEXT, RESEARCH, INGESTION_MANIFEST, UAT, and cross-artifact alignment. Each reviewer must produce two consecutive clean passes before the gate clears. Review depth is configurable per artifact type in .planning/config.json (deep / standard / quick — standard is the default). Inserted in silver:feature before the UAT audit step.
Validates SPEC ↔ REQUIREMENTS ↔ ROADMAP ↔ DESIGN alignment in a single pass. If a DESIGN.md is absent, the DESIGN check is skipped with an informational notice. Misalignment findings block proceeding to Step 17 until resolved. Inserted in silver:feature after Step 17a.
CI must be green before any deployment step. Run local verify commands first, then check CI status with gh run list --limit 1 --json status,conclusion. In Interactive mode, the runtime shows status and waits for confirmation. In Autonomous mode, the runtime polls every 30 seconds up to 10 minutes. If CI is red: fix, re-push, re-check. Do not proceed to the deployment checklist while CI is failing.
Pre-deployment verification gate. A structured checklist run before any deployment — confirms rollback plan, monitoring, and stakeholder sign-off are in place.
Ship
Creates the pull request from the verified, deployed work. The PR body is auto-generated with phase summaries and requirement coverage. Includes links to verification and UAT results.
Release
Runs the milestone-level release workflow when the work is ready to publish: release quality gates, UAT and milestone audits, documentation checks, cross-artifact review, /verify-tests, gsd:ship, gsd:complete-milestone, then /silver:create-release as the final tag/release step.
Review Loop Enforcement Rule
Every review loop in the workflow (spec review, plan review, code review, verification) must iterate until the reviewer returns Approved TWICE IN A ROW. A single clean pass is not sufficient.
- Never stop because issues look minor or "close enough"
- Never count a loop as done unless the reviewer outputs Approved on two consecutive passes
- A single Approved is not sufficient — the next pass must also be clean
- The loop is self-limiting — it ends naturally when two consecutive passes are clean
- Surface to the user only if the reviewer raises an issue it cannot resolve (missing decision, external dependency, or constraint)
Anti-Skip Rules
These rules apply to every non-trivial change with no exceptions:
- You must not skip a required step because "it's simple enough"
- You must not combine or implicitly cover steps ("I did code review while writing")
- You must not claim a step is "not applicable" without explicit user approval
- You must not proceed to the next phase before completing the current one
- Every required skill must be explicitly invoked via the Skill tool — implicit coverage does not count