Lightweight spec-driven development for AI coding agents.

"I have a feature idea" → and then? → clarify → and then? → spec → and then? → exec-spec → and then? → review → ship it.

AndThen brings spec-driven development to AI coding agents – lightweight, open, and adoptable piece by piece. The core idea: write a spec before you code, then let the agent execute it autonomously. The pipeline produces a Feature Implementation Specification (FIS) as its central artifact – a structured blueprint that turns requirements into reliable, verifiable implementations.

Gentle adoption, not rigid process. Use the full pipeline or just the parts you need – quick-implement skips specs entirely, clarify is optional, every skill works standalone. AndThen is opinionated about how work flows from clarified requirements to detailed specs, then exec-spec, then review, then remediate-findings when review turns up real gaps; multi-story plans follow the same underlying loop story-by-story, with exec-plan available when you want that flow orchestrated for you (add --team for Agent Teams parallelism). Under the hood, review routes to the right specialist review (review-code, review-doc, or review-gap) for the actual target. Skills read a lightweight Document Index in your CLAUDE.md to find where specs, plans, and docs live – adapting to your project's structure rather than imposing its own. No mandatory directory layouts, no proprietary formats, no lock-in.

Works as a Claude Code plugin with full sub-agent orchestration, and skills are designed to be agent-agnostic – falling back to direct execution when sub-agents aren't available.

Get started → · Skills reference →

Most AI coding goes straight from idea to code. That works for small fixes, but complex features drift, miss requirements, and produce code that's hard to verify. Spec-driven development adds one step: write a spec first, then implement against it. The spec becomes the contract – what to build, how to verify it, and when it's done.

AndThen makes this practical for AI agents without imposing a heavy methodology. You can start with quick-implement for small tasks and reach for spec when complexity warrants it.

The central artifact. A structured document generated by spec containing everything needed for autonomous implementation:

• Requirements and acceptance criteria
• Technical approach and architecture
• File changes and dependencies
• Validation checklist

Four paths, pick the one that fits. Every step produces an artifact that the next step consumes — each step suggests the next command with the right path pre-filled.

┌─────────────────────────────────────────────────────────────────────┐
│  FEATURE WORKFLOW (single feature)                                  │
│                                                                     │
│  ┌──────────── optional pre-work ──────────────┐                    │
│  │ wireframes · design-system · trade-off      │                    │
│  └─────────────────────┬───────────────────────┘                    │
│                        │                                            │
│                        ▼                                            │
│                    [clarify] (optional)                             │
│                        │                                            │
│                        │ requirements-clarification.md              │
│                        ▼                                            │
│                     [spec] ────→ [review] (optional)                │
│                        │                                            │
│                        │ feature.md (FIS)                           │
│                        ▼                                            │
│                   [exec-spec]                                       │
│                        │                                            │
│                        │ implemented code                           │
│                        ▼                                            │
│                     [review] (optional)                             │
│                    (PASS/FAIL)                                      │
│                        │                                            │
│                        └──→ [remediate-findings] (optional)         │
│                                                                     │
│  You drive each step. [review] reports findings;                    │
│  [remediate-findings] applies validated fixes when code is the issue│
└─────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────┐
│  PLAN WORKFLOW (manual story-by-story loop)                         │
│                                                                     │
│  ┌──────────── optional pre-work ──────────────┐                    │
│  │ wireframes · design-system · trade-off      │                    │
│  └─────────────────────┬───────────────────────┘                    │
│                        │                                            │
│                        ▼                                            │
│              [clarify] (optional)                                   │
│                        │                                            │
│                        │ requirements-clarification.md              │
│                        ▼                                            │
│                     [plan] ────→ [review] (optional)                │
│                        │                                            │
│                        │ prd.md + plan.md (stories)                 │
│                        ▼                                            │
│      [spec-plan] or per-story [spec]                                │
│                        │                                            │
│                        └──→ per story: [exec-spec]                  │
│                                 └──→ optional [review]              │
│                        │                └──→ [remediate-findings]   │
│                        ▼                                            │
│                     optional final [review]                         │
│                              └──→ [remediate-findings]              │
│                                                                     │
│  You run stories yourself, in plan order, and review when needed.   │
└─────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────┐
│  PLAN WORKFLOW (automated orchestration)                            │
│                                                                     │
│   optional pre-work (see above)                                     │
│     │                                                               │
│     ▼                                                               │
│  [plan] ───→ [exec-plan]                                            │
│               │                                                     │
│               ├── [spec-plan] (per phase)                           │
│               │                                                     │
│               ├── per story: [exec-spec] → [quick-review]           │
│               │                                                     │
│               └── after all stories:                                │
│                    [review-gap] → [remediate-findings] if needed    │
└─────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────┐
│  QUICK PATH (small features / fixes)                                │
│                                                                     │
│  [quick-implement] ───→ [review] (optional)                         │
│                          └──→ [remediate-findings] (optional)       │
│                                   └──→ done (or PR)                 │
└─────────────────────────────────────────────────────────────────────┘

When to use which:

• Quick path (quick-implement): Bug fix, small feature, GitHub issue – you know what to do and it's under ~3 files
• Feature workflow (clarify → spec → exec-spec → review): Single feature with real complexity – multiple files, non-obvious requirements, needs a blueprint
• Manual plan workflow (clarify → plan → spec-plan or per-story spec → exec-spec): Multiple features, MVP, or a new project where you want explicit control story by story, with optional per-story or final review/remediation
• Automated plan workflow (clarify → plan → exec-plan): The same underlying plan flow, with spec-plan plus implementation orchestrated for you. Use --team for Agent Teams parallelism

In both plan workflows, the per-story execution step is handled by exec-spec.

Not sure? Start with quick-implement. If it feels too complex, switch to the feature workflow. See Getting Started for a full walkthrough.

Both exec-spec and quick-implement use an internal implement → verify → evaluate cycle, repeating if needed. Verification includes code review, testing, and visual validation (when applicable).

# Add marketplace
/plugin marketplace add IT-HUSET/andthen

# Install plugin
/plugin install andthen

Scope options:

/plugin install andthen --scope project   # current project only (default: user scope)

Enable auto-update (recommended): Run /plugin, go to the Marketplaces tab, select the andthen marketplace, and choose Enable auto-update.

Local install (if you have the repo cloned):

claude plugin install ./plugin

Skills use capability detection and work without the plugin infrastructure. Use the installer to export skills with andthen--prefixed names to the agent skills directory and install matching Codex custom agents:

# Install skills, references, helper scripts, and Codex agents
./scripts/install-skills.sh

# Optional overrides
./scripts/install-skills.sh --dry-run
./scripts/install-skills.sh --skills-dir ~/.agents/skills
./scripts/install-skills.sh --codex-agents-dir .codex/agents
./scripts/install-skills.sh --no-codex-agents

This exports all skills as andthen--prefixed directories (e.g., andthen-clarify/, andthen-spec/, andthen-review/). Plugin reference docs, shared templates, and helper scripts are also copied. By default, the installer also copies the Codex TOML agents into ~/.codex/agents/ and rewrites them to point at the installed shared references path.

Invoke with /andthen:<skill> in Claude Code, or $andthen-<skill> in Codex and other agents.

If you use a custom --skills-dir or --prefix, the installer rewrites the copied Codex agent TOML files to match that installed references path and agent name prefix automatically.

The quickest way to get started:

/andthen:init

This is the single entry point for all project types – new, partial setups, and existing codebases. It interactively generates CLAUDE.md, creates selected document types, and copies guidelines. For existing codebases, it offers to run map-codebase to auto-generate architecture, stack, and conventions documentation from code analysis.

Manual setup – if you prefer to set things up yourself, skills reference your project's CLAUDE.md for context. Add these sections:

1. Project Document Index – tells skills where to write output (specs, plans, etc.) 2. Workflow Rules, Guardrails and Guidelines – behavioral rules and development standards

See templates/CLAUDE.template.md for a starter template.

Optional project docs – The Document Index includes optional rows for State, Requirements, Roadmap, Architecture, Conventions, Learnings, and Stack documents. Starter templates for these are in templates/project-state-templates.md. You can also auto-generate Architecture, Conventions, and Stack docs from an existing codebase using /andthen:map-codebase.

exec-plan --team and review-council --team use Agent Teams for enhanced parallel multi-agent coordination with real-time inter-agent communication. Without --team, both skills use sub-agents with sequential fallback and work across all agents. To enable Agent Teams:

// ~/.claude/settings.json
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

You have a feature idea – maybe just a sentence, maybe a rough description. Here's how the pipeline works in practice.

Step 1: Clarify requirements (interactive)

/andthen:clarify "users should be able to export their data"

This starts an interactive conversation. Claude analyzes your input, identifies gaps, and asks you 3-5 targeted questions at a time – about scope, user flows, edge cases, success criteria. You answer, it asks more. Typically 2-4 rounds until requirements are solid.

Input can be anything: a sentence, a paragraph, a file path (@docs/feature-idea.md), or a GitHub issue (--issue 42).

When done, you'll have a structured requirements document:

docs/specs/data-export/requirements-clarification.md

You can also start directly from a GitHub issue:

/andthen:clarify --issue 42

Step 2a: Create a spec (single feature)

/andthen:spec docs/specs/data-export/
# Optional GitHub-first handoff:
/andthen:spec docs/specs/data-export/ --to-issue

This reads your clarified requirements, analyzes the codebase, and produces a Feature Implementation Specification (FIS) – the blueprint for autonomous implementation. No code changes happen here.

docs/specs/data-export/data-export.md

Step 2b: Or create a plan (multi-feature / MVP)

/andthen:plan docs/specs/data-export/
# Or directly from a GitHub issue:
/andthen:plan --issue 42
# Optional GitHub-first handoff:
/andthen:plan docs/specs/data-export/ --to-issue

This picks up requirements-clarification.md automatically (or fetches the GitHub issue), creates a PRD (filling any remaining gaps with a brief targeted interview), and breaks it into sequenced stories with phases and dependencies.

docs/specs/data-export/prd.md
docs/specs/data-export/plan.md

Step 3: Execute

# Single feature:
/andthen:exec-spec docs/specs/data-export/data-export.md
# Or resume from a typed GitHub FIS artifact:
/andthen:exec-spec --issue 123

# Multi-feature (manual story-by-story loop):
# Option A: generate all story specs up front
/andthen:spec-plan docs/specs/data-export/
# Or resume from a typed GitHub plan artifact:
/andthen:spec-plan --issue 456
# Option B: generate one story spec at a time
# /andthen:spec docs/specs/data-export/s01-story-name.md
/andthen:exec-spec docs/specs/data-export/s01-story-name.md
# Optional per-story review:
/andthen:review --gap-only docs/specs/data-export/s01-story-name.md
/andthen:remediate-findings <path-to-review-report>   # if review reports actionable gaps
# ...repeat for each story in plan order
# Optional final plan-level review:
/andthen:review --gap-only docs/specs/data-export/plan.md
/andthen:remediate-findings <path-to-review-report>   # if needed after final review

# Multi-feature (automated):
/andthen:exec-plan docs/specs/data-export/
# Or resume from a typed GitHub plan artifact:
/andthen:exec-plan --issue 456

# Claude Code Agent Teams for enhanced parallelism:
/andthen:exec-plan docs/specs/data-export/ --team
# Or with worktree isolation for parallel execution:
/andthen:exec-plan docs/specs/data-export/ --team --worktree

Step 4: Review

# Single feature:
/andthen:review --gap-only <path-to-fis>

# Manual per-story or final multi-feature review:
/andthen:review --gap-only <path-to-plan-or-fis>

exec-plan runs quick-review per story automatically, then a final review-gap on the whole plan. For manual review of individual stories, use review --gap-only on the FIS path.

review is the default review entrypoint. It routes to review-gap when the question is whether implementation matches requirements, to review-doc for document readiness, and to review-code for implementation-only review.

When spec, plan, review, review-gap, or review-code publish to GitHub, the issue / PR comment is a typed AndThen artifact. That means you can continue from GitHub directly:

• /andthen:exec-spec --issue <fis-issue-number>
• /andthen:spec-plan --issue <plan-issue-number>
• /andthen:exec-plan --issue <plan-issue-number>
• /andthen:remediate-findings <review-issue-url-or-pr-comment-url>

Step 5: Remediate Findings (when review returns actionable gaps)

/andthen:remediate-findings <path-to-review-report>
# Or directly from a typed GitHub review artifact:
/andthen:remediate-findings https://github.com/org/repo/issues/789
/andthen:remediate-findings https://github.com/org/repo/pull/456#issuecomment-123

This re-validates the findings against the current workspace, applies the smallest safe fixes, re-runs the relevant verification, and updates plan/FIS state when the reviewed work is now complete.

clarify is optional – but knowing when to use it saves time.

Rule of thumb: If you can't list 3 concrete acceptance criteria for the feature, run clarify first.

Both clarify and plan can do requirements discovery. The difference:

• clarify does deep, thorough discovery – design space decomposition, domain language extraction, detailed edge case analysis. It produces a standalone requirements document.
• plan has a lighter built-in discovery (Step 1b) for when you skip clarify. It focuses on getting enough information to create a PRD and break it into stories, but won't go as deep on edge cases or design alternatives.

Use clarify first when: The problem space is genuinely unclear, you're exploring multiple design directions, or the domain is complex. plan will pick up the output and skip its own discovery.

Skip clarify and let plan handle it when: You have a reasonable understanding of what you want – maybe not perfectly documented, but you could explain it in a few paragraphs. plan's lighter discovery will fill the gaps.

Invoke with /andthen:<skill> (e.g. /andthen:triage, /andthen:spec).

Use these individually for everyday development — no setup, no pipeline, no prior artifacts needed.

These compose into structured workflows — from requirements through implementation to review.

Specialist review skills remain available for explicit or internal use: review-code, review-doc, and review-gap. The recommended user-facing entrypoint is review.

Both exec-plan and review-council auto-detect Agent Teams and use them when available. Use --team to force Agent Teams mode.

Specialized sub-agents used internally by skills:

Simplified starting points – copy into your project and adapt to your needs. Workflow skills reference these via your project's CLAUDE.md, so you can replace them entirely with your own.

Optional standalone Claude Code hooks for safety and productivity. See hooks/README.md for setup.

• Agent Browser (CLI tool and Skill) - https://github.com/vercel-labs/agent-browser

• Other useful plugins from the official marketplace (anthropics/claude-plugins-official):

  • semgrep - external but officially recommended
  • playground
  • claude-md-management

AndThen evolved from cc-workflows – a general-purpose AI coding agent toolkit.

and then

Too many to list, but special shoutout to:

• Peter Steinberger
• Cole Medin
• IndieDevDan
• Matt Maher
• Mario Zechner
• Matt Pocock

MIT