From 4178147b0f828d4cd3b9243947b9e203a77a8247 Mon Sep 17 00:00:00 2001 From: Parfii-bot Date: Tue, 21 Apr 2026 20:52:49 +0800 Subject: [PATCH] feat(skills): /new-project 4-phase pipeline MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Hub-and-spoke orchestrator for RULE 0.12 at project scale. SKILL.md indexes 4 phase files: intake, fork-skeleton, parallel-exec, merge- ceremony. Flow: Phase 1 — 1 free-text line (GOAL) + 1 batch of 5 AskUserQuestion (type, theory, fanout, main-agent, DB mode). Phase 2 — project/ branch, kei-ledger fork root, theoretical sub-agent spawn confirmation click. Phase 3 — poll kei-ledger list --status running, aggregate progress.json, steering click (continue / add / kill / merge / pause). Phase 4 — kei-ledger validate per bundle, per-branch merge verdict click (merge --no-ff / squash / reject / defer), final integration + NO-DOWNGRADE close click if any rejected / deferred. >=6 AskUserQuestion calls minimum (1 batch Phase 1 + 1 Phase 2 + 1 Phase 3 + >=2 per-branch Phase 4 + 1 close). Constructor Pattern: SKILL.md 109 LOC, phase files 80-108 LOC each — all under 150 LOC. Co-Authored-By: Claude Opus 4.7 (1M context) --- skills/new-project/SKILL.md | 109 +++++++++++++++++++ skills/new-project/phase-1-intake.md | 92 ++++++++++++++++ skills/new-project/phase-2-fork-skeleton.md | 94 ++++++++++++++++ skills/new-project/phase-3-parallel-exec.md | 80 ++++++++++++++ skills/new-project/phase-4-merge-ceremony.md | 108 ++++++++++++++++++ 5 files changed, 483 insertions(+) create mode 100644 skills/new-project/SKILL.md create mode 100644 skills/new-project/phase-1-intake.md create mode 100644 skills/new-project/phase-2-fork-skeleton.md create mode 100644 skills/new-project/phase-3-parallel-exec.md create mode 100644 skills/new-project/phase-4-merge-ceremony.md diff --git a/skills/new-project/SKILL.md b/skills/new-project/SKILL.md new file mode 100644 index 0000000..7668097 --- /dev/null +++ b/skills/new-project/SKILL.md @@ -0,0 +1,109 @@ +--- +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: +--- + +# New-Project — 4-Phase Pipeline (index) + +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/` 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/` | +| `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: ... +Project slug: +Project branch: +Ledger root id: +Sub-agents: +Merge verdicts: +Artefact bundle: +Next action: +``` + +--- + +## 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//agent-` branch OR worktree + 2. `kei-ledger fork --parent --spec-sha ` + 3. Produce 6-file bundle in `.claude/agents//`: spec.md, plan.md, + progress.json, chatlog.md, handoffs.md, review.md + 4. `kei-ledger done ` OR `kei-ledger fail ` on completion + 5. `kei-ledger validate` before merge ceremony +- **Surgical scope.** new-project writes only to: ledger DB, `.claude/agents//` + bundles it orchestrates, and a project manifest file it creates under + `_manifests/project-.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) diff --git a/skills/new-project/phase-1-intake.md b/skills/new-project/phase-1-intake.md new file mode 100644 index 0000000..1c92d8a --- /dev/null +++ b/skills/new-project/phase-1-intake.md @@ -0,0 +1,92 @@ +# Phase 1 — Intake + +One free-text line + one click batch of 5 questions. Only Phase 1a is typed. + +## 1a — Ask for the project goal + +Emit a regular message (NOT AskUserQuestion): + +> Describe the project in one line: what do you want to produce / prove / +> ship, at what scope (feature / service / paper / proof)? Reply in one +> message. The main agent and sub-agents will read this verbatim. + +Store the reply as `GOAL`. Derive `PROJECT_SLUG = kebab-case(first 4-6 +meaningful words of GOAL)`, ≤ 40 chars, ASCII only. + +## 1b — Shape click (AskUserQuestion, ONE batch of 5) + +```json +{ + "questions": [ + { + "question": "Project type?", + "header": "Type", + "multiSelect": false, + "options": [ + {"label": "new code", "description": "Greenfield implementation — ship a running artefact"}, + {"label": "research", "description": "Empirical investigation — experiments + results doc"}, + {"label": "theoretical", "description": "Math / physics / algorithmic derivation — proofs + chatlog"}, + {"label": "hybrid", "description": "Code + theory in parallel — both tracks merged at end"}, + {"label": "documentation", "description": "Docs-only project — no new runtime code"} + ] + }, + { + "question": "Theoretical component shape?", + "header": "Theory", + "multiSelect": false, + "options": [ + {"label": "none", "description": "Pure-implementation project"}, + {"label": "math derivation", "description": "Lemma → theorem chain, reviewed by physics-deriver"}, + {"label": "prior-art research", "description": "Literature + existing-project sweep before any write"}, + {"label": "architecture spec", "description": "Design document + interface contracts before code"}, + {"label": "paradigm analysis", "description": "Observable classification + falsifier design (RULE 0.6)"} + ] + }, + { + "question": "Parallel sub-agent budget?", + "header": "Fanout", + "multiSelect": false, + "options": [ + {"label": "single", "description": "Main agent only — sequential work, no sub-forks"}, + {"label": "up to 3", "description": "Small fleet — typical feature work"}, + {"label": "up to 5", "description": "Medium fleet — multi-track research or cross-cutting refactor"}, + {"label": "up to 10", "description": "Wide fanout — parallel experiments / audits / prior-art sweeps"} + ] + }, + { + "question": "Main-agent role?", + "header": "Main", + "multiSelect": false, + "options": [ + {"label": "meta-orchestrator", "description": "Generic orchestrator that only fans out and merges"}, + {"label": "spawn specialist", "description": "Create a new dedicated agent via /new-agent before Phase 2"}, + {"label": "compose-solution decides", "description": "Hand off project shape to /compose-solution for auto-routing"} + ] + }, + { + "question": "DB / ledger mirror?", + "header": "DB", + "multiSelect": false, + "options": [ + {"label": "file-only", "description": "No SQLite — write bundle files only; skip kei-ledger"}, + {"label": "SQLite ledger", "description": "Use kei-ledger (default — RULE 0.12 compliant)"}, + {"label": "external tool", "description": "Mirror to another tracker (Jira / Linear / Forgejo issues)"} + ] + } + ] +} +``` + +Store answers as `PROJECT_TYPE`, `THEORY_PART`, `FANOUT`, `MAIN_AGENT`, +`DB_MODE`. + +## Verify-criterion + +- `GOAL` non-empty. +- `PROJECT_SLUG` matches `^[a-z0-9][a-z0-9-]{2,39}$`. +- All 5 click answers are exactly one of the labels above. +- If `MAIN_AGENT == "spawn specialist"` — Phase 2 begins with a handoff to + `/new-agent` before any ledger fork. +- If `DB_MODE == "file-only"` — Phase 2 skips the `kei-ledger fork` call + but STILL writes the 6-file bundle. Report this deviation in the final + report so the user sees the ledger SSoT was bypassed by explicit choice. diff --git a/skills/new-project/phase-2-fork-skeleton.md b/skills/new-project/phase-2-fork-skeleton.md new file mode 100644 index 0000000..9f4a0ad --- /dev/null +++ b/skills/new-project/phase-2-fork-skeleton.md @@ -0,0 +1,94 @@ +# Phase 2 — Fork Skeleton + +Create the project branch, the root ledger entry, and the first +theoretical sub-agent spawn(s) per Phase 1's `THEORY_PART` choice. + +## 2a — Project branch + +Resolve `PROJECT_BRANCH = project/`. + +Run (via Bash tool): + +```sh +git fetch origin main +git checkout -b "$PROJECT_BRANCH" origin/main +``` + +Failure modes — emit a NO-DOWNGRADE recovery AskUserQuestion: + +```json +{ + "questions": [ + { + "question": "Branch creation failed — how to proceed?", + "header": "Recovery", + "multiSelect": false, + "options": [ + {"label": "rename slug", "description": "Use a suffix (-v2, -alt) and retry"}, + {"label": "reuse existing branch", "description": "Check out the existing branch and append this work"}, + {"label": "abort project", "description": "Stop before touching the ledger"} + ] + } + ] +} +``` + +## 2b — Ledger root entry + +Skip when `DB_MODE == "file-only"`. Otherwise: + +```sh +spec_sha=$(printf '%s' "$GOAL" | shasum -a 256 | cut -c1-16) +LEDGER_ID="project-${PROJECT_SLUG}-$(date +%s)" +kei-ledger init +kei-ledger fork "$LEDGER_ID" "$PROJECT_BRANCH" \ + --parent main \ + --spec-sha "$spec_sha" +``` + +Also write the root bundle under +`.claude/agents/$LEDGER_ID/{spec.md, plan.md, progress.json, chatlog.md, handoffs.md, review.md}`. +`spec.md` = `GOAL` + 5 Phase-1 answers; others start empty / scaffolded. + +## 2c — Theoretical sub-agent spawn (AskUserQuestion, ONE) + +Branch on `THEORY_PART`. Emit this confirmation click: + +```json +{ + "questions": [ + { + "question": "Confirm theoretical sub-agent fan-out (derived from Phase 1)?", + "header": "Spawn", + "multiSelect": true, + "options": [ + {"label": "physics-deriver", "description": "Math derivation agent (only if THEORY_PART = math derivation)"}, + {"label": "research sweep", "description": "Prior-art research sub-agent (only if THEORY_PART = prior-art research)"}, + {"label": "architect", "description": "Architecture spec agent (only if THEORY_PART = architecture spec)"}, + {"label": "paradigm-classifier", "description": "Observable classification per RULE 0.6 (only if THEORY_PART = paradigm analysis)"}, + {"label": "skip theory", "description": "No theoretical sub-agent — straight to implementation fan-out"} + ] + } + ] +} +``` + +For each selected label (except `skip theory`): + +1. Derive `agent_id = -`, `agent_branch = project/$PROJECT_SLUG/agent-$agent_id` +2. `git worktree add .claude/worktrees/$agent_id -b $agent_branch` (when fanout > single) +3. `kei-ledger fork "$agent_id" "$agent_branch" --parent "$PROJECT_BRANCH" --spec-sha "$spec_sha"` (skip if file-only) +4. Invoke the Agent tool with the matching `subagent_type` and + `isolation: "worktree"` (the `agent-fork-logger.sh` hook will emit a + second fork row — OK, ledger de-duplicates by primary key and the hook + attempt returns nonzero silently) +5. Append `{id, branch, kind}` to `SUB_AGENTS` + +## Verify-criterion + +- `git branch --show-current` returns `$PROJECT_BRANCH`. +- `kei-ledger list --status running` returns ≥ 1 row whose id == `LEDGER_ID` + (unless `DB_MODE == "file-only"`). +- Every entry in `SUB_AGENTS` has a corresponding `kei-ledger list` row + with `parent_branch == $PROJECT_BRANCH`. +- If any spawn failed: emit NO-DOWNGRADE recovery click (retry / skip / abort). diff --git a/skills/new-project/phase-3-parallel-exec.md b/skills/new-project/phase-3-parallel-exec.md new file mode 100644 index 0000000..209cc2a --- /dev/null +++ b/skills/new-project/phase-3-parallel-exec.md @@ -0,0 +1,80 @@ +# Phase 3 — Parallel Execution + +Poll the ledger, aggregate progress, let the user steer the fleet mid-run. + +## 3a — Aggregate current state + +Every ~60s (or whenever the user asks "status"): + +```sh +kei-ledger list --status running +kei-ledger list --status done +kei-ledger list --status failed +``` + +For each row, attempt to read +`.claude/agents//progress.json` (written by the child every ≥ 30s per +`feedback_agent_observability`). Shape: + +```json +{ + "pct": 0..100, + "last_step": "short free text", + "wall_time_s": int, + "last_updated": iso8601 +} +``` + +Aggregate into `PROGRESS = {id: {status, pct, last_summary, stale_s}}`. +`stale_s = now - last_updated`. Flag `stale_s > 300` as "possibly hung". + +Render one-line-per-agent table: + +``` + % stale=s +``` + +## 3b — Steering click (AskUserQuestion, ONE) + +After displaying the table: + +```json +{ + "questions": [ + { + "question": "Fleet state — how to proceed?", + "header": "Steer", + "multiSelect": false, + "options": [ + {"label": "continue polling", "description": "Wait and re-poll — default if > 0 agents are running"}, + {"label": "add sub-agent", "description": "Spawn another sub-agent — returns to Phase 2c"}, + {"label": "kill stale", "description": "Call kei-ledger fail on agents with stale_s > 300"}, + {"label": "proceed to merge", "description": "All required agents done — jump to Phase 4"}, + {"label": "pause and review", "description": "Stop polling — user reviews manually, re-enter later"} + ] + } + ] +} +``` + +Route: +- `continue polling` → re-run 3a after a user-initiated "status" request + (do NOT busy-loop on a timer — let the user drive polling cadence) +- `add sub-agent` → jump to Phase 2c, add new row, return to Phase 3 +- `kill stale` → for each `stale_s > 300` running row: `kei-ledger fail --reason "stale > 300s, killed by orchestrator"` +- `proceed to merge` → Phase 4 (verify no `running` rows remain first) +- `pause and review` → emit final report with current state, user re-enters + the skill later (ledger survives) + +## Verify-criterion + +- Ledger-polling code actually called `kei-ledger list` at least once per + Phase-3 entry (unless `DB_MODE == "file-only"` — in which case the + orchestrator reads each `progress.json` directly). +- Every running sub-agent either has a fresh `progress.json` + (`stale_s < 300`) or has been flagged as "possibly hung" in the + displayed table. +- If `proceed to merge` is clicked while `kei-ledger list --status running` + is non-empty — block the transition and re-ask with the list shown. +- NO-DOWNGRADE: if every child has failed, DO NOT close the project silently. + Emit a 3-path recovery click (retry failed / re-fanout / abort with audit). diff --git a/skills/new-project/phase-4-merge-ceremony.md b/skills/new-project/phase-4-merge-ceremony.md new file mode 100644 index 0000000..5c1e00a --- /dev/null +++ b/skills/new-project/phase-4-merge-ceremony.md @@ -0,0 +1,108 @@ +# Phase 4 — Merge Ceremony + +Per-branch verdict, ledger bookkeeping, integration into the project +branch. One AskUserQuestion **per sub-agent branch** (therefore the +skill's AskUserQuestion floor rises with fanout). + +## 4a — Validate bundles first + +For every `SUB_AGENTS[i]` where status ∈ {done, failed}: + +```sh +kei-ledger validate "$agent_branch" +``` + +This verifies all 6 required artefacts exist under +`.claude/agents//`: spec.md, plan.md, progress.json, chatlog.md, +handoffs.md, review.md. + +If any agent is MISSING artefacts — mark its verdict as "reject-bundle" +and skip the per-branch click below. The final report lists them. + +## 4b — Per-branch merge click (AskUserQuestion, ONE per branch) + +For each sub-agent whose bundle is complete, emit: + +```json +{ + "questions": [ + { + "question": "Merge verdict for on (status=, summary=)?", + "header": "Verdict", + "multiSelect": false, + "options": [ + {"label": "merge --no-ff", "description": "Preserve the sub-branch history — default for substantive work"}, + {"label": "squash", "description": "Collapse into one commit on project branch — for small / fixup work"}, + {"label": "reject", "description": "Do not merge — kei-ledger rejected; branch stays for audit"}, + {"label": "defer", "description": "Leave for later — no merge, no rejection; re-enter skill next session"} + ] + } + ] +} +``` + +Execute per click: + +- `merge --no-ff` → + ```sh + git checkout "$PROJECT_BRANCH" + git merge --no-ff "$agent_branch" -m "merge($agent_id): $summary" + kei-ledger merged "$agent_id" + ``` +- `squash` → + ```sh + git checkout "$PROJECT_BRANCH" + git merge --squash "$agent_branch" + git commit -m "feat($agent_id): $summary (squashed)" + kei-ledger merged "$agent_id" + ``` +- `reject` → + ```sh + kei-ledger fail "$agent_id" --reason "rejected at merge ceremony" + # Update status table — ledger has no explicit 'rejected' from 'done', + # so we log rejection via a `fail` with reason; the row stays as audit + # evidence. (If the agent was already in 'failed' — leave as is.) + ``` +- `defer` → no git action, no ledger state change; record in `MERGE_PLAN` + as deferred so the final report reminds the user. + +## 4c — Final integration checkpoint + +After every sub-branch has a verdict: + +```sh +git checkout "$PROJECT_BRANCH" +git log --oneline -20 +kei-ledger tree "$LEDGER_ID" +``` + +Emit a final NO-DOWNGRADE click if any sub-branch was rejected or +deferred — never silently close the project: + +```json +{ + "questions": [ + { + "question": "Project state has rejected + deferred branches. Next step?", + "header": "Close", + "multiSelect": false, + "options": [ + {"label": "open PR as-is", "description": "Push project branch, open PR — rejected work is audit-logged only"}, + {"label": "retry rejected", "description": "Return to Phase 2c with the rejected sub-agents as fresh spawns"}, + {"label": "close and re-enter later", "description": "Leave project branch local; re-enter skill next session"} + ] + } + ] +} +``` + +## Verify-criterion + +- `kei-ledger list --status running` returns zero rows whose + `parent_branch == $PROJECT_BRANCH`. +- Every `SUB_AGENTS[i]` has exactly one entry in `MERGE_PLAN` — one of + `merge`, `squash`, `reject`, `defer`, `reject-bundle`. +- For every `merge` / `squash` verdict, `kei-ledger list --status merged` + contains a matching row. +- Final report cites each verdict explicitly and does NOT gloss over + rejected / deferred branches.