Skip to content

robertraf/rob-agent-workflow

BranchesTags

Repository files navigation

rob-agent-workflow

Spec Driven Development skills for Claude Code — from ambiguous requirement to merged PR.

A set of Claude Code skills implementing Spec Driven Development (SDD) — a methodology that eliminates ambiguity before code gets written. Language and framework agnostic.

Why SDD?

AI coding agents don't fail because the model is weak. They fail because the instructions are ambiguous.

When you tell an agent "add a feature to manage items from the backoffice," it has to guess: which backoffice, which API contract, which authorization model, which error handling strategy. Each guess is a silent decision. Some are right. Some are wrong.

SDD fixes this by separating what to build from how to build it, then breaking work into self-contained tasks:

Specify → Plan → Tasks → Implement → Review → Ship → Close-loop

By the time the agent writes code, it has everything it needs. No guessing. After merge, a final close-loop phase archives lessons into a per-repo knowledge base so the next feature starts smarter.

Skills Overview

Core SDD Pipeline

Phase Skill What it does
1 /spec Functional specification — WHAT to build. Given/When/Then acceptance criteria. Technology-agnostic.
2 /plan Technical plan — HOW to build it. Reads the codebase. Architecture decisions, testing strategy.
3 /tasks Task breakdown — DIVIDE. Small, ordered, self-contained tasks. Creates GitHub issue + branch via gh.
4 /implement TDD implementation — BUILD. Red → Green → Refactor, one task at a time.
5 /review Code review — CHECK. Bugs, security, performance, conventions before shipping.
6 /ship Commit + push + PR — DELIVER. Conventional commits. PR via gh pr create. Optional wiki preliminary ingest.
7 /sdd:wiki-close-loop Post-merge CLOSE-LOOP. Archive review findings and lessons learned into the repo wiki. Manual by design.

Use /sdd:run to orchestrate phases 1-6 in a single pipeline with quality gates. Phase 7 stays manual — nothing is written to the wiki without explicit confirmation.

/ship is not terminal. The PR is a live artifact until merge. Review feedback, CI failures, and post-review commits are expected between /ship and the actual merge.

sequenceDiagram
    actor User
    participant Spec as /spec
    participant SR as spec-reviewer
    participant Plan as /plan
    participant PR as plan-reviewer
    participant Tasks as /tasks
    participant Impl as /implement
    participant Review as /review
    participant Ship as /ship

    User->>Spec: User story or PRD
    Spec->>User: Functional specification
    User-->>SR: Review spec (optional)
    SR-->>User: Issues / Ready
    rect rgb(255, 245, 230)
        Note over User,Spec: Gate: User approval
    end

    User->>Plan: Approved spec
    Plan->>User: Technical plan
    User-->>PR: Review plan (optional)
    PR-->>User: Issues / Ready
    rect rgb(255, 245, 230)
        Note over User,Plan: Gate: User approval
    end

    User->>Tasks: Approved plan
    Tasks->>User: Task list + GitHub issue + branch
    rect rgb(255, 245, 230)
        Note over User,Tasks: Gate: User approval
    end

    User->>Impl: Task list
    loop Each task
        Impl->>Impl: Red → Green → Refactor
    end
    Impl->>User: All tests passing

    User->>Review: Review changes
    Review->>User: Verdict + issues

    User->>Ship: Ship it
    Ship->>User: Committed + PR created
    Ship-->>User: Ingest spec/plan/tasks to .wiki/? (optional)

    Note over User,Ship: PR is live — review, CI, post-review commits happen here

    User->>User: PR merges
    User-->>User: /sdd:wiki-close-loop (optional, post-merge)
Loading

Knowledge Base (Wiki)

A per-repo .wiki/ directory accumulates high-value SDD artifacts so future sessions consult prior work instead of rediscovering context. Everything is opt-in — the wiki is never written without explicit user confirmation.

Skill What it does
/sdd:wiki-ingest Write SDD artifacts to .wiki/. --preliminary (spec/plan/tasks) or --final (review findings/lessons). Delegated from /ship and /sdd:wiki-close-loop.
/sdd:wiki-close-loop Post-merge: gather review comments + post-review commits via gh, then write final pages cross-linked to the preliminary entries.

/spec and /plan automatically consult the wiki before interviewing the user — if a matching prior spec or plan exists, it is surfaced for reuse. Absence of .wiki/ is a graceful no-op. See .claude/rules/wiki-conventions.md for the full schema.

Migration Workflow

Skill What it does
/migrate Scan → analyze → migrate files from one pattern to another
/review-migration Validate completed migrations: residual check, tests, build, quality report

Utility

Skill What it does
/sync-config Detect project type → compare CLAUDE.md against templates → sync across projects

Agent Teams

Requires CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS to be enabled.

Skill What it does
/team-review Parallel multi-perspective code review. Spawns specialized reviewers (security, performance, tests, conventions) that challenge each other's findings.
/team-implement Parallel task implementation. Each teammate owns independent tasks and follows strict TDD. No two teammates edit the same file.
/team-debug Competing-hypothesis debugging. Multiple investigators test different theories simultaneously and debate to converge on the root cause.

Quality Gate Agents

Subagents that provide adversarial review at pipeline gates. They run on Sonnet for fast, focused feedback.

Agent Model Purpose Used after
spec-reviewer Sonnet Reviews specs for completeness, ambiguity, missing edge cases /spec
plan-reviewer Sonnet Reviews plans against the codebase for feasibility and correctness /plan

Installation

Prerequisites

  • Claude Code installed
  • gh CLI authenticated (gh auth login)

Install as plugin

This repo is its own Claude Code marketplace (.claude-plugin/marketplace.json at the root). Add the marketplace, then install the sdd plugin.

From inside Claude Code (slash commands):

/plugin marketplace add h4b-dev/rob-agent-workflow
/plugin install sdd@rob-agent-workflow

From the CLI:

claude plugin marketplace add h4b-dev/rob-agent-workflow
claude plugin install sdd@rob-agent-workflow            # default scope: user
# or scope it to the current project / workspace:
claude plugin install sdd@rob-agent-workflow -s project
claude plugin install sdd@rob-agent-workflow -s local

Scopes:

  • user (default) — available in every project for this OS user.
  • project — committed via .claude/ for the current repo.
  • local — tied to a specific checkout, not shared.

Or test locally during development without installing:

claude --plugin-dir /path/to/rob-agent-workflow

Skills are namespaced: /sdd:run, /sdd:spec, /sdd:plan, /sdd:implement, etc.

Update the plugin

The plugin follows semver; .claude-plugin/plugin.json is bumped on every feature release. Run:

# update this plugin (use the same scope you installed it at)
claude plugin update sdd@rob-agent-workflow -s <user|project|local>

# or update everything at once
claude plugin update

Check the installed scope and version first if unsure:

claude plugin list

Restart Claude Code after an update for the new skills to load.

Enable / disable

A plugin can be installed but inactive. claude plugin list shows Status: ✘ disabled in that case — Claude Code will not load its skills until you enable it:

claude plugin enable sdd@rob-agent-workflow -s <scope>
claude plugin disable sdd@rob-agent-workflow -s <scope>

Recommended settings

Plugins cannot ship permissions or environment variables. Add these to your project or user settings.json for a smoother experience:

{
  "permissions": {
    "allow": [
      "Bash(gh issue:*)",
      "Bash(gh pr:*)",
      "Bash(gh api:*)",
      "Bash(git checkout:*)",
      "Bash(git add:*)",
      "Bash(git commit:*)",
      "Bash(git push:*)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git push --force *)",
      "Bash(git reset --hard *)",
      "Bash(git rebase -i *)"
    ]
  },
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Note: The plugin ships an automatic PreToolUse hook that blocks git push --force, git reset --hard, git add ., and --no-verify. The deny rules above are a defense-in-depth complement. The CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS env var is required for /sdd:team-* skills.

Uninstall

From inside Claude Code:

/plugin uninstall sdd@rob-agent-workflow

From the CLI (pass the scope it was installed at):

claude plugin uninstall sdd@rob-agent-workflow -s <user|project|local>

# optionally remove the marketplace entry too
claude plugin marketplace remove rob-agent-workflow

Pass --keep-data to preserve the plugin's persistent data under ~/.claude/plugins/data/.

Usage

Full SDD Pipeline

/sdd:run

As a user, I want to authenticate with my Google or GitHub account
so that I can access the platform without creating a separate password.

The agent runs all 6 phases with quality gates. User approval required after spec, plan, and tasks.

flowchart TD
    Start(["/sdd:run + user story"]) --> Spec["/spec — Write specification"]
    Spec --> SpecReview{"spec-reviewer\n(optional)"}
    SpecReview --> SpecGate{User approves spec?}
    SpecGate -- No --> Spec
    SpecGate -- Yes --> Plan["/plan — Technical plan"]
    Plan --> PlanReview{"plan-reviewer\n(optional)"}
    PlanReview --> PlanGate{User approves plan?}
    PlanGate -- No --> Plan
    PlanGate -- Yes --> Tasks["/tasks — Break into tasks + GitHub issue"]
    Tasks --> TaskGate{User approves tasks?}
    TaskGate -- No --> Tasks
    TaskGate -- Yes --> TeamChoice{Use agent team?}
    TeamChoice -- Yes --> TeamImpl["/team-implement — Parallel TDD"]
    TeamChoice -- No --> Impl["/implement — Sequential TDD"]
    TeamImpl --> Review["/review — Code review"]
    Impl --> Review
    Review --> ReviewGate{Issues found?}
    ReviewGate -- Yes --> Impl
    ReviewGate -- No --> Ship["/ship — Commit + PR"]
    Ship --> Done([PR created])
Loading

Individual Phases

Use individual skills when you don't need the full pipeline:

/spec <paste PRD or user story>    # Just write the spec
/plan                              # Just create the technical plan
/tasks                             # Just break into tasks + create issue
/implement                         # Just implement with TDD
/review                            # Just review code before shipping
/ship                              # Just commit + push + PR

When to use what

Situation Use
New feature from scratch /sdd:run
Complex multi-file change /sdd:run
Already have a spec from PM Start at /plan
Already have a plan Start at /tasks
Quick bug fix /implement → /review
Config change /ship directly
Pre-ship sanity check /review directly
Batch migration /migrate → /review-migration
Archive lessons after merge /sdd:wiki-close-loop
New feature in a repo with prior work /sdd:run (Step 0 of /spec and /plan will surface relevant wiki pages)
Large or critical PR /team-review
3+ independent parallel tasks /team-implement
Bug with multiple possible causes /team-debug

Migration

/migrate convert all deprecated_api calls to new_api in src/

Then validate:

/review-migration deprecated_api src/

sequenceDiagram
    actor User
    participant Migrate as /migrate
    participant ReviewMig as /review-migration

    User->>Migrate: Pattern + scope
    Migrate->>Migrate: Scan for matches
    Migrate->>User: Migration plan (files, transforms)
    User->>Migrate: Approve

    loop Each batch of files
        Migrate->>Migrate: Apply transforms
        Migrate->>Migrate: Run tests
    end
    Migrate->>User: Migration complete

    User->>ReviewMig: Validate migration
    ReviewMig->>ReviewMig: Check for residual old pattern
    ReviewMig->>ReviewMig: Run full test suite + build
    ReviewMig->>User: Quality report
Loading

Agent Teams Workflow

Agent teams coordinate multiple Claude Code instances working in parallel. Each team has a lead that spawns teammates, monitors progress, synthesizes results, and cleans up.

flowchart TD
    subgraph team-review["/team-review"]
        TR_Lead[Lead: Gather scope] --> TR_Spawn[Spawn reviewers]
        TR_Spawn --> TR_Sec[Security reviewer]
        TR_Spawn --> TR_Perf[Correctness & performance]
        TR_Spawn --> TR_Test[Tests & conventions]
        TR_Sec --> TR_Synth[Lead: Synthesize report]
        TR_Perf --> TR_Synth
        TR_Test --> TR_Synth
    end

    subgraph team-implement["/team-implement"]
        TI_Lead[Lead: Analyze dependencies] --> TI_Spawn[Spawn implementers]
        TI_Spawn --> TI_A[Teammate A: Tasks 1-3]
        TI_Spawn --> TI_B[Teammate B: Tasks 4-6]
        TI_Spawn --> TI_C[Teammate C: Tasks 7-9]
        TI_A --> TI_Verify[Lead: Full test suite]
        TI_B --> TI_Verify
        TI_C --> TI_Verify
    end

    subgraph team-debug["/team-debug"]
        TD_Lead[Lead: Form hypotheses] --> TD_Spawn[Spawn investigators]
        TD_Spawn --> TD_H1[Investigator: Hypothesis A]
        TD_Spawn --> TD_H2[Investigator: Hypothesis B]
        TD_Spawn --> TD_H3[Investigator: Hypothesis C]
        TD_H1 <-.->|Challenge findings| TD_H2
        TD_H2 <-.->|Challenge findings| TD_H3
        TD_H1 --> TD_Report[Lead: Root cause report]
        TD_H2 --> TD_Report
        TD_H3 --> TD_Report
    end
Loading

TDD Cycle

Every /implement and /team-implement task follows strict TDD:

flowchart TD
    Start([Pick next behavior]) --> Red[RED: Write failing test]
    Red --> Green[GREEN: Minimal code to pass]
    Green --> Refactor[REFACTOR: Clean up]
    Refactor --> More{More behaviors?}
    More -- Yes --> Start
    More -- No --> Done([All tests green])
Loading

Skill Structure

Each skill follows the Claude Code skills format with YAML frontmatter:

skills/{skill-name}/
├── SKILL.md                 # Main skill with frontmatter + instructions
├── scripts/                 # Helper shell scripts (optional)
└── references/              # Reference documents (optional)

Quality gate agents live in a separate directory:

agents/{agent-name}.md       # Agent definition with frontmatter

Frontmatter enables auto-triggering:

---
name: skill-name
description: >
  What it does. Trigger phrases. Negative triggers.
metadata:
  author: roberto-ramirez
  version: 1.0.0
  category: sdd
  tags: [relevant, tags]
---

Contributing

  1. Fork and create a branch: feat/{issue}-{description}
  2. Add or update a skill under skills/{skill-name}/SKILL.md
  3. Include YAML frontmatter with name, description (trigger + negative triggers), and metadata
  4. Keep skills language and framework agnostic
  5. For agent team skills, follow conventions in .claude/rules/agent-teams.md (file ownership, team sizing, cleanup)
  6. Test with claude --plugin-dir .
  7. Submit a PR

References

About

AI-assisted development process

Resources

Readme
Activity

Stars

4 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages