@dombaras/agent-harness 0.1.6 → 0.1.8

package/README.md

@@ -34,10 +34,11 @@ npx @dombaras/agent-harness init --target . --dry-run
 | Path | Content | Ownership |
 |---|---|---|
 | `AGENTS.md` | root dispatcher (points to the rulebook) | harness (overwrite) |
-| `.opencode/agents/*.md` | 13 persona subagent defs (with `model:` pins + `permission`/`steps`/`temperature`/`hidden`) | harness (overwrite) |
+| `.opencode/agents/*.md` | 14 persona subagent defs (with `model:` pins + `permission`/`steps`/`temperature`/`hidden`) | harness (overwrite) |
 | `.agents/AGENTS.md` | full canonical operating rulebook | harness (overwrite) |
 | `.agents/rules/00-operating.md` | always-loaded rules summary (wired into `opencode.json` `instructions`) | harness (overwrite) |
 | `.agents/skills/*/SKILL.md` | persona instruction skills | harness (overwrite) |
+| `.agents/features/INDEX.md` | feature backlog + status board (durable feature doc tree root) | **project** (create-if-missing) |
 | `opencode.json` | main/small model routing + `instructions` | harness (**merged**, see below) |
 | `scripts/qa/*` | `test:dispatch` / `test:governance` / `test:qa-plan` gates + QA-script wiring check | harness (overwrite) |
 | `.agents/memory/*` | project data (domain-map, stack-versions, handoff, locations, model-routing, history, flow-map, qa-plan) | **project** (create-if-missing) |
@@ -59,6 +60,17 @@ tiers, trust tiers) live in `.agents/memory/domain-map.md`, which `init`
 scaffolds for you to fill in — the skills and rules reference memory instead of
 hardcoding domain assumptions.
 
+**Features (`.agents/features/`)** — the durable, feature-centric plan of record. A
+found item is captured as one light row in `.agents/features/INDEX.md` (backlog: what's
+known, priority, context, status). When a feature is picked up, the `features` persona
+authors the per-feature doc chain (`.agents/features/<slug>/`), each layer routed to its
+author persona — `intent.md` (product-manager) → `scope.md` (system-architect, HIGH-risk
+only) → `plan.md` (planner) → `tests.md` (qa-architect, points to `qa-plan.md`). Ceremony
+is right-sized to blast radius: trivial → none, low → single `intent.md`, high (auth/DB/
+public API/flow-siblings) → full chain. Docs live beside the code, are written-back before
+continuing when implementation invalidates them, and are archived on ship. See
+`.agents/skills/features/SKILL.md`.
+
 **Flow map (`.agents/memory/flow-map.md`)** — the project-owned registry powering the
 flow-closure half of `test:qa-plan`. Each user-facing flow lists the code surfaces that
 implement the same behavior across codebases/layers (e.g. web component, `mobile/` sheet,
@@ -123,6 +135,10 @@ npx @dombaras/agent-harness update --target /path/to/project
   modified harness files. Your unrelated uncommitted work is never staged.
   - `--no-commit` to skip commit+push, `--no-push` to commit but not push.
   - `init` never commits.
+  - Harness-owned paths are **force-added**, so a project that gitignores deployment
+    artifacts (an inherited `.agents/` `.opencode/` `AGENTS.md` pattern) still gets the
+    harness commit instead of a raw `git add` failure that silently skips it — force-added
+    files are called out in the summary.
 - **`[Nothing-to-Update]` confirmation**: if the target is already at this CLI's version and no
   harness-owned file changed, `update` says so explicitly, writes nothing, and makes no commit —
   a no-op is never mistaken for a sync and never churns `.harness.json`.

package/bin/agent-harness.js

@@ -15,7 +15,7 @@
  * PROJECT_NAME }} / {{ PROJECT_DOMAIN }}.
  *
  * Ownership model:
- *   - `.agents/memory/*` is project data -> create-if-missing (never overwrite).
+ *   - `.agents/memory/*` + `.agents/features/*` is project data -> create-if-missing (never overwrite).
  *   - `opencode.json` is MERGED: harness manages $schema/model/small_model/
  *     instructions; every other key the project adds is preserved.
  *   - all other harness-owned files are overwritten. If a harness-owned file was
@@ -89,9 +89,19 @@ function relKey(rel) {
   return rel.split(path.sep).join("/");
 }
 
-function isMemoryFile(rel) {
+/* `.agents/memory/*` (session memory) and `.agents/features/*` (feature doc
+ * tree) are project data — scaffolded create-if-missing, never overwritten,
+ * and never tracked in the manifest, exactly like the memory files. */
+function isProjectScaffold(rel) {
   const parts = rel.split(path.sep);
-  return parts.includes(".agents") && parts.includes("memory");
+  return (
+    parts.includes(".agents") &&
+    (parts.includes("memory") || parts.includes("features"))
+  );
+}
+/* Back-compat alias (kept for any external caller referencing the old name). */
+function isMemoryFile(rel) {
+  return isProjectScaffold(rel);
 }
 
 function isOpencodeJson(rel) {
@@ -210,9 +220,12 @@ function isGitRepo(target) {
 // project's next session never sees "unexplained" modified harness files. Scoped
 // to this run's changed harness files (never `git add -A`) so unrelated uncommitted
 // work is NEVER swept in. Memory/backup files are excluded (project data / rollback).
-// Returns { committed:boolean, staged:string[], skipped:string[], pushed:boolean|null }.
+// Harness-owned paths are force-added (`-f`): target projects often gitignore
+// .agents/ .opencode/ AGENTS.md (inherited from the harness's own .gitignore), and
+// a plain `git add` would fail on the first ignored path and commit NOTHING.
+// Returns { committed:boolean, staged:string[], skipped:string[], pushed:boolean|null, forceAdded:string[] }.
 function commitHarnessChanges(target, changedRels, opts) {
-  const out = { committed: false, staged: [], skipped: [], pushed: null };
+  const out = { committed: false, staged: [], skipped: [], pushed: null, forceAdded: [] };
   if (!opts.commit) return out;
   if (!isGitRepo(target)) {
     out.skipped.push("not a git repo");
@@ -222,9 +235,13 @@ function commitHarnessChanges(target, changedRels, opts) {
     out.skipped.push("no harness files changed");
     return out;
   }
-  const addR = runGit(target, ["add", "--", ...changedRels]);
+  const ignored = runGit(target, ["check-ignore", ...changedRels]);
+  if (ignored.ok && ignored.out) {
+    out.forceAdded = ignored.out.split(/\r?\n/).filter(Boolean).map(relKey);
+  }
+  const addR = runGit(target, ["add", "-f", "--", ...changedRels]);
   if (!addR.ok) {
-    out.skipped.push("git add failed: " + addR.err);
+    out.skipped.push("git add failed: " + firstGitErrorLine(addR.err));
     return out;
   }
   const diffCached = runGit(target, ["diff", "--cached", "--name-only"]);
@@ -238,7 +255,7 @@ function commitHarnessChanges(target, changedRels, opts) {
   const message = `chore(harness): @dombaras/agent-harness ${prior}${PKG.version}`;
   const commitR = runGit(target, ["commit", "-m", message]);
   if (!commitR.ok) {
-    out.skipped.push("commit failed: " + commitR.err);
+    out.skipped.push("commit failed: " + firstGitErrorLine(commitR.err));
     return out;
   }
   out.committed = true;
@@ -247,7 +264,7 @@ function commitHarnessChanges(target, changedRels, opts) {
     if (hasRemote) {
       const pushR = runGit(target, ["push", "origin", "HEAD"]);
       out.pushed = pushR.ok;
-      if (!pushR.ok) out.skipped.push("push failed: " + pushR.err);
+      if (!pushR.ok) out.skipped.push("push failed: " + firstGitErrorLine(pushR.err));
     } else {
       out.skipped.push("no git remote to push");
     }
@@ -255,6 +272,16 @@ function commitHarnessChanges(target, changedRels, opts) {
   return out;
 }
 
+/* Pull the first real error line out of git's stderr, dropping the LF/CRLF
+ * warnings and `hint:` noise that bury the actual message. */
+function firstGitErrorLine(err) {
+  const line = String(err || "")
+    .split(/\r?\n/)
+    .map((l) => l.trim())
+    .find((l) => l && !/^warning:/i.test(l) && !/^hint:/i.test(l));
+  return line || "git command failed";
+}
+
 // ---------------------------------------------------------------- deploy
 
 function backup(target, rel, content) {
@@ -323,7 +350,7 @@ async function deploy(target, opts) {
       continue;
     }
 
-    if (isMemoryFile(rel)) {
+    if (isProjectScaffold(rel)) {
       if (fs.existsSync(targetAbs)) {
         actions.push({ rel: key, kind: "preserve" });
       } else {
@@ -386,7 +413,10 @@ async function deploy(target, opts) {
   let commitResult = null;
   if (isUpdate && !dryRun && !nothingToUpdate) {
     const changedRels = changedRelsAll.filter(
-      (r) => !r.startsWith(".agents/memory/") && !r.startsWith(".harness-backup/")
+      (r) =>
+        !r.startsWith(".agents/memory/") &&
+        !r.startsWith(".agents/features/") &&
+        !r.startsWith(".harness-backup/")
     );
     changedRels.push(CONFIG_FILE); // .harness.json reflects the new deployed version
     commitResult = commitHarnessChanges(target, changedRels, {
@@ -464,7 +494,9 @@ function printNextSteps() {
   console.log("      test:qa-plan enforces their sibling-surface/variant closure).");
   console.log("   2. Harness gate scripts (`test:dispatch`, `test:governance`, `test:qa-plan`) were");
   console.log('      auto-wired into package.json "scripts".');
-  console.log("   3. Restart your agent CLI (config is read once at startup).\n");
+  console.log("   3. Capture found items as rows in `.agents/features/INDEX.md`; dispatch the `features`");
+  console.log("      persona to author the per-feature doc chain when one is picked up.");
+  console.log("   4. Restart your agent CLI (config is read once at startup).\n");
 }
 
 function printUsage() {
@@ -537,6 +569,12 @@ function printCommitResult(result) {
   console.log("");
   if (c.committed) {
     console.log("  committed harness files: " + c.staged.join(", "));
+    if (c.forceAdded.length) {
+      console.log(
+        "  force-added (gitignored in this project, but harness-owned): " +
+          c.forceAdded.join(", ")
+      );
+    }
     console.log(
       c.pushed === true
         ? "  pushed to origin."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dombaras/agent-harness",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "Reusable multi-agent harness for AI-assisted development: personas, skills, operating rules, model routing, and QA gates. Deploy into any project with `npx @dombaras/agent-harness init`.",
   "bin": {
     "agent-harness": "bin/agent-harness.js"

package/templates/.agents/AGENTS.md

@@ -55,6 +55,16 @@ The canonical rulebook. The always-loaded summary is `.agents/rules/00-operating
     | Data ingestion / entity resolution | `data-engineer` |
     | Deployment / cron / secrets / build+release | `devops-engineer` |
     | Session wrap-up / handoff | `handoff` |
+    | Feature backlog + per-feature doc tree (intent/scope/plan/tests) | `features` |
+  - **Feature docs, not ceremony**: capture a found item as one light row in
+    `.agents/features/INDEX.md` (backlog). When a feature is picked up, dispatch
+    `features` to author the doc chain — `intent` (product-manager) → `scope`
+    (system-architect, HIGH-risk only) → `plan` (planner) → `tests` (qa-architect) —
+    each by its author persona. Match ceremony to blast radius: trivial → none,
+    low → single `intent.md`, high (auth/DB/API/flow-siblings) → full chain. Write
+    back first (update the doc before continuing when implementation invalidates it),
+    archive on ship. Feature docs are durable and complementary to the per-session
+    `qa-plan.md`/`handoff.md`; the `tests` doc points to `qa-plan.md`, never duplicates it.
   - **QA planning is never optional (no silent skip)**: every change that touches
     code paths MUST get a QA plan before it is verified. The plan is authored by
     `qa-architect` (thinker). If `qa-architect` is not dispatched — for ANY reason,

package/templates/.agents/features/INDEX.md

@@ -0,0 +1,22 @@
+# Features — backlog & status board
+
+Project-owned (like all `.agents/features/*`). This is the **collection box**, not a
+spec and not a status board. Every found item gets one terse row here; the per-feature
+doc chain (`.agents/features/<slug>/` intent · scope · plan · tests) is written only
+when the main agent focuses on the feature. Keep rows ultra-light — a note, not a promise.
+
+Maintained by the `features` persona (`.agents/skills/features/SKILL.md`).
+
+## Backlog
+
+One row per found item. `Status`: `backlog → ready → in-progress → testing → shipped → archived`.
+
+| ID | Item (what's known so far) | Priority | Context | Status |
+|----|----------------------------|----------|---------|--------|
+| F-001 | _replace: short, only-what-is-known description; open questions with `?`_ | P3 | _pointer to evidence (file/log/ticket/words), not a re-derivation_ | backlog |
+
+<!-- Add rows as items surface. Never invent status or priority — leave blank/`?` if unknown. -->
+
+## Active / next
+
+- _when a feature is about to be worked, cite it here and route the docs to the author personas (see skill)._

package/templates/.agents/memory/model-routing.md

@@ -27,6 +27,7 @@ frontmatter:
 - **Thinkers** (`planner`, `product-manager`) have `permission: { edit: deny, bash: deny }`.
 - **`qa-architect`** has `permission: { bash: deny }` (authors tests, never runs).
 - **`handoff`** has `permission: { bash: deny }`.
+- **`features`** (Feature Registrar) has `permission: { bash: deny }` — owns `.agents/features/*` (backlog + per-feature docs), routes each doc layer to its author persona.
 - **Code personas** (`frontend-engineer`, `mobile-engineer`, `ui-designer`,
   `data-engineer`, `devops-engineer`, `security-engineer`, `system-architect`,
   `diagnostics-expert`) allow `edit` everywhere except governance/harness paths

package/templates/.agents/rules/00-operating.md

@@ -11,6 +11,7 @@ Before reading or editing any file for a task, dispatch the relevant personas vi
 - **Accept, don't trust.** After a code persona reports done, the orchestrator re-runs the gate itself (`tsc --noEmit`, `lint:hooks`, `test:quick`) and greps the metric before integrating — a subagent's `Evidence` is a claim, not proof.
 - **QA planning is never optional.** Every change touching code paths gets a QA plan (coverage map in `.agents/memory/qa-plan.md`) from `qa-architect`; if it isn't dispatched, the main orchestrator plans in its place. `npm run test:qa-plan` fails on any changed code path with no covering assertion or waiver, and on any touched flow (`.agents/memory/flow-map.md`) whose sibling surfaces / declared variants the plan doesn't address.
 - Persona map, waivers, and the dispatch-failure ladder: `.agents/AGENTS.md` §5 and `.agents/memory/model-routing.md`.
+- **Features**: capture a found item as one light row in `.agents/features/INDEX.md`; on pickup dispatch `features` to author the per-feature doc chain (`.agents/skills/features/SKILL.md`). Right-size ceremony to risk.
 - Every subagent returns the output contract (`Result` → `Evidence` → `Deferred & risks`).
 - Wrap up with a **dispatch log** (`subagent → model → shipped/deferred`) in `.agents/memory/handoff.md`.
 

package/templates/.agents/skills/features/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: features
+description: Use when the user asks to capture a found item, register a feature, manage the feature backlog, or prepare a feature for implementation — owns the .agents/features/ doc tree (INDEX + per-feature intent/scope/plan/tests).
+model: mechanical
+---
+
+# Features — backlog & per-feature doc tree
+
+You are the Feature Registrar for {{PROJECT_NAME}}. You keep the
+`.agents/features/` tree as the durable, feature-centric plan of record — the
+backlog of found items plus, once a feature is picked up, the intent → scope →
+plan → tests docs that frame it. You coordinate the authors; you do NOT pull the
+implementation work onto yourself (that is dispatched to the code personas).
+
+The doc tree is **complementary** to the session memory (`.agents/memory/*`):
+features are durable and survive across sessions; `handoff.md`/`qa-plan.md` track
+per-session execution. Link between them, never duplicate.
+
+## Two layers — do not cross them
+
+| Layer | What it is | Weight |
+|---|---|---|
+| **Backlog** (`.agents/features/INDEX.md`) | collection box of found items — one short row per item (what's known, priority, context, status). NOT a spec, NOT a status board. | ultra-light — every item gets one |
+| **Feature docs** (`.agents/features/<slug>/` intent · scope · plan · tests) | the contract, written ONLY when the main agent focuses on the feature. | right-sized to risk |
+
+A found item is **only** ever a backlog row until it is picked up. Do not
+pre-write the full chain for every item — that is exactly what turns this into
+the heavy SDLC the harness is designed to avoid.
+
+## Tree layout
+
+```
+.agents/features/
+  INDEX.md                 # backlog + status board (one row per item)
+  <slug>/
+    intent.md              # what & why, boundaries, acceptance criteria (1 pager)
+    scope.md               # optional — only on HIGH-risk features
+    plan.md                # implementation decomposition (HOW)
+    tests.md               # intent-level acceptance + pointer to qa-plan.md
+  archive/                 # completed feature dirs moved here
+```
+
+Save docs beside the code they describe; keep them in the same commit as the
+code that implements them so a feature's intent and its delivery cannot drift.
+
+## Backlog — `.agents/features/INDEX.md`
+
+One row per found item. Add a row when the user brings up a new idea/need/bug
+that is not yet being worked. Fields (keep each terse):
+
+- **What's known so far** — only what is actually known; mark open questions with `?`.
+- **Priority** — `P0` (blocking) / `P1` (important) / `P2` (nice-to-have) / `P3` (backlog).
+- **Context** — a pointer to evidence (file, log, ticket, the user's words), never a re-derivation.
+- **Status** — `backlog → ready → in-progress → testing → shipped → archived`.
+
+Never invent status or priority. If a field is unknown, leave it blank or `?` and
+say so; the row is a note, not a promise.
+
+## Feature lifecycle (when the main agent focuses on a feature)
+
+Pick the ready item from `INDEX.md`, then author the docs **by routing each layer
+to the correct persona** via the `task` tool (Step Zero dispatch — see
+`.agents/rules/00-operating.md` §Step Zero):
+
+| Doc | Frames | Author persona (dispatch) |
+|---|---|---|
+| `intent.md` | WHAT & WHY: outcomes, boundaries/out-of-scope, acceptance criteria, open questions | `product-manager` |
+| `scope.md` | technical constraints, blast radius, data-model/API impact | `system-architect` (only on HIGH-risk features) |
+| `plan.md` | HOW: ordered steps, owned files, per-step verification, commit boundaries | `planner` |
+| `tests.md` | intent-level acceptance — the minimal tier + progression tests; **points to** `.agents/memory/qa-plan.md`, never duplicates it | `qa-architect` |
+
+### Right-size the ceremony to blast radius
+
+- **Trivial** (copy/docs, CSS tweak, single-file bug, anything a human would fix
+  in <30 minutes): no feature docs. Optionally note it in `INDEX.md` and close it.
+- **Low risk** (touches few files, no auth/DB/API contract): ONE `intent.md`
+  (what & why, boundaries, acceptance) is enough. Fold scope into it.
+- **High risk** (auth/security, DB schema/migration, public API, payments, a flow
+  with cross-surface siblings from `.agents/memory/flow-map.md`): full chain —
+  `intent.md` + `scope.md` + `plan.md` + `tests.md`.
+
+Split `scope.md` out of `intent.md` only when the feature earns it (above). Two
+docs restating the same boundary is drift surface, not rigor.
+
+## Keeping docs current (non-negotiable)
+
+- **Write back first, then continue.** If implementation invalidates any doc,
+  update the doc BEFORE coding continues. A stale spec is worse than none.
+- **Archive when it ships.** Move `.agents/features/<slug>/` to `archive/` and
+  mark the `INDEX.md` row `shipped`/`archived`. Do not leave a pile of completed
+  designs cluttering the live tree.
+- Each doc starts with a `status:` line (`proposed → scoped → planned → testing →
+  shipped → archived`) so an agent knows validity without reading the whole file.
+- When implementation drifts from a doc, fix the implementation to match the
+  doc; when the doc is genuinely wrong, update the doc explicitly (with a one-line
+  note in `INDEX.md`), then regenerate the derived layers — never let the code
+  and the doc mutely diverge.
+
+## Output contract (always return)
+
+1. **Backlog delta** — items added / status changes, in `.agents/features/INDEX.md`.
+2. **Docs authored** — which feature docs were created/updated, by which dispatched persona.
+3. **Deferred & risks** — features parked, open questions, and what the orchestrator must route next.

package/templates/.opencode/agents/features.md

@@ -0,0 +1,20 @@
+---
+description: Use when the user asks to capture a found item, register/manage a feature, or prepare a feature for implementation — owns the .agents/features/ doc tree (INDEX backlog + per-feature intent/scope/plan/tests) and routes each layer to its author persona.
+mode: subagent
+model: opencode/gpt-5-nano
+temperature: 0.1
+steps: 15
+hidden: true
+permission:
+  bash: deny
+---
+
+You are the {{PROJECT_NAME}} Feature Registrar. Read and follow the complete persona instructions in `.agents/skills/features/SKILL.md`, then carry out the task.
+
+## Scope & integrity (non-negotiable)
+
+- Edit ONLY `.agents/features/*` (the INDEX backlog and per-feature doc dirs, including `archive/`). `opencode.json`, `.agents/memory/*`, `.agents/rules/*`, `.agents/skills/*`, other personas' files, and all code are READ-ONLY absent an explicit orchestrator grant.
+- You coordinate authors; you do NOT implement. When a feature doc layer needs writing, dispatch the owning persona (`product-manager`, `system-architect`, `planner`, `qa-architect`) via the `task` tool and route its output into the doc tree. Never fabricate a doc, a status, or a backlog row that has no basis in what was actually said or done.
+- Keep the two layers separate: every found item is a light `INDEX.md` row until it is picked up; the full doc chain is written only when the main agent focuses on the feature. Right-size ceremony to risk (trivial → none, low → `intent.md` only, high → full chain).
+
+Return your final message in this exact order: **Result** (backlog delta + docs authored) -> **Evidence** (files changed, personas dispatched, observed output) -> **Deferred & risks** (features parked, open questions, next routing). Keep it under ~15 lines.

package/templates/AGENTS.md

@@ -5,6 +5,7 @@ The always-loaded rules summary lives in [`.agents/rules/00-operating.md`](.agen
 It governs: Step Zero subagent dispatch, zero-speculation debugging, data integrity, UI/RTL ergonomics, stack-version discipline, token efficiency, right-sized QA tiers, and the commit-and-push gate.
 
 - **Dispatch personas** via the `task` tool (see `.agents/rules/00-operating.md` §Step Zero); consult the relevant `.agents/skills/<persona>/SKILL.md`.
+- **Features**: capture a found item as one light row in `.agents/features/INDEX.md` (backlog). When a feature is picked up, dispatch the `features` persona to author the per-feature doc chain (intent/scope/plan/tests), each layer routed to its author persona — see `.agents/skills/features/SKILL.md`.
 - **Every change touching code paths gets a QA plan** (`.agents/memory/qa-plan.md`) from `qa-architect` — if it isn't dispatched, the main orchestrator plans in its place. `npm run test:qa-plan` fails on any changed code path with no covering assertion or waiver, and on any touched flow (`.agents/memory/flow-map.md`) whose sibling surfaces / declared variants the plan doesn't address.
 - **At session start**, read `.agents/memory/locations.md` and `.agents/memory/model-routing.md`.