Harness

Harness — the workspace control plane

The harness is the control plane of a workspace. A workspace need not be code: it can be a company, an ops desk, a legal archive, a personal knowledge vault. Whatever it is, the harness is the durable apparatus that keeps it operable and legible, made of three parts:

• 01-TOOLS/<PROVIDER>/ — the operational tooling layer. One folder per external provider, co-locating credentials (.env) with the scripts that consume them. Each tool ships a working test_connection against the real API.

• 02-DOCS/ — the Karpathy chaos→knowledge engine: a domain-agnostic LLM wiki (inbox/, raw/, raw/worklog/, wiki/ with its index.md / log.md / gaps.md / scores.json and .base views), embedded in this skill — no external sub-skill required.

  Two on-ramps feed it. Ingest: the user drops any file in any format into inbox/, and the Auto-Ingest Sweep extracts, classifies, cross-links and compiles it — then goes for a walk, discovering un-ingested documents anywhere in the workspace, bounded by .rscignore (baseline: references/ingest-ignore-defaults.md) and de-duplicated through the wiki/.ingested.json ledger. Worklog: every meaningful session of work is itself a raw source in raw/worklog/, captured on PreCompact/SessionEnd, at a commit milestone, or by the daily curation pass.

  Ingest relocates, never deletes: a loose file at the workspace root moves into raw/; a file inside a folder the user maintains is copied, and consolidating that folder needs explicit consent.

  The wiki/ is simultaneously an OKF-v0.1 bundle (Open Knowledge Format) and an Obsidian-native vault: markdown links, YAML frontmatter, readable filenames, .base views giving a real graph and live tables. Structure, not vector DB / embeddings / RAG. The agent writes it; the human reads it in Obsidian. Topics are inferred from content (finanzas/, legal/, crm/…), never hardcoded.

  It compounds on its own: every Ingest, Sweep and Query triggers a Maintenance Pass (lint, score recomputation, gap detection, Related sweep), a Micro-Improve runs every N interactions, and Deep Improve runs on request or on the daily schedule (references/daily-curation-automation.md — on Claude Code, wire it via the schedule skill). Protocol → references/wiki-protocol.md; formats → references/ingest-formats.md; capture → references/wiki-worklog-template.md; vault → references/obsidian-scaffolding.md.

• The Knowledge map — the ## Knowledge map section of the root CLAUDE.md that indexes the wiki (including the harness/ topic) and is read by every other skill before it works in its area.

harness is the protagonist concept. init is the bootstrap front door — it gauges the user, drafts the profile, and hands off the first scaffold. THIS skill (harness) is the ongoing control: it audits, migrates, scaffolds, sweeps the inbox, and keeps the wiki, the tooling and the Knowledge map honest over the life of the workspace. It also generates root CLAUDE.md and AGENTS.md, and migrates legacy XX-* numbered folders into the canonical layout.

How the harness talks to the user

Read 02-DOCS/wiki/harness/user-profile.md before you start. Its technical_level picks the register: technical terms used directly, or plain words with everyday analogies. Everything else is the one orient voice: short sentences, and every answer understandable on its own. No profile yet → use analogies, and let init run first contact (it owns the one register question; do not re-ask it here).

Two files carry the state, both indexed from the root CLAUDE.md Knowledge map under harness/: user-profile.md for the living portrait of the user, and decisions.md as an append-only log — date, requirements gathered, options presented, choice, why. Log every significant decision you take.

.rsc/.no-harness is the user's explicit "no harness in this repo". Treat it as canonical: never overwrite it, never delete it, never auto-start onboarding past it.

For long SDD work, write the recovery note 02-DOCS/wiki/sdd/sessions/<date>-<slug>.md before context compacts or the work is handed off — active artifacts, phase, last verdict, next steps, risks, commands. It is what lets the next agent resume without trusting chat history.

Significant decisions: requirements first, then exactly three options

For any significant decision (deploy target, database, hosting, tooling), gather the requirements that actually drive the choice before presenting anything — for a deploy: expected and concurrent users, budget, data residency, the team's ops comfort, scaling needs. Ask only the ones that change the answer, in one short batch. Then present exactly three options with honest trade-offs, recommend one in their register, and log it.

The canonical deploy trio is Hetzner+Coolify (cheap, total control, self-managed), Vercel (zero-ops, scales itself, costly at scale), and a third chosen from their answers. Apply the pattern yourself for harness-level choices, but defer concrete deploy mechanics to deployment, which owns them.

Core principle

Detection with interactive confirmation. Never speculative tools. Never destructive without explicit consent.

The skill proposes, the user confirms, the skill executes. Every destructive operation (deleting a legacy folder, merging into an existing CLAUDE.md) requires explicit consent quoted back from the user, not inferred.

Out of scope: adding a single tool — the user does cp -r 01-TOOLS/_TEMPLATE 01-TOOLS/<X> manually, no need for the full protocol; and refactoring runtime code — this skill is operational tooling only, never runtime.

Protocol — five phases

SCAN → AUDIT → CONSENT → APPLY → VERIFY

Never skip a phase. Never collapse phases. The user reads the AUDIT before anything is written.

Phase 1 — SCAN (read-only)

Walk the workspace root and gather:

1. Workspace root — current directory unless the user passes one explicitly.
2. Subprojects — top-level directories containing a manifest (package.json, pyproject.toml, pubspec.yaml, Cargo.toml, go.mod). Record stack per subproject (Next.js, FastAPI, Flutter, Express, etc.) from manifest contents.
3. Provider detection — for every entry in references/providers.yaml, search the workspace for evidence:
   • imports: grep for the SDK import patterns across source files (skip node_modules/, .venv/, .next/, __pycache__/, .git/, dist/, build/, .dart_tool/).
   • env_vars: grep for the variable names in .env*, *.yaml, *.yml, source files.
   • deps: search the dependency name in manifest files.
   • Record evidence with path:line for each hit. A provider counts as detected if any detector matches.
4. Legacy XX-* folders — list root entries matching ^[0-9]+-[A-Z_]+$. For each, recursively classify every file:
   • TOOLING — folder contains .env, .env.example, executable scripts (*.sh, *.py with shebang), or integrates a provider from the catalog.
   • DOCS — *.md, *.txt, diagrams (*.png, *.svg, *.mmd), notes.
   • AMBIGUOUS — mixed, runtime code (Python modules without shebang, TS files), or content the classifier cannot place with high confidence.
5. Existing canonical layout — check whether 01-TOOLS/, 02-DOCS/, CLAUDE.md, AGENTS.md already exist. If yes, read their current content.
6. Git state — for each subproject that's a git repo, capture git status --short. Don't act on dirty trees without flagging.

Phase 2 — AUDIT (presented to user)

Render two artifacts:

1. A compact text summary in the conversation — 1–3 sentences per section, the full destructive-ops list, the consent prompt, in the format of references/audit-report-template.md. This keeps the terminal flow fast. A full walked-through audit on a synthetic project: examples/audit-example.md.
2. A full HTML report at <workspace_root>/02-DOCS/audits/audit-YYYY-MM-DD-HHMM.html using references/audit-report-template.html. Self-contained (inline CSS, no CDN). Includes color-coded action tables, collapsible legacy-folder sections, highlighted destructive ops, and the consent prompt. Gitignored (per-run artifact).

If 02-DOCS/audits/ does not exist, create it (with .gitkeep) before writing — even on first run, before Phase 4 builds the rest of 02-DOCS/. Same for 02-DOCS/ itself: the audits subdirectory is the only piece allowed to materialize during Phase 2; the rest waits until APPLY. Never write the audit HTML at the workspace root.

The text summary points to the HTML: "Full audit at ./02-DOCS/audits/audit-XXX.html — open it to review details, then reply 'yes, proceed' or 'adjust'."

The HTML must contain:

• Stack summary — one line per subproject with detected stack and path.
• Tools to create — table: Tool | Evidence (path:line) | Action (CREATE / MERGE / SKIP).
• Legacy XX-* folders — one sub-section per folder, with a per-file classification table and a proposed destination.
• Ambiguous files — explicit list. These will NOT be moved. The user decides later.
• Root files — what happens to CLAUDE.md / AGENTS.md (CREATE, MERGE-additive, or SKIP if identical).
• 02-DOCS/ plan — list of sources to ingest (per references/wiki-protocol.md), the topics that will appear in wiki/, and confirmation that the wiki layer is built in-skill.
• Files NEVER touched — explicit list reminding the user of the safety boundary: real .env, contents of node_modules/, .venv/, .next/, __pycache__/, .git/, subproject runtime source.
• Destructive operations — separate section, bold. List every folder that would be deleted and under what condition.
• Dirty git trees — if any subproject has uncommitted changes, list them and recommend stashing/committing before proceeding.

Phase 3 — CONSENT

The user must respond with explicit approval. Accept ONLY these forms:

• "yes, proceed" / "go" / "proceed" → APPLY.
• "adjust" / "modify" → ask which tools to drop/add, then re-AUDIT.
• Anything else, including silence, ambiguous "ok", "sure", "sounds good" → DO NOT PROCEED. Re-prompt explicitly: "I need explicit confirmation. Reply yes, proceed or adjust."

Destructive consent is separate. Even after the main "yes, proceed", the deletion of any legacy XX-* folder requires a SECOND consent after migration is verified (see APPLY step 7).

Phase 4 — APPLY

Execute in this exact order. Each step writes to disk; abort and report on first error.

1. Root files.
   • If CLAUDE.md does not exist: render references/claude-md-template.md with the scan data and write it.
   • If CLAUDE.md exists: read it, compute a section-level diff against the template, and apply ONLY additive merges. Never delete user content. Never overwrite a section the user has customized. Append missing sections at the end with an <!-- added by harness YYYY-MM-DD --> marker.
   • Same logic for AGENTS.md, rendered from references/agents-md-template.md.
2. Create 01-TOOLS/ skeleton.
   • Create 01-TOOLS/ directory.
   • Copy assets/_TEMPLATE/ to 01-TOOLS/_TEMPLATE/. The asset ships its ignore rules as gitignore (no leading dot, because npm never packages a .gitignore) and it must land as .gitignore; the installer already does this on every apply, so normally you will find the directory built. This template is generic boilerplate with placeholders (<NOMBRE_TOOL>, <TOOL>_API_KEY). The user copies it manually when adding a tool NOT in the catalog. The skill itself does NOT use _TEMPLATE/ to generate the detected tools — those come from providers.yaml.
3. Per detected tool (in catalog order):
   • Create 01-TOOLS/<ID>/.
   • Write every file from the provider entry's files: map verbatim (replacing template variables: {{TOOL_ID}}, {{DASHBOARD_URL}}, etc.).
   • Write .env.example from the provider entry's env_example field.
   • Write .gitignore from the template (.env, keys/, out/, common secrets).
   • chmod +x on test_connection.* and any other executables.
   • NEVER write a real .env file. NEVER fill credentials.
4. Migrate legacy XX-* folders.
   • For each TOOLING file: move to its mapped destination in 01-TOOLS/<X>/. If the destination file already exists from step 3, the legacy file goes to 01-TOOLS/<X>/migrated/<original-name> so nothing is overwritten. The user resolves manually.
   • For each DOCS file: move to 02-DOCS/raw/migrated/<original-folder>/<path>.
   • For each AMBIGUOUS file: leave in place. Record in the verification report. Never force-classify — a file moved to the wrong place is harder to recover than one left where the user put it.
5. Verify migration.
   • Count files moved vs files originally present. They must match (moved + ambiguous-remaining = original).
   • If counts don't match, abort and report. Don't proceed to deletion.
6. Write 01-TOOLS/README.md.
   • Render references/tools-readme-template.md AFTER all tool folders exist (steps 3 + 4 completed). The catalog table then reflects actual on-disk state, not a promise.
7. Destructive consent for legacy folder deletion.
   • For each legacy folder where ALL files were classified (zero ambiguous) AND migration verified: prompt the user with the exact path: "Migration verified. Delete 00-TOOLS/? Reply with the literal string 'yes, delete 00-TOOLS'."
   • Only delete on exact-string match. Anything else: skip the deletion, preserve the now-empty folder.
   • For folders WITH ambiguous files: never delete. The folder stays with the ambiguous content.
8. Build 02-DOCS/ (embedded wiki protocol).
   • Open references/wiki-protocol.md and follow it. It defines initialization, ingest, query, and lint flows in full.
   • For the bootstrap pass on this APPLY: run the Initialization sub-section (create 02-DOCS/inbox/, 02-DOCS/inbox/README.md from inbox-readme-template.md, 02-DOCS/inbox/_processed/, 02-DOCS/raw/, 02-DOCS/wiki/, 02-DOCS/wiki/index.md, 02-DOCS/wiki/log.md), then run the bootstrap ingest (one optional seeding pass — the ongoing path is dropping files into inbox/ and running the Inbox Sweep) for each of these sources (see the "How harness uses this protocol" section at the bottom of wiki-protocol.md):
     • Each subproject README.md if present.
     • 01-TOOLS/README.md (just written in step 6).
     • Each 01-TOOLS/<TOOL>/README.md and CREDENTIALS.md.
     • Every file under 02-DOCS/raw/migrated/ (from legacy XX-* migration in step 4).
     • Root CLAUDE.md and AGENTS.md.
   • Use these templates verbatim; wiki-protocol.md is the source of truth for 02-DOCS, so do NOT invent a different structure or format:
     • references/wiki-raw-template.md — raw/<topic>/*.md.
     • references/wiki-article-template.md — wiki/<topic>/*.md (OKF v0.1 frontmatter + relative markdown links + ## Related).
     • references/wiki-index-template.md — wiki/index.md (machine catalog; the .base views are the human navigation).
     • references/wiki-gaps-template.md — wiki/gaps.md (Knowledge Gaps log).
     • references/wiki-dashboard-template.html — the live wiki dashboard, regenerated by Maintenance Pass.
     • references/wiki-archive-template.html — archived query answers (point-in-time, never edited).
     • references/wiki-deep-improve-report-template.html — Deep Improve run reports.