cclaw-cli 0.10.1 → 0.12.0

package/dist/content/stage-common-guidance.js

@@ -0,0 +1,71 @@
+import { RUNTIME_ROOT } from "../constants.js";
+export const STAGE_COMMON_GUIDANCE_REL_PATH = `${RUNTIME_ROOT}/references/stages/common-guidance.md`;
+export function stageCommonGuidanceMarkdown() {
+    return `# Common Stage Guidance
+
+Shared guidance loaded by every stage skill. Keep this file concise and stable so
+per-stage skills can stay focused on stage-specific work.
+
+## Shared completion protocol
+
+- Stage-specific skills expose **Completion Parameters** only.
+- Generic execution steps live in \`.cclaw/references/protocols/completion.md\`.
+- Do not restate the protocol in each stage file.
+
+## Shared decision protocol
+
+- Decision wording, ask-tool format, retry budget, and escalation rules live in
+  \`.cclaw/references/protocols/decision.md\`.
+- Stage files should reference that path, not duplicate the full text.
+
+## Shared handoff menu
+
+Use this same closeout menu for every stage:
+
+- **A) Advance** — run \`/cc-next\` and continue.
+- **B) Revise this stage** — stay on current stage and apply feedback.
+- **C) Pause / park** — stop now and resume later.
+- **D) Rewind** — move to a prior stage explicitly chosen by the user.
+- **E) Abandon** — cancel this flow; artifacts remain on disk.
+
+Recommendation defaults:
+
+- Completion status \`DONE\` -> recommend **A**.
+- Completion status \`DONE_WITH_CONCERNS\` -> recommend **B**.
+- Completion status \`BLOCKED\` -> recommend **B** or **C**.
+
+## Completion status vocabulary
+
+- \`DONE\` — all required gates and checks satisfied.
+- \`DONE_WITH_CONCERNS\` — required gates pass, but recommended items remain.
+- \`BLOCKED\` — one or more required/triggered conditions fail.
+
+## Decision record template
+
+Use when a stage makes a non-trivial architecture/scope/testing decision.
+
+\`\`\`
+Decision: <one-line title>
+Context: <what forced this decision>
+Options considered:
+- A: ...
+- B: ...
+Chosen option: <A/B/...>
+Why: <short rationale>
+Risk: <main downside>
+Rollback / fallback: <if decision proves wrong>
+\`\`\`
+
+## Self-improvement reminder
+
+If a reusable lesson appears during the stage, append one strict-schema JSONL
+entry via \`/cc-learn add\`. Do not keep operational lessons only in chat.
+
+## Progressive disclosure baseline
+
+- Start with the current stage skill.
+- Load deeper references only when required by a blocker or gate.
+- Prefer \`.cclaw/references/stages/<stage>-examples.md\` and protocol files over
+  copying large instruction blocks into stage skills.
+`;
+}

package/dist/content/stage-schema.d.ts

@@ -2,6 +2,9 @@ import type { FlowStage, TransitionRule } from "../types.js";
 export interface StageGate {
     id: string;
     description: string;
+    tier?: "required" | "recommended" | "conditional";
+    /** Used when tier=conditional. Predicate syntax mirrors conditional delegation rules. */
+    condition?: string;
 }
 export interface StageRationalization {
     claim: string;
@@ -24,10 +27,13 @@ export interface CrossStageTrace {
 export interface ArtifactValidation {
     section: string;
     required: boolean;
+    tier?: "required" | "recommended" | "conditional";
+    /** Optional predicate for conditional validations. */
+    condition?: string;
     validationRule: string;
 }
 export interface StageAutoSubagentDispatch {
-    agent: "planner" | "spec-reviewer" | "code-reviewer" | "security-reviewer" | "test-author" | "doc-updater" | "repo-research-analyst" | "learnings-researcher" | "framework-docs-researcher" | "best-practices-researcher" | "git-history-analyzer";
+    agent: "planner" | "reviewer" | "security-reviewer" | "test-author" | "doc-updater";
     /**
      * - `mandatory` — must be dispatched (or explicitly waived) before stage transition.
      * - `proactive` — should be dispatched automatically when context matches `when`.
@@ -75,6 +81,8 @@ export interface StageSchema {
     requiredEvidence: string[];
     inputs: string[];
     requiredContext: string[];
+    /** In-thread research procedures for this stage (`.cclaw/skills/research/*.md`). */
+    researchPlaybooks?: string[];
     outputs: string[];
     blockers: string[];
     exitCriteria: string[];
@@ -106,6 +114,8 @@ export declare function conditionalDispatchesForStage(stage: FlowStage): StageAu
 export declare function stageSchema(stage: FlowStage): StageSchema;
 export declare function orderedStageSchemas(): StageSchema[];
 export declare function stageGateIds(stage: FlowStage): string[];
+export declare function stageRecommendedGateIds(stage: FlowStage): string[];
+export declare function stageConditionalGateIds(stage: FlowStage): string[];
 export declare function nextCclawCommand(stage: FlowStage): string;
 export declare function buildTransitionRules(): TransitionRule[];
 export declare function stagePolicyNeedles(stage: FlowStage): string[];

package/dist/content/stage-schema.js

@@ -1,4 +1,122 @@
 import { COMMAND_FILE_ORDER } from "../constants.js";
+/**
+ * Gate tiers:
+ * - required: blocking for stage completion.
+ * - recommended: quality signal; unmet -> DONE_WITH_CONCERNS, not BLOCKED.
+ * - conditional: becomes blocking only when triggered.
+ */
+const REQUIRED_GATE_IDS = {
+    brainstorm: [
+        "brainstorm_approaches_compared",
+        "brainstorm_direction_approved",
+        "brainstorm_artifact_reviewed"
+    ],
+    scope: [
+        "scope_mode_selected",
+        "scope_contract_written",
+        "scope_user_approved"
+    ],
+    design: [
+        "design_architecture_locked",
+        "design_data_flow_mapped",
+        "design_failure_modes_mapped",
+        "design_test_and_perf_defined"
+    ],
+    spec: [
+        "spec_acceptance_measurable",
+        "spec_testability_confirmed",
+        "spec_user_approved"
+    ],
+    plan: [
+        "plan_tasks_sliced_2_5_min",
+        "plan_dependency_waves_defined",
+        "plan_acceptance_mapped",
+        "plan_wait_for_confirm"
+    ],
+    tdd: [
+        "tdd_red_test_written",
+        "tdd_green_full_suite",
+        "tdd_refactor_completed",
+        "tdd_traceable_to_plan"
+    ],
+    review: [
+        "review_layer1_spec_compliance",
+        "review_layer2_security",
+        "review_criticals_resolved",
+        "review_army_json_valid"
+    ],
+    ship: [
+        "ship_review_verdict_valid",
+        "ship_preflight_passed",
+        "ship_rollback_plan_ready",
+        "ship_finalization_executed"
+    ]
+};
+const CONDITIONAL_GATE_RULES = {
+    review: {
+        review_security_audit_swept: "diff_lines_gt:100||files_touched_gt:10||trust_boundary_changed"
+    },
+    ship: {
+        ship_post_merge_tests: "files_touched_gt:10||release_blast_radius_high"
+    }
+};
+const REQUIRED_ARTIFACT_SECTIONS = {
+    brainstorm: ["Context", "Problem", "Approaches", "Selected Direction"],
+    scope: ["Scope Mode", "In Scope / Out of Scope", "Completion Dashboard", "Scope Summary"],
+    design: ["Architecture Boundaries", "Architecture Diagram", "Failure Mode Table", "Completion Dashboard"],
+    spec: ["Acceptance Criteria", "Edge Cases", "Testability Map", "Approval"],
+    plan: ["Task List", "Dependency Waves", "Acceptance Mapping", "WAIT_FOR_CONFIRM"],
+    tdd: ["RED Evidence", "GREEN Evidence", "REFACTOR Notes", "Traceability"],
+    review: ["Layer 1 Verdict", "Review Army Contract", "Severity Summary", "Final Verdict"],
+    ship: ["Preflight Results", "Release Notes", "Rollback Plan", "Finalization"]
+};
+const CONDITIONAL_ARTIFACT_RULES = {
+    review: {
+        "Review Readiness Dashboard": "diff_lines_gt:100||files_touched_gt:10||trust_boundary_changed"
+    },
+    ship: {
+        Monitoring: "release_blast_radius_high"
+    }
+};
+function tieredStageGates(stage, gates) {
+    const requiredSet = new Set(REQUIRED_GATE_IDS[stage]);
+    const conditional = CONDITIONAL_GATE_RULES[stage] ?? {};
+    return gates.map((gate) => {
+        const condition = conditional[gate.id];
+        if (condition) {
+            return {
+                ...gate,
+                tier: "conditional",
+                condition
+            };
+        }
+        return {
+            ...gate,
+            tier: requiredSet.has(gate.id) ? "required" : "recommended"
+        };
+    });
+}
+function tieredArtifactValidation(stage, rows) {
+    const requiredSections = new Set(REQUIRED_ARTIFACT_SECTIONS[stage]);
+    const conditional = CONDITIONAL_ARTIFACT_RULES[stage] ?? {};
+    return rows.map((row) => {
+        const condition = conditional[row.section];
+        if (condition) {
+            return {
+                ...row,
+                tier: "conditional",
+                condition,
+                required: false
+            };
+        }
+        const required = requiredSections.has(row.section);
+        return {
+            ...row,
+            tier: required ? "required" : "recommended",
+            required
+        };
+    });
+}
 const BRAINSTORM = {
     stage: "brainstorm",
     skillFolder: "brainstorming",
@@ -72,6 +190,10 @@ const BRAINSTORM = {
         "current behavior of affected area",
         "business and delivery constraints"
     ],
+    researchPlaybooks: [
+        "research/repo-scan.md",
+        "research/learnings-lookup.md"
+    ],
     outputs: [
         "approved design direction",
         "alternatives with trade-offs",
@@ -221,6 +343,9 @@ const SCOPE = {
         "existing capabilities and reusable components",
         "delivery deadlines and risk tolerance"
     ],
+    researchPlaybooks: [
+        "research/git-history.md"
+    ],
     outputs: ["scope mode decision", "scope contract", "discretion areas list", "deferred scope list", "scope summary", "scope completion dashboard"],
     blockers: [
         "scope mode not selected",
@@ -435,6 +560,10 @@ const DESIGN = {
         "operational constraints",
         "security and reliability expectations"
     ],
+    researchPlaybooks: [
+        "research/framework-docs-lookup.md",
+        "research/best-practices-lookup.md"
+    ],
     outputs: [
         "architecture lock",
         "risk and failure map",
@@ -1148,7 +1277,7 @@ const REVIEW = {
     checklist: [
         "Diff Scope — Run `git diff` against base branch. If no diff, exit early with APPROVED (no changes to review). Scope the review to changed files unless blast-radius analysis requires wider inspection.",
         "Change-Size Check — ~100 lines = normal. ~300 lines = consider splitting. ~1000+ lines = strongly recommend stacked PRs. Flag large diffs to the user.",
-        "Adversarial Trigger Check — compute changed-line count (`git diff --shortstat <base>..HEAD`), files-touched count, and whether trust boundaries changed (auth/secrets/external inputs/permissions). If `lines > 100` OR `files > 10` OR `trust boundary changed`, **dispatch a SECOND code-reviewer agent with the `adversarial-review` skill loaded** and reconcile its findings into the review army (treat the conditional dispatch as mandatory whenever the trigger holds; record the trigger that fired in the dashboard).",
+        "Adversarial Trigger Check — compute changed-line count (`git diff --shortstat <base>..HEAD`), files-touched count, and whether trust boundaries changed (auth/secrets/external inputs/permissions). If `lines > 100` OR `files > 10` OR `trust boundary changed`, **dispatch a SECOND reviewer agent with the `adversarial-review` skill loaded** and reconcile its findings into the review army (treat the conditional dispatch as mandatory whenever the trigger holds; record the trigger that fired in the dashboard).",
         "Load upstream evidence — read TDD artifact (RED + GREEN + REFACTOR), spec, and plan. Verify evidence chain is unbroken.",
         "Layer 1: Spec Compliance — check every acceptance criterion against implementation. Verdict: pass/fail per criterion.",
         "Layer 2a: Correctness — logic errors, race conditions, boundary violations, null handling.",
@@ -1524,20 +1653,6 @@ const STAGE_AUTO_SUBAGENT_DISPATCH = {
             when: "When request is ambiguous, multi-surface, or spans multiple modules.",
             purpose: "Map scope and alternatives before direction lock.",
             requiresUserGate: false
-        },
-        {
-            agent: "repo-research-analyst",
-            mode: "proactive",
-            when: "When the user's idea touches an unfamiliar module, stack, or integration surface.",
-            purpose: "Parallel fan-out: summarise existing code paths, tech stack, and similar features already present — feeds the alternatives list.",
-            requiresUserGate: false
-        },
-        {
-            agent: "learnings-researcher",
-            mode: "proactive",
-            when: "On every non-trivial brainstorm where `.cclaw/knowledge.jsonl` has entries.",
-            purpose: "Surface prior learnings and anti-patterns that apply to the current task before direction lock.",
-            requiresUserGate: false
         }
     ],
     scope: [
@@ -1547,13 +1662,6 @@ const STAGE_AUTO_SUBAGENT_DISPATCH = {
             when: "Always during scope shaping.",
             purpose: "Challenge premise, map alternatives, and produce explicit in/out contract.",
             requiresUserGate: false
-        },
-        {
-            agent: "git-history-analyzer",
-            mode: "proactive",
-            when: "When scope touches modules with churn, recent regressions, or unclear ownership.",
-            purpose: "Read recent commits, PRs, and issue references for the affected paths before scope lock.",
-            requiresUserGate: false
         }
     ],
     design: [
@@ -1570,20 +1678,6 @@ const STAGE_AUTO_SUBAGENT_DISPATCH = {
             when: "When trust boundaries, auth, secrets, or external inputs are involved.",
             purpose: "Catch design-level security risks before implementation.",
             requiresUserGate: false
-        },
-        {
-            agent: "framework-docs-researcher",
-            mode: "proactive",
-            when: "When a specific framework/library version is detected and a non-trivial API is in play.",
-            purpose: "Retrieve version-specific docs + migration notes so the design does not rely on stale training priors.",
-            requiresUserGate: false
-        },
-        {
-            agent: "best-practices-researcher",
-            mode: "conditional",
-            when: "When the user flags a quality axis (performance, accessibility, reliability) as primary.",
-            purpose: "Pull domain best-practices and contrast them with the current design choice.",
-            requiresUserGate: false
         }
     ],
     spec: [
@@ -1595,7 +1689,7 @@ const STAGE_AUTO_SUBAGENT_DISPATCH = {
             requiresUserGate: false
         },
         {
-            agent: "spec-reviewer",
+            agent: "reviewer",
             mode: "proactive",
             when: "When acceptance criteria and edge cases are drafted and need independent validation before plan stage.",
             purpose: "Independent review of spec against measurability, testability, and completeness before locking the contract for plan.",
@@ -1629,17 +1723,10 @@ const STAGE_AUTO_SUBAGENT_DISPATCH = {
     ],
     review: [
         {
-            agent: "spec-reviewer",
-            mode: "mandatory",
-            when: "Always in review stage.",
-            purpose: "Verify implementation against acceptance criteria with file evidence.",
-            requiresUserGate: false
-        },
-        {
-            agent: "code-reviewer",
+            agent: "reviewer",
             mode: "mandatory",
             when: "Always in review stage.",
-            purpose: "Assess correctness, maintainability, architecture, and ship risk.",
+            purpose: "Run spec compliance and code-quality passes with file evidence.",
             requiresUserGate: false
         },
         {
@@ -1651,10 +1738,10 @@ const STAGE_AUTO_SUBAGENT_DISPATCH = {
             skill: "security-audit"
         },
         {
-            agent: "code-reviewer",
+            agent: "reviewer",
             mode: "conditional",
             condition: "diff_lines_gt:100||files_touched_gt:10||trust_boundary_changed",
-            when: "When the diff exceeds 100 changed lines, touches more than 10 files, or modifies trust boundaries — dispatch a SECOND, independent code-reviewer with the adversarial-review skill loaded so the review army has at least two voices on a high-blast-radius change.",
+            when: "When the diff exceeds 100 changed lines, touches more than 10 files, or modifies trust boundaries — dispatch a SECOND, independent reviewer with the adversarial-review skill loaded so the review army has at least two voices on a high-blast-radius change.",
             purpose: "Adversarial second-opinion review on large or trust-sensitive diffs. The second reviewer treats the implementation as hostile and tries to break it (hostile-user, future-maintainer, competitor lenses) instead of sympathetically explaining it.",
             requiresUserGate: false,
             skill: "adversarial-review"
@@ -1669,10 +1756,10 @@ const STAGE_AUTO_SUBAGENT_DISPATCH = {
             requiresUserGate: false
         },
         {
-            agent: "code-reviewer",
+            agent: "security-reviewer",
             mode: "proactive",
-            when: "When release involves broad blast radius or unresolved concerns.",
-            purpose: "Provide final integration-scale quality pass.",
+            when: "When release involves broad blast radius, trust-boundary movement, or unresolved security concerns.",
+            purpose: "Provide final exploitability check before release finalization.",
             requiresUserGate: false
         }
     ]
@@ -1689,8 +1776,12 @@ export function conditionalDispatchesForStage(stage) {
 }
 export function stageSchema(stage) {
     const base = STAGE_SCHEMA_MAP[stage];
+    const tieredGates = tieredStageGates(stage, base.requiredGates);
+    const tieredValidation = tieredArtifactValidation(stage, base.artifactValidation);
     return {
         ...base,
+        requiredGates: tieredGates,
+        artifactValidation: tieredValidation,
         mandatoryDelegations: mandatoryDelegationsForStage(stage)
     };
 }
@@ -1698,7 +1789,19 @@ export function orderedStageSchemas() {
     return COMMAND_FILE_ORDER.map((stage) => stageSchema(stage));
 }
 export function stageGateIds(stage) {
-    return stageSchema(stage).requiredGates.map((gate) => gate.id);
+    return stageSchema(stage).requiredGates
+        .filter((gate) => gate.tier === "required")
+        .map((gate) => gate.id);
+}
+export function stageRecommendedGateIds(stage) {
+    return stageSchema(stage).requiredGates
+        .filter((gate) => gate.tier === "recommended")
+        .map((gate) => gate.id);
+}
+export function stageConditionalGateIds(stage) {
+    return stageSchema(stage).requiredGates
+        .filter((gate) => gate.tier === "conditional")
+        .map((gate) => gate.id);
 }
 export function nextCclawCommand(stage) {
     const next = stageSchema(stage).next;

package/dist/content/start-command.js

@@ -25,7 +25,7 @@ This is the **recommended way to start** working with cclaw. Use \`/cc-next\` fo
 ## HARD-GATE
 
 - **Do not** skip reading \`${flowPath}\` — always check current state before acting.
-- **Do not** start implementation stages directly from \`/cc <prompt>\` — always begin at the first stage of the resolved track (brainstorm for standard, spec for quick).
+- **Do not** start implementation stages directly from \`/cc <prompt>\` — always begin at the first stage of the resolved track (brainstorm for medium/standard, spec for quick).
 - **Do not** start a stage pipeline for a task that is not a software change (pure question, non-software task, conversation).
 
 ## Algorithm
@@ -40,6 +40,7 @@ This is the **recommended way to start** working with cclaw. Use \`/cc-next\` fo
    | **pure-question** | "how does X work?", "explain Y", "what are the trade-offs of Z?" | Answer directly, do NOT open a stage. |
    | **trivial** | typo, one-liner, rename, config tweak, copy change, version bump with zero behavior change | Fast-path: skip \`brainstorm\` and \`scope\`, seed \`00-idea.md\`, move straight to \`design\` or \`spec\` depending on whether an interface change is involved. |
    | **software — bug fix with repro** | regression / hotfix / named symptom + repro steps | Fast-path: set track to \`quick\`, seed \`04-spec.md\` with the reproduction, enter \`tdd\` with a RED reproduction test first. |
+   | **software — medium** | additive feature following existing architecture | medium track (\`brainstorm → spec → plan → tdd → review → ship\`). |
    | **software — standard** | feature, refactor, migration, integration, architecture change | Full 8-stage flow starting at \`brainstorm\`. |
 
    Record the chosen class in \`.cclaw/artifacts/00-idea.md\` on the \`Class:\` line. Do NOT silently treat a non-software task as software.
@@ -63,20 +64,23 @@ This is the **recommended way to start** working with cclaw. Use \`/cc-next\` fo
 4. Read \`${flowPath}\`.
 5. If flow already has completed stages beyond brainstorm, warn the user that starting a new brainstorm will reset progress. Ask for confirmation before proceeding.
 6. **Track heuristic** — classify the idea text and **recommend** a track (the user can override before any state mutation):
+   - First, load \`${RUNTIME_ROOT}/config.yaml\`. If \`trackHeuristics\` is defined, apply those per-track rules (\`priority\`, \`fallback\`, \`tracks.<id>.{triggers,patterns,veto}\`) before built-in defaults.
    - **quick** (\`spec → tdd → review → ship\`) — single-purpose work where the spec is essentially already known.
      Triggers (case-insensitive substring or close variant): \`bug\`, \`bugfix\`, \`fix\`, \`hotfix\`, \`patch\`, \`typo\`, \`regression\`, \`copy change\`, \`rename\`, \`bump\`, \`upgrade dep\`, \`config tweak\`, \`docs only\`, \`comment\`, \`lint\`, \`format\`, \`small\`, \`tiny\`, \`one-liner\`, \`revert\`.
-   - **standard** (full 8 stages — default) — anything that introduces a new capability, touches multiple modules, or has unclear scope.
-     Triggers: \`new feature\`, \`add\`, \`build\`, \`design\`, \`refactor\`, \`migration\`, \`platform\`, \`architecture\`, \`endpoint\`, \`schema\`, \`api\`, \`integrate\`, \`workflow\`, \`onboarding\`, or any prompt that does not match quick triggers.
-   - When triggers conflict (e.g. "small refactor that touches 5 modules") prefer **standard** — quick is opt-in and only safe when scope is genuinely tiny.
+   - **medium** (\`brainstorm → spec → plan → tdd → review → ship\`) — additive work that fits existing architecture and still needs product framing.
+     Triggers: \`add endpoint\`, \`add field\`, \`extend existing\`, \`wire integration\`, \`small migration\`, \`new screen following existing patterns\`.
+   - **standard** (full 8 stages — default fallback) — anything that introduces a new capability with architecture uncertainty, touches many modules, or has unclear scope.
+     Triggers: \`new feature\`, \`refactor\`, \`migration\`, \`platform\`, \`architecture\`, \`schema\`, \`integrate\`, \`workflow\`, \`onboarding\`, or any prompt that does not match quick/medium confidently.
+   - When triggers conflict, prefer **standard** over **medium**, and **medium** over **quick**.
 7. Present the recommendation as a single decision with explicit options:
-   > \`Recommended track: <quick|standard>\` because \`<one-line reason citing matched triggers>\`.
-   > Override? (A) keep \`<recommended>\`  (B) switch to \`<other>\`  (C) cancel.
+   > \`Recommended track: <quick|medium|standard>\` because \`<one-line reason citing matched triggers>\`.
+   > Override? (A) keep \`<recommended>\`  (B) switch track  (C) cancel.
    If \`AskQuestion\`/\`AskUserQuestion\` is available, send exactly ONE question; on schema error, fall back to plain text.
-8. Persist the chosen track to \`${flowPath}\` (\`track\` field). Compute \`skippedStages\` from the track and write that too. Use the **first stage of the chosen track** as \`currentStage\` (quick → \`spec\`, standard → \`brainstorm\`, trivial fast-path → \`design\` or \`spec\` per Phase 0).
+8. Persist the chosen track to \`${flowPath}\` (\`track\` field). Compute \`skippedStages\` from the track and write that too. Use the **first stage of the chosen track** as \`currentStage\` (quick → \`spec\`, medium/standard → \`brainstorm\`, trivial fast-path → \`design\` or \`spec\` per Phase 0).
 9. Write the prompt to \`.cclaw/artifacts/00-idea.md\` with the following header lines: \`Class:\` (from Phase 0), \`Track:\` (chosen track + matched heuristic), \`Stack:\` (from Phase 2 detection, or \`unknown\`), and a \`Discovered context\` section if Phase 1 found origin docs.
 10. Load the **first-stage skill for the chosen track** and its command file:
     - quick → \`.cclaw/skills/specification-authoring/SKILL.md\` + \`.cclaw/commands/spec.md\`
-    - standard → \`.cclaw/skills/brainstorming/SKILL.md\` + \`.cclaw/commands/brainstorm.md\`
+    - medium/standard → \`.cclaw/skills/brainstorming/SKILL.md\` + \`.cclaw/commands/brainstorm.md\`
     - trivial fast-path → design or spec skill per Phase 0 decision.
 11. Execute that stage with the prompt + Phase 1/Phase 2 context as initial input.
 
@@ -136,19 +140,21 @@ Do **not** silently discard an existing flow when the user provides a prompt. If
    - Ask: "Continue with reset? (A) Yes, start fresh (B) No, resume current flow"
    - If (B) → switch to Path B behavior.
 6. **Classify the idea** using the heuristic below and present a single track recommendation. Wait for explicit confirmation or override before mutating any state.
+   - If \`${RUNTIME_ROOT}/config.yaml\` defines \`trackHeuristics\`, apply that override first (priority/fallback/rules), then use built-in defaults only as fallback.
 
    **Track heuristic** (lowercase substring match against the user prompt):
 
    | Track | Triggers | Use when |
    |---|---|---|
    | \`quick\` | \`bug\`, \`bugfix\`, \`fix\`, \`hotfix\`, \`patch\`, \`typo\`, \`regression\`, \`rename\`, \`bump\`, \`upgrade dep\`, \`docs only\`, \`comment\`, \`lint\`, \`format\`, \`small\`, \`tiny\`, \`one-liner\`, \`revert\`, \`copy change\` | Single-purpose, spec is essentially known, low blast radius |
-   | \`standard\` | \`new feature\`, \`add\`, \`build\`, \`design\`, \`refactor\`, \`migration\`, \`platform\`, \`architecture\`, \`endpoint\`, \`schema\`, \`api\`, \`integrate\`, \`workflow\`, \`onboarding\` (or no quick trigger matched) | Anything new, multi-module, or unclear scope |
+   | \`medium\` | \`add endpoint\`, \`add field\`, \`extend existing\`, \`wire integration\`, \`small migration\`, \`new screen following existing pattern\` | Additive work with existing architecture |
+   | \`standard\` | \`new feature\`, \`build\`, \`design\`, \`refactor\`, \`migration\`, \`platform\`, \`architecture\`, \`schema\`, \`api\`, \`integrate\`, \`workflow\`, \`onboarding\` (or no confident quick/medium match) | New or uncertain multi-module work |
 
-   - On conflict, prefer \`standard\` (quick is opt-in for genuinely tiny work).
-   - Always state the recommendation as a one-line reason citing the matched trigger.
-7. Persist the chosen track in \`${flowPath}\` (\`track\` + \`skippedStages\`). Set \`currentStage\` to the first stage of the chosen track (\`quick\` → \`spec\`, \`standard\` → \`brainstorm\`, trivial fast-path → \`design\` or \`spec\`). Reset gate catalog.
+   - On conflict, prefer \`standard\` over \`medium\`, and \`medium\` over \`quick\`.
+   - Always state the recommendation as a one-line reason citing matched triggers.
+7. Persist the chosen track in \`${flowPath}\` (\`track\` + \`skippedStages\`). Set \`currentStage\` to the first stage of the chosen track (\`quick\` → \`spec\`, \`medium\`/ \`standard\` → \`brainstorm\`, trivial fast-path → \`design\` or \`spec\`). Reset gate catalog.
 8. Write \`${RUNTIME_ROOT}/artifacts/00-idea.md\` with the user's prompt plus header lines: \`Class:\`, \`Track:\`, \`Stack:\`, and a \`Discovered context\` section from Phase 1.
-9. Load and execute the **first stage skill of the chosen track** (\`brainstorming\` for standard, \`specification-authoring\` for quick) plus its matching command file.
+9. Load and execute the **first stage skill of the chosen track** (\`brainstorming\` for medium/standard, \`specification-authoring\` for quick) plus its matching command file.
 
 ### Reclassification on discovery
 

package/dist/content/subagents.d.ts

@@ -7,7 +7,7 @@ export declare function subagentDrivenDevSkill(): string;
 export declare function parallelAgentsSkill(): string;
 /**
  * Returns markdown fragments augmenting each specialist persona with Task tool
- * delegation guidance. Combine with the existing `body` field from `agents.ts`.
+ * delegation guidance. Combine with the existing `body` field from `core-agents.ts`.
  */
 export declare function enhancedAgentBody(agentName: string): string;
 export declare function subagentsAgentsMdBlock(): string;