Core Concepts

Skills

A skill is a markdown file that contains a detailed prompt and instructions for the active runtime to follow when performing a specific task. When you invoke a skill, the runtime reads the file and executes its instructions as if it were a step-by-step process guide. Silver Bullet includes orchestration workflow skills (silver:feature, silver:bugfix, silver:ui, silver:devops, silver:research, silver:release, silver:fast), spec-pipeline skills (silver:spec, silver:ingest, silver:validate), artifact reviewer skills, and supporting skills for quality gates, enforcement, analytics, and project management.

How Skills Are Stored

Skills live in two locations:

• ~/.claude/skills/ — flat .md files, one per skill
• ~/.claude/plugins/cache/ — structured as publisher/plugin/version/skills/skill-name/SKILL.md

How Skills Are Invoked

Inside the host coding agent, skills are invoked with the Skill tool using a slash-command shorthand:

The /silver Router

/silver is Silver Bullet's smart dispatcher. It accepts freeform natural language, classifies task complexity and intent, then composes the right SB, GSD, and plugin workflow path for the work at hand. GSD has its own /gsd:do router; Silver Bullet's added value is broader dynamic workflow composition plus enforcement around GSD-backed execution.

Skill Discovery

At the start of each task, Silver Bullet scans all installed skills and cross-references them against the task description. It surfaces candidates that might apply — for example, flagging /security when auth changes are involved. This prevents relevant skills from being forgotten.

Hooks

A hook is a script that the host coding agent runs on lifecycle events such as PreToolUse, PostToolUse, UserPromptSubmit, Stop, and session start. Silver Bullet uses hooks to make the process enforceable instead of relying on the active runtime to remember every rule.

What Hooks Enforce

• Skill recording — records actual Skill tool invocations; implicit coverage never counts.
• Workflow order — blocks plan/execute/ship movement when required upstream gates are missing.
• Planning file ownership — blocks direct edits to GSD-managed artifacts and forces the owning GSD workflow to make lifecycle changes.
• Completion and delivery gates — blocks final delivery commands until the required planning, review, verification, test, CI, and release gates are complete.
• CI freshness — warns or blocks based on operation type so broken builds do not reach PR/deploy/release steps.
• Prompt reminders — re-inject missing-step state before user prompts so context compaction cannot erase the workflow contract.

Trivial Changes

Not every edit needs a full workflow. For trivial edits and bounded medium changes, use /silver:fast. It routes Tier 1 work to gsd:fast, Tier 2 work to gsd:quick with flags, and escalates anything larger into the full Silver Bullet workflow instead of relying on legacy marker files.

GSD — The Lifecycle Engine

GSD (Get Shit Done) is the planning and execution engine inside Silver Bullet. SB composes the surrounding workflow; GSD owns requirements, roadmap, per-phase planning, execution, verification, and phase-level ship. It manages the complete lifecycle of a development task — from requirements through shipment — using a structured file-based workflow in the .planning/ directory.

What GSD Manages

• .planning/PROJECT.md — Project definition and goals
• .planning/REQUIREMENTS.md — Authoritative requirements list (single source of truth)
• .planning/ROADMAP.md — Phased implementation plan
• .planning/{phase}-CONTEXT.md — Decisions captured in Discuss step
• .planning/{phase}-PLAN.md — Detailed task-level implementation plan
• .planning/{phase}-VERIFICATION.md — Goal-backward verification results

GSD Commands

GSD is invoked via slash commands that the host coding agent resolves to GSD's installed workflows:

Superpowers Helpers

Superpowers is used by Silver Bullet only at explicit helper boundaries selected by the active workflow. GSD remains the lifecycle authority for planning, execution, verification, code-review artifacts, and shipping. SB may call Superpowers-backed helpers for TDD discipline, review framing/triage, verification-before-completion, and branch finishing.

Key Superpowers-backed Helpers Used in Silver Bullet

• tdd — SB wrapper that delegates to Superpowers TDD only before behavior-changing execution
• /requesting-code-review — Frames review scope and dispatches superpowers:code-reviewer only when the active SB workflow selects that helper. It does not replace /gsd:code-review.
• /receiving-code-review — Triage all feedback: accept or reject each item with reasoning before fixing
• /verification-before-completion — Final claim verification helper used by SB release gates
• /finishing-a-development-branch — Branch/PR finishing helper used only at the selected ship boundary

SB / GSD / Helper Ownership Model

Silver Bullet enforces a strict ownership split to prevent duplicate planning, duplicate review artifacts, and execution outside GSD:

Quality Gates

Quality gates are a mandatory pre-planning step where the active runtime evaluates the proposed design against 8 core product quality dimensions plus conditional gates when applicable. All must pass before planning begins — a single is a hard stop.

How Quality Gates Are Evaluated

The /silver:quality-gates skill evaluates each relevant dimension, commonly by dispatching parallel reviewers in isolated worktrees. Results are synthesised by the active runtime. The most conservative finding wins: if one reviewer flags a dimension as , the whole gate fails.

DevOps Quality Gates

For infrastructure work, /devops-quality-gates applies 7 IaC-adapted dimensions, excluding usability and AI/LLM safety when they do not apply. The focus shifts to idempotency, drift prevention, least-privilege IAM, and infrastructure reliability.

Enforcement Layers

Silver Bullet v0.35.1 describes twelve independent enforcement layers. They overlap deliberately: if one context path misses a rule, another hook or instruction surface restates it.

Session Modes

Every session begins with a mode selection that controls how much the runtime pauses for approval:

The mode is written to ~/.claude/.silver-bullet/mode and read by hooks throughout the session. If the file is missing or unreadable at any point, the system defaults to Interactive.

Autonomous Mode Safeguards

Even in autonomous mode, Silver Bullet has stall-detection to prevent infinite loops. Two independent tiers run in parallel:

• Wall-clock sentinel: If no skill has been recorded in the last 10 minutes, a timeout warning fires.
• Call-count tier: Warns at 30, 60, and 100+ tool calls since the last skill invocation — escalating in urgency at each threshold.
• Identical-call guard: The same tool call with identical arguments producing the same result 2+ times consecutively is treated as a stall.

On any stall: the runtime makes a best-judgment call, moves on, and logs the decision for review.

Agent Teams

Silver Bullet uses the runtime's sub-agent capability to parallelize work. When a phase has independent implementation units (different modules, different quality dimensions), multiple agents run simultaneously in isolated git worktrees.

How It Works

1. GSD's execute-phase identifies independent tasks within a wave
2. Each task is dispatched as a separate agent with isolation: "worktree"
3. All agents run in parallel (with run_in_background: true in Autonomous mode)
4. After all agents complete, a merge gate resolves any conflicts before the next wave starts

Semantic Context Compression

Silver Bullet includes an automatic context optimization system that runs as a PostToolUse hook. It scans your source and documentation files, ranks chunks by relevance to the current phase goal using TF-IDF scoring, and injects the most relevant context into the active runtime's working memory before each tool use.

This keeps the runtime focused on the right parts of a large codebase without exhausting its context window on irrelevant files. Results are cached between tool uses and invalidated when files change.

Configure it in .silver-bullet.json under "semantic_compression".

Standard File Structure

After /silver:init initializes a project, you'll find this structure:

Documentation Scheme

Silver Bullet scaffolds a bounded, non-redundant documentation architecture for every project. Documentation lives in three layers: planning (.planning/, ephemeral per-milestone), project docs (docs/, durable across milestones), and public (README.md). Every document uses one of five scalability patterns — snapshot, capped table, rotation, summary+archive, or fixed — so no file grows unbounded.

Project intelligence is split into docs/knowledge/ (project-specific patterns, gotchas, decisions) and docs/lessons/ (portable lessons with a strict category taxonomy). Both use monthly files (YYYY-MM.md) that freeze after their month ends.

Spec-Driven Development

Silver Bullet’s spec pipeline provides three skills that take you from raw requirements to a validated, traceable SPEC.md before any code is written.

SPEC.md Canonical Format

The SPEC.md file is the authoritative spec artifact. It holds structured requirements, acceptance criteria, assumption tracking, and a cross-reference to source inputs (JIRA tickets, Figma links, PRD excerpts). All downstream artifacts — REQUIREMENTS.md, ROADMAP.md, DESIGN.md — must stay aligned with SPEC.md.

silver:spec — Spec Creation

/silver:spec runs an AI-driven elicitation session that produces a canonical SPEC.md. It asks structured questions about user stories, acceptance criteria, assumptions, and non-goals, then writes the file in the canonical format. Use it at the start of any feature that needs a formal spec before GSD planning.

silver:ingest — External Ingestion

/silver:ingest ingests artifacts from external sources — JIRA epics/issues, Figma files, and Google Docs — via MCP connectors. No custom API code is written; all external data access is delegated to MCP. The output is a structured INGESTION_MANIFEST that maps external inputs to spec sections.

silver:validate — Pre-Build Validation

/silver:validate performs read-only pre-build gap analysis. It reads .planning/SPEC.md plus any PLAN.md files, emits BLOCK/WARN/INFO findings, surfaces all assumptions, and writes .planning/VALIDATION.md. BLOCK findings must be resolved before implementation begins.

Related hooks enforce adjacent lifecycle guarantees:

• Spec floor check (spec-floor-check.sh) — verifies the SPEC.md meets minimum completeness requirements
• PR-to-spec traceability (pr-traceability.sh) — appends spec traceability after PR creation
• UAT pipeline gate (uat-gate.sh) — blocks milestone completion when UAT is missing, failing, or stale

Multi-Repo Spec Coordination

For multi-repo projects, Silver Bullet fetches the parent repo’s spec via GitHub CLI and caches it as .planning/SPEC.main.md (read-only). This gives the child repo access to the upstream spec without git submodules or repo coupling.

Artifact Review System

Silver Bullet includes a structured artifact review framework. Reviewer skills apply domain-specific quality checks to planning artifacts, and a 2-consecutive-clean-pass rule ensures artifacts are genuinely ready before they are approved.

8 Reviewer Skills

2-Consecutive-Clean-Pass Enforcement

Every artifact must pass two consecutive clean review rounds before it is approved. State is tracked per artifact in ~/.claude/.silver-bullet/review-state/ as JSON keyed by an 8-character SHA256 of the artifact’s absolute path. A new finding in any round resets the consecutive-pass counter.

Configurable Review Depth

Each artifact type can be configured for deep, standard, or quick review depth in .planning/config.json. Standard is the default and is backward-compatible. Deep adds additional structural and consistency checks. Quick reduces the check set for low-risk or time-sensitive reviews.

Review Analytics

Silver Bullet emits structured metrics from the review loop. Every review round appends a JSON Lines record to a metrics file — no configuration required.

JSON Lines Metrics

Each record captures: artifact type, review depth, round number, pass/fail result, finding categories, and timestamp. The metrics file accumulates across sessions, giving you a long-running history of artifact quality.

silver:review-stats Reports

Run /silver:review-stats to generate three summary tables from the accumulated metrics:

• Pass rates by artifact type — what percentage of review rounds pass cleanly
• Rounds to clean pass — how many rounds artifacts typically need before approval
• Finding categories by artifact type — which QC checks fire most frequently

Verification-Before-Completion in Review Loop

The review loop enforces that verification completes before any completion claim is recorded. This mirrors the workflow-level gsd:verify-work gate but applies specifically to the artifact review cycle — an artifact cannot be declared approved without confirmed verification in the review record.

Cross-Artifact Consistency

Silver Bullet includes a cross-artifact consistency reviewer that validates alignment across the full planning artifact chain in a single pass. It is wired into milestone completion and the release workflow — misaligned artifacts block shipping.

What Is Validated

• SPEC ↔ REQUIREMENTS — every requirement traces back to a SPEC user story; every SPEC story has at least one requirement
• REQUIREMENTS ↔ ROADMAP — every requirement is assigned to a phase; no phase references non-existent requirements
• ROADMAP ↔ DESIGN — where a DESIGN.md exists, its components cover the interfaces described in the roadmap phases

The DESIGN check (QC-3) is fully conditional — it is skipped with an XART-I01 INFO notice when no DESIGN.md is present. Misalignment findings block completion until resolved.

Where It Runs

The cross-artifact reviewer fires at two points: Step 17b in silver:feature (after artifact review gates, before milestone audit) and Step 7 in silver:release (after /gsd:ship and before gsd:complete-milestone).

Composable Workflow Orchestration

Silver Bullet's composable flows architecture replaces fixed pipelines with a catalog of 18 named paths. When you invoke /silver, it classifies context and dynamically composes a chain of flows appropriate to the work — with the active per-instance tracker .planning/workflows/<id>.md providing real-time tracking of every active composition.

Routing Logic

/silver is the dynamic composition entry point for Silver Bullet work. It classifies complexity and intent, then composes the appropriate path from SB workflows, GSD commands, and supporting plugin skills. In runtimes that support prompt interception, plain work requests may be routed through this layer; explicit /silver invocation remains the portable path.

Operational Efficiency

Silver Bullet's efficiency comes from composing the smallest safe workflow for the task. Small and bounded work routes through /silver:fast, fuzzy work routes through clarification or spec creation, DevOps work gets blast-radius and IaC gates, and release work gets finalization checks. Model routing is delegated to the active host and GSD configuration; the historical ensure-model-routing.sh hook is disabled.

Verification Before Completion

gsd:verify-work is a non-skippable gate that runs before any workflow completes. It is a §3 rule — it cannot be waived via §10 preferences or the step-skip protocol. "Done" means tests pass and behavior is confirmed, not just that code was written.

User Workflow Preferences

§10 of silver-bullet.md stores per-project routing preferences — permanent step skips, lightweight alternative substitutions, and workflow customizations recorded after using the step-skip protocol. Changes are always written to both silver-bullet.md and templates/silver-bullet.md.base atomically.

Session Startup

At the start of every new session, Silver Bullet loads the SB contract, relevant project context, session state, active workflow state, and update checks before project work begins. This is the §0 startup sequence.