KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#typescript #ai-agents #developer-tools #cli #codex #claude-code #react #dsh-plugin #mcp #open-source #dsh #deepseek-harness

subagent-driven-dev-kit

★ 3 Open GitHub ↗

A portable, teachable setup for subagent-driven development with an AI coding agent: one orchestrator delegates each task to a fresh single-purpose subagent, reviewed by an independent panel before the next task. Prompts + cloud/PR/git-flow guides included.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Subagent-Driven Development Kit

**A portable, teachable setup for building software with AI coding agents where an automated pipeline does the
work — one orchestrator delegates every task to a fresh, single-purpose subagent, an independent panel reviews each
task before the next begins, and lifecycle agents merge the result and open the next PR.** Written for both humans
and AI agents; designed to drop into any project.

> **Start here → [`overview.md`](./overview.md)** (the teaching hub, with diagrams).

---

## What this is really about

### 1. Automated delivery, not just an AI that types faster
The goal is a **95–100% self-driving code pipeline**. You set direction and seed a backlog; the pipeline does the
rest — plan a filed issue, implement it, test it, review it from every angle, fix it, align the docs, decide it's
safe, merge it, and open the next PR. Triggers on git-forge events chain the agents into a closed loop:

```
issue filed → PR opened → executor runs (implement · review · verify) → gatekeeper merges → PM/EM opens next PR → …
```

A human touches it at two points only: **direction** (what to build) and **genuine blockers** (a real ambiguity or a
product-direction fork). Everything between is automated. See [`automation-pipeline.md`](./automation-pipeline.md).

### 2. The unreasonable effectiveness of subagents
A single agent grinding a big task in one long context degrades — it loses the thread, rationalizes shortcuts, skips
tests, and "reviews itself" (which is not review). Splitting the work across many short-lived, single-purpose
subagents is *disproportionately* more effective than it looks, for compounding reasons:

- **Fresh context per unit of work.** Each subagent gets exactly what it needs and nothing else — no pollution, no
  drift, full attention on one thing.
- **Adversarial review beats self-review.** An implementer can't see its own blind spots. A *separate* spec /
  architecture / QA / domain reviewer, with its own prompt and its own verdict, catches what the author cannot.
  Independence is the whole point — which is why **one subagent = one role or one task, never merged.**
- **Isolation scales.** Roles run in parallel; a big review panel costs wall-clock, not quality. You can throw *more*
  independent perspectives at a change than any single context could hold.
- **The orchestrator stays clean.** It coordinates and decides; it doesn't burn its context implementing. That
  preserved context is what lets it run a whole plan end-to-end.

The result is high quality *and* high speed — the two usually trade off, and here they don't, because quality comes
from **structure** (fresh context + independent review + a hard verification gate), not from one heroic model call.

### 3. Self-feedback: the system tunes itself to YOUR repo
Every run ends with a **mandatory documentation agent** that does more than update docs — it **folds the run's
learnings back into the prompts**, so the next run is better *on this specific project*:

- A gotcha that tripped a reviewer becomes a one-line preventive note in that reviewer's prompt.
- A **token ledger** (every subagent reports its biggest token cost) becomes concrete, often **named-file**
  optimizations ("that config file is huge — grep the block, never read it whole").
- The orientation doc gets **consolidated** each run — shorter and sharper, pruning history to a changelog.

Over time the prompts accrete **project-specific wisdom** — the safe way to run *your* dev server, the fast way to
find *your* rollup builder, the gotcha in *your* migration flow. The kit ships generic; it becomes yours. This is
the flywheel that makes a long-running pipeline get *cheaper and more reliable* the more it runs.

---

## Where it fits best

Match the automation to the stakes. The **sweet spot for running it fully automated** is code where moving fast pays
off and a slip is cheap:

- **High business value + speed-to-market matters** (greenfield products, MVPs, new features, prototypes)
- **Low risk** — not safety-critical; a bug is an annoyance, not a catastrophe
- **Low security sensitivity** — not auth internals, payments, secrets, or regulated PII
- **Low uptime requirement** — a bad deploy rolls back cheaply; no 99.99% SLA
- **Standalone or internal-facing** — internal tools, dashboards, admin panels, internal APIs — contained blast radius

For **security-sensitive, high-uptime, or safety-critical** code, use the same kit but **turn the dial down** — keep
the *merge* human, add a security reviewer, stage and roll out progressively. Full autonomy is a setting, not a
requirement. Details + the sweet-spot/caution table: [`overview.md` §10](./overview.md#10-where-this-fits-best-and-where-to-be-careful).

---

## The pieces

| Doc | What it covers |
|-----|----------------|
| **[`overview.md`](./overview.md)** | the teaching hub — principles, the per-task loop, roles, mandates, diagrams |
| **[`automation-pipeline.md`](./automation-pipeline.md)** | auto-triggers on PR open/merge → the ~95–100% hands-off flywheel + how to wire it |
| **[`verification-gate.md`](./verification-gate.md)** | the gate + CI (the bedrock — fast tight-loop test/verify; prefer typed languages) |
| **[`git-flow.md`](./git-flow.md)** | one branch per plan, the rebase gate, per-task commits (with a git graph) |
| **[`issue-management.md`](./issue-management.md)** | epics, native sub-issues, phase roadmaps, keeping the backlog honest |
| **[`cloud-setup.md`](./cloud-setup.md)** | cloud execution, fast dependency/e2e provisioning, triggers, cost model |
| **[`pr-flows.md`](./pr-flows.md)** | kickoff PR anatomy, review, the merge gatekeeper, post-merge triage |
| **[`prompts/`](./prompts/)** | the reusable role prompts (fill the `{{PLACEHOLDERS}}`) |

---

## Adopt it in five steps

```text
1. Copy this folder into your repo (or use it as its own repo).
2. Set up your verification gate FIRST (verification-gate.md) — fast, reliable,
   hermetic, runnable in the cloud env. Prefer a typed language.
3. Fill every {{PLACEHOLDER}} in prompts/ (start with {{GATE}}, {{GOLDEN_FILES}},
   {{DOMAIN_REVIEWERS}}).
4. Seed a backlog: epics + grounded issues (issue-management.md).
5. Wire the three PR-event triggers (automation-pipeline.md) and let it run.
```

**If you are an AI agent adopting this:** read `overview.md`, then `prompts/README.md`; confirm `{{GATE}}` is
defined and runs; then run the loop. Never skip the per-task panel or the documentation stage; one subagent per
role/task, always.

---

## The non-negotiables (in one place)

1. **One subagent = one role or one task** — never merge roles or tasks.
2. **The review panel runs per task, before the next task** — never batched.
3. **The verification gate is the proof** — evidence over assertions; re-run it, don't trust claims.
4. **The documentation stage is mandatory** — every run ends with it (it's how the system learns).
5. **Autopilot** — go end-to-end; stop only on a genuine blocker.
6. **Real-world accuracy over grandfathering** — a domain reviewer's "this is wrong" outranks a prior "intentional."

subagent-driven-dev-kit

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README