harness-everything 0.2.1 → 0.3.6

package/to-spec/scripts/check-project-docs.js

@@ -0,0 +1,259 @@
+#!/usr/bin/env node
+/**
+ * Project Docs Framework Check
+ *
+ * Mechanized gate for `to-spec` (and `to-tickets`, once installed): has this
+ * repo already pinned down where reference docs live, how issues are
+ * tracked, and what counts as a valid issue? Stored as a `projectDocs` entry
+ * inside the SAME harness-everything/manifest.json this package already
+ * owns (see scripts/lib/manifest.js and self-evolve's `generated` skill
+ * registry) - not a new docs/agents/ file convention, so there's one config
+ * surface, not two.
+ *
+ * Deliberately repo-local only: unlike self-evolve's `generated` skills
+ * (intentionally reusable across projects), doc location / tracker / issue
+ * definition are PER-REPO facts. Reading or writing them through the global
+ * ~/.agents or ~/.claude manifest homes would leak one project's tracker
+ * into every other project sharing that global install, so this script
+ * scans only the workspace-relative platform homes, never the user-home ones.
+ *
+ * Exit 0 -> at least one detected platform's manifest.json (inside this
+ *           repo) has a complete projectDocs entry. Read it, skip Step 0.
+ * Exit 1 -> missing or incomplete everywhere. Run the Step 0 interview in
+ *           to-spec/SKILL.md for the flagged field(s), then persist with `init`.
+ *
+ * manifest.json is read on every single tier-router.js invocation (every
+ * prompt, not just to-spec runs) to scan for self-evolve's generated
+ * skills - so projectDocs MUST stay a short pointer, never a growing log.
+ * `init` enforces a length cap per field (see MAX_FIELD_LENGTH) precisely so
+ * this can't quietly bloat over time. If a real answer is genuinely long
+ * (a multi-context doc map, a full custom issue template), write that detail
+ * into its own file - a CONTEXT-MAP.md entry, a `.github/ISSUE_TEMPLATE/`
+ * file, a docs/ README - and pass just that path as the field's value.
+ * Anything to-spec might later want to log per-session or per-doc (e.g.
+ * "which doc got published for which conversation") belongs in a separate,
+ * session-scoped file under the state dir (see hooks/scripts/lib/harness-
+ * state.js's getSessionDir) - never appended into this manifest.
+ */
+const fs = require('fs');
+const path = require('path');
+
+function getWorkspaceRoot() {
+  let dir = path.resolve(process.cwd());
+  while (dir !== path.parse(dir).root) {
+    if (fs.existsSync(path.join(dir, '.git'))) return dir;
+    dir = path.dirname(dir);
+  }
+  return process.cwd();
+}
+
+function loadManifestHelper() {
+  const candidates = [
+    path.join(__dirname, '../../scripts/lib/manifest'),
+    path.join(__dirname, '../scripts/lib/manifest'),
+    path.join(__dirname, '../../../scripts/lib/manifest'),
+    path.join(getWorkspaceRoot(), 'scripts/lib/manifest'),
+    path.join(getWorkspaceRoot(), 'harness-everything/scripts/lib/manifest'),
+  ];
+  for (const cand of candidates) {
+    try {
+      if (fs.existsSync(cand + '.js') || fs.existsSync(cand)) {
+        return require(cand);
+      }
+    } catch (e) {}
+  }
+  throw new Error('[to-spec/check-project-docs] Failed to locate manifest helper module (scripts/lib/manifest)');
+}
+const { getManifestPath, readManifest, writeManifest } = loadManifestHelper();
+
+const REQUIRED_FIELDS = ['docLocation', 'tracker', 'issueDefinition'];
+const FLAG_TO_FIELD = {
+  'doc-location': 'docLocation',
+  'tracker': 'tracker',
+  'issue-definition': 'issueDefinition',
+};
+// A pointer, not a payload: one short line each. Long enough for "GitHub
+// Issues via gh, label ready-for-agent" or "docs/reference/, see
+// CONTEXT-MAP.md for per-context layout", too short for embedding a full
+// issue template or a multi-paragraph doc-location policy inline.
+const MAX_FIELD_LENGTH = 200;
+
+// Workspace-relative platform homes ONLY - no userHome/.agents or
+// userHome/.claude here (see file header). tier-router.js and
+// register-dynamic-skill.js include those two because self-evolved skills
+// are meant to travel with the user across projects; projectDocs must not.
+function getRepoManifestHomes(workspaceRoot) {
+  return [
+    path.join(workspaceRoot, '.claude'),
+    path.join(workspaceRoot, '.cursor'),
+    path.join(workspaceRoot, '.github'),
+    path.join(workspaceRoot, '.codex'),
+    path.join(workspaceRoot, '.continue'),
+  ];
+}
+
+function missingFields(projectDocs) {
+  if (!projectDocs) return REQUIRED_FIELDS.slice();
+  return REQUIRED_FIELDS.filter(f => !String(projectDocs[f] || '').trim());
+}
+
+/**
+ * Heuristic workspace convention detector.
+ * Automatically infers docLocation, tracker, and issueDefinition from standard directory layouts.
+ */
+function detectWorkspaceConventions(workspaceRoot) {
+  const inferred = {};
+
+  // Detect docLocation
+  const docCandidates = ['docs/roadmaps', 'docs/reference', 'docs/specs', 'docs', 'doc'];
+  for (const dir of docCandidates) {
+    if (fs.existsSync(path.join(workspaceRoot, dir))) {
+      inferred.docLocation = `${dir}/`;
+      break;
+    }
+  }
+
+  // Detect tracker
+  if (fs.existsSync(path.join(workspaceRoot, '.github/ISSUE_TEMPLATE'))) {
+    inferred.tracker = 'GitHub Issues via .github/ISSUE_TEMPLATE/';
+  } else if (fs.existsSync(path.join(workspaceRoot, 'docs/roadmaps'))) {
+    inferred.tracker = 'docs/roadmaps/ local markdown tickets';
+  } else if (fs.existsSync(path.join(workspaceRoot, 'tasks/tickets'))) {
+    inferred.tracker = 'tasks/tickets/ local markdown tickets';
+  } else if (fs.existsSync(path.join(workspaceRoot, '.scratch'))) {
+    inferred.tracker = '.scratch/ local markdown workspace';
+  } else if (inferred.docLocation) {
+    inferred.tracker = `${inferred.docLocation}tickets/ local markdown tickets`;
+  }
+
+  // Detect issueDefinition
+  if (inferred.tracker && inferred.tracker.includes('ISSUE_TEMPLATE')) {
+    inferred.issueDefinition = '.github/ISSUE_TEMPLATE/ template structure';
+  } else if (inferred.tracker) {
+    inferred.issueDefinition = 'Title + acceptance criteria + Status: ready-for-agent';
+  }
+
+  return inferred;
+}
+
+function runCheck(workspaceRoot) {
+  const existingPaths = getRepoManifestHomes(workspaceRoot)
+    .map(getManifestPath)
+    .filter(p => fs.existsSync(p));
+
+  // Check explicit projectDocs entries in manifest files
+  for (const manifestPath of existingPaths) {
+    const docs = readManifest(manifestPath).projectDocs;
+    if (docs && missingFields(docs).length === 0) {
+      console.log(`[Project Docs Check] OK: ${manifestPath} defines document location, issue tracker, and issue definition.`);
+      process.exit(0);
+    }
+  }
+
+  // Fallback to heuristic workspace detection
+  const inferred = detectWorkspaceConventions(workspaceRoot);
+  const missingInferred = missingFields(inferred);
+
+  if (missingInferred.length === 0) {
+    console.log(`[Project Docs Check] OK (Inferred from workspace structure):`);
+    console.log(`  - docLocation: ${inferred.docLocation}`);
+    console.log(`  - tracker: ${inferred.tracker}`);
+    console.log(`  - issueDefinition: ${inferred.issueDefinition}`);
+    process.exit(0);
+  }
+
+  console.log(`[Project Docs Check] INCOMPLETE: no manifest.json or standard folder structure covers all fields. Missing: ${missingInferred.join(', ')}`);
+  console.log('=> Run the Step 0 framework interview for missing fields, or proceed using default workspace fallbacks.');
+  process.exit(1);
+}
+
+function parseFlags(args) {
+  const values = {};
+  for (let i = 0; i < args.length; i += 2) {
+    const flag = args[i];
+    const value = args[i + 1];
+    if (flag && flag.startsWith('--') && value !== undefined) {
+      values[flag.slice(2)] = value;
+    }
+  }
+  return values;
+}
+
+function runInit(workspaceRoot, args) {
+  const flags = parseFlags(args);
+  const missingFlags = Object.keys(FLAG_TO_FIELD).filter(f => !flags[f]);
+  if (missingFlags.length > 0) {
+    console.error(`[Project Docs Check] init requires --${missingFlags.join(', --')}`);
+    process.exit(1);
+  }
+
+  const oversizedFlags = Object.keys(FLAG_TO_FIELD).filter(f => flags[f].length > MAX_FIELD_LENGTH);
+  if (oversizedFlags.length > 0) {
+    for (const f of oversizedFlags) {
+      console.error(`[Project Docs Check] --${f} is ${flags[f].length} chars - projectDocs fields must stay <= ${MAX_FIELD_LENGTH} chars (a pointer, not the content).`);
+    }
+    console.error('=> Write the detailed content to its own file instead (e.g. a CONTEXT-MAP.md entry, a .github/ISSUE_TEMPLATE/ file, a docs/ README), then pass just that path here.');
+    process.exit(1);
+  }
+
+  const projectDocs = {
+    docLocation: flags['doc-location'],
+    tracker: flags['tracker'],
+    issueDefinition: flags['issue-definition'],
+    updatedAt: new Date().toISOString(),
+  };
+
+  const homes = getRepoManifestHomes(workspaceRoot);
+
+  // Write to every platform home already bootstrapped with harness in THIS
+  // repo (their harness-everything/ subfolder already exists), so switching
+  // editors mid-project never loses this config.
+  let wrote = 0;
+  for (const home of homes) {
+    const manifestPath = getManifestPath(home);
+    if (!fs.existsSync(path.dirname(manifestPath))) continue;
+    const data = readManifest(manifestPath);
+    data.projectDocs = projectDocs;
+    writeManifest(manifestPath, data);
+    console.log(`[Project Docs Check] Wrote projectDocs to ${manifestPath}`);
+    wrote++;
+  }
+
+  // No repo-local platform bootstrapped yet: create the primary one
+  // (.claude/harness-everything/manifest.json) rather than falling back to
+  // any global/user-home manifest - this data must never leave the repo.
+  if (wrote === 0) {
+    const manifestPath = getManifestPath(homes[0]);
+    const data = readManifest(manifestPath);
+    data.projectDocs = projectDocs;
+    writeManifest(manifestPath, data);
+    console.log(`[Project Docs Check] No platform bootstrapped yet in this repo - wrote projectDocs to ${manifestPath}`);
+  }
+
+  process.exit(0);
+}
+
+if (process.argv[2] === '--help' || process.argv[2] === '-h') {
+  console.log(`Gate: has this repo already pinned doc location / issue tracker / issue definition?
+
+Usage:
+  node check-project-docs.js [check]                                                Exit 0 if a complete projectDocs entry already exists in this repo's manifest.json; exit 1 with the missing field(s) otherwise.
+  node check-project-docs.js init --doc-location "..." --tracker "..." --issue-definition "..."
+                                                                                       Persist all three fields (each <= ${MAX_FIELD_LENGTH} chars - a pointer, not the content) to every already-bootstrapped platform manifest.json in this repo.
+
+Repo-local only: writes only to workspace-relative manifest homes (.claude/, .cursor/,
+.github/, .codex/, .continue/), never to the user-home manifests self-evolve uses.`);
+  process.exit(0);
+}
+
+const command = process.argv[2] || 'check';
+const workspaceRoot = getWorkspaceRoot();
+
+if (command === 'check') {
+  runCheck(workspaceRoot);
+} else if (command === 'init') {
+  runInit(workspaceRoot, process.argv.slice(3));
+} else {
+  console.error(`[Project Docs Check] Unknown command "${command}". Use 'check' or 'init'.`);
+  process.exit(1);
+}

package/to-spec/templates/cli-reference.md

@@ -0,0 +1,31 @@
+# CLI / API Reference Template
+
+Use this shape when the artifact is documenting a new or changed command surface — a CLI command, flag set, or a single API endpoint. Lighter than `feature-spec.md`: no user stories, no seam-sketching. Fits Tier 2 work just as often as Tier 3.
+
+<spec-template>
+
+## Synopsis
+
+One-line usage form, e.g. `harness todo add <task> [--priority <n>]` or `POST /api/orders/:id/cancel`.
+
+## Description
+
+What this command/endpoint does and when you'd reach for it, from the caller's perspective.
+
+## Flags / Arguments / Parameters
+
+Each flag, positional argument, or request field: name, type, required/optional, default, what it controls.
+
+## Examples
+
+2-3 concrete invocations covering the common case and at least one edge case.
+
+## Exit Codes / Errors
+
+Every distinct exit code or error response: what triggers it, what the caller should do about it.
+
+## Related Commands / See Also
+
+Other commands/endpoints this one is commonly paired with, supersedes, or is superseded by.
+
+</spec-template>

package/to-spec/templates/dev-doc.md

@@ -0,0 +1,27 @@
+# Dev / Design Doc Template
+
+Use this shape for a scoped technical decision that doesn't rise to a full ADR (see `grill-with-docs`'s three-criteria test) but is still worth writing down before implementing — the kind of thing a Tier 2 task produces when it makes a real design call along the way.
+
+<spec-template>
+
+## Context
+
+What prompted this decision — the constraint, bug, or request behind it.
+
+## Decision
+
+What was decided, stated plainly.
+
+## Alternatives Considered
+
+Other options that were on the table and why they were passed over.
+
+## Trade-offs
+
+What this decision costs, even though it was the right call.
+
+## Rollout / Rollback
+
+How this ships (flag, gradual, all-at-once) and how to undo it if it's wrong.
+
+</spec-template>

package/to-spec/templates/feature-spec.md

@@ -0,0 +1,59 @@
+# Feature Spec (PRD) Template
+
+Use this shape when the artifact is a new feature, product surface, or anything with user-facing behavior and multiple implementation decisions to record. This is the heaviest template — reserve it for work that will get broken into tickets by `to-tickets` afterward.
+
+<spec-template>
+
+## Problem Statement
+
+The problem that the user is facing, from the user's perspective.
+
+## Solution
+
+The solution to the problem, from the user's perspective.
+
+## User Stories
+
+A LONG, numbered list of user stories. Each user story should be in the format of:
+
+1. As an <actor>, I want a <feature>, so that <benefit>
+
+<user-story-example>
+1. As a mobile bank customer, I want to see balance on my accounts, so that I can make better informed decisions about my spending
+</user-story-example>
+
+This list of user stories should be extremely extensive and cover all aspects of the feature.
+
+## Implementation Decisions
+
+A list of implementation decisions that were made. This can include:
+
+- The modules that will be built/modified
+- The interfaces of those modules that will be modified
+- Technical clarifications from the developer
+- Architectural decisions
+- Schema changes
+- API contracts
+- Specific interactions
+
+Do NOT include specific file paths or code snippets. They may end up being outdated very quickly.
+
+Exception: if a prototype produced a snippet that encodes a decision more precisely than prose can (state machine, reducer, schema, type shape), inline it within the relevant decision and note briefly that it came from a prototype. Trim to the decision-rich parts — not a working demo, just the important bits.
+
+## Testing Decisions
+
+A list of testing decisions that were made. Include:
+
+- A description of what makes a good test (only test external behavior, not implementation details)
+- Which modules will be tested
+- Prior art for the tests (i.e. similar types of tests in the codebase)
+
+## Out of Scope
+
+A description of the things that are out of scope for this spec.
+
+## Further Notes
+
+Any further notes about the feature.
+
+</spec-template>

package/to-spec/templates/schema-doc.md

@@ -0,0 +1,31 @@
+# Schema / File Format Template
+
+Use this shape when the artifact is documenting a data shape — a database schema change, a config file format, a wire payload, or an on-disk state file. Lighter than `feature-spec.md`: no user stories, no seam-sketching.
+
+<spec-template>
+
+## Purpose
+
+What this schema represents and why it exists, in one or two sentences.
+
+## Shape
+
+Every field: name, type, required/optional, constraints (enum values, ranges, format). A snippet is appropriate here — schemas are exactly the case where inlining the shape beats describing it in prose.
+
+## Versioning / Migration
+
+How a previous version maps to this one, if this is a change rather than a new schema. Whether old readers/writers still work, and for how long.
+
+## Validation Rules
+
+Constraints that span multiple fields, or that a type system alone can't express (e.g. "end_date must be after start_date").
+
+## Backward Compatibility
+
+What breaks for existing consumers, if anything, and what the mitigation is (dual-write, expand-contract, feature flag).
+
+## Example Payload
+
+One realistic, complete example instance of the schema.
+
+</spec-template>

package/to-tickets/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: to-tickets
+description: Break a to-spec feature-spec, a plan, or a conversation into tracer-bullet tickets with declared blocking edges — one file per ticket locally or issues on a real tracker via projectDocs. Use when an approved spec needs dependency-aware ordering.
+license: Apache-2.0
+metadata:
+  author: Miya Daniel
+  version: 0.3.4
+---
+
+# To Tickets
+
+Cuts a plan or spec into tracer-bullet vertical slices, each declaring its blockers.
+
+## USE FOR:
+- Break a spec or settled plan into tracer-bullet vertical slices
+- Declaring blocking edges and dependency order
+- Publishing tickets to local files or a tracker
+
+## DO NOT USE FOR:
+- Writing the feature spec itself — instead use `to-spec`
+- Trivial single-edit tasks needing no breakdown
+- Closing parent tracker issues
+
+## Skill Contract
+
+| Component | Specification |
+| :--- | :--- |
+| **Trigger / Input** | Explicit /to-tickets only; input: spec reference or plan in context. |
+| **Expected Output** | Tickets with What-to-build, Blocked-by, criteria — per projectDocs/convention/fallback. |
+| **State Mutations** | None to manifest.json (reads only); writes tickets at resolved location. |
+| **Enforcement Gate** | Run `node "to-spec/scripts/check-project-docs.js" check` if available; never block on Exit 1; MUST get user approval before publishing. |
+
+## Process
+
+1. Resolve path: script check (Exit 0 = configured location) → workspace convention dirs → platform fallback (`.claude`/`.github`/`.cursor` + `/harness-everything/tickets/`).
+2. Gather context: prefer a referenced to-spec spec — design-audit verification MANDATORY first, else refuse; no spec is fine.
+3. Explore codebase (optional): evidence-cited findings only; prefactor first.
+4. Draft vertical slices: complete path through every layer, demoable alone, one context window each; declare blocking edges.
+5. Quiz the user on granularity and edges until approved (MANDATORY gate).
+6. Publish per ticket: one `<NN>-<slug>.md` file or tracker issue, dependency order, ready-for-agent, blocking links. Work the frontier; never close parents.
+
+Deep dive: references/publishing-and-templates.md

package/to-tickets/references/publishing-and-templates.md

@@ -0,0 +1,97 @@
+# Storage Path Resolution & Publishing Detail (moved from SKILL.md)
+
+### 0. Resolve Storage Path & Framework (Gated Resolution Loop)
+
+Follow the decision matrix below to determine where ticket artifacts must be published:
+
+```mermaid
+flowchart TD
+    Start[Receive /to-tickets Request] --> CheckScript{1. Node.js & Script Executable?}
+    
+    CheckScript -- Yes --> RunCheck[Run check-project-docs.js check]
+    RunCheck -- Exit 0 (Configured) --> PathConfig[Use Project Configured Path<br>e.g. docs/roadmaps/, tracker, or .scratch/]
+    RunCheck -- Exit 1 (Unset) --> InspectRepo
+    
+    CheckScript -- No / Fails --> InspectRepo{2. Inspect Existing Workspace Conventions}
+    
+    InspectRepo -- Existing Folder Found --> PathRepo[Use Workspace Convention<br>e.g. docs/roadmaps/, docs/tickets/, tasks/tickets/]
+    InspectRepo -- No Conventional Folder --> CheckPlatform{3. Fallback to Active Platform Home}
+    
+    CheckPlatform -- Claude Code --> PathClaude[Write to .claude/harness-everything/tickets/]
+    CheckPlatform -- GitHub Copilot / VS Code --> PathCopilot[Write to .github/harness-everything/tickets/]
+    CheckPlatform -- Cursor / Other --> PathCursor[Write to .cursor/harness-everything/tickets/]
+    
+    PathConfig --> Draft
+    PathRepo --> Draft
+    PathClaude --> Draft
+    PathCopilot --> Draft
+    PathCursor --> Draft
+    Draft[Draft & Publish Tickets]
+```
+
+#### Path Resolution Rules:
+1. **Explicit Project Configuration (`projectDocs`)**: If `check-project-docs.js` returns `Exit 0`, use the configured `docLocation` or `tracker`.
+2. **Workspace Convention Inspection**: If unconfigured or script unavailable, check if any of these directories exist in the workspace:
+   - `docs/roadmaps/`
+   - `docs/tickets/`
+   - `tasks/tickets/`
+   - `.scratch/issues/`
+   If found, save tickets in the matching directory.
+3. **Platform Isolation Fallback**: If no directory convention exists, create and write ticket files inside the active IDE platform state folder:
+   - Claude Code: `.claude/harness-everything/tickets/<NN>-<slug>.md`
+   - GitHub Copilot: `.github/harness-everything/tickets/<NN>-<slug>.md`
+   - Cursor: `.cursor/harness-everything/tickets/<NN>-<slug>.md`
+
+# Wide Refactors: Expand-Contract Exception
+
+Give each ticket its **blocking edges** — the other tickets that must complete before it can start. A ticket with no blockers can start immediately.
+
+**Wide refactors are the exception to vertical slicing.** A **wide refactor** is one mechanical change — rename a column, retype a shared symbol — whose **blast radius** fans across the whole codebase, so a single edit breaks thousands of call sites at once and no vertical slice can land green. Don't force it into a tracer bullet; sequence it as **expand–contract**. First expand: add the new form beside the old so nothing breaks. Then migrate the call sites over in batches sized by blast radius (per package, per directory), each batch its own ticket blocked by the expand, keeping CI green batch to batch because the old form still exists. Finally contract: delete the old form once no caller remains, in a ticket blocked by every migrate batch. When even the batches can't stay green alone, keep the sequence but let them share an integration branch that all block a final integrate-and-verify ticket — green is promised only there.
+
+# Ticket Templates
+
+<local-ticket-template>
+
+# <NN> — <Ticket title>
+
+**What to build:** the end-to-end behaviour this ticket makes work, from the user's perspective — not a layer-by-layer implementation list.
+
+**Blocked by:** the numbers/titles of the tickets that gate this one, or "None — can start immediately".
+
+**Status:** ready-for-agent
+
+- [ ] Acceptance criterion 1
+- [ ] Acceptance criterion 2
+
+</local-ticket-template>
+
+<issue-template>
+
+## Parent
+
+A reference to the parent issue/spec on the tracker (the `to-spec` feature spec this came from, if any — otherwise omit this section).
+
+## What to build
+
+The end-to-end behaviour this ticket makes work, from the user's perspective — not layer-by-layer implementation.
+
+## Acceptance criteria
+
+- [ ] Criterion 1
+- [ ] Criterion 2
+
+## Blocked by
+
+- A reference to each blocking ticket, or "None — can start immediately".
+
+</issue-template>
+
+In either form, avoid specific file paths or code snippets — they go stale fast. Exception: if a prototype produced a snippet that encodes a decision more precisely than prose can (state machine, reducer, schema, type shape), inline it and note briefly that it came from a prototype. Trim to the decision-rich parts — not a working demo, just the important bits.
+
+# Gather-Context Notes
+
+If the referenced doc is a cli-reference, schema-doc, or dev-doc (a lighter to-spec shape, not a feature-spec), it is usually already ticket-sized on its own — confirm with the user whether it needs splitting before drafting.
+
+# Evidence Format (Zero-Trust Exploration)
+
+Every finding must cite explicit evidence: `Evidence: [File path & line number / Tool output] -> Finding: [What it means]`. Never guess codebase layout or dependencies.

package/todo-driven-workflow/SKILL.md

@@ -1,54 +1,40 @@
----
-name: todo-driven-workflow
-description: Enforces a deliberate, step-by-step execution loop.
-author: Miya Daniel | Harness Core Team
-version: 1.1.0
-metadata:
-  type: harness-discipline
----
-
-# Todo-Driven Workflow (以 TODO 驅動的自動化工作流)
-
-## 📋 Skill Contract
-
-| Component | Specification |
-| :--- | :--- |
-| **Trigger / Input** | Tier 2/3 Task Identification. Input: High-level task description. |
-| **Expected Output** | Granular execution state. A series of terminal calls to `todo-cli.js`. |
-| **State Mutations** | MUST write to `.claude/harness-state/todo-state.json` via CLI. |
-| **Enforcement Gate** | `node harness-everything/scripts/todo-cli.js`. Exits with Code 1 if multitasking, bypassing initialization, or skipping `verify-gate.js`. |
-
-This skill enforces a disciplined execution loop. It prevents "hallucinated progress" by forcing the Agent to track exact state and prove completion before moving to the next step. 
-
----
-
-## ⚡ Core Trigger (觸發時機)
-This workflow is **the default operating behavior** for any complex, multi-step, or multi-file development tasks (Tier 2 and Tier 3).
-
-## ⚙️ Execution Method
-
-| Environment | Primary Task Tracker | Implementation Method |
-| :--- | :--- | :--- |
-| **All Environments** | `todo-cli.js` | You MUST use `node harness-everything/scripts/todo-cli.js` for all state transitions. Do NOT rely on prompt text. |
-
----
-
-## 🔄 Execution Loop: Think > Try > Summarize > Record
-
-### 1. Analyze and Plan (Think)
-Break the high-level goal into **3 to 7 concrete, verifiable sub-tasks**.
-
-### 2. Initialize the Todo List (Record)
-- **CRITICAL ACTION**: You MUST use the `run_in_terminal` tool to run `node harness-everything/scripts/todo-cli.js init "Task 1" "Task 2"` BEFORE modifying any code.
-- *Rule*: The terminal output will confirm the list is initialized.
-
-### 3. Step-by-Step Execution
-1. **Start**: Use `run_in_terminal` to run `node harness-everything/scripts/todo-cli.js start <id>`. **If you try to start two tasks, the script will crash and block you.**
-2. **Execute**: Perform the necessary actions (read files, grep, run terminal commands, edit files).
-3. **Verify**: The validation gate is hardcoded into the completion step.
-4. **Complete**: Use `run_in_terminal` to run `node harness-everything/scripts/todo-cli.js complete <id>`. If the internal `verify-gate.js` check fails, this command will Exit 1 and block you.
-
-### 4. Handling Blocker Failures (Dynamic Adaptation)
-If a step fails:
-- Use `node harness-everything/scripts/todo-cli.js add "Fix specific error"` to insert a blocker.
-- Do NOT silently ignore or bypass the error.
+---
+name: todo-driven-workflow
+description: "Enforce a deliberate step-by-step execution loop for complex multi-step or multi-file tasks (Tier 2/3), one sub-task in-progress at a time. USE FOR: \"track a complex multi-step task as todos\", \"work through a multi-file refactor step by step\". DO NOT USE FOR: \"trivial single-file edits\", \"quick questions without implementation\"."
+license: Apache-2.0
+metadata:
+  author: Miya Daniel
+  version: 0.3.5
+---
+
+# Todo-Driven Workflow
+
+Single-task milestones prevent context drift in Tier 2/3 work.
+
+## USE FOR:
+- Track multi-step, multi-file development tasks
+- Enforce exactly one active milestone
+
+## DO NOT USE FOR:
+- Trivial single-file edits
+- Parallel sub-agent state without worktree isolation (`using-git-worktrees`)
+
+## Skill Contract
+
+| Component | Specification |
+| :--- | :--- |
+| **Trigger / Input** | Tier 2/3 task with a high-level description. |
+| **Expected Output** | Native TODO state or a Markdown checklist with verifiable milestones. |
+| **State Mutations** | Host-native TODO state or `tasks/todo.md` / `.github/harness-everything/todo.md`. |
+| **Enforcement Gate** | Exactly one milestone is `in-progress`; verify before marking it complete. |
+
+## Execution Loop: Think > Try > Summarize > Record
+
+1. [Think] State the goal and split it into 3-7 checkable milestones.
+2. [Record] Initialize the native host tracker before edits; if unavailable, create a Markdown checklist.
+3. Start exactly one milestone, execute only its scope, and run its named check.
+4. Mark it complete only after evidence passes; then start the next milestone.
+5. Record blockers in the checklist and escalate after the applicable circuit-breaker threshold.
+
+Native TODO tools take priority. Markdown is the portable fallback; this skill
+does not depend on a repository CLI state machine. See `references/execution-guide.md`.