solo-agent-kit

The vault-based workflow for a single human orchestrating multiple Claude AI agents. Battle-tested on the ai-talkie project (Apr 2026: 7 PRs / single session, Epic I-400 closed in one day).

Status: v0.7.1 — frictionless deploy. npm CLI (sak), remote installer, auto-detect --repo/--user from git, agent-driven first-run scan that fills orchestrator-prompt placeholders by reading the actual repo, upgrade-kit.sh for one-command self-update.

What this kit gives you

A project-agnostic command center you drop into any repo in one command:

your-project/
├── <project>-vault/         ← Ops vault: Dashboard / Issues / Sprints / ADRs / Handoffs / Inbox / Retros
├── docs/AGENT-WORKFLOW.md   ← protocol (size caps · WIP=3 · FINAL GATE · pre-flight scan)
├── .solo-agent-kit.conf     ← VAULT_DIR=<name>, sibling scripts read this
└── ~/worktrees/<project>/   ← agent worktrees live OUTSIDE your repo

Plus 7 cross-project MEMORY entries that auto-load in every Claude Code session in that project:

| Entry | Lesson | |---|---| | workflow_protocol.md | Vault + AGENT-WORKFLOW layered model | | git_gotchas.md | 7 git pitfalls (ours/theirs inversion, --no-edit, branch -D after squash) | | final_gate.md | Executor agents must not exit mid-task without "stopping at X because Y" | | solo_ai_setup.md | approvals=0 on main · worktrees outside repo · interface-first parallelism | | audit_scope.md | Audit/sweep tasks must enumerate ALL CLAUDE.md (root + module) | | id_namespace.md | Issue ID collision prevention (I-100 user, I-200 UI, ...) | | dogfood_iteration.md | Visual UX needs ≥ 2 rounds + screenshot proof; "diff clean + tests green" insufficient |

Quick start — new project (1 command)

Pick whichever channel you prefer. All three end up doing the same thing and auto-detect --repo/--user from git remote + git config.

A. npm / npx (no global state, one-shot):

cd ~/YourProject
npx solo-agent-kit init

Or install globally and use sak everywhere:

npm i -g solo-agent-kit
cd ~/YourProject && sak init

B. Remote one-liner shell (clones seed to ~/solo-agent-kit):

cd ~/YourProject
curl -fsSL https://raw.githubusercontent.com/huberthe-pro/solo-agent-kit/main/install.sh | bash

C. Explicit (if seed already cloned):

cd ~/YourProject
bash ~/solo-agent-kit/scripts/bootstrap-project.sh
# Override auto-detection if needed:
#   bash ~/solo-agent-kit/scripts/bootstrap-project.sh --repo owner/repo --user "Your Name"

That single command:

1. Scaffolds <project>-vault/ (10 standard subdirs with templates)
2. Copies docs/AGENT-WORKFLOW.md (the protocol) into your repo
3. Sets git config gc.auto 0 (worktree safety)
4. Configures GitHub branch protection (PR required · approvals=0 · force-push off)
5. Installs orchestrator-prompt.md to <vault>/80-Templates/ with placeholders auto-filled
6. Injects 7 MEMORY entries into ~/.claude/projects/<encoded>/memory/
7. Runs kit-doctor.sh for a final health check

After bootstrap:

• Open Claude Code in the project — MEMORY auto-loads + a FIRST-SCAN.md task waits in <vault>/50-Inbox/. Tell Claude: "Execute the task in 50-Inbox/FIRST-SCAN.md". The agent reads your CLAUDE.md, package.json, README, git log, and proposes values for the remaining ⚠️{{...}} placeholders. You approve, the agent writes.
• Open Obsidian → File → Open folder as vault → your <vault>/
• Install 4 plugins: Dataview · Tasks · Kanban · Templater

Quick start — second / Nth project

Same command. The kit is fully project-agnostic; nothing inside ai-talkie leaks.

cd ~/your-second-project
bash ~/solo-agent-kit/scripts/bootstrap-project.sh --repo you/your-second --user "Your Name"

Upgrading an existing project to a newer kit version

cd ~/YourProject
sak upgrade                                    # via npm
# — or —
bash ~/solo-agent-kit/scripts/upgrade-kit.sh   # via raw script

What it does: git pull the seed kit → inject-memory.sh --refresh → refresh docs/AGENT-WORKFLOW.md if behind → kit-doctor.sh. --repo auto-detected from git remote.

vault-template/ is deliberately not overwritten on re-init — your project vault is yours.

Health check anytime

cd ~/YourProject
sak doctor                                                     # via npm
# — or —
bash ~/solo-agent-kit/scripts/kit-doctor.sh [--repo owner/repo]

8 checks:

1. .solo-agent-kit.conf present + VAULT_DIR resolves
2. Vault dir exists + 10 standard subdirs
3. docs/AGENT-WORKFLOW.md exists
4. git gc.auto = 0
5. ~/worktrees/<project>/ exists
6. Claude Code MEMORY dir + 7 kit entries injected
7. orchestrator-prompt.md present + placeholders filled
8. (with --repo) GitHub branch protection: PR required · approvals=0 · force-push off

Returns 0 if PASS+WARN only, 1 if any FAIL.

Directory map

solo-agent-kit/
├── README.md                  ← you are here
├── VERSION                    ← v0.6.0
├── CHANGELOG.md
│
├── vault-template/            ← copied into each project as <project>-vault/
│   ├── 00-Dashboard/          (Home / Project-Radar / Project-Architecture / Project-Features)
│   ├── 10-Strategy/ADR/
│   ├── 20-Sprints/
│   ├── 30-Issues/
│   ├── 40-Handoffs/
│   ├── 50-Inbox/              (Ideas.md append-only)
│   ├── 60-Retros/
│   ├── 70-Growth/             (Agent-Scoreboard, Routines-Activity)
│   ├── 80-Templates/          (issue / handoff / adr / daily / weekly-journal / orchestrator-prompt)
│   ├── 90-Links/
│   └── 99-Archive/
│
├── docs/
│   ├── AGENT-WORKFLOW.md      ← the protocol (v1.3)
│   ├── ROUTINES.md            ← 4 scheduled agents (planner/triage/retro/digest)
│   └── GROWTH-MECHANISM.md    ← Agent-Scoreboard + 6-knob scoring
│
├── reference-adrs/            ← anonymized ADRs from prior projects (learn-from samples)
│
├── routines/                  ← prompt templates for 4 scheduled Claude agents
│   ├── planner.prompt.md
│   ├── triage.prompt.md
│   ├── retro.prompt.md
│   └── digest.prompt.md
│
├── package.json              ← npm distribution (NEW v0.7) — `npx solo-agent-kit init`
├── bin/solo-agent-kit.js     ← `sak` CLI wrapper (NEW v0.7)
├── install.sh                ← remote one-liner installer (NEW v0.7)
├── scripts/
│   ├── bootstrap-project.sh           ← one-shot setup (auto-detects repo/user in v0.7)
│   ├── upgrade-kit.sh                 ← self-update (NEW v0.7)
│   ├── kit-doctor.sh                  ← health check
│   ├── init-vault.sh                  ← scaffold vault + docs
│   ├── configure-branch-protection.sh ← gh api PATCH recipe
│   ├── inject-memory.sh               ← copies MEMORY entries (--refresh in v0.6)
│   ├── install-routines.sh            ← register 4 scheduled agents
│   ├── routines-status.sh             ← inspect routine activity
│   ├── agent-launch-template.sh       ← emits FINAL-GATE executor prompt
│   ├── agent-score.sh                 ← score a merged PR
│   ├── cleanup-merged-worktree.sh     ← post-merge cleanup (strict order)
│   ├── growth-setup.sh / growth-digest.sh
│   └── propose-upstream.sh            ← contribute lessons back to kit
│
├── memory-entries/            ← 7 cross-project MEMORY files (read by Claude Code)
└── playbooks/                 ← end-to-end flows

Philosophy

This kit assumes:

1. You are a single human (not a team)
2. AI agents are your collaborators (Claude Code, Codex, Cursor, etc.)
3. Local-first: vault is markdown in git, not a SaaS
4. Workflow is a living document: the protocol evolved through real use; expect your copy to evolve too

Hard rules the kit enforces:

• WIP cap 3: never more than 3 executor agents running concurrently
• Review budget 2/day: no launching new agents when review queue full
• Size caps: size:l is forbidden; Planner must split to s/m
• FINAL GATE: agents may not exit mid-task without explicit "stopping at step X because Y"
• Handoff in PR branch: not in main clone
• Worktrees outside repo: never inside, to prevent git pull breakage on secondary machines
• Pre-flight scan: before launching an Epic's first issue, verify the repo actually matches the issue's assumptions
• Audit scope is explicit: enumerate all CLAUDE.md (root + module), not "the docs"
• ID collisions are prevented, not fixed: ls <vault>/30-Issues/ | grep ^I- before claiming a number

Versioning

The kit follows semver. MAJOR.MINOR.PATCH:

• MAJOR: breaking change to the workflow protocol or vault structure
• MINOR: new memory entries, new scripts, new templates
• PATCH: bug fixes, doc edits

CHANGELOG.md documents every version. Each project carries its own snapshot of docs/AGENT-WORKFLOW.md and the kit version it was bootstrapped from.

License

Non-commercial use only. If you want to use this kit commercially, open an issue.