Installation

Quick Start (Recommended)

Install via the skills CLI — works with Claude Code, Cursor, Gemini CLI, GitHub Copilot, and 40+ other agents:

# Install workflow skills for your agent
npx skills add nikhilw/structured-agentic-workflow

# Install for a specific agent
npx skills add nikhilw/structured-agentic-workflow -a claude-code

# Install superpowers skills separately (test-driven-development, systematic-debugging, verification-before-completion)
npx skills add obra/superpowers -s test-driven-development -s systematic-debugging -s verification-before-completion

The npx skills CLI will discover all skills in the repo, let you pick which ones to install, and symlink them into your agent's skills directory.

Note: The superpowers skills (test-driven-development, systematic-debugging, verification-before-completion) live in a separate repo and must be installed separately. The workflow works without them, but they are strongly recommended — the build phase expects /test-driven-development, and the workflow enforces /verification-before-completion after every review.

We keep the upstream skill names verbatim (systematic-debugging, verification-before-completion) rather than renaming them to debug/verify. The npx skills CLI has no rename flag, so keeping the upstream names means installs via npx skills and installs via our install.sh both end up with identically-named skills.

Alternative: Install Script

If you prefer a single command that pulls superpowers and installs everything at once:

# Clone the repo
git clone https://github.com/nikhilw/structured-agentic-workflow.git
cd structured-agentic-workflow

# Install for all supported agents (pulls superpowers automatically)
./install.sh

# Or on Windows (PowerShell — requires Developer Mode or admin)
.\install.ps1

What the Install Script Does

1. Pulls superpowers skills — sparse-clones obra/superpowers (MIT-licensed) into vendor/superpowers/, then copies the adopted skills into skills/ under their upstream names.
2. Symlinks all skills into the global skills directory for each supported agent:

| Agent | Skills Directory | |-------|-----------------| | Claude Code | ~/.claude/skills/ | | Cursor | ~/.cursor/skills/ | | Gemini CLI | ~/.gemini/skills/ | | GitHub Copilot | ~/.config/github-copilot/skills/ |

Note: Cursor also reads ~/.claude/skills/ natively, so installing for Claude Code alone is sufficient if you use both.

All skills use the standard SKILL.md format supported by all four agents.

Targeting a Specific Agent

./install.sh --target claude        # Claude Code only
./install.sh --target gemini        # Gemini CLI only
./install.sh --target cursor        # Cursor only
./install.sh --target copilot       # GitHub Copilot only

Other Options

./install.sh --local                # Skip superpowers pull (use existing vendor/)
./install.sh --remove               # Remove all symlinks
./install.sh --remove --target claude  # Remove for a specific agent
./install.sh --list                 # Show agents and install status

Installed Skills

The installer symlinks these skills from the skills/ directory:

Core workflow skills:

| Skill | Source | Description | |-------|--------|-------------| | agentic-workflow | This project | Orchestrates the full development lifecycle | | workflow-config | This project | Configure workflow preferences (TDD/BDD, caveman output style) | | brainstorm | This project | Explore approaches, challenge the design, estimate impact, produce decision documents | | write-plan | This project | Write phased implementation plans | | build-phase | This project | Execute one plan phase with test + review loop | | 3p-review | This project | Independent third-person code review | | triage | This project | Recommend next task, minimize context thrash | | test-driven-development | superpowers | RED-GREEN-REFACTOR discipline | | systematic-debugging | superpowers | Systematic 4-phase root cause investigation | | verification-before-completion | superpowers | Evidence before completion claims |

Optional vendor skills (installed but not part of the workflow):

| Skill | Source | Description | |-------|--------|-------------| | brainstorming | superpowers | Interactive brainstorming with visual companion and spec review loop. Not used by the workflow — available if you prefer it over /brainstorm. |

Configuring the Workflow

The workflow supports configurable preferences via the /workflow-config skill:

/workflow-config enable caveman full
/workflow-config use bdd

Testing Methodology

• TDD (default) — Red-Green-Refactor via /test-driven-development
• BDD — Given-When-Then scenarios and feature files

Only one can be active at a time. The core rule — "test first, always" — applies regardless.

Output Style: Caveman Compatibility

The workflow integrates with the caveman brevity style. When enabled, all workflow phases adapt their prose to the requested level:

| Level | Style | |-------|-------| | off (default) | Normal verbose output | | lite | Shorter prose, all technical detail preserved | | full | Terse bullets, minimal preamble | | ultra | Maximum compression, sentence fragments |

Technical accuracy is never sacrificed — only verbosity changes.

This workflow does not bundle or vendor caveman. Caveman compatibility is built in — each skill checks memory for the configured brevity level and adapts its output independently. If you also want caveman to govern the agent's base system prompt (outside of workflow skills), install the caveman package separately.

What Cannot Be Configured

These are core workflow guarantees and cannot be disabled:

• Verification (/verification-before-completion) — always mandatory
• Phase order — Brainstorm → Plan → Build → 3p-Review → Verify
• Plan lifecycle — new/ → plans/ → done/
• Review loop — loops until clean

Preferences are persisted to agent memory and apply across sessions.

Manual Installation

If the install script doesn't work on your system, you can do it by hand. There are two steps: pulling the superpowers skills, and symlinking everything into your agent's skills directory.

Step 1: Pull Superpowers Skills

Clone the superpowers repo and copy the skills you need into skills/:

# Clone superpowers into a temp directory
git clone --depth 1 https://github.com/obra/superpowers.git /tmp/superpowers

# Copy the four adopted skills into vendor/ (for reference)
mkdir -p vendor/superpowers
cp -r /tmp/superpowers/skills/brainstorming vendor/superpowers/
cp -r /tmp/superpowers/skills/test-driven-development vendor/superpowers/
cp -r /tmp/superpowers/skills/systematic-debugging vendor/superpowers/
cp -r /tmp/superpowers/skills/verification-before-completion vendor/superpowers/
cp /tmp/superpowers/LICENSE vendor/superpowers/

# Copy into skills/ under their upstream names
cp -r /tmp/superpowers/skills/brainstorming skills/brainstorming
cp -r /tmp/superpowers/skills/test-driven-development skills/test-driven-development
cp -r /tmp/superpowers/skills/systematic-debugging skills/systematic-debugging
cp -r /tmp/superpowers/skills/verification-before-completion skills/verification-before-completion

# Clean up
rm -rf /tmp/superpowers

Step 2: Symlink Skills

Create symlinks from the skills/ directory to your agent's global skills directory. Replace ~/.claude/skills with the appropriate path for your agent (see the table above).

macOS / Linux:

mkdir -p ~/.claude/skills

# Symlink each skill
ln -sf "$(pwd)/skills/agentic-workflow" ~/.claude/skills/agentic-workflow
ln -sf "$(pwd)/skills/brainstorming" ~/.claude/skills/brainstorming
ln -sf "$(pwd)/skills/write-plan" ~/.c