harness-everything 0.2.1 → 0.3.6

package/docs/workflows/skill-creator.md

@@ -1,75 +1,80 @@
-# Workflow: Skill Creator
-
-> Authors, audits, and evolves SKILL.md files against a single quality bar — the Skill Contract format plus predictability/pruning/progressive-disclosure principles from external skill-writing research — and is the required gate for skills `self-evolve` generates dynamically.
-
----
-
-## 1. Skill Behavior Workflow
-
-This section visualizes how the `skill-creator` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
-
-```mermaid
-graph TD
-  Start([New skill request / existing SKILL.md to audit / self-evolve dynamic-generation call]) --> Intent["Capture intent: what it does, the one canonical description sentence, which Tier, does an existing skill already own this ground"]
-  Intent --> Draft["Draft: Skill Contract table first, then body sized by information hierarchy (steps vs flat reference vs guides/references)"]
-  Draft --> Test["Test 2-3 realistic prompts via create-agent-launcher: with-skill subagent vs baseline subagent"]
-  Test --> Checklist{"Quality Checklist (§3): SSOT, no duplication >5 lines, every MUST has a real gate, no no-ops, info hierarchy, leading words reused, checkable completion criteria, human-facing description"}
-  Checklist -->|Fails| Prune["Prune and rewrite the failing item"]
-  Prune --> Checklist
-  Checklist -->|Passes| Route{Static or dynamic?}
-  Route -->|Static| Register["Register: harness-everything §5 row + tier-router.js keyword line"]
-  Route -->|Dynamic, from self-evolve| DynamicContract["§4 Dynamic Skill Generation Contract: write to .claude/harness-everything/skills/generated/<name>/, metadata.type=dynamic, status=draft"]
-  Register --> End([Skill live in the repo, single source of truth for its own description])
-  DynamicContract --> End
-```
-
----
-
-## 2. Triggering and Routing Path
-
-This diagram illustrates how `skill-creator` is triggered through user requests or developer actions, and how it integrates or chains together with other companion skills in the Harness OS ecosystem to form unified workflows.
-
-```mermaid
-graph LR
-  Router["harness-everything / tier-router.js"] -->|Keyword: skill / skill.md / new skill / write a skill| Creator["skill-creator / SKILL.md"]
-  Creator -->|Table shape spec| SkillStyle["skill-style / SKILL.md"]
-  Creator -->|With/without test subagents| Launcher["create-agent-launcher / SKILL.md"]
-  Creator -->|Registers new static skills into| Registry["harness-everything / SKILL.md §5"]
-  Evolve["self-evolve / SKILL.md §4"] -->|MUST load before packaging a session insight| Creator
-  Creator -->|Writes dynamic skills to| Generated[".claude/harness-everything/skills/generated/"]
-```
-
----
-
-## 3. Real-World Use Case Flowchart
-
-Here we model concrete real-world scenarios and use cases of the `skill-creator` skill, illustrating standard success paths, error handling, or recovery loops — one for a human-directed static skill, one for `self-evolve`'s dynamic path.
-
-```mermaid
-graph TD
-  Start1["Developer: 'I want a skill for deploying to AWS'"] --> Intent1["skill-creator §2 Step 1: capture intent, one canonical description sentence"]
-  Intent1 --> Draft1["Draft Skill Contract table + steps, push detail to deploy-aws/guides/"]
-  Draft1 --> Test1["Spawn with/without subagents via create-agent-launcher on 2-3 realistic prompts"]
-  Test1 --> Check1{Quality Checklist passes?}
-  Check1 -->|No| Fix1["Fix flagged item, re-test"]
-  Fix1 --> Check1
-  Check1 -->|Yes| Reg1["Add row to harness-everything §5 + one line to tier-router.js"]
-  Reg1 --> Done1([deploy-aws/SKILL.md live as a static, reviewed skill])
-
-  Start2["zoom-out recovery ends: root cause found for a recurring connection-pool exhaustion bug"] --> Trigger2["self-evolve §3 Step 3: Dynamic Skill Generation"]
-  Trigger2 --> Load2["self-evolve MUST load skill-creator §4 before writing anything"]
-  Load2 --> Gate2{Quality Checklist §3 passes?}
-  Gate2 -->|No| Reject2["Do not persist — this checklist is the only review a dynamic skill gets"]
-  Gate2 -->|Yes| Write2["Write .claude/harness-everything/skills/generated/orm-transaction-batching/SKILL.md, metadata.type=dynamic, status=draft"]
-  Write2 --> Done2([Dynamic skill available next session, lifecycle tracked separately from static skills])
-```
-
----
-
-## 4. Verification Check
-
-To ensure that the `skill-creator` skill is operating in strict compliance with Harness OS design laws, verify the following:
-
-- [ ] **Physical Boundary Verification**: The skill boundaries are respected and do not leak context.
-- [ ] **State Checkpoint Verification**: The active state is established, validated, and recorded at the beginning and end of each execution branch.
-- [ ] **Cognitive Alignment**: The skill conforms to the **Think > Try > Summarize > Record** cognitive loop.
+# Workflow: Skill Creator
+
+> Authors, audits, and evolves SKILL.md files against a single quality bar — the Skill Contract format plus predictability/pruning/progressive-disclosure principles from external skill-writing research — and is the required gate for skills `self-evolve` generates dynamically.
+
+---
+
+## 1. Skill Behavior Workflow
+
+This section visualizes how the `skill-creator` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
+
+```mermaid
+graph TD
+  Start([New skill request / existing SKILL.md to audit / self-evolve dynamic-generation call after LLM selection]) --> Intent["Capture intent: what it does, the one canonical description sentence, which Tier, does an existing skill already own this ground"]
+  Intent --> Draft["Draft: Skill Contract table first, then body sized by information hierarchy (steps vs flat reference vs guides/references)"]
+  Draft --> Test["Test 2-3 realistic prompts via multi-agent-workspace: with-skill subagent vs baseline subagent"]
+  Test --> Checklist{"Quality Checklist (§3): SSOT, no duplication >5 lines, every MUST has a real gate, no no-ops, info hierarchy, leading words reused, checkable completion criteria, human-facing description"}
+  Checklist -->|Fails| Prune["Prune and rewrite the failing item"]
+  Prune --> Checklist
+  Checklist -->|Passes| Route{Static or dynamic?}
+  Route -->|Static| Register["Register: harness-everything §5 row + tier-router.js keyword line"]
+  Route -->|Dynamic, from self-evolve| DynamicContract["§4 Dynamic Skill Generation Contract: write to .claude/harness-everything/skills/generated/<name>/ & register-dynamic-skill.js to manifest.json, metadata.type=dynamic, status=draft"]
+  Register --> End([Skill live in the repo, single source of truth for its own description])
+  DynamicContract --> End
+```
+
+---
+
+## 2. Triggering and Routing Path
+
+This diagram illustrates how `skill-creator` is triggered through user requests or developer actions, and how it integrates or chains together with other companion skills in the Harness OS ecosystem to form unified workflows.
+
+```mermaid
+graph LR
+  Router["harness-everything / tier-router.js"] -->|Keyword: skill / skill.md / new skill / write a skill| Creator["skill-creator / SKILL.md"]
+  Creator -->|Table shape spec| SkillStyle["skill-style / SKILL.md"]
+  Creator -->|With/without test subagents| Launcher["multi-agent-workspace / SKILL.md"]
+  Creator -->|Registers new static skills into| Registry["harness-everything / SKILL.md §5"]
+  Evolve["self-evolve / SKILL.md §4"] -->|LLM decides to promote insight| Creator
+  Creator -->|Writes dynamic skills to| Generated[".claude/harness-everything/skills/generated/"]
+  Generated -->|Registered in| Manifest["manifest.json 'generated' registry"]
+  Manifest -->|Matched & auto-loaded by| Router
+```
+
+---
+
+## 3. Real-World Use Case Flowchart
+
+Here we model concrete real-world scenarios and use cases of the `skill-creator` skill, illustrating standard success paths, error handling, or recovery loops — one for a human-directed static skill, one for `self-evolve`'s dynamic path.
+
+```mermaid
+graph TD
+  Start1["Developer: 'I want a skill for deploying to AWS'"] --> Intent1["skill-creator §2 Step 1: capture intent, one canonical description sentence"]
+  Intent1 --> Draft1["Draft Skill Contract table + steps, push detail to deploy-aws/guides/"]
+  Draft1 --> Test1["Spawn with/without subagents via multi-agent-workspace on 2-3 realistic prompts"]
+  Test1 --> Check1{Quality Checklist passes?}
+  Check1 -->|No| Fix1["Fix flagged item, re-test"]
+  Fix1 --> Check1
+  Check1 -->|Yes| Reg1["Add row to harness-everything §5 + one line to tier-router.js"]
+  Reg1 --> Done1([deploy-aws/SKILL.md live as a static, reviewed skill])
+
+  Start2["zoom-out recovery ends: root cause found for a recurring connection-pool exhaustion bug"] --> Decide2{"LLM: Does it warrant a standalone complex skill?"}
+  Decide2 -->|No: Simple Tip| Save2["persist-memory.js writes simple rule to RULES.md"]
+  Decide2 -->|Yes: Complex Skill| Trigger2["self-evolve §3 Step 3: Promote to Dynamic Skill"]
+  Trigger2 --> Load2["self-evolve MUST load skill-creator §4 before writing anything"]
+  Load2 --> Gate2{Quality Checklist §3 passes?}
+  Gate2 -->|No| Reject2["Do not persist — this checklist is the only review a dynamic skill gets"]
+  Gate2 -->|Yes| Write2["Write .claude/harness-everything/skills/generated/orm-transaction-batching/SKILL.md & run register-dynamic-skill.js"]
+  Write2 --> Done2([Dynamic skill available next session via manifest registration and tier-router.js scan])
+  Save2 --> Done3([Simple memory rule available in RULES.md])
+```
+
+---
+
+## 4. Verification Check
+
+To ensure that the `skill-creator` skill is operating in strict compliance with Harness OS design laws, verify the following:
+
+- [ ] **Physical Boundary Verification**: The skill boundaries are respected and do not leak context.
+- [ ] **State Checkpoint Verification**: The active state is established, validated, and recorded at the beginning and end of each execution branch.
+- [ ] **Cognitive Alignment**: The skill conforms to the **Think > Try > Summarize > Record** cognitive loop.

package/docs/workflows/skill-style.md

@@ -1,64 +1,64 @@
-# Workflow: Skill Style
-
-> Guidelines and style rules for authoring, refactoring, and maintaining SKILL.md files to enforce clean frontmatter and logical boundaries.
-
----
-
-## 1. Skill Behavior Workflow
-
-This section visualizes how the `skill-style` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
-
-```mermaid
-graph TD
-  Start([Authoring / Editing a SKILL.md]) --> ParseFrontmatter["Parse and validate YAML Frontmatter: name, description"]
-  ParseFrontmatter --> ValidateBoundary["Check for explicit physical boundaries & state checkpoints"]
-  ValidateBoundary --> VerifyCognitiveLoop["Verify integration with Cognitive Loop laws"]
-  VerifyCognitiveLoop --> CheckFormatting["Ensure clean markdown layout and bullet-style rules"]
-  CheckFormatting --> FormatApproved{Complies with STYLE.md?}
-  FormatApproved -->|No| FixSkillFile["Refactor and clean file formatting"]
-  FormatApproved -->|Yes| SaveSkillFile["Commit clean, validated SKILL.md"]
-  FixSkillFile --> SaveSkillFile
-  SaveSkillFile --> End([Skill document aligned with professional guidelines])
-```
-
----
-
-## 2. Triggering and Routing Path
-
-This diagram illustrates how `skill-style` is reached — as of the `skill-creator` split, it is no longer the first stop. `tier-router.js`'s `/\bskill\b|skill\.md|new skill|write a skill/` match now recommends `skill-creator` first (the full authoring/audit/testing workflow) and `skill-style` second (the terse Skill Contract table shape it builds on) — see `harness-everything/scripts/tier-router.js`.
-
-```mermaid
-graph LR
-  Router["harness-everything / tier-router.js"] -->|Keyword: skill / skill.md / new skill| Creator["skill-creator / SKILL.md"]
-  Creator -->|Builds on the table shape defined in| SkillStyle["skill-style / SKILL.md"]
-  SkillStyle -->|Audits format correctness of| OtherSkills["Any SKILL.md in the workspace"]
-  SkillStyle -->|Pre-PR validation gate integration| VerLoop["verification-loop / SKILL.md"]
-```
-
----
-
-## 3. Real-World Use Case Flowchart
-
-§1 already walks the linear audit steps for a single file. This section instead shows the case that motivated splitting `skill-creator` out of this skill in the first place: a developer who needs the *fuller* workflow, not just the table shape.
-
-```mermaid
-graph TD
-  Start["Developer: 'help me write a new skill for deploying to AWS'"] --> Router["tier-router.js recommends skill-creator + skill-style"]
-  Router --> Creator["skill-creator: capture intent, draft, test against real prompts (§2)"]
-  Creator --> StyleCheck["skill-style: does the draft's Skill Contract table match the required shape?"]
-  StyleCheck -->|Missing/malformed table| Fix["Fix table shape per skill-style, re-run skill-creator's Quality Checklist"]
-  StyleCheck -->|Table shape OK| Checklist["skill-creator §3 Quality Checklist: no-op / duplication / negation / progressive-disclosure checks"]
-  Fix --> Checklist
-  Checklist --> Register["Register in harness-everything §5 + tier-router.js (skill-creator §2 Step 4)"]
-  Register --> Done([deploy-aws/SKILL.md committed, consistent with the rest of the repo])
-```
-
----
-
-## 4. Verification Check
-
-To ensure that the `skill-style` skill is operating in strict compliance with Harness OS design laws, verify the following:
-
-- [ ] **Physical Boundary Verification**: The skill boundaries are respected and do not leak context.
-- [ ] **State Checkpoint Verification**: The active state is established, validated, and recorded at the beginning and end of each execution branch.
-- [ ] **Cognitive Alignment**: The skill conforms to the **Think > Try > Summarize > Record** cognitive loop.
+# Workflow: Skill Style
+
+> Guidelines and style rules for authoring, refactoring, and maintaining SKILL.md files to enforce clean frontmatter and logical boundaries.
+
+---
+
+## 1. Skill Behavior Workflow
+
+This section visualizes how the `skill-style` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
+
+```mermaid
+graph TD
+  Start([Authoring / Editing a SKILL.md]) --> ParseFrontmatter["Parse and validate YAML Frontmatter: name, description"]
+  ParseFrontmatter --> ValidateBoundary["Check for explicit physical boundaries & state checkpoints"]
+  ValidateBoundary --> VerifyCognitiveLoop["Verify integration with Cognitive Loop laws"]
+  VerifyCognitiveLoop --> CheckFormatting["Ensure clean markdown layout and bullet-style rules"]
+  CheckFormatting --> FormatApproved{Complies with STYLE.md?}
+  FormatApproved -->|No| FixSkillFile["Refactor and clean file formatting"]
+  FormatApproved -->|Yes| SaveSkillFile["Commit clean, validated SKILL.md"]
+  FixSkillFile --> SaveSkillFile
+  SaveSkillFile --> End([Skill document aligned with professional guidelines])
+```
+
+---
+
+## 2. Triggering and Routing Path
+
+This diagram illustrates how `skill-style` is reached — as of the `skill-creator` split, it is no longer the first stop. `tier-router.js`'s `/\bskill\b|skill\.md|new skill|write a skill/` match now recommends `skill-creator` first (the full authoring/audit/testing workflow) and `skill-style` second (the terse Skill Contract table shape it builds on) — see `harness-everything/scripts/tier-router.js`.
+
+```mermaid
+graph LR
+  Router["harness-everything / tier-router.js"] -->|Keyword: skill / skill.md / new skill| Creator["skill-creator / SKILL.md"]
+  Creator -->|Builds on the table shape defined in| SkillStyle["skill-style / SKILL.md"]
+  SkillStyle -->|Audits format correctness of| OtherSkills["Any SKILL.md in the workspace"]
+  SkillStyle -->|Pre-PR validation gate integration| VerLoop["verification-loop / SKILL.md"]
+```
+
+---
+
+## 3. Real-World Use Case Flowchart
+
+§1 already walks the linear audit steps for a single file. This section instead shows the case that motivated splitting `skill-creator` out of this skill in the first place: a developer who needs the *fuller* workflow, not just the table shape.
+
+```mermaid
+graph TD
+  Start["Developer: 'help me write a new skill for deploying to AWS'"] --> Router["tier-router.js recommends skill-creator + skill-style"]
+  Router --> Creator["skill-creator: capture intent, draft, test against real prompts (§2)"]
+  Creator --> StyleCheck["skill-style: does the draft's Skill Contract table match the required shape?"]
+  StyleCheck -->|Missing/malformed table| Fix["Fix table shape per skill-style, re-run skill-creator's Quality Checklist"]
+  StyleCheck -->|Table shape OK| Checklist["skill-creator §3 Quality Checklist: no-op / duplication / negation / progressive-disclosure checks"]
+  Fix --> Checklist
+  Checklist --> Register["Register in harness-everything §5 + tier-router.js (skill-creator §2 Step 4)"]
+  Register --> Done([deploy-aws/SKILL.md committed, consistent with the rest of the repo])
+```
+
+---
+
+## 4. Verification Check
+
+To ensure that the `skill-style` skill is operating in strict compliance with Harness OS design laws, verify the following:
+
+- [ ] **Physical Boundary Verification**: The skill boundaries are respected and do not leak context.
+- [ ] **State Checkpoint Verification**: The active state is established, validated, and recorded at the beginning and end of each execution branch.
+- [ ] **Cognitive Alignment**: The skill conforms to the **Think > Try > Summarize > Record** cognitive loop.

package/docs/workflows/tdd.md

@@ -14,24 +14,27 @@ graph TD
   DesignInterface --> WriteTest["Write unit/integration tests first"]
   
   WriteTest --> RunRed["Try: Run tests (EXPECT FAILURE)"]
-  RunRed --> VerifyRed{Gate: Exit Code 1?}
+  RunRed --> AssertRed["Assert: Present terminal logs as evidence (Law 4)"]
+  AssertRed --> VerifyRed{Gate: Exit Code 1?}
   VerifyRed -->|Exit 0: Fake Test| FixTest["Reflect: Test is broken/fake. Fix it."]
   FixTest --> RunRed
   
   VerifyRed -->|Exit 1: True Red| WriteCode["Write minimal code to pass test"]
   
   WriteCode --> RunGreen["Try: Run tests (EXPECT SUCCESS)"]
-  RunGreen --> VerifyGreen{Gate: verify-gate.js}
+  RunGreen --> AssertGreen["Assert: Present terminal logs as evidence (Law 4)"]
+  AssertGreen --> VerifyGreen{Gate: verify-gate.js}
   
   VerifyGreen -->|Exit 1: Still Broken| DebugCode["Reflect: Read logs, fix code"]
   DebugCode --> RunGreen
   VerifyGreen -->|Exit 1: 3x Failures| CircuitBreaker["Trigger rule-of-3.js: ZOOM OUT"]
   CircuitBreaker --> DebugCode
   
-  VerifyGreen -->|Exit 0: Green| Refactor["Refactor code for readability"]
+  VerifyGreen -->|Exit 0: Green| Refactor["Refactor: Optimize & audit Code-Doc Alignment (Law 6)"]
   
   Refactor --> RunVerify["Try: Run tests again"]
-  RunVerify --> VerifyRefactor{Gate: verify-gate.js}
+  RunVerify --> AssertRefactor["Assert: Present terminal logs as evidence (Law 4)"]
+  AssertRefactor --> VerifyRefactor{Gate: verify-gate.js}
   VerifyRefactor -->|Exit 1| Revert["Revert refactor / Fix"]
   Revert --> RunVerify
   

package/docs/workflows/to-spec.md

@@ -0,0 +1,83 @@
+# Workflow: To Spec
+
+> Synthesizes an already-discussed conversation into whichever written artifact actually fits — feature spec, CLI/API reference, schema doc, or dev doc — and publishes it per this repo's own `projectDocs` entry inside `harness-everything/manifest.json`. Advisory in both Tier 2 and Tier 3 toward other skills; its own Step 0 framework check is a mechanized script gate, not advisory.
+
+---
+
+## 1. Skill Behavior Workflow
+
+This section visualizes how the `to-spec` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
+
+```mermaid
+graph TD
+  Start(["/to-spec invoked"]) --> OutlinePreview["Phase 1: Present 10-20 Line Outline Preview & Path to User"]
+  OutlinePreview --> UserApproved{"User Approves Outline?"}
+  UserApproved -->|No / Adjustments Needed| AdjustOutline["Refine Template Shape & Outline"] --> OutlinePreview
+  
+  UserApproved -->|Yes| CheckScript["Phase 2: node to-spec/scripts/check-project-docs.js check"]
+  CheckScript --> ExitCode{"Exit code?"}
+  ExitCode -->|0: projectDocs complete or inferred| ResolveConfig["Use Configured / Inferred docLocation"]
+  ExitCode -->|1 / Script Missing| InspectWorkspace{"Inspect Workspace Folders"}
+  
+  InspectWorkspace -->|Folder Found| ResolveWorkspace["Use docs/specs/, docs/reference/, docs/adr/, .scratch/"]
+  InspectWorkspace -->|No Folder| ResolvePlatform["Fallback to .github/harness-everything/specs/"]
+  
+  ResolveConfig --> WriteDoc["Generate & Publish Full Document"]
+  ResolveWorkspace --> WriteDoc
+  ResolvePlatform --> WriteDoc
+  
+  WriteDoc --> End(["Spec Document Published Successfully"])
+```
+
+---
+
+## 2. Triggering and Routing Path
+
+This diagram illustrates how `to-spec` is reached through user requests and how it chains with companion skills in the Harness OS ecosystem.
+
+```mermaid
+graph LR
+  Router["harness-everything / tier-router.js"] -->|Keyword: spec / PRD / cli reference / schema doc / dev doc| Suggest["Suggests to-spec/SKILL.md - advisory only, still explicit-invoke"]
+  Suggest --> TS["to-spec / SKILL.md"]
+  TS -->|Step 0, mandatory| Gate["check-project-docs.js check - scans repo-local manifest.json homes only"]
+  Gate -->|Exit 1, first run only| Init["check-project-docs.js init writes projectDocs into manifest.json"]
+  Init --> TS
+  Manifest["harness-everything/manifest.json (also owned by scripts/lib/manifest.js + self-evolve's generated registry)"] -.->|same file, different key| Gate
+  GWD["grill-with-docs / SKILL.md"] -->|Settles decisions BEFORE, feeds feature-spec shape| TS
+  GM["grill-me / SKILL.md"] -->|Settles decisions BEFORE| TS
+  TDD["tdd / SKILL.md (Tier 2)"] -.->|Optional pre-implementation doc, never blocks Red/Green/Refactor| TS
+  TS -->|Unresolved fork found mid-synthesis| GWD
+  TS -->|Published doc becomes input for| ToTickets["to-tickets / SKILL.md (planned)"]
+```
+
+---
+
+## 3. Real-World Use Case Flowchart
+
+```mermaid
+graph TD
+  Start["Tier 2 task: add a new `harness todo export` CLI command"] --> Invoke["/to-spec invoked (optional, offered by router)"]
+  Invoke --> RunCheck["node check-project-docs.js check"]
+  RunCheck --> Exit0["Exit 0 - .claude/harness-everything/manifest.json already has projectDocs from a prior run"]
+  Exit0 --> Gather2["Gathers context: existing native or Markdown checklist conventions"]
+  Gather2 --> PickShape2["Picks cli-reference.md - not feature-spec, no user stories needed"]
+  PickShape2 --> ConfirmFlags["Confirms --format and --since flag names with user"]
+  ConfirmFlags --> Draft["Writes doc from templates/cli-reference.md, adapted headings"]
+  Draft --> ReadDocLoc["projectDocs.docLocation says docs/reference/"]
+  ReadDocLoc --> PublishLocal["docs/reference/todo-export.md - not filed as an issue"]
+  PublishLocal --> Done(["Doc published; TDD proceeds unblocked either way"])
+```
+
+---
+
+## 4. Verification Check
+
+To ensure `to-spec` is operating in strict compliance with Harness OS design laws, verify the following:
+
+- [ ] **Mechanized Gate, Not Prose**: Step 0 ran `check-project-docs.js check` and honored its exit code — it did not skip straight to inferring the framework from prose memory of past runs.
+- [ ] **Repo-Local, Not Global**: `projectDocs` was read from / written to a workspace-relative platform home only (`.claude/`, `.cursor/`, `.github/`, `.codex/`, `.continue/` under this repo) — never `~/.agents` or the global `~/.claude` manifest, which would leak this repo's tracker into unrelated projects.
+- [ ] **Pointer, Not Payload**: Every `projectDocs` field is a short pointer (≤ 200 chars, enforced by `init`) — elaborate content (a full issue template, a per-context doc map) lives in its own file, referenced by path, not inlined into `manifest.json`.
+- [ ] **No Re-Interview Violation**: Beyond the one-time Step 0 setup, the skill did not ask the user questions that a prior `grill-me`/`grill-with-docs` pass, or the conversation itself, already answered.
+- [ ] **Adaptive Shape Selection**: The template picked (feature-spec / cli-reference / schema-doc / dev-doc) actually matches the artifact being documented — not defaulted to the heaviest shape out of habit.
+- [ ] **Shape-Correct Destination**: A feature-spec was filed as an issue; a CLI-reference/schema-doc/dev-doc was written under `docLocation` instead, unless the user explicitly confirmed it should also be an issue.
+- [ ] **Non-Blocking Toward Other Skills**: The Step 3 confirmation happened before publishing, and to-spec's own execution never delayed or gated `tdd`/`verification-loop` in a Tier 2 flow.

package/docs/workflows/to-tickets.md

@@ -0,0 +1,80 @@
+# Workflow: To Tickets
+
+> Breaks a `to-spec` feature spec, a plan, or the current conversation into tracer-bullet tickets with declared blocking edges, published through the same `projectDocs` entry `to-spec` already established. Reuses `to-spec`'s own project-docs gate — never a second setup interview.
+
+---
+
+## 1. Skill Behavior Workflow
+
+This section visualizes how the `to-tickets` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
+
+```mermaid
+graph TD
+  Start(["/to-tickets invoked"]) --> CheckScript["Step 0: node to-spec/scripts/check-project-docs.js check"]
+  CheckScript --> ExitCode{"Exit code?"}
+  ExitCode -->|0: projectDocs configured/inferred| PathConfig["Use Configured / Inferred Tracker"]
+  ExitCode -->|1 / Script Missing| InspectRepo{"Inspect Workspace Directories"}
+  
+  InspectRepo -->|Folder Found| PathRepo["Use docs/roadmaps/, docs/tickets/, tasks/tickets/, .scratch/issues/"]
+  InspectRepo -->|No Folder| PathPlatform["Fallback to .github/harness-everything/tickets/"]
+  
+  PathConfig --> Gather["Step 1: Gather context from spec, plan, or conversation"]
+  PathRepo --> Gather
+  PathPlatform --> Gather
+  
+  Gather --> Explore["Step 2: Explore codebase & identify prefactor opportunities"]
+  Explore --> Draft["Step 3: Draft vertical slices with tracer bullets & blocking edges"]
+  Draft --> Quiz["Step 4: Quiz user on granularity, blocking edges, and merges"]
+  
+  Quiz --> Approved{"User approves breakdown?"}
+  Approved -->|No| Draft
+  Approved -->|Yes| Publish["Step 5: Publish ticket files at resolved storage path"]
+  Publish --> End(["Tickets published, frontier = unblocked tickets"])
+```
+
+---
+
+## 2. Triggering and Routing Path
+
+This diagram illustrates how `to-tickets` is reached through user requests and how it chains with companion skills in the Harness OS ecosystem.
+
+```mermaid
+graph LR
+  Router["harness-everything / tier-router.js"] -->|Keyword: break into tickets / vertical slice / tracer bullet / blocking edges| Suggest["Suggests to-tickets/SKILL.md - advisory only, still explicit-invoke"]
+  Suggest --> TT["to-tickets / SKILL.md"]
+  TT -->|Step 0, mandatory, SAME script as to-spec| Gate["check-project-docs.js check"]
+  Gate -->|Exit 1| RedirectToSpec["Stop - point user to /to-spec's Step 0 interview, not a duplicate here"]
+  TS["to-spec / SKILL.md"] -->|Published feature-spec is the preferred input| TT
+  TS -.->|Same projectDocs entry, read not written| Gate
+  TT -->|No spec exists yet, still works from| Convo["Current conversation / plan"]
+  TT -->|Publishes tickets that unblock| TDD["tdd / SKILL.md (Tier 2, per ticket)"]
+```
+
+---
+
+## 3. Real-World Use Case Flowchart
+
+```mermaid
+graph TD
+  Start["A to-spec feature-spec for 'notification retry limits' was published earlier"] --> Invoke["/to-tickets invoked with the spec's issue number"]
+  Invoke --> RunCheck["node check-project-docs.js check - Exit 0, projectDocs already set from the to-spec run"]
+  RunCheck --> FetchSpec["Fetches full spec body via gh issue view"]
+  FetchSpec --> ExploreCode["Explores retry-policy module, finds a shared RetryConfig prefactor opportunity"]
+  ExploreCode --> DraftSlices["Drafts 3 tracer-bullet tickets: 01 prefactor RetryConfig, 02 per-tenant override (blocked by 01), 03 UI toggle (blocked by 02)"]
+  DraftSlices --> QuizUser["Presents numbered breakdown, user merges 02+03"]
+  QuizUser --> Publish2["Publishes 2 GitHub issues in dependency order, Status: ready-for-agent"]
+  Publish2 --> Done(["Frontier = ticket 01, unblocked, ready to claim"])
+```
+
+---
+
+## 4. Verification Check
+
+To ensure `to-tickets` is operating in strict compliance with Harness OS design laws, verify the following:
+
+- [ ] **Shared Gate, No Duplicate Interview**: Step 0 called `to-spec`'s own `check-project-docs.js check` — it did not run a second, parallel setup interview for tracker/doc-location/issue-definition.
+- [ ] **Vertical, Not Horizontal**: Every non-wide-refactor ticket cuts a complete path through all layers it touches — no ticket is "just the schema" or "just the UI" for the same feature.
+- [ ] **Blocking Edges Are Real**: Each ticket's "Blocked by" lists only tickets that genuinely gate it, not every ticket that merely precedes it in reading order.
+- [ ] **Wide-Refactor Exception Applied Correctly**: A mechanical, huge-blast-radius change was sequenced as expand → migrate batches → contract, not forced into a single tracer-bullet ticket that can't land green.
+- [ ] **User Approval Before Publish**: The numbered breakdown was shown and approved (or iterated on) before Step 5 published anything.
+- [ ] **No Forced Decomposition**: A `cli-reference`/`schema-doc`/`dev-doc` shaped `to-spec` doc that was already a single unit of work was not artificially split into multiple tickets.

package/docs/workflows/todo-driven-workflow.md

@@ -1,36 +1,34 @@
 # Workflow: Todo-Driven Workflow
 
-> The fundamental execution loop. Driven entirely by terminal state machines (`todo-cli.js`).
-
----
-
-## 1. Skill Behavior Workflow
-
-This section visualizes the rigid state constraints. Transitioning state is blocked unless verification gates pass.
+> The fundamental execution loop for Tier 2/3 work. Prefer the host's native
+> TODO tracker; use a Markdown checklist when no native tracker is available.
 
 ```mermaid
 graph TD
-  Start([Initialize Checklist]) --> Plan["Define 3-7 Verifiable Sub-tasks"]
-  Plan --> SaveTodo["Try: node todo-cli.js init ..."]
-  
-  SaveTodo --> ChooseTask["Choose ONE pending task"]
-  ChooseTask --> MarkInProgress["Try: node todo-cli.js start <id>"]
-  
-  MarkInProgress --> CheckStart{Gate: Exit Code?}
-  CheckStart -->|Exit 1: Multitasking Blocked| ReflectStart["Reflect: Must complete previous task first"]
-  ReflectStart --> Execute
-  
-  CheckStart -->|Exit 0| Execute["Execute code changes"]
-  
-  Execute --> GatherEvidence["Try: node verify-gate.js"]
-  GatherEvidence --> VerifySuccess{Gate: Exit Code?}
-  
-  VerifySuccess -->|Exit 1: Code is broken| ReflectCode["Reflect: Read Error Log & Fix"]
-  ReflectCode --> Execute
-  
-  VerifySuccess -->|Exit 0: Code works| MarkCompleted["Try: node todo-cli.js complete <id>"]
-  
-  MarkCompleted --> CheckRemaining{All tasks completed?}
-  CheckRemaining -->|No| ChooseTask
-  CheckRemaining -->|Yes| Finish([Signal Task Completion])
+  Start[Initialize checklist] --> Plan[Define 3-7 verifiable milestones]
+  Plan --> Native{Native TODO tracker available?}
+  Native -->|Yes| Host[Use host tracker]
+  Native -->|No| Markdown[Create tasks/todo.md]
+  Host --> One[Keep one item in-progress]
+  Markdown --> One
+  One --> Execute[Execute bounded scope]
+  Execute --> Verify[Run named verification command]
+  Verify -->|pass| Complete[Record evidence and complete item]
+  Verify -->|fail| Reflect[Inspect failure and update plan]
+  Reflect --> Execute
+  Complete --> More{More milestones?}
+  More -->|Yes| One
+  More -->|No| Done[Finish]
 ```
+
+## Operating rules
+
+1. Define 3-7 milestones before editing.
+2. Give each milestone an output, pass condition, and verification command.
+3. Keep exactly one milestone `in-progress`.
+4. Mark a milestone complete only after its check passes.
+5. Use `using-git-worktrees` when parallel agents would otherwise share a write scope.
+6. Leave a blocker visible in the checklist and escalate instead of inventing progress.
+
+The repository has no TODO CLI state machine. This keeps progress portable,
+host-native, and transparent across sessions.