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.14.0 — agent integration: sak init/upgrade now writes a marker-fenced kit block into the project's CLAUDE.md and installs the sak agent skill (.claude/skills/sak/) so Claude Code/Cowork agents create issues, launch executors, lint and archive themselves — the human never relays terminal commands. Plus v0.13.x — template consistency sweep + adversarial-review hardening (17 fixes incl. the octal sak launch 042 blocker). Plus v0.12 — chat-first knowledge loop (protocol v1.6). The entry point is a conversation: you think out loud with an agent, and it lands as 知识 (research note in 10-Strategy/Research/, verdict + feeds: required) / 决策 (ADR — open-criteria codified, accepted ⇒ decompose into issues immediately) / 工作 (issue via sak new). Inbox demoted to optional on-demand capture. Plus v0.11: mechanized lifecycle (sak new/launch/lint/archive, rules that aren't mechanized are suggestions), slim vault, handoff-lite, sak-pm Obsidian plugin. Plus v0.10: DocDD gates (docs-touched, CI-green), dependency-aware dispatch (⛓/📅/🏁 board).

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 IDs come from sak new allocator (manual numbering retired) | | 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 (6 steps): git pull seed → inject-memory.sh --refresh → refresh docs/AGENT-WORKFLOW.md → sync-vault-additions.sh (add-only sync of new vault files like new templates / inboxes that the upgrade introduced) → sync-sprint-board.sh (re-render kanban) → kit-doctor.sh. --repo auto-detected.

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

Daily operating rhythm

Three intake streams live in <vault>/50-Inbox/ — capture-first, triage-later. Each has its own cadence:

| Stream | What goes there | Triaged by | Cadence | |---|---|---|---| | 💡 Ideas.md | Product / design / feature ideas | Planner agent | Weekly Mon 09:00 | | 🐛 Bugs.md | Confirmed broken behavior (with severity) | Daily-Ops agent | Daily 08:00 | | ✅ Todos.md | Operational / admin / owed tasks (with due:) | Daily-Ops agent | Daily 08:00 |

Sprint board at <vault>/00-Dashboard/Sprint-Board.md is auto-generated from issue frontmatter — status: is the source of truth, the board is a read-only rendered view. To move an issue, edit its frontmatter; the board refreshes on next sync.

sak sync-board    # re-render board after editing issues
sak daily         # stage daily-ops task for manual run in Claude Code

The Daily-Ops agent writes a brief to <vault>/00-Dashboard/Daily-Brief.md each morning: severity-ranked new bugs, due/overdue todos, idea count, stale-issue alerts, top-3 suggested actions.

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/           (Roadmap · ADR/ · Research/ ← knowledge layer, v0.12)
│   ├── 30-Issues/             (IDs via `sak new`)
│   ├── 40-Handoffs/
│   ├── 80-Templates/          (issue / bug / todo / handoff / adr / research / dogfood / orchestrator-prompt / ...)
│   ├── 99-Archive/            (`sak archive` writes monthly dirs)
│   └── 20-Sprints/ 50-Inbox/ 60-Retros/ 70-Growth/   ← on-demand (created when their routine is installed)
│
├── obsidian-plugin/sak-pm/    ← in-vault buttons: launch / new / lint / archive (v0.11)
│
├── docs/
│   ├── AGENT-WORKFLOW.md      ← the protocol (v1.6)
│   ├── DOC-SYSTEM.md          ← core document standard (Tier 0/1/2)
│   ├── 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.