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](https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/okf)) 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 and adapt verbosity and question count to the `technical_level` and `accompaniment_level` you find. L0 means terse and almost silent; L3 means explain everything and ask a lot. No profile yet → assume non-technical, and let `init` run first contact (it owns the two gauging questions and the dial; do not re-ask them 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. At L0 ask only the few that change the answer; at L3 ask all of them, one at a time. Then present exactly three options with honest trade-offs, recommend one in language matched to their level, 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. ### Phase 5 — VERIFY **Syntax gate — `bash -n` on every generated shell.** After scaffolding (APPLY steps 3–4), run `bash -n` on every generated `01-TOOLS/*/test_connection.sh` and any other generated shell script (e.g. `migrated/*.sh`) as a per-tool syntax gate. This parses each script without executing it, catching truncation or copy errors before the user ever runs them: ```bash fail=0 for f in 01-TOOLS/*/test_connection.sh; do [ -f "$f" ] || continue