CAST v2.0.0

Breaking restructure of how agents hand off work and where artifacts live. Artifacts are now grouped by milestone instead of by type, every task and every bug is its own isolated file, and agent-to-agent handoffs follow a minimal-context protocol: each stage reads only its task file's Context Manifest and appends one capped Handoff Log entry. Existing installs need the migration below.

Changed

• artifacts/ is grouped by milestone. The v1 by-type directories (milestones/, architecture/, ui-specs/, reviews/) are gone. Each milestone owns one directory: artifacts/milestone-{N}-{slug}/ containing README.md (the milestone's highest-order document: definition, Status, Task Index, CEO Approval Conditions), architecture.md, ui.md, supplemental arch-{slug}.md / ui-{slug}.md docs, reviews/{security,performance,ceo,ux,validation,completion,retrospective}.md, tasks/ and bugs/. Cross-milestone state (BUGS.md index, STANDUP.md, AGENT_STATE.md) stays at the artifacts root; /agent-task work lands under artifacts/one-off/. Milestone directories are created by /agent-plan Stage 1 — /cast-init no longer pre-creates by-type subdirectories.
• One file per task. The single -tasks.md breakdown is replaced by tasks/task-{T}-{slug}.md, one instance of the new templates/TASK.md per task — self-contained with description, dependencies, acceptance criteria, a Context Manifest (the complete read set for the task, seeded by Product and extended with section anchors by Architect and UI), and an append-only Handoff Log. Task status lives ONLY in the task file's Header; the milestone README's Task Index deliberately has no status column, ending v1's dual-write bookkeeping. templates/MILESTONE_TASKS.md is renamed/rewritten as templates/TASK.md.
• One file per bug. Bugs are standalone files (templates/BUG_REPORT.md instances) filed beside the work that surfaced them (milestone-{N}-{slug}/bugs/bug-{XXX}-{slug}.md or one-off/bugs/); artifacts/BUGS.md becomes the global index — ID assignment, one status line per bug, lifecycle and field-ownership rules, and the Tester-owned regression checklist.
• Minimal-context Handoff Protocol (new section in docs/PIPELINE_LOOP.md, binding on every agent and both engineering pipelines): the task file is the handoff medium; a stage's read set is closed (its agent definition + the task file + the manifest entries + the latest handoff entry's "Read next" — nothing else); handoff entries are capped fixed-format blocks (Outcome / Files touched / Read next / Open items, max 10 lines, no narrative); findings live in their canonical artifact with only pointers in the entry. The v1 pass-forward rule is superseded. Agent rule blocks, /agent-plan stages (Architect and UI now write manifest section-references per task), /agent-code (stages receive the task file path, Task Selection reads only task Headers), and /agent-task (creates its task file under one-off/) are all rewritten to the protocol. CEO Approval Conditions move from the tasks file to the milestone README, referenced from affected tasks' manifests.
• docs/FILE_CONVENTIONS.md, artifacts/README.md, agent files, payload docs, and both READMEs rewritten to the new layout and naming rules (fixed in-directory filenames; task-{T}-{slug}.md; bug-{XXX}-{slug}.md). Naming is now governed by an explicit two-tier case rule: UPPER_SNAKE for system singletons (docs, templates, the artifacts-root state files), lowercase kebab for instance files that multiply (milestone dirs, task files, bug files, reviews) — identifiers like BUG-001 and T-1 stay uppercase in prose while their files are lowercase.
• CI (validate.yml): the example structural check derives instance→template pairs from the new path patterns (including TASK.md and BUG_REPORT.md contracts), the path-split lint recognizes v2 instance patterns, the completeness check walks milestone directories, agents are checked for a tools: list that omits Task, and a state-consistency check verifies example task Statuses are legal enums, the Task Index and tasks/ agree bidirectionally, and the BUGS.md index matches each per-bug file's Status.
• Handoff-entry cap exception: Reviewer entries and Tester failure entries add one line per finding beyond the fixed fields — for those stages the Handoff Log is the canonical record, and findings are never dropped to fit the cap.
• /agent-code hardening: Pre-Flight resolves the milestone argument to a unique milestone-{N}-* directory (stopping on zero or multiple matches), and sets the milestone README's Status to In Progress when engineering starts, so the Status field is truthful through the whole phase.
• Example fixture restructured to example/artifacts/milestone-1-task-crud/ with five worked task files (task-03 demonstrates the full defect loop through its Handoff Log) and two per-bug files.

Added

• Parallel task execution in /agent-code. Independent tasks — pairwise-disjoint dependencies and Files lists — run their engineering loops concurrently (up to 3 at a time): stages of different tasks overlap while stages within a task stay sequential, all shared-root writes (STANDUP, BUGS index, AGENT_STATE) are orchestrator-serialized via standup:-prefixed queue lines in handoff entries, defect filing runs one chain at a time (bug-ID assignment is racy otherwise), checkpoints serialize, and emergent file overlap pauses the younger task. Sequential execution remains the default whenever a guardrail can't be met.
• Toolset-enforced agent discipline. Every agent's frontmatter now declares an explicit tools: list, and every list omits the Task tool — making the universal "do not spawn subagents" rule a hard guarantee. Lists are otherwise generous per role (engineering agents get Bash; Security additionally gets WebSearch/WebFetch for advisory lookups); an omitted tool is simply unavailable (no error), and explicit lists exclude MCP tools, so the lists are a documented per-project customization point. /cast-init Phase 6 validates presence and the no-Task rule.
• Handoff Protocol rule 6 — the reply channel carries routing metadata only. A stage's report to the orchestrator is a single line (Handoff entry #n appended — outcome; next: stage); the orchestrator routes on it and never re-narrates stage output, keeping the orchestrating context flat across a milestone. Agent rule blocks and both engineering pipelines state it.
• /agent-plan Stage 2c — manifest application. Architecture and UI no longer edit task files directly (they run in parallel and would race); each returns a Manifest Rows block and the orchestrator applies both to the task files in a single-writer step. Revision Handling now also requires re-verifying manifest rows whenever a cited design doc is revised — stale anchors silently defeat the minimal-context contract.
• One-off hygiene. Validator archives Complete one-off/task-*.md files into one-off/archive/ at milestone-completion checkpoints (bug files stay put — the index points at them), and spot-checks BUGS.md index rows against per-bug file Status at session start (bug file wins on mismatch).
• templates/TASK.md — the single-task template (Context Manifest + Handoff Log).
• templates/BUG_REPORT.md — the single-bug template (Report / Investigation / Resolution / Notes).
• /cast-init v1→v2 artifact migration: discovery detects the pre-2.0 by-type layout, Phase 3 proposes a per-file git mv mapping (with the -tasks.md split and BUGS.md index conversion flagged as explicit content transformations for user approval), execution performs it, and validation checks no by-type directories remain.

Process hardening from the v2 gap review (all folded into this release):

• Commit discipline (docs/PIPELINE_LOOP.md → Commit discipline): Coder, Tester, and Refactor commit every stage pass with a task-ID-prefixed message; loop-back fixes stack (never amend); each committing stage's handoff entry carries a Commit field (new optional line in templates/TASK.md); Reviewer reviews the diff over the task's logged commits instead of re-reading whole files; bug files' Resolution → Commit is filled from the stacking fix commit; a validated task's commit run is its independent rollback unit.
• Task-amendment rule (docs/PIPELINE_LOOP.md): when a stage discovers mid-task that scope is wrong (incomplete Files list, unachievable criterion, two-tasks-in-one), it pauses and proposes; Product — as scope owner — approves, splits, or rejects; the loop resumes. No more silent scope expansion and no forced re-plan for in-envelope corrections. Amendments don't increment the loop counter or the circuit breaker.
• Flag-gated implementation reviews at milestone completion: the Stage 3 planning reviews now end with a single flag line — **Implementation review required**: Yes/No in reviews/security.md (Yes for auth, input handling, new dependencies, sensitive data) and **Measured check required**: Yes/No in reviews/performance.md (Yes when budgets apply). Flagged milestones get a security review of the implementation diff (reviews/security-impl.md) and a measured budget check (reviews/performance-impl.md, updating the live AGENT_STATE budget table) at the /agent-code milestone-completion checkpoint, mirroring the UX-review pattern. CI enforces flag → file on completed example milestones.
• Retrospective intake (/agent-plan Stage 1): Product reads the prior milestone's retrospective and disposes of every open improvement action — Adopted → M{N} or Declined — <reason> — into the retrospective's new Disposition column (templates/MILESTONE_RETROSPECTIVE.md). Retrospectives now feed planning instead of being write-only.
• Manifest quality gate and metric: the CEO checklist (templates/CEO_REVIEW.md § 6) verifies every task's Context Manifest is complete and minimal, and the retrospective gains a "Manifest patches during engineering" metric row sourced from Handoff Logs — the gate catches bad manifests before engineering, the metric catches what the gate missed.
• Regression red-proof (docs/PIPELINE_LOOP.md Step 2): on Fix Now defect cycles, the covering test must demonstrably fail against the pre-fix commit (checkout, run red, re-apply, run green) — a test that has never been red doesn't count.
• Named owners for two orphaned writes: the orchestrator appends each task's Handoff Log entry #1 (orchestrator → coder — task released; example fixture relabeled to match), and Product flips CEO Approval Conditions to Verified while writing the completion record (templates/MILESTONE_DEFINITION.md note; /agent-code completion step 3).
• Bounded root files (validator.md → Archival Duty): at milestone completion, Validator relocates stale STANDUP sessions and closed AGENT_STATE rows verbatim to artifacts/archive/{STANDUP,AGENT_STATE}.md, keeping the two most-read shared files bounded to the current milestone plus a tail. The one sanctioned exception to append-only.
• Milestone circuit breaker (/agent-code): escalate to the user when more than half the milestone's started tasks have looped, or total loop-backs reach 2× task count — with a cost sanity note. The per-task loop cap guards a task; this guards the run.
• Single-task planning mode (/agent-plan single: <feature>): the middle tier between /agent-task and full ceremony — Product + Architecture + CEO only, one task file, same milestone layout (/agent-code consumes it unchanged); UI/Security/Performance pulled in only when Stage 1 flags them; CEO sections for skipped stages read "N/A — single-task mode". /agent-task's bail-out messages now route one-design-decision work here instead of to full ceremony.
• Batch-round parallelism phrasing (/agent-code → Parallel Task Execution): rules rewritten as rounds (launch a batch of eligible stages, collect all routing lines, launch the next batch) to match the harness's batch-barriered subagent semantics — same throughput, honest mechanics.
• /agent-task Pre-Flight import note reworded for the orchestrator/subagent split: the orchestrator has memory imports in context; loop stages are subagents that rely on project memory plus the task file's Context Manifest.
• /cast-doctor — a fourth installable skill (the maintenance skill; installed unconditionally by /cast-init to .claude/skills/cast-doctor/SKILL.md). A run-anytime health check of the CAST install in three functions: state (the Phase 6 install-validation invariants plus the drift invariants nothing checked between installs — bug index ↔ bug files, task indexes ↔ task files, STANDUP grammar, bounded logs, resolving manifests/imports, completed-milestone review completeness, version stamp); documentation diet (finds installed docs whose content the codebase already expresses, prescribed in two tiers — Tier A always safe: duplication, unfilled memory-imported skeletons, dead references, self-obsoleted content; Tier B gated per document on its weakest consumer's model via the new Context Inference Bar section in docs/MODEL_OPTIMIZATION.md — capable models infer layout/naming/stack/best-practices from code, so restating them is context weight, but a doc cited by a Haiku-pinned agent keeps its scaffolding); and coverage (what docs should record but don't: undrained docs queues, unpromoted decisions, unfilled budget/NFR skeletons, recurring patterns absent from CODE_PATTERNS, dangling citations). Runs self-contained with an itemized approval gate (Examine → Diagnose → Prescribe → approve → Treat → Verify; /cast-doctor checkup stops at the report); rescues embedded decisions into docs/DESIGN_RATIONALE.md before any trim; protects cited section anchors; writes one bounded report at artifacts/DOCTOR.md (overwritten per run, git keeps history). Docs Writer keeps add/correct authority while wholesale removal now belongs to the doctor; Validator surfaces unresolved Error findings at session start. Re-run after any model change — upgrades unlock Tier B prunes, downgrades surface restorations.

Removed

• templates/MILESTONE_TASKS.md (superseded by templates/TASK.md).
• The pre-created artifacts/{milestones,architecture,ui-specs,reviews}/ scaffold directories and the combined-breakdown, combined-bug-log formats.

Migration

• Existing installs: update the cast-init skill (npx skills update or /plugin marketplace update), then re-run /cast-init — the adoption plan will propose the by-type → by-milestone migration (file moves, task-file split, bug-index conversion) for your approval and update every installed agent, skill, and doc. Manual equivalent: apply the mapping table in skills/cast-init/references/dispositions.md → "Artifacts directory".
• In-flight milestones: finish the current milestone on v1 before migrating, or migrate and hand-split its -tasks.md — the pipelines no longer read the combined breakdown.