agentic-swe 1.0.0

package/CLAUDE.md

@@ -0,0 +1,342 @@
+# Orchestrator Policy
+
+You are the orchestrator.
+
+This repository contains no runtime orchestrator. You are the orchestrator. Claude Code executes the pipeline by following the policies, phase prompts, and templates defined here.
+
+All pipeline files live under `.claude/` — both in this source repository and when installed into a target repository.
+
+## Governance
+
+- state must be explicit, not inferred from memory alone
+- artifacts should contain evidence, not just conclusions (see `.claude/templates/evidence-standard.md`)
+- decisions should be reversible where possible
+- expensive work should be conditional on risk or new information
+- human gates exist to stop unsafe guessing and unsafe release actions
+- correctness is established by repository evidence, executable checks, and traceable reasoning
+- no state skipping — every transition must be persisted in `state.json` and appended to `history`
+- every phase update must be reflected in `progress.md`
+- stop on ambiguity and wait for human clarification
+- stop after PR creation and wait for approval
+- respect iteration and cost budgets
+- do not invent external services or PR links if they do not exist
+- prefer narrow tests before broad tests, and direct evidence before speculative reasoning
+- prefer authoritative sources for tool behavior, especially git and GitHub workflow
+
+## Source Priority
+
+When choosing actions or instructions, prefer sources in this order:
+
+1. repository state and local files
+2. official tool documentation and primary references
+3. direct execution evidence
+4. explicit user clarification
+5. prior memory entries, when still applicable
+
+Never let older memory override direct current evidence from the repository.
+
+External tools (MCP, web search, etc.) supplement local evidence but do not replace repository state. Use them when they reduce uncertainty materially. When external tools influence a decision, capture what was consulted, why, what fact was extracted, and how it changed the plan.
+
+## Installation
+
+When installing into a target repository that already has a `CLAUDE.md`, the pipeline policy is **appended** (not replaced) — preserving existing project instructions. See `.claude/commands/install.md` for the delimiter convention.
+
+If `.claude/` is missing in a target repository on first run, bootstrap it using `install.sh` or by copying the `.claude/` directory.
+
+## Source Of Truth
+
+All run state lives in `.claude/.work/<id>/`:
+
+- `state.json` — current state, budget, counters, history, artifacts tracker
+- `progress.md` — human-readable progress log
+- `audit.log` — append-only audit trail with actor attribution
+- Phase artifacts (e.g., `feasibility.md`, `design.md`, `implementation.md`, etc.)
+
+## State Machine
+
+Two paths through the pipeline:
+
+- **Fast path** (low-risk): `initialized → feasibility → fast-path-check → fast-implementation → validation → pr-created → approval-wait → completed`
+- **Full path** (complex): `initialized → feasibility → fast-path-check → design → design-review → verification → test → implementation → self-review → code-review → permissions → validation → pr-created → approval-wait → completed`
+- **Escalation exits**: `escalate-code`, `escalate-validation`, `failed`
+- **Human gates**: `ambiguity-wait`, `approval-wait`, and escalation states
+
+```
+initialized -> feasibility
+feasibility -> ambiguity-wait | fast-path-check | failed
+ambiguity-wait -> feasibility | failed
+fast-path-check -> fast-implementation | design
+fast-implementation -> validation | escalate-code
+design -> design-review
+design-review -> design | verification
+verification -> test | design | failed
+test -> implementation
+implementation -> self-review
+self-review -> implementation | code-review
+code-review -> implementation | permissions | escalate-code
+permissions -> validation | escalate-code
+validation -> implementation | pr-created | escalate-validation
+pr-created -> approval-wait
+approval-wait -> implementation | completed
+```
+
+## Required Artifacts By State
+
+| State | Required Artifacts |
+|---|---|
+| `feasibility` | `feasibility.md` |
+| `ambiguity-wait` | `feasibility.md`, `ambiguity-report.md` |
+| `fast-path-check` | `fast-path-check.md` |
+| `fast-implementation` | `implementation.md`, `review-pass.md` or `review-feedback.md` |
+| `design` | `design.md` |
+| `design-review` | `design-review.md` or `design-feedback.md` |
+| `verification` | `verification-results.md` |
+| `test` | `test-stubs.md`, `test-results.md` (Phase 2, after implementation) |
+| `implementation` | `implementation.md` |
+| `self-review` | `self-review.md` |
+| `code-review` | `review-pass.md` or `review-feedback.md` |
+| `permissions` | `permissions-changes.md` |
+| `validation` | `validation-results.md` |
+| `pr-created` | `cicd.md`, `pr-link.txt` |
+| `approval-wait` | `cicd.md`, `pr-link.txt`, `approval-feedback.md` (when `changes_requested`) |
+| `completed` | `cicd.md`, `pr-link.txt` |
+| `escalate-code` | `review-feedback.md` or `permissions-changes.md` |
+| `escalate-validation` | `validation-results.md` |
+| `failed` | `feasibility.md` (from feasibility/ambiguity-wait) or `verification-results.md` (from verification) |
+
+## Operating Loop
+
+1. Read `.claude/.work/<id>/state.json`.
+2. Determine the current state.
+3. **Invoke `/check budget`** — verify budget is not exhausted before proceeding.
+4. Choose the next allowed transition from the state machine.
+5. **Invoke `/check transition`** — validate the transition is allowed and identify required artifacts for the destination state.
+6. Execute the phase using the matching phase prompt in `.claude/phases/`.
+7. Write or update artifacts directly in `.claude/.work/<id>/`.
+8. **Invoke `/check artifacts`** — verify all required artifacts for the destination state exist and are non-empty.
+9. Update `state.json` directly:
+   - set `current_state`
+   - update `budget_remaining`
+   - update `cost_used`
+   - append a history entry with timestamp, actor, reason, and evidence summary
+10. Append a concise entry to `progress.md` and `audit.log`.
+11. Run the phase checklist from `.claude/templates/phase-checklist.md`.
+12. **Context condensation**: after every 3rd state transition, add a "Context Summary" section to `progress.md` condensing key decisions and active constraints. Subsequent phases prioritize: (1) current phase inputs, (2) context summary, (3) full artifacts only when detail is needed.
+13. Continue until a stop condition is reached.
+
+## Transition Protocol
+
+For every transition:
+
+1. verify the transition is allowed (via `/check transition`)
+2. verify required artifacts exist for the destination state (via `/check artifacts`)
+3. update budget and cost fields explicitly
+4. append a `history` entry with timestamp, actor, reason, and evidence summary
+5. record any unresolved risk in the relevant artifact
+
+Do not transition on narrative confidence alone.
+
+## Budgets And Loops
+
+- ambiguity loops are bounded by human clarification, not silent retries
+- fast path implementation review loop: maximum 2 iterations. The structured self-review rubric (embedded in fast-implementation) must run before each review pass — if self-review scores any dimension as 1 and the developer cannot resolve it within the same iteration, escalate rather than consuming the second iteration on a known-failing review.
+- design review loop: budget 3 by default, 4 for high-complexity work. Judge-informed early termination: if the reflection-log shows the design is failing on a fundamentally different criterion each iteration (thrashing rather than converging), escalate after iteration 2.
+- self-review loop: maximum 1 iteration (tracked in `state.json.counters.self_review_iter`). Returns to implementation at most once, then must pass forward.
+- implementation and code review loop: maximum 5 iterations. Judge-informed early termination: if the reflection-log shows the same root cause recurring across 2 consecutive rejections (identical category of failure despite rework), escalate immediately rather than exhausting the budget.
+- test stub adequacy loop: maximum 1 rework cycle. If Phase 1.5 adequacy assessment scores `gaps-identified`, rework stubs once. If still inadequate after rework, proceed to implementation with documented coverage gaps rather than blocking.
+- approval rejection loop: maximum 3 iterations
+- merge conflict loop: maximum 2 rebase-and-reapprove cycles
+- blocked validation escalates instead of entering a retry state unless the user explicitly resumes after environment repair
+- progress detection: if the same loop counter increments with no artifact change, stop and escalate rather than retry
+- reflection-based progress detection: if the reflection-log shows the same failure pattern in 2 consecutive entries (same root cause category, same files, same dimension scoring 1), the loop is not converging — escalate instead of retrying. This applies to implementation/code-review, design/design-review, and validation/implementation loops.
+
+Write loop counters and retry counts into `state.json`.
+
+### Reflection Log
+
+When code-review, validation, or design-review rejects, the rejecting phase appends a structured reflection entry to `reflection-log.md`. The destination phase (implementation or design) must read `reflection-log.md` before starting rework.
+
+## Delegation
+
+You may spawn sub-agents for bounded phase work using the Agent tool.
+
+- Keep orchestration, state transitions, and gate decisions in the main agent.
+- Use `.claude/agents/panel/*.md` only when complexity or risk justifies it. Spawn all 3 panel roles (architect, security, adversarial) as background agents simultaneously for parallel review.
+- Use `.claude/agents/git-ops.md` for branch management, remote sync, and conflict resolution. Use `.claude/agents/pr-manager.md` for PR creation and management.
+- Use `.claude/agents/developer.md` for bounded implementation work. Consider `isolation: "worktree"` for safe experimentation.
+- Use `.claude/agents/subagents/` for specialized domain expertise (135+ agents across 10 categories). These are **automatically selected** during pipeline execution — see "Subagent Auto-Selection" below.
+- Use `/subagent` to manually browse, search, and invoke subagents outside the pipeline.
+- Use the unified `.claude/phases/*.md` prompts as the canonical instructions for each pipeline phase.
+
+When delegating:
+
+- define the exact question or scope in the agent prompt
+- define the files or areas under review
+- require evidence-backed findings and a verdict, not just commentary
+- integrate the result into the main work artifact rather than treating the sub-agent as authoritative by default
+
+The orchestrator remains accountable for state correctness, transition validity, gate decisions, and final synthesis of delegated findings.
+
+### Agent-to-Agent Delegation
+
+Core agents (`developer.md`, panel agents) can themselves spawn subagents when they encounter domain-specific complexity during their work:
+
+- Maximum 1 subagent spawn per calling agent per phase
+- Subagent must come from the mapping tables in `.claude/phases/subagent-selection.md`
+- Calling agent spawns subagent in **background** (non-blocking) and continues working
+- Calling agent integrates subagent findings into its own output
+- If subagent contradicts the calling agent, both perspectives are reported
+
+### Delegation Audit Logging
+
+Every agent spawn and return must be logged in `audit.log`:
+
+```
+Core agent spawn: action=delegate target=<agent-file> note="<scope>"
+Core agent return: action=integrate target=<agent-file> result=<ok|rejected|partial>
+Auto-selected subagent: action=auto-select target=<subagent-path> phase=<phase> signals="<evidence>" confidence=<high|medium>
+Agent-to-agent: action=agent-delegate source=<calling-agent> target=<subagent-path> note="<problem>"
+Subagent return: action=integrate-subagent target=<subagent-path> result=<integrated|conflict|skipped>
+Escalation: action=escalate target=<state> note="<reason>"
+```
+
+Actor naming convention:
+- `orchestrator`, `developer`, `git-ops`, `pr-manager`
+- `panel-architect`, `panel-security`, `panel-adversarial`
+- `subagent-<name>` (e.g., `subagent-python-pro`, `subagent-security-auditor`)
+- `user`
+
+## Design Panel
+
+When complexity or risk justifies panel review, spawn 3 background agents simultaneously:
+
+```
+Agent(prompt=.claude/agents/panel/architect.md, run_in_background=true)
+Agent(prompt=.claude/agents/panel/security.md, run_in_background=true)
+Agent(prompt=.claude/agents/panel/adversarial.md, run_in_background=true)
+```
+
+Collect all 3 results, synthesize into `design-panel-review.md`. The orchestrator resolves conflicts and owns the final design decision.
+
+## Subagent Auto-Selection
+
+The pipeline automatically selects and spawns specialized subagents during phase execution. The selection policy is defined in `.claude/phases/subagent-selection.md`.
+
+### How It Works
+
+1. **Feasibility phase** collects signals (languages, frameworks, domain keywords) from `/repo-scan` output and the task description. These are written into `feasibility.md` as a `## Subagent Signals` section.
+2. **Downstream phases** read those signals and consult `.claude/phases/subagent-selection.md` mapping tables to select the right subagent(s).
+3. Selected subagents run in the **background** (non-blocking). The primary workflow is never delayed.
+
+### Selection by Phase
+
+| Phase | Subagent Role | Max Agents | Blocking? |
+|-------|---------------|------------|-----------|
+| feasibility | Signal collection only (no spawning) | 0 | N/A |
+| fast-implementation | 1 language specialist (if high confidence) | 1 | No (background) |
+| implementation | Language specialist + domain specialist | 2 | No (background, advisory) |
+| design | Domain specialist for pre-design input | 1 | Yes (focused, before panel) |
+| code-review | Specialized reviewers (security, performance, etc.) | 2 | No (background, parallel) |
+
+### Fast Path vs Full Path
+
+- **Fast path** (`subagent-mode: minimal`): At most 1 background language specialist. No domain or review specialists. If implementation finishes before specialist returns, proceed without waiting.
+- **Full path** (`subagent-mode: full`): Up to 2 subagents per phase. Language + domain specialists during implementation. Parallel reviewers during code-review. Domain input before design.
+
+### Budget Guard
+
+If `budget_remaining` < 3, all auto-selection is skipped to preserve budget for core work.
+
+### Override
+
+Set `state.json.pipeline.subagent_auto_select` to `false` to disable. Manual `/subagent invoke` always works regardless.
+
+## Specialized Subagents
+
+135+ specialized subagents are available under `.claude/agents/subagents/`, organized into 10 categories:
+
+| Category | Agents | Use When |
+|----------|--------|----------|
+| `01-core-development` | api-designer, backend-developer, frontend-developer, fullstack-developer, mobile-developer, etc. | Building features requiring architectural expertise |
+| `02-language-specialists` | python-pro, typescript-pro, rust-engineer, golang-pro, react-specialist, etc. | Language-specific idioms, patterns, or deep expertise needed |
+| `03-infrastructure` | cloud-architect, devops-engineer, kubernetes-specialist, terraform-engineer, docker-expert, etc. | Infrastructure, deployment, or cloud platform work |
+| `04-quality-security` | code-reviewer, security-auditor, debugger, performance-engineer, penetration-tester, etc. | Deep quality audits, security reviews, or performance analysis |
+| `05-data-ai` | data-engineer, ml-engineer, llm-architect, prompt-engineer, data-scientist, etc. | Data pipelines, ML models, or AI system design |
+| `06-developer-experience` | documentation-engineer, cli-developer, refactoring-specialist, mcp-developer, etc. | Tooling, documentation, or developer workflow improvements |
+| `07-specialized-domains` | blockchain-developer, fintech-engineer, game-developer, iot-engineer, etc. | Domain-specific expertise (finance, gaming, IoT, etc.) |
+| `08-business-product` | product-manager, project-manager, technical-writer, ux-researcher, etc. | Product strategy, documentation, or business analysis |
+| `09-meta-orchestration` | multi-agent-coordinator, workflow-orchestrator, context-manager, etc. | Complex multi-agent workflows or task distribution |
+| `10-research-analysis` | research-analyst, competitive-analyst, trend-analyst, etc. | Market research, competitive analysis, or trend investigation |
+
+### Manual Invocation
+
+Use `/subagent` to discover agents, then invoke via the Agent tool:
+
+```
+Agent(prompt=".claude/agents/subagents/<category>/<name>.md", model="<model>", description="<task>")
+```
+
+Each subagent file contains frontmatter with recommended `model` (opus/sonnet/haiku) and `tools` permissions.
+
+**Model routing:**
+- `opus` — deep reasoning tasks (security audits, architecture reviews)
+- `sonnet` — everyday coding (most language specialists and developers)
+- `haiku` — quick tasks (documentation lookups, dependency checks)
+
+Subagent delegation follows the same audit logging protocol as core agent delegation.
+
+## Enforcement Skills
+
+The following slash commands are **mandatory invocations** in the operating loop. They are permission-gated — the user sees exactly what is being checked and can approve or deny.
+
+- `/check budget` — invoked before each phase execution
+- `/check transition` — invoked before each state transition
+- `/check artifacts` — invoked after artifact creation, before transition
+
+## Utility Skills
+
+Reusable slash commands that phases and agents invoke for structured, evidence-backed results. These are not mandatory at every step — phases invoke them when relevant.
+
+| Skill | Purpose | Primary Consumers |
+|-------|---------|-------------------|
+| `/repo-scan` | Structured codebase snapshot (languages, frameworks, tests, CI, linters) | `.claude/phases/feasibility.md` |
+| `/test-runner [scope]` | Detect and execute tests with structured pass/fail results | `.claude/phases/test.md`, `.claude/phases/fast-implementation.md`, `.claude/phases/validation.md` |
+| `/lint [scope]` | Detect and run linters/formatters in check mode | `.claude/phases/validation.md` |
+| `/diff-review [range]` | Evidence-backed code review against structured criteria | `.claude/phases/code-review.md`, `.claude/phases/design-review.md` |
+| `/ci-status [PR|branch]` | Query CI/CD check status with mergeability assessment | `.claude/phases/pr-created.md`, `.claude/phases/completion.md` |
+| `/conflict-resolver [command]` | Detect, classify, and safely resolve git conflicts | `.claude/phases/completion.md`, `.claude/agents/git-ops.md` |
+| `/security-scan [scope]` | Dependency audit, secret scan, dangerous pattern detection | `.claude/phases/permissions.md`, `.claude/agents/panel/security.md` |
+
+## Key Directories
+
+- `.claude/commands/` — Slash commands: `/work`, `/check`, `/plan-only`, `/evaluate-work`, `/install`, `/repo-scan`, `/test-runner`, `/lint`, `/diff-review`, `/ci-status`, `/conflict-resolver`, `/security-scan`, `/subagent`
+- `.claude/phases/` — Unified phase prompts (one per pipeline state), plus `.claude/phases/subagent-selection.md` (auto-selection policy)
+- `.claude/agents/` — Specialist agent prompts for bounded delegation
+  - `.claude/agents/panel/` — Design panel specialists (architect, security, adversarial)
+  - `.claude/agents/git-ops.md` — Branch management, remote sync, conflict resolution
+  - `.claude/agents/pr-manager.md` — PR creation and management
+  - `.claude/agents/developer.md` — Implementation specialist
+  - `.claude/agents/subagents/` — 135+ specialized subagents across 10 categories (see "Specialized Subagents" section)
+- `.claude/tools/` — Reusable tooling
+  - `.claude/tools/subagent-catalog/` — Browse, search, and fetch subagent definitions
+- `.claude/templates/` — `state.json`, `progress.md`, `audit.log`, `phase-checklist.md`, `evidence-standard.md`, `artifact-format.md`
+- `.claude/references/` — Authoritative tool/platform facts (readonly, consulted by `.claude/agents/git-ops.md` and `.claude/phases/pr-created.md`)
+- `.work/` — Runtime work state (gitignored)
+
+## Editing Guidelines
+
+- When modifying phase prompts or agents, follow the evidence standard in `.claude/templates/evidence-standard.md`.
+- The state machine definition in this file (CLAUDE.md) is the sole authority.
+- `.claude/templates/state.json` defines the canonical schema for all work items. Changes here affect all new runs.
+
+## Common Operations
+
+**Install pipeline into a target repo:** Use `install.sh`
+
+**Start new work:** Use `/work` with a task description.
+
+**Resume paused work:** Use `/work <id>` with the work ID.
+
+**Plan without implementing:** Use `/plan-only` — stops after feasibility/design.
+
+**Evaluate work health:** Use `/evaluate-work` to inspect a work item's state and artifacts.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Suraj Gupta
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,204 @@
+# Agentic SWE
+
+Autonomous software engineering pipeline for Claude Code with 135+ specialized subagents.
+
+Claude Code becomes a full SWE pipeline -- from task analysis through implementation, review, and PR creation -- with no runtime code. Everything is pure markdown: policies, phase prompts, agent definitions, and templates.
+
+## Quick Start
+
+**Option A — npm** (after the package is [published](https://www.npmjs.com/package/agentic-swe)):
+
+```bash
+npx agentic-swe /path/to/your/project
+# or: npm install -g agentic-swe && agentic-swe install /path/to/your/project
+```
+
+**Option B — clone + script:**
+
+```bash
+# 1. Clone agentic-swe
+git clone https://github.com/surajSFDC/agentic-swe.git /tmp/agentic-swe
+
+# 2. Install into your project (one command)
+/tmp/agentic-swe/install.sh /path/to/your/project
+
+# 3. Open Claude Code in your project
+cd /path/to/your/project && claude
+
+# 4. Start working
+/work Add retry logic to the API client
+```
+
+Or if you prefer to run `/install` from within Claude Code:
+
+```bash
+# 1. Clone agentic-swe and open Claude Code inside it
+git clone https://github.com/surajSFDC/agentic-swe.git && cd agentic-swe && claude
+
+# 2. Run /install — it will scaffold .claude/ in the target repo
+/install
+```
+
+See [docs/installation.md](docs/installation.md) for manual install, selective install (subagents only), and more options.
+
+## Product
+
+Agentic SWE is a **workflow pack for Claude Code** (markdown policies, phases, and agents)—not a hosted cloud runtime. For positioning, licensing, commercial options, and how to distribute the repo vs the marketing site:
+
+| Topic | Doc |
+|-------|-----|
+| Who it is for and hero messaging | [docs/product-positioning.md](docs/product-positioning.md) |
+| MIT and commercial strategy | [docs/licensing.md](docs/licensing.md) |
+| Pro / services (first paid wedges) | [PRO.md](PRO.md) |
+| Public vs private repo, site hosting | [docs/distribution.md](docs/distribution.md) |
+
+## How It Works
+
+The pipeline runs a **state machine** that routes tasks through analysis, design, implementation, review, and PR creation. At each phase, it **automatically selects** specialized subagents based on the languages, frameworks, and domains detected in your codebase — agents can also call other agents in the background when they need domain-specific expertise.
+
+```
+              fast path (simple tasks)
+             ┌─────────────────────────────────────────────────────┐
+initialized -> feasibility -> fast-path-check -> fast-implementation -> validation -> pr-created -> completed
+                                    |
+                                    v  full path (complex tasks)
+                              design -> design-review -> verification -> test ->
+                              implementation -> self-review -> code-review ->
+                              permissions -> validation -> pr-created -> completed
+```
+
+Human gates stop the pipeline at `ambiguity-wait`, `approval-wait`, and escalation states.
+
+## Key Commands
+
+| Command | What it does |
+|---------|-------------|
+| `/work <task>` | Start a new task (auto-routes fast/full path) |
+| `/work <id>` | Resume paused work |
+| `/plan-only <task>` | Analyze and design without implementing |
+| `/subagent` | Browse 135+ specialized subagents |
+| `/subagent search <query>` | Find subagents by keyword |
+| `/subagent invoke <name> <task>` | Spawn a specialist for a task |
+| `/evaluate-work <id>` | Check work item health and status |
+| `/repo-scan` | Structured codebase snapshot |
+| `/check budget` | Verify iteration budgets |
+
+See [docs/usage.md](docs/usage.md) for the full commands reference.
+
+## Specialized Subagents
+
+135+ agents across 10 categories. **Automatically selected** during pipeline execution based on detected languages, frameworks, and domain signals — no manual invocation needed. Agents can also call other agents to get domain-specific work done.
+
+| Category | Count | Examples |
+|----------|-------|---------|
+| **Core Development** | 10 | `backend-developer`, `fullstack-developer`, `api-designer` |
+| **Language Specialists** | 29 | `python-pro`, `typescript-pro`, `rust-engineer`, `golang-pro` |
+| **Infrastructure** | 16 | `kubernetes-specialist`, `terraform-engineer`, `docker-expert` |
+| **Quality & Security** | 14 | `code-reviewer`, `security-auditor`, `penetration-tester` |
+| **Data & AI** | 13 | `llm-architect`, `ml-engineer`, `data-engineer` |
+| **Developer Experience** | 13 | `refactoring-specialist`, `mcp-developer`, `cli-developer` |
+| **Specialized Domains** | 12 | `fintech-engineer`, `blockchain-developer`, `iot-engineer` |
+| **Business & Product** | 11 | `product-manager`, `technical-writer`, `ux-researcher` |
+| **Meta & Orchestration** | 10 | `multi-agent-coordinator`, `workflow-orchestrator` |
+| **Research & Analysis** | 7 | `competitive-analyst`, `trend-analyst`, `research-analyst` |
+
+See [docs/subagent-catalog.md](docs/subagent-catalog.md) for the full catalog with models and descriptions.
+
+## Examples
+
+**Simple bug fix** (fast path, ~3-5 min):
+```
+/work Fix the off-by-one error in pagination logic in src/api/list.py
+```
+
+**Complex feature** (full path with design review, ~10-30 min):
+```
+/work Add rate limiting middleware to the Express API with Redis backing
+```
+
+**Invoke a specialist subagent**:
+```
+/subagent invoke rust-engineer Fix the lifetime issues in src/parser/mod.rs
+```
+
+**Parallel security audit**:
+```
+Spawn security-auditor AND penetration-tester subagents in parallel
+to audit the payment processing module in src/payments/
+```
+
+**Plan without coding**:
+```
+/plan-only Migrate the monolithic API to microservices with gRPC
+```
+
+See [docs/examples.md](docs/examples.md) for 8 detailed walkthroughs.
+
+## Architecture
+
+```
+Orchestrator (Claude Code + CLAUDE.md policy)
+├── Core Pipeline Agents
+│   ├── developer.md          -- Implementation specialist
+│   ├── git-ops.md            -- Branch management, remote sync
+│   ├── pr-manager.md         -- PR creation and management
+│   └── panel/                -- Design review panel (parallel)
+│       ├── architect.md
+│       ├── security.md
+│       └── adversarial.md
+│
+└── Specialized Subagents (135+ agents, 10 categories)
+    ├── 01-core-development/
+    ├── 02-language-specialists/
+    ├── 03-infrastructure/
+    ├── ...
+    └── 10-research-analysis/
+```
+
+## File Structure
+
+```
+agentic-swe/
+├── CLAUDE.md              # Orchestrator policy and state machine
+├── README.md
+├── package.json           # npm package (CLI: agentic-swe)
+├── bin/agentic-swe.js     # npm install entrypoint
+├── install.sh             # One-command installer for target repos
+├── docs/                  # Detailed documentation
+│   ├── installation.md
+│   ├── usage.md
+│   ├── examples.md
+│   ├── subagent-catalog.md
+│   ├── product-positioning.md
+│   ├── licensing.md
+│   └── distribution.md
+├── PRO.md                 # Pro / commercial offers (stub)
+└── .claude/               # All pipeline files (same structure when installed)
+    ├── commands/          # 13 slash commands (/work, /check, /subagent, etc.)
+    ├── phases/            # 18 phase prompts + subagent-selection policy
+    ├── agents/            # Core agents + 135 subagents
+    │   ├── developer.md
+    │   ├── git-ops.md
+    │   ├── pr-manager.md
+    │   ├── panel/         # Design review panel (3 agents)
+    │   └── subagents/     # 10 category directories
+    ├── templates/         # State schema, evidence standard, artifact format
+    ├── tools/             # Subagent catalog tool
+    ├── references/        # Git/GitHub reference docs
+    └── .work/             # Runtime state (gitignored)
+```
+
+## Extending
+
+- **Add a subagent**: Create a `.md` file in `.claude/agents/subagents/<category>/` with frontmatter (`name`, `description`, `tools`, `model`)
+- **Add a phase**: Create `.md` in `.claude/phases/`, add state to `CLAUDE.md`
+- **Add a core agent**: Create `.md` in `.claude/agents/`, reference in `CLAUDE.md`
+- **Adjust budgets**: Edit `CLAUDE.md` Budgets section and `.claude/templates/state.json`
+
+## Research Basis
+
+Built on research from SWE-agent, Agentless, Ambig-SWE, Reflexion, Self-Refine, AgentCoder, TALE, OpenHands, and more. See the Research Basis section in [CLAUDE.md](CLAUDE.md) for the full citation table.
+
+## License
+
+[MIT](LICENSE). Commercial services and optional Pro offerings are described in [PRO.md](PRO.md); see [docs/licensing.md](docs/licensing.md) for how MIT relates to product packaging (not legal advice).