diff --git a/DEVLOG.md b/DEVLOG.md index 9ba7117..99e6ac9 100644 --- a/DEVLOG.md +++ b/DEVLOG.md @@ -5,6 +5,126 @@ Auto-maintained via [claude-devlog-skill](https://github.com/code-katz/claude-de --- +## [2026-09-09] `ck` Phase 0: six of eight spikes answered in one cloud session; the nested panel must be called by name + +**Category:** `milestone` +**Tags:** `ck`, `phase-0`, `spikes`, `workflows`, `hooks`, `review-pages` +**Risk Level:** `low` +**Breaking Change:** `no` + +### Summary +A throwaway `ck` plugin (two persona agents, two skills, two workflows, two hooks) was loaded into a nested Claude Code with `--plugin-dir` and driven non-interactively. Six of the eight Phase 0 spikes have answers; two need Will's or Clare's machine. Record: `plans/2026-09-09-ck-phase-0-spikes.md`. + +### Detail + +- **Answered yes:** `/ck:next` registers and `${CLAUDE_PLUGIN_ROOT}` expands (S1, this machine); a persona agent inside a workflow runs on its frontmatter model and a per-call `model` overrides it (S2); the `SubagentStart` hook fires for direct delegation and inside workflows, with `agent_type`, `agent_id`, `session_id`, `cwd` on stdin, and writes under `CLAUDE_PLUGIN_DATA` (S4); a neutral agent inside a nested workflow ran a real web search (S7); the extra `personas` key in `meta` loads; a plugin workflow is addressed by `name: "ck:"`. +- **One design change:** a nested workflow must be called by name, `workflow('ck:panel', args)`. Calling it by script path is refused when the plugin lives outside the working directory. The PRD's `draft.js`, `/ck:prd` skill, and §6.6 are updated. +- **From the docs (S5):** review pages work in the CLI (2.1.183 or later) and the desktop app on any paid plan; comments need 2.1.221 or later and a Team or Enterprise organization. Clare's plan is the check. +- **Still local:** the interactive consent prompt for a nested workflow (S3), a marketplace install on a second machine (S1), and Clare's CPU count (S8). + +### Decisions Made +- **Nest by name, launch by name.** `workflow('ck:panel', args)` and `Workflow({ name: "ck:draft" })`; script paths are for development only. +- **Check Clare's plan before the build.** Comments on review pages are gated by plan; the file-edit fallback stays specified at every gate. + +### Related +- Drill log and the spike plugin: `plans/2026-09-09-ck-phase-0-spikes.md`, `plans/phase-0/ck-spike/` +- PRD §8.0, §10.4, Appendix B and E updated: `plans/2026-09-05-ck-plugin-prd-phase-1.md` + +--- + +## [2026-09-09] `ck` PRD revision 3 after Will's review: `ck` independent, the full definition pipeline in phase one, Fable tier restored, Workbench committed as phase three + +**Category:** `decision` +**Tags:** `ck`, `prd`, `review`, `clare`, `pipeline`, `model-tiers`, `workbench` +**Risk Level:** `medium` +**Breaking Change:** `no` + +### Summary +Will reviewed revision 2 of the `ck` phase-one PRD on its review page and left sixteen comments. Revision 3 is a rewrite, not a patch: the old team tool is out of the picture, Clare is the primary user with two named journeys, every path is written against ``, six judgment seats return to Fable 5.1, phase one grows from four commands to the whole product-definition pipeline plus a design step, the Workbench is committed as phase three, and every review goes through Claude's built-in comment system. Each comment and the decision it drove is recorded in PRD §3.4. + +### Detail + +- **`ck` is independent.** Every coexistence and retirement passage is gone. `ck` owns `profiles/` and `tiers.conf` after a one-time import; there is no vendored copy, lock, or sync script. Uninstalling the old tool is a prerequisite, with a `SessionStart` hook that warns in plain words while it remains. +- **Clare, not "Will's wife".** Proficient with the current tool, runs many sessions at once, and her learnings drive the rebuild. Her failure mode is inconsistency, not error text. J1 (idea to definition) and J2 (feature to design mockups, the same way every time) are the acceptance journeys; efficiency (fewer sessions and hand-offs) is a goal with a measure. +- **Phase one is the pipeline:** `/ck:opportunity`, `/ck:market-research`, `/ck:brief` (with a market pass), `/ck:prd`, `/ck:team` (roles and responsibilities), `/ck:roadmap`, `/ck:architecture`, `/ck:brand-guide` (proposals, finalists, guide; modelled on the NIGHTGRID process and the d20Mob guide), `/ck:design`, plus `/ck:panel`, `/ck:next`, and 21 persona switch commands. Ten document contracts. One drafting engine (`draft.js`) serves the PRD and the architecture document. Four scripts written in full; five to the stage level. +- **Models:** Fable 5.1 for River, Akira, Morgan, Sage, Jordan, Reiner; Opus 5 for the eleven craft seats; Sonnet 5 for the four execution seats; Haiku for validators. The panel default is River on Fable, Toni on Opus, Kai moved down to Sonnet; the one override moves a lens down, never up. +- **Reviews:** Claude's built-in review and comment system, in the desktop app or at claude.ai. Every review page carries the five how-to-comment steps in its banner, because the first one did not and could not be commented on. +- **Phase two:** `/ck:feature` (explained; open for Will to pull forward), `/ck:bugfix`, `/ck:gtm`, Routines, `/ck:map`, `/ck:report`. **Phase three:** the Workbench, a rewrite replacing the conductor dashboard, local, never a hosted store. + +### Decisions Made +- **Treat `ck` as a replacement, built independently; require the old tool's removal.** Will, 2026-09-08. +- **Fable where judgment matters, Sonnet where volume matters.** Three persona tiers; stage tiers for research, validation, and synthesis. +- **The document is the state, under `/docs/`.** The cache directory holds nothing a document depends on. +- **The Workbench will be built** as phase three, after phase one has run on a real product. +- **`/ck:feature` stays in phase two.** Will, 2026-09-09, after the PRD put the question to him: it consumes phase one's documents and would double the build. + +### Related +- PRD revision 3: `plans/2026-09-05-ck-plugin-prd-phase-1.md` (§3.4 for the comment-by-comment record) +- Panel memo, §8 added for the superseded items: `plans/2026-09-05-ck-prd-panel-memo.md` + +--- + +## [2026-09-05] `ck` PRD revised after a cross-model panel: nine changes adopted, eleven rejected with reasons; review pages become the feedback channel + +**Category:** `decision` +**Tags:** `ck`, `prd`, `panel`, `cross-model-review`, `user-2`, `review-pages` +**Risk Level:** `medium` +**Breaking Change:** `no` + +### Summary +Will shared a PRD for the same plugin written by Opus, with a hand-run panel brief and five workbench mockups. Fable took the brief's engineering lens and verified the Opus PRD's load-bearing claims against the docs and the repos. Result: the `ck` PRD stays the base; nine changes are ported from the Opus PRD; eleven of its claims are rejected with the reason recorded. Will's new rule for feedback (review pages with comments; mockups as labeled variants) is written into the PRD. Record: `plans/2026-09-05-ck-prd-panel-memo.md`. + +### Detail + +- **Biggest finding against the `ck` PRD:** it named Will's wife as customer zero and then designed for Will (a ten-question interview, model names in a prompt, a hidden run directory). The Opus PRD made her the harder constraint. The `ck` PRD now has a users table, her journey, three failure rules (no stack trace, model name, or token count; always name the file holding the work; always one next action), and a done criterion: she produces a PRD on a new project without a text editor or `.ck/`. +- **Shape changes:** `/ck:brief` added before `/ck:prd`; the interview is optional; the review is a page with comments or a file edit; documents live at fixed committed paths (`docs/brief.md`, `docs/PRD.md`, `docs/decisions/`); the run directory is a cache; workflows accept a start-at stage; `/ck:next` promoted to phase one; a Phase 0 of six spikes; each panel lens reads its own evidence and sees the author's rationale only after forming a view; effort is set per workflow stage, never per persona. +- **Verified errors in the Opus PRD:** it says workflows cannot call workflows (they can, one level); it pauses a running workflow to ask about escalation (workflows accept no mid-run input, and its own principle P6 says so); its quota fallback hangs on a hook that fires only on a requested session model switch; its gates use the wrong hook for subagents; it retires team-cli at Phase 1 in one place and Phase 5 in another; it counts 22 personas (21); it retires `TODOS.md`, a shipped plugin; its workbench edits the installed plugin copy, which updates overwrite; it ignores conductor's existing cost parser. +- **Panel health:** one lens ran, so no agreement rate. The memo follows the brief's format anyway so the gaps show. + +### Decisions Made +- **Base document: the `ck` PRD.** Engineering-complete, verified, family-aware. Product thinking ported from Opus. +- **The artifact is the state.** Fixed, conventional, committed paths; the plugin keeps nothing the deliverable depends on. +- **Review pages are the feedback channel** (Will's rule). A private page with comments per review; Claude holds and resolves every comment after "done"; mockups as labeled variants side by side; a file-edit path always remains. +- **`PreModelSwitch` arbitration: answered no.** Recorded as Phase 0 spike S6 with the docs citation, so it is not re-litigated. + +### Related +- Panel memo: `plans/2026-09-05-ck-prd-panel-memo.md` +- Opus inputs, verbatim: `plans/opus/` +- Revised PRD: `plans/2026-09-05-ck-plugin-prd-phase-1.md` + +--- + +## [2026-09-05] `ck` plugin phase-one PRD: gates in skills, spans in workflows, no UI yet + +**Category:** `decision` +**Tags:** `ck`, `plugin`, `workflows`, `personas`, `prd`, `marketplace` +**Risk Level:** `medium` +**Breaking Change:** `no` + +### Summary +Turned the 2026-09-05 agent-workflows research proposal into a phase-one PRD for a single code-katz plugin named `ck`: 21 persona subagents generated from team-cli profiles, `/ck:panel` (three lenses on three models) and `/ck:prd` (River-led, panel-challenged) end to end, one instrumentation hook, no UI. Both documents are committed under `plans/`. + +### Detail + +- **Proposal §8 resolved.** Q2 (granularity) decides the shape: a sign-off is a gate in a skill, the only place `AskUserQuestion` exists; each span between gates that needs fan-out is one plugin workflow; single-agent spans run inline. Docs quote: "For sign-off between stages, run each stage as its own workflow." +- **Fifteen corrections to the proposal** are recorded in PRD §3.3. The load-bearing ones: the plugin must be named `ck` because the command prefix is the plugin name; §5.5 (each lens on a different model) contradicts §5.6 (River, Toni, Kai all on Opus 5) and is resolved by a per-invocation override in `panel.js` only; seven personas left unassigned in §5.6 are placed on Opus 5; `TaskCompleted` and `Stop` hook gates are replaced by in-workflow validation; `PreModelSwitch` does not cover subagent fallback; the roster is 21, not 22. +- **Plugin, web app, wrapper, or dashboard:** plugin. `/workflows` is the run view. A phase-two `/ck:map` renders the catalog from workflow `meta`. A workbench, if ever, is local: the viewer may read from files, the editor must run the generator and tests before a commit. Never a hosted app with its own store of definitions. +- **Harness facts** were verified against code.claude.com docs and the pricing page on 2026-09-05. Sonnet 5's scheduled price increase was cancelled, so $2/$10 stands. + +### Decisions Made +- **Marketplace publishing superseded for `ck` only.** team-cli's 2026-07-31 retirement stands for team-cli. `ck` accepts the two-character prefix because workflows and subagents need no shell CLI, and `/akira`, `launch`, and `session` stay on team-cli's install path. +- **Coexist, not retire.** `ck` is additive. Revisit at 90 days with the usage log the plugin ships. +- **All 21 personas port now; prune on evidence.** Generated from a vendored, pinned copy of team-cli profiles with a drift test. `## Required Interactive Behaviors` is rewritten mechanically to output form, because a subagent cannot ask. +- **Tiers change upstream first.** `tiers.conf` is the single source of truth. The §5.6 re-base is a prerequisite team-cli PR; `ck` copies the value verbatim. +- **New repo `code-katz/ck`, one plugin per repo,** as the eighth marketplace entry. + +### Related +- PRD: `plans/2026-09-05-ck-plugin-prd-phase-1.md` +- Proposal: `plans/2026-09-05-agent-workflows-research-and-proposal.md` +- team-cli `ROADMAP.md` revision history, 2026-07-29 and 2026-07-31 (superseded for `ck`) + +--- + ## [2026-03-22] Code Katz marketing plan fully executed: 20 blog posts, README overhauls, org infrastructure **Category:** `milestone` diff --git a/plans/2026-09-05-agent-workflows-research-and-proposal.md b/plans/2026-09-05-agent-workflows-research-and-proposal.md new file mode 100644 index 0000000..2251f8f --- /dev/null +++ b/plans/2026-09-05-agent-workflows-research-and-proposal.md @@ -0,0 +1,379 @@ +# Code Katz Agent Workflows — Research & Product Proposal + +> **Status:** proposal, ready for PRD +> **Date:** 2026-09-05 +> **Author:** Will Curran (with Claude) +> **Handoff:** intended input for Fable to turn into a PRD and build +> **Supersedes:** `claude-conductor/plans/2026-09-04-agent-coordination-engine.md` — see §9 + +--- + +## 1. How to use this document + +This is a research summary and a product proposal, not a PRD. It contains the evidence, the decisions taken and why, the proposed shape of the product, and the questions still open. It deliberately does not contain acceptance criteria, schemas beyond illustrative sketches, or sequencing beyond a rough phase order. + +Every empirical claim is graded: + +- **[M]** measured, independent, method stated +- **[V]** vendor self-measured +- **[D]** product documentation, verified against primary source on 2026-09-05 +- **[P]** practitioner assertion, no measurement + +Where the evidence is weak or absent, the document says so. Several recommendations rest on judgment rather than measurement, and those are flagged. + +--- + +## 2. Goals + +Stated by Will, in his own framing: + +1. **Enjoyment and utility.** claude-team-cli gives a sense of assigning experts to tasks in a larger project. Advance it to be as useful as possible given current models and current harness capability. +2. **Willingness to break.** The next iteration should respond to the research and to current technology. It may break from the current implementation. +3. **Customer zero: Will and his wife.** Used to build and maintain real products. The core requirement is **team members that behave consistently.** A product should start with exploration of the opportunity, then a PRD, then a branding guide — and there is a specific way a branding guide should be done, with specific expected artifacts. +4. **Adversarial and complementary input.** On a decision such as whether to include a feature, get the product lens, the marketing lens, and the UX lens. +5. **Building should be fun.** Personas make building feel exciting and engaging. +6. **Kill it if it does not help.** If this is no better — or worse — than opening Claude and working directly, say so. Challenge the affinity for personas. +7. **Current evidence only.** Ideas should be grounded in the last two months. Models and harnesses have moved. + +### 2.1 How Will works today + +Open a project. Open a session, "use Akira." Open another session, "use Toni." The repeatable activity is: open Claude to advance a project, where the work is the next stage of a project plan, plus occasional exploratory analysis. + +Named recurring jobs: market research; implement a roadmap feature (backend + frontend + UX + marketing content); fix bugs; plan the next roadmap phase; write a PRD; create a GTM plan. + +**The unit is the workflow, not the roster.** Most of these should be present in every project, run in the right order, and produce consistent output. + +--- + +## 3. The central finding + +> The persona is the interface. The artifact spec is the mechanism. The model tier is a policy decision. Today all three are conflated into a markdown profile, and only the first one is actually working. + +Three distinct claims, each with its own evidence, follow. + +### 3.1 Role-based decomposition of a single build task is worse, not merely pricier + +This was the load-bearing question, and the first answer given was wrong and had to be corrected. + +Anthropic's frequently-cited planner/implementer/tester/reviewer experiment reports **token allocation only** — no quality metric, no N, no pass rate. They assert a correctness mechanism ("each handoff degrading fidelity") but publish a cost number. **[V]** On its own it cannot settle the question, and citing it as a quality finding is over-reading. + +Independent work does measure quality: + +| Source | Method | Finding | +|---|---|---| +| arXiv 2606.00308 **[M]** | Roles ON/OFF ablation, 164 HumanEval, 1,968 paired obs, gpt-4o | Pure Analyst→Coder→Tester pipeline is **worst at 84.15%**; debugger-only configs reach **92.07%**. Persona-heavy configs produced 50–130% more complex code for zero pass@1 gain. | +| E2EDev, ACL 2026 **[M]** | 8 frameworks × 6 backbones incl. Claude Haiku 4.5 | Single-agent GPT-Engineer best on **4/6**; ChatDev falls *below* a plain single prompt on 4/6. | +| *Nature Machine Intelligence* 8(7), Jul 2026 **[M]** | 260 compute-matched configs, SWE-bench Verified + Terminal-Bench | Coordination effect ranges **+80.8% to −70.0%**. A **~45% single-agent-capability threshold** above which multi-agent is zero-to-negative; predicts the sign in **94%** of validation configs. Our tasks sit well above it. | +| CooperBench, Jan 2026 **[M]** | 600+ real OSS collaborative tasks | Agents score **~30% lower collaborating than solo**. Communication reduced merge conflicts but **did not improve success rate at all.** | + +**Mechanism.** The damage is handoff loss and Cognition's "conflicting implicit decisions" — every action silently fixes a decision the spec never named, and two agents holding different resolutions produce artifacts that are individually correct and jointly unmergeable. Full context sharing does not fix this **[P]**. This is a property of *topology*, not of the persona string. + +### 3.2 Persona strings do very little; profile *content* does the work + +Expert personas are measurably inert for correctness on frontier models: + +- Wharton *Prompting Science Report 4*, Dec 2025 **[M]** — GPQA-D + MMLU-Pro, 4,950–7,500 runs per cell, four model families: **30 expert-persona comparisons, one significant, and it is negative.** +- Zheng et al., Findings of EMNLP 2024 **[M]** — 162 personas × 2,410 MMLU questions × 9 models: no significant difference vs control; in-domain match worth **+0.4pp**. +- CodePromptEval, IEEE TSE **[M]** — 63,648 functions: persona has **no statistically significant impact on correctness**, but **does** measurably reduce code smells and complexity. + +**Read this carefully, because it is easy to misread as "drop the personas."** What it says is that "you are a senior backend engineer" buys nothing. What buys something is the *content* of the profile — Akira's "as much as needed, as little as possible" principle, a specific API-design checklist, a required output shape. The persona is a container. Today some of Code Katz's 22 profiles are full of real constraints and some are closer to character description. That ratio is the actual lever. + +And the null results are all on single-turn QA or single-function generation. **Nobody has measured persona effects on multi-turn agentic work or on judgment/creative tasks.** Extending these findings to "personas don't help Will pick a positioning angle" would be reasoning from analogy, not evidence. + +### 3.3 Where spending more genuinely buys better work + +| Intervention | Evidence | Effect | +|---|---|---| +| Cross-model review | arXiv 2607.21656, Jul 2026, 116 LiveCodeBench tasks **[M]** | Claude Opus 4.7 reviewing Codex GPT-5.5: **+18.1pp** (p=.0010) | +| Same-model self-review | same study **[M]** | Claude Opus 4.7 on own output: 3 fixes, 3 regressions, **±0, at +72% cost** | +| External oracle vs LLM critique | Stechly et al., ICLR 2025 **[M]** | GPT-4 Game of 24: 5% → **3%** with self-critique → **36–38%** with a sound external verifier | +| Cheap verification pre-pass | AgentGUI, ETH Zürich, Jul 2026 **[M]** | Completion **44%→78%** on a 4B worker, manager tokens **0.19–0.56%** of total | +| One-at-a-time human review | AgentGUI, N=8 within-participant **[M]** | **38% faster** (90s vs 145s, p=0.023), accuracy **93% vs 80%** (p=0.031), lower NASA-TLX. Small sample; authors flag limited power | + +**Conclusion:** buy quality with a *different model checking against a real oracle*, and with more thinking inside one agent. Do not buy it with more job titles. + +### 3.4 What this means for the goals + +| Goal | Verdict | +|---|---| +| 3 — consistency | **Not an agent problem.** Consistency comes from an artifact template plus a checklist plus a gate. The five existing Code Katz skills each own a file format, and that is exactly why their output is stable. The personas own no artifacts, which is exactly why theirs varies. | +| 4 — multi-lens panels | **Supported, with one correction.** This is not decomposition; it is coverage of considerations on a judgment call, which the null results do not touch. But lenses must run on **different models** — >350 models agree 60% of the time *when both are wrong*, and error correlation rises with capability **[M]**. Same model in three costumes is one opinion. | +| 5 — fun | **Legitimate and load-bearing.** Retention is the real success metric for a personal tool; an optimal tool that goes unused is worth nothing. But the fun should come from real disagreement between lenses, not a name badge on identical output. | +| 6 — the challenge | **Personas earn their cost at phase transitions and panels, not at task execution.** Inside an established context on a single task, opening Claude directly wins: `claude-team launch` means fresh context, and re-explaining the project costs more than the specialist adds. If the next iteration does not make that distinction structural, it is a tax with a nicer wrapper. | + +--- + +## 4. Platform capabilities, verified 2026-09-05 + +All **[D]**, verified against primary docs on the date above. This section is the reason the earlier plan is obsolete: most of what it proposed to build now ships natively. + +### 4.1 Dynamic workflows — the key primitive + +A dynamic workflow is a **JavaScript script that orchestrates many subagents**, written by Claude, executed by a runtime *outside the conversation context*. Only the final answer enters context. + +```javascript +export const meta = { + name: 'audit-routes', + description: 'Audit every route handler for missing auth checks', +} + +const found = await agent('List every .ts file under src/routes/.', { + schema: { type: 'object', required: ['files'], + properties: { files: { type: 'array', items: { type: 'string' } } } }, +}) + +const audits = await pipeline(found.files, file => + agent(`Audit ${file} for missing authentication checks.`, { label: file }), +) + +return audits.filter(Boolean) +``` + +Primitives available in the script body: `agent()` spawns one subagent, `pipeline()` runs one per list item, `parallel()` runs a set concurrently, `phase()` groups agents in the progress view, `log()` emits a message, and `args` is a global carrying invocation input. + +**Repeatability — this is the whole answer to goal 3.** Run `/workflows`, select a run, press `s`, and the script saves to `.claude/workflows/` (repo-shared) or `~/.claude/workflows/` (personal). It then runs as `/` in every future session. + +**Distribution.** Place a script in `workflows/` at a plugin root and it is namespaced: a plugin `acme-tools` with `meta.name: release-audit` runs as `/acme-tools:release-audit`. + +**Constraints that shape the design:** + +| Constraint | Consequence | +|---|---| +| **No mid-run user input.** Docs: *"For sign-off between stages, run each stage as its own workflow."* | **Goal 5 is a decomposition rule, not a feature.** Every stage requiring Will's sign-off must be its own workflow. | +| Up to 16 concurrent agents; 1,000 agents per run; 4,096 items per `parallel()`/`pipeline()` | Generous. Not a binding limit for this use case. | +| `Date.now()`, `Math.random()`, no-arg `new Date()` **throw** inside scripts | Enforced determinism so a relaunched run repeats the same calls. Pass timestamps via `args`. | +| No module loading; no direct filesystem or shell access from the script | The script coordinates; agents do the work. | +| Resumable **within the same session**. A failed agent reruns, and so does every agent that started after it | A mid-fan-out failure reruns completed work. Prefer smaller workflows. | +| Size guideline in `/config`: `small` <5, `medium` <15 (default), `large` <50 agents | Set per workflow expectation. | +| Warning at >25 agents or >1.5M projected tokens | Advisory only, does not pause. | + +**Prompt caching.** In a fan-out, agents sharing model + effort + agent type + tools + output schema + cwd build the same prefix; the runtime holds all but the first until the first response begins so the rest read a warm cache. Default stagger cap 5000ms. Workflow agents sit outside the main conversation's cache TTL bucket — 5 minutes by default, settable to `1h` via `subagentPromptCacheTtl`. + +**Bundled:** `/deep-research` — fans out web searches across angles, cross-checks sources, votes on claims, returns a cited report with unsurvived claims filtered out. This is a working reference implementation for the market-research workflow. + +**Authoring:** `/workflow-authoring` bundled skill (v2.1.248+) loads the script-writing reference before editing a saved script. + +### 4.2 Subagents — the persona vehicle + +`agents/*.md` frontmatter supports `name`, `description`, `tools`, `disallowedTools`, `model`, `effort`, `maxTurns`, `maxBudgetUsd`, `skills`, `memory`, `background`, and `isolation: worktree`. + +`model` accepts family aliases (`sonnet`, `opus`, `haiku`, `fable`), `inherit`, or a full ID. Only the subagent's **final message** returns to the caller; intermediate tool calls stay inside. Limits: `CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS` (20), `CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION` (200), `CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH` (3). + +**`isolation: worktree` is available to subagents and not to teammates.** This is the single most important asymmetry for parallel implementation work. + +### 4.3 Agent Teams — verified, and not the executor + +Experimental, disabled unless `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`. + +**What it genuinely provides:** a shared task list with claiming and dependency tracking (a pending task with unresolved dependencies cannot be claimed); direct teammate-to-teammate messaging via mailbox JSON at `~/.claude/teams/{team}/inboxes/{agent}.json`; per-teammate models; roles drawn from subagent definitions; `TaskCreated` / `TaskCompleted` / `TeammateIdle` hooks where exit code 2 blocks and returns feedback. + +**Why it is not the executor for shipped pipelines:** + +1. **Cannot be packaged or versioned.** Team config holds live runtime state — session IDs, tmux pane IDs — and the docs say do not hand-author or pre-author it. There is no project-level equivalent; `.claude/teams/teams.json` is treated as an ordinary file. A team is convened, never shipped. +2. **Cannot run unattended.** *"In non-interactive mode with the `-p` flag, including Agent SDK sessions, Claude doesn't spawn teammates."* No scheduled or headless runs, ever. +3. **No source-file protection.** File locking exists **only for task claiming**. On source files: *"Two teammates editing the same file leads to overwrites. Break the work so each teammate owns a different set of files."* No worktree option. +4. **Documented breakage on routine operations.** `/resume` and `/rewind` do not restore in-process teammates; task status lags and blocks dependents; shutdown is slow; one team per session; no nested teams; lead is fixed; teammates cannot spawn background subagents. +5. **Enabling it changes unrelated behavior.** Any subagent Claude names launches as a teammate, so teams form when not requested. + +**Where Teams is right.** The docs' own headline examples are goal 4 — *"one on UX, one on technical architecture, one playing devil's advocate"*, a three-lens parallel PR review, and adversarial competing-hypothesis debugging. For **ad-hoc exploration where the decomposition is unknown**, Teams is the better tool. For anything repeatable, Workflows win because they can be saved and shipped. + +### 4.4 Plugins, skills, hooks + +**Plugins** bundle skills, commands, agents, hooks, MCP servers, LSP servers, output styles, background monitors, and **workflows**, via `.claude-plugin/plugin.json`, distributed through a GitHub or GitLab marketplace. This is the distribution unit; it replaces `install.sh`, symlinking, and sync logic entirely. + +**Skills** — `SKILL.md` with frontmatter supporting `name`, `description`, `allowed-tools`, `model`, `disable-model-invocation`, `argument-hint`. `context: fork` runs a skill as a subagent with no conversation history; `agent:` selects the subagent type. Since Jul 2026 forked skills run in the background by default. + +**Hooks** — the enforcement layer. `TaskCreated`, `TaskCompleted`, `TeammateIdle`, `SubagentStart`, `SubagentStop`, `Stop`, `PreToolUse`/`PostToolUse`, `SessionStart`/`SessionEnd`, `PreCompact`/`PostCompact`, and — new in Aug 2026 — **`PreModelSwitch`/`PostModelSwitch`**, which can block, confirm, or annotate a model switch. `PreToolUse` can rewrite tool arguments and its `deny` holds even under bypass-permissions. + +**Output styles do not reach subagents.** They apply to the main conversation only and are fixed at session start. **Artifact consistency must therefore come from skill bodies plus hooks, not from a style.** + +**Routines** — GA on Pro/Max/Team/Enterprise. Cloud-run automations triggered by schedule, API call, or GitHub event. The path to unattended pipeline runs. + +**Advisor tool** — experimental, Anthropic API only. Lets a cheaper executor consult a stronger model at decision points with full conversation context. **[V]** +2.7pp SWE-bench Multilingual at −11.9% cost. Relevant to the routing goal: it escalates *without* a model switch, so it sidesteps the context-rebuild cost entirely. + +### 4.5 Model lineup — the tier map is stale + +| Model | ID | In/Out $/MTok | Cache read | Context | Position | +|---|---|---|---|---|---| +| Fable 5.1 | `claude-fable-5-1` | $10 / $50 | **0.025×** | 1M | Hours-long agent sessions, multistep deep research | +| Opus 5 | `claude-opus-5` | $5 / $25 | 0.1× | 1M | Complex agentic coding, systems engineering, vision-heavy | +| Sonnet 5 | `claude-sonnet-5` | $2 / $10 | 0.1× | 1M | Everyday coding, data analysis, content creation | +| Haiku 4.5 | `claude-haiku-4-5-20251001` | $1 / $5 | 0.1× | 200K | Real-time, high-volume, sub-agent tasks | + +**Changed in the last eight weeks:** Opus 5 launched Jul 24 as the coding flagship at half Fable's price. Fable 5.1 launched Sep 1 with a **4× cache-read price cut**. Sonnet 5's $2/$10 was made permanent Sep 1 — the scheduled increase to $3/$15 was cancelled. Opus 4.1 retired Aug 5. Sonnet 4.5's retirement window opens **Sep 29, 2026**. + +`tiers.conf` currently references `claude-fable-5` and `claude-opus-4-8`. Both are legacy. **Opus 5 should absorb most of what currently routes to Fable.** + +--- + +## 5. Proposal: the `code-katz` plugin + +### 5.1 Shape + +Retire the bash CLI. Ship one installable plugin containing four component types: + +``` +code-katz/ +├── .claude-plugin/plugin.json +├── workflows/ # the product: named, ordered, repeatable pipelines +│ ├── opportunity.js ├── prd.js ├── brand-guide.js +│ ├── roadmap.js ├── feature.js ├── bugfix.js +│ ├── gtm.js ├── market-research.js +│ └── panel.js +├── agents/ # the roster: 22 personas as subagent definitions +│ ├── akira.md ├── sasha.md ├── river.md ├── toni.md ├── kai.md … +├── skills/ # the artifact contracts (templates + checklists) +│ ├── prd/SKILL.md ├── brand-guide/SKILL.md ├── gtm/SKILL.md … +└── hooks/ # the gates + └── hooks.json # TaskCompleted / Stop → artifact validators +``` + +The five existing skill repos (`plans`, `todo`, `roadmap`, `devlog`, `publish`) fold in as the artifact contracts they already are. + +### 5.2 The four layers, and what each is for + +| Layer | Primitive | Owns | Why here | +|---|---|---|---| +| **Workflow** | `workflows/*.js` | The order of stages | Repeatable, versioned, shippable, runs outside context. Goal 3. | +| **Persona** | `agents/*.md` | Voice, domain constraints, model tier | Fun and intent expression (goals 1, 5); model policy (goal 2) | +| **Artifact** | `skills/*/SKILL.md` | Output template + checklist | The actual mechanism of consistency (§3.2) | +| **Gate** | `hooks/hooks.json` | Rejection of malformed output | Enforcement; personas cannot be trusted to self-certify | + +The design intent: **a persona without an artifact contract is decoration.** Every workflow stage names an owning persona *and* the artifact skill it must produce into. + +### 5.3 Workflow catalog + +Each is one workflow. Each stage boundary that needs Will's sign-off is a workflow boundary, because workflows accept no mid-run input (§4.1). + +| Command | Purpose | Owner persona | Artifact | +|---|---|---|---| +| `/ck:opportunity` | Explore the opportunity before committing | River | `opportunity-brief.md` | +| `/ck:market-research` | Competitive and market scan | River + Toni | `market-research.md` | +| `/ck:prd` | Product requirements | River | `PRD.md` | +| `/ck:brand-guide` | Brand and visual system | Iris + Kai | `brand/` asset set + `brand-guide.md` | +| `/ck:roadmap` | Plan or re-plan the next phase | River + Quinn | `ROADMAP.md` (existing skill) | +| `/ck:feature` | Implement a roadmap item end to end | per slice | code + tests + docs | +| `/ck:bugfix` | Diagnose and fix | Robin → owner | fix + regression test | +| `/ck:gtm` | Go-to-market plan | Toni | `gtm.md` | +| `/ck:panel` | Multi-lens decision input | 3 lenses | decision memo | + +The natural project order is `opportunity → market-research → prd → brand-guide → roadmap → feature*`, with `panel` callable at any point. **Recommendation: do not hard-wire the order in code.** Ship it as documented convention plus a `/ck:next` helper that reads which artifacts exist and suggests the next stage. Hard sequencing would fight exploratory use, which is goal 1. + +### 5.4 `/ck:feature` — the one with real parallelism + +The only workflow where the build-topology research binds. Structure: + +1. **Plan phase** (Opus 5, one agent) — decompose the feature into **vertical slices**, each owning a feature plus its tests plus its docs. Emit an interface contract naming every decision two slices could otherwise resolve differently: exact signatures, the enumerated error set, canonical entity names, single file ownership. Freeze it. +2. **Build phase** — `parallel()` over slices, one persona each, each subagent declared `isolation: worktree`. One writer per slice. No mid-feature handoffs. +3. **Verify phase** — per slice, a gate agent on a **different persona and a different model tier** than the writer, whose job is to *run the oracle*, not to opine. Carries the anti-early-victory instruction verbatim: *"You MUST run the complete test suite before marking as passed."* +4. **Merge** — sequential, one at a time, base suite as the gate. + +Parallelize only when the interface contract exists. Absent it, run sequential — §3.1 is unambiguous that unshared implicit decisions are what break parallel builds. + +### 5.5 `/ck:panel` — goal 4 + +The one piece with no native primitive, and the one Will will feel most day to day. + +- Three lenses, invoked on one question: **product** (River), **marketing** (Toni), **UX** (Kai). +- **Each lens runs on a different model.** Not negotiable — same model in three costumes is one opinion, and error correlation rises with capability **[M]**. +- Each lens must return, in a fixed schema: its recommendation, its **strongest argument against its own recommendation**, and **the specific condition that would make it say no**. Forcing the disagreement is the point; three approvals is a failed panel. +- A synthesis agent surfaces *where the lenses disagree* and does not resolve it. The decision is Will's. + +The workflow runtime explicitly supports this shape: *"it can have independent agents adversarially review each other's findings before they're reported, or draft a plan from several angles and weigh them against each other."* + +### 5.6 Proposed tier re-base + +Simplify from three tiers across 22 personas to a policy with four positions: + +| Tier | Model | Assign to | +|---|---|---| +| Deep research | Fable 5.1 | `/ck:market-research`, `/ck:opportunity` deep passes only | +| Judgment | **Opus 5** | Akira, River, Toni, Kai, Iris, Morgan, Sage, Jordan, Quinn, Casey — most of what is currently Fable **or** Opus 4.8 | +| Execution | Sonnet 5 | Sasha, Alex, Robin, Piper, and all high-volume implementation | +| Classification | Haiku 4.5 | Routing, status rollups, summarization, `/ck:next` | + +Opus 5 becomes the default judgment tier. Fable 5.1 is reserved for genuinely long-horizon research, where its 4× cache-read discount also does the most good. + +**Keep tiers.conf as declared intent** and treat the resolved model as separate, recorded per run. Two additions: + +- **Fallback chain** (`fable-5-1 → opus-5 → sonnet-5`) with quota/429 detection, using the new `PreModelSwitch` hook as the enforcement point. This fixes the observed failure where an Akira delegation pinned to Fable died on quota exhaustion and had to be rerun by hand. +- **Prefer the Advisor tool over a model switch** where available. Escalating within a task avoids the context-rebuild cost entirely, which is the correct answer to the "switching is not free" objection. + +### 5.7 Artifact contracts + +For each artifact, the skill defines: the section structure, the required fields, the file path convention, and a **machine-checkable validator**. The hook (`TaskCompleted` or `Stop`, exit code 2) rejects malformed output and returns the specific failure. + +This is where goal 3 is actually satisfied. "There is a specific way I like a branding guide" becomes a template plus a checklist plus a validator — not a personality trait of Iris. + +--- + +## 6. What we are deliberately not building + +| Not building | Because | +|---|---| +| A bash orchestrator | Dynamic workflows are the orchestrator, and they are saveable and shippable | +| A custom task graph, lock protocol, or state file | Workflow scripts hold state in script variables; the runtime handles resumption | +| An Agent Teams executor for shipped pipelines | §4.3 — unpackageable, interactive-only, no source-file protection, documented breakage | +| A model picker | The thesis is that the user expresses intent and policy resolves the model | +| Role pipelines for building a single feature | §3.1 — measured 8–40pp worse at 3–10× the tokens | +| A bandit router | No outcome data yet. A bandit with no data is a random number generator. Revisit after telemetry exists | +| Free-form inter-agent chat | CooperBench: communication reduced conflicts, did not improve success **[M]** | +| A batch review mode | §3.3 — one at a time is 38% faster and 13pp more accurate | + +--- + +## 7. Honest assessment against goal 6 + +**Where this beats opening Claude directly:** + +- Phase transitions. Starting a PRD from a fresh context with a template and a checklist is genuinely better than continuing a conversation that has drifted. +- Repeated multi-stage jobs. `/ck:prd` producing the same shape every time, in every project, is a real gain over remembering how you did it last time. +- Panels. Three lenses on different models surfaces considerations one session will not. +- Fan-out work. Auditing 40 route handlers is what workflows are for. + +**Where it does not, and should not be used:** + +- Any single task inside a context you are already deep in. Fresh context costs more than the specialist adds. +- Small changes. The coordination overhead exceeds the benefit. +- Work where the decomposition is unknown. Use a team, or just work directly. + +**The specific risk to watch:** 22 personas is likely 15 more than are used. Unused personas are maintenance surface and choice paralysis. Recommendation for the PRD: instrument which personas and workflows actually get invoked, and prune on evidence after 90 days. + +--- + +## 8. Open questions for the PRD + +1. **Retire or coexist?** Does `claude-team-cli` get archived once the plugin ships, or does the CLI remain for the `/akira`-in-current-session route? The three-route model (current context / fresh context / separate session) is good and should survive in some form. +2. **Workflow granularity vs sign-off.** Because workflows take no mid-run input, every sign-off point is a workflow boundary. Is `/ck:prd` one workflow, or `prd-draft` → review → `prd-finalize`? This is the highest-leverage open design question. +3. **Where do artifacts live?** Repo-relative (`docs/`, `brand/`) or a `.code-katz/` directory? Committed, presumably — confirm. +4. **Which personas survive?** A proposed cut list based on 90-day usage should precede the port, not follow it. +5. **Panel model assignment.** Which three models for the three lenses? Constrained to the Claude family, decorrelation is imperfect — all share one training pipeline. Worth stating that limitation explicitly. +6. **`/ck:feature` scope.** Full end-to-end including marketing copy, or code-only with content as a separate workflow? +7. **Routines integration.** Which workflows, if any, should run scheduled or on GitHub events? +8. **Verification for non-code artifacts.** A test suite is a real oracle. What is the oracle for a brand guide? Probably a structural validator plus Will's review — which means non-code stages lean harder on the human gate, and should be sized accordingly. + +--- + +## 9. Relationship to the previous plan + +`claude-conductor/plans/2026-09-04-agent-coordination-engine.md` proposed extending claude-conductor with a task graph, a spawn wrapper, a routing module, and a coordination UI, executing via Agent Teams. **That plan is substantially obsolete.** Dynamic workflows, packageable in a plugin, provide the orchestration, the repeatability, the distribution, and the resumption it proposed to build. Agent Teams is the wrong executor for the reasons in §4.3. + +Two things from it survive and should carry forward: + +- **The conductor bug findings.** `update_session_field` and `insert_active_row` both write a fixed `.tmp` then `mv`, with no lock — two concurrent writers destroy each other. And `dashboard/watcher.js:134` filters empty cells while the four awk parsers are positional, so a row with an empty Notes field is already parsed differently by the two. Both are real and worth fixing regardless of this proposal. +- **The coordination UI question.** Workflows have a built-in progress view (`/workflows` — phases, agent counts, token totals, elapsed time, drill-down to any agent's prompt and result). **Recommendation: use it and do not build a UI until it proves insufficient.** Goal 6 applies to the UI as much as to the personas. + +--- + +## 10. Sources + +**Platform documentation** — all verified 2026-09-05: +[Agent teams](https://code.claude.com/docs/en/agent-teams) · [Dynamic workflows](https://code.claude.com/docs/en/workflows) · [Subagents](https://code.claude.com/docs/en/sub-agents) · [Skills](https://code.claude.com/docs/en/skills) · [Plugins reference](https://code.claude.com/docs/en/plugins-reference) · [Hooks](https://code.claude.com/docs/en/hooks) · [Routines](https://code.claude.com/docs/en/routines) · [Advisor tool](https://code.claude.com/docs/en/advisor) · [Prompt caching](https://code.claude.com/docs/en/prompt-caching) · [Pricing](https://platform.claude.com/docs/en/about-claude/pricing) · [Model deprecations](https://platform.claude.com/docs/en/about-claude/model-deprecations) + +**Measured research:** +[Capable language models can outgrow the benefits of collaboration](https://www.nature.com/articles/s42256-026-01268-y), *Nature Machine Intelligence* 8(7), Jul 2026 · [How Generation Architecture Shapes Code Complexity](https://arxiv.org/abs/2606.00308) · [E2EDev](https://arxiv.org/abs/2510.14509), ACL 2026 · [CooperBench](https://cooperbench.com/), Jan 2026 · [Why Do Multi-Agent LLM Systems Fail? (MAST)](https://arxiv.org/abs/2503.13657) · [AgentGUI](https://arxiv.org/html/2607.26300v1), ETH Zürich, Jul 2026 · [Cross-Model LLM Code Review](https://arxiv.org/abs/2607.21656), Jul 2026 · [Expert Personas Don't Improve Factual Accuracy](https://arxiv.org/abs/2512.05858), Wharton, Dec 2025 · [Personas in System Prompts Do Not Improve Performance](https://arxiv.org/abs/2311.10054), EMNLP 2024 · [Impact of Prompt Programming on Function-Level Code Generation](https://arxiv.org/abs/2412.20545), IEEE TSE · [Stechly et al.](https://arxiv.org/abs/2402.08115), ICLR 2025 · [Great Models Think Alike](https://arxiv.org/abs/2502.04313), ICML 2025 + +**Position pieces:** +[Building multi-agent systems: When and how to use them](https://claude.com/blog/building-multi-agent-systems-when-and-how-to-use-them), Anthropic, Jan 2026 · [How we built our multi-agent research system](https://www.anthropic.com/engineering/multi-agent-research-system), Anthropic, Jun 2025 · [Don't Build Multi-Agents](https://cognition.com/blog/dont-build-multi-agents), Cognition, Jun 2025 · [The model picker is a dead end](https://lovable.dev/blog/the-model-picker-is-a-dead-end), Lovable + +**Prior art reviewed:** [ruvnet/ruflo](https://github.com/ruvnet/ruflo) — renamed from claude-flow; task DAG and complexity-bucketed Thompson-bandit router are worth studying, but its own commissioned audit found headline performance multipliers unsubstantiated and one fabricated at runtime. Do not copy its template decomposition or its executor-less agent pool. diff --git a/plans/2026-09-05-ck-plugin-prd-phase-1.md b/plans/2026-09-05-ck-plugin-prd-phase-1.md new file mode 100644 index 0000000..e280c55 --- /dev/null +++ b/plans/2026-09-05-ck-plugin-prd-phase-1.md @@ -0,0 +1,2426 @@ +# `ck` Plugin, Phase One: Product Requirements Document + +> **Status:** PRD, revision 3, ready for build +> **Date:** 2026-09-08 (first version 2026-09-05) +> **Author:** Fable (with Will Curran) +> **Derives from:** [`plans/2026-09-05-agent-workflows-research-and-proposal.md`](2026-09-05-agent-workflows-research-and-proposal.md) (the research proposal) +> **Scope:** phase one: the plugin skeleton, the full product-definition pipeline (`/ck:opportunity`, `/ck:market-research`, `/ck:brief`, `/ck:prd`, `/ck:team`, `/ck:roadmap`, `/ck:architecture`, `/ck:brand-guide`, `/ck:design`), `/ck:panel`, `/ck:next`, and 21 personas as subagents and switch commands on three model tiers. Phases two and three are in §10 +> **Revision history:** rev 2 (2026-09-05) after a cross-model panel against the Opus-written PRD, see [`plans/2026-09-05-ck-prd-panel-memo.md`](2026-09-05-ck-prd-panel-memo.md); rev 3 (2026-09-08) after Will's sixteen-comment review of rev 2, see §3.4 + +--- + +## 0. How to read this document + +### 0.1 Grading + +Every claim carries the proposal's grade, plus two more: + +| Grade | Meaning | +|---|---| +| **[D]** | Product documentation, verified against the primary source on 2026-09-05. The URL is in Appendix J | +| **[M]** | Measured, independent, method stated (carried over from the proposal) | +| **[V]** | Vendor self-measured | +| **[R]** | The family's own record: a devlog entry, roadmap revision, or test in a code-katz repo | +| **[W]** | Will's decision, recorded with its date. Not open to challenge in this document | +| **[P]** | Practitioner assertion or judgment call. Open to challenge; the rationale is stated | + +### 0.2 What this document is + +The proposal is a research summary with a proposed shape. This is the specification for the first release of that shape: what ships, what each command must do, what each document it produces must contain, how it is tested, and what is deliberately left for phases two and three. It contains acceptance criteria, schemas, four complete workflow scripts, two complete skills, and two complete document contracts, as appendices. The remaining workflows are specified to the stage level in §6; their scripts are build work that follows the four written here. + +### 0.3 Three words that mean one thing each + +| Word | Meaning in this document | +|---|---| +| `` | The git repository of the product being built: the folder where Claude Code was opened. Every document `ck` produces is written here and committed here. It is never the plugin's own directory and never the home directory. See §4.3 | +| Gate | A point where a person reviews and decides. Gates run in the main session, never inside a workflow, because a workflow cannot pause for input [D]. See §4.2 | +| Review page | Claude's built-in review and comment system: a private page in the Claude desktop app or at claude.ai, with comment mode. Every document or gallery that needs a decision is reviewed there. See §4.9 | + +### 0.4 The three answers up front + +1. **It is a plugin, and a Workbench follows it.** Claude Code is the runtime for subagents, workflow scripts, and skills; nothing else can run them. Phase one ships the plugin with no UI. Phase three rewrites the conductor dashboard as the `ck` Workbench: catalog, runs, cost, and persona and workflow editing against the plugin's source checkout, running locally. See §4.7 and §10.3. +2. **The skill owns the gates; each span between gates is one workflow.** A sign-off point is not a workflow. It is a gate: a review page with comments, or a file the author edits. See §4.2. +3. **`ck` is independent.** It replaces `claude-team-cli`, owns its persona definitions, and requires that `claude-team-cli` be uninstalled before use. Nothing in this document depends on, defers to, or coexists with it. [W, 2026-09-08] + +--- + +## 1. Summary + +`ck` is a Claude Code plugin. Phase one ships: + +| Component | Count | What it is | +|---|---|---| +| Persona subagents | 21 | `agents/.md`, generated from `ck/profiles/`, registered as `ck:`, on three model tiers: Fable 5.1 for judgment, Opus 5 for craft, Sonnet 5 for execution (§5.3) | +| Persona switch commands | 21 | `/ck:`, generated from the same profiles, for the session-switch route that `claude-team-cli` used to provide (§5.6) | +| Pipeline commands | 9 | `/ck:opportunity`, `/ck:market-research`, `/ck:brief`, `/ck:prd`, `/ck:team`, `/ck:roadmap`, `/ck:architecture`, `/ck:brand-guide`, `/ck:design`: the definition pipeline from an idea to a designed feature, each writing one committed document or gallery into `` (§6) | +| Decision and navigation commands | 2 | `/ck:panel` (three lenses on three models argue one question; a memo shows where they disagree) and `/ck:next` (says what to run next in one sentence) | +| Document contracts | 10 | One skill per document type: section order, required fields, checklist. Consistency comes from these, not from who writes (§7) | +| Workflow scripts | 9 | `panel`, `brief`, `draft` (serves the PRD and the architecture document), `team`, `opportunity`, `market-research`, `roadmap`, `brand`, `design` | +| Hooks | 2 | `SubagentStart` on `^ck:` appending one line per persona invocation to a usage log; `SessionStart` warning in plain words if `claude-team-cli` is still installed | +| Tests | 1 suite | Manifest, generation drift, script lint, contract-to-script consistency, plain-language checks, Phase 0 answers, end-to-end drills (§9) | + +What changed in revision 3, from Will's review (§3.4): `ck` no longer references `claude-team-cli` except to require its removal; Clare is named as the primary user and her two journeys drive the design; every path is written as `/...`; the Fable tier is restored for the six judgment seats; phase one grows from four commands to the full definition pipeline; the Workbench is committed as phase three; and every review happens in Claude's built-in comment system. + +Phase two is `/ck:feature`, `/ck:bugfix`, `/ck:gtm`, Routines, `/ck:map`, and `/ck:report`. Phase three is the Workbench. Both are in §10 with the reason for each placement. Will confirmed on 2026-09-09 that `/ck:feature` stays in phase two. + +--- + +## 2. Problem, users, journeys, goals + +### 2.1 Problem + +The unit of the work is the workflow, not the roster (proposal §2.1). Today the personas exist only as session takeovers and delegation subagents. They own no documents, so their output varies run to run (proposal §3.4). Multi-lens input on a decision means opening three sessions by hand, and the three lenses run on one model, which is one opinion in three costumes (proposal §3.4; [M] error correlation rises with capability). Nothing is repeatable across projects, and nothing is measured, so the persona question ("likely 15 more than are used", proposal §7) cannot be answered. + +The person who feels this most is not Will. It is Clare, who runs the current tool every day. + +### 2.2 Users + +| | Clare | Will | +|---|---|---| +| Technical? | No. She has shipped several iOS apps with Claude and `claude-team-cli`, and has become proficient with it: she knows which workflows, process, and documents a product needs | Yes. Reads and writes code; maintains the plugin | +| How she works | Runs many sessions at once, one persona per session, and hands work between them by hand | One session at a time, plus panels on decisions | +| Wants | The same, efficient, high-fidelity process every time: an idea to a definition, a feature to design mockups, without re-explaining the process to each persona | Repeatability, adversarial input on decisions, visibility into cost and activity, a place to tune personas | +| Tolerates | Plain language and one command at a time. Model names are fine when they explain a cost; she does not need to choose one | Flags, JavaScript, terminal output, cost decisions | +| Fails when | Workflows, personas, and documents are inconsistent: the same step produces a different shape, asks different questions, or needs a different number of sessions than last time | The tool is slower than doing it himself | + +The rebuild is based on Clare's learnings from running the current tool. Two things follow. First, she is the primary user, and a phase-one command is done when it works for her from the README alone. Second, she is not fragile: she does not need to be protected from the tool, she needs it to be consistent and to cost her fewer sessions. Her persona work should take fewer hand-offs than it does today. [W, 2026-09-08] + +### 2.3 Journeys + +**J1. Clare takes a new product from an idea to a definition.** The primary journey. Phase one is done when it works end to end on a new project. + +1. She has an idea. She creates a folder, opens Claude Code in it, and runs `/ck:next`. It sees an empty project and says: "Start with `/ck:opportunity` and describe your idea in a sentence. It writes `docs/opportunity.md`: what the product is, who it is for, what the market looks like, and whether it is worth doing." +2. She runs `/ck:opportunity `. River frames it, Toni writes the market context and positioning, Akira the technical shape, and the domain seat (a game designer, for a game) its own section. River assembles the analysis with stage gates, risks, and open questions. A review page opens. She comments where she disagrees and says "done". Claude applies every comment, republishes, and resolves each one with a line saying what changed. `docs/opportunity.md` is committed. +3. `/ck:next` says: "Run `/ck:market-research` to go deeper on the market, or `/ck:brief` if the opportunity is enough." She picks. Each writes its document into `docs/`. +4. `/ck:brief` writes the brief, with its own short market pass, and asks nothing. She reads it and edits or comments. +5. `/ck:team` writes `docs/TEAM.md`: which personas are on this product, who owns which document and stage, and which seat is missing. She adjusts by comment. +6. `/ck:prd` drafts the requirements, checks them, has three specialists argue about them on three different models, and rewrites. The review page carries one question at the top: "Imagine this shipped and did not move the number. What went wrong?" She answers in a comment. Claude finalizes `docs/PRD.md`. +7. `/ck:roadmap`, `/ck:architecture`, and `/ck:brand-guide` follow, each with the same shape: run, review by comment, done. The brand guide takes two review rounds, first on proposals, then on finalists, both as galleries she comments on. +8. At the end, `docs/` holds one document per step, every one committed, every one the same shape it was on her last product. + +**J2. Clare takes one feature to design mockups, the same way every time.** The journey that fails most often today. + +1. In a project with a PRD and a brand guide, she runs `/ck:design `. +2. Kai reads the feature's requirements from `docs/PRD.md` and the brand guide, and produces a gallery: three labeled variants (A, B, C) of the feature's screens, each with its rationale and its trade-off. +3. The gallery opens as a review page. She comments on the variant she wants, and on what to change. +4. Claude applies the comments, produces the chosen variant at full fidelity with a written design spec, republishes, and resolves each comment. +5. `docs/design//` holds the gallery, the chosen variant, and the spec, committed. The next feature runs exactly the same way. + +**J3. Will runs a panel on a decision.** `/ck:panel ` with any context document. Three lenses on three models argue it; a memo shows where they disagree and leaves the decision to him. `docs/decisions/` holds the memo, committed. + +### 2.4 Goals and measures + +| # | Goal | Measure | Source | +|---|---|---|---| +| G1 | Consistency: the same step produces the same document shape every time | Two documents of one type from two projects have identical section structure; the validator passes on both | The contracts (§7) | +| G2 | Repeatability: the pipeline ships with every project | A fresh project has every phase-one command after one install | The install drill (§9) | +| G3 | Adversarial input: real disagreement on a judgment call | In more than half of panel runs, at least one lens recommends differently, or at least one kill condition is met | `panelFailedToDisagree` and `agreementRate` in each memo | +| G4 | Clare's journeys work | J1 and J2 complete on a new project from the README alone | The J1 and J2 drills (§9) | +| G5 | Efficiency for Clare | J2 takes one command and one review, where today it takes several sessions and hand-offs by hand | The J2 drill, session count | +| G6 | Retention (proposal §3.4: the real metric for a personal tool) | At 30 days after install, at least one pipeline or panel run per week of active building | `${CLAUDE_PLUGIN_DATA}/usage.jsonl` (§5.5) | +| G7 | Instrumented: the persona question can be answered at 90 days | Every persona invocation is logged with its type and session | The same log | + +Leading indicator: usage-log entries in the first week. A panel that always agrees is a failed panel (proposal §5.5); if G3 is missed, the lenses or the question template are wrong, not the users. + +### 2.5 Non-goals for phase one + +- No `/ck:feature`, `/ck:bugfix`, or `/ck:gtm`. They need the definition pipeline's documents as inputs and are phase two (§10.2). Will confirmed `/ck:feature` stays there [W, 2026-09-09]. +- No UI. `/workflows` is the run view in phase one [D]. The Workbench is phase three (§10.3). +- No hook-enforced document gates, no model fallback chain, no Advisor tool, no Routines, no mid-run arbitration (workflows cannot pause; §4.2). +- No persona pruning. All 21 ship; the instrument ships; the cut list follows the data. +- No compatibility with, migration from, or reference to `claude-team-cli` beyond the one-time import of its profiles (§5.1) and the uninstall prerequisite (§8.4). + +--- + +## 3. Decisions + +### 3.1 Decisions on record that this PRD honors or supersedes + +| Date | Decision and where it is recorded | What `ck` does | Grade | +|---|---|---|---| +| 2026-07-29 | No second source of persona truth (team-cli `ROADMAP.md` revision history, `CONTRIBUTING.md`) | Honored by moving the source, not forking it. `ck/profiles/` is the only place persona text is edited; `agents/` and the switch skills are generated from it and drift-tested. The import from the old tool happens once (§5.1) | [R] | +| 2026-07-04 | Conductor: keep and harden the local Node dashboard; JSONL parsing fenced with fixtures (conductor `DEVLOG.md`) | Superseded in part. The dashboard is rewritten as the `ck` Workbench after phase one (§10.3). The fixture-fenced JSONL cost parser and `pricing.json` are reused | [W, 2026-09-08] | +| 2026-07-25 | Conductor research branch: "drop Tauri, target local server + browser" | Honored. The Workbench is a local server and a browser | [R] | +| proposal §9 | "Use `/workflows` and do not build a UI until it proves insufficient" | Honored in phase one, superseded for phase three: the Workbench will be built | [W, 2026-09-08] | + +### 3.2 The proposal's §8, resolved + +| # | Question (proposal §8) | Decision | Grade | +|---|---|---|---| +| 1 | Retire or coexist with the old tool? | **Neither is a consideration.** `ck` is a replacement, built independently. The old tool must be uninstalled before `ck` is used (§8.4). What it did that must not be lost (persona switch, "who should be on this", parallel work) is carried by `ck` itself (§5.6, §6.5, §10.2) | [W, 2026-09-08] | +| 2 | Workflow granularity vs sign-off | **The skill owns the gates; each span between gates that needs fan-out or verification is one workflow; a single-agent span runs inline via the Agent tool.** Full rule: §4.2 | [D]-backed | +| 3 | Where documents live | **The document is the state.** Every deliverable lives at a fixed, conventional, committed path under `` (§4.3). `.ck/runs//` is a cache; nothing depends on it | [W, 2026-09-08], [P] | +| 4 | Which personas survive? | **All 21 ship; prune at 90 days on evidence.** Generation makes carrying 21 free. No usage data exists, so a cut list today is a guess. The instrument ships in phase one (§5.5). Agrees with proposal §7, contradicts §8.4 | [P] | +| 5 | Panel model assignment | **River on Fable 5.1, Toni on Opus 5, Kai on Sonnet 5 by default.** River and Toni run on their own tiers; only Kai is moved, downward, so that three lenses are three models. Overridable per run. The memo header states the limitation: one training pipeline, partial decorrelation | [W, 2026-09-08] for the tiers; [P] for the assignment | +| 6 | `/ck:feature` scope | **Phase two.** Will confirmed the placement on 2026-09-09 (§10.2). The two scope options (full end-to-end with content, or code-only) stay open until `feature.js` is designed | [W, 2026-09-09] | +| 7 | Routines | **Phase two.** One constraint carried into phase one: every pure workflow (`panel`, `market-research`, `brief`, `team`, `roadmap`) is runnable headless. `market-research` is the first candidate for a schedule | deferred | +| 8 | Oracle for non-code documents | **A structural validator plus the human gate.** Each contract skill carries a checklist; a neutral Haiku agent checks the draft against it inside the workflow, with at most two revise loops; the review page is the human oracle. Hook-based gates are a phase-two spike (§3.3 item 6) | [P] | + +### 3.3 Corrections to the proposal + +Each item names the proposal section, what is wrong, and what this PRD does instead. + +1. **§5.1, plugin name.** The tree is rooted at `code-katz/` and every command is `/ck:...`. The command prefix is the plugin's `name` and cannot be opted out of [D]. The plugin is named `ck`. The repo is `code-katz/ck`. +2. **§3.2, §5.1, §5.6, §7, roster count.** The proposal says 22. `profiles/` holds 21 personas [R]. +3. **§5.6, collapsing Fable into Opus.** The proposal re-bases the six Fable seats onto Opus 5 on price. Rejected: Will wants Fable where judgment matters and Sonnet where volume matters [W, 2026-09-08]. The six judgment seats stay on Fable, moving from Fable 5 to Fable 5.1 (same price [D]); the eleven craft seats move from Opus 4.8 to Opus 5; the four execution seats stay on Sonnet 5. The seven personas the proposal left unassigned (Reiner, Cornelius, Ernie, Rez, Tracy, Travolta, Noon) are placed in §5.3. Haiku 4.5 is a workflow-stage tier for validators, never a persona tier. +4. **§5.5 vs §5.6, the panel contradiction.** "Each lens runs on a different model. Not negotiable" and a tier table that puts River and Toni on one model cannot both hold through frontmatter alone. With the tiers in item 3, River (Fable 5.1) and Toni (Opus 5) already differ; Kai is moved from Opus 5 to Sonnet 5 by a per-invocation override in `panel.js`. Tiers are defaults; `panel.js` is the one script that may override them (§4.5). +5. **§5.2 and §5.7, the gate mechanism.** "`TaskCompleted` or `Stop`, exit code 2, rejects malformed output." `Stop` is the main conversation's event; the subagent event is `SubagentStop`, whose exit-2 feedback path to the agent is not documented [D as read]; plugin agents ignore per-agent `hooks:` frontmatter [D]. Phase one validates inside the workflow: schema-forced output, which the harness retries on mismatch [D], plus a validator agent against the contract checklist. +6. **§5.6, fallback chain via `PreModelSwitch`.** The hook fires "before Claude Code applies a model switch that you or a client requested" [D]. Nothing says it covers subagent model selection or an API quota error. Phase-one resilience is null-tolerant scripts: a lens or stage that fails returns `null`, and the script continues and logs it. +7. **§8.4 vs §7.** "A cut list should precede the port" against "instrument and prune after 90 days." No data exists. Ship everything and instrument (§3.2 item 4). +8. **§6, "no state file".** Script variables die with the run. A gate between two workflows requires the document on disk. The documents in `/docs/` are that state; `.ck/runs/` is a cache. The proposal's argument against a custom task graph and lock protocol still holds. +9. **§4.1 vs §3.4, what buys consistency.** §4.1 says repeatability "is the whole answer to goal 3"; §3.4 says consistency comes from the document contract. §3.4 is right, and Clare's failure mode (§2.2) is exactly the one contracts fix. Workflows give the same process; contracts give the same shape. Phase one's most important files are the ten contracts in §7. +10. **§4.2, `maxBudgetUsd`.** Not in the subagent frontmatter table read today [D]. Not relied on. +11. **§9, the superseded plan.** `claude-conductor/plans/2026-09-04-agent-coordination-engine.md` is on no branch of that repo. Commit it, so the supersession is traceable. +12. **§5.2, the persona layer.** "Voice, domain constraints, model tier" omits that a subagent has no user to ask. Every persona's `## Required Interactive Behaviors` is written as questions to the user; unrewritten, it is dead text or a stall. §5.4 has the transform. +13. **§4.1, fan-out cache economics.** The prompt-cache sharing described there applies to agents matching on model, effort, agent type, tools, schema, and cwd [D]. A persona panel is three agent types on three models and shares nothing. The cost model in Appendix I assumes no sharing. +14. **§5.3, the catalog's phasing.** The proposal's phase one was `/ck:prd` and `/ck:panel`. To test the shape on a real product the whole definition pipeline is needed, and Clare's design step with it [W, 2026-09-08]. §6 is that pipeline. + +What the proposal gets right and this PRD keeps unchanged: §3 (topology, not persona strings, is the lever; buy quality with a different model and a real oracle), §4.3 (Agent Teams is not the executor), §5.2 (the four layers), §5.5 (forced self-disagreement; three approvals is a failed panel), §6 (the not-building list), §7 (the honest assessment). + +### 3.4 Will's review of revision 2 (sixteen comments, 2026-09-08) + +Revision 2 was published as a review page; Will left sixteen comments. Each is recorded here with the decision it drove, so the thread on the page can be resolved against a line in the document. + +| # | Comment (abridged) | Decision | Where | +|---|---|---|---| +| 1 | "Why is this PRD so focused on retiring team-cli? Treat ck as independent." (four comments) | Every coexistence and retirement passage removed; `ck` owns its profiles; uninstall required | §0.4, §3.2 item 1, §5.1, §8.4 | +| 2 | "Clare is not technical, but has become very proficient. She runs many multiple sessions. I want her persona work to be more efficient." | Clare named as primary user; her learnings drive the design; efficiency is a goal | §2.2, §2.4 G5 | +| 3 | "Workflows, personas and artifacts are not consistent. She wants the same, efficient, high-fidelity process for moving features into design mockups." | J2 and `/ck:design` added; contracts made the consistency mechanism | §2.3 J2, §6.9, §7 | +| 4 | "I would prefer a rewrite of the UI / dashboard after we complete ck." | Conductor's dashboard is rewritten as the Workbench, phase three | §3.1, §10.3 | +| 5 | "Be precise on these paths. Use `/docs/brief.md`." (two comments) | `` defined once; every path written against it | §0.3, §4.3 | +| 6 | "`/ck:feature`: what is this? Why is it out of scope?" | Explained in one paragraph; phase two, confirmed by Will on 2026-09-09 | §10.2 | +| 7 | "It will be built." (the Workbench) | "If ever" removed; phase three committed | §4.7, §10.3 | +| 8 | "Use Claude's review/comment system in the Claude desktop UI." | §4.9 rewritten around it; `ck` builds nothing of its own for reviews | §4.9 | +| 9 | "Why are there no Fable models? Use Fable where it matters, Sonnet where it matters." | Fable tier restored for six judgment seats; Sonnet for four execution seats; panel default follows | §3.3 item 3, §5.3, §6.10 | +| 10 | "The brief must do some basic market research." | Toni's market pass added to `/ck:brief` and to the brief contract | §6.3, §7.3 | +| 11 | "I also want a branding / style guide. See d20mob and nightgrid." | `/ck:brand-guide` modelled on the NIGHTGRID process and the d20Mob guide | §6.8, §7.8 | +| 12 | "I also want team selection. This step basically outlines R&R." | `/ck:team` writes `docs/TEAM.md` | §6.5, §7.5 | +| 13 | "I also want an architecture workflow. PRD and roadmap in, architecture out." | `/ck:architecture` | §6.7, §7.7 | +| 14 | "To truly test this I need opportunity, market-research, branding." | Phase one is the full definition pipeline | §6 | + +The earlier cross-model review (2026-09-05, against the PRD Opus wrote from the same proposal) still stands where Will's review did not touch it: the users table, the goals table, the document-is-the-state rule, per-lens evidence, the effort axis, Phase 0 spikes, `/ck:next`, and persona scopes for the 90-day prune came from that review. Its record, including eleven rejected items with reasons, is [`plans/2026-09-05-ck-prd-panel-memo.md`](2026-09-05-ck-prd-panel-memo.md). One of its rejections (coexistence with the old tool) is now moot: Will's decision replaced both positions. + +--- + +## 4. Architecture + +### 4.1 The four layers and their phase-one instances + +| Layer | Primitive | Owns | Phase-one instance | +|---|---|---|---| +| Workflow | `workflows/*.js` | The order of stages, outside the conversation | `panel`, `brief`, `draft`, `team`, `opportunity`, `market-research`, `roadmap`, `brand`, `design` | +| Persona | `agents/*.md` | Voice, domain constraints, default model tier | 21 generated files, `ck:` | +| Contract | `skills/-artifact/SKILL.md` | Section order, required fields, checklist for one document type | 10 contracts (§7) | +| Gate | The skill in the main session | Sign-off: a review page with comments, or a file edit; plus schema-forced output and a validator agent inside the workflow | `opportunity`, `prd`, `architecture`, `brand-guide`, `design` skills; the validators in every workflow | + +The proposal put the gate layer in `hooks/hooks.json`. Phase one puts human gates in the skill and machine gates in the scripts (§3.3 item 5). The hooks that ship are instrumentation and a prerequisite check, not enforcement. + +**One drafting engine.** `/ck:prd` and `/ck:architecture` have the same shape: one author drafts to a contract, a checker validates, a three-lens panel challenges, the author rewrites with a challenged-claims appendix and a premortem. One script, `workflows/draft.js`, serves both; the skill passes which contract, which author, and which lenses. A third document with that shape costs a skill and a contract, not a script. [P] + +### 4.2 The gate rule + +The docs: "No mid-run user input. Only agent permission prompts can pause a run. For sign-off between stages, run each stage as its own workflow." [D] And: `AskUserQuestion` is removed from every subagent [D]. + +Therefore: + +1. A sign-off is a **gate**. A gate runs in the main session, inside a skill: a review page with comments (§4.9), or a file the author edits and re-runs. +2. The span between two gates is a **workflow** when it needs fan-out, structured output, or resume. A span that is one agent runs inline through the Agent tool; a workflow for one agent buys nothing. +3. A workflow never contains a decision point. A skill never fans out by hand. +4. A skill or slash command whose instructions say to call Workflow is explicit opt-in [D]; no `ultracode` keyword, no "use a workflow" phrase is needed. + +Rejected alternatives: one workflow per persona action (the skill would orchestrate fan-out itself, which is what Workflow exists to do); one workflow per command (impossible with a gate in the middle); no workflows (loses resume, schema validation, the progress view, and the "don't ask again for ``" consent that plugin workflows get by name [D]). + +What would make the rule wrong: subagents regaining `AskUserQuestion`, or workflows gaining a pause primitive. Neither is on the record. + +Applied to the catalog: + +| Command | Shape | Gates | +|---|---|---| +| `/ck:panel`, `/ck:market-research`, `/ck:brief`, `/ck:team`, `/ck:roadmap` | A pure workflow: inputs are arguments, output is a document, no gate. The document is reviewed afterwards by comment or by edit whenever the author wants | None inside | +| `/ck:opportunity`, `/ck:prd`, `/ck:architecture` | Skill: workflow, then one review gate, then an inline finalize | One | +| `/ck:brand-guide` | Skill: three workflow stages with a gallery gate between each | Two | +| `/ck:design` | Skill: one workflow stage, a gallery gate, one more stage | One | +| `/ck:next`, `/ck:` | Skill only, no agents | None | + +### 4.3 ``: the document is the state + +`` is the git repository of the product being built: the folder in which Claude Code was opened. It is not the `ck` plugin's install directory (a copy under `~/.claude/plugins/`), not the `ck` source checkout, and not `~/.claude`. Every document `ck` writes goes into `` at a fixed, conventional path, and is committed with the product. [W, 2026-09-08] + +| Document | Path in `` | Written by | +|---|---|---| +| Opportunity analysis | `docs/opportunity.md` | `/ck:opportunity` | +| Market research | `docs/market-research.md` | `/ck:market-research` | +| Brief | `docs/brief.md` | `/ck:brief` | +| PRD | `docs/PRD.md` | `/ck:prd` | +| Team, roles and responsibilities | `docs/TEAM.md` | `/ck:team` | +| Roadmap | `ROADMAP.md` (the family's root-level convention [R]) | `/ck:roadmap` | +| Architecture | `docs/ARCHITECTURE.md` | `/ck:architecture` | +| Brand direction record | `docs/decisions/-brand-direction.md` | `/ck:brand-guide` | +| Brand guide | `docs/brand-guide.md` | `/ck:brand-guide` | +| Brand galleries and assets | `brand/proposals/`, `brand/finalists/`, `brand/final/` | `/ck:brand-guide` | +| Design gallery, chosen variant, spec | `docs/design//gallery.html`, `chosen.html`, `spec.md` | `/ck:design` | +| Decision memo | `docs/decisions/-.md` | `/ck:panel`, and the panel inside `draft` | + +Paths are overridable by argument. The plugin never edits `.gitignore`; nothing it writes needs excluding except the cache below. + +The cache lives at `/.ck/runs//` and holds what a fresh session might want but nothing a document depends on: + +``` +.ck/runs// +├── run.json { runId, command, createdAt, status, stage, outputPath, lenses, harnessRunId, workflow } +├── panel/.json one file per lens +├── sections/.md one file per contributor, for the assembled documents +└── review.md the comments and how each was applied +``` + +Rules, each of which closes a failure mode found in review: + +| Rule | Failure it closes | +|---|---| +| `run-id` is `-`, minted by the skill with `date -u`; workflows receive `timestamp` in `args` because `Date.now()` throws in scripts [D] | Non-deterministic scripts break resume | +| A skill passes `projectRoot` and `runDir` **absolute** in `args`; a direct slash invocation gets the typed text as a string, and the script defaults both to the session's directory | Subagents inherit the session cwd; a skill run from a subdirectory would otherwise write `docs/` in the wrong place, and a direct run must work with nothing but the text (Phase 0, 2026-09-09) | +| Every workflow accepts `args.startAt` and skips completed stages; the skill decides `startAt` by which documents exist | A fresh session cannot replay the harness cache [D]; the file on disk is what survives | +| The skill writes the Workflow tool's own run id into `run.json` as `harnessRunId` before it waits | Within a session, `resumeFromRunId` replays completed agents at no cost [D] | +| The skill adds `.ck/` to `/.git/info/exclude` on first use, never to `.gitignore` | The cache must not appear in the product's history, and the plugin must not edit a tracked file the author did not ask it to | +| Every agent that writes returns the path it wrote, in its schema | The script cannot check the filesystem; the next stage needs the path | +| Scripts never depend on `${CLAUDE_PLUGIN_ROOT}`: contracts and the roster are skills (`ck:-artifact`, `ck:roster`) that an agent loads by name when no `pluginRoot` was passed | The variable expands in skill and agent text, not inside workflow scripts (Phase 0, 2026-09-09) | + +### 4.4 Naming + +- Plugin `name`: `ck`. Everything is `/ck:` or `ck:` [D]. +- Pipeline skills: `opportunity`, `prd`, `architecture`, `brand-guide`, `design`, `next` (user-invocable, `disable-model-invocation: true`). +- Workflows: `panel`, `market-research`, `brief`, `team`, `roadmap` (user-invocable directly, since they have no gate) and `draft`, `opportunity-draft`, `brand`, `design-round` (launched by their skills; runnable directly by Will). A plugin workflow is itself a slash command [D], so all nine appear in autocomplete. No name is shared between a skill and a workflow, because both occupy `/ck:`. +- Contracts: `-artifact` (not user-invocable; read by agents and loadable by Claude when writing that document type anywhere). +- Persona switch skills: `/ck:`, one per persona (§5.6). No persona name collides with a command name. +- Agents: `river`, `akira`, ... in frontmatter (no colon allowed [D]); registered as `ck:river`, referenced as `agentType: 'ck:river'` in scripts and `subagent_type: "ck:river"` from the Agent tool. + +### 4.5 Model policy and the effort axis + +Three persona tiers and two stage tiers. The persona sets the model floor; the workflow stage sets the effort. Difficulty belongs to the task, not the persona. [W, 2026-09-08] for the tiers; the effort axis is from the Opus PRD §7.8. + +| Tier | Model | Who | Why | +|---|---|---|---| +| Judgment | `claude-fable-5-1` | River, Akira, Morgan, Sage, Jordan, Reiner | The seats whose output is a decision: product, architecture, security, business, data, game design. Fable where it matters | +| Craft | `claude-opus-5` | Toni, Kai, Iris, Quinn, Casey, Cornelius, Ernie, Rez, Tracy, Travolta, Noon | Judgment-heavy craft at moderate volume | +| Execution | `claude-sonnet-5` | Sasha, Alex, Robin, Piper | Implementation and volume. Sonnet where it matters | +| Research (stage) | `claude-sonnet-5` | Neutral research agents in `market-research` | Volume reading and web search, checked afterwards | +| Classification (stage) | `claude-haiku-4-5-20251001` | Validators in every workflow | Shape checks against a checklist | +| Synthesis (stage) | The session model | Neutral synthesis and assembly agents | Holds no lens; inherits | + +| Agent kind | Model comes from | Effort comes from | Who may override the model | +|---|---|---|---| +| Persona agent (`agentType: 'ck:'`) | Frontmatter `model:` from `ck/tiers.conf` | The script, per stage: the draft and rewrite stages and the memo synthesis run at `medium` (drill 5c showed the author stages spending most of a run's tokens on turns, not on the document); omitted means the session's effort | `panel.js` only, and only downward, for lens decorrelation | +| Neutral utility agent (no `agentType`) | The script | The script: validators at `low`, researchers at `medium` | The script | +| The main session (gates, `/ck:next`, finalize, switch skills) | The user's session model | The session | The user | + +Precedence is per-invocation → frontmatter → `CLAUDE_CODE_SUBAGENT_MODEL` → session [D]. `agent()` accepts `effort` per call [D]. Persona frontmatter never sets `effort`, so one persona can run a mechanical stage at `low` and a design stage at `xhigh` without a second definition. `/workflows` shows the requested and any substituted model per agent [D]. + +Not in phase one: escalation chains, the Advisor tool, and mid-run arbitration. Workflows cannot pause for input [D], and `PreModelSwitch` fires only on a requested session switch [D]. Phase-one resilience is null-tolerant scripts: a stage that fails returns `null`, the script logs it and continues where it can. + +### 4.6 What phase one deliberately does not build + +Everything in proposal §6, plus: hook-enforced gates, a fallback chain, the Advisor tool, Routines, mid-run arbitration, a `bin/` CLI, any UI, any review mechanism of its own (§4.9). Reasons are in §10. + +### 4.7 Plugin, web app, wrapper, or dashboard + +Will's question, answered: + +1. **It is a plugin.** Subagents, workflow scripts, and skills execute only inside Claude Code. A web app cannot run them. The plugin is the product; nothing wraps it. +2. **Single source of truth rules out a hosted app with its own store.** The family retired local persona overrides twice on exactly this ground [R]. Anything that edits a persona or a workflow edits the same files in the `ck` source checkout, and the change flows through git, the generator, and the tests. +3. **`/workflows` is the run view in phase one** [D]: phases, agent counts, tokens, elapsed time, drill-down to any agent's prompt and result. What it does not show: the static catalog (which workflows exist; which personas, tiers, and models each stage uses) and the per-run interaction graph (which lens asked which lens what). +4. **The catalog is derivable from files.** Every `ck` workflow declares `phases` and a `personas` list in `meta`. `meta` is a pure literal [D], so it names the default roster, not a run-time choice. Phase two `/ck:map` emits a Mermaid graph (workflow → phase → persona → tier → model) with one agent and no infrastructure; `/ck:map --run ` draws the per-run graph from `panel/*.json`. +5. **The Workbench will be built, as phase three** [W, 2026-09-08]. It is a rewrite of the conductor dashboard, not an extension of it: a local server and a browser (the shape conductor already settled on [R]), Python by Will's preference, that shows the catalog, run history, cost, and persona usage, and edits personas and workflows against the `ck` source checkout by running the generator and the tests and committing. It reuses conductor's fixture-fenced JSONL cost parser and `pricing.json`. It never hosts a store of definitions. Its own PRD is written after phase one has run for real, because the catalog and run data it displays do not exist yet. §10.3 has the scope as far as it is known today. + +### 4.8 Plain language: house style for every message a skill prints + +Adapted from the Opus PRD §7.11. Clare is proficient, so this is house style rather than protection. Three rules: + +1. Never show a stack trace. +2. Always name the file that holds the work completed so far. +3. Always give exactly one next action. + +Model names and costs may appear once, in the closing line of a run ("Three reviewers on three models; about $0.80"), never as a choice the user must make to proceed. Will's escape hatch: `/workflows` shows every agent, model, and token count. + +Three failure classes and what the user sees: + +| Failure | What she sees | What she can do | +|---|---|---| +| The checker rejects a draft | "The PRD is missing a success metric. Fixing that section." | Nothing. It self-corrects, up to twice | +| A stage fails after retries | "I couldn't finish the requirements section. Everything up to it is saved in `docs/PRD.md`. Run `/ck:prd` again to continue from there." | Run it again. Completed stages are skipped | +| A panel lens or the whole workflow is unavailable | "One of the three reviewers didn't answer. The memo is based on the other two and says so." or "Claude is at capacity right now. Run `/ck:prd` again in a few minutes." | Wait or retry | + +### 4.9 Reviews: Claude's built-in review and comment system + +Will's rule, recorded 2026-09-05 and confirmed 2026-09-08: every document for review arrives as a page he can comment on; every design for review arrives as a gallery of labeled variants, side by side, that he can comment on. That page is how feedback is given. Claude holds every comment, then works through and resolves all of them once the reviewer says "done". The page is Claude's own review and comment system, in the Claude desktop app or at claude.ai; `ck` builds nothing of its own for this. [W] + +Mechanism, verified in this session's tool contract: a published page is private to the account; viewers switch it to comment mode and leave threads on any passage or element; Claude reads the threads, replies on threads a person has sent to Claude, republishes the same URL, and marks each thread resolved. + +Every review page carries these five steps in its banner, because a page that says "comment anywhere" without them is a page nobody can comment on [R, 2026-09-08]: + +1. Open the link signed in to your Claude account. +2. Switch the page to comment mode from the bar at the top. +3. Click the passage or the variant and type. +4. Put `@claude` in the comment so Claude can reply to it and resolve it. +5. Say "done" in the chat when you have finished. + +Rules: + +1. One page per review, republished in place; never a new URL for a revision. +2. When the reviewer says "done", Claude reads every thread, applies each change to the file on disk (the document is the state, §4.3), republishes, and resolves each thread with one line saying what changed. A comment Claude will not act on gets a reply with the reason and stays open. A thread not sent to Claude is applied and reported in chat, because it cannot be replied to or resolved. +3. Document pages are built by `scripts/render-review.py` in one command, never by the session writing HTML: the document with a sticky table of contents, so a comment can point at a section. Drill 5c measured the hand-built page at about a third of a `/ck:prd` run's cost. +4. Gallery pages show labeled variants (A, B, C) side by side, each with its rationale and trade-off, each commentable; the reviewer comments to pick one or ask for changes. Brand galleries and design galleries use one page shape (§7.8, §7.9). +5. Availability, from the docs (Phase 0, S5): the Claude Code CLI 2.1.183 or later or the desktop app, signed in with `/login`, on a paid plan; reading comments needs 2.1.221 or later; replying on its own needs 2.1.228 or later; and comments are taken only on an artifact shared within a Team or Enterprise organization, so an account on a Pro or Max plan reviews by file edit. Every gate keeps that file-edit path: "Edit the file and run the command again; I'll pick up from your edits." + +Phase one uses this at every gate in §4.2's table, and for the PRD you are reading. + +--- + +## 5. Personas as subagents and switch commands + +### 5.1 Source of truth + +`ck/profiles/.md` and `ck/tiers.conf` are the only place persona text and tiers are edited. They are imported once from the old tool's `profiles/` directory at its commit `b4b211fbf4ec6f4d365a550b55e9981610ed7dda`, in the first commit of the `ck` repository, and are owned by `ck` from then on. There is no vendored copy, no lock file, no sync script, and no drift check against anything outside the repository. [W, 2026-09-08] + +Two files are generated from every profile, and one index from all of them: + +| Generated file | Purpose | Registered as | +|---|---|---| +| `agents/.md` | The persona as a subagent, on its tier, with interactive behaviors rewritten for output (§5.2, §5.4) | `ck:` | +| `skills//SKILL.md` | The persona as a session switch: the profile with its interactive behaviors intact, because a session has a user (§5.6) | `/ck:` | +| `profiles/ROSTER.md` and `skills/roster/SKILL.md` | One line per persona: name, role, tier, one-sentence domain. Read by `/ck:team` and `/ck:opportunity` when choosing a cast; the skill form is what a workflow agent loads when it has no plugin path | `ck:roster` (not for typing) | + +`scripts/generate.sh` produces all three; CI fails on drift between `profiles/` and the generated files (§9). The two coordinator profiles are not imported: their routing behavior becomes `/ck:team` (§6.5) and `/ck:next` (§6.12), and their session greeting has no equivalent in a plugin. + +### 5.2 Generation rule for agents + +For each `profiles/.md`: + +``` +--- +name: +description: , . Reviews and drafts from the perspective for ck workflows and delegation; returns structured findings. +model: +--- + + + + + +--- + +You are running as a delegated subagent. When the prompt names a project root and a run directory, read inputs from the project and write outputs only where the prompt says. If a schema is imposed, fill every required field; anything you would have asked goes in `questions`. Return findings first, detail after. +``` + +Frontmatter carries `name`, `description`, `model` and nothing else. Not set, with the reason: + +| Field | Why not in phase one | +|---|---| +| `effort` | Effort belongs to the stage, set by the script (§4.5) | +| `tools`, `disallowedTools` | Agents must write under ``; per-path scoping is not available; revisit after the drill | +| `maxTurns` | Workflow caps are the budget guard in phase one | +| `color` | Cosmetic; the style guide assigns colors to projects, not personas | +| `permissionMode`, `hooks`, `mcpServers` | Ignored for plugin agents [D] | + +### 5.3 Tier table + +`ck/tiers.conf`, format ` `, one line each. Three tiers [W, 2026-09-08]; the seven personas the proposal left unassigned are placed by role. + +| Persona | Role | Tier | Model | Change from the imported file | +|---|---|---|---|---| +| river | Product Manager | Judgment | `claude-fable-5-1` | Fable 5 to Fable 5.1 | +| akira | Backend Engineering | Judgment | `claude-fable-5-1` | Fable 5 to Fable 5.1 | +| morgan | Security Engineering | Judgment | `claude-fable-5-1` | Fable 5 to Fable 5.1 | +| sage | Business Advisor | Judgment | `claude-fable-5-1` | Fable 5 to Fable 5.1 | +| jordan | Data and ML | Judgment | `claude-fable-5-1` | Fable 5 to Fable 5.1 | +| reiner | Tabletop Game Designer | Judgment | `claude-fable-5-1` | Fable 5 to Fable 5.1 | +| toni | Product Marketing | Craft | `claude-opus-5` | Opus 4.8 to Opus 5 | +| kai | UX Design and Visual Art | Craft | `claude-opus-5` | Opus 4.8 to Opus 5 | +| iris | Brand and Illustration | Craft | `claude-opus-5` | Opus 4.8 to Opus 5 | +| quinn | Project Manager | Craft | `claude-opus-5` | Opus 4.8 to Opus 5 | +| casey | Data Analyst | Craft | `claude-opus-5` | Opus 4.8 to Opus 5 | +| cornelius | Military Historian | Craft | `claude-opus-5` | Opus 4.8 to Opus 5 | +| ernie | WW2 Narrative Author | Craft | `claude-opus-5` | Opus 4.8 to Opus 5 | +| rez | Cyberpunk Genre Advisor | Craft | `claude-opus-5` | Opus 4.8 to Opus 5 | +| tracy | Fantasy Genre Advisor | Craft | `claude-opus-5` | Opus 4.8 to Opus 5 | +| travolta | Fantasy Narrative Author | Craft | `claude-opus-5` | Opus 4.8 to Opus 5 | +| noon | Cyberpunk Narrative Author | Craft | `claude-opus-5` | Opus 4.8 to Opus 5 | +| sasha | Frontend Engineering | Execution | `claude-sonnet-5` | unchanged | +| alex | DevOps and Platform | Execution | `claude-sonnet-5` | unchanged | +| robin | QA and Testing | Execution | `claude-sonnet-5` | unchanged | +| piper | Tabletop Playtester | Execution | `claude-sonnet-5` | unchanged | + +Six on Fable 5.1, eleven on Opus 5, four on Sonnet 5. Stage tiers (research, classification, synthesis) are set in scripts, never on a persona (§4.5). + +Fable 5.1 rather than Fable 5: same price [D], newer generation. Full model IDs rather than aliases, so a tier changes only when someone edits this file; the resolved model is visible per agent in `/workflows` [D]. [P] + +### 5.4 The interactive-behavior rewrite + +Every profile has a `## Required Interactive Behaviors` section written as questions to the user (River: Three Whys, V0 Challenge, Premortem). A subagent cannot ask [D]. The transform is mechanical, identical for all 21 personas, and adds no per-persona prose: + +1. Rename the heading to `## Required Behaviors (subagent form)`. +2. Insert directly under it: + + > You are running with no user present. Every behavior below still applies, in output form. Where a behavior tells you to ask, halt, interrupt, or require an answer before proceeding: do not stop. State the question verbatim under `questions` (addressed to `author` or to a named teammate), state the assumption you will proceed on, and proceed. Where a behavior produces an artifact (table, diagram, scenario, counter-proposal, pitch), produce it in full. Where it requires a decision from the user, give your recommendation with evidence and mark the decision as open. + +3. Keep the profile text verbatim beneath. + +What the preamble makes River do, and what the scripts ask for by name: + +| Profile behavior | Subagent form | +|---|---| +| Three Whys: ask "Why?" up to three times | Write the root-cause chain yourself from the input (solution → why → why → why), each step more specific, until the user pain is exposed or the request is shown to address a symptom; say which. A why the input cannot answer becomes a `questions` entry with your assumption | +| V0 Challenge: propose a V0 cutting half the scope and require a decision | Always include the V0 counter-proposal, what it cuts, whether it would still move the metric, and your recommendation with evidence. The decision stays with the author and is listed as open | +| Premortem: write the failure scenario and ask "What went wrong?" | Write the 2-3 sentence scenario in which this shipped on time and missed the metric, name the assumption it exposes, add that assumption to the Assumptions section, and leave the question verbatim for the author's review | + +The interactive versions of River's three behaviors live in `skills/prd/SKILL.md` for the optional interview, and in `skills/river/SKILL.md` for the switch. A CI check asserts both carry the three behavior headings from `profiles/river.md`, so a renamed behavior fails the build instead of diverging silently (§9). + +### 5.5 Hooks + +`hooks/hooks.json`: + +```json +{ + "description": "ck: persona usage log, and a check that the old tool is gone", + "hooks": { + "SubagentStart": [ + { + "matcher": "^ck:", + "hooks": [ + { "type": "command", "command": "\"${CLAUDE_PLUGIN_ROOT}/scripts/usage-log.sh\"" } + ] + } + ], + "SessionStart": [ + { + "hooks": [ + { "type": "command", "command": "\"${CLAUDE_PLUGIN_ROOT}/scripts/check-prereqs.sh\"" } + ] + } + ] + } +} +``` + +`scripts/usage-log.sh` reads the hook's stdin JSON, appends one line `{"ts":"","agent_type":"ck:","session_id":"","cwd":""}` to `${CLAUDE_PLUGIN_DATA}/usage.jsonl`, and always exits 0. Facts it relies on: `SubagentStart` matchers accept plugin-scoped names such as `^my-plugin:reviewer$`; stdin carries `agent_type` and `session_id`; `CLAUDE_PLUGIN_DATA` is exported to hook processes and survives plugin updates [D]. It never blocks: a logging failure must not stop a persona. The 90-day review reads this file and answers proposal §8.4. Observed in Phase 0 (S4): the hook fires for persona agents inside a workflow as well as for direct delegation; stdin carries `agent_type`, `agent_id`, `session_id`, `cwd`, and `transcript_path`; with `--plugin-dir` the data directory resolves to `~/.claude/plugins/data/ck-inline`. + +`scripts/check-prereqs.sh` looks for `~/.claude/team/`, `~/.local/bin/claude-team`, and the old tool's block in `~/.claude/CLAUDE.md`. If any is present it prints one plain sentence ("The old team tool is still installed and its persona commands will collide with ck's. Remove it with the steps in the ck README.") and exits 0. It never blocks a session. + +### 5.6 Persona switch commands + +The session-switch route survives as `/ck:`, one generated skill per persona, `disable-model-invocation: true`, description "Switch this session to , ." The body is the profile verbatim, including `## Required Interactive Behaviors` and `## Greeting`, because a switched session has a user to ask. One sentence is prepended: "You are now for the rest of this session. You run on this session's model, not on your tier; to run on your tier, delegate to the `ck:` subagent." + +The three hand-off routes, all inside `ck`: + +| Route | How | Runs on | +|---|---|---| +| Switch this session | `/ck:river` | The session's model | +| Delegate one task | `Agent({ subagent_type: "ck:river" })` | River's tier | +| Run a pipeline stage or a fan-out | The `ck` workflows | Each persona's tier, per stage | + +The fourth route the old tool offered, a separate terminal session per persona, is what the workflows replace. What still needs a separate session (a long parallel build in its own worktree) is `/ck:feature`'s job in phase two. + +### 5.7 Acceptance criteria + +- [ ] `agents/` and `skills//` each hold exactly one file per `profiles/*.md` (21 today); `profiles/ROSTER.md` has 21 rows. +- [ ] Every agent's `model:` equals its `tiers.conf` line; `name:` equals the filename and contains no colon; `## Handoff Brief` present; `## Greeting` absent; the §5.4 preamble present; no `effort:` line. +- [ ] Every switch skill carries `## Required Interactive Behaviors` and `## Greeting` verbatim from its profile, and the prepended sentence. +- [ ] Regenerating from `profiles/` produces no diff against the committed generated files. +- [ ] In a session with the plugin enabled, `@ck:river` appears in the subagent typeahead and `Agent({subagent_type: "ck:river", ...})` runs on `claude-fable-5-1` (visible in the transcript); `/ck:river` switches the session. +- [ ] After one `ck:` delegation, `${CLAUDE_PLUGIN_DATA}/usage.jsonl` has one new line with `agent_type` set. +- [ ] With `~/.claude/team/` present, a new session prints the one-sentence warning; without it, nothing. + +--- + +## 6. The pipeline + +### 6.1 Order, inputs, and outputs + +Each command runs when its required inputs exist in `` and names the missing one in a sentence when they do not. Optional inputs are read when present and skipped when absent. The order below is the order `/ck:next` recommends; any command can run on its own. + +| Step | Command | Requires | Reads if present | Writes | Gate | +|---|---|---|---|---|---| +| 1 | `/ck:opportunity` | An idea in a sentence | `docs/market-research.md`, `docs/TEAM.md` | `docs/opportunity.md` | Review page | +| 2 | `/ck:market-research` | `docs/opportunity.md` or `docs/brief.md` or a focus in a sentence | both | `docs/market-research.md` | None | +| 3 | `/ck:brief` | An idea in a sentence, or `docs/opportunity.md` | `docs/market-research.md` | `docs/brief.md` | None | +| 4 | `/ck:team` | `docs/brief.md` or `docs/opportunity.md` | `docs/PRD.md`, `docs/market-research.md` | `docs/TEAM.md` | None | +| 5 | `/ck:prd` | `docs/brief.md` | `docs/opportunity.md`, `docs/market-research.md`, `docs/TEAM.md`, `ROADMAP.md` | `docs/PRD.md`, `docs/decisions/-prd-review.md` | Review page | +| 6 | `/ck:roadmap` | `docs/PRD.md` | `docs/opportunity.md`, `docs/market-research.md`, `docs/TEAM.md` | `ROADMAP.md` | None | +| 7 | `/ck:architecture` | `docs/PRD.md`, `ROADMAP.md` | `docs/TEAM.md`, `docs/opportunity.md` | `docs/ARCHITECTURE.md`, `docs/decisions/-architecture-review.md` | Review page | +| 8 | `/ck:brand-guide` | `docs/opportunity.md` or `docs/brief.md` | `docs/PRD.md`, `docs/market-research.md` | `brand/`, `docs/decisions/-brand-direction.md`, `docs/brand-guide.md` | Two gallery pages | +| 9 | `/ck:design ` | `docs/PRD.md` | `docs/brand-guide.md`, `brand/final/`, `docs/ARCHITECTURE.md` | `docs/design//` | Gallery page | +| any | `/ck:panel ` | A question | Anything named as context | `docs/decisions/-.md` | None | +| any | `/ck:next` | Nothing | The table above | Nothing | None | + +Every subsection below has the same parts: purpose, invocation, cast and models, stages, the document, the gate, cost, acceptance. Stages are given as the `meta.phases` of the script. Four scripts are written in full in the appendices (`panel`, `brief`, `draft`, `team`); the other five are specified here to the stage level and follow the same conventions (required args, `startAt`, null-tolerant stages, a validator, the document path returned in the schema). + +### 6.2 `/ck:opportunity` + +**Purpose.** The first document on a new product: is this worth doing, for whom, in what market, in what technical shape, and what would have to be true. Modelled on the NIGHTGRID opportunity analysis, which is a multi-persona document: each lens writes its own section, and River holds the frame, the stage gates, and the risks. [W, 2026-09-08] + +**Invocation.** `/ck:opportunity `. With `docs/opportunity.md` already present, the skill offers to revise it (re-running Sections and Assemble on the comments) or start over. + +**Cast and models.** River (Fable 5.1) frames and assembles. Contributors are chosen by River from `profiles/ROSTER.md` and `docs/TEAM.md` when it exists, up to four: Toni (Opus 5) always, for market context, positioning, and a go-to-market sketch; Akira (Fable 5.1) always, for the technical shape; a domain seat for the product's kind (Reiner for a game, Jordan for a data product, Sage for a business-model question, Cornelius for a historical setting); Sage optionally, for stage gates and monetization when the domain seat is not Sage. Contributors whose sections make claims about the world use web search and cite a source per claim (Phase 0 spike S7 confirms web search is available to subagents inside a workflow). + +**Stages** (`workflows/opportunity-draft.js`, `meta.personas: ['river', 'toni', 'akira', 'sage', 'reiner', 'jordan']`): + +| Phase | Agents | What happens | Writes | +|---|---|---|---| +| Frame | 1, `ck:river` | Reads the idea, the roster, and `docs/TEAM.md` and `docs/market-research.md` if present. Writes the concept statement and the hypothesis, chooses the contributors with a reason each, and writes one brief per contributor: the questions that section must answer | `/frame.json` | +| Sections | Up to 4, in parallel, `agentType` per contributor, `effort: 'high'` | Each writes its section to the contract's section spec for its lens, with sources for external claims and its Handoff Brief | `/sections/.md` | +| Assemble | 1, `ck:river` | Writes `docs/opportunity.md` to the contract: summary, concept, market context, one section per lens, stage gates, monetization, risks, open questions, sources. Applies River's behaviors in subagent form: the root-cause chain under the problem; a smaller first version under scope; the premortem left for the review | `docs/opportunity.md` | +| Validate | 1 neutral, Haiku 4.5, `effort: 'low'`; then `ck:river` to revise, at most twice | Checks the document against the contract checklist | `docs/opportunity.md` | + +Seven to nine agents. Under the "medium" size guideline [D]. + +**The document.** `docs/opportunity.md`, contract §7.1. + +**The gate.** The skill publishes the document as a review page (§4.9) with one question at the top: "Imagine this was built and nobody wanted it. What did we get wrong?" On "done" it applies every comment, republishes, resolves, and finalizes inline with `ck:river` (fold the answer into Risks and Assumptions; resolve answered open questions; re-check the contract). + +**Cost.** About $2.50 per run (Appendix I). + +**Acceptance.** +- [ ] On a fixture idea for a game, River chooses Reiner as the domain seat and says why in `frame.json`; on a fixture idea for a data product, Jordan. +- [ ] Every external claim in Market context carries a source; the Sources section lists each once. +- [ ] `docs/opportunity.md` has every contract section in order and passes the validator. +- [ ] The review page shows the premortem question at the top and the five comment steps in the banner; two comments are applied and resolved with one-line replies. +- [ ] Re-running with the document present offers revise or start over, and revise re-runs only Sections and Assemble. + +### 6.3 `/ck:market-research` + +**Purpose.** A deeper market pass than the brief's, run as a fan-out: several questions researched in parallel on the web, cross-checked, and written up with a source per claim. The shape of a deep-research run: plan, fan out, cross-check, cite. [W, 2026-09-08] + +**Invocation.** `/ck:market-research [focus in a sentence]`. With no focus, the questions come from `docs/opportunity.md` or `docs/brief.md`; with neither and no focus, the workflow stops and names the missing input. + +**Cast and models.** Toni (Opus 5) plans and writes. Research agents are neutral, on Sonnet 5 at `effort: 'medium'`, one per question, with web search. The cross-checker is neutral on Sonnet 5. The validator is Haiku 4.5. + +**Stages** (`workflows/market-research.js`, `meta.personas: ['toni']`): + +| Phase | Agents | What happens | Writes | +|---|---|---|---| +| Plan | 1, `ck:toni` | Reads the inputs. Writes four to six research questions across: market size and trends; competitors and substitutes; customers, segments, and channels; pricing and business models; platform, legal, or regulatory constraints. Each question names what a good answer contains | `/plan.json` | +| Research | 4 to 6, in parallel, neutral, Sonnet 5, `effort: 'medium'` | Each answers one question from the web: findings, each with a source URL, a date, and a confidence; contradictions it noticed; what it could not find | `/research/.json` | +| Cross-check | 1 neutral, Sonnet 5 | Every claim must carry a source or be marked unverified; claims that contradict each other across researchers are listed with both sources; stale sources (older than 18 months for a moving market) are flagged | `/crosscheck.json` | +| Write | 1, `ck:toni` | Writes `docs/market-research.md` to the contract: summary; market size and trends; competitors table; customers and channels; pricing and business models; constraints; contradictions and unknowns; implications for positioning; sources | `docs/market-research.md` | +| Validate | 1 neutral, Haiku 4.5, `effort: 'low'`; Toni revises at most once | Contract checklist, including "every claim in the body has a source in Sources" | `docs/market-research.md` | + +Eight to ten agents. Runnable headless; the first candidate for a Routine in phase two. + +**The document.** `docs/market-research.md`, contract §7.2. No gate: the author reviews by comment or edit when they want to, and `/ck:brief` and `/ck:prd` read it as it stands. + +**Cost.** About $1.20 per run (Appendix I). + +**Acceptance.** +- [ ] `plan.json` has between four and six questions covering at least four of the five areas. +- [ ] `/workflows` shows the Research phase running its agents in parallel on Sonnet 5. +- [ ] Every body claim carries a footnote or inline source that appears in Sources; a fixture with a planted contradiction (two researchers given conflicting seed facts) appears in Contradictions and unknowns. +- [ ] With no inputs and no focus, the workflow stops with one sentence naming what to run first. + +### 6.4 `/ck:brief` + +**Purpose.** The short document that governs the expensive PRD run: the problem, the person, the number, the scope, and a basic market pass. One line of idea text in; `docs/brief.md` out; nothing asked. [W, 2026-09-08] for the market pass. + +**Invocation.** `/ck:brief `, or `/ck:brief` alone when `docs/opportunity.md` exists, in which case the idea and the market context come from it. + +**Cast and models.** Toni (Opus 5) for the market pass, with web search; River (Fable 5.1) drafts; Haiku 4.5 validates. + +**Stages** (`workflows/brief.js`, Appendix C, `meta.personas: ['toni', 'river']`): + +| Phase | Agents | What happens | Writes | +|---|---|---|---| +| Market pass | 1, `ck:toni` | Reads `docs/market-research.md` and `docs/opportunity.md` if present and searches only for what they lack. Returns three to five comparable products: what each does, who it is for, its price or model, and the gap this idea would fill; one source each; one paragraph on how crowded the space is | `/market.json` | +| Draft | 1, `ck:river` | Writes `docs/brief.md` to the contract: idea; problem and root-cause chain; user; success metric and leading indicator; comparable products (from Toni's pass, attributed); scope with a smaller first version and a recommendation; non-goals; open questions for the author. River's behaviors in subagent form: the whys are written, not asked; the smaller version is proposed, not negotiated | `docs/brief.md` | +| Validate | 1 neutral, Haiku 4.5, `effort: 'low'`; then `ck:river` once if needed | Contract checklist; one revision at most | `docs/brief.md` | + +Three to four agents. About two minutes. + +**The document.** `docs/brief.md`, contract §7.3 (full text: Appendix G). + +**The gate.** None. The closing message names the file and gives one action: "Read it, change anything, then run `/ck:team` or `/ck:prd`." + +**Cost.** About $0.55 per run (Appendix I). + +**Acceptance.** +- [ ] `docs/brief.md` has the contract's eight sections in order and passes the validator. +- [ ] Comparable products lists three to five entries with a source each; when `docs/market-research.md` exists, the section cites it and the market pass makes fewer searches (visible in the transcript). +- [ ] The open-questions list is present even when empty. +- [ ] The closing message names the file and one next action. + +### 6.5 `/ck:team` + +**Purpose.** Team selection and roles and responsibilities: which personas are on this product, who owns which document and stage, who reviews, and which seat is missing. "Say you are building a game: do you have the game designer on your team?" [W, 2026-09-08]. This is the old coordinator's routing behavior, written down once per product instead of asked once per session. + +**Invocation.** `/ck:team`. Reads `docs/opportunity.md`, `docs/brief.md`, `docs/PRD.md`, `docs/market-research.md`, whichever exist; requires at least one of the first two. With `docs/TEAM.md` present, re-nominates against the current documents and shows the diff in the closing message. + +**Cast and models.** River (Fable 5.1) nominates and assembles. Each nominated persona confirms on its own tier at `effort: 'low'`. Haiku 4.5 validates. + +**Stages** (`workflows/team.js`, Appendix D, `meta.personas: [all 21]`): + +| Phase | Agents | What happens | Writes | +|---|---|---|---| +| Nominate | 1, `ck:river` | Reads the documents and `profiles/ROSTER.md`. Proposes the cast, up to eight: for each pipeline document and stage, an owner and reviewers; for each requirement area in the PRD if present, an owner; and the missing seats: needs no persona covers (legal, audio, localization, a specific domain), with what a person in that seat would own | `/nominations.json` | +| Confirm | Up to 8, in parallel, `agentType` per nominee, `effort: 'low'` | Each nominee reads the documents and its nomination and returns: accept or decline each responsibility with a reason; what it needs from whom before it can start; one risk in its domain; and one seat it thinks is missing | `/confirmations/.json` | +| Assemble | 1, `ck:river` | Writes `docs/TEAM.md` to the contract: cast table (persona, role, tier, why on this product); roles and responsibilities matrix (document or stage × owner, contributors, reviewers); hand-off order with what each hand-off carries; needs per persona; missing seats; declined nominations and why | `docs/TEAM.md` | +| Validate | 1 neutral, Haiku 4.5, `effort: 'low'`; River revises at most once | Contract checklist, including "every pipeline document has exactly one owner" | `docs/TEAM.md` | + +Up to eleven agents; under the "medium" guideline. The Confirm fan-out is where a persona says "not me, and here is who": a nominee that declines names a replacement from the roster, and River takes it or explains why not. + +**The document.** `docs/TEAM.md`, contract §7.5. It is read by `/ck:opportunity` and `/ck:architecture` when choosing contributors and lenses, so a persona added here shows up in the later steps. + +**The gate.** None. The author edits or comments when they disagree. + +**Cost.** About $1.00 per run (Appendix I). + +**Acceptance.** +- [ ] On the game fixture, Reiner and Piper are nominated and the missing-seats list is non-empty (audio, at least); on the data-product fixture, Jordan and Casey are nominated and Reiner is not. +- [ ] `/workflows` shows Confirm running the nominees in parallel, each on its tier model, at low effort. +- [ ] A fixture nominee instructed (via a seeded profile note in the test) to decline produces a replacement in `docs/TEAM.md` with River's reason. +- [ ] Every pipeline document in §6.1 has exactly one owner in the matrix; the validator passes. + +### 6.6 `/ck:prd` + +**Purpose.** Proposal goal 3: a PRD that has the same shape every time, in every project, produced by River with the product, marketing, and UX lenses challenging it on three different models before the author sees it. The shape comes from the contract (§7.4); the process comes from the `draft` workflow (§4.1, one drafting engine). + +**Invocation.** `/ck:prd [--interview]`. Requires `docs/brief.md`; without it: "Run `/ck:brief ` first. It takes about two minutes and writes `docs/brief.md`. Then run `/ck:prd` again." With `--interview` and no brief, River interviews in the session (Will's path, Appendix E step 2) and writes the brief from the answers. + +**Cast and models.** River (Fable 5.1) drafts and rewrites. The panel: River on Fable 5.1 reading the brief, `docs/opportunity.md`, and `ROADMAP.md`; Toni on Opus 5 reading `docs/market-research.md` and `docs/opportunity.md`; Kai on Sonnet 5 (moved down from Opus 5 by the script, §4.5) reading `brand/` and `docs/design/`. Haiku 4.5 validates. Neutral synthesis inherits the session model. + +**Stages** (`workflows/draft.js` with `args.artifact: 'prd'`, Appendix B, `meta.personas: ['river', 'akira', 'toni', 'kai', 'morgan', 'alex', 'jordan']`; stages are skipped when `args.startAt` names a later one): + +| Phase | Agents | What happens | Writes | +|---|---|---|---| +| Draft | 1, `ck:river` | Reads `docs/brief.md`, the optional inputs, and the PRD contract. Writes `docs/PRD.md` to the contract's section order. Tags every claim not taken from the brief `[C1]`, `[C2]`, ... so the lenses can address it. Root-cause chain and V0 counter-proposal in subagent form. No premortem yet | `docs/PRD.md` | +| Validate | 1 neutral, Haiku 4.5, `effort: 'low'`; then `ck:river` to revise, at most twice | Checks the draft against the contract checklist; returns `{valid, missing[], notes}`. On `missing`, River revises in place, keeping every tag. After two revisions the workflow proceeds and logs what is still missing | `docs/PRD.md` | +| Panel | 4, nested `workflow('ck:panel', ...)` (by name; Phase 0 showed a script path outside the working directory is refused) | Question: "Is this PRD ready for the author's review, and what would you change before it ships?" Material: `docs/PRD.md`. Rationale, read second: `docs/brief.md`. Evidence per lens as above | `panel/*.json`, `docs/decisions/-prd-review.md` | +| Synthesize | 1, `ck:river` | Rewrites `docs/PRD.md`: revised where the panel showed a claim wrong or unsupported; **Appendix A, Challenged claims** (claim, challenged by, severity, status ∈ upheld, revised, withdrawn, open; resolution; the memo's disagreements and kill conditions reproduced verbatim; nothing deleted); **Appendix B, Premortem** (the scenario, the exposed assumption, the question "What went wrong?" left verbatim for the review) | `docs/PRD.md` | + +Seven agents without a revision, up to nine with two. If the nested panel throws, the workflow logs it and synthesizes without it, saying so in the PRD header. + +**Launch and wait.** The skill calls the Workflow tool with `name: "ck:draft"` and the args in Appendix E (a plugin workflow is addressed by name; Phase 0, open question 3), writes the returned run id into `run.json` as `harnessRunId`, tells the user in plain words that the draft is running in the background, and **stops: it waits for the task notification. It does not poll, does not narrate, and does not start other work on this run.** On a stop or failure it prints the §4.8 message naming `docs/PRD.md` and the one action, and records the failed stage in `run.json` so the next run passes the right `startAt`. `${CLAUDE_PLUGIN_ROOT}` expands anywhere in skill content [D]. + +**The document.** `docs/PRD.md`, contract §7.4 (full text: Appendix G). + +**The gate.** The review page (§4.9) with the premortem question at the top. On "done": every comment applied to `docs/PRD.md` (or answered with a reason), the page republished, each thread resolved with one line. File-edit fallback: "Open `docs/PRD.md`, change anything, save, and run `/ck:prd` again; I'll fold your edits in." Either path may trigger a focused re-run of the panel on named sections before finalizing. + +**Finalize.** One agent, inline (§4.2): `ck:river` folds the premortem answer into Assumptions and Risks, resolves each open decision as answered, keeps Appendix A intact, checks the result against the contract, writes `docs/PRD.md`, sets `status: final` in `run.json`. The skill prints the path and one next action: "Run `/ck:next`." + +**Cost.** About $2.30 per run without a revision, about $2.90 with one, plus the main session's turns (Appendix I). + +**Acceptance.** +- [ ] `/ck:prd` without a brief stops with the one-action message and runs nothing. +- [ ] `/ck:prd --interview` asks one question at a time; after the second why, `/interview.md` already holds the first two answers; killing the session and re-running offers to resume. +- [ ] `run.json` contains `harnessRunId` before the skill goes idle; `.git/info/exclude` contains `.ck/`; `git status` shows `docs/` files and nothing under `.ck/`. +- [ ] `/workflows` shows phases Draft, Validate, Panel (with the nested panel's agents on three models), Synthesize; the validator runs on Haiku 4.5; River runs on Fable 5.1. +- [ ] `docs/PRD.md` has every contract section, an Appendix A with at least one row per finding a lens raised, and an Appendix B with a scenario and the verbatim question. +- [ ] Stopping the workflow during Panel, then running `/ck:prd` again, continues from Panel without re-drafting (`startAt`). +- [ ] The review page is published with the five steps in its banner; two comments are applied and resolved with one-line replies; a thread not sent to Claude is applied and reported in chat. +- [ ] Without the publishing tool: the file-edit message is printed; an edit to `docs/PRD.md` followed by `/ck:prd` finalizes from the edited file. +- [ ] The final PRD is at `docs/PRD.md` with `status: final` in `run.json`, and its checklist passes when re-validated by hand. +- [ ] `skills/prd/SKILL.md` contains the three behavior headings from `profiles/river.md` (CI-checked). + +### 6.7 `/ck:roadmap` + +**Purpose.** The roadmap in the family's own format (the roadmap skill's `ROADMAP.md` structure [R]): a current-state snapshot, opportunities in three tiers with why-now and a success signal, recommended sequencing, open questions, an OKR table, and a revision history. River prioritizes; Quinn sequences. + +**Invocation.** `/ck:roadmap`. Requires `docs/PRD.md`. With `ROADMAP.md` present, runs in update mode: Section 1 is rewritten and a revision-history entry is appended, per the roadmap skill's own workflow [R]. + +**Cast and models.** River (Fable 5.1), Quinn (Opus 5), Haiku 4.5 validates. + +**Stages** (`workflows/roadmap.js`, `meta.personas: ['river', 'quinn']`): + +| Phase | Agents | What happens | Writes | +|---|---|---|---| +| Prioritize | 1, `ck:river` | Reads the PRD and the optional inputs. Writes the current-state snapshot and the opportunities in three tiers (ship next; high value, next sprint; strategic), each with why now or why not now and a measurable success signal, and the OKR table | `/priorities.json` | +| Sequence | 1, `ck:quinn` | Writes `ROADMAP.md` to the contract: recommended sequencing with dependencies and what each step unblocks; open questions; the revision-history entry (what changed, why, open questions resolved or added, triggered by) | `ROADMAP.md` | +| Validate | 1 neutral, Haiku 4.5, `effort: 'low'`; Quinn revises at most once | Contract checklist | `ROADMAP.md` | + +Three to four agents. + +**The document.** `ROADMAP.md` at the root of ``, contract §7.6, which is the roadmap skill's structure verbatim so that the skill and this workflow produce interchangeable files. + +**The gate.** None. + +**Cost.** About $0.70 per run (Appendix I). + +**Acceptance.** +- [ ] On a project with no `ROADMAP.md`, the file is created with Section 1 and Section 2 in the roadmap skill's format and passes that skill's lint check [R]. +- [ ] On a project with one, Section 1 is replaced and exactly one revision-history entry is prepended, dated with the run's timestamp. +- [ ] Every Tier 1 opportunity traces to a numbered PRD requirement. + +### 6.8 `/ck:architecture` + +**Purpose.** The PRD and the roadmap in; a recommended architecture out, with the alternatives considered, the decision record, and a security, platform, and data challenge on three models before the author sees it. [W, 2026-09-08] + +**Invocation.** `/ck:architecture`. Requires `docs/PRD.md` and `ROADMAP.md`; names the missing one otherwise. + +**Cast and models.** Akira (Fable 5.1) drafts and rewrites. The panel: Morgan (security) on Fable 5.1 reading `docs/PRD.md` and any `SECURITY.md`; Alex (platform and operations) on Sonnet 5 reading any `infra/`, `Dockerfile`, or CI configuration; Jordan (data) on Opus 5 (moved down from Fable 5.1 by the script) reading `docs/market-research.md` and any `data/` or schema files. Three models. Haiku 4.5 validates. + +**Stages.** `workflows/draft.js` with `args.artifact: 'architecture'` (Appendix B): the same Draft, Validate, Panel, Synthesize as §6.6, with the architecture contract, Akira as author, the lenses above, and the panel question "Would you build it this way, and what would you change before the first line of code?" + +| Phase | Author's work, specific to this document | +|---|---| +| Draft | `docs/ARCHITECTURE.md` to the contract: context and constraints from the PRD and roadmap; quality attributes ranked; the recommended architecture with a Mermaid diagram; components and their responsibilities; data model sketch; integration points; alternatives considered and why not; decision record; sequencing against the roadmap; risks; open questions. Every claim not from the PRD tagged `[C]` | +| Synthesize | The same appendices as the PRD: Challenged claims, and a Premortem written as "this shipped and fell over in production; what did we get wrong?" | + +**The document.** `docs/ARCHITECTURE.md`, contract §7.7. + +**The gate.** The review page with the premortem question. Finalize inline with `ck:akira`. + +**Cost.** About $2.40 per run (Appendix I). + +**Acceptance.** +- [ ] Without `ROADMAP.md`, the skill stops and names `/ck:roadmap`. +- [ ] `/workflows` shows Akira on Fable 5.1, and the three lenses on three different models. +- [ ] `docs/ARCHITECTURE.md` has a rendered Mermaid diagram, an alternatives table with at least two rows, and a decision record with a date. +- [ ] Every Tier 1 roadmap item is placed in the sequencing section. + +### 6.9 `/ck:brand-guide` + +**Purpose.** A brand identity, produced the way NIGHTGRID's was: proposal rounds, then candidates, then finalists, each as a gallery of labeled variants the author comments on, ending in a brand direction record and a brand identity guide with the d20Mob guide's structure. [W, 2026-09-08] + +**Invocation.** `/ck:brand-guide`. Requires `docs/opportunity.md` or `docs/brief.md`. With `docs/brand-guide.md` present, offers a revision round on the finalists. + +**Cast and models.** Iris (Opus 5) leads: marks, palette, type, art direction. Kai (Opus 5) skins UI surfaces in each direction. Toni (Opus 5) supplies one positioning line per direction before Iris starts. Haiku 4.5 validates each gallery against the gallery contract. Output is SVG, HTML, and CSS; raster generation is out of scope. + +**Stages** (`workflows/brand.js` with `args.stage` ∈ `proposals | finalists | guide`; the skill runs one stage, gates, then the next; `meta.personas: ['iris', 'kai', 'toni']`): + +| Stage | Agents | What happens | Writes | +|---|---|---|---| +| Proposals | Toni, then Iris, then Kai, then validator | Toni: a positioning line and an audience note per candidate direction. Iris: four to six brand directions, each with a name treatment, palette, type pairing, mood words, one hero mark, and a rationale and trade-off. Kai: one UI surface per direction in that direction's skin. Assembled as a gallery page, labeled A to F | `brand/proposals/gallery.html`, `brand/proposals/