Workflow Setup

Installs the development workflow layer. Requires an existing .claude/ directory — run the greenfield or brownfield skill first.

Step 1 — Preflight

Check that prerequisites exist:

ls .claude/ 2>/dev/null || echo "MISSING"
ls .claude/hooks/stop-quality-gate.sh 2>/dev/null && echo "GATE_EXISTS" || echo "GATE_MISSING"
cat .claude/settings.json 2>/dev/null | grep -q "AGENT_TEAMS" && echo "TEAMS_ENABLED" || echo "TEAMS_DISABLED"

If .claude/ is missing, stop:

"No .claude/ directory found. Run the greenfield or brownfield skill first, then re-run /workflow."

If .claude/commands/ or .claude/agents/ already have files, warn:

"Existing commands/agents will be overwritten. Continue? (yes/no)"

Step 2 — Check for Previous Configuration

Before starting the interview, check if this skill has been run before:

SKILL_NAME="workflow" \
bash "${CLAUDE_SKILL_DIR}/scripts/load-config.sh"

If the output is a non-empty JSON object (not {}), previous answers exist. Present them:

Previous workflow configuration found:

  Orchestration: [ORCHESTRATION]
  Commands:      [COMMANDS]
  Gitleaks:      [GITLEAKS]
  Semgrep:       [SEMGREP]

Would you like to:
  a) Update — reinstall all commands and agents using these settings
  b) Reconfigure — start the interview from scratch

Use AskUserQuestion and wait for the response.

If Update: load all saved values into environment variables and skip to Step 3.
If Reconfigure: proceed to the full interview below.

If no previous config exists, proceed directly to the interview.

Step 2b — Interview

Ask each question using AskUserQuestion and wait for the response before proceeding to the next question.

Question 1 — Orchestration Mode

Use AskUserQuestion with this prompt:

Setting up your development workflow.

Orchestration mode — How should /breakdown, /spec, and /work orchestrate agents?

  a) Subagents — PEE loop (recommended) — sequential Planner → Executor →
     Evaluator loop per spec on a shared branch, with one full quality pass
     at the end. One-shot subagents (no team infrastructure). Optimized for
     spec-compliance correctness. Uses opus for planner, sonnet for the
     evaluator, and haiku for the executor.

  b) Subagents — parallel — parallel workers in isolated git worktrees,
     merged by the git-expert agent. Stable, works everywhere.

  c) Agent teams (experimental) — teammates work on parallel domains of the
     codebase on a shared branch. Requires CC v2.1.32+ and
     CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS enabled.

Map the answer to the internal ORCHESTRATION value: a → loop, b → subagents, c → teams.

Question 2 — Commands

Use AskUserQuestion with this prompt:

Which commands would you like installed? (default: all)

  a) /breakdown, /spec, /work  — feature planning and implementation   ✓
  b) /commit                   — conventional commit message generator  ✓
  c) /review                   — code review of current changes         ✓
  d) /pr, /squash-pr, /address-pr-comments — pull request workflow      ✓
  e) /fix-issue                — implement a GitHub issue end-to-end    ✓
  f) /security-scan            — on-demand deep security scan           ✓
  g) /triage                   — GitHub issue analysis (requires gh)    ✓
  h) /update-skills            — find and install skills for your deps  ✓

Enter "all" or list letters to include (e.g. "a, b, d"):

Step 2c — Save Configuration

After the interview (or after loading previous config for an update), save the current answers:

SKILL_NAME="workflow" \
CONFIG_JSON='{"ORCHESTRATION":"[val]","COMMANDS":"[val]","GITLEAKS":"[val]","SEMGREP":"[val]"}' \
bash "${CLAUDE_SKILL_DIR}/scripts/save-config.sh"

Replace [val] with actual values. This writes to .claude/skill-config.json so future runs can reuse these answers.

Step 3 — Detect Quality Tools

bash scripts/detect-tools.sh

For any missing tools, list what they do and how to install them. Do NOT offer to install them automatically.

Recommended tools:

  gitleaks — Scans for accidentally committed secrets
    https://github.com/gitleaks/gitleaks#installing
    brew install gitleaks

  semgrep — SAST security scanner (injection, OWASP Top 10)
    https://semgrep.dev/docs/getting-started/
    pip install semgrep  /  brew install semgrep

  gh CLI — Required for /triage, /pr, /squash-pr, /address-pr-comments
    https://cli.github.com/
    brew install gh

The quality gate will skip checks for tools that aren't installed.

Step 4 — Install Commands and Agents

Run in parallel if subagents are available, otherwise sequential:

ORCHESTRATION="[subagents|teams|loop]" \
COMMANDS="[comma-separated approved list]" \
bash scripts/install-commands.sh

ORCHESTRATION="[subagents|teams|loop]" \
bash scripts/install-agents.sh

If gh CLI is available and /triage was approved:

bash scripts/install-triage-skill.sh

Step 5 — Verify Quality Gate

Confirm the installed .claude/hooks/stop-quality-gate.sh is the scoped, stack-aware template (gitleaks and semgrep are now built into the hook's shared security block and run only on changed files — no patching needed):

bash scripts/patch-quality-gate.sh

The script is a no-op when the hook is already the scoped template. If it detects an older unscoped hook, it prints instructions to re-run greenfield/brownfield to regenerate.

Step 6 — Patch Settings for Agent Teams (if chosen)

If orchestration = teams only (the PEE loop mode uses one-shot subagents and does not need team infrastructure):

bash scripts/patch-settings-teams.sh

Adds TaskCompleted hook to .claude/settings.json that runs format.sh and task-summary.sh. Quality gates are handled by the dedicated Quality Gate agent between groups — no teammate-quality-gate.sh is created.

Note to developer after patching:

VS Code may show schema warnings on TaskCompleted. This is a known schema lag — agent teams hooks are newer than the schema. The hooks work correctly at runtime. To suppress the warning add this to .vscode/settings.json: { "json.schemas": [{ "fileMatch": ["**/.claude/settings.json"], "schema": {} }] }

Step 7 — Commit

git add .claude/
git commit -m "chore(claude): install development workflow"

Step 8 — Completion

✅ Workflow Setup Complete

Commands installed:
  /breakdown + /spec + /work  — [subagents parallel | subagents PEE loop | agent teams] orchestration
  /commit                     — conventional commit message generator
  /review                     — code review of current changes
  /pr + /squash-pr            — pull request workflow
  /address-pr-comments        — address GitHub review comments
  /fix-issue                  — implement a GitHub issue end-to-end
  /security-scan              — on-demand deep security scan
  /triage                     — GitHub issue analysis and planning
  /update-skills              — find and install skills for project dependencies

Agents installed:
  architect                                       — plans features and architecture
  [implementer | domain-implementer | planner+executor+evaluator]  — implement specs
  quality                                         — 8-gate quality review
  git-expert                                      — worktrees, merges, verification

Quality tools:
  gitleaks: [✅ active in quality gate | ⚠️ not installed]
  semgrep:  [✅ active in quality gate | ⚠️ not installed]
  gh CLI:   [✅ installed | ⚠️ not installed — /triage, /pr, /squash-pr need this]

Agent teams hooks: [added to settings.json | not needed for this orchestration mode]

⚠️ Restart Claude Code to load the new commands and agents.

Typical workflow once restarted:
  /breakdown my-feature     — decompose into tasks
  /spec my-feature          — generate implementation specs
  /work my-feature --all    — implement with agents
  /squash-pr my-feature     — create PR

Reference Files

Commands: references/commands/
Agents: references/agents/
Triage skill: references/triage-skill.md

workflow