harness-everything 0.3.6 → 0.4.0

package/plugins/harness-everything/skills/to-spec/scripts/check-project-docs.js

@@ -0,0 +1,239 @@
+#!/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');
+// Keep project-doc path decisions in the resolver carried by the installed
+// multi-agent-workspace skill. This script consumes the same contract.
+const { getWorkspaceRoot, getRepoManifestHomes, detectProjectDocsConventions } =
+  require('./project-docs-resolver');
+
+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) {}
+  }
+  // A standalone installed skill may not carry the package helper. Keep its
+  // manifest format compatible with the package's tiny helper instead of
+  // making document resolution depend on the source checkout.
+  return {
+    getManifestPath: home => path.join(home, 'harness-everything', 'manifest.json'),
+    readManifest: file => {
+      try {
+        const data = JSON.parse(fs.readFileSync(file, 'utf8'));
+        if (!Array.isArray(data.skills)) data.skills = [];
+        if (!Array.isArray(data.agents)) data.agents = [];
+        return data;
+      } catch {
+        return { package: 'harness-everything', skills: [], agents: [] };
+      }
+    },
+    writeManifest: (file, data) => {
+      fs.mkdirSync(path.dirname(file), { recursive: true });
+      fs.writeFileSync(file, JSON.stringify(data, null, 2), 'utf8');
+    }
+  };
+}
+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;
+
+function missingFields(projectDocs) {
+  if (!projectDocs) return REQUIRED_FIELDS.slice();
+  return REQUIRED_FIELDS.filter(f => !String(projectDocs[f] || '').trim());
+}
+
+function detectWorkspaceConventions(workspaceRoot) {
+  return detectProjectDocsConventions(workspaceRoot);
+}
+
+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 commandArgs = process.argv.slice(3);
+const workspaceIndex = commandArgs.indexOf('--workspace');
+// An explicit workspace is authoritative. Only the omitted flag walks up to
+// the repository root; otherwise a nested target would silently resolve to
+// its containing checkout and inspect the wrong project configuration.
+if (workspaceIndex !== -1 && !commandArgs[workspaceIndex + 1]) {
+  console.error('[Project Docs Check] --workspace requires a path');
+  process.exit(1);
+}
+const workspaceRoot = workspaceIndex === -1
+  ? getWorkspaceRoot()
+  : path.resolve(commandArgs[workspaceIndex + 1]);
+if (!workspaceRoot) {
+  console.error('[to-spec/check-project-docs] Cannot inspect project docs without a resolved git workspace.');
+  process.exit(1);
+}
+
+if (command === 'check') {
+  runCheck(workspaceRoot);
+} else if (command === 'init') {
+  runInit(workspaceRoot, commandArgs);
+} else {
+  console.error(`[Project Docs Check] Unknown command "${command}". Use 'check' or 'init'.`);
+  process.exit(1);
+}

package/plugins/harness-everything/skills/to-spec/scripts/project-docs-resolver.js

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+'use strict';
+
+// In the source tree this is the single shared resolver. A to-spec-only
+// installation has no sibling multi-agent skill, so its fallback preserves
+// the same explicit/inferred/fallback provenance contract locally.
+try {
+  module.exports = require('../../multi-agent-workspace/scripts/project-docs-resolver');
+} catch (error) {
+  const fs = require('fs');
+  const os = require('os');
+  const path = require('path');
+  const crypto = require('crypto');
+  const PLATFORM_HOMES = Object.freeze(['.claude', '.cursor', '.github', '.codex', '.continue']);
+  function getWorkspaceRoot(start = process.cwd()) {
+    let dir = path.resolve(start);
+    while (dir !== path.parse(dir).root) {
+      if (fs.existsSync(path.join(dir, '.git'))) return dir;
+      dir = path.dirname(dir);
+    }
+    return path.resolve(start);
+  }
+  function getRepoManifestHomes(root) { return PLATFORM_HOMES.map(home => path.join(root, home)); }
+  function readProjectDocs(root) {
+    for (const home of getRepoManifestHomes(root)) {
+      const file = path.join(home, 'harness-everything', 'manifest.json');
+      try {
+        const data = JSON.parse(fs.readFileSync(file, 'utf8'));
+        if (data.projectDocs) return { file, projectDocs: data.projectDocs };
+      } catch { /* not bootstrapped or invalid; the check command reports it */ }
+    }
+    return null;
+  }
+  function getWorkspaceKey(root) {
+    let real = path.resolve(root);
+    try { real = fs.realpathSync(real); } catch { /* best effort */ }
+    const slug = path.basename(real).toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '') || 'workspace';
+    return `${slug}-${crypto.createHash('sha1').update(real).digest('hex').slice(0, 12)}`;
+  }
+  function getStateHome() { return process.env.HARNESS_STATE_HOME || path.join(os.homedir(), '.agents', 'harness-everything'); }
+  function getRuntimeRoot(root) { return path.join(getStateHome(), 'workspaces', getWorkspaceKey(root), 'multi-agent'); }
+  function resolveProjectDocs(root) {
+    const workspaceRoot = path.resolve(root);
+    const manifest = readProjectDocs(workspaceRoot);
+    const docs = manifest ? manifest.projectDocs : {};
+    const fields = {
+      decision: ['decisionLocation', 'decisions', 'adrLocation', 'adr'],
+      domain: ['domainLocation', 'domains', 'contextLocation', 'contexts', 'domain'],
+      architecture: ['architectureLocation', 'architectures', 'architecture']
+    };
+    const conventional = {
+      decision: ['docs/adr', 'docs/decisions', 'adr', 'decisions'],
+      domain: ['docs/domain', 'docs/contexts', 'domain', 'contexts'],
+      architecture: ['docs/architecture', 'architecture']
+    };
+    const fallback = { decision: 'docs/adr', domain: 'docs/domain', architecture: 'docs/architecture' };
+    const paths = {};
+    for (const zone of Object.keys(fields)) {
+      let selected = null;
+      for (const field of fields[zone]) {
+        if (typeof docs[field] === 'string' && docs[field].trim()) {
+          selected = { path: path.resolve(workspaceRoot, docs[field]), source: 'projectDocs', resolution: 'explicit', field };
+          break;
+        }
+      }
+      if (!selected && docs.docLocation) {
+        const base = path.resolve(workspaceRoot, docs.docLocation);
+        const names = { decision: ['adr', 'decisions'], domain: ['domain', 'contexts'], architecture: ['architecture'] }[zone];
+        selected = { path: names.includes(path.basename(base).toLowerCase()) ? base : path.join(base, names[0]), source: 'projectDocs', resolution: 'inferred' };
+      }
+      if (!selected) {
+        const existing = conventional[zone].map(item => path.join(workspaceRoot, item)).find(item => {
+          try { return fs.statSync(item).isDirectory(); } catch { return false; }
+        });
+        if (existing) selected = { path: existing, source: 'inference', resolution: 'inferred' };
+      }
+      if (!selected) selected = { path: path.join(workspaceRoot, fallback[zone]), source: 'fallback', resolution: 'fallback' };
+      paths[zone] = { path: path.resolve(selected.path), relativePath: path.relative(workspaceRoot, selected.path).replace(/\\/g, '/'), source: selected.source, resolution: selected.resolution || selected.source, origin: selected.source, ...(selected.field ? { field: selected.field } : {}) };
+    }
+    const runtimeRoot = getRuntimeRoot(workspaceRoot);
+    return {
+      workspaceRoot,
+      workspaceKey: getWorkspaceKey(workspaceRoot),
+      stateHome: getStateHome(),
+      runtimeRoot,
+      runtime: { root: runtimeRoot, state: path.join(runtimeRoot, 'state'), logs: path.join(runtimeRoot, 'logs'), roles: path.join(runtimeRoot, 'roles') },
+      projectDocs: manifest ? { ...manifest.projectDocs, manifestPath: manifest.file } : null,
+      paths,
+      decisions: paths.decision,
+      domains: paths.domain,
+      architectures: paths.architecture
+    };
+  }
+  function detectProjectDocsConventions(root) {
+    const workspaceRoot = path.resolve(root);
+    const configured = readProjectDocs(workspaceRoot);
+    const inferred = configured && configured.projectDocs && configured.projectDocs.docLocation
+      ? { docLocation: configured.projectDocs.docLocation } : {};
+    if (!inferred.docLocation) {
+      for (const dir of ['docs/roadmaps', 'docs/reference', 'docs/specs', 'docs', 'doc']) {
+        if (fs.existsSync(path.join(workspaceRoot, dir))) { inferred.docLocation = `${dir}/`; break; }
+      }
+    }
+    if (fs.existsSync(path.join(workspaceRoot, '.github', 'ISSUE_TEMPLATE'))) inferred.tracker = 'GitHub Issues via .github/ISSUE_TEMPLATE/';
+    else if (inferred.docLocation) inferred.tracker = `${inferred.docLocation}tickets/ local markdown tickets`;
+    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;
+  }
+  module.exports = { PLATFORM_HOMES, getWorkspaceRoot, getStateHome, getRuntimeRoot, getWorkspaceKey, getRepoManifestHomes, readProjectDocs, resolveProjectDocs, detectProjectDocsConventions, ensureCommittableFallback: resolution => resolution };
+}

package/plugins/harness-everything/skills/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/plugins/harness-everything/skills/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/plugins/harness-everything/skills/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/plugins/harness-everything/skills/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/plugins/harness-everything/skills/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.4.0
+---
+
+# 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 "<skills-repo-root>/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 one file or issue per ticket in dependency order; work the frontier; never close parents.
+
+Deep dive: <this-skill-dir>/references/publishing-and-templates.md

package/plugins/harness-everything/skills/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.