harness-everything 0.2.1 → 0.3.6

package/git-commit/guides/ANGULAR_STYLE.md

@@ -1,61 +1,61 @@
-# Angular-Style Conventional Commits
-
-**[State Checkpoint]**
-- MUST verify the target language determined by Language Detection.
-
-## Commit Message Format
-
-```text
-<type>(<scope>): <subject>
-
-<body>
-
-<footer>
-```
-
-## Field Definitions
-
-1. **Type**: MUST be exactly one of: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`.
-   - MUST use `style` or `chore` for trivial/formatting changes.
-2. **Scope**: MUST enclose in parentheses if used.
-   - For Sub Repos: MUST use the Sub Repo name.
-   - For Code: MUST use a concise, high-level module name (e.g., `auth`, `ui`). MUST NOT use file paths.
-3. **Subject**: MUST use imperative mood, present tense, maximum 50 characters, NO trailing period. MUST be in the target language.
-4. **Body**: MUST describe motivation and context, and MUST analyze the staged changes to list the exact modifications in a clear, structured bulleted list.
-   - MUST analyze the `git diff --cached` output to extract the specific files, functions, or logic modified.
-   - MUST list each major change or file-level modification with a brief description of "what was changed" (e.g., `- Updated user schema to support OAuth IDs in src/models/user.ts`).
-   - MUST NOT separate bullet points with blank lines.
-   - MUST NOT artificially wrap lines.
-   - MUST be in the target language.
-5. **Footer**: MUST prefix breaking changes with `BREAKING CHANGE:`. MUST reference issues via `Closes #<id>`.
-
-## Code Change Output Example
-
-```text
-feat(auth): add OAuth2 login support
-
-Core intent: Allows users to sign in using Google and GitHub to simplify user authentication.
-
-Changes:
-- Added OAuth2 client config schema and defaults in `config/auth.ts`
-- Implemented OAuth2 middleware verification pipeline in `src/middleware/oauth.ts`
-- Updated user database model to store external provider IDs in `src/models/user.ts`
-- Added comprehensive integration tests for external provider flows in `tests/auth.test.ts`
-```
-
-## Submodule Update Output Example
-
-```text
-chore(ui): update ui submodule
-
-Core intent: Introduces dark mode support and resolves various UI layout issues.
-
-Included commits:
-- fix: align button text
-- feat: add dark mode
-- style: update primary color hex
-- fix: resolve layout shift on mobile
-```
-- style: update primary color hex
-- fix: resolve layout shift on mobile
+# Angular-Style Conventional Commits
+
+**[State Checkpoint]**
+- MUST verify the target language determined by Language Detection.
+
+## Commit Message Format
+
+```text
+<type>(<scope>): <subject>
+
+<body>
+
+<footer>
+```
+
+## Field Definitions
+
+1. **Type**: MUST be exactly one of: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`.
+   - MUST use `style` or `chore` for trivial/formatting changes.
+2. **Scope**: MUST enclose in parentheses if used.
+   - For Sub Repos: MUST use the Sub Repo name.
+   - For Code: MUST use a concise, high-level module name (e.g., `auth`, `ui`). MUST NOT use file paths.
+3. **Subject**: MUST use imperative mood, present tense, maximum 50 characters, NO trailing period. MUST be in the target language.
+4. **Body**: MUST describe motivation and context, and MUST analyze the staged changes to list the exact modifications in a clear, structured bulleted list.
+   - MUST analyze the `git diff --cached` output to extract the specific files, functions, or logic modified.
+   - MUST list each major change or file-level modification with a brief description of "what was changed" (e.g., `- Updated user schema to support OAuth IDs in src/models/user.ts`).
+   - MUST NOT separate bullet points with blank lines.
+   - MUST NOT artificially wrap lines.
+   - MUST be in the target language.
+5. **Footer**: MUST prefix breaking changes with `BREAKING CHANGE:`. MUST reference issues via `Closes #<id>`.
+
+## Code Change Output Example
+
+```text
+feat(auth): add OAuth2 login support
+
+Core intent: Allows users to sign in using Google and GitHub to simplify user authentication.
+
+Changes:
+- Added OAuth2 client config schema and defaults in `config/auth.ts`
+- Implemented OAuth2 middleware verification pipeline in `src/middleware/oauth.ts`
+- Updated user database model to store external provider IDs in `src/models/user.ts`
+- Added comprehensive integration tests for external provider flows in `tests/auth.test.ts`
+```
+
+## Submodule Update Output Example
+
+```text
+chore(ui): update ui submodule
+
+Core intent: Introduces dark mode support and resolves various UI layout issues.
+
+Included commits:
+- fix: align button text
+- feat: add dark mode
+- style: update primary color hex
+- fix: resolve layout shift on mobile
+```
+- style: update primary color hex
+- fix: resolve layout shift on mobile
 ```

package/git-commit/guides/COMMIT_GENERATION.md

@@ -1,24 +1,24 @@
-# Commit Generation Workflow
-
-**[State Checkpoint]**
-- MUST verify the target repository path passed from the previous step.
-- MUST ensure terminal is located in the target repository BEFORE generating commits.
-- MUST explicitly recall diff content and any provided Sub Repo logs.
-
-## [Preparation Phase]
-1. Language Selection: MUST execute `LANGUAGE_DETECTION.md`.
-2. Format Rules: MUST read and strictly follow `ANGULAR_STYLE.md`.
-
-## [Action Phase]
-3. Message Construction: MUST generate a strict Angular format message (Type, Scope, Subject, Body, Footer) integrating diff analysis.
-   - MUST perform a detailed analysis on `git diff --cached` to extract the exact files modified, functions/classes added or adjusted, and logical configuration changes.
-   - MUST compile these extracted points into a structured, bulleted list in the commit message body (e.g., listing changes file-by-file or feature-by-feature) so that the commit message serves as an accurate, self-contained changelog of the staged changes.
-4. Context Integration: IF Sub Repo logs were passed, MUST seamlessly integrate ALL Sub Repo log summaries into the commit body.
-5. State Isolation: MUST ignore unstaged changes AND MUST NOT run `git add` to prevent contamination.
-6. Execution: MUST execute the commit securely (e.g., `git commit -F - <<EOF` or writing to a temporary file) to ensure special characters do not break the terminal command.
-
-## [Validation & Summarize Phase]
-7. Error Handling: MUST verify if the commit command succeeded. IF it fails (e.g., pre-commit hooks, GPG), MUST NOT blindly halt. MUST diagnose the error, preserve the generated message in a temporary file, and pause to ask the user for remediation.
-
-## [Record: Handoff]
+# Commit Generation Workflow
+
+**[State Checkpoint]**
+- MUST verify the target repository path passed from the previous step.
+- MUST ensure terminal is located in the target repository BEFORE generating commits.
+- MUST explicitly recall diff content and any provided Sub Repo logs.
+
+## [Preparation Phase]
+1. Language Selection: MUST execute `LANGUAGE_DETECTION.md`.
+2. Format Rules: MUST read and strictly follow `ANGULAR_STYLE.md`.
+
+## [Action Phase]
+3. Message Construction: MUST generate a strict Angular format message (Type, Scope, Subject, Body, Footer) integrating diff analysis.
+   - MUST perform a detailed analysis on `git diff --cached` to extract the exact files modified, functions/classes added or adjusted, and logical configuration changes.
+   - MUST compile these extracted points into a structured, bulleted list in the commit message body (e.g., listing changes file-by-file or feature-by-feature) so that the commit message serves as an accurate, self-contained changelog of the staged changes.
+4. Context Integration: IF Sub Repo logs were passed, MUST seamlessly integrate ALL Sub Repo log summaries into the commit body.
+5. State Isolation: MUST ignore unstaged changes AND MUST NOT run `git add` to prevent contamination.
+6. Execution: MUST execute the commit securely (e.g., `git commit -F - <<EOF` or writing to a temporary file) to ensure special characters do not break the terminal command.
+
+## [Validation & Summarize Phase]
+7. Error Handling: MUST verify if the commit command succeeded. IF it fails (e.g., pre-commit hooks, GPG), MUST NOT blindly halt. MUST diagnose the error, preserve the generated message in a temporary file, and pause to ask the user for remediation.
+
+## [Record: Handoff]
 8. Handoff: MUST record the successful commit log summary and return control with updated state to the calling workflow.

package/git-commit/guides/LANGUAGE_DETECTION.md

@@ -1,16 +1,16 @@
-# Language Detection Workflow
-
-**[State Checkpoint]**
-- MUST verify terminal access to the target repository.
-
-## [Discovery Phase]
-1. Memory Check: MUST read `/memories/git-commit-prefs.md` for a cached target language.
-
-## [Evaluation Phase]
-2. Sampling: IF memory cache is missing, MUST run `git log -n 5` securely to sample recent commit languages.
-3. Language Determination:
-   - IF a non-English language is detected dominantly in recent commits, MUST update `/memories/git-commit-prefs.md` with this language.
-   - OTHERWISE, MUST default to English.
-
-## [Record: Handoff]
-4. Handoff: MUST record the determined target language into the state context and return control to the Commit Generation workflow.
+# Language Detection Workflow
+
+**[State Checkpoint]**
+- MUST verify terminal access to the target repository.
+
+## [Discovery Phase]
+1. Memory Check: MUST read the resolved Harness memory file `git-commit-prefs.md` for a cached target language. Prefer an existing `MEMORY.md`/`RULES.md`; otherwise use `.github/harness-everything/memories/git-commit-prefs.md`.
+
+## [Evaluation Phase]
+2. Sampling: IF memory cache is missing, MUST run `git log -n 5` securely to sample recent commit languages.
+3. Language Determination:
+   - IF a non-English language is detected dominantly in recent commits, MUST update the resolved Harness memory file with this language.
+   - OTHERWISE, MUST default to English.
+
+## [Record: Handoff]
+4. Handoff: MUST record the determined target language into the state context and return control to the Commit Generation workflow.

package/git-commit/guides/MAIN_REPO.md

@@ -1,15 +1,15 @@
-# Main Repo Processing Workflow
-
-**[State Checkpoint]**
-- MUST verify terminal is located at the Main Repo root.
-- MUST acknowledge and retrieve any completed Sub Repo updates passed down from the previous phase.
-
-## [Elimination Phase]
-1. Diff Analysis: MUST analyze `git diff --cached` securely to identify staged changes (including Sub Repo pointer updates).
-2. Validation: IF no staged changes exist, MUST declare success and terminate workflow without further action.
-
-## [Summarize Phase]
-3. Context Gathering: IF Sub Repo pointer updates exist, MUST extract their commit logs (e.g., via `git log --oneline <old>..<new>`) to serve as context for the Main Repo commit.
-
-## [Action Phase]
+# Main Repo Processing Workflow
+
+**[State Checkpoint]**
+- MUST verify terminal is located at the Main Repo root.
+- MUST acknowledge and retrieve any completed Sub Repo updates passed down from the previous phase.
+
+## [Elimination Phase]
+1. Diff Analysis: MUST analyze `git diff --cached` securely to identify staged changes (including Sub Repo pointer updates).
+2. Validation: IF no staged changes exist, MUST declare success and terminate workflow without further action.
+
+## [Summarize Phase]
+3. Context Gathering: IF Sub Repo pointer updates exist, MUST extract their commit logs (e.g., via `git log --oneline <old>..<new>`) to serve as context for the Main Repo commit.
+
+## [Action Phase]
 4. Commit Generation: MUST explicitly pass the verified diff and extracted Sub Repo logs as context, then execute `COMMIT_GENERATION.md`.

package/git-commit/guides/SUBMODULES.md

@@ -1,27 +1,27 @@
-# Submodule Processing Workflow
-
-**[State Checkpoint]**
-- MUST verify the Main Repo absolute path transferred from the previous step.
-- MUST ensure terminal is located at the Main Repo root BEFORE beginning discovery.
-
-## [Discovery Phase]
-1. Deep Discovery: MUST run `git submodule status --recursive` to find all Sub Repos.
-
-## [Elimination Phase]
-2. Evaluation: For EACH Sub Repo, MUST run `git diff --cached` securely to check for staged changes. IF NO staged changes exist, MUST eliminate from target list.
-
-## [Execution Phase]
-3. Generation: For Sub Repos WITH staged changes, MUST execute `COMMIT_GENERATION.md`.
-4. Validation: MUST verify generation success. IF ANY Sub Repo has remaining staged changes, MUST diagnose failure and halt.
-
-## [Indexing Phase]
-5. Preference Check: MUST read `/memories/git-commit-prefs.md` for `auto_stage_submodules` setting.
-6. Execution:
-   - IF `auto_stage_submodules=true`: MUST run `git add <path>` in the Main Repo for all updated Sub Repos.
-   - IF missing: MUST prompt user exactly: "[1] Yes, [2] No, [3] Yes & Always allow".
-   - IF user selects [3]: MUST write `auto_stage_submodules=true` to `/memories/git-commit-prefs.md` AND run `git add <path>`.
-   - IF user selects [1]: MUST run `git add <path>` in the Main Repo.
-   - IF user selects [2]: MUST NOT run `git add`.
-
-## [State Handoff]
-7. Handoff: MUST summarize completed Sub Repo updates (including paths and logs) and explicitly carry them over when returning control to `SKILL.md`.
+# Submodule Processing Workflow
+
+**[State Checkpoint]**
+- MUST verify the Main Repo absolute path transferred from the previous step.
+- MUST ensure terminal is located at the Main Repo root BEFORE beginning discovery.
+
+## [Discovery Phase]
+1. Deep Discovery: MUST run `git submodule status --recursive` to find all Sub Repos.
+
+## [Elimination Phase]
+2. Evaluation: For EACH Sub Repo, MUST run `git diff --cached` securely to check for staged changes. IF NO staged changes exist, MUST eliminate from target list.
+
+## [Execution Phase]
+3. Generation: For Sub Repos WITH staged changes, MUST execute `COMMIT_GENERATION.md`.
+4. Validation: MUST verify generation success. IF ANY Sub Repo has remaining staged changes, MUST diagnose failure and halt.
+
+## [Indexing Phase]
+5. Preference Check: MUST read the resolved Harness memory file `git-commit-prefs.md` for the `auto_stage_submodules` setting. Prefer an existing `MEMORY.md`/`RULES.md`; otherwise use `.github/harness-everything/memories/git-commit-prefs.md`.
+6. Execution:
+   - IF `auto_stage_submodules=true`: MUST run `git add <path>` in the Main Repo for all updated Sub Repos.
+   - IF missing: MUST prompt user exactly: "[1] Yes, [2] No, [3] Yes & Always allow".
+   - IF user selects [3]: MUST write `auto_stage_submodules=true` to the resolved Harness memory file AND run `git add <path>`.
+   - IF user selects [1]: MUST run `git add <path>` in the Main Repo.
+   - IF user selects [2]: MUST NOT run `git add`.
+
+## [State Handoff]
+7. Handoff: MUST summarize completed Sub Repo updates (including paths and logs) and explicitly carry them over when returning control to `SKILL.md`.

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
----
-
-# Grill Me (Interrogation & Stress Testing)
-
-## 📋 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).
+---
+name: grill-me
+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)
+
+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** | 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.