infinity-harness 2.0.0 → 2.0.2

package/harness/skills/capability-acquisition.md

@@ -1,72 +1,75 @@
 ---
 name: capability-acquisition
-description: The capability ladder — HAVE, ACQUIRE, CREATE, KEEP — for skills, MCP servers, and tools
-tags: [meta, capability, acquire, search, skill, mcp, tool, ladder, library]
-when: a task needs knowledge, system access, or an executable the project lacks
+description: The capability ladder — HAVE, ACQUIRE, CREATE, KEEP — for skills, extensions and project scripts
+tags: [meta, capability, acquire, search, skill, extension, tool, script, ladder, library]
+when: a task needs knowledge, an integration, or an executable the project lacks
 phases: []
+kind: meta
 provenance: { origin: built-in }
 ---
 
 # Capability Acquisition — The Ladder
 
-Your task needs something the library lacks. Resolve it with the ladder —
-and register what you find so the NEXT task starts at Tier 0.
+The task needs something you do not have. Work the ladder in order, and leave
+the result behind so the next task starts one rung higher.
 
-## Step 1 — Decide the capability TYPE
+pi has three kinds of capability. Pick the right shape first — most wasted
+effort here is building the wrong one.
 
-- Need **knowledge or method** (how to do X well) → a **skill**
-- Need to **interact with an external system** (DB, API, browser, tracker) → an **MCP server**
-- Need a **repeatable executable action** (reset fixtures, run a codemod) → a **tool**
-- Need a **fact** (does API X support Y?) → follow `research.md` — findings
-  saved under `docs/research/` with frontmatter become matchable facts
+| You need | Build | Lives in |
+|---|---|---|
+| Knowledge or method — how to do X well | a **skill** | `.pi/skills/<name>.md` |
+| A repeatable action — reset fixtures, run a codemod | a **script** | the repo, run through bash |
+| A tool the model can call, or a slash command | an **extension** | its own package, `pi install`ed |
+| A fact — does API X support Y? | neither | `research.md`, written into `harness/docs/` |
 
-## Step 2 — ACQUIRE: search the sources
+## 1 — HAVE: check before you build
 
-```
-the capability index "<2-4 keywords>" --type skill|mcp|tool
-```
+- **Skills already loaded.** This package ships 28. The brief names the ones
+  that match the current task; `/skill:<name>` invokes any of them.
+- **Scripts already in the repo.** `package.json` scripts, `Makefile`,
+  `scripts/`. Read before you write — the thing you are about to build is
+  often already there under a name you did not guess.
+- **Extensions already installed.** `pi list`.
 
-This queries the machine-queryable registries directly (npm, MCP registry,
-GitHub, crates, …). Browse-only sources are listed after — use them only
-if you have web access.
+## 2 — ACQUIRE: take what exists
 
-**Choosing among hits** (in order): trust tier (official > curated >
-community) → actively maintained → widely used → known author →
-permissive license (MIT/Apache/BSD) → small and composable. NEVER adopt a
-framework that wants to own your whole process — the harness owns the
-process.
+- **A skill** is plain markdown. Copy one in, then *adapt* it: trim to the
+  useful core, re-point its references at this project's surfaces, and add an
+  attribution line naming the source and its licence.
+- **An extension**: `pi install npm:<pkg> -l` (project-local, so the team gets
+  it through `.pi/settings.json`) or `pi install git:<host>/<repo>`. Pin the
+  version, and read what it registers before you trust it.
 
-**Adapt, don't adopt.** Whatever you take: trim it to the useful core,
-re-point references to harness surfaces (DOMAIN.md, feature-list,
-learn/decision), add an attribution line (source + license), then register:
+**Choosing among candidates**, in order: actively maintained → widely used →
+permissive licence (MIT/Apache/BSD) → small and composable. Never adopt
+something that wants to own the whole process — the harness owns the process.
 
-```
-infinity-harness capability add skill <path> --from <url>
-infinity-harness capability add mcp <name> --command npx --args -y,<pkg>@<exact-version> \
-  --tags ... --description "..." --trust curated
-infinity-harness capability add tool <file> --run "..." --tags ... --description "..."
-```
+## 3 — CREATE: nothing usable exists
 
-**MCP security (hard rules):** pin exact versions (`pkg@1.2.3`, never
-`@latest`); community-tier servers need `--force` after you review their
-source; secrets go through env indirection, never into configs.
+- **A skill** → write it per `writing-skills.md` into `.pi/skills/<name>.md`.
+  pi loads it on the next start. There is nothing to register.
+- **A script** → build it per `building-tools.md`, and name it where a cold
+  reader will look (`AGENTS.md`, or `package.json` scripts).
+- **An extension** → only when the capability has to be a tool the model calls
+  or a slash command. It is a package with a `pi.extensions` entry;
+  `pi install ./<dir> -l` loads it straight from a checkout.
 
-## Step 3 — CREATE: nothing usable exists
+## 4 — KEEP: or you will do this again
 
-```
-infinity-harness capability create skill|tool|mcp <name>
-```
+A capability that lives only in this session is not a capability.
 
-- skill → fill the stub per `writing-skills.md`
-- tool → implement per `building-tools.md`
-- mcp → the scaffold is a WORKING server; fill in handlers per
-  `building-mcp-servers.md`, verify with its self-test, then register
+- **Commit it.** A skill in `.pi/skills/` and a script in the repo both travel
+  with the project.
+- **Make it findable.** Tags in a skill's frontmatter are how the brief
+  surfaces it later; a script nobody can find is a script nobody runs.
 
-## Step 4 — Budget and fallback (never block the pipeline)
+## 5 — Budget: never block the pipeline
 
-Acquisition fits ONE working session. If the search didn't conclude, or you
+Acquisition fits inside one working session. If it does not conclude, or you
 have no network:
 
-1. Record the gap: `harness/lessons-decisions.md "capability gap: <what was needed>"`
-2. Proceed with general best practices — a missing skill is not a blocked task
-3. The gap resurfaces via `infinity-harness capability gaps` for a later pass
+1. Record the gap in `harness/lessons-decisions.md` — what was needed, what
+   you tried, what you would try next.
+2. Carry on with general best practice. A missing skill is not a blocked task,
+   and it is never a reason to mark work complete that is not.

package/harness/skills/cli-design.md

@@ -4,6 +4,7 @@ description: Command-line tool design — argument conventions, output contracts
 tags: [cli, command, terminal, flags, arguments, stdout, stdin, shell, script, tool]
 when: task builds or extends a command-line interface
 phases: [plan, build]
+kind: domain
 provenance: { origin: built-in }
 ---
 
@@ -30,9 +31,8 @@ provenance: { origin: built-in }
   consistently; flags kebab-case with `--long` forms; `-` means stdin/
   stdout where files are expected; respect `NO_COLOR` and non-TTY (no
   spinners into pipes).
-- **Errors say what + why + what next:** `✗ config not found:
-  harness/config.json — run: infinity-harness init`. Never a bare stack trace
-  for an expected failure.
+- **Errors say what + why + what next:** `✗ config not found: ./app.config.json
+  — run: myapp init`. Never a bare stack trace for an expected failure.
 - **Fast startup matters.** A CLI invoked in loops pays its startup cost
   ×N — lazy-load heavy imports per subcommand.
 

package/harness/skills/code-review.md

@@ -4,6 +4,7 @@ description: Two-axis review (spec fidelity + standards/smells) with the Fowler
 tags: [review, quality, smell, refactor, standards, spec, diff, audit]
 when: reviewing a diff, a branch, or the whole delivery before shipping
 phases: [review, simplify]
+kind: process
 provenance: { origin: "mattpocock/skills", license: MIT, adapted: true }
 ---
 

package/harness/skills/codebase-design.md

@@ -4,6 +4,7 @@ description: Deep modules — small interfaces hiding lots of behavior, seams, t
 tags: [design, architecture, module, interface, seam, refactor, coupling, abstraction, api]
 when: designing module boundaries, planning features, refactoring for clarity
 phases: [plan, simplify]
+kind: process
 provenance: { origin: "mattpocock/skills", license: MIT, adapted: true }
 ---
 

package/harness/skills/concurrency-async.md

@@ -4,6 +4,7 @@ description: Concurrency and async correctness — races, idempotency, queues, c
 tags: [concurrency, async, race, parallel, queue, lock, mutex, retry, idempotent, worker, thread, promise, deadlock, atomic]
 when: task involves parallel work, background jobs, shared state, or retried operations
 phases: [plan, build, verify]
+kind: domain
 provenance: { origin: built-in }
 ---
 

package/harness/skills/config-and-secrets.md

@@ -4,6 +4,7 @@ description: Configuration discipline — env-driven config, validation at boot,
 tags: [config, configuration, environment, env, secret, settings, deploy, dotenv, variable]
 when: task adds configuration, environment handling, or deployment settings
 phases: [build, ship]
+kind: domain
 provenance: { origin: built-in }
 ---
 

package/harness/skills/context-hygiene.md

@@ -4,6 +4,7 @@ description: Externalize state before it decays — write discoveries down, re-r
 tags: [meta, context, memory, handoff, session, notes, playbook]
 when: any long session, and always before ending one
 phases: []
+kind: process
 provenance: { origin: built-in, notes: frontier-playbook }
 ---
 

package/harness/skills/databases.md

@@ -4,6 +4,7 @@ description: Relational database craft — schema design, migrations, transactio
 tags: [database, db, sql, postgres, postgresql, mysql, sqlite, schema, migration, transaction, index, query, orm, persistence, storage]
 when: task touches persistent data, schemas, queries, or migrations
 phases: [plan, build, verify]
+kind: domain
 provenance: { origin: built-in }
 ---
 

package/harness/skills/diagnosing-bugs.md

@@ -4,6 +4,7 @@ description: Feedback-loop-first debugging discipline for hard bugs and regressi
 tags: [debug, debugging, bug, error, failure, crash, flaky, slow, performance, regression, bisect]
 when: something is broken, throwing, failing intermittently, or slow
 phases: [verify, build]
+kind: process
 provenance: { origin: "mattpocock/skills", license: MIT, adapted: true }
 ---
 

package/harness/skills/domain-modeling.md

@@ -4,6 +4,7 @@ description: Pin down domain terminology — glossary discipline and decision re
 tags: [domain, glossary, terminology, naming, model, ubiquitous, language, adr, decision]
 when: defining specs, resolving fuzzy or conflicting terms, recording decisions
 phases: [define, plan]
+kind: process
 provenance: { origin: "mattpocock/skills", license: MIT, adapted: true }
 ---
 

package/harness/skills/error-handling-logging.md

@@ -4,6 +4,7 @@ description: Error taxonomy, fail-loud handling, structured logging that debugs
 tags: [error, exception, logging, log, observability, retry, crash, handling, monitoring, trace]
 when: task defines error paths, adds logging, or hardens failure behavior
 phases: [build, verify]
+kind: domain
 provenance: { origin: built-in }
 ---
 

package/harness/skills/frontend-ui.md

@@ -4,6 +4,7 @@ description: Frontend craft — state discipline, componentization, accessibilit
 tags: [frontend, ui, component, react, vue, svelte, state, form, accessibility, a11y, css, browser, render]
 when: task builds or changes user interface
 phases: [plan, build]
+kind: domain
 provenance: { origin: built-in }
 ---
 

package/harness/skills/grilling.md

@@ -4,6 +4,7 @@ description: Stress-test a spec or plan with relentless one-at-a-time questions
 tags: [grill, spec, requirements, questions, stress, interview, scope, clarify]
 when: before proposing the sprint contract, or when a plan feels underspecified
 phases: [define]
+kind: process
 provenance: { origin: "mattpocock/skills", license: MIT, adapted: true }
 ---
 

package/harness/skills/http-apis.md

@@ -4,6 +4,7 @@ description: HTTP/REST API design — resources, status codes, errors, versionin
 tags: [api, http, rest, endpoint, route, json, status, error, versioning, pagination, webhook, request, response]
 when: task designs or implements HTTP endpoints or consumes external APIs
 phases: [plan, build]
+kind: domain
 provenance: { origin: built-in }
 ---
 

package/harness/skills/performance.md

@@ -4,6 +4,7 @@ description: Performance work — measure first, fix the biggest cost, cache wit
 tags: [performance, slow, latency, profiling, optimize, cache, memory, benchmark, throughput, speed]
 when: something is slow, memory-hungry, or a task sets performance targets
 phases: [verify, build]
+kind: domain
 provenance: { origin: built-in }
 ---
 

package/harness/skills/pi-todo-adapted.md

@@ -4,6 +4,7 @@ description: "Atomic infinity_plan pattern with omission deletion, baseRevision
 tags: [harness, pi-todo, atomic, baseRevision, omission, deletion, compaction, widget, task-list, dependency]
 when: "implementing infinity_plan, atomic revisioning, Pi widget with session persistence or task dependencies"
 phases: [build, verify]
+kind: domain
 provenance: { origin: "https://github.com/99percentpeople/pi-extensions", license: MIT, adapted: true, url: "https://github.com/99percentpeople/pi-extensions", contentHash: abf626df6a74a6fb }
 ---
 

package/harness/skills/planning-tasks.md

@@ -4,6 +4,7 @@ description: Break specs into tracer-bullet vertical slices with checkable accep
 tags: [plan, planning, slice, ticket, decompose, criteria, backlog, breakdown, refactor]
 when: writing or restructuring the feature list from a spec
 phases: [plan]
+kind: process
 provenance: { origin: "mattpocock/skills", license: MIT, adapted: true }
 ---
 

package/harness/skills/prototype.md

@@ -3,7 +3,8 @@ name: prototype
 description: Throwaway code that answers a design question fast, then gets deleted
 tags: [prototype, spike, experiment, explore, poc, throwaway, design]
 when: a state model, logic shape, or UI direction cannot be judged on paper
-phases: [build, plan]
+phases: [plan, build]
+kind: process
 provenance: { origin: "mattpocock/skills", license: MIT, adapted: true }
 ---
 

package/harness/skills/research.md

@@ -4,6 +4,7 @@ description: Answer factual questions from primary sources; capture cited findin
 tags: [research, docs, documentation, investigate, source, facts, api, spec, evidence]
 when: a factual question about an API, library, protocol, or tool blocks progress
 phases: [define, plan, build]
+kind: process
 provenance: { origin: "mattpocock/skills", license: MIT, adapted: true }
 ---
 

package/harness/skills/resolving-merge-conflicts.md

@@ -4,6 +4,7 @@ description: Resolve git merge/rebase conflicts by original intent, verify, and
 tags: [git, merge, rebase, conflict, branch, hunk]
 when: an in-progress git merge or rebase has conflicting hunks
 phases: []
+kind: process
 provenance: { origin: "mattpocock/skills", license: MIT, adapted: true }
 ---
 
@@ -23,7 +24,7 @@ provenance: { origin: "mattpocock/skills", license: MIT, adapted: true }
    trade-off. Do **not** invent new behaviour. Always resolve; never
    `--abort`.
 4. **Run the project's automated checks** — typecheck, then tests, then
-   lint (`the infinity_validate tool` runs the configured set). Fix anything the
+   lint (`infinity_validate` runs the configured set). Fix anything the
    merge broke.
 5. **Finish the merge/rebase.** Stage everything and commit. If rebasing,
    continue until all commits are rebased. Record anything surprising:

package/harness/skills/scope-discipline.md

@@ -4,6 +4,7 @@ description: The contract is the boundary — park ideas, resist drive-by fixes,
 tags: [meta, scope, creep, contract, focus, discipline, playbook]
 when: mid-task ideas, adjacent problems, or "while I'm here" temptations appear
 phases: []
+kind: process
 provenance: { origin: built-in, notes: frontier-playbook }
 ---
 

package/harness/skills/self-review.md

@@ -4,6 +4,7 @@ description: Structured pass before claiming done — criteria re-check, real ru
 tags: [meta, review, verify, done, quality, check, playbook]
 when: before running validate on any task — every time
 phases: [build, verify, simplify]
+kind: process
 provenance: { origin: built-in, notes: frontier-playbook }
 ---
 

package/harness/skills/stuck-protocol.md

@@ -4,6 +4,7 @@ description: What to do after repeated failures — stop, write down, reframe on
 tags: [meta, stuck, retry, failure, escalate, blocked, playbook]
 when: the same step has failed 2-3 times, or you notice you are looping
 phases: []
+kind: process
 provenance: { origin: built-in, notes: frontier-playbook }
 ---
 
@@ -28,7 +29,7 @@ catch any of these tells:
    what you're trying to achieve, the exact error/failure, the attempts
    made, and what each attempt ruled out. Writing this usually exposes the
    gap — half the time you solve it here.
-2. **Re-read the brief and the skill** (`the infinity_brief tool`; the skill it
+2. **Re-read the brief and the skill** (`infinity_brief`; the skill it
    references). Stuck often means a constraint was missed, not that the
    problem is hard.
 3. **Reframe ONCE** — one genuinely different angle, not a variation:

package/harness/skills/tdd.md

@@ -4,6 +4,7 @@ description: Red → green test-driven loop — what a good test is, seams, anti
 tags: [tdd, test, testing, unit, integration, red-green, seam, mock, coverage]
 when: implementing any BUILD task, or fixing a bug that needs a regression test
 phases: [build, verify]
+kind: process
 provenance: { origin: "mattpocock/skills", license: MIT, adapted: true }
 ---
 

package/harness/skills/testing-infra.md

@@ -4,6 +4,7 @@ description: Test infrastructure — fixtures, isolation, flaky-test policy, CI
 tags: [test, testing, fixture, ci, flaky, coverage, mock, isolation, pipeline, suite]
 when: task sets up test tooling, fixtures, CI, or fights slow/flaky suites
 phases: [build, verify]
+kind: domain
 provenance: { origin: built-in }
 ---
 

package/harness/skills/writing-skills.md

@@ -4,6 +4,7 @@ description: How to author a skill worth keeping — scope, structure, frontmatt
 tags: [meta, skill, writing, author, documentation, checklist]
 when: creating a new skill or adapting an acquired one
 phases: []
+kind: meta
 provenance: { origin: "mattpocock/skills writing-great-skills", license: MIT, adapted: true }
 ---
 
@@ -54,7 +55,7 @@ Frontmatter uses a strict subset: `key: value`, `key: [a, b]`,
 
 ## Checklist
 
-- [ ] Frontmatter passes: `infinity-harness capability add skill <path>` (it validates)
+- [ ] Frontmatter is complete: `name` matching the filename, `description`, `kind`, `tags`, `when`, `phases`
 - [ ] A cold reader knows exactly what to do and how to check they did it
 - [ ] Every rule is checkable; every anti-pattern has a fix
 - [ ] Attribution line present if adapted from elsewhere

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "infinity-harness",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "description": "A pi agent extension that runs a gated build pipeline unattended \u2014 enforces phases, validates with deterministic gates, and keeps working for hours or days without losing the plan.",
   "type": "module",
   "keywords": [

package/src/core/brief.ts

@@ -22,6 +22,23 @@ import { runChecks } from "./gates.ts";
 import { getPhaseOrder, nextPhase, isFinalPhase } from "./phases.ts";
 import * as P from "./paths.ts";
 import { readText } from "./fsx.ts";
+import { loadSkills, matchSkills } from "./skills.ts";
+
+/**
+ * What the agent calls to have its work judged.
+ *
+ * This said `harness validate` for a long time — a command line that has not
+ * existed since the CLI was ported into `src/`. A brief that ends by telling
+ * the model to run a command that does not exist is a brief that ends in a
+ * failed shell call and a confused retry, every single turn.
+ */
+const VALIDATE_TOOL = "infinity_validate";
+
+/**
+ * Two is the number that gets read. One hides a better match; five is a
+ * reading list, and a reading list is a thing you skip.
+ */
+const SKILL_SUGGESTIONS = 2;
 
 const PHASE_INTENT: Record<Phase, string> = {
   init: "Set up the project skeleton and confirm the harness can see it.",
@@ -88,7 +105,7 @@ export async function buildBrief(targetDir: string, options: BuildBriefOptions =
         }
       : null,
     criteria: collectCriteria(feature, nextTask?.criteria),
-    validateCommand: "harness validate",
+    validateCommand: VALIDATE_TOOL,
     gate,
     progress: {
       tasksDone: progress.tasksDone,
@@ -102,10 +119,39 @@ export async function buildBrief(targetDir: string, options: BuildBriefOptions =
       phase: config.phaseRetryCount ?? 0,
       max: retry.tasks.max,
     },
+    skills: suggestSkills(phase, {
+      goal: (list.goals ?? [])[0]?.title ?? null,
+      feature: feature?.name ?? null,
+      task: nextTask?.description ?? null,
+      criteria: collectCriteria(feature, nextTask?.criteria),
+    }),
     notes,
   };
 }
 
+/**
+ * Which craft skills to point at, given what is being worked on.
+ *
+ * The skills ship with the package, so this works in an install with no
+ * project-level setup. If they are missing — someone vendored `src/` alone —
+ * the brief simply has no SKILLS section rather than failing to build.
+ */
+function suggestSkills(
+  phase: Phase | null,
+  work: { goal: string | null; feature: string | null; task: string | null; criteria: string[] },
+): Brief["skills"] {
+  const text = [work.task, work.feature, work.goal, ...work.criteria].filter(Boolean).join(" \n ");
+  try {
+    return matchSkills(loadSkills(), { phase, text, limit: SKILL_SUGGESTIONS }).map((m) => ({
+      name: m.skill.name,
+      description: m.skill.description,
+      why: m.why,
+    }));
+  } catch {
+    return [];
+  }
+}
+
 function collectCriteria(
   feature: { criteria?: string[] } | null,
   taskCriteria: string[] | undefined,
@@ -189,6 +235,15 @@ export function renderBrief(brief: Brief, config?: HarnessConfig): string {
     for (const c of brief.criteria) L.push(`  - ${c}`);
   }
 
+  if (brief.skills.length) {
+    L.push("");
+    L.push("SKILLS   read before you start — invoke by name");
+    for (const s of brief.skills) {
+      L.push(`  - ${s.name} — ${s.description}`);
+      if (s.why) L.push(`    (${s.why})`);
+    }
+  }
+
   if (brief.gate) {
     L.push("");
     L.push(`GATE     ${brief.gate.overall ? "PASS" : "FAIL"}`);
@@ -207,7 +262,7 @@ export function renderBrief(brief: Brief, config?: HarnessConfig): string {
   L.push("");
   L.push("THE LOOP");
   L.push("  1. Do the work described above.");
-  L.push(`  2. Run: ${brief.validateCommand}`);
+  L.push(`  2. Call the ${brief.validateCommand} tool (a human types /infinity:validate).`);
   L.push("  3. FAIL → fix the listed checks and validate again.");
   L.push("  4. PASS → the harness advances the phase and issues the next brief.");
   L.push("");