AI Skills

<img src="claude-corps.png" alt="claude-corps banner" width="100%"> Parallel agentic development framework for Claude Code Turn Claude Code into an autonomous development team — multiple agents working simultaneously in isolated git worktrees, coordinated by an orchestrator, with structured workflow that improves across sessions. <a href="#quick-start">Quick Start</a> · <a href="#why-claude-corps">Why?</a> · <a href="#claude-code-skills-reference">Skills</a> · <a href="#autonomous-multi-hour-orchestration">Auto-Run</a> · <a href="#faq">FAQ</a> <a href="https://github.com/josephneumann/claude-corps/blob/main/LICENSE"><img src="https://img.shields.io/github/license/josephneumann/claude-corps" alt="License"></a> <a href="https://github.com/josephneumann/claude-corps/stargazers"><img src="https://img.shields.io/github/stars/josephneumann/claude-corps" alt="Stars"></a> <a href="https://github.com/josephneumann/claude-corps/commits/main"><img src="https://img.shields.io/github/last-commit/josephneumann/claude-corps" alt="Last Commit"></a> <img src="https://img.shields.io/badge/Claude%20Code-compatible-blueviolet" alt="Claude Code Compatible"> <img src="https://img.shields.io/badge/Agent%20Teams-supported-green" alt="Agent Teams">

Why claude-corps?

Claude Code is powerful on its own. claude-corps makes it a team.

Parallel execution — Dispatch 3-5 Claude agents working simultaneously on different tasks, each in an isolated git worktree
Full lifecycle coverage — From spec to dispatch to PR to code review, every step has a skill
Autonomous multi-hour runs — /auto-run chains dispatch, reconcile, and repeat until your entire backlog is done
Human in the loop — Agents execute, you decide. PRs are created, never auto-merged

Quick Start

Option A: Plugin Install

In Claude Code:

/plugin marketplace add josephneumann/claude-corps
/plugin install claude-corps@claude-corps

Note: Plugin install namespaces skills as /claude-corps:orient, /claude-corps:dispatch, etc. For the full un-namespaced experience with CLAUDE.md integration, use Option B.

Option B: Full Install (Recommended)

git clone https://github.com/josephneumann/claude-corps.git ~/Code/claude-corps
cd ~/Code/claude-corps && ./install.sh

This symlinks skills, agents, hooks, scripts, and docs into ~/.claude/ for un-namespaced /orient, /dispatch, etc.

Then in any project:

claude
> /orient              # Survey your project and identify parallel work
> /dispatch --count 3  # Spawn 3 agent teammates in parallel worktrees
> /auto-run            # Or go fully autonomous

The Workflow

graph LR
    A["/spec"] --> B["/spec --deepen"]
    B -.->|"refine"| A
    B --> D["/orient"]
    A --> D
    D --> E["/dispatch"]
    E --> F["Workers: /start-task"]
    F --> G["Workers: /finish-task"]
    G --> H["/reconcile-summary"]
    E -.->|"/auto-run loop"| H

Phase	What happens
Spec	`/spec` refines ideas via Q&A, researches the codebase with parallel agents, writes a plan to `docs/plans/`, and decomposes into tasks with dependencies. `/spec --deepen` adds depth with targeted parallel research.
Execute	`/orient` surveys the project. `/dispatch` spawns Agent Teams teammates — each gets a task, creates a worktree, implements, runs tests, creates a PR, and writes a session summary. `/auto-run` does this in a loop until all tasks are done.
Review	`/multi-review` runs parallel specialized code review. `/reconcile-summary` syncs worker output with the task board.

Claude Code Skills Reference

All workflow capabilities are implemented as slash commands in skills/.

Planning

Skill	Purpose
`/spec`	Research, plan, decompose into tasks with dependencies
`/spec --deepen`	Enhance an existing plan with parallel research

Execution

Skill	Purpose
`/orient`	Survey project, identify parallel work streams
`/start-task <id>`	Claim task, create worktree, gather context
`/finish-task <id>`	Tests, commit, PR, code review, session summary, close

Orchestration

Skill	Purpose
`/dispatch`	Spawn parallel Agent Teams teammates in worktrees
`/auto-run`	Autonomous dispatch-reconcile loop for multi-hour runs
`/reconcile-summary`	Sync worker output with task board
`/summarize-session <id>`	Mid-session progress checkpoint (read-only)

Quality

Skill	Purpose
`/multi-review`	Parallel code review with specialized agents
`/humanizer`	Remove AI writing patterns, add natural voice
`/verify`	Verification discipline — evidence before claims
`/debug`	Systematic debugging methodology
`/writing-skills`	Skill authoring guidance (structure, tone, persuasion)

<details> <summary>Skill details (click to expand)</summary>

Planning Skills

/spec — Interactive refinement (Phase 0) moves from a vague idea to clear requirements. Runs parallel research agents (repo-research-analyst, spec-flow-analyzer, and conditionally best-practices-researcher and framework-docs-researcher). Writes plan to docs/plans/, then decomposes into tasks with dependencies via bd create and bd dep add.

/spec --deepen — Finds the most recent plan in docs/plans/, discovers and applies all available skills, runs parallel research agents per-section, launches all review agents, and merges findings back into the plan. Updates tasks accordingly.

Execution Skills

/orient — Discovers project structure, reads CLAUDE.md/README/PROJECT_SPEC, analyzes task state, checks git health, outputs a structured orientation report with recommended parallel work streams. Always offers /dispatch as next action.

/dispatch — Identifies ready tasks, generates context, creates an Agent Teams team, and spawns teammates. Each teammate works in an isolated git worktree with full autonomy. Supports --count N, --plan-first, --no-plan, --yes, and custom per-task context.

/start-task <id> — Validates the task, claims it, creates a git worktree for isolation, gathers project context, optionally runs research agents, defines acceptance criteria, and begins implementation.

/finish-task <id> — Runs quality gates (tests must pass), commits changes, pushes to remote, creates a PR, runs /multi-review with auto-fix, closes the task, outputs a session summary. Tests must pass or the command stops.

/reconcile-summary — Auto-discovers unreconciled summaries in docs/session_summaries/, cross-references summary claims against PR/CI evidence before trusting them, analyzes spec divergences, updates affected tasks, creates new tasks for discovered work, closes obsoleted tasks. Supports --yes for autonomous operation and --no-cleanup to skip team shutdown.

/summarize-session <id> — Read-only progress snapshot. Does not commit, push, or close anything.

Quality Skills

/multi-review — Selects 3-5 review agents based on change types, runs them in parallel, aggregates findings by severity, auto-fixes high-confidence issues. Maximum 3 review cycles.

/humanizer — Writing editor that identifies and removes AI writing patterns (significance inflation, sycophantic tone, filler phrases, em dash overuse, etc.) to make text sound natural and human. Based on Wikipedia's Signs of AI writing. Outputs a draft rewrite, self-audit for remaining tells, and final revision.

Discipline Skills

/verify — Centralized verification discipline cross-referenced by other skills. Contains the Iron Law (no claims without evidence), anti-rationalization table, red flags list, verification checklist, and anti-sycophancy guidance. Inspired by obra/superpowers.

/debug — Four-phase systematic debugging: reproduce, trace root cause, test hypotheses, minimal fix. Includes three-strikes rule (3 failed fixes = wrong assumptions). Adapted from obra/superpowers.

/writing-skills — Meta-skill for authoring effective skills. Covers CSO (description design), word count targets, anti-rationalization patterns, tone guidance from the humanizer, and persuasion principles. Informed by obra/superpowers.

</details>

Autonomous Multi-Hour Orchestration

/auto-run enables fully autonomous operation. It dispatches workers, waits for completions (Agent Teams delivers messages as conversation turns), reconciles results, dispatches newly unblocked tasks, and repeats.

# All ready tasks
/auto-run

# Everything needed to complete a specific task (resolves dependency graph)
/auto-run --through Proj-xyz

# All tasks in an epic
/auto-run --epic Proj-abc

# Specific tasks plus their blockers
/auto-run --only Proj-abc Proj-def

# With limits
/auto-run --max-batches 3 --max-hours 4 --max-concurrent 5

Unattended Mode (Wrapper Script)

For runs that outlast a single context window, the wrapper script provides process-level resilience:

~/.claude/scripts/auto-run.sh --max-hours 8
~/.claude/scripts/auto-run.sh --through Proj-xyz --max-hours 4

The wrapper uses expect to allocate a pty (Agent Teams requires interactive mode), sends /auto-run --resume into each fresh Claude session, and checks task state between iterations. State is checkpointed to docs/auto-run-checkpoint.json and survives restarts.

Specialized Agents

Agent definitions in agents/ are used by skills for research and review.

Research Agents

Deployed by /orient and /start-task to gather context before implementation.

Agent	Purpose
`repo-research-analyst`	Map architecture and conventions
`git-history-analyzer`	Historical context and contributors
`framework-docs-researcher`	Library docs and deprecation checks
`best-practices-researcher`	Industry patterns and recommendations

Code Review Agents

Deployed by /multi-review for parallel specialized review.

Agent	Focus
`code-simplicity-reviewer`	YAGNI, minimize complexity
`security-sentinel`	CWE-enriched OWASP review, business logic, absence detection
`performance-oracle`	N+1 queries, memory, caching
`pattern-recognition-specialist`	Anti-patterns, conventions
`architecture-strategist`	SOLID, design alignment
`agent-native-reviewer`	Action/context parity for agents
`api-security-reviewer`	Rate limiting, pagination, CORS, response filtering
`data-integrity-guardian`	Migration safety, ACID, GDPR/CCPA
`data-migration-expert`	Validates mappings against production
`nextjs-reviewer`	App Router, RSC, metadata, routing
`tailwind-reviewer`	Tailwind/shadcn, accessibility, responsive
`python-backend-reviewer`	FastAPI, SQLAlchemy, async, Alembic, pytest

Note: Framework-specific reviewers (nextjs, tailwind, python-backend, api-security) auto-detect from changed files. Use reviewers.exclude in .claude/review.json to suppress. See Setting Up a New Project.

Workflow Agents

Agent	Purpose
`spec-flow-analyzer`	Analyze specs for dependencies, gaps, feasibility

Security

claude-corps uses a layered security model combining AI-driven review with deterministic CI/CD tooling for comprehensive coverage.

AI Agent Layer (security-sentinel)

The security-sentinel agent focuses on what AI uniquely excels at:

Business logic vulnerabilities — IDOR (CWE-639), authorization bypass (CWE-863), workflow manipulation, mass assignment (CWE-915)
Absence detection — Missing rate limiting, CSRF protection, auth middleware, input validation, security headers, audit logging
Self-verification — Every finding is tested against mitigating controls before reporting, reducing false positives
CWE-enriched output — All findings include CWE numbers, confidence scores, exploit scenarios, and specific remediation
SAST triage — When CI/CD produces SAST results, security-sentinel verifies each finding in context (confirm, dismiss, or escalate)

The api-security-reviewer agent covers API-specific gaps: rate limiting, pagination bounds, response data filtering, CORS, request size limits, and security logging.

CI/CD Layer (deterministic tools)

A template workflow at docs/examples/security-checks.yml adds SAST and container scanning alongside your existing CI:

Tool	Purpose
Semgrep	Known vulnerability patterns (SQLi, XSS, path traversal) via SAST
Trivy	CVEs in container base images and OS packages
SARIF	Results uploaded to GitHub Security tab

This complements (not replaces) existing CI checks like dependency audit (pnpm audit, pip-audit) and secret scanning (TruffleHog).

Pre-Commit Layer

A secret scanning hook (hooks/secret-scan-precommit.sh) blocks commits containing credentials before they enter git history. Uses gitleaks if installed, falls back to regex pattern matching for AWS keys, GitHub tokens, private keys, and generic secrets.

Recommended Configuration

For security-conscious projects, add security-sentinel as an always-on reviewer in .claude/review.json:

{
  "reviewers": {
    "include": ["security-sentinel"]
  }
}

How It All Fits Together

project-root/
├── CLAUDE.md                        # Project-specific config (you write this)
├── .claude/
│   ├── review.json                  # Optional: review config (tiers, reviewer overrides)
│   └── worktrees/                   # Isolated worktrees for each task
├── docs/
│   ├── session_summaries/           # Worker outputs (created by /finish-task)
│   │   └── reconciled/              # Processed by /reconcile-summary
│   ├── plans/                       # Output from /spec
│   ├── auto-run-checkpoint.json     # Auto-run state (survives restarts)
│   └── auto-run-logs/               # Wrapper iteration logs

~/.claude/                           # Global config (symlinked from this repo)
├── CLAUDE.md                        # Global workflow guidance
├── skills/                          # Slash commands
├── agents/                          # Specialized agent definitions
├── hooks/                           # Event hooks
├── scripts/                         # Wrapper scripts (auto-run.sh)
└── docs/                            # Global documentation

Principles

Parallel by default — Multiple Claude sessions work simultaneously in isolated git worktrees.
Orchestrator + Workers — One session coordinates, teammates execute discrete tasks and report back.
Task-sized work — Big enough to be a meaningful atomic change, small enough to complete without exhausting context.
Bounded autonomy — Clarify requirements first, then execute autonomously within those bounds.
Tests as the contract — "Done" means tests pass. The code proves itself.
Human in the loop — Humans approve PRs, prioritize tasks, and make architectural decisions.
Handoffs over context bloat — Fresh context beats exhausted context.
Session summaries — Every completed task leaves breadcrumbs for the next session.
Save what you learn — Save debugging insights and non-obvious solutions to auto-memory when completing tasks.
Codify the routine — Repeated patterns become skills. If you do something twice, automate it.
Evaluate, don't agree — Verify claims against evidence before acting. No performative agreement.

Workflow Examples

Single-Session

/orient
/start-task Project-abc
# implement...
/finish-task Project-abc

Multi-Agent Parallel

/orient
/dispatch --count 3
# 3 teammates spawn, each in a worktree, working in parallel
# Use Shift+Up/Down to switch between teammates
/reconcile-summary

Fully Autonomous

# Interactive
/auto-run --through target-task-id

# Unattended (hours-long, restarts across context exhaustions)
~/.claude/scripts/auto-run.sh --max-hours 8

Full Planning Pipeline

/spec "real-time price alerts for crypto"
/spec --deepen   # optional: enhance with parallel research
/orient
/dispatch

Setting Up a New Project

Global workflow config loads automatically from ~/.claude/CLAUDE.md. Each project only needs its own CLAUDE.md for project-specific details:

cd /path/to/your/project
bd init                    # Initialize task management
claude
> /orient                  # Start working

Your project CLAUDE.md should include: project summary, dev commands (uv run pytest, pnpm dev, etc.), critical rules, and architecture overview. Everything else comes from the global config.

Optionally, create a .claude/review.json to configure risk tiers and reviewer overrides. Framework-specific reviewers auto-detect from changed files — no config needed. See docs/examples/review-fullstack.json for an example.

For security-conscious projects: add "include": ["security-sentinel"] to your review config for always-on security review, and copy docs/examples/security-checks.yml to .github/workflows/ for CI/CD SAST and container scanning.

FAQ

How is this different from using Claude Code directly?

Claude Code runs as a single agent. claude-corps adds orchestration — multiple Claude sessions working in parallel on different tasks, each in isolated git worktrees, coordinated by a team lead session that dispatches work and reconciles results.

Can I run this unattended for hours?

Yes. /auto-run with the wrapper script (~/.claude/scripts/auto-run.sh) runs for hours, restarting Claude when context is exhausted. State is checkpointed and restored across restarts. PRs are created but never auto-merged — you review when ready.

Do I need beads?

Yes. beads (bd) is the task management backend. Skills use it for task tracking, dependencies, dispatch, and coordination. Run bd init in your project to set up.

What is the review config?

The review config (.claude/review.json) lets you configure per-project file sensitivity levels and reviewer overrides. It drives three behaviors: (1) /multi-review selects more reviewers for higher-risk files, (2) /dispatch uses plan-mode for critical/high-risk tasks, and (3) model selection routes critical/high tasks to Opus and medium/low to Sonnet. Framework-specific reviewers auto-detect from changed files — use reviewers.exclude to suppress false positives and reviewers.include to force always-on reviewers. Without a config file, skills fall back to keyword-based detection.

How does smart model selection work?

/dispatch automatically selects Opus for critical/high-risk tasks and Sonnet for medium/low tasks. Use --model opus or --model sonnet to override. During /multi-review, critical-tier files get Opus for security-sentinel and architecture-strategist reviews.

How does security review work?

claude-corps uses a layered model: the security-sentinel AI agent handles business logic vulnerabilities (IDOR, auth bypass, absence detection) that require understanding intent, while CI/CD tools handle deterministic checks (SAST via Semgrep, container scanning via Trivy, dependency audit, secret scanning). A pre-commit hook catches secrets before they enter git history. When SAST results are available, the AI agent triages them in context — confirming real vulnerabilities and dismissing false positives. See the Security section for setup.

Can I use this without Agent Teams?

Partially. /orient, /start-task, /finish-task, and /multi-review all work without Agent Teams. /dispatch and /auto-run require it — they spawn parallel teammates.

How claude-corps Fits the Ecosystem

Tool	What It Does	Relationship
Claude Code	Anthropic's agentic coding CLI	Required — claude-corps extends it
beads	Task management CLI with dependencies	Required — skills use `bd` for task tracking
Claude Squad	Manage multiple terminal Claude agents	Alternative approach to multi-agent
Aider	AI pair programming in your terminal	Different paradigm (pair vs team)

Prerequisites

Required

Claude Code — Anthropic's CLI for Claude
beads (bd) — Task management with dependencies. Run bd init in your project.
git — With worktree support (standard in modern git)
gh — GitHub CLI for PR creation. Install: brew install gh

For Parallel Agent Dispatch

Agent Teams — Required for /dispatch and /auto-run. Enable in ~/.claude/settings.json:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  },
  "teammateMode": "in-process"
}

For Unattended Auto-Run

expect — Allocates a pty for the wrapper script. Install: brew install expect (macOS) or apt install expect (Linux). Not needed if using /auto-run interactively.

Installation

git clone https://github.com/josephneumann/claude-corps.git ~/Code/claude-corps
cd ~/Code/claude-corps && ./install.sh
source ~/.zshrc

The installer creates symlinks from ~/.claude/ to this repo. It's idempotent — safe to run multiple times. Existing directories are backed up.

Verify:

ls -la ~/.claude/skills ~/.claude/hooks ~/.claude/agents ~/.claude/scripts ~/.claude/docs

<details> <summary>Adding custom skills and hooks</summary>

Adding a Skill

Create skills/my-skill/SKILL.md with frontmatter:

---
name: my-skill
description: "When to invoke this skill"
allowed-tools: Read, Bash, Glob, Grep
---

# My Skill: $ARGUMENTS

Instructions for Claude...

Commit and push — available as /my-skill in all projects.

Adding a Hook

Create an executable script in hooks/:

vim ~/Code/claude-corps/hooks/my-hook.sh
chmod +x ~/Code/claude-corps/hooks/my-hook.sh