g-sdd

G's SDD

A spec-driven development pipeline for AI coding agents.

Turn product ideas into implementable vertical slices through a structured pipeline: PRD → Plan → Tasks → Agents Config → Implement. Run the full pipeline with a single command, or use individual stages as needed.

Quick Start

# Install (once) — from inside Claude Code
> /plugin marketplace add kgiwojno/g-sdd
> /plugin install g-sdd@kgiwojno

# In any project
cd my-project
claude
> /g-run

That's it. /g-run walks you through the entire pipeline. Skills, named subagents, and hooks are all bundled — no settings.json editing required.

Commands

Command	Purpose	Output
/g-run	Full pipeline — PRD through implementation	All artifacts
/g-prd	Create a Product Requirements Document	docs/features/[name]/PRD.md
/g-plan	Create an implementation plan with vertical slices	docs/features/[name]/PLAN.md
/g-tasks	Generate self-contained tasks from plan	docs/features/[name]/TASKS.md
/g-agents	Generate agent operating manual	AGENTS.md
/g-implement	Execute tasks via subagents with dashboard	reports/
/g-fix	Fix bugs in an isolated branch	docs/fixes/
/g-adr	Audit and manage Architecture Decision Records	docs/adr/
/g-qa	Aggregate slice and review reports into a post-implementation QA report	docs/features/[name]/qa-report.md
/g-setup	Initialize project directory structure	docs/ directories
/g-review	Per-change review gate (internal — invoked by /g-implement and /g-fix, not user-facing in v1)	review-reports/[NN]-[slug].md

Use /g-run for new features end-to-end. Use individual commands to re-run a stage, resume implementation, or use a stage standalone. /g-review is listed for discoverability but not intended for direct invocation — the orchestrator calls it automatically.

Install / Update / Uninstall

G's SDD ships as a Claude Code plugin. The repo is both the plugin and its marketplace, so one marketplace add is all the setup you need. Run these inside a Claude Code session:

# Install (once per machine)
> /plugin marketplace add kgiwojno/g-sdd
> /plugin install g-sdd@kgiwojno

# Update (when you want)
> /plugin marketplace update kgiwojno    # refresh the catalog
> /plugin update g-sdd                # pull the latest

# Uninstall (removes skills, agents, AND hooks)
> /plugin uninstall g-sdd

SSH errors on marketplace add? The owner/repo shorthand clones over SSH (git@github.com). If you don't have SSH keys registered with GitHub, either add an SSH key or use the full HTTPS URL to force HTTPS cloning:

> /plugin marketplace add https://github.com/kgiwojno/g-sdd.git
> /plugin install g-sdd@kgiwojno

Installing enables everything the plugin bundles — the /g-* skills, the four named subagents (g-implementer, g-reviewer, g-architect, g-qa-aggregator), and the hooks (g-sdd-pretooluse.sh guardrail + g-sdd-cost.sh capture on 11 events). The hooks auto-register via hooks/hooks.json — you no longer paste a snippet into ~/.claude/settings.json.

Versioning. plugin.json carries a SemVer version. Bump it to publish a release: patch for docs/fixes, minor for a new skill or additive behaviour, major for a breaking command-surface change. /plugin marketplace update kgiwojno then /plugin update g-sdd pulls it; enable auto-update on the marketplace to make updates zero-touch.

Two update caveats.

• No "update available" nag — Claude Code doesn't notify you when a plugin is stale; enable auto-update or run /plugin marketplace update kgiwojno periodically.
• Hook changes need an explicit update + relaunch — per upstream Claude Code issue #52218, marketplace auto-update does not refresh plugin-bundled hooks. When a release touches anything under hooks/, run /plugin update g-sdd and relaunch; release notes flag such changes.

Enable auto-update

Auto-update is per-marketplace and off by default for third-party marketplaces like this one. Turn it on either way:

• In the menu: /plugin → Marketplaces → select kgiwojno → Enable auto-update.

• In settings.json (copy-paste, any scope) — add autoUpdate to the marketplace entry:

  {
    "extraKnownMarketplaces": {
      "kgiwojno": {
        "source": { "source": "git", "url": "https://github.com/kgiwojno/g-sdd.git" },
        "autoUpdate": true
      }
    }
  }
  

With it on, Claude Code updates the plugin at start-up. But per the hook caveat above (#52218), auto-update does not refresh bundled hooks — a release that touches hooks/ still needs an explicit /plugin update g-sdd + relaunch.

Managing from the terminal (no menu)

/plugin inside a session opens an interactive, arrow-driven manager. To manage the plugin without the menu, use the claude plugin CLI from your shell — it runs non-interactively:

claude plugin list
claude plugin update g-sdd
claude plugin uninstall g-sdd
claude plugin marketplace update kgiwojno

This applies only to managing the plugin — it doesn't change how the /g-* pipeline commands work. You invoke those in-session as usual, including their interactive prompts (e.g. the /g-implement dashboard). Prefer the menu for plugin management too? /plugin stays fully supported — the CLI is just an option.

Private repo?

The repo does not need to be public — anyone with read access can install. Mind the clone transport, though: the owner/repo shorthand clones over SSH, so it needs an SSH key registered with GitHub. If you authenticate over HTTPS instead (a gh token or a git credential helper), add the marketplace by its HTTPS URL (see the SSH-errors note above) — that path uses your HTTPS credentials and needs no SSH key.

Local development / dogfooding

To iterate on the pipeline itself without pushing, point the marketplace at your working copy and reload after edits:

> /plugin marketplace add ./           # from the repo root
> /plugin install g-sdd@kgiwojno
> /reload-plugins                       # after editing skills/hooks

Migrating from a copy-based install

Earlier versions installed by copying into ~/.claude/{skills,agents,hooks}/ with a manual settings.json hook registration. If you have that, remove it before installing the plugin — otherwise every hook fires twice (duplicate cost rows). See MIGRATION.md for the clean-up sequence. install.sh has been removed — the sanctioned paths are now the plugin (users) and claude --plugin-dir . (contributors).

Pipeline Flow

Step 0: Initialize project (once per project)

Terminal:  cd my-project && claude
Claude:    /g-setup

/g-setup requires a git repository. If the project isn't a git repo yet, it runs git init for you and asks you to fully restart Claude Code before scaffolding (Claude Code caches the pre-init git state for the session, so a restart is needed to detect the new repo). After restarting, re-run /g-setup to scaffold.

On a git-backed project, /g-setup reads its bundled manifest.txt (resolved via ${CLAUDE_SKILL_DIR}, so it works whether g-sdd is installed as a plugin or copied into ~/.claude/skills/) and creates docs/templates/, docs/features/, and docs/adr/, seeding the bundled templates. The scaffolding commit is chore: initialize SDD pipeline scaffolding on a fresh repo or chore: refresh SDD pipeline templates on re-runs. /g-run invokes /g-setup automatically if needed.

Step 1: Create PRD

Claude:    /g-run  (or /g-prd standalone)

/g-prd refuses to run unless /g-setup has been completed — it checks that .git/ and docs/templates/ both exist and otherwise stops with "Project not set up for the g-sdd pipeline. Run /g-setup first."

• You describe the problem and ideas
• Skill proposes a feature name (e.g. "user-auth"), you approve
• Creates and checks out the feature branch (named {feature-name} — no feat/ prefix; base auto-detected via origin/HEAD, fallback main)
• Creates docs/features/user-auth/ on that branch
• Explores the codebase (skips if greenfield)
• Interviews you relentlessly — recommends answers, you confirm or push back, informed by codebase findings
• Sketches modules (deep vs shallow, which need tests)
• Writes docs/features/user-auth/PRD.md

Step 2: Create Plan

Claude:    (automatic in /g-run, or /g-plan standalone)

• Reads the PRD, explores codebase (technical patterns focus)
• Interviews you on durable technical decisions — starts from PRD decisions, confirms/refines/expands
• Drafts vertical slices — each is a thin end-to-end path through every layer, demoable on its own
• Quizzes you on the breakdown (title, stories, AC per slice)
• Writes docs/features/user-auth/PLAN.md

Step 3: Generate Tasks

Claude:    (automatic in /g-run, or /g-tasks standalone)

• Reads PLAN.md + PRD.md
• Generates one self-contained task per vertical slice
• Each task includes: Context, What to build, Given/When/Then AC, HITL/AFK type, dependencies, Status: Pending
• Flags ambiguity — proposes recommendation, you decide
• Presents draft for review
• Writes docs/features/user-auth/TASKS.md

Step 4: Generate Agent Config

Claude:    (automatic in /g-run, or /g-agents standalone)

• Reads PLAN.md + PRD.md + codebase conventions
• Generates AGENTS.md with conventions, boundaries, workflow
• Includes brief rationale for non-obvious decisions
• Presents for review
• Writes AGENTS.md to project root

Step 5: Implement

Claude:    (automatic in /g-run, or /g-implement standalone)

/g-prd already created the feature branch (named {feature-name} — no feat/ prefix). /g-implement runs against the existing branch: it verifies the current branch matches the feature branch, switches to it if not, and stops if the branch is missing (telling you to run /g-prd first). Then it shows an interactive dashboard:

Feature: user-auth
Branch:  user-auth
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  1. Registration       ● Pending    AFK  (unblocked)
  2. Login              ○ Pending    AFK  (blocked by #1)
  3. Password Reset     ○ Pending    AFK  (blocked by #1)
  4. OAuth              ○ Pending    HITL (blocked by #2)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
4 of 4 tasks remaining

Commands: next | run N | skip N | auto | auto --parallel | status N | stop

Three execution modes:

• Manual (next / run N): pick tasks one at a time
• Auto (auto): sequential execution in dependency order — recommended when all tasks are AFK
• Auto parallel (auto --parallel): concurrent execution in waves, merged in order (beta)

Each agent runs in an isolated git worktree on a child branch named {feature-name}-slice-NN-{slug}. On completion, the slice is squash merged into the feature branch — one clean commit per slice. Child branches stay local; the only remote surface is the single feature PR ({feature-name} → base) created at wrap-up.

For each task:

• HITL tasks: discusses what needs your input first
• Spawns an independent subagent in an isolated worktree
• Subagent receives: task + AGENTS.md + codebase access
• Subagent implements, tests, commits, writes slice report
• Orchestrator runs the per-slice review gate (/g-review) against the slice diff before merging; severe findings loop back to the author for rework
• Orchestrator squash merges, reads report, updates dashboard
• Friction (Blocked/REVIEW REQUIRED)? Pauses for human, then resumes automatically
• After all slices: runs /g-adr audit, then /g-qa aggregates slice and review reports into a single QA report, and finally offers to create the PR

Task statuses: Pending → In Progress → Complete | Blocked | Skipped

Fix bugs

Claude:    /g-fix

When bugs are discovered after implementation:

• Describe one or more bugs
• Skill associates them with features (if possible)
• Creates a fix branch, works through bugs one by one
• Each fix runs in an isolated worktree with its own agent
• Fix reports track root cause, changes, and ADR impact
• When all bugs are resolved, merge fix branch back

Step 6: Next feature

Claude:    /g-run  (or /g-prd for new feature)

New feature name → new directory → full cycle repeats. Previous feature's docs preserved. AGENTS.md accumulates.

Project Structure

After running the pipeline on two features:

my-project/
  AGENTS.md                              ← project-wide
  CONTEXT.md                             ← domain glossary (seeded once)
  docs/
    templates/
      context-format.md
      slice-report.md
      adr.md
      fix-report.md
      review-report.md
      qa-report.md
    adr/                                 ← Architecture Decision Records
      0001-use-postgresql.md
      0002-rest-over-graphql.md
    fixes/                               ← bug fix reports
      fix-login-redirect/
        01-session-cookie.md
        review-reports/
          01-session-cookie.md
    features/
      user-auth/                         ← feature 1 (complete)
        PRD.md
        PLAN.md
        TASKS.md
        qa-report.md
        reports/
          slice-01-registration.md
          slice-02-login.md
          slice-03-password-reset.md
          slice-04-oauth.md
        review-reports/
          slice-01-registration.md
          slice-02-login.md
          slice-03-password-reset.md
          slice-04-oauth.md
      listings/                          ← feature 2 (in progress)
        PRD.md
        PLAN.md
        TASKS.md
        reports/
          slice-01-create-listing.md
        review-reports/
          slice-01-create-listing.md

Key Principles

Vertical slices over horizontal layers. Each slice delivers a complete, demoable feature end-to-end (schema, API, UI, tests). Not "all database tables first, then all APIs."

Self-contained tasks. Each task includes all context the implementing agent needs. No cross-referencing other documents. The implementing agent sees only: task + AGENTS.md + codebase.

Independent agents. Each task is executed by a fresh subagent with its own isolated context window. Less context = less hallucination, more focused execution.

Durable decisions only in the plan. No file names, no function signatures — things that change during implementation stay out. The implementing agent figures them out in context.

Per-feature isolation. Each feature gets its own directory with its own PRD, plan, tasks, and slice reports. Parallel development is possible. AGENTS.md is the only shared artifact.

Slice reports for feedback. After each slice, the agent writes a completion report with suggested doc updates. Friction points prompt for lessons learned to improve the pipeline over time.

Cost tracking (capture-side, iteration 1)

The plugin bundles a cost-capture hook (g-sdd-cost.sh) that records one JSONL row per Claude Code hook event to a per-project log at $CLAUDE_CONFIG_DIR/cost-logs/[project-slug].jsonl (default ~/.claude/cost-logs/). It's observer-class — it never blocks a tool call and never exits non-zero. The /g-cost consumer skill that turns those logs into per-feature / per-slice / per-iteration reports lands in iteration 2; iteration 1 ships capture only.

For the mental model, the captured-field list, debug toggles, and known limitations (including parent-session cost), see the companion doc hooks/g-sdd-cost.md.

Customization

Global skills can be overridden per-project by creating a local copy in your project's .claude/skills/ directory. Claude Code resolves local skills before global ones.

Documentation

• Changelog — release notes
• Migration guide — moving from the copy-based install
• Pipeline Design Rationale — why the pipeline works the way it does

License

MIT