The Structured Agentic Development Workflow

A pragmatic approach to building complex software with autonomous AI agents. This methodology shifts the developer's role from Individual Contributor to Engineering Manager, focusing on deterministic outcomes, architectural integrity, and continuous improvement.

The Philosophy: Beyond "Vibe Coding"

Working with LLMs for software development often devolves into "vibe-based coding"—you ask for a massive feature, the AI hallucinates a messy implementation, breaks existing dependencies, and you spend the next three hours in debugging hell.

The Structured Agentic Development Workflow treats the AI not as a magical junior developer who can read your mind, but as an incredibly fast, highly capable engineer that lacks object permanence. To get senior-level results, you must provide a rigid scaffolding of context, constraints, and deterministic planning.

The Trade-offs

Benefits:

• Architectural Integrity: You get maintainable, predictably structured code instead of a patchwork of different styles.
• Near-Zero Regressions: Because changes are isolated and tested phase-by-phase, bugs are caught instantly.
• Elimination of "Vibe-Lost" Time: You spend less time untangling spaghetti code and more time in active, forward-moving development.
• Role Elevation: You operate as a Tech Lead defining the "what" and "how," delegating the keystrokes to the agent.

Drawbacks:

• Higher Token Consumption: Planning and context-loading consume significantly more tokens (and therefore money) than zero-shot coding.
• Higher Active Involvement: You cannot simply prompt "build the app" and walk away. This workflow demands your constant attention as a reviewer and decision-maker.

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:

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:

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

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:

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