From 7df143b82cea8f9416af7245be1e75bc05e66e1c Mon Sep 17 00:00:00 2001 From: SUaDtL Date: Tue, 4 Aug 2026 07:35:20 -0400 Subject: [PATCH 1/2] feat(brainstorming): modernize spec refinement for capable models Five phases replace four: a split-before-you-spend bundling check in Phase 1, a new shape-the-approach phase (genuine alternatives with one recommendation, isolation + YAGNI lenses), a decide-or-ask question discipline replacing one-question-per-round (parameters decided and recorded in the spec, forks asked in full with a recommendation and batched when independent), a rationalization guard making closure a checklist instead of a feeling, a breaker for non-converging loops, and a Phase 5 review upgrade: mechanical self-review of the file as written plus an adversarial pass presented WITH the spec at approval. INDEX row and curated site page aligned; ca 2.11.5, ca-codex 0.4.4, ca-pi 0.2.4 (root manifest regenerated; ca-pi changelog entry per its release guard). Implements the accepted slice of #597; D1-D4 deferred there. CHANGELOG: the brainstorming skill now splits bundled ideas before refining, shapes the approach with a recommendation, decides routine parameters while asking genuine forks in full, and adversarially reviews its own spec before approval Claude-Session: https://claude.ai/code/session_01QjJeSbcwPHwMmd6CEZeagB --- core/surface/skills/INDEX.md | 2 +- core/surface/skills/brainstorming/SKILL.md | 65 ++++++++++++++----- package.json | 2 +- plugins/ca-codex/.codex-plugin/plugin.json | 2 +- plugins/ca-codex/routines/INDEX.md | 2 +- .../ca-codex/routines/brainstorming/SKILL.md | 65 ++++++++++++++----- plugins/ca-pi/CHANGELOG.md | 6 ++ plugins/ca-pi/package.json | 2 +- plugins/ca-pi/routines/INDEX.md | 2 +- plugins/ca-pi/routines/brainstorming/SKILL.md | 65 ++++++++++++++----- plugins/ca/.claude-plugin/plugin.json | 2 +- plugins/ca/skills/INDEX.md | 2 +- plugins/ca/skills/brainstorming/SKILL.md | 65 ++++++++++++++----- site/src/curated/skills/brainstorming.md | 37 +++++++---- 14 files changed, 229 insertions(+), 90 deletions(-) diff --git a/core/surface/skills/INDEX.md b/core/surface/skills/INDEX.md index c132b5e3..1afdc2b1 100644 --- a/core/surface/skills/INDEX.md +++ b/core/surface/skills/INDEX.md @@ -14,7 +14,7 @@ Skill bodies load on routing only. This index is the surface scan; never bulk-re | [refactor](refactor/SKILL.md) | `/refactor` | Behavior-preserving change behind a parity-coverage proof gate; routes to `tdd` Phase 1 only when new test seams are needed. | | [context-creation](context-creation/SKILL.md) | `/create-context` (brownfield) | Back-fills `.codearbiter/` from existing source via parallel scouts; writes `CONTEXT.md` (`arbiter: enabled` + `stage:`) and locks it ``. | | [decompose](decompose/SKILL.md) | greenfield startup, `/decompose` | Six-layer senior-architect interview, compaction-resilient via per-layer disk drafts + DRAFT ADRs; populates `.codearbiter/` and locks it initialized. | -| [brainstorming](brainstorming/SKILL.md) | `/feature` (front), `/sprint` planning | Socratic idea→spec: one question at a time, challenge vagueness, force trade-offs; writes `specs/.md` whose acceptance criteria become `tdd` obligations. Hard-gate: no code until the spec is approved. | +| [brainstorming](brainstorming/SKILL.md) | `/feature` (front), `/sprint` planning | Socratic idea→spec: split bundles, shape the approach, then decide parameters / ask forks in full; adversarial self-review before approval; writes `specs/.md` whose acceptance criteria become `tdd` obligations. Hard-gate: no code until the spec is approved. | | [writing-plans](writing-plans/SKILL.md) | `/feature`, `/sprint` (after the spec) | Decomposes an approved spec into small tasks, each with a path + a verification that maps to a `tdd` obligation; writes `plans/.md` with bijective criterion↔task coverage. | | [executing-plans](executing-plans/SKILL.md) | `/feature` | Checkpoint coordinator — groups tasks into batches, delegates each to `subagent-driven-development` (fresh author agent per task, full review chain), stops for user acknowledgement between batches. | | [subagent-driven-development](subagent-driven-development/SKILL.md) | `/sprint` (engine), `executing-plans` (batch scope) | Fresh subagent per task → spec-compliance then quality review → fresh-run verification; accepts only on proof. Hard-stops on `tdd` BLOCK, security CRITICAL, `[CONFIRM-NN]`. | diff --git a/core/surface/skills/brainstorming/SKILL.md b/core/surface/skills/brainstorming/SKILL.md index d89a63c2..6057902d 100644 --- a/core/surface/skills/brainstorming/SKILL.md +++ b/core/surface/skills/brainstorming/SKILL.md @@ -1,6 +1,6 @@ --- name: brainstorming -description: The Socratic spec-refinement front of /feature, and the planning front of /sprint. Routed to BEFORE any code — it takes a one-line idea and drives it to an approved, concrete spec with testable acceptance criteria. Four gated phases — frame, refine, write, approve. No implementation and no handoff to tdd until the spec is on disk and approved; each acceptance criterion becomes one tdd Phase 1 obligation. +description: The Socratic spec-refinement front of /feature, and the planning front of /sprint. Routed to BEFORE any code — it takes a one-line idea and drives it to an approved, concrete spec with testable acceptance criteria. Five gated phases — frame, shape, refine, write, review-and-approve. No implementation and no handoff to tdd until the spec is on disk and approved; each acceptance criterion becomes one tdd Phase 1 obligation. --- # brainstorming @@ -15,61 +15,92 @@ Read these, or STOP and surface the gap — never guess scope or stack: - `{{PROJECT_DIR}}/.codearbiter/tech-stack.md` — the stack the feature must fit; rule out incompatible designs early. - `{{PROJECT_DIR}}/.codearbiter/open-questions.md` — existing `[CONFIRM-NN]` items; new ones number sequentially from here. -Per-feature and light. NOT decompose's whole-project six-layer interview — one feature, four phases. +Per-feature and light. NOT decompose's whole-project six-layer interview — one feature, five phases. Depth scales with the feature, not the ceremony: a small feature earns a short pass through every phase, never a skipped one. A spec can be five sentences; it cannot be zero — smallness changes the spec's length, not its existence. ## Phase 1 — Frame the problem · gate: BLOCK -Take the one-line idea and pin its boundaries before asking anything else: +Take the one-line idea and pin its boundaries before designing or asking anything: - State the problem in one sentence — the concrete pain, not the proposed solution. - Name the user or caller who feels it, and what "done" looks like to them. - Name what this feature explicitly does NOT do — the boundary that keeps scope honest. - Check the framing against `CONTEXT.md`: it never contradicts the NOT-building list or redefines domain vocabulary. A contradiction is a conflict — surface it, do not reconcile it silently. +- **Split before you spend.** If the idea bundles more than one independently shippable concern — distinct callers, acceptance criteria that would partition into disjoint sets, separable data or surfaces — say so NOW and negotiate the split with the user before any refinement effort is spent on one piece. Each surviving piece is its own spec and its own run of this skill. A bundle discovered in Phase 4 has already wasted every question asked about the piece that gets cut. -Gate: problem, caller, and out-of-scope boundary stated and consistent with `CONTEXT.md`. +Gate: problem, caller, and out-of-scope boundary stated and consistent with `CONTEXT.md`, and the idea is confirmed to be ONE feature — or the split is agreed and this run proceeds on exactly one piece. -## Phase 2 — Socratic refinement loop · gate: BLOCK +## Phase 2 — Shape the approach · gate: BLOCK -One focused question at a time. Never advance on a hand-wavy answer. Run every answer through three lenses: +Before drilling into details, establish WHICH design the details belong to: -- **Vague language** — Force concrete nouns, numbers, and verbs. "Manage", "handle", "support" are not verbs. "Fast", "secure", "scalable" are not specifications. "We'll figure it out later" is not an answer — every "later" becomes a `[CONFIRM-NN]`. -- **Hidden complexity** — Name what the user assumes is easy but is hard: state, concurrency, edge cases, failure modes, validation, idempotency, migration of existing data. Surface it now or it surfaces in `tdd`. -- **Trade-off forcing** — When a real decision exists, frame it: "X gives you A but costs B; Y gives you C but costs D — choose." Do not pick for the user. +- Propose the genuine candidate approaches — usually two or three — each with its real trade-off stated (`X gives you A but costs B`). Recommend exactly one, with the reasoning that picks it. The user chooses under `/feature`; under `/sprint`, SMARTS chooses and the choice is logged with its scoring. +- **Never manufacture alternatives.** When only one sane approach exists, say so and say why — a padded list of straw options is noise wearing the costume of rigor, and it trains the reader to skim the one section that matters. +- Apply the isolation lens to the recommended shape while it is still soft: can each part be understood without reading its internals, and can its internals change without breaking its consumers? A design that fails this here fails it again in review, after the code exists. +- Apply the YAGNI lens: strike anything the Phase 1 problem statement does not demand. A capability the caller never asked for is scope creep with a head start. + +Gate: one approach chosen (user-chosen, or SMARTS-chosen and logged), its trade-off stated, and nothing in it the problem does not require. + +## Phase 3 — Socratic refinement loop · gate: BLOCK + +Turn the chosen approach concrete. The discipline is decide-or-ask, never drift: + +- **Decide the parameters; ask the forks.** A parameter-level choice — a naming, a default, a threshold, an ordering with one sensible answer — is yours to make: decide it, and record it in the spec where the user will see it at approval. A genuine fork — a real trade-off, a scope boundary, anything irreversible or user-visible — is the user's: ask it IN FULL the first time, leading with your recommendation and its reasoning. Never merely mention that an open decision exists; a named-but-unasked question is an omission wearing a disclaimer. +- **Batch what is independent.** Forks whose answers do not depend on each other are asked together, not serialized into rounds. One round of three real questions beats three rounds of one. +- Run every answer through three lenses: + - **Vague language** — force concrete nouns, numbers, and verbs. "Manage", "handle", "support" are not verbs. "Fast", "secure", "scalable" are not specifications. "We'll figure it out later" is not an answer — every "later" becomes a `[CONFIRM-NN]`. + - **Hidden complexity** — name what the user assumes is easy but is hard: state, concurrency, edge cases, failure modes, validation, idempotency, migration of existing data. Surface it now or it surfaces in `tdd`. + - **Trade-off forcing** — when a real decision exists, frame it with a recommendation and let the user rule. Do not pick for the user; do not hide that a pick exists. +- **The loop has a breaker.** When refinement stops converging — an answer contradicts an earlier one, or the same fork resurfaces after being answered — STOP the loop: restate the contradiction plainly, force one adjudication (a user ruling, or a recorded `[CONFIRM-NN]`), and only then continue. A loop that circles is not being thorough; it is failing to close. +- **Closure is a checklist, not a feeling.** The reasons to stop asking that do not count, each with why: + - *"The feature is simple enough."* — Simplicity shortens the spec; it does not waive it. The five-sentence spec still names its criteria. + - *"I've asked enough questions."* — Question fatigue is not an exit condition. The exit is the Phase 5 review passing. + - *"The user seems eager to move on."* — Eagerness is a signal to compress the asking (decide more parameters, batch harder), never to skip an unresolved fork. + - *"We can settle it during implementation."* — Every deferral is a `[CONFIRM-NN]` on record, or it is a guess that `tdd` will faithfully implement. Record every genuinely-unresolved unknown as `[CONFIRM-NN]` in `{{PROJECT_DIR}}/.codearbiter/open-questions.md`, numbered sequentially. A finding that belongs to a different feature or a future scope gets an inline `[NEEDS-TRIAGE]` marker in the notes — never route it to a ticket. -Gate: every vague term made concrete; every forced trade-off resolved or recorded as `[CONFIRM-NN]`; no unresolved "later" outside a `[CONFIRM-NN]`. A blocking `[CONFIRM-NN]` that gates the spec's core stops the loop — surface it and STOP. +Gate: every vague term made concrete; every fork resolved by the user or recorded as `[CONFIRM-NN]`; every parameter decision recorded in the spec draft; no unresolved "later" outside a `[CONFIRM-NN]`. A blocking `[CONFIRM-NN]` that gates the spec's core stops the loop — surface it and STOP. -## Phase 3 — Write the spec · gate: BLOCK +## Phase 4 — Write the spec · gate: BLOCK Write the agreed spec to `{{PROJECT_DIR}}/.codearbiter/specs/.md`. The slug is derived from the feature. The spec holds: - **Problem** — the Phase 1 framing in final form. +- **Approach** — the Phase 2 choice and the trade-off that picked it, in two or three sentences. - **Scope** — what is in, and the explicit out-of-scope boundary. +- **Decided parameters** — the parameter-level choices made in Phase 3, each in one line, so the approval reads them instead of discovering them in code review. - **Acceptance criteria** — a numbered list, each criterion concrete and testable: a specific input, the observable output, the boundary or failure behavior. Each criterion is verifiable by a single test. "It works well" is not a criterion. These become `tdd` Phase 1 obligations — one obligation per criterion, so an untestable criterion is a defect to fix here, not in `tdd`. - **Open questions** — every `[CONFIRM-NN]` raised, cross-referenced to `open-questions.md`. - **Governs** *(optional)* — a spec-header line `**Governs:** ` that enrolls the approved spec in file-scoped just-in-time context injection: on a Read of any file matching one of the listed globs, a pointer to this spec is surfaced to the agent (tier 3 of the file→knowledge map). Adding the line is sufficient to enroll; no other change required. Gate: the spec file exists on disk under `specs/`, with at least one acceptance criterion and every criterion individually testable. -## Phase 4 — Approval & handoff · gate: STOP +## Phase 5 — Review, approval & handoff · gate: STOP -The spec is approved before any code is written or any handoff to `tdd` occurs — no exceptions: +The spec earns its approval; it is not waved through. Two passes over the FILE as written, then the stop: -- **Under `/feature`** — present the spec and request explicit user approval. Iterate on the file in place until the user approves. A blocking `[CONFIRM-NN]` must be resolved by the user before approval — never auto-resolve it. -- **Under `/sprint`** — approval may be granted automatically by SMARTS scoring, logged to the `.codearbiter/` audit trail. A blocking `[CONFIRM-NN]` is never auto-approvable; it escalates to the user and STOPs the sprint flow. +1. **Mechanical self-review** — one pass, fix inline, no re-review: no placeholder text (`TBD`, `???`, an unfilled section); no criterion that contradicts the scope; nothing that crosses the `CONTEXT.md` NOT-building boundary; every criterion still testable by a single test after the edits; the vague-language lens applied to the spec's own prose. +2. **Adversarial pass** — build the strongest case AGAINST the design before the user reads it: the failure mode most likely to be real, the criterion most likely to be wrong, the assumption that would invalidate the approach if false. Present what survives WITH the spec at approval — the user rules on a challenged design, not a defended one. Finding nothing is a reportable result, stated in one line, not a silent skip. +3. **Approval:** + - **Under `/feature`** — present the spec and the adversarial findings, and request explicit user approval. Iterate on the file in place until the user approves. A blocking `[CONFIRM-NN]` must be resolved by the user before approval — never auto-resolve it. + - **Under `/sprint`** — approval may be granted automatically by SMARTS scoring, logged to the `.codearbiter/` audit trail. A blocking `[CONFIRM-NN]` is never auto-approvable; it escalates to the user and STOPs the sprint flow. On approval, hand off to the `tdd` skill, which enters Phase 1 against the approved spec — one obligation per acceptance criterion. -Gate: the spec is approved (by the user under `/feature`, or by logged SMARTS auto-approval under `/sprint`) with no unresolved blocking `[CONFIRM-NN]`. Only then does control pass to `tdd`. +Gate: both review passes run against the file on disk, adversarial findings presented, and the spec approved (by the user under `/feature`, or by logged SMARTS auto-approval under `/sprint`) with no unresolved blocking `[CONFIRM-NN]`. Only then does control pass to `tdd`. ## Hard rules - MUST NOT write implementation code or route to `tdd` before the spec is on disk under `specs/` AND approved. +- MUST NOT refine a bundle — an idea holding more than one independently shippable concern splits in Phase 1, before any question budget is spent. +- MUST NOT manufacture alternatives in Phase 2 — when one sane approach exists, say so and why. - MUST NOT write an acceptance criterion that cannot be verified by a single test. +- MUST decide parameter-level choices and record them in the spec; MUST ask genuine forks in full, with a recommendation, the first time — never name an open decision without asking it. +- MUST stop a non-converging refinement loop and force one adjudication — a contradiction or a resurfacing fork is a breaker, not a prompt to circle. +- MUST run the Phase 5 mechanical self-review and adversarial pass against the file as written, and present the adversarial findings at approval. - MUST NOT resolve a `[CONFIRM-NN]` by guessing — surface it and record it in `open-questions.md`. - MUST NOT auto-approve a spec carrying a blocking `[CONFIRM-NN]`, even under `/sprint` — it escalates to the user. - MUST NOT contradict the NOT-building list or redefine domain vocabulary in `CONTEXT.md` — a contradiction is a conflict to surface, not reconcile. -- MUST NOT run decompose's six-layer whole-project interview — this is one feature, four phases. +- MUST NOT run decompose's six-layer whole-project interview — this is one feature, five phases. - MUST log a `/sprint` auto-approval to the `.codearbiter/` audit trail. - MUST, at exit, run the follow-up harvest (`{{PLUGIN_ROOT}}/includes/harvest.md`) over any `[NEEDS-TRIAGE]` notes raised this run — batch-confirm promoting them to `open-tasks.md` (work) or `open-questions.md` (decisions) so out-of-scope ideas don't vanish. diff --git a/package.json b/package.json index 6a46a727..3fdbd9b7 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "ca-pi", - "version": "0.2.0", + "version": "0.2.4", "private": true, "license": "AGPL-3.0-only", "engines": { diff --git a/plugins/ca-codex/.codex-plugin/plugin.json b/plugins/ca-codex/.codex-plugin/plugin.json index d7bef188..36b6850a 100644 --- a/plugins/ca-codex/.codex-plugin/plugin.json +++ b/plugins/ca-codex/.codex-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "ca-codex", "description": "Governance kernel for OpenAI Codex CLI: the full codeArbiter surface — 37 ca-prefixed governance skills (spec-driven /feature pipeline, nine-gate commit gate, ADRs, audits) plus enforcement hooks (persona injection, blocking pre-exec and pre-write gates, append-only audit trail) — sharing one .codearbiter/ store with the Claude Code sibling plugin. Standalone: opt a repo in with ca-init; enforcement stays dormant until .codearbiter/CONTEXT.md carries 'arbiter: enabled'. Requires Python 3 and Codex >= 0.143.0. CI continuously verifies, through a real Codex host at 0.143.0 and 0.145.0, that the plugin installs, reads back enabled, and ships every hook script it declares; an advisory lane tracks npm latest for upstream drift. Hook FIRING - live persona injection and live blocks inside a turn - is verified by hand per release against docs/codex-parity-testing.md, because a turn needs a model and a provider credential cannot gate fork pull requests.", - "version": "0.4.0", + "version": "0.4.4", "author": { "name": "arbiterForge" }, diff --git a/plugins/ca-codex/routines/INDEX.md b/plugins/ca-codex/routines/INDEX.md index 7b589016..c27b608b 100644 --- a/plugins/ca-codex/routines/INDEX.md +++ b/plugins/ca-codex/routines/INDEX.md @@ -14,7 +14,7 @@ Skill bodies load on routing only. This index is the surface scan; never bulk-re | [refactor](refactor/SKILL.md) | `/refactor` | Behavior-preserving change behind a parity-coverage proof gate; routes to `tdd` Phase 1 only when new test seams are needed. | | [context-creation](context-creation/SKILL.md) | `/create-context` (brownfield) | Back-fills `.codearbiter/` from existing source via parallel scouts; writes `CONTEXT.md` (`arbiter: enabled` + `stage:`) and locks it ``. | | [decompose](decompose/SKILL.md) | greenfield startup, `/decompose` | Six-layer senior-architect interview, compaction-resilient via per-layer disk drafts + DRAFT ADRs; populates `.codearbiter/` and locks it initialized. | -| [brainstorming](brainstorming/SKILL.md) | `/feature` (front), `/sprint` planning | Socratic idea→spec: one question at a time, challenge vagueness, force trade-offs; writes `specs/.md` whose acceptance criteria become `tdd` obligations. Hard-gate: no code until the spec is approved. | +| [brainstorming](brainstorming/SKILL.md) | `/feature` (front), `/sprint` planning | Socratic idea→spec: split bundles, shape the approach, then decide parameters / ask forks in full; adversarial self-review before approval; writes `specs/.md` whose acceptance criteria become `tdd` obligations. Hard-gate: no code until the spec is approved. | | [writing-plans](writing-plans/SKILL.md) | `/feature`, `/sprint` (after the spec) | Decomposes an approved spec into small tasks, each with a path + a verification that maps to a `tdd` obligation; writes `plans/.md` with bijective criterion↔task coverage. | | [executing-plans](executing-plans/SKILL.md) | `/feature` | Checkpoint coordinator — groups tasks into batches, delegates each to `subagent-driven-development` (fresh author agent per task, full review chain), stops for user acknowledgement between batches. | | [subagent-driven-development](subagent-driven-development/SKILL.md) | `/sprint` (engine), `executing-plans` (batch scope) | Fresh subagent per task → spec-compliance then quality review → fresh-run verification; accepts only on proof. Hard-stops on `tdd` BLOCK, security CRITICAL, `[CONFIRM-NN]`. | diff --git a/plugins/ca-codex/routines/brainstorming/SKILL.md b/plugins/ca-codex/routines/brainstorming/SKILL.md index b058c111..138e5adf 100644 --- a/plugins/ca-codex/routines/brainstorming/SKILL.md +++ b/plugins/ca-codex/routines/brainstorming/SKILL.md @@ -1,6 +1,6 @@ --- name: brainstorming -description: The Socratic spec-refinement front of /feature, and the planning front of /sprint. Routed to BEFORE any code — it takes a one-line idea and drives it to an approved, concrete spec with testable acceptance criteria. Four gated phases — frame, refine, write, approve. No implementation and no handoff to tdd until the spec is on disk and approved; each acceptance criterion becomes one tdd Phase 1 obligation. +description: The Socratic spec-refinement front of /feature, and the planning front of /sprint. Routed to BEFORE any code — it takes a one-line idea and drives it to an approved, concrete spec with testable acceptance criteria. Five gated phases — frame, shape, refine, write, review-and-approve. No implementation and no handoff to tdd until the spec is on disk and approved; each acceptance criterion becomes one tdd Phase 1 obligation. --- # brainstorming @@ -15,61 +15,92 @@ Read these, or STOP and surface the gap — never guess scope or stack: - `/.codearbiter/tech-stack.md` — the stack the feature must fit; rule out incompatible designs early. - `/.codearbiter/open-questions.md` — existing `[CONFIRM-NN]` items; new ones number sequentially from here. -Per-feature and light. NOT decompose's whole-project six-layer interview — one feature, four phases. +Per-feature and light. NOT decompose's whole-project six-layer interview — one feature, five phases. Depth scales with the feature, not the ceremony: a small feature earns a short pass through every phase, never a skipped one. A spec can be five sentences; it cannot be zero — smallness changes the spec's length, not its existence. ## Phase 1 — Frame the problem · gate: BLOCK -Take the one-line idea and pin its boundaries before asking anything else: +Take the one-line idea and pin its boundaries before designing or asking anything: - State the problem in one sentence — the concrete pain, not the proposed solution. - Name the user or caller who feels it, and what "done" looks like to them. - Name what this feature explicitly does NOT do — the boundary that keeps scope honest. - Check the framing against `CONTEXT.md`: it never contradicts the NOT-building list or redefines domain vocabulary. A contradiction is a conflict — surface it, do not reconcile it silently. +- **Split before you spend.** If the idea bundles more than one independently shippable concern — distinct callers, acceptance criteria that would partition into disjoint sets, separable data or surfaces — say so NOW and negotiate the split with the user before any refinement effort is spent on one piece. Each surviving piece is its own spec and its own run of this skill. A bundle discovered in Phase 4 has already wasted every question asked about the piece that gets cut. -Gate: problem, caller, and out-of-scope boundary stated and consistent with `CONTEXT.md`. +Gate: problem, caller, and out-of-scope boundary stated and consistent with `CONTEXT.md`, and the idea is confirmed to be ONE feature — or the split is agreed and this run proceeds on exactly one piece. -## Phase 2 — Socratic refinement loop · gate: BLOCK +## Phase 2 — Shape the approach · gate: BLOCK -One focused question at a time. Never advance on a hand-wavy answer. Run every answer through three lenses: +Before drilling into details, establish WHICH design the details belong to: -- **Vague language** — Force concrete nouns, numbers, and verbs. "Manage", "handle", "support" are not verbs. "Fast", "secure", "scalable" are not specifications. "We'll figure it out later" is not an answer — every "later" becomes a `[CONFIRM-NN]`. -- **Hidden complexity** — Name what the user assumes is easy but is hard: state, concurrency, edge cases, failure modes, validation, idempotency, migration of existing data. Surface it now or it surfaces in `tdd`. -- **Trade-off forcing** — When a real decision exists, frame it: "X gives you A but costs B; Y gives you C but costs D — choose." Do not pick for the user. +- Propose the genuine candidate approaches — usually two or three — each with its real trade-off stated (`X gives you A but costs B`). Recommend exactly one, with the reasoning that picks it. The user chooses under `/feature`; under `/sprint`, SMARTS chooses and the choice is logged with its scoring. +- **Never manufacture alternatives.** When only one sane approach exists, say so and say why — a padded list of straw options is noise wearing the costume of rigor, and it trains the reader to skim the one section that matters. +- Apply the isolation lens to the recommended shape while it is still soft: can each part be understood without reading its internals, and can its internals change without breaking its consumers? A design that fails this here fails it again in review, after the code exists. +- Apply the YAGNI lens: strike anything the Phase 1 problem statement does not demand. A capability the caller never asked for is scope creep with a head start. + +Gate: one approach chosen (user-chosen, or SMARTS-chosen and logged), its trade-off stated, and nothing in it the problem does not require. + +## Phase 3 — Socratic refinement loop · gate: BLOCK + +Turn the chosen approach concrete. The discipline is decide-or-ask, never drift: + +- **Decide the parameters; ask the forks.** A parameter-level choice — a naming, a default, a threshold, an ordering with one sensible answer — is yours to make: decide it, and record it in the spec where the user will see it at approval. A genuine fork — a real trade-off, a scope boundary, anything irreversible or user-visible — is the user's: ask it IN FULL the first time, leading with your recommendation and its reasoning. Never merely mention that an open decision exists; a named-but-unasked question is an omission wearing a disclaimer. +- **Batch what is independent.** Forks whose answers do not depend on each other are asked together, not serialized into rounds. One round of three real questions beats three rounds of one. +- Run every answer through three lenses: + - **Vague language** — force concrete nouns, numbers, and verbs. "Manage", "handle", "support" are not verbs. "Fast", "secure", "scalable" are not specifications. "We'll figure it out later" is not an answer — every "later" becomes a `[CONFIRM-NN]`. + - **Hidden complexity** — name what the user assumes is easy but is hard: state, concurrency, edge cases, failure modes, validation, idempotency, migration of existing data. Surface it now or it surfaces in `tdd`. + - **Trade-off forcing** — when a real decision exists, frame it with a recommendation and let the user rule. Do not pick for the user; do not hide that a pick exists. +- **The loop has a breaker.** When refinement stops converging — an answer contradicts an earlier one, or the same fork resurfaces after being answered — STOP the loop: restate the contradiction plainly, force one adjudication (a user ruling, or a recorded `[CONFIRM-NN]`), and only then continue. A loop that circles is not being thorough; it is failing to close. +- **Closure is a checklist, not a feeling.** The reasons to stop asking that do not count, each with why: + - *"The feature is simple enough."* — Simplicity shortens the spec; it does not waive it. The five-sentence spec still names its criteria. + - *"I've asked enough questions."* — Question fatigue is not an exit condition. The exit is the Phase 5 review passing. + - *"The user seems eager to move on."* — Eagerness is a signal to compress the asking (decide more parameters, batch harder), never to skip an unresolved fork. + - *"We can settle it during implementation."* — Every deferral is a `[CONFIRM-NN]` on record, or it is a guess that `tdd` will faithfully implement. Record every genuinely-unresolved unknown as `[CONFIRM-NN]` in `/.codearbiter/open-questions.md`, numbered sequentially. A finding that belongs to a different feature or a future scope gets an inline `[NEEDS-TRIAGE]` marker in the notes — never route it to a ticket. -Gate: every vague term made concrete; every forced trade-off resolved or recorded as `[CONFIRM-NN]`; no unresolved "later" outside a `[CONFIRM-NN]`. A blocking `[CONFIRM-NN]` that gates the spec's core stops the loop — surface it and STOP. +Gate: every vague term made concrete; every fork resolved by the user or recorded as `[CONFIRM-NN]`; every parameter decision recorded in the spec draft; no unresolved "later" outside a `[CONFIRM-NN]`. A blocking `[CONFIRM-NN]` that gates the spec's core stops the loop — surface it and STOP. -## Phase 3 — Write the spec · gate: BLOCK +## Phase 4 — Write the spec · gate: BLOCK Write the agreed spec to `/.codearbiter/specs/.md`. The slug is derived from the feature. The spec holds: - **Problem** — the Phase 1 framing in final form. +- **Approach** — the Phase 2 choice and the trade-off that picked it, in two or three sentences. - **Scope** — what is in, and the explicit out-of-scope boundary. +- **Decided parameters** — the parameter-level choices made in Phase 3, each in one line, so the approval reads them instead of discovering them in code review. - **Acceptance criteria** — a numbered list, each criterion concrete and testable: a specific input, the observable output, the boundary or failure behavior. Each criterion is verifiable by a single test. "It works well" is not a criterion. These become `tdd` Phase 1 obligations — one obligation per criterion, so an untestable criterion is a defect to fix here, not in `tdd`. - **Open questions** — every `[CONFIRM-NN]` raised, cross-referenced to `open-questions.md`. - **Governs** *(optional)* — a spec-header line `**Governs:** ` that enrolls the approved spec in file-scoped just-in-time context injection: on a Read of any file matching one of the listed globs, a pointer to this spec is surfaced to the agent (tier 3 of the file→knowledge map). Adding the line is sufficient to enroll; no other change required. Gate: the spec file exists on disk under `specs/`, with at least one acceptance criterion and every criterion individually testable. -## Phase 4 — Approval & handoff · gate: STOP +## Phase 5 — Review, approval & handoff · gate: STOP -The spec is approved before any code is written or any handoff to `tdd` occurs — no exceptions: +The spec earns its approval; it is not waved through. Two passes over the FILE as written, then the stop: -- **Under `/feature`** — present the spec and request explicit user approval. Iterate on the file in place until the user approves. A blocking `[CONFIRM-NN]` must be resolved by the user before approval — never auto-resolve it. -- **Under `/sprint`** — approval may be granted automatically by SMARTS scoring, logged to the `.codearbiter/` audit trail. A blocking `[CONFIRM-NN]` is never auto-approvable; it escalates to the user and STOPs the sprint flow. +1. **Mechanical self-review** — one pass, fix inline, no re-review: no placeholder text (`TBD`, `???`, an unfilled section); no criterion that contradicts the scope; nothing that crosses the `CONTEXT.md` NOT-building boundary; every criterion still testable by a single test after the edits; the vague-language lens applied to the spec's own prose. +2. **Adversarial pass** — build the strongest case AGAINST the design before the user reads it: the failure mode most likely to be real, the criterion most likely to be wrong, the assumption that would invalidate the approach if false. Present what survives WITH the spec at approval — the user rules on a challenged design, not a defended one. Finding nothing is a reportable result, stated in one line, not a silent skip. +3. **Approval:** + - **Under `/feature`** — present the spec and the adversarial findings, and request explicit user approval. Iterate on the file in place until the user approves. A blocking `[CONFIRM-NN]` must be resolved by the user before approval — never auto-resolve it. + - **Under `/sprint`** — approval may be granted automatically by SMARTS scoring, logged to the `.codearbiter/` audit trail. A blocking `[CONFIRM-NN]` is never auto-approvable; it escalates to the user and STOPs the sprint flow. On approval, hand off to the `tdd` skill, which enters Phase 1 against the approved spec — one obligation per acceptance criterion. -Gate: the spec is approved (by the user under `/feature`, or by logged SMARTS auto-approval under `/sprint`) with no unresolved blocking `[CONFIRM-NN]`. Only then does control pass to `tdd`. +Gate: both review passes run against the file on disk, adversarial findings presented, and the spec approved (by the user under `/feature`, or by logged SMARTS auto-approval under `/sprint`) with no unresolved blocking `[CONFIRM-NN]`. Only then does control pass to `tdd`. ## Hard rules - MUST NOT write implementation code or route to `tdd` before the spec is on disk under `specs/` AND approved. +- MUST NOT refine a bundle — an idea holding more than one independently shippable concern splits in Phase 1, before any question budget is spent. +- MUST NOT manufacture alternatives in Phase 2 — when one sane approach exists, say so and why. - MUST NOT write an acceptance criterion that cannot be verified by a single test. +- MUST decide parameter-level choices and record them in the spec; MUST ask genuine forks in full, with a recommendation, the first time — never name an open decision without asking it. +- MUST stop a non-converging refinement loop and force one adjudication — a contradiction or a resurfacing fork is a breaker, not a prompt to circle. +- MUST run the Phase 5 mechanical self-review and adversarial pass against the file as written, and present the adversarial findings at approval. - MUST NOT resolve a `[CONFIRM-NN]` by guessing — surface it and record it in `open-questions.md`. - MUST NOT auto-approve a spec carrying a blocking `[CONFIRM-NN]`, even under `/sprint` — it escalates to the user. - MUST NOT contradict the NOT-building list or redefine domain vocabulary in `CONTEXT.md` — a contradiction is a conflict to surface, not reconcile. -- MUST NOT run decompose's six-layer whole-project interview — this is one feature, four phases. +- MUST NOT run decompose's six-layer whole-project interview — this is one feature, five phases. - MUST log a `/sprint` auto-approval to the `.codearbiter/` audit trail. - MUST, at exit, run the follow-up harvest (`${CLAUDE_PLUGIN_ROOT}/includes/harvest.md`) over any `[NEEDS-TRIAGE]` notes raised this run — batch-confirm promoting them to `open-tasks.md` (work) or `open-questions.md` (decisions) so out-of-scope ideas don't vanish. diff --git a/plugins/ca-pi/CHANGELOG.md b/plugins/ca-pi/CHANGELOG.md index 3b25e536..0c02c904 100644 --- a/plugins/ca-pi/CHANGELOG.md +++ b/plugins/ca-pi/CHANGELOG.md @@ -4,6 +4,12 @@ All notable changes to `ca-pi` are documented in this file. ## [Unreleased] +## [0.2.4] - 2026-08-04 + +### Changed + +- The `brainstorming` routine is modernized for capable models: bundles split before refinement, candidate approaches shaped with one recommendation, parameter choices decided-and-recorded while genuine forks are asked in full, a breaker stops non-converging loops, and the spec is mechanically self-reviewed and adversarially challenged before approval. + ## [0.2.0] - 2026-08-01 ### Added diff --git a/plugins/ca-pi/package.json b/plugins/ca-pi/package.json index 35bee47c..f79f9557 100644 --- a/plugins/ca-pi/package.json +++ b/plugins/ca-pi/package.json @@ -1,6 +1,6 @@ { "name": "ca-pi", - "version": "0.2.0", + "version": "0.2.4", "private": true, "license": "AGPL-3.0-only", "type": "module", diff --git a/plugins/ca-pi/routines/INDEX.md b/plugins/ca-pi/routines/INDEX.md index 2070f0f4..922b651c 100644 --- a/plugins/ca-pi/routines/INDEX.md +++ b/plugins/ca-pi/routines/INDEX.md @@ -14,7 +14,7 @@ Skill bodies load on routing only. This index is the surface scan; never bulk-re | [refactor](refactor/SKILL.md) | `/refactor` | Behavior-preserving change behind a parity-coverage proof gate; routes to `tdd` Phase 1 only when new test seams are needed. | | [context-creation](context-creation/SKILL.md) | `/create-context` (brownfield) | Back-fills `.codearbiter/` from existing source via parallel scouts; writes `CONTEXT.md` (`arbiter: enabled` + `stage:`) and locks it ``. | | [decompose](decompose/SKILL.md) | greenfield startup, `/decompose` | Six-layer senior-architect interview, compaction-resilient via per-layer disk drafts + DRAFT ADRs; populates `.codearbiter/` and locks it initialized. | -| [brainstorming](brainstorming/SKILL.md) | `/feature` (front), `/sprint` planning | Socratic idea→spec: one question at a time, challenge vagueness, force trade-offs; writes `specs/.md` whose acceptance criteria become `tdd` obligations. Hard-gate: no code until the spec is approved. | +| [brainstorming](brainstorming/SKILL.md) | `/feature` (front), `/sprint` planning | Socratic idea→spec: split bundles, shape the approach, then decide parameters / ask forks in full; adversarial self-review before approval; writes `specs/.md` whose acceptance criteria become `tdd` obligations. Hard-gate: no code until the spec is approved. | | [writing-plans](writing-plans/SKILL.md) | `/feature`, `/sprint` (after the spec) | Decomposes an approved spec into small tasks, each with a path + a verification that maps to a `tdd` obligation; writes `plans/.md` with bijective criterion↔task coverage. | | [executing-plans](executing-plans/SKILL.md) | `/feature` | Checkpoint coordinator — groups tasks into batches, delegates each to `subagent-driven-development` (fresh author agent per task, full review chain), stops for user acknowledgement between batches. | | [subagent-driven-development](subagent-driven-development/SKILL.md) | `/sprint` (engine), `executing-plans` (batch scope) | Fresh subagent per task → spec-compliance then quality review → fresh-run verification; accepts only on proof. Hard-stops on `tdd` BLOCK, security CRITICAL, `[CONFIRM-NN]`. | diff --git a/plugins/ca-pi/routines/brainstorming/SKILL.md b/plugins/ca-pi/routines/brainstorming/SKILL.md index c94caba7..e5cc59f4 100644 --- a/plugins/ca-pi/routines/brainstorming/SKILL.md +++ b/plugins/ca-pi/routines/brainstorming/SKILL.md @@ -1,6 +1,6 @@ --- name: brainstorming -description: The Socratic spec-refinement front of /feature, and the planning front of /sprint. Routed to BEFORE any code — it takes a one-line idea and drives it to an approved, concrete spec with testable acceptance criteria. Four gated phases — frame, refine, write, approve. No implementation and no handoff to tdd until the spec is on disk and approved; each acceptance criterion becomes one tdd Phase 1 obligation. +description: The Socratic spec-refinement front of /feature, and the planning front of /sprint. Routed to BEFORE any code — it takes a one-line idea and drives it to an approved, concrete spec with testable acceptance criteria. Five gated phases — frame, shape, refine, write, review-and-approve. No implementation and no handoff to tdd until the spec is on disk and approved; each acceptance criterion becomes one tdd Phase 1 obligation. --- # brainstorming @@ -15,61 +15,92 @@ Read these, or STOP and surface the gap — never guess scope or stack: - `/.codearbiter/tech-stack.md` — the stack the feature must fit; rule out incompatible designs early. - `/.codearbiter/open-questions.md` — existing `[CONFIRM-NN]` items; new ones number sequentially from here. -Per-feature and light. NOT decompose's whole-project six-layer interview — one feature, four phases. +Per-feature and light. NOT decompose's whole-project six-layer interview — one feature, five phases. Depth scales with the feature, not the ceremony: a small feature earns a short pass through every phase, never a skipped one. A spec can be five sentences; it cannot be zero — smallness changes the spec's length, not its existence. ## Phase 1 — Frame the problem · gate: BLOCK -Take the one-line idea and pin its boundaries before asking anything else: +Take the one-line idea and pin its boundaries before designing or asking anything: - State the problem in one sentence — the concrete pain, not the proposed solution. - Name the user or caller who feels it, and what "done" looks like to them. - Name what this feature explicitly does NOT do — the boundary that keeps scope honest. - Check the framing against `CONTEXT.md`: it never contradicts the NOT-building list or redefines domain vocabulary. A contradiction is a conflict — surface it, do not reconcile it silently. +- **Split before you spend.** If the idea bundles more than one independently shippable concern — distinct callers, acceptance criteria that would partition into disjoint sets, separable data or surfaces — say so NOW and negotiate the split with the user before any refinement effort is spent on one piece. Each surviving piece is its own spec and its own run of this skill. A bundle discovered in Phase 4 has already wasted every question asked about the piece that gets cut. -Gate: problem, caller, and out-of-scope boundary stated and consistent with `CONTEXT.md`. +Gate: problem, caller, and out-of-scope boundary stated and consistent with `CONTEXT.md`, and the idea is confirmed to be ONE feature — or the split is agreed and this run proceeds on exactly one piece. -## Phase 2 — Socratic refinement loop · gate: BLOCK +## Phase 2 — Shape the approach · gate: BLOCK -One focused question at a time. Never advance on a hand-wavy answer. Run every answer through three lenses: +Before drilling into details, establish WHICH design the details belong to: -- **Vague language** — Force concrete nouns, numbers, and verbs. "Manage", "handle", "support" are not verbs. "Fast", "secure", "scalable" are not specifications. "We'll figure it out later" is not an answer — every "later" becomes a `[CONFIRM-NN]`. -- **Hidden complexity** — Name what the user assumes is easy but is hard: state, concurrency, edge cases, failure modes, validation, idempotency, migration of existing data. Surface it now or it surfaces in `tdd`. -- **Trade-off forcing** — When a real decision exists, frame it: "X gives you A but costs B; Y gives you C but costs D — choose." Do not pick for the user. +- Propose the genuine candidate approaches — usually two or three — each with its real trade-off stated (`X gives you A but costs B`). Recommend exactly one, with the reasoning that picks it. The user chooses under `/feature`; under `/sprint`, SMARTS chooses and the choice is logged with its scoring. +- **Never manufacture alternatives.** When only one sane approach exists, say so and say why — a padded list of straw options is noise wearing the costume of rigor, and it trains the reader to skim the one section that matters. +- Apply the isolation lens to the recommended shape while it is still soft: can each part be understood without reading its internals, and can its internals change without breaking its consumers? A design that fails this here fails it again in review, after the code exists. +- Apply the YAGNI lens: strike anything the Phase 1 problem statement does not demand. A capability the caller never asked for is scope creep with a head start. + +Gate: one approach chosen (user-chosen, or SMARTS-chosen and logged), its trade-off stated, and nothing in it the problem does not require. + +## Phase 3 — Socratic refinement loop · gate: BLOCK + +Turn the chosen approach concrete. The discipline is decide-or-ask, never drift: + +- **Decide the parameters; ask the forks.** A parameter-level choice — a naming, a default, a threshold, an ordering with one sensible answer — is yours to make: decide it, and record it in the spec where the user will see it at approval. A genuine fork — a real trade-off, a scope boundary, anything irreversible or user-visible — is the user's: ask it IN FULL the first time, leading with your recommendation and its reasoning. Never merely mention that an open decision exists; a named-but-unasked question is an omission wearing a disclaimer. +- **Batch what is independent.** Forks whose answers do not depend on each other are asked together, not serialized into rounds. One round of three real questions beats three rounds of one. +- Run every answer through three lenses: + - **Vague language** — force concrete nouns, numbers, and verbs. "Manage", "handle", "support" are not verbs. "Fast", "secure", "scalable" are not specifications. "We'll figure it out later" is not an answer — every "later" becomes a `[CONFIRM-NN]`. + - **Hidden complexity** — name what the user assumes is easy but is hard: state, concurrency, edge cases, failure modes, validation, idempotency, migration of existing data. Surface it now or it surfaces in `tdd`. + - **Trade-off forcing** — when a real decision exists, frame it with a recommendation and let the user rule. Do not pick for the user; do not hide that a pick exists. +- **The loop has a breaker.** When refinement stops converging — an answer contradicts an earlier one, or the same fork resurfaces after being answered — STOP the loop: restate the contradiction plainly, force one adjudication (a user ruling, or a recorded `[CONFIRM-NN]`), and only then continue. A loop that circles is not being thorough; it is failing to close. +- **Closure is a checklist, not a feeling.** The reasons to stop asking that do not count, each with why: + - *"The feature is simple enough."* — Simplicity shortens the spec; it does not waive it. The five-sentence spec still names its criteria. + - *"I've asked enough questions."* — Question fatigue is not an exit condition. The exit is the Phase 5 review passing. + - *"The user seems eager to move on."* — Eagerness is a signal to compress the asking (decide more parameters, batch harder), never to skip an unresolved fork. + - *"We can settle it during implementation."* — Every deferral is a `[CONFIRM-NN]` on record, or it is a guess that `tdd` will faithfully implement. Record every genuinely-unresolved unknown as `[CONFIRM-NN]` in `/.codearbiter/open-questions.md`, numbered sequentially. A finding that belongs to a different feature or a future scope gets an inline `[NEEDS-TRIAGE]` marker in the notes — never route it to a ticket. -Gate: every vague term made concrete; every forced trade-off resolved or recorded as `[CONFIRM-NN]`; no unresolved "later" outside a `[CONFIRM-NN]`. A blocking `[CONFIRM-NN]` that gates the spec's core stops the loop — surface it and STOP. +Gate: every vague term made concrete; every fork resolved by the user or recorded as `[CONFIRM-NN]`; every parameter decision recorded in the spec draft; no unresolved "later" outside a `[CONFIRM-NN]`. A blocking `[CONFIRM-NN]` that gates the spec's core stops the loop — surface it and STOP. -## Phase 3 — Write the spec · gate: BLOCK +## Phase 4 — Write the spec · gate: BLOCK Write the agreed spec to `/.codearbiter/specs/.md`. The slug is derived from the feature. The spec holds: - **Problem** — the Phase 1 framing in final form. +- **Approach** — the Phase 2 choice and the trade-off that picked it, in two or three sentences. - **Scope** — what is in, and the explicit out-of-scope boundary. +- **Decided parameters** — the parameter-level choices made in Phase 3, each in one line, so the approval reads them instead of discovering them in code review. - **Acceptance criteria** — a numbered list, each criterion concrete and testable: a specific input, the observable output, the boundary or failure behavior. Each criterion is verifiable by a single test. "It works well" is not a criterion. These become `tdd` Phase 1 obligations — one obligation per criterion, so an untestable criterion is a defect to fix here, not in `tdd`. - **Open questions** — every `[CONFIRM-NN]` raised, cross-referenced to `open-questions.md`. - **Governs** *(optional)* — a spec-header line `**Governs:** ` that enrolls the approved spec in file-scoped just-in-time context injection: on a Read of any file matching one of the listed globs, a pointer to this spec is surfaced to the agent (tier 3 of the file→knowledge map). Adding the line is sufficient to enroll; no other change required. Gate: the spec file exists on disk under `specs/`, with at least one acceptance criterion and every criterion individually testable. -## Phase 4 — Approval & handoff · gate: STOP +## Phase 5 — Review, approval & handoff · gate: STOP -The spec is approved before any code is written or any handoff to `tdd` occurs — no exceptions: +The spec earns its approval; it is not waved through. Two passes over the FILE as written, then the stop: -- **Under `/feature`** — present the spec and request explicit user approval. Iterate on the file in place until the user approves. A blocking `[CONFIRM-NN]` must be resolved by the user before approval — never auto-resolve it. -- **Under `/sprint`** — approval may be granted automatically by SMARTS scoring, logged to the `.codearbiter/` audit trail. A blocking `[CONFIRM-NN]` is never auto-approvable; it escalates to the user and STOPs the sprint flow. +1. **Mechanical self-review** — one pass, fix inline, no re-review: no placeholder text (`TBD`, `???`, an unfilled section); no criterion that contradicts the scope; nothing that crosses the `CONTEXT.md` NOT-building boundary; every criterion still testable by a single test after the edits; the vague-language lens applied to the spec's own prose. +2. **Adversarial pass** — build the strongest case AGAINST the design before the user reads it: the failure mode most likely to be real, the criterion most likely to be wrong, the assumption that would invalidate the approach if false. Present what survives WITH the spec at approval — the user rules on a challenged design, not a defended one. Finding nothing is a reportable result, stated in one line, not a silent skip. +3. **Approval:** + - **Under `/feature`** — present the spec and the adversarial findings, and request explicit user approval. Iterate on the file in place until the user approves. A blocking `[CONFIRM-NN]` must be resolved by the user before approval — never auto-resolve it. + - **Under `/sprint`** — approval may be granted automatically by SMARTS scoring, logged to the `.codearbiter/` audit trail. A blocking `[CONFIRM-NN]` is never auto-approvable; it escalates to the user and STOPs the sprint flow. On approval, hand off to the `tdd` skill, which enters Phase 1 against the approved spec — one obligation per acceptance criterion. -Gate: the spec is approved (by the user under `/feature`, or by logged SMARTS auto-approval under `/sprint`) with no unresolved blocking `[CONFIRM-NN]`. Only then does control pass to `tdd`. +Gate: both review passes run against the file on disk, adversarial findings presented, and the spec approved (by the user under `/feature`, or by logged SMARTS auto-approval under `/sprint`) with no unresolved blocking `[CONFIRM-NN]`. Only then does control pass to `tdd`. ## Hard rules - MUST NOT write implementation code or route to `tdd` before the spec is on disk under `specs/` AND approved. +- MUST NOT refine a bundle — an idea holding more than one independently shippable concern splits in Phase 1, before any question budget is spent. +- MUST NOT manufacture alternatives in Phase 2 — when one sane approach exists, say so and why. - MUST NOT write an acceptance criterion that cannot be verified by a single test. +- MUST decide parameter-level choices and record them in the spec; MUST ask genuine forks in full, with a recommendation, the first time — never name an open decision without asking it. +- MUST stop a non-converging refinement loop and force one adjudication — a contradiction or a resurfacing fork is a breaker, not a prompt to circle. +- MUST run the Phase 5 mechanical self-review and adversarial pass against the file as written, and present the adversarial findings at approval. - MUST NOT resolve a `[CONFIRM-NN]` by guessing — surface it and record it in `open-questions.md`. - MUST NOT auto-approve a spec carrying a blocking `[CONFIRM-NN]`, even under `/sprint` — it escalates to the user. - MUST NOT contradict the NOT-building list or redefine domain vocabulary in `CONTEXT.md` — a contradiction is a conflict to surface, not reconcile. -- MUST NOT run decompose's six-layer whole-project interview — this is one feature, four phases. +- MUST NOT run decompose's six-layer whole-project interview — this is one feature, five phases. - MUST log a `/sprint` auto-approval to the `.codearbiter/` audit trail. - MUST, at exit, run the follow-up harvest (`/includes/harvest.md`) over any `[NEEDS-TRIAGE]` notes raised this run — batch-confirm promoting them to `open-tasks.md` (work) or `open-questions.md` (decisions) so out-of-scope ideas don't vanish. diff --git a/plugins/ca/.claude-plugin/plugin.json b/plugins/ca/.claude-plugin/plugin.json index f963449c..2bc213d4 100644 --- a/plugins/ca/.claude-plugin/plugin.json +++ b/plugins/ca/.claude-plugin/plugin.json @@ -2,7 +2,7 @@ "name": "ca", "displayName": "codeArbiter", "description": "Orchestration layer for Claude Code. Routes every intent through gated skills and reviewer agents, drives spec-driven TDD, mechanically enforces the commit and audit-trail gates, decides via SMARTS, and keeps an append-only audit trail. Requires Python 3 on PATH. Dormant until you opt a repo in; run /ca:init to activate.", - "version": "2.11.1", + "version": "2.11.5", "author": { "name": "arbiterForge" }, "license": "AGPL-3.0-only", "homepage": "https://github.com/arbiterForge/codeArbiter", diff --git a/plugins/ca/skills/INDEX.md b/plugins/ca/skills/INDEX.md index 9fd95843..e9438f38 100644 --- a/plugins/ca/skills/INDEX.md +++ b/plugins/ca/skills/INDEX.md @@ -14,7 +14,7 @@ Skill bodies load on routing only. This index is the surface scan; never bulk-re | [refactor](refactor/SKILL.md) | `/refactor` | Behavior-preserving change behind a parity-coverage proof gate; routes to `tdd` Phase 1 only when new test seams are needed. | | [context-creation](context-creation/SKILL.md) | `/create-context` (brownfield) | Back-fills `.codearbiter/` from existing source via parallel scouts; writes `CONTEXT.md` (`arbiter: enabled` + `stage:`) and locks it ``. | | [decompose](decompose/SKILL.md) | greenfield startup, `/decompose` | Six-layer senior-architect interview, compaction-resilient via per-layer disk drafts + DRAFT ADRs; populates `.codearbiter/` and locks it initialized. | -| [brainstorming](brainstorming/SKILL.md) | `/feature` (front), `/sprint` planning | Socratic idea→spec: one question at a time, challenge vagueness, force trade-offs; writes `specs/.md` whose acceptance criteria become `tdd` obligations. Hard-gate: no code until the spec is approved. | +| [brainstorming](brainstorming/SKILL.md) | `/feature` (front), `/sprint` planning | Socratic idea→spec: split bundles, shape the approach, then decide parameters / ask forks in full; adversarial self-review before approval; writes `specs/.md` whose acceptance criteria become `tdd` obligations. Hard-gate: no code until the spec is approved. | | [writing-plans](writing-plans/SKILL.md) | `/feature`, `/sprint` (after the spec) | Decomposes an approved spec into small tasks, each with a path + a verification that maps to a `tdd` obligation; writes `plans/.md` with bijective criterion↔task coverage. | | [executing-plans](executing-plans/SKILL.md) | `/feature` | Checkpoint coordinator — groups tasks into batches, delegates each to `subagent-driven-development` (fresh author agent per task, full review chain), stops for user acknowledgement between batches. | | [subagent-driven-development](subagent-driven-development/SKILL.md) | `/sprint` (engine), `executing-plans` (batch scope) | Fresh subagent per task → spec-compliance then quality review → fresh-run verification; accepts only on proof. Hard-stops on `tdd` BLOCK, security CRITICAL, `[CONFIRM-NN]`. | diff --git a/plugins/ca/skills/brainstorming/SKILL.md b/plugins/ca/skills/brainstorming/SKILL.md index bf813809..d9d8f6e6 100644 --- a/plugins/ca/skills/brainstorming/SKILL.md +++ b/plugins/ca/skills/brainstorming/SKILL.md @@ -1,6 +1,6 @@ --- name: brainstorming -description: The Socratic spec-refinement front of /feature, and the planning front of /sprint. Routed to BEFORE any code — it takes a one-line idea and drives it to an approved, concrete spec with testable acceptance criteria. Four gated phases — frame, refine, write, approve. No implementation and no handoff to tdd until the spec is on disk and approved; each acceptance criterion becomes one tdd Phase 1 obligation. +description: The Socratic spec-refinement front of /feature, and the planning front of /sprint. Routed to BEFORE any code — it takes a one-line idea and drives it to an approved, concrete spec with testable acceptance criteria. Five gated phases — frame, shape, refine, write, review-and-approve. No implementation and no handoff to tdd until the spec is on disk and approved; each acceptance criterion becomes one tdd Phase 1 obligation. --- # brainstorming @@ -15,61 +15,92 @@ Read these, or STOP and surface the gap — never guess scope or stack: - `${CLAUDE_PROJECT_DIR}/.codearbiter/tech-stack.md` — the stack the feature must fit; rule out incompatible designs early. - `${CLAUDE_PROJECT_DIR}/.codearbiter/open-questions.md` — existing `[CONFIRM-NN]` items; new ones number sequentially from here. -Per-feature and light. NOT decompose's whole-project six-layer interview — one feature, four phases. +Per-feature and light. NOT decompose's whole-project six-layer interview — one feature, five phases. Depth scales with the feature, not the ceremony: a small feature earns a short pass through every phase, never a skipped one. A spec can be five sentences; it cannot be zero — smallness changes the spec's length, not its existence. ## Phase 1 — Frame the problem · gate: BLOCK -Take the one-line idea and pin its boundaries before asking anything else: +Take the one-line idea and pin its boundaries before designing or asking anything: - State the problem in one sentence — the concrete pain, not the proposed solution. - Name the user or caller who feels it, and what "done" looks like to them. - Name what this feature explicitly does NOT do — the boundary that keeps scope honest. - Check the framing against `CONTEXT.md`: it never contradicts the NOT-building list or redefines domain vocabulary. A contradiction is a conflict — surface it, do not reconcile it silently. +- **Split before you spend.** If the idea bundles more than one independently shippable concern — distinct callers, acceptance criteria that would partition into disjoint sets, separable data or surfaces — say so NOW and negotiate the split with the user before any refinement effort is spent on one piece. Each surviving piece is its own spec and its own run of this skill. A bundle discovered in Phase 4 has already wasted every question asked about the piece that gets cut. -Gate: problem, caller, and out-of-scope boundary stated and consistent with `CONTEXT.md`. +Gate: problem, caller, and out-of-scope boundary stated and consistent with `CONTEXT.md`, and the idea is confirmed to be ONE feature — or the split is agreed and this run proceeds on exactly one piece. -## Phase 2 — Socratic refinement loop · gate: BLOCK +## Phase 2 — Shape the approach · gate: BLOCK -One focused question at a time. Never advance on a hand-wavy answer. Run every answer through three lenses: +Before drilling into details, establish WHICH design the details belong to: -- **Vague language** — Force concrete nouns, numbers, and verbs. "Manage", "handle", "support" are not verbs. "Fast", "secure", "scalable" are not specifications. "We'll figure it out later" is not an answer — every "later" becomes a `[CONFIRM-NN]`. -- **Hidden complexity** — Name what the user assumes is easy but is hard: state, concurrency, edge cases, failure modes, validation, idempotency, migration of existing data. Surface it now or it surfaces in `tdd`. -- **Trade-off forcing** — When a real decision exists, frame it: "X gives you A but costs B; Y gives you C but costs D — choose." Do not pick for the user. +- Propose the genuine candidate approaches — usually two or three — each with its real trade-off stated (`X gives you A but costs B`). Recommend exactly one, with the reasoning that picks it. The user chooses under `/feature`; under `/sprint`, SMARTS chooses and the choice is logged with its scoring. +- **Never manufacture alternatives.** When only one sane approach exists, say so and say why — a padded list of straw options is noise wearing the costume of rigor, and it trains the reader to skim the one section that matters. +- Apply the isolation lens to the recommended shape while it is still soft: can each part be understood without reading its internals, and can its internals change without breaking its consumers? A design that fails this here fails it again in review, after the code exists. +- Apply the YAGNI lens: strike anything the Phase 1 problem statement does not demand. A capability the caller never asked for is scope creep with a head start. + +Gate: one approach chosen (user-chosen, or SMARTS-chosen and logged), its trade-off stated, and nothing in it the problem does not require. + +## Phase 3 — Socratic refinement loop · gate: BLOCK + +Turn the chosen approach concrete. The discipline is decide-or-ask, never drift: + +- **Decide the parameters; ask the forks.** A parameter-level choice — a naming, a default, a threshold, an ordering with one sensible answer — is yours to make: decide it, and record it in the spec where the user will see it at approval. A genuine fork — a real trade-off, a scope boundary, anything irreversible or user-visible — is the user's: ask it IN FULL the first time, leading with your recommendation and its reasoning. Never merely mention that an open decision exists; a named-but-unasked question is an omission wearing a disclaimer. +- **Batch what is independent.** Forks whose answers do not depend on each other are asked together, not serialized into rounds. One round of three real questions beats three rounds of one. +- Run every answer through three lenses: + - **Vague language** — force concrete nouns, numbers, and verbs. "Manage", "handle", "support" are not verbs. "Fast", "secure", "scalable" are not specifications. "We'll figure it out later" is not an answer — every "later" becomes a `[CONFIRM-NN]`. + - **Hidden complexity** — name what the user assumes is easy but is hard: state, concurrency, edge cases, failure modes, validation, idempotency, migration of existing data. Surface it now or it surfaces in `tdd`. + - **Trade-off forcing** — when a real decision exists, frame it with a recommendation and let the user rule. Do not pick for the user; do not hide that a pick exists. +- **The loop has a breaker.** When refinement stops converging — an answer contradicts an earlier one, or the same fork resurfaces after being answered — STOP the loop: restate the contradiction plainly, force one adjudication (a user ruling, or a recorded `[CONFIRM-NN]`), and only then continue. A loop that circles is not being thorough; it is failing to close. +- **Closure is a checklist, not a feeling.** The reasons to stop asking that do not count, each with why: + - *"The feature is simple enough."* — Simplicity shortens the spec; it does not waive it. The five-sentence spec still names its criteria. + - *"I've asked enough questions."* — Question fatigue is not an exit condition. The exit is the Phase 5 review passing. + - *"The user seems eager to move on."* — Eagerness is a signal to compress the asking (decide more parameters, batch harder), never to skip an unresolved fork. + - *"We can settle it during implementation."* — Every deferral is a `[CONFIRM-NN]` on record, or it is a guess that `tdd` will faithfully implement. Record every genuinely-unresolved unknown as `[CONFIRM-NN]` in `${CLAUDE_PROJECT_DIR}/.codearbiter/open-questions.md`, numbered sequentially. A finding that belongs to a different feature or a future scope gets an inline `[NEEDS-TRIAGE]` marker in the notes — never route it to a ticket. -Gate: every vague term made concrete; every forced trade-off resolved or recorded as `[CONFIRM-NN]`; no unresolved "later" outside a `[CONFIRM-NN]`. A blocking `[CONFIRM-NN]` that gates the spec's core stops the loop — surface it and STOP. +Gate: every vague term made concrete; every fork resolved by the user or recorded as `[CONFIRM-NN]`; every parameter decision recorded in the spec draft; no unresolved "later" outside a `[CONFIRM-NN]`. A blocking `[CONFIRM-NN]` that gates the spec's core stops the loop — surface it and STOP. -## Phase 3 — Write the spec · gate: BLOCK +## Phase 4 — Write the spec · gate: BLOCK Write the agreed spec to `${CLAUDE_PROJECT_DIR}/.codearbiter/specs/.md`. The slug is derived from the feature. The spec holds: - **Problem** — the Phase 1 framing in final form. +- **Approach** — the Phase 2 choice and the trade-off that picked it, in two or three sentences. - **Scope** — what is in, and the explicit out-of-scope boundary. +- **Decided parameters** — the parameter-level choices made in Phase 3, each in one line, so the approval reads them instead of discovering them in code review. - **Acceptance criteria** — a numbered list, each criterion concrete and testable: a specific input, the observable output, the boundary or failure behavior. Each criterion is verifiable by a single test. "It works well" is not a criterion. These become `tdd` Phase 1 obligations — one obligation per criterion, so an untestable criterion is a defect to fix here, not in `tdd`. - **Open questions** — every `[CONFIRM-NN]` raised, cross-referenced to `open-questions.md`. - **Governs** *(optional)* — a spec-header line `**Governs:** ` that enrolls the approved spec in file-scoped just-in-time context injection: on a Read of any file matching one of the listed globs, a pointer to this spec is surfaced to the agent (tier 3 of the file→knowledge map). Adding the line is sufficient to enroll; no other change required. Gate: the spec file exists on disk under `specs/`, with at least one acceptance criterion and every criterion individually testable. -## Phase 4 — Approval & handoff · gate: STOP +## Phase 5 — Review, approval & handoff · gate: STOP -The spec is approved before any code is written or any handoff to `tdd` occurs — no exceptions: +The spec earns its approval; it is not waved through. Two passes over the FILE as written, then the stop: -- **Under `/feature`** — present the spec and request explicit user approval. Iterate on the file in place until the user approves. A blocking `[CONFIRM-NN]` must be resolved by the user before approval — never auto-resolve it. -- **Under `/sprint`** — approval may be granted automatically by SMARTS scoring, logged to the `.codearbiter/` audit trail. A blocking `[CONFIRM-NN]` is never auto-approvable; it escalates to the user and STOPs the sprint flow. +1. **Mechanical self-review** — one pass, fix inline, no re-review: no placeholder text (`TBD`, `???`, an unfilled section); no criterion that contradicts the scope; nothing that crosses the `CONTEXT.md` NOT-building boundary; every criterion still testable by a single test after the edits; the vague-language lens applied to the spec's own prose. +2. **Adversarial pass** — build the strongest case AGAINST the design before the user reads it: the failure mode most likely to be real, the criterion most likely to be wrong, the assumption that would invalidate the approach if false. Present what survives WITH the spec at approval — the user rules on a challenged design, not a defended one. Finding nothing is a reportable result, stated in one line, not a silent skip. +3. **Approval:** + - **Under `/feature`** — present the spec and the adversarial findings, and request explicit user approval. Iterate on the file in place until the user approves. A blocking `[CONFIRM-NN]` must be resolved by the user before approval — never auto-resolve it. + - **Under `/sprint`** — approval may be granted automatically by SMARTS scoring, logged to the `.codearbiter/` audit trail. A blocking `[CONFIRM-NN]` is never auto-approvable; it escalates to the user and STOPs the sprint flow. On approval, hand off to the `tdd` skill, which enters Phase 1 against the approved spec — one obligation per acceptance criterion. -Gate: the spec is approved (by the user under `/feature`, or by logged SMARTS auto-approval under `/sprint`) with no unresolved blocking `[CONFIRM-NN]`. Only then does control pass to `tdd`. +Gate: both review passes run against the file on disk, adversarial findings presented, and the spec approved (by the user under `/feature`, or by logged SMARTS auto-approval under `/sprint`) with no unresolved blocking `[CONFIRM-NN]`. Only then does control pass to `tdd`. ## Hard rules - MUST NOT write implementation code or route to `tdd` before the spec is on disk under `specs/` AND approved. +- MUST NOT refine a bundle — an idea holding more than one independently shippable concern splits in Phase 1, before any question budget is spent. +- MUST NOT manufacture alternatives in Phase 2 — when one sane approach exists, say so and why. - MUST NOT write an acceptance criterion that cannot be verified by a single test. +- MUST decide parameter-level choices and record them in the spec; MUST ask genuine forks in full, with a recommendation, the first time — never name an open decision without asking it. +- MUST stop a non-converging refinement loop and force one adjudication — a contradiction or a resurfacing fork is a breaker, not a prompt to circle. +- MUST run the Phase 5 mechanical self-review and adversarial pass against the file as written, and present the adversarial findings at approval. - MUST NOT resolve a `[CONFIRM-NN]` by guessing — surface it and record it in `open-questions.md`. - MUST NOT auto-approve a spec carrying a blocking `[CONFIRM-NN]`, even under `/sprint` — it escalates to the user. - MUST NOT contradict the NOT-building list or redefine domain vocabulary in `CONTEXT.md` — a contradiction is a conflict to surface, not reconcile. -- MUST NOT run decompose's six-layer whole-project interview — this is one feature, four phases. +- MUST NOT run decompose's six-layer whole-project interview — this is one feature, five phases. - MUST log a `/sprint` auto-approval to the `.codearbiter/` audit trail. - MUST, at exit, run the follow-up harvest (`${CLAUDE_PLUGIN_ROOT}/includes/harvest.md`) over any `[NEEDS-TRIAGE]` notes raised this run — batch-confirm promoting them to `open-tasks.md` (work) or `open-questions.md` (decisions) so out-of-scope ideas don't vanish. diff --git a/site/src/curated/skills/brainstorming.md b/site/src/curated/skills/brainstorming.md index c6b8c32c..9a58e22a 100644 --- a/site/src/curated/skills/brainstorming.md +++ b/site/src/curated/skills/brainstorming.md @@ -4,31 +4,40 @@ related: [commands/feature, commands/sprint, writing-plans] gates: - gate: frame the problem when: at the start of a new feature idea - effect: the one-line idea must resolve to a stated problem, caller, and out-of-scope boundary before questioning begins + effect: the one-line idea must resolve to a stated problem, caller, and out-of-scope boundary — and to exactly one feature, with bundles split — before any refinement begins - gate: spec approval - when: after the spec is drafted - effect: hard stop until you (or, under an autonomous sprint, a logged auto-approval) sign off; no code and no handoff to test-first work happens before that + when: after the spec is drafted and self-reviewed + effect: hard stop until you (or, under an autonomous sprint, a logged auto-approval) sign off on a spec presented with its own adversarial findings; no code and no handoff to test-first work happens before that --- ## What it does This is where a feature starts before any code exists. `/feature` opens here, and `/sprint`'s planning stage runs the same interview. Given a one-line idea, it drives a Socratic -back-and-forth — one question at a time — until the idea is concrete enough to build from: a -named problem, a named caller, an explicit boundary of what the feature does not do, and a set -of acceptance criteria specific enough that each one maps to a single test. Anything genuinely +back-and-forth until the idea is concrete enough to build from: a named problem, a named +caller, an explicit boundary of what the feature does not do, a chosen approach with its +trade-off stated, and a set of acceptance criteria specific enough that each one maps to a +single test. Routine parameter choices are decided for you and recorded in the spec where you +review them; genuine forks are asked in full, with a recommendation, and batched where the +answers are independent — you decide the forks, not the ceremony. Anything genuinely unresolved becomes a numbered open question on record rather than a guess. ## Phases -1. The problem, its caller, and the out-of-scope boundary are pinned down and checked against - the project's existing context for a contradiction. -2. A question-at-a-time refinement loop closes every vague term, surfaces hidden complexity, and - forces any real trade-off to a resolution or a recorded open question. -3. The agreed spec — problem, scope, testable acceptance criteria, open questions — is written to - disk. -4. The spec is approved (by you directly, or by a logged automatic approval under an autonomous - sprint) before anything moves on to test-first implementation. +1. The problem, its caller, and the out-of-scope boundary are pinned down, checked against the + project's existing context for a contradiction, and an idea bundling several independent + concerns is split before any refinement effort is spent. +2. The genuine candidate approaches are laid out with their trade-offs and one recommendation; + you choose (or a sprint's scored auto-decision does, on the record). +3. A refinement loop closes every vague term, surfaces hidden complexity, and forces any real + trade-off to a resolution or a recorded open question — with a breaker that stops a + non-converging loop and forces one adjudication instead of circling. +4. The agreed spec — problem, approach, scope, decided parameters, testable acceptance + criteria, open questions — is written to disk. +5. The spec is self-reviewed mechanically, challenged adversarially (the strongest case + against the design travels with it), and then approved — by you directly, or by a logged + automatic approval under an autonomous sprint — before anything moves on to test-first + implementation. ## Exits From ec65f889489fd638b7b7c27ef135932e9294208b Mon Sep 17 00:00:00 2001 From: SUaDtL Date: Tue, 4 Aug 2026 07:38:50 -0400 Subject: [PATCH 2/2] fix(release-surfaces): advance changelog and README with the 2.11.5 bump The version-advance surfaces the CI gates pin: CHANGELOG top section equals the ca manifest, README version badge matches, and the README Codex line names the shipped ca-codex version. CHANGELOG: (internal release-surface sync; no user-facing change beyond the 2.11.5 entry itself) Claude-Session: https://claude.ai/code/session_01QjJeSbcwPHwMmd6CEZeagB --- CHANGELOG.md | 10 ++++++++++ README.md | 4 ++-- 2 files changed, 12 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 7933577b..fa803a78 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,6 +12,16 @@ predate the plugin rewrite and are grouped by date. ## [Unreleased] +## [2.11.5] — 2026-08-04 + +### Changed + +- Modernized the `brainstorming` skill for capable models: bundled ideas split + before refinement, candidate approaches shaped with one recommendation, + parameter-level choices decided and recorded while genuine forks are asked in + full, a breaker stops non-converging refinement loops, and the spec is + mechanically self-reviewed and adversarially challenged before approval. + ## [2.11.1] — 2026-08-03 ### Fixed diff --git a/README.md b/README.md index 8ea04715..69d99600 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ project context. You decide. codeArbiter enforces. Claude Code plugin Codex plugin Pi Feature Forge preview -version 2.11.1 +version 2.11.5 commands skills agents @@ -119,7 +119,7 @@ Approve the normal plugin trust prompt, open the target repository, and continue ### Codex CLI -The public GitHub-slug flow is **available now**. The repository currently ships `ca-codex 0.4.0`; +The public GitHub-slug flow is **available now**. The repository currently ships `ca-codex 0.4.4`; the dated end-to-end public-install record discovered `ca-codex 0.2.4` from release `v2.8.13`. Current packaging and shared-core parity are continuously verified, while that dated live-install record stays labeled rather than being silently promoted to evidence for a newer adapter: