groundwork-method 0.0.1 → 0.10.0

package/src/hidden-skills/groundwork-design-system/tracks/_foundation.md

@@ -0,0 +1,136 @@
+# Shared Foundation (Brand Level)
+
+A product has one brand — one mood, one personality, one interaction philosophy, one language — no matter how many interface types express it. This flow establishes that brand once. The type tracks (`graphical-ui.md`, `cli.md`, `agentic-protocol.md`) then translate it into each medium: CSS tokens for a screen, ANSI roles for a terminal, protocol semantics for an agent surface. Running the brand conversation per type would ask the user to decide their product's personality twice and invite the two answers to drift; running translation at brand level would produce a spec too abstract to implement. The split keeps each conversation at its right altitude.
+
+This file owns the session's spine:
+
+1. **Phases 1–4 run once, here.** Each phase pulls the type-specific contributions it needs from the active tracks' `Foundation Contributions` sections — the envelope dimensions, research palettes, and language dimensions that genuinely differ by medium. Phase 3 (structure) is the exception: it is inherently per type, so this flow runs each active track's Phase 3 in turn.
+2. **Phase 5 (translation + guided review) runs once per active type.** Load each active track's Phase 5 and execute it; the track is authoritative for its medium's translation.
+3. **Phase 6 (commit) runs once, here,** after every active type's walkthrough completes.
+
+The active types were recorded in `.groundwork/cache/design-system-cache.md` during initialization. With one active type, this flow degrades to the familiar single-track session — the same phases in the same order, with the foundation and the type conversation indistinguishable to the user.
+
+Before Phase 1, read each active track's **Default Stance** and **Foundation Contributions** sections in full — they carry the defaults, palettes, and dimensions the phases below draw on.
+
+---
+
+## Cross-Phase Signal Capture
+
+Design conversations routinely surface signals that belong to a different phase — a performance target or startup budget with infrastructure implications, an offline expectation or configuration store that shapes data architecture, a sequencing instinct about which features ship first. As these signals arise during any phase — foundation or track — append them as bullets under the matching section header in `.groundwork/cache/discovery-notes.md`: `## Architecture` for infrastructure or technology opinions, `## Design Details` for async, schema, or contract implications, `## Bets` for feature sequencing, `## Product Brief` for vision-level refinements — then return to the current topic. Capturing them now means the downstream phase finds them instead of asking the user to repeat themselves.
+
+---
+
+## Phase 1: Non-Functional Requirements (NFR)
+
+NFRs define the engineering envelope the design system must operate within. Budgets, baselines, and tolerance policies constrain design choices downstream — a design system that specifies 300ms transitions inside a 50ms interaction budget, rich interactive prompts for a tool that must run headless in CI, or rich diagnostic output inside a 4K-token context budget is internally contradictory.
+
+Read `docs/product-brief.md`. For each active type, apply its track's **Envelope** contribution — the dimensions to cover, the type defaults to advocate, and any pre-step the track requires (the CLI track settles its composable/interactive/hybrid paradigm before anything else, because that decision shapes its whole envelope). Using the product brief and those track defaults as your starting position, draft one complete NFR proposal immediately — do not open with questions. The proposal covers the product-wide envelope and each active type's envelope; when two types share a dimension (error tolerance, offline behaviour), state it once at product level and note any per-type divergence. Skip dimensions that are clearly irrelevant to the product.
+
+Present the proposed NFRs in full and invite the user to confirm, challenge, or adjust specific items. The proposal is the starting position — accept what the user confirms, revise what they challenge. Once approved, write the confirmed NFRs to the Phase 1 section of `.groundwork/cache/design-system-cache.md` and set its status to `done`. Proceed to Phase 2.
+
+---
+
+## Phase 2: Research
+
+The inspiration library grounds the design conversation in concrete, existing products. Abstract discussions ("make it premium", "make it precise") produce vague specs. Discussions anchored in specific examples — Linear's command palette rendering from local cache before the server responds, ripgrep streaming results so the first match appears before the search completes, Terraform's plan-apply-verify loop forcing explicit approval before any state mutation — produce actionable design decisions.
+
+Drawing on the product context and agreed NFRs from Phase 1, identify the 3–5 core design challenges this product faces (e.g., "async generation with delayed delivery," "streaming dense results into a terminal," "media-heavy reading experience"). For each challenge, find 1–2 leading products that solve it exceptionally well, pulling from each active track's Default Stance palette and any **Research notes** in its Foundation Contributions. Match sources to what was settled in Phase 1 — an interactive CLI needs interactive exemplars; a composable one does not borrow REPL patterns it will never use. Describe the **specific pattern, interaction, or mechanism** worth borrowing — not just the product's reputation. Aim for 5–8 references total; when several types are active, every type's challenges must be represented. Breadth across challenges is more valuable than depth on one.
+
+Present this Inspiration Library and ask for the user's reaction. Do they agree? Are there specific paradigms they want to adopt? Do not proceed until they have confirmed the direction.
+
+Once approved, write to the Phase 2 section of `.groundwork/cache/design-system-cache.md` and set its status to `done`. Proceed to Phase 3.
+
+---
+
+## Phase 3: Structure (Per Type)
+
+Structure is the one foundation-stage conversation that cannot run at brand level: a screen product needs an app shell, a terminal product needs a command architecture, a protocol product needs a workspace topology. Each is the structural container every later decision for that type lives inside, and Phase 4's language conversation reacts to it.
+
+For each active type, run its track's Phase 3 in full — the track owns the conversation. Record each type's approved structure in its own subsection under Phase 3 in `.groundwork/cache/design-system-cache.md`. When every active type's structure is approved, set the Phase 3 status to `done` and proceed to Phase 4.
+
+---
+
+## Phase 4: Brand Language
+
+This phase captures the user's taste — the brand's mood, personality, interaction philosophy, and language — as the raw material every type's Phase 5 translation draws from. The user should never need to think about specific values, in any medium. Decide the brand once; let each type express it.
+
+Draw on the product brief for identity and audience context, and on the inspiration library from Phase 2 for concrete reference points. Cover the language in three focused clusters — grouping related decisions so the user can react to a coherent stance rather than isolated individual choices. Each cluster pairs the brand-level core below with each active type's dimensions for that cluster, taken from the track's **Type language** contribution, so the brand stance and its per-medium expression are settled in the same conversation. For each cluster, open with a cohesive proposal that reflects what the product brief and inspiration library suggest, then invite the user to react and redirect.
+
+**Cluster 1: Identity** — The brand's personality and emotional register: what the product feels like, how it speaks, and what vocabulary conventions carry that identity. Fold in each active type's identity dimensions.
+
+**Cluster 2: Feel** — Information density, pacing, and feedback philosophy: how much the product communicates, how physical or restrained it feels, and how it signals work in progress. Fold in each active type's feel dimensions.
+
+**Cluster 3: Craft** — Error philosophy and microcopy character: how the product behaves when things go wrong, and how its smallest text units feel. Fold in each active type's craft dimensions.
+
+After each cluster proposal, invite the user to react and refine before advancing. Mark each cluster as covered in `.groundwork/cache/design-system-cache.md` as you go. Skip a dimension only when it is clearly irrelevant to the product.
+
+### Synthesis Gate
+
+Before caching, distill the entire Phase 4 conversation into a structured design direction and present it to the user for confirmation. Scattered conversation notes are not sufficient input for Phase 5 — the synthesis forces the agent to reconcile any contradictions and present a coherent vision.
+
+The synthesis stays in the user's language. No CSS values, no ANSI codes, no state schemas. It captures the *decisions* the user made in terms they recognise and can confidently approve or correct.
+
+Brand-level fields, always:
+
+- **Brand personality**: A short characterisation of the overall feel and voice.
+- **Emotional register**: The mood and temperature the product carries.
+- **Voice and tone**: How the product speaks to its users.
+- **Information density**: How much the product communicates per view or per turn.
+- **Feedback philosophy**: How the product responds to the user working — motion, progress, status.
+- **Error philosophy**: How failures feel and how much the product explains.
+
+Plus each active type's expression fields, listed in its track's Type language contribution.
+
+Present this as a clear summary the user can scan and approve in one read. Ask them to confirm or correct before proceeding.
+
+Once confirmed, write the synthesis to the Phase 4 section of `.groundwork/cache/design-system-cache.md` and set its status to `done`. Proceed to Phase 5.
+
+---
+
+## Phase 5: Per-Type Translation & Review
+
+For each active type in turn, load its track's Phase 5 and execute it in full — translation (5a), independent review, and guided walkthrough (5b). The track is the single source of truth for its medium's translation mandate, quality standard, and cluster walkthrough. Track each type's walkthrough progress separately in `.groundwork/cache/design-system-cache.md`.
+
+### Draft Layout
+
+All types share one draft directory, `.groundwork/cache/design-system-draft/`, concatenated by filename at commit.
+
+**Single active type:** use the track's file table exactly as written, with one change — the first type-specific section file (`02-…`) opens with the type's section title as its first line (`# Graphical UI`, `# CLI`, or `# Agentic Protocol`) so `docs/surfaces.md` design-track references (`docs/design-system.md § CLI`) resolve. Everything else, including heading levels, is unchanged.
+
+**Several active types:**
+
+- `00-header.md` and `01-foundation.md` are written once, by the first type's 5a run. `00-header.md` carries the document title and intro as the track describes — no summary section; the Downstream Context (Protocol 5) is written separately to `.groundwork/context/design-system.md` at commit, not concatenated into the spec. `01-foundation.md` carries `# Part 1 — Foundation`: the product-wide constraints from Phase 1 and the brand language direction from Phase 4 in specification form — the shared reference every type section translates, and the anchor for cross-surface consistency.
+- Each type's section files take a decade prefix in run order (`10-`, `20-`, `30-`) with the type slug in the name — e.g. `10-graphical-ui-shell.md`, `20-cli-command-architecture.md` — replacing the track table's `02-`…`07-` prefixes; the section content per file is as the track's table defines, except that each type's envelope-specific constraints open its own section rather than sharing Part 1. The type's first file opens with the type's `#`-level section title, and the track's part headings demote one level beneath it so section boundaries stay unambiguous when the document is read as a whole.
+- The numeric prefixes keep `cat *.md` concatenation in order: header, foundation, then each type's section.
+
+When the last active type's walkthrough completes, proceed to Phase 6.
+
+---
+
+## Phase 6: Commit
+
+Execute **only** after every active type's Phase 5b walkthrough is complete and the user has explicitly approved each type's specification. Verify every walkthrough checklist in `.groundwork/cache/design-system-cache.md` is marked complete before proceeding.
+
+Follow the Phase Lifecycle commit protocol from the Operating Contract:
+
+1. **Write the Downstream Context file (Protocol 5).** Apply `groundwork-writer` to write `.groundwork/context/design-system.md` — the four-subsection contract per Protocol 5 of the operating contract: Key Decisions covering the brand foundation and every active type (each track's Commit Contributions section names its key-decision set), Binding Constraints (accessibility floors, performance budgets, fallback chains, machine-readability requirements), Deferred Questions, Out of Scope. This is written to the ephemeral context store, not into `docs/design-system.md` — the assembled spec carries no summary section.
+
+   **Persist the design references as a technique library.** When a `graphical-ui` type is active, confirm the foundation draft carries a `## Design References` section — and, now that the aesthetic direction is settled, run one **convergent research pass** to build it. The Phase 2 inspiration library was divergent: it explored directions. This pass is convergent: find the named, high-end products that are best-in-class at *this specific* settled aesthetic, and for each extract the concrete techniques at the parameter level — surface treatment (blur radius, tint opacity, border), the elevation stack, motion timing and easing, type and spacing rhythm — never screenshots. Record per product: its name, the specific qualities admired and the technique behind them ("Linear's command palette: ~12px backdrop blur, a 1px top highlight, restrained accent on under 5% of surface"), and the design challenge it answers — naming at least three products. This is a **technique library, not a mood board**: borrow the rigour, never the signature look. It feeds two consumers — the atmosphere and motion tokens (step 3) and the per-surface micro-polish spec at bet design — so a technique admired but never written here evaporates with the rest of the inspiration cache in step 5. The `visual` block's `references` array (step 3) carries the named set machine-readably.
+
+2. **Assemble the final spec.** Concatenate the section files into the canonical location: `run_command("cat .groundwork/cache/design-system-draft/*.md > docs/design-system.md")`. The numeric prefixes guarantee the correct order — the glob picks up per-type decades and the CLI track's `06`/`07` files automatically. This is a shell operation, not a model emission — it does not consume output tokens regardless of spec size.
+
+3. **Emit brand tokens.** Write `.groundwork/config/brand-tokens.json` following the contract at `.groundwork/skills/groundwork-design-system/templates/brand-tokens.md`: the Tier 1 `identity` block always (every product gets a branded `./dev` CLI), plus one Tier 2 block per active type that defines one — `terminal` from the CLI track, `visual` from the graphical-ui track; the agentic-protocol track contributes no Tier 2 block. Each block carries the *same* values as the corresponding type section just written into `docs/design-system.md` — this is a mechanical projection of approved decisions, not a new conversation. The file lives in persistent config and is not removed by the cache cleanup in the next step.
+
+4. **Write the hand-off file.** Copy `.groundwork/skills/templates/handoff.md` to `.groundwork/cache/handoff/design-system.md` and fill in only the sections that have content: rejected directions, deferred design decisions, and user instincts not yet committed — each active track's Commit Contributions section lists what its medium typically leaves behind — plus any other context the architecture phase needs. Omit empty sections.
+
+5. **Clean up caches.** Remove the draft directory, the design-system cache, and the consumed previous hand-off: `run_command("rm -rf .groundwork/cache/design-system-draft .groundwork/cache/design-system-cache.md .groundwork/cache/handoff/product-brief.md")`. Cache Isolation (Protocol 7) requires the previous hand-off to be deleted once consumed.
+
+6. Apply the Living Documents protocol — scan the conversation for insights that refine any existing `docs/` artifact (e.g. `docs/product-brief.md`). Apply surgical updates and refresh the affected Downstream Context files in `.groundwork/context/` (Protocol 5). Report what changed. If an update **reverses** a prior Key Decision or Binding Constraint (Protocol 2 — e.g. the design system overturns a brief commitment), follow the Reversal Protocol: reconcile the full body of the affected doc, fix dependent docs, write the superseding ADR, and re-invoke `groundwork-review` on each mutated doc before committing.
+
+7. Update discovery notes — scan for out-of-phase signals not captured in real time. Remove `## Design System` entries incorporated into `docs/design-system.md` or the hand-off file.
+
+8. Confirm that the phase is complete.
+
+9. Recommend a fresh context for the next phase — a clean context gives the next skill full working memory.
+
+10. Immediately load and execute the `groundwork-orchestrator` skill to show the user what's next. Do not ask the user to invoke it — hand off automatically.

package/src/hidden-skills/groundwork-design-system/tracks/agentic-protocol.md

@@ -0,0 +1,269 @@
+# Agentic Protocol Track
+
+This track applies to products whose primary interface is an agent-to-human or agent-to-agent protocol: skill frameworks, MCP servers, developer methodology tools, agent orchestrators, and any product where the "user interface" is a structured conversation between humans and AI agents.
+
+The shared foundation flow (`tracks/_foundation.md`) owns the session spine: it runs the brand-level Phases 1, 2, and 4 once for the whole product, drawing this track's contributions from the Foundation Contributions section below, and it runs this track's Phase 3 and Phase 5 at the right points. Its Cross-Phase Signal Capture rule stays in force throughout every phase of this track.
+
+---
+
+## Default Stance
+
+Be fluid. Adapt seamlessly to the user's product positioning and the specific agent ecosystem they target. The agent's role is to match the user's vision — not to impose a rigid protocol style.
+
+The default starting position is modern, high-precision protocol design. When the user has no strong preference, advocate for the following defaults — and be ready to explain *why* each one matters:
+
+**Technical defaults:**
+- Zero-boilerplate context loading — the agent must reach operational awareness from cold start in under 3 file reads. Every extra file read burns tokens and delays the agent's first useful action.
+- Declarative state management via flat, machine-readable files (JSON, TOML). Agents parse structured data reliably; they hallucinate when reconstructing state from prose.
+- Agent-agnostic design — the protocol must function identically across Claude Code, Gemini, Cursor, Windsurf, and any future agent runtime. Platform-specific features create lock-in that limits adoption.
+- Filesystem as the shared memory layer. No database, no API, no external service required for protocol state — because every external dependency is a failure mode the agent cannot diagnose or recover from.
+- Deterministic phase transitions — every state change must be traceable and reversible. Ambiguous state is the primary cause of agent confusion in multi-phase workflows.
+- Version-controlled everything — every design decision, state transition, and artifact must live in the repo. The repo is the single source of truth; anything outside it is invisible to the agent.
+
+**Precision bar** (examples of the premium standard the agent targets):
+- Surgical context injection — the agent receives exactly the information it needs for the current task, nothing more.
+- Contract-first design — interfaces, schemas, and data flows are defined before implementation begins.
+- Proof-of-work verification — system-wide tests, not human code review, are the primary quality signal.
+- Layered fidelity — information flows from abstract (vision) to concrete (implementation) through strict layers.
+- Explicit error postures — every failure mode has a defined recovery path.
+- Human-as-architect — humans own design decisions; agents own execution within those decisions.
+
+Draw inspiration from trend-setting systems: Shape Up, Linear Method, OpenAPI, Protocol Buffers, Terraform, LSP, MCP, Unix philosophy.
+
+---
+
+## Foundation Contributions
+
+The shared foundation flow pulls these sections into its brand-level phases.
+
+### Envelope (foundation Phase 1)
+
+Cover all relevant dimensions of the protocol envelope: agentic efficiency (context budgets, token consciousness, cold-start file-read ceiling), context persistence and resumability, authority model (human-led vs agent-led boundaries), verification and governance, error resilience, interoperability across agent runtimes, auditability and traceability, and security and trust boundaries. Ground each decision in the product brief and apply the track defaults where applicable: zero-boilerplate context loading (under 3 file reads from cold), declarative state in flat machine-readable files, agent-agnostic interfaces, filesystem-as-memory, deterministic phase transitions, version-controlled artifacts.
+
+### Research notes (foundation Phase 2)
+
+Sources for this type span methodologies, specification systems, developer tools, formal methods, and protocol designs — describe the specific **mechanism** worth borrowing, not the system's reputation.
+
+### Type language (foundation Phase 4)
+
+Fold these dimensions into the foundation's language clusters. The user should never need to think about specific formatting rules or state schemas:
+
+- **Cluster 1: Identity** — Tone and posture, microcopy and phrasing, naming and taxonomy. Propose the agent's voice as a unified stance: where it sits on the terse-to-pedagogical spectrum, how its smallest text units feel, and what vocabulary conventions govern commands, phases, and artifacts.
+- **Cluster 2: Feel** — Information density and the propose-vs-prompt ratio. Propose how much an agent communicates per turn, whether it leads conclusions-first or builds narrative, and where it defaults to proposals vs open questions.
+- **Cluster 3: Craft** — Status semantics, documentation hierarchy, and error communication. Propose how state is signalled, how protocol documents are structured for both humans and agents, and where errors land on the spectrum from silent recovery to loud halts.
+
+This type's Synthesis Gate expression fields:
+
+- **Propose-vs-prompt ratio**: The default interaction mode.
+- **Status language**: How the protocol signals state.
+- **Naming instinct**: The vocabulary style.
+- **Microcopy tone**: How the smallest units of text feel.
+
+---
+
+## Phase 3: Workspace Topology
+
+*Runs inside the foundation flow's Phase 3 step — once for this type.*
+
+The workspace topology is the structural container everything else lives inside — the filesystem architecture, state management, and discovery surfaces that agents and humans interact with. Getting this wrong means reworking every skill. Getting it right means every subsequent protocol decision has a home.
+
+Define the structural skeleton using patterns from the Phase 2 inspiration library. The agent should explore and propose decisions across: filesystem architecture (where config, state, cache, and deliverables live), state management (format, schema, valid transitions), skill and tool discovery (manifests, directory conventions, routing tables), context injection strategy (global vs phase vs task layers), empty and boot states (first run, interrupted, stale), and progressive disclosure (how complexity scales as the project matures).
+
+Guide the conversation with leading-edge protocol patterns. Propose the topology based on the inspiration library, then ask the user to react and refine.
+
+When a topology decision implies a backend or infrastructure capability — state-store service, registry or routing backend, agent runtime, distribution channel, identity provider — append the implication as a bullet under `## Architecture` in `.groundwork/cache/discovery-notes.md` before continuing the conversation. The architecture phase finds these notes and skips re-deriving what was already decided here.
+
+Once approved, write to this type's subsection under Phase 3 in `.groundwork/cache/design-system-cache.md` and set it to `done`. Return to the foundation flow.
+
+---
+
+## Phase 5: Expert Translation & Review
+
+*The foundation flow runs this phase once per active type, after the brand language direction (foundation Phase 4) is confirmed. The agent translates that direction into concrete protocol specifications — the user never sees a raw schema until the walkthrough.*
+
+### 5a: Translation (Agent-Driven, Autonomous)
+
+The user provided taste, instinct, and direction across Phases 1–4. The agent now translates that into a rigorous protocol design specification — autonomously.
+
+**Output location**: `.groundwork/cache/design-system-draft/` — a directory of per-section files. Each file stays bounded in size, so any later change (review revise, 5b re-flow) touches only the affected files instead of regenerating the whole spec in a single turn. Regenerating the whole spec at once exhausts the per-response output token budget on rich specs; the per-section layout makes that failure structurally impossible. Writing to `docs/design-system.md` is prohibited until Phase 6 (Commit) — on initial generation that file does not exist; do not attempt to read it.
+
+**Write each section as a separate file.** Use one `write_file` call per section (the tool creates parent directories automatically):
+
+| File | Content |
+|---|---|
+| `00-header.md` | The document title and the "implementation-ready specification" intro paragraph. No summary section — the Downstream Context (Protocol 5) is written separately to `.groundwork/context/design-system.md` at commit, not concatenated into the spec |
+| `01-constraints.md` | Part 1 — context-loading budgets, verification requirements, authority boundaries, error resilience policies, interoperability guarantees |
+| `02-workspace-topology.md` | Part 2 — filesystem architecture, state management, discovery surfaces, context injection strategy, communication posture |
+| `03-foundation.md` | Part 3 Cluster 1 — state architecture, context hierarchy, document architecture |
+| `04-interaction.md` | Part 3 Cluster 2 — interaction semantics, tone & posture specification |
+| `05-surface.md` | Part 3 Cluster 3 — skill & tool anatomy, error & recovery choreography, naming & taxonomy, versioning & evolution |
+
+The numeric prefixes determine concatenation order at commit. Each file is a self-contained markdown section — start its top-level heading at H1 (`# Part 1 — Constraints`) or H2 as appropriate so the files compose cleanly when concatenated.
+
+This table is the single-active-type layout; the foundation flow's Draft Layout rule governs how it adapts — the type section title (`# Agentic Protocol`) opening the first type-specific file, and, when several types are active, decade-prefixed type-slugged filenames with part headings demoted beneath the type title and `01-foundation.md` carrying the shared Part 1.
+
+Compile each section using the approved outputs stored in `.groundwork/cache/design-system-cache.md`. The document combines NFRs from Phase 1 with a comprehensive protocol design system that the agent derives from the interaction language direction captured in Phase 4.
+
+Apply the `groundwork-writer` skill to ensure the tone is declarative, assertive, and free of hedging. Structure it to read like a rigorous protocol specification that simultaneously serves as instruction material for any agent runtime.
+
+#### The Translation Mandate
+
+The user said "collaborative peer" — the agent specifies the exact persona brief, prohibited hedging phrases, and propose-vs-prompt triggers. The user said "conclusions first" — the agent defines the inverted pyramid rule with concrete structural templates. The user said "verb-noun commands" — the agent produces a complete naming convention with casing rules, artifact patterns, and vocabulary definitions. Every high-level preference from Phase 4 must be resolved into concrete, enforceable specifications. If the cached direction is ambiguous, the agent makes the design call — that is the job.
+
+Agent runtimes consistently fail to maintain protocol coherence without deeply specified interaction rules. The protocol design system must go beyond naming conventions and tone guidelines — it must prescribe exact state schemas, phase transition rules, error choreography, and a clear taxonomy.
+
+#### Quality Standard: Deep vs. Shallow
+
+Every section must contain enough detail that a developer implementing this protocol would not need to make any design decisions of their own.
+
+**Shallow output (unacceptable):**
+```
+Error Handling:
+- Recoverable errors: retry automatically
+- Blocking errors: ask the user
+- Use clear error messages
+```
+
+**Deep output (required standard):**
+```
+Error & Recovery Choreography
+═════════════════════════════
+
+Severity Levels
+───────────────
+
+  Level          │ Agent Response              │ Human Visibility
+  ───────────────┼─────────────────────────────┼──────────────────────────
+  recoverable    │ Self-repair: retry with      │ Silent unless retry fails
+                 │ backoff (1s, 2s, 4s, max 3). │ 3x. Then escalate to
+                 │ Log attempt to cache.        │ blocking.
+  blocking       │ Halt immediately. Do not     │ Full diagnostic:
+                 │ attempt workaround.          │ what → why → next step.
+  inconsistent   │ Run reconciliation:          │ Report divergence and
+                 │ filesystem wins over state   │ resolution taken. Ask
+                 │ file. Update state to match. │ to confirm if destructive.
+  violation      │ Hard stop. No override.      │ "Contract violation:
+                 │ No workaround. Log and halt. │ [contract] requires [X],
+                 │                              │ found [Y]. Human-led
+                 │                              │ design revision required."
+
+  Escalation Ladder
+  ─────────────────
+  1. Self-repair (recoverable only, max 3 attempts)
+  2. Diagnostic halt — format: "Blocked: {what}. Cause: {why}. 
+     Action: {what the human should do}."
+  3. If blocked 2x in same phase → suggest the user open a new chat
+     with fresh context, referencing the cache state.
+
+  Halt Message Template
+  ─────────────────────
+  ⚠ Blocked: {description of what failed}
+    Cause: {why it matters / what triggered it}
+    State: {current phase, last successful step}
+    Action: {specific next step for the human}
+```
+
+The shallow version gives a developer three bullets. The deep version gives them a complete error system with severity classifications, escalation rules, reconciliation algorithms, and message templates. **Every section of the protocol design system must hit this depth.**
+
+The same standard applies across the entire specification:
+- **State architecture**: Not just "use JSON" — exact schema with required fields, valid values, type constraints, transition rules, cold-start resolution algorithm, and reconciliation rules when filesystem and state disagree.
+- **Context hierarchy**: Not just "load context in layers" — exact files per layer, load order, context budget rules (max file reads, max tokens), and cache invalidation triggers.
+- **Document architecture**: Not just "use frontmatter" — required sections, heading hierarchy, metadata schema, cross-reference format, inverted pyramid rule, and machine-parsability constraints.
+- **Interaction semantics**: Not just "use status markers" — full status vocabulary table with symbols, exact meanings, and usage rules. Log level definitions. Colour semantics if terminal output is involved. Progress communication rules.
+- **Tone and posture specification**: Not just "be collaborative" — concrete persona brief, prohibited phrase list with required replacements, propose-vs-prompt ratio with triggers, and microcopy templates for confirmations, transitions, errors, and status.
+- **Skill and tool anatomy**: Not just "skills have phases" — standard skill interface, pre-flight checklist, action contract (idempotency, atomicity, rollback), handoff protocol, and post-action validation rules.
+- **Naming and taxonomy**: Not just "use kebab-case" — command naming convention, artifact naming convention, vocabulary boundary definitions with precise term meanings, and the naming self-test.
+- **Versioning and evolution**: Breaking change protocol, backward compatibility guarantees, and changelog format.
+
+#### Design System Target Structure
+
+**Part 1 — Constraints**: Context-loading budgets, verification requirements, authority boundaries, error resilience policies, interoperability guarantees.
+
+**Part 2 — Workspace Topology & Interaction Principles**: Filesystem architecture, state management, discovery surfaces, context injection strategy, communication posture.
+
+**Part 3 — Protocol Design System** (each at the depth standard above):
+State architecture · Context hierarchy · Document architecture · Interaction semantics · Tone & posture specification · Skill & tool anatomy · Error & recovery choreography · Naming & taxonomy · Versioning & evolution
+
+---
+
+Before presenting the draft, run this self-check:
+1. **Does every section contain committed, implementable specifications?** If a section reads like a brief ("use a collaborative tone with clear errors"), the translation is incomplete.
+2. **Does every specification include concrete schemas, templates, or tables?** Prose descriptions without structured examples are insufficient.
+3. **Would a developer implementing this protocol need to make any design decisions?** If yes, the spec is underspecified.
+
+### Independent Review (Pre-Walkthrough)
+
+The user is about to see this draft in Phase 5b. Before they do, the draft passes through an independent review — `groundwork-review` checks the draft for silent invention, dropped commitments from Phase 4, and contradictions against the upstream Product Brief that the user is unlikely to catch during a walkthrough of state schemas and naming taxonomy tables. The protocol design system constrains every downstream skill and tool; catching these failures here is cheaper than catching them after `docs/design-system.md` becomes the source of truth.
+
+1. **Announce** the shift — the agent is moving from translation into an independent review before presenting to the user.
+2. **Assemble the draft for review.** Run `run_command("cat .groundwork/cache/design-system-draft/*.md > .groundwork/cache/design-system-draft.md")` to concatenate the section files into a single document. This is a shell operation, not a model emission — it does not consume output tokens regardless of spec size.
+3. **Invoke the review subagent** (Protocol 9) with `document_path: .groundwork/cache/design-system-draft.md` and `document_type: design-system`. The gate is fail-closed (Protocol 8): proceed only on a parseable `VERDICT: PRESENT`; a review that errors, hangs, or returns no verdict follows Protocol 9's failure path — do not present the draft as reviewed.
+4. **Revise loop.** If the verdict is **REVISE**, apply every 🔴 Critical finding directly to the affected section file(s) under `.groundwork/cache/design-system-draft/` — rewrite only the files the finding implicates. After revisions, re-assemble with `cat` and run the review again. Repeat until the verdict is **PRESENT**. After 3 REVISE verdicts, apply the revise cap defined in Protocol 8.
+5. **Clean up the assembled file.** Once the verdict is PRESENT, run `run_command("rm .groundwork/cache/design-system-draft.md")`. The section files in the draft directory remain the source of truth for Phase 5b and Phase 6.
+6. **Carry advisory findings forward.** When the verdict is PRESENT, hold any 🟡 Advisory findings — they surface to the user during or after Phase 5b so the user can decide whether to act on them.
+
+Once the review verdict is PRESENT, proceed to Phase 5b.
+
+### 5b: Guided Review (Collaborative)
+
+The draft is a proposal. Present it to the user as one — explicitly frame it as what the agent built from their direction.
+
+**Do not ask the user to approve the full spec.** Do not present a summary and ask "does this look right?" Instead, walk through the spec in three focused clusters, each earning approval before advancing. When the user wants to push a section deeper — or a section reads thin against the quality standard above — load `.groundwork/skills/groundwork-elicit/instructions.md` and follow it.
+
+#### Cluster Walkthrough
+
+The cluster names here are deliberately distinct from the Phase 4 language clusters (Identity / Feel / Craft) — Phase 4 grouped *aesthetic decisions* the user owns; Phase 5b walks through *implementation specifics* the agent owns. Distinct names keep both schemes legible when both phases are referenced in the same conversation.
+
+**Cluster 1: Foundation** — State architecture, context hierarchy, and document architecture.
+
+These are the base primitives every later decision composes from. Present the state schema with required fields and transition rules, the context-injection layers with file ordering and budgets, and the document anatomy with frontmatter and heading hierarchy side by side. Teach the reasoning: why flat machine-readable state, why this load order, how the inverted-pyramid rule keeps documents agent-parseable. Offer alternatives that honour the same direction. Wait for the user's reaction before advancing.
+
+**Cluster 2: Interaction** — Interaction semantics and the tone & posture specification.
+
+These define how the agent behaves turn to turn. Present the status vocabulary table, the persona brief with prohibited phrases and required replacements, and the propose-vs-prompt trigger rules as a connected system. Teach the trade-offs: terse status markers feel efficient but reduce orientation; pedagogical microcopy builds trust but adds tokens. Justify the specific choices against the Phase 4 direction. Offer alternatives. Wait for the user's reaction.
+
+**Cluster 3: Surface** — Everything else: skill and tool anatomy, error and recovery choreography, naming and taxonomy specifications, versioning and evolution.
+
+These are engineering craft — decisions the agent should own. Present the full set as a summary table: what was decided, in one line per topic. Call out any judgment calls the user might have an opinion on. Ask if anything feels wrong. Do not walk through each one individually unless the user flags a concern.
+
+#### Re-flow Protocol
+
+When the user requests a change in any cluster:
+
+1. Acknowledge the change and confirm understanding.
+2. Assess downstream impact — state explicitly which section files are affected, including any downstream files whose rules reference the change.
+3. **Rewrite the affected section files.** Each section lives in its own file under `.groundwork/cache/design-system-draft/`. Use `write_file` to replace the implicated files in turn — for example, a change to the state schema rewrites `03-foundation.md`, and may ripple into `05-surface.md` if skill anatomy or error choreography references the state shape. Each `write_file` is bounded by the size of one section, never the whole spec.
+4. Summarise the re-flow: list every section file that changed and what specifically shifted.
+5. If a previously-approved cluster was affected substantively, re-present it before continuing.
+
+A protocol design system is a web of interconnected decisions. Changing the state schema affects skill anatomy, which affects error choreography. Propagate the change into every section file it implicates — file-by-file, never as a single full-spec rewrite. Isolated edits that ignore downstream effects create internal contradictions that surface during implementation; the propagation is mandatory, the file-at-a-time mechanic is what makes it safe.
+
+#### Walkthrough Progress
+
+Track which clusters have been reviewed in `.groundwork/cache/design-system-cache.md` under the Phase 5 checklist. Mark each cluster as complete when the user approves it.
+
+#### Completion Gate
+
+The walkthrough is complete when all three clusters have been presented and approved. Mark this type's walkthrough done in the cache, then return to the foundation flow — it proceeds to the next active type's translation, or to Phase 6 (Commit) when this is the last.
+
+---
+
+## Commit Contributions
+
+Phase 6 runs once for the whole design system, in the foundation flow. This track contributes:
+
+- **Document section:** the `# Agentic Protocol` section files assembled into `docs/design-system.md`.
+- **Brand tokens:** no Tier 2 block — a protocol has no terminal or visual treatment to project. When this is the only active type, the file is Tier 1: `identity` essentials only (`appName`, a short `wordmark` glyph, `primary` and `accent` colours, and a `voice` descriptor), projected mechanically from the product brief and any palette decisions, so scaffolding can brand the project's `./dev` CLI even though this product is a protocol, not a CLI.
+- **Summary key decisions:** state schema shape, context-injection order, document architecture. Binding constraints include token budgets, naming conventions, agent-parseable structure.
+- **Hand-off content:** rejected protocol-anatomy choices, deferred decisions (versioning policy, multi-skill orchestration), user instincts about agent posture or naming not yet committed.
+
+## Verification Gate
+
+The visual verification loop is medium-general: observe the running artifact in its medium, against intent and reference. For an `agentic-protocol` surface the artifact is the **response payload**, and the same three tiers apply — graphical screenshots are one instance of a wider pattern.
+
+- **Capture:** the protocol response to a representative request, captured by the surface's interface tests.
+- **Tier 1 — does it run:** the request succeeds and the response is well-formed against the contract — deterministic, asserted on structure and status.
+- **Tier 2 — does it read coherently:** the delivery agent reads the captured payload and judges it against this track's response anatomy and naming conventions.
+- **Tier 3 — is it excellent:** response shape and ergonomics graded against the protocol spec and the reference protocols this track names — token economy, parseability, error vocabulary.
+
+This is the lightest-touch instance and its build is deferred; the framing here keeps the gate concept covering all three interface types so no track is silently graphical-only.