036bc6a52e
Group G — markdown tech-debt cleanup (post-audit 2026-05-02).
- 36 SKILL.md files: added "## When to use" section. Was missing across the
catalog; orchestrator routing by keyword could not auto-dispatch.
- 20 code-implementer agent .md files: added Output Footer block prescribing
RULE 0.16 STATUS-TRUTH MARKER schema in agent's final report. Previously only
code-implementer-rust.md had it; other 27 language/role variants were silent
about the marker, breaking RULE 0.16 §3 status-truth aggregation for non-Rust
batches.
- skills/site-create/: added phase-5-preview.md and phase-6-deploy.md skeleton
files. SKILL.md table-of-contents referenced 7 phases; only 5 existed on disk.
- skills/{ai-animation,rag-pipeline}/skill.md: added migration banner comment
noting they should be SKILL.md (canonical filename). Case-rename via git is a
separate orchestrator task (macOS APFS is case-insensitive; Linux deploy needs
explicit rename).
- 3 deprecated skills (site-builder, competitor-analysis, design-inspiration):
added concrete removed-after dates (was vague "before v2").
- docs/CONVERGENCE-PLAN.md:129: TBD on _blocks/evidence-grading.md duplicate
resolved (file exists, not duplicated).
- docs/DNA-INDEX.md: count edits made then overwritten by auto-encyclopedia-refresh
hook during agent run. The .kei-registry-ignore files in test fixtures (Group F)
are the structural fix; kei-registry walker implementation is the follow-up.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
115 lines
6.1 KiB
Markdown
115 lines
6.1 KiB
Markdown
---
|
||
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](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](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](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](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:
|
||
1. Create `project/<slug>/agent-<id>` branch OR worktree
|
||
2. `kei-ledger fork <id> <branch> --parent <project-branch> --spec-sha <sha>`
|
||
3. Produce 6-file bundle in `.claude/agents/<id>/`: spec.md, plan.md,
|
||
progress.json, chatlog.md, handoffs.md, review.md
|
||
4. `kei-ledger done <id>` OR `kei-ledger fail <id>` on completion
|
||
5. `kei-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-1-intake.md) · [phase-2-fork-skeleton.md](phase-2-fork-skeleton.md) · [phase-3-parallel-exec.md](phase-3-parallel-exec.md) · [phase-4-merge-ceremony.md](phase-4-merge-ceremony.md)
|
||
- `skills/compose-solution/SKILL.md` — per-sub-task kit-artefact composer
|
||
- `skills/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)
|