harness-everything 0.2.2 → 0.3.6

package/git-commit/references/commit-flow.md

@@ -0,0 +1,30 @@
+# Git Commit — Decision Matrix
+
+Details moved from SKILL.md. Read when you need the full commit execution flow.
+
+## Process & Commit Execution Flow
+
+```mermaid
+flowchart TD
+    Start[Trigger: Commit Request / Task Complete] --> CheckGit{1. Is Git Repo Initialized?}
+    
+    CheckGit -- No --> OfferInit[Prompt User: Run git init or Skip Commit]
+    CheckGit -- Yes --> CheckSubmodules{2. Has Submodule Changes?}
+    
+    CheckSubmodules -- Yes --> CommitSubmodules["Commit Submodules First (Bottom-Up)<br>Consult git-commit/guides/SUBMODULES.md"] --> CheckStatus
+    CheckSubmodules -- No --> CheckStatus[3. Run git status & git diff --cached]
+    
+    CheckStatus --> StagedCheck{4. Are Files Staged?}
+    
+    StagedCheck -- No Staged Files --> AskStage[Prompt User / Stage Targeted Files] --> Format
+    StagedCheck -- Files Staged --> Format[5. Format Angular Commit Message]
+    
+    Format --> CheckShell{6. Shell / Multiline Escaping Check}
+    
+    CheckShell -- Simple Single Line --> DirectCommit["Run git commit -m 'type(scope): subject'"]
+    CheckShell -- Multiline / Windows Shell --> TempFileCommit[Write .git-commit-msg.txt -> Run git commit -F -> Cleanup]
+    
+    DirectCommit --> VerifyCommit[Run git log -1 to Verify]
+    TempFileCommit --> VerifyCommit
+    VerifyCommit --> Done[Commit Complete]
+```

package/grill-me/SKILL.md

@@ -1,36 +1,43 @@
 ---
 name: grill-me
-description: Acts as a relentless challenger to stress-test plans, find loopholes, combat AI sycophancy, and ensure real-time documentation updates.
-author: Miya Daniel | Harness Core Team
-version: 0.2.0
+description: Acts as a relentless challenger to stress-test plans and architectures by interrogating one question at a time, finding loopholes, combating AI sycophancy, updating the CONTEXT.md glossary in real time, and handing off resolved decisions to to-spec for formal specs/ADRs.
+license: Apache-2.0
+metadata:
+  author: Miya Daniel
+  version: 0.3.4
 ---
 
 # Grill Me (Interrogation & Stress Testing)
 
-## 📋 Skill Contract
+A relentless Senior Architect persona that stress-tests plans via one-question-at-a-time interrogation until consensus, then hands off to `to-spec`.
+
+## USE FOR:
+- Stress-test a vague plan or architecture proposal
+- Find loopholes and undefined boundary conditions pre-build
+- Combat AI sycophancy with adversarial questioning
+- Resolve decision-tree ambiguity before spec generation
+
+## DO NOT USE FOR:
+- Implementing code or writing specs (`to-spec`, `tdd`)
+- Ticket breakdown of an approved spec (`to-tickets`)
+- Casual Q&A needing no adversarial challenge
+
+## Skill Contract
 
 | Component | Specification |
 | :--- | :--- |
-| **Trigger / Input** | User proposes a vague plan, asks to "evaluate architecture", or explicitly says "grill me" / "grill with docs". |
-| **Expected Output** | A single-question-at-a-time interrogation loop that resolves every branch of the plan's decision tree, ending in a documented shared understanding. |
-| **State Mutations** | Updates or generates ADR / `CONTEXT.md`-style docs inline as each blind spot is resolved. |
-| **Enforcement Gate** | **MUST** ask exactly one question at a time (listing multiple questions at once is prohibited); **MUST NOT** exit until all decision-tree branches are resolved and documented, then **MUST** hand off to `fable-mode` or `tdd` via `harness-everything`. |
-
-This skill is designed to combat the AI's "Sycophantic" personality and ensure Documentation as Code.
-Triggered when the user proposes a vague plan, asks to "evaluate architecture", or explicitly inputs "grill me" or "grill with docs".
-
-## 1. Persona: The Relentless Challenger
-When this skill is activated, you are no longer an obedient assistant, but a **strict Senior Architect**.
-Your goal is to find loopholes, undefined boundary conditions, and potential performance bottlenecks in the human's plan, while maintaining strict adherence to existing domain models.
-
-## 2. The Grilling Loop
-- **Environment Discovery `[Discover]`**: First, use `read_file` to scan the core code related to the plan. Also read `CONTEXT.md`, `README.md`, or any ADRs under `docs/adr/`.
-- **Domain Language**: Your grilling MUST be based on the domain model and terminology of the project. If the user uses inconsistent terminology, correct them.
-- **Rule of Single Question**: **You MUST only ask one question at a time**. Listing a long questionnaire with 5 questions is STRICTLY PROHIBITED.
-- **Tree Parsing**: Go deep down every branch of the decision tree. Only move to the next blind spot after resolving the current one.
-- **Provide Your Insight**: When asking a question, attach your professional insight.
-- **Real-time Documentation**: Whenever consensus is reached on an architectural blind spot, you MUST immediately update or generate the corresponding Markdown document (e.g., ADR or CONTEXT.md).
-
-## 3. Exit Conditions and Handoff
-- Continue until you and the user reach a **"Shared Understanding with no suspense"**, and all branches of the decision tree are parsed and documented.
-- After finishing, automatically call `harness-everything` to route to subsequent implementation in `fable-mode` (for large plans) or `tdd` (for small features).
+| **Trigger / Input** | Vague plan proposal, "evaluate architecture", or explicit "grill me". |
+| **Expected Output** | Single-question interrogation loop resolving decision-tree branches; handoff to `to-spec` for spec/ADR generation. |
+| **State Mutations** | Updates `CONTEXT.md` glossary inline; delegates document creation to `to-spec`. |
+| **Enforcement Gate** | ONE question at a time; on consensus, invoke `to-spec` to preview & publish spec/ADR docs. |
+
+## Workflow
+
+1. [Discover] Scan plan-related code plus `CONTEXT.md`, `README.md`, ADRs under `docs/adr/`.
+2. Grill strictly using the project's domain model and terminology.
+3. Ask exactly ONE question at a time (questionnaires prohibited); attach your insight; resolve each branch before moving on.
+4. Update `CONTEXT.md` glossary inline as terms resolve.
+5. On consensus, hand off to `to-spec/SKILL.md` to preview the outline and publish (PRD, CLI/API reference, Schema doc, or ADR).
+6. Route execution: `to-tickets`, `fable-mode`, or `tdd`.
+
+Deep dive: references/grilling-playbook.md

package/grill-me/references/grilling-playbook.md

@@ -0,0 +1,38 @@
+# Grilling Playbook (Deep Dive)
+
+## Decision Flow
+
+```mermaid
+flowchart TD
+    Start[Trigger: Grill Me / Evaluate Plan] --> Discovery[1. Scan Related Code & Existing ADRs]
+    Discovery --> Loop[2. Ask Exactly ONE Question at a Time]
+    
+    Loop --> Answer[Receive Answer & Resolve Decision Branch]
+    Answer --> UpdateGlossary[Update CONTEXT.md Glossary Inline if Term Resolves]
+    UpdateGlossary --> MoreBranches{3. Unresolved Decision Branches Remain?}
+    
+    MoreBranches -- Yes --> Loop
+    MoreBranches -- No (Consensus Reached) --> ToSpec[4. Hand off to to-spec for Outline Preview & Spec/ADR Publishing]
+    
+    ToSpec --> Execution[5. Route to to-tickets / fable-mode / tdd via harness-everything]
+```
+
+## 1. Persona: The Relentless Challenger
+
+When this skill is activated, you are no longer an obedient assistant, but a **strict Senior Architect**.
+Your goal is to find loopholes, undefined boundary conditions, and potential performance bottlenecks in the human's plan, while maintaining strict adherence to existing domain models.
+
+## 2. The Grilling Loop
+
+- **Environment Discovery `[Discover]`**: First, use `read_file` to scan the core code related to the plan. Also read `CONTEXT.md`, `README.md`, or any ADRs under `docs/adr/`.
+- **Domain Language**: Your grilling MUST be based on the domain model and terminology of the project. If the user uses inconsistent terminology, correct them.
+- **Rule of Single Question**: **You MUST only ask one question at a time**. Listing a long questionnaire with 5 questions is STRICTLY PROHIBITED.
+- **Tree Parsing**: Go deep down every branch of the decision tree. Only move to the next blind spot after resolving the current one.
+- **Provide Your Insight**: When asking a question, attach your professional insight.
+- **Real-time Glossary & Spec Handoff**: As domain terms and blind spots resolve, update `CONTEXT.md` (glossary) inline. Once the interrogation concludes with a full consensus, hand off to `to-spec` to preview the outline and publish the formal specification document (PRD, CLI/API reference, Schema doc, or ADR).
+
+## 3. Exit Conditions and Handoff
+
+- Continue until you and the user reach a **"Shared Understanding with no suspense"**, and all branches of the decision tree are parsed and resolved.
+- **Handoff to Specification (`to-spec`)**: Once grilling concludes and all decision-tree branches are resolved, **MUST** hand off to `to-spec/SKILL.md` to synthesize the conversation into an outline preview and publish the corresponding document (PRD, CLI reference, Schema doc, or ADR) using `to-spec`'s path resolution flow.
+- **Handoff to Execution**: After `to-spec` publishes the specification, route to `to-tickets` (for ticket breakdown), `fable-mode` (for macro scaffolding), or `tdd` (for feature implementation).

package/grill-with-docs/ADR-FORMAT.md

@@ -1,47 +1,47 @@
-# ADR Format
-
-ADRs live in `docs/adr/` and use sequential numbering: `0001-slug.md`, `0002-slug.md`, etc.
-
-Create the `docs/adr/` directory lazily — only when the first ADR is needed.
-
-## Template
-
-```md
-# {Short title of the decision}
-
-{1-3 sentences: what's the context, what did we decide, and why.}
-```
-
-That's it. An ADR can be a single paragraph. The value is in recording *that* a decision was made and *why* — not in filling out sections.
-
-## Optional sections
-
-Only include these when they add genuine value. Most ADRs won't need them.
-
-- **Status** frontmatter (`proposed | accepted | deprecated | superseded by ADR-NNNN`) — useful when decisions are revisited
-- **Considered Options** — only when the rejected alternatives are worth remembering
-- **Consequences** — only when non-obvious downstream effects need to be called out
-
-## Numbering
-
-Scan `docs/adr/` for the highest existing number and increment by one.
-
-## When to offer an ADR
-
-All three of these must be true:
-
-1. **Hard to reverse** — the cost of changing your mind later is meaningful
-2. **Surprising without context** — a future reader will look at the code and wonder "why on earth did they do it this way?"
-3. **The result of a real trade-off** — there were genuine alternatives and you picked one for specific reasons
-
-If a decision is easy to reverse, skip it — you'll just reverse it. If it's not surprising, nobody will wonder why. If there was no real alternative, there's nothing to record beyond "we did the obvious thing."
-
-### What qualifies
-
-- **Architectural shape.** "We're using a monorepo." "The write model is event-sourced, the read model is projected into Postgres."
-- **Integration patterns between contexts.** "Ordering and Billing communicate via domain events, not synchronous HTTP."
-- **Technology choices that carry lock-in.** Database, message bus, auth provider, deployment target. Not every library — just the ones that would take a quarter to swap out.
-- **Boundary and scope decisions.** "Customer data is owned by the Customer context; other contexts reference it by ID only." The explicit no-s are as valuable as the yes-s.
-- **Deliberate deviations from the obvious path.** "We're using manual SQL instead of an ORM because X." Anything where a reasonable reader would assume the opposite. These stop the next engineer from "fixing" something that was deliberate.
-- **Constraints not visible in the code.** "We can't use AWS because of compliance requirements." "Response times must be under 200ms because of the partner API contract."
-- **Rejected alternatives when the rejection is non-obvious.** If you considered GraphQL and picked REST for subtle reasons, record it — otherwise someone will suggest GraphQL again in six months.
+# ADR Format
+
+ADRs live in `docs/adr/` and use sequential numbering: `0001-slug.md`, `0002-slug.md`, etc.
+
+Create the `docs/adr/` directory lazily — only when the first ADR is needed.
+
+## Template
+
+```md
+# {Short title of the decision}
+
+{1-3 sentences: what's the context, what did we decide, and why.}
+```
+
+That's it. An ADR can be a single paragraph. The value is in recording *that* a decision was made and *why* — not in filling out sections.
+
+## Optional sections
+
+Only include these when they add genuine value. Most ADRs won't need them.
+
+- **Status** frontmatter (`proposed | accepted | deprecated | superseded by ADR-NNNN`) — useful when decisions are revisited
+- **Considered Options** — only when the rejected alternatives are worth remembering
+- **Consequences** — only when non-obvious downstream effects need to be called out
+
+## Numbering
+
+Scan `docs/adr/` for the highest existing number and increment by one.
+
+## When to offer an ADR
+
+All three of these must be true:
+
+1. **Hard to reverse** — the cost of changing your mind later is meaningful
+2. **Surprising without context** — a future reader will look at the code and wonder "why on earth did they do it this way?"
+3. **The result of a real trade-off** — there were genuine alternatives and you picked one for specific reasons
+
+If a decision is easy to reverse, skip it — you'll just reverse it. If it's not surprising, nobody will wonder why. If there was no real alternative, there's nothing to record beyond "we did the obvious thing."
+
+### What qualifies
+
+- **Architectural shape.** "We're using a monorepo." "The write model is event-sourced, the read model is projected into Postgres."
+- **Integration patterns between contexts.** "Ordering and Billing communicate via domain events, not synchronous HTTP."
+- **Technology choices that carry lock-in.** Database, message bus, auth provider, deployment target. Not every library — just the ones that would take a quarter to swap out.
+- **Boundary and scope decisions.** "Customer data is owned by the Customer context; other contexts reference it by ID only." The explicit no-s are as valuable as the yes-s.
+- **Deliberate deviations from the obvious path.** "We're using manual SQL instead of an ORM because X." Anything where a reasonable reader would assume the opposite. These stop the next engineer from "fixing" something that was deliberate.
+- **Constraints not visible in the code.** "We can't use AWS because of compliance requirements." "Response times must be under 200ms because of the partner API contract."
+- **Rejected alternatives when the rejection is non-obvious.** If you considered GraphQL and picked REST for subtle reasons, record it — otherwise someone will suggest GraphQL again in six months.

package/grill-with-docs/CONTEXT-FORMAT.md

@@ -1,63 +1,63 @@
-# CONTEXT.md Format
-
-## Structure
-
-```md
-# {Context Name}
-
-{One or two sentence description of what this context is and why it exists.}
-
-## Language
-
-**Order**:
-{A one or two sentence description of the term}
-_Avoid_: Purchase, transaction
-
-**Invoice**:
-A request for payment sent to a customer after delivery.
-_Avoid_: Bill, payment request
-
-**Customer**:
-A person or organization that places orders.
-_Avoid_: Client, buyer, account
-```
-
-## Rules
-
-- **Be opinionated.** When multiple words exist for the same concept, pick the best one and list the others as aliases to avoid.
-- **Flag conflicts explicitly.** If a term is used ambiguously, call it out in "Flagged ambiguities" with a clear resolution.
-- **Keep definitions tight.** One or two sentences max. Define what it IS, not what it does.
-- **Show relationships.** Use bold term names and express cardinality where obvious.
-- **Only include terms specific to this project's context.** General programming concepts (timeouts, error types, utility patterns) don't belong even if the project uses them extensively. Before adding a term, ask: is this a concept unique to this context, or a general programming concept? Only the former belongs.
-- **Group terms under subheadings** when natural clusters emerge. If all terms belong to a single cohesive area, a flat list is fine.
-- **Write an example dialogue.** A conversation between a dev and a domain expert that demonstrates how the terms interact naturally and clarifies boundaries between related concepts.
-
-## Single vs multi-context repos
-
-**Single context (most repos):** One `CONTEXT.md` at the repo root.
-
-**Multiple contexts:** A `CONTEXT-MAP.md` at the repo root lists the contexts, where they live, and how they relate to each other:
-
-```md
-# Context Map
-
-## Contexts
-
-- [Ordering](./src/ordering/CONTEXT.md) — receives and tracks customer orders
-- [Billing](./src/billing/CONTEXT.md) — generates invoices and processes payments
-- [Fulfillment](./src/fulfillment/CONTEXT.md) — manages warehouse picking and shipping
-
-## Relationships
-
-- **Ordering → Fulfillment**: Ordering emits `OrderPlaced` events; Fulfillment consumes them to start picking
-- **Fulfillment → Billing**: Fulfillment emits `ShipmentDispatched` events; Billing consumes them to generate invoices
-- **Ordering ↔ Billing**: Shared types for `CustomerId` and `Money`
-```
-
-The skill infers which structure applies:
-
-- If `CONTEXT-MAP.md` exists, read it to find contexts
-- If only a root `CONTEXT.md` exists, single context
-- If neither exists, create a root `CONTEXT.md` lazily when the first term is resolved
-
-When multiple contexts exist, infer which one the current topic relates to. If unclear, ask.
+# CONTEXT.md Format
+
+## Structure
+
+```md
+# {Context Name}
+
+{One or two sentence description of what this context is and why it exists.}
+
+## Language
+
+**Order**:
+{A one or two sentence description of the term}
+_Avoid_: Purchase, transaction
+
+**Invoice**:
+A request for payment sent to a customer after delivery.
+_Avoid_: Bill, payment request
+
+**Customer**:
+A person or organization that places orders.
+_Avoid_: Client, buyer, account
+```
+
+## Rules
+
+- **Be opinionated.** When multiple words exist for the same concept, pick the best one and list the others as aliases to avoid.
+- **Flag conflicts explicitly.** If a term is used ambiguously, call it out in "Flagged ambiguities" with a clear resolution.
+- **Keep definitions tight.** One or two sentences max. Define what it IS, not what it does.
+- **Show relationships.** Use bold term names and express cardinality where obvious.
+- **Only include terms specific to this project's context.** General programming concepts (timeouts, error types, utility patterns) don't belong even if the project uses them extensively. Before adding a term, ask: is this a concept unique to this context, or a general programming concept? Only the former belongs.
+- **Group terms under subheadings** when natural clusters emerge. If all terms belong to a single cohesive area, a flat list is fine.
+- **Write an example dialogue.** A conversation between a dev and a domain expert that demonstrates how the terms interact naturally and clarifies boundaries between related concepts.
+
+## Single vs multi-context repos
+
+**Single context (most repos):** One `CONTEXT.md` at the repo root.
+
+**Multiple contexts:** A `CONTEXT-MAP.md` at the repo root lists the contexts, where they live, and how they relate to each other:
+
+```md
+# Context Map
+
+## Contexts
+
+- [Ordering](./src/ordering/CONTEXT.md) — receives and tracks customer orders
+- [Billing](./src/billing/CONTEXT.md) — generates invoices and processes payments
+- [Fulfillment](./src/fulfillment/CONTEXT.md) — manages warehouse picking and shipping
+
+## Relationships
+
+- **Ordering → Fulfillment**: Ordering emits `OrderPlaced` events; Fulfillment consumes them to start picking
+- **Fulfillment → Billing**: Fulfillment emits `ShipmentDispatched` events; Billing consumes them to generate invoices
+- **Ordering ↔ Billing**: Shared types for `CustomerId` and `Money`
+```
+
+The skill infers which structure applies:
+
+- If `CONTEXT-MAP.md` exists, read it to find contexts
+- If only a root `CONTEXT.md` exists, single context
+- If neither exists, create a root `CONTEXT.md` lazily when the first term is resolved
+
+When multiple contexts exist, infer which one the current topic relates to. If unclear, ask.

package/grill-with-docs/SKILL.md

@@ -1,99 +1,41 @@
 ---
 name: grill-with-docs
-description: Grilling session that challenges your plan against the existing domain model, sharpens terminology, and updates documentation (CONTEXT.md, ADRs) inline as decisions crystallise. Use when user wants to stress-test a plan against their project's language and documented decisions.
-author: Miya Daniel | Harness Core Team
-version: 0.2.0
+description: Challenge the plan against the existing domain model, sharpen terminology, and update CONTEXT.md and ADRs inline as decisions crystallise; use when stress-testing a plan against documented language and decisions.
+license: Apache-2.0
+metadata:
+  author: Miya Daniel
+  version: 0.3.4
 ---
 
+# Grill With Docs (Domain Modeling & Architectural Alignment)
+
+Interview the design tree one question at a time with recommended answers; explore the codebase instead of asking.
+
 ## 📋 Skill Contract
 
 | Component | Specification |
 | :--- | :--- |
-| **Trigger / Input** | User wants to stress-test a plan against the project's existing domain language and documented decisions (`CONTEXT.md`, ADRs). |
-| **Expected Output** | A one-question-at-a-time interview walking the design tree to resolution; `CONTEXT.md` updated inline as terms resolve; new ADRs created only when a decision is hard-to-reverse, surprising, and a genuine trade-off. |
-| **State Mutations** | Creates/edits `CONTEXT.md` and `docs/adr/*.md` (or the per-context equivalents under a `CONTEXT-MAP.md` layout). |
-| **Enforcement Gate** | `CONTEXT.md` **MUST** stay a pure glossary — no implementation details. An ADR **MUST NOT** be offered unless all three criteria (hard to reverse, surprising without context, real trade-off) hold. |
-
-<what-to-do>
-
-Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.
-
-Ask the questions one at a time, waiting for feedback on each question before continuing.
-
-If a question can be answered by exploring the codebase, explore the codebase instead.
-
-</what-to-do>
-
-<supporting-info>
-
-## Domain awareness
-
-During codebase exploration, also look for existing documentation:
-
-### File structure
-
-Most repos have a single context:
-
-```
-/
-├── CONTEXT.md
-├── docs/
-│   └── adr/
-│       ├── 0001-event-sourced-orders.md
-│       └── 0002-postgres-for-write-model.md
-└── src/
-```
-
-If a `CONTEXT-MAP.md` exists at the root, the repo has multiple contexts. The map points to where each one lives:
-
-```
-/
-├── CONTEXT-MAP.md
-├── docs/
-│   └── adr/                          ← system-wide decisions
-├── src/
-│   ├── ordering/
-│   │   ├── CONTEXT.md
-│   │   └── docs/adr/                 ← context-specific decisions
-│   └── billing/
-│       ├── CONTEXT.md
-│       └── docs/adr/
-```
-
-Create files lazily — only when you have something to write. If no `CONTEXT.md` exists, create one when the first term is resolved. If no `docs/adr/` exists, create it when the first ADR is needed.
-
-## During the session
-
-### Challenge against the glossary
-
-When the user uses a term that conflicts with the existing language in `CONTEXT.md`, call it out immediately. "Your glossary defines 'cancellation' as X, but you seem to mean Y — which is it?"
-
-### Sharpen fuzzy language
-
-When the user uses vague or overloaded terms, propose a precise canonical term. "You're saying 'account' — do you mean the Customer or the User? Those are different things."
-
-### Discuss concrete scenarios
-
-When domain relationships are being discussed, stress-test them with specific scenarios. Invent scenarios that probe edge cases and force the user to be precise about the boundaries between concepts.
-
-### Cross-reference with code
-
-When the user states how something works, check whether the code agrees. If you find a contradiction, surface it: "Your code cancels entire Orders, but you just said partial cancellation is possible — which is right?"
-
-### Update CONTEXT.md inline
-
-When a term is resolved, update `CONTEXT.md` right there. Don't batch these up — capture them as they happen. Use the format in [CONTEXT-FORMAT.md](./CONTEXT-FORMAT.md).
-
-`CONTEXT.md` should be totally devoid of implementation details. Do not treat `CONTEXT.md` as a spec, a scratch pad, or a repository for implementation decisions. It is a glossary and nothing else.
-
-### Offer ADRs sparingly
-
-Only offer to create an ADR when all three are true:
-
-1. **Hard to reverse** — the cost of changing your mind later is meaningful
-2. **Surprising without context** — a future reader will wonder "why did they do it this way?"
-3. **The result of a real trade-off** — there were genuine alternatives and you picked one for specific reasons
-
-If any of the three is missing, skip the ADR. Use the format in [ADR-FORMAT.md](./ADR-FORMAT.md).
-
-</supporting-info>
+| **Trigger / Input** | Stress-testing a plan against domain language and documented decisions. |
+| **Expected Output** | Structured interview; inline `CONTEXT.md` updates; ADR handoff. |
+| **State Mutations** | Writes `CONTEXT.md` and ADRs at resolved locations. |
+| **Enforcement Gate** | Pure glossary; ADRs meet the 3-part bar; hand to `to-spec` after. |
+
+## Workflow
+
+1. Resolve storage (root `CONTEXT-MAP.md` wins); else `node "to-spec/scripts/check-project-docs.js" check` or inspect `docs/adr/` / `docs/`; else `.github/harness-everything/adr/` (or `.claude/…`, `.cursor/…`). Formats: [CONTEXT-FORMAT.md](./CONTEXT-FORMAT.md) · [ADR-FORMAT.md](./ADR-FORMAT.md)
+2. Challenge glossary conflicts; sharpen fuzzy terms to canonical ones.
+3. Stress-test relationships with concrete scenarios; cross-check claims against code.
+4. Update `CONTEXT.md` inline, never batch; zero implementation details.
+5. Offer an ADR only if hard to reverse + surprising without context + a real trade-off.
+6. Hand off: unverified design → `grill-me`; aligned → `to-spec/SKILL.md` publishes; execution → `to-tickets`/`fable-mode`/`tdd`.
+
+Deep dive: references/session-playbook.md
+
+## USE FOR:
+- stress-testing plans against the domain model
+- resolving fuzzy domain terminology
+- capturing decisions into CONTEXT.md/ADRs inline
+
+## DO NOT USE FOR:
+- verifying unstable designs (`grill-me`)
+- spec publishing without a grilling pass

package/grill-with-docs/references/session-playbook.md

@@ -0,0 +1,97 @@
+# Grill With Docs — Full Session Playbook
+
+## Decision Flow
+
+```mermaid
+flowchart TD
+    Start[Trigger: Stress-test Plan against Domain Model] --> Scan[1. Scan Codebase, CONTEXT.md & Existing ADRs]
+    Scan --> Frontier[2. Calculate Frontier & Ask Questions]
+
+    Frontier --> Answer[Receive Answer & Resolve Domain Term]
+    Answer --> UpdateGlossary[3. Update CONTEXT.md Glossary Inline]
+
+    UpdateGlossary --> CheckADR{4. Hard-to-reverse Trade-off Decision Reached?}
+
+    CheckADR -- Yes --> ResolvePath{Resolve ADR Storage Path}
+    CheckADR -- No --> CheckMore
+
+    ResolvePath -- projectDocs / docs/adr Exists --> WriteMain[Write to docs/adr/ or CONTEXT-MAP.md Location]
+    ResolvePath -- No Folder Found --> WritePlatform[Write to .github/harness-everything/adr/ or Delegate to to-spec]
+
+    WriteMain --> CheckMore{5. All Design Tree Branches Resolved?}
+    WritePlatform --> CheckMore
+
+    CheckMore -- Unresolved Branches Remain --> Frontier
+    CheckMore -- All Branches Resolved --> ToSpec[6. Hand off to to-spec for Outline Preview & Spec/ADR Publishing]
+
+    ToSpec --> Execution[7. Route to to-tickets / fable-mode / tdd via harness-everything]
+```
+
+## Core interview prompt
+
+Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.
+
+Ask the questions one at a time, waiting for feedback on each question before continuing.
+
+If a question can be answered by exploring the codebase, explore the codebase instead.
+
+## Dynamic storage resolution & file structure
+
+Inspect the workspace and resolve document locations dynamically:
+
+1. **Monorepo / Multi-Context**: If `CONTEXT-MAP.md` exists at the root, follow its context-specific mapping.
+2. **Project Configured / Inferred Location**: Run `node "to-spec/scripts/check-project-docs.js" check` or inspect if `docs/adr/` or `docs/` exists in the workspace.
+3. **Platform Fallback**: If no documentation directory exists, write ADRs under `.github/harness-everything/adr/` (or `.claude/harness-everything/adr/`, `.cursor/harness-everything/adr/`), or delegate formal document generation to `to-spec`.
+
+```
+/
+├── CONTEXT.md                        ← Primary domain glossary
+├── docs/                             ← Default documentation root
+│   └── adr/                          ← System-wide ADR decisions
+│       ├── 0001-event-sourced-orders.md
+│       └── 0002-postgres-for-write-model.md
+└── .github/harness-everything/adr/   ← Fallback ADR storage if workspace has no docs/ directory
+```
+
+Create files lazily — only when you have resolved terms or ADRs to write.
+
+## Session techniques in full
+
+### Challenge against the glossary
+
+When the user uses a term that conflicts with the existing language in `CONTEXT.md`, call it out immediately. "Your glossary defines 'cancellation' as X, but you seem to mean Y — which is it?"
+
+### Sharpen fuzzy language
+
+When the user uses vague or overloaded terms, propose a precise canonical term. "You're saying 'account' — do you mean the Customer or the User? Those are different things."
+
+### Discuss concrete scenarios
+
+When domain relationships are being discussed, stress-test them with specific scenarios. Invent scenarios that probe edge cases and force the user to be precise about the boundaries between concepts.
+
+### Cross-reference with code
+
+When the user states how something works, check whether the code agrees. If you find a contradiction, surface it: "Your code cancels entire Orders, but you just said partial cancellation is possible — which is right?"
+
+### Update CONTEXT.md inline
+
+When a term is resolved, update `CONTEXT.md` right there. Don't batch these up — capture them as they happen. Use the format in [CONTEXT-FORMAT.md](../CONTEXT-FORMAT.md).
+
+`CONTEXT.md` should be totally devoid of implementation details. Do not treat `CONTEXT.md` as a spec, a scratch pad, or a repository for implementation decisions. It is a glossary and nothing else.
+
+### Offer ADRs sparingly
+
+Only offer to create an ADR when all three are true:
+
+1. **Hard to reverse** — the cost of changing your mind later is meaningful
+2. **Surprising without context** — a future reader will wonder "why did they do it this way?"
+3. **The result of a real trade-off** — there were genuine alternatives and you picked one for specific reasons
+
+If any of the three is missing, skip the ADR. Use the format in [ADR-FORMAT.md](../ADR-FORMAT.md).
+
+## Handoffs in full
+
+1. **Pre-flight**: If the core proposal is highly vague or its technical robustness (SRE, security, locks, concurrency, fail-safes) is unverified, recommend the user run `grill-me` first. Do not attempt to align a glossary for a broken or unstable design.
+2. **Transition**: Once technical issues are hardened in `grill-me`, transition here to solidify domain terms and record architectural choices.
+3. **Downstream Specification Handoff**: Once alignment is complete and domain terms are updated, hand off to `to-spec/SKILL.md` to present an outline preview and publish the formal specification document or ADR.
+4. **Execution Handoff**: Route to `to-tickets` (for ticket decomposition), `fable-mode` (for macro scaffolding), or `tdd` (for feature implementation) via `harness-everything`.