Your agent drifts after 20 minutes because it doesn't know what "done" looks like.
This toolkit fixes that. It gives Claude Code and Codex the decomposition methodology to execute autonomously for hours — grounded in the Linear Method.
The core insight: long autonomous runs don't fail because of bad prompts. They fail because of bad decomposition. An agent with a well-defined issue (clear outcome, explicit scope boundaries, verifiable acceptance criteria) will execute reliably. An agent with a vague goal will hallucinate scope, drift, or stall.
Every project follows this chain. Each step produces a concrete artifact that feeds the next.
You write Agent + you refine Agent executes
┌─────────┐ ┌──────────────────┐ ┌────────────────┐
│ SPEC │───────▶│ MILESTONE │───────▶│ ISSUE DOCS │───▶ Autonomous
│ │ │ (hardened) │ │ (per-issue) │ execution
└─────────┘ └──────────────────┘ └────────────────┘
1. Spec → Milestone — You define the target architecture. The agent converts it into a milestone: a completion-oriented slice of 6-10 issues with sequencing and dependencies.
2. Harden the Milestone — The agent expands every issue with acceptance criteria, scope boundaries, verification steps, and prework prompts. This is the step that makes long runs possible — it eliminates the ambiguity agents trip on.
3. Break into Issue Docs — Fractal decomposition: the milestone becomes an index, parent issues become sub-indexes, leaf issues carry full implementation detail.
4. Prework Sweep — Resolve remaining open questions embedded in issue docs before any code runs.
5. Execute — The agent picks up issues one at a time in isolated git worktrees, each scoped by its issue doc.
- workflows/execute-issue.md — single issue
- workflows/execute-milestone.md — full milestone loop
- workflows/orchestrate-milestone.md — orchestrator layer with context + taste
6. Review & Fix — Principal-level review of each issue, then a fix loop.
skills/ — The mental models. These teach your agent how to think about decomposition, issue quality, and safe parallel work.
| Skill | What it teaches |
|---|---|
| linear-method/ | Issues as units of value + behavior. Milestones as completion-oriented phases. Sizing, triage, templates. |
| architecture/ | Target architecture definition via decision packets and migration slices. Turning exploration into specs. |
| git-worktrees/ | Safe worktree isolation so each issue executes in its own checkout. Every workflow depends on this. |
| parallel-development/ | Multi-agent coordination: one worktree per agent, Graphite stacks for ordering, no global side effects. |
| autonomous-development/ | The safety contract: worktree lifecycle rules, structured output, allowed operations. |
workflows/ — The mechanical procedures. Step-by-step agent instructions for each phase of the pipeline.
docs/ — Human-readable guides for understanding and adopting the toolkit.
| Doc | What it covers |
|---|---|
| how-it-works.md | The full methodology — why decomposition matters, what makes a good issue, how milestones work |
| getting-started.md | Concrete first steps for trying this with your own project |
| glossary.md | Terms used in the workflows (worktrees, Graphite, stacks, agent prefixes) |
Understand the idea: Read docs/how-it-works.md.
Try it with your project: Follow docs/getting-started.md.
Install the skills: Drop the skills/ directories into your .claude/commands/ or Codex skills directory. Put workflows/ in your commands directory.
Use as system context: Reference the SKILL.md files in your CLAUDE.md or include them via custom commands.
These workflows assume specific tooling that you can swap:
| Assumption | What to change |
|---|---|
| Graphite for stacked PRs | Replace gt commands with plain git equivalents |
| Linear for issue tracking | The patterns work with any tracker — adapt the references |
| Git worktrees for isolation | Set $WORKTREES_ROOT to your preferred location |
| Multi-agent setup | The agent--... branch naming simplifies if you're solo |