| name | new-project |
| description | 4-phase pipeline for bootstrapping a new multi-agent project — intake, fork skeleton (branch + ledger row + sub-agent spawn), parallel execution with progress aggregation, and per-branch merge ceremony. Implements RULE 0.12 (agent git-model) at project scale. Hub-and-spoke — each phase lives in its own file and is executed in order. |
| argument-hint | <project name or one-line goal> |
New-Project — 4-Phase Pipeline (index)
When to use
- Bootstrapping a new multi-agent project with full git-model compliance (branch + 6-file artefact bundle + ledger row + merge ceremony).
- Kicking off a research, code, or hybrid project that will run as a main agent plus N parallel sub-agents.
- Implementing RULE 0.12 (agent git-model) at project scale with fork, execute, and merge ceremony.
You are bootstrapping a new project — research, code, theoretical, or
hybrid — that will run as a main agent plus N parallel sub-agents with
full git-model compliance (branch + 6-file artefact bundle + ledger row +
merge ceremony). This skill is the orchestrator wrapper; each phase lives
in its own file.
This skill does NOT itself write production code. It routes to
compose-solution (for each sub-task that needs a kit artefact) and to
new-agent (for each new specialist spawn) and records every fork in the
kei-ledger SQLite SSoT. Final merge decisions are user clicks.
Pipeline overview (4 phases + final report)
| Phase | File | Purpose | Free-text? | AskUserQuestion |
|---|
| 1 | phase-1-intake.md | Project-shape intake (type / theory / parallelism / main-agent / DB) | 1 line (GOAL) | 1× batch of 5 questions |
| 2 | phase-2-fork-skeleton.md | Create project/<slug> branch, ledger entry, theoretical sub-agent spawn | no | 1× (sub-agent kind confirm) |
| 3 | phase-3-parallel-exec.md | Poll kei-ledger list --status running, aggregate progress.json | no | 1× (continue / pause / add agent) |
| 4 | phase-4-merge-ceremony.md | Per-branch merge decision — squash / no-ff / reject / defer | no | ≥ 1× per branch (multi-select) |
Minimum AskUserQuestion count across a full session: ≥ 6 — one batch
of five questions in Phase 1, one per spawn confirmation in Phase 2, one
polling click in Phase 3, and one per sub-branch in Phase 4 (≥ 2 branches
assumed). This is the pure-click contract: only the goal statement is
free-text.
Variables the pipeline produces
| Name | Set in | Meaning |
|---|
GOAL | Phase 1a | One-line project description |
PROJECT_TYPE | Phase 1b | new-code / research / theoretical / hybrid / documentation |
THEORY_PART | Phase 1b | none / math-derivation / prior-art / architecture-spec / paradigm-analysis |
FANOUT | Phase 1b | single / up-to-3 / up-to-5 / up-to-10 |
MAIN_AGENT | Phase 1b | meta-orchestrator / spawn specialist / compose-solution decides |
DB_MODE | Phase 1b | file-only / sqlite-ledger / external-tool |
PROJECT_SLUG | Phase 2a | kebab-case slug derived from GOAL |
PROJECT_BRANCH | Phase 2a | project/<slug> |
LEDGER_ID | Phase 2b | agent id issued via kei-ledger fork |
SUB_AGENTS | Phase 2c | list of {id, branch, kind} spawned |
PROGRESS | Phase 3 | per-sub-agent {status, pct, last_summary} aggregated |
MERGE_PLAN | Phase 4 | per-branch verdict (merge / squash / reject / defer) |
Final report (emit after Phase 4)
=== NEW-PROJECT REPORT ===
Goal: <first 80 chars of GOAL>...
Project slug: <PROJECT_SLUG>
Project branch: <PROJECT_BRANCH>
Ledger root id: <LEDGER_ID>
Sub-agents: <N spawned, M done, K failed>
Merge verdicts: <a merged / b squashed / c rejected / d deferred>
Artefact bundle: <per sub-agent — 6/6 present / missing list>
Next action: <push / open PR / rerun failed / review deferred>
Rules (apply throughout — enforced at every phase)
- Pure-click contract. Only
GOAL (Phase 1a) is typed. Every other
decision is an AskUserQuestion call.
- NO DOWNGRADE (RULE -1). Any phase that fails returns 2-3 constructive
paths, never "can't be done". E.g. Phase 2 branch-conflict → (A) rename
slug, (B) force new branch off HEAD, (C) abort — user clicks.
- NO HALLUCINATION (RULE 0.4). Every sub-agent kind referenced MUST
exist in
_manifests/ or be scheduled for creation via new-agent
before Phase 3 polling.
- Plan Mode First (RULE 0.5). This skill IS the plan; each phase file
has its own verify-criterion. No Edit/Write to production scope before
the corresponding phase's confirm click.
- Constructor Pattern (RULE ZERO).
SKILL.md < 200 LOC, phase files
< 150 LOC each.
- RULE 0.12 compliance. Every sub-agent spawn MUST:
- Create
project/<slug>/agent-<id> branch OR worktree
kei-ledger fork <id> <branch> --parent <project-branch> --spec-sha <sha>- Produce 6-file bundle in
.claude/agents/<id>/: spec.md, plan.md,
progress.json, chatlog.md, handoffs.md, review.md
kei-ledger done <id> OR kei-ledger fail <id> on completionkei-ledger validate before merge ceremony
- Surgical scope. new-project writes only to: ledger DB,
.claude/agents/<id>/
bundles it orchestrates, and a project manifest file it creates under
_manifests/project-<slug>.toml if Phase 1b MAIN_AGENT != "compose-solution decides".
References
- phase-1-intake.md · phase-2-fork-skeleton.md · phase-3-parallel-exec.md · phase-4-merge-ceremony.md
skills/compose-solution/SKILL.md — per-sub-task kit-artefact composerskills/new-agent/SKILL.md — 8-phase specialist manifest wizard_primitives/_rust/kei-ledger/ — SQLite ledger CLI (kei-ledger init / fork / done / fail / list / tree / validate)hooks/agent-fork-logger.sh — PreToolUse:Agent advisory logger (auto-fork row)~/.claude/rules/agent-git-model.md — RULE 0.12 full text (fork / sub-fork / completion / merge ceremony)
