@damiangilgonzalez/harness 1.3.7

package/skills/harness/SKILL.md

@@ -0,0 +1,301 @@
+---
+name: harness
+description: "Use when governing a workspace's control plane, code or not — the `01-TOOLS/` tooling layer, the `docs/` chaos→knowledge wiki, the root Knowledge map. Audits it, migrates legacy `XX-*` folders, scaffolds provider tooling, sweeps the inbox, writes root CLAUDE.md/AGENTS.md. NOT the bootstrap front door (that is `init`, which hands off here)."
+tags: [harness, company, ops, docs, wiki, connect, tools, knowledge]
+recommends: [init]
+profiles: [minimal, core, ui, full]
+origin: risco
+---
+
+# 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.
+- **`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 `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 `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/`, `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>/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 `docs/audits/` does not exist, create it (with `.gitkeep`) before writing — even on first run, before Phase 4 builds the rest of `docs/`. Same for `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 ./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).
+- **`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 `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 `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 `docs/inbox/`, `docs/inbox/README.md` from `inbox-readme-template.md`, `docs/inbox/_processed/`, `docs/raw/`, `docs/wiki/`, `docs/wiki/index.md`, `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 `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 `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
+  if bash -n "$f" 2>/tmp/harness-bashn.err; then
+    echo "ok   $f"
+  else
+    echo "FAIL $f"
+    sed 's/^/       /' /tmp/harness-bashn.err
+    fail=1
+  fi
+done
+[ "$fail" -eq 0 ] || echo "One or more generated shells failed bash -n — report each above and do not claim the scaffold is clean."
+```
+
+Report any script that fails the gate (with its parse error) in the final report. A failing gate is a red flag: the provider entry in `providers.yaml` is likely malformed — surface it, don't silently ship a broken script.
+
+**Preflight — `python3` availability.** Most provider smoke-tests pipe the API response through `python3 -c '…'` to parse JSON (Stripe, Mailjet, OpenAI, Anthropic, Gemini, Mistral, SendGrid, Vercel and ~30 more). Before telling the user to rely on those `test_connection.sh` scripts, confirm `python3` is on `PATH` and tell them how to install it if not:
+
+```bash
+if command -v python3 >/dev/null 2>&1; then
+  echo "python3 present: $(python3 --version 2>&1)"
+else
+  echo "python3 NOT found — most test_connection.sh scripts parse JSON with it and will fail."
+  echo "  macOS:         brew install python   (or: xcode-select --install)"
+  echo "  Debian/Ubuntu: sudo apt install python3"
+  echo "  Fedora/RHEL:   sudo dnf install python3"
+  echo "  Windows:       winget install -e --id Python.Python.3.13   (bump the version if unavailable)"
+fi
+```
+
+Print a final report:
+
+- `python3` preflight result (present + version, or the install hint above).
+- `bash -n` syntax-gate result (per generated shell: ok / FAIL with parse error).
+- Files written (full list with paths).
+- Folders deleted (with consent quote).
+- Ambiguous files preserved (with locations).
+- Suggested next steps:
+  - `cp 01-TOOLS/<X>/.env.example 01-TOOLS/<X>/.env && chmod 600 01-TOOLS/<X>/.env` per tool.
+  - `01-TOOLS/<X>/test_connection.{sh,py}` once `.env` is filled.
+  - Any subproject with a dirty git tree to clean up.
+
+## Equip — install the skills this workspace needs
+
+Once the structure stands, make sure the workspace has the rsc skills its stack and goals call for — detection here, not just at `init`:
+
+1. **Detect → propose.** From the detected stacks/providers and the user's goals in `docs/wiki/harness/`, build a shortlist. Ask the CLI if unsure: `npx @damiangilgonzalez/harness consult "<stack + goal>"`. (Map e.g. detected Stripe→`stripe`, Postgres→`postgresdb`, Next→`nextjs`+`design`, a company/ops focus→`finance-ops`/`invoicing`/`gdpr-privacy`…)
+2. **Confirm, then install yourself.** Show the shortlist with a one-line *why* each (matched to the dial), get a one-word confirm, and run it via Bash — installing writes to their environment, so always confirm first:
+   ```bash
+   npx @damiangilgonzalez/harness add <skill> [<skill> ...]
+   ```
+   Can't run a shell? Print the exact command for another terminal tab.
+3. **Flag the new session.** New skills load at session start — tell the user to open a **new tab/session** (or reload Cursor/Codex/Gemini) in this folder for them to activate. Log the installed set in `docs/wiki/harness/decisions.md`.
+
+## Keep CLAUDE.md lean — the index lives in the wiki
+
+Root `CLAUDE.md` is read on **every** turn, so every line is a permanent context tax (2026 best
+practice: keep it **under ~200 lines**; beyond that, adherence rots as the rules that matter get
+diluted by an index nobody needs in context). The biggest growth vector is the `## Knowledge map` —
+a row per wiki article, appended by many skills, forever.
+
+**The rule:** the **full** Knowledge map lives in `docs/wiki/index.md` (loaded on demand, grows
+freely). Root `CLAUDE.md`'s `## Knowledge map` is a **short pointer** — only the read-first entries
+(`harness/user-profile.md`, `sdd/constitution.md`) plus "full index → `docs/wiki/index.md`".
+
+**Offload when it bloats (a move, never a trim — no info lost):** when `CLAUDE.md` passes ~200 lines
+(the SessionStart hook nudges you) or its `## Knowledge map` has grown past the read-first entries:
+
+1. Open `docs/wiki/index.md` (create it if absent).
+2. **Move** every Knowledge-map row beyond the read-first entries from `CLAUDE.md` into
+   `docs/wiki/index.md`, merging — don't duplicate, don't delete.
+3. Leave `CLAUDE.md`'s `## Knowledge map` as the short pointer above.
+4. Same for any other section overgrown into an index (e.g. a huge tool table): detail to the wiki,
+   pointer stays.
+
+From then on, **new index entries go to `docs/wiki/index.md`**, not `CLAUDE.md`. This is additive
+and reversible; it honors the "never delete user content" rule (you relocate it, with a pointer).
+Opt out of the size nudge with `.rsc/.no-claudemd-check`.
+
+## Invariants
+
+The consent, merge and `.env` rules live with the phases that enforce them above. These four are
+scope rules that no single phase owns, and breaking one destroys something the user cannot get back:
+
+1. **No speculative tools.** A tool is created if and only if the detector found evidence in the user's code. No "we should probably have a Sentry tool too".
+2. **Idempotent.** Running the skill twice produces no extra side effects. Re-scanning a project already canonical detects "nothing to do".
+3. **Out-of-scope dirs are invisible.** `node_modules/`, `.venv/`, `.next/`, `__pycache__/`, `.git/`, `dist/`, `build/`, `.dart_tool/` are never read for detection and never touched.
+4. **Subproject internals are out of scope.** `.env.example`, `requirements.txt`, `package.json`, source files inside subprojects are READ for detection only. They are NEVER moved, renamed, modified, or deleted. The skill operates exclusively on workspace-root artifacts (`CLAUDE.md`, `AGENTS.md`, `01-TOOLS/`, `docs/`, and `XX-*` legacy folders at the root level).
+
+## Red flags — abort and re-plan
+
+If any of these occur, stop and report:
+
+- A `git status` on any subproject shows uncommitted changes the user didn't acknowledge.
+- The AUDIT shows zero detected tools AND zero legacy folders AND `CLAUDE.md`/`AGENTS.md` already exist → there's nothing for the skill to do. Tell the user.
+- The user types anything ambiguous after AUDIT → do not infer consent.
+- Migration verification (step 5 of APPLY) shows file count mismatch → abort, don't delete anything.
+- The catalog has no entry for a provider obviously present in code → tell the user, suggest adding an entry to `references/providers.yaml` (that file, never `SKILL.md`, is where providers are added), don't fake one.
+
+This skill is fully self-contained. No external sub-skill required.
+
+## Orientación (siempre)
+
+Cierra cada turno con el **bloque-brújula** (📍 dónde estás · ✅ qué hiciste · 🧭 por qué · ➡️ siguiente, terminando en pregunta), calibrado al dial de `docs/wiki/harness/user-profile.md`. **Nunca termines en seco.** Protocolo completo: skill `orient` → `skills/orient/references/orientation-contract.md`. (Defiere a `suggest` el "¿instalo la skill que falta?".)
+

package/skills/harness/assets/_TEMPLATE/.env.example

@@ -0,0 +1,8 @@
+# <TOOL_NAME> — operational credentials
+# Generate at: https://...
+#
+# Copy this file to `.env`, fill in real values, and `chmod 600 .env`.
+
+<TOOL>_ENV=test
+<TOOL>_API_KEY=
+<TOOL>_API_SECRET=

package/skills/harness/assets/_TEMPLATE/CREDENTIALS.md

@@ -0,0 +1,25 @@
+# Credentials — <TOOL_NAME>
+
+## Provider dashboard
+
+- URL: https://...
+- Account: <owner email>
+- 2FA: <yes/no, where the second factor lives>
+
+## Variables
+
+| Variable | Type | Where to generate | Rotation |
+|----------|------|-------------------|----------|
+| `<TOOL>_API_KEY`     | secret | Dashboard → API → Create key       | <when and how> |
+| `<TOOL>_API_SECRET`  | secret | Next to the API key                | same event as API_KEY |
+
+## Exceptions to the `<TOOL>_<VAR>` naming convention
+
+> Only if any. Document why.
+
+## If a credential leaks
+
+1. Revoke immediately in the provider dashboard.
+2. Generate a new one and update local `.env`.
+3. If the app consumes it at runtime: update deployment env vars and redeploy.
+4. Log the incident with a date in this file.

package/skills/harness/assets/_TEMPLATE/README.md

@@ -0,0 +1,25 @@
+# <TOOL_NAME>
+
+> One sentence: what this tool is and what we use it for.
+
+## When to use
+
+> 1–2 sentences in business terms. Which operational flow does it enable?
+
+## Setup
+
+1. `cp .env.example .env && chmod 600 .env`
+2. Fill in the real values from the provider dashboard (link in `CREDENTIALS.md`).
+3. `./test_connection.sh` (or `python3 test_connection.py`) — should end with
+   `OK — …`.
+
+## Scripts
+
+| Script | What it does | Example |
+|--------|--------------|---------|
+| `test_connection.{sh,py}` | Smoke-test: confirms `.env` authenticates. | `./test_connection.sh` |
+| `<verb_object>.{sh,py}`  | <one-line description>                    | `./<verb_object>.sh <args>` |
+
+## Operational notes
+
+- Rate limits, sandbox vs production, gotchas, costs.

package/skills/harness/assets/_TEMPLATE/gitignore

@@ -0,0 +1,10 @@
+.env
+keys/
+out/
+*.p8
+*.p12
+*.jks
+*.json
+!*.example.json
+__pycache__/
+*.pyc

package/skills/harness/assets/_TEMPLATE/test_connection.sh

@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+# Smoke-test of the connection to <TOOL_NAME>.
+#
+# Confirms the co-located .env credentials are valid by making a cheap
+# read-only call. No parameters.
+#
+# Exit code: 0 if the API responds, ≠ 0 with detail on stderr otherwise.
+#
+# Usage:
+#   ./test_connection.sh
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ENV_PATH="$SCRIPT_DIR/.env"
+
+[ -f "$ENV_PATH" ] || { echo "ERROR: missing $ENV_PATH" >&2; exit 1; }
+
+set -a
+# shellcheck disable=SC1090
+source "$ENV_PATH"
+set +a
+
+: "${<TOOL>_API_KEY:?<TOOL>_API_KEY not set in $ENV_PATH}"
+
+# TODO: replace with the real read-only call for this provider.
+# curl -fsS "https://api.<provider>.com/v1/me" \
+#   -H "Authorization: Bearer ${<TOOL>_API_KEY}" \
+#   | python3 -m json.tool
+
+echo "OK — credentials valid."

package/skills/harness/evals/README.md

@@ -0,0 +1,54 @@
+# Eval harness — `harness` skill
+
+This evaluates the `harness` skill on two axes: **triggering** (does it fire on
+the right prompts and stay quiet on near-misses) and **capability** (does loading
+it measurably improve the agent's output). These run via an **agent harness**
+(an agent loop with skills loadable on/off), not a pure shell script — grading the
+triggering and rubric coverage requires a model in the loop.
+
+`cases.yaml` is the source of truth: `should_trigger` (7), `should_not_trigger`
+(6), `capability` (2 scenarios).
+
+## Triggering
+
+1. Load **only** the `harness` skill into the agent (plus its declared siblings'
+   *names/descriptions* so routing is realistic — do not load their bodies).
+2. For each `should_trigger` prompt: feed it cold to the agent, run **3–5 trials**,
+   record whether the agent invokes `harness`. Pass = it fires on every trial.
+3. For each `should_not_trigger` prompt: same protocol. Pass = `harness` does
+   **not** fire; bonus-check that it routes toward the `route_to` sibling (or
+   correctly declines when `route_to: none`).
+4. Score = (correct trigger decisions) / (total prompts × trials).
+
+**Pass bar: >= 90% trigger accuracy** across all prompts and trials, with **no
+single `should_not_trigger` prompt firing harness in a majority of its trials**
+(a consistent false-positive is a hard fail even if the average clears 90%).
+
+## Capability
+
+For each `capability` scenario, run it twice with an identical agent:
+
+- **WITHOUT** the skill (baseline) — skill not loaded.
+- **WITH** the skill loaded.
+
+Grade each transcript against that scenario's `must_include` checklist: one point
+per checkable point that appears, correct and unprompted, in the output. A second
+agent (or a human) grades; keep the grading rubric = the literal `must_include`
+list so it stays reproducible.
+
+**Pass bar:**
+- WITH the skill covers **>= 80%** of the `must_include` points.
+- WITH must **beat** WITHOUT by a clear margin (>= 30 percentage points). If the
+  baseline already covers most points, the skill isn't adding value — investigate.
+
+## Honesty notes
+
+- These are **model-graded** evals; expect run-to-run variance. Always run
+  multiple trials and report the spread, not a single number.
+- Keep prompts **cold** — no system hint that the harness skill exists, or the
+  trigger test is meaningless.
+- Do **not** let the capability runs actually write to disk; the skill is
+  destructive-by-consent. Run in a throwaway/sandbox workspace, or grade on the
+  *proposed plan* (AUDIT output) rather than executed APPLY.
+- When a case starts failing after a SKILL.md edit, fix the skill or the case —
+  don't tune the grader to pass.

package/skills/harness/evals/cases.yaml

@@ -0,0 +1,72 @@
+skill: harness
+
+# >=5 realistic, VARIED prompts that MUST invoke the harness skill.
+# Includes non-obvious phrasings and cases where the user never names the tool.
+should_trigger:
+  - prompt: "Control the harness of this workspace — audit 01-TOOLS and docs and tell me what's drifted."
+    why: "Names the harness control plane and its two layers (01-TOOLS / docs) directly; this is the core ongoing-control job of the skill."
+
+  - prompt: "Gestiona el arnés de mi proyecto: tengo carpetas 00-TOOLS, 03-NOTES y 04-LEGACY sueltas y quiero la estructura canónica."
+    why: "Spanish trigger 'gestiona el arnés' plus legacy XX-* numbered folders to migrate into the canonical 01-TOOLS/docs layout — squarely the migration/control behavior the skill owns."
+
+  - prompt: "My repo uses Stripe and Mailjet but there's no operational tooling for them. Set up connection-ready folders with a test_connection for each."
+    why: "Detecting external provider integrations in code and scaffolding 01-TOOLS/<PROVIDER>/ tools (with test_connection, .env.example) is exactly the provider-detection scaffolding the harness performs; does not name the skill."
+
+  - prompt: "I've been dumping PDFs, CSVs and screenshots into a folder for weeks. Process the inbox and turn it into a proper knowledge base I can query."
+    why: "This is the docs Inbox Sweep / chaos->knowledge engine embedded in the harness ('procesa el inbox'); the user describes the behavior without naming the skill."
+
+  - prompt: "Generate a root CLAUDE.md and AGENTS.md for this workspace with a Knowledge map that the other skills can read."
+    why: "Generating root CLAUDE.md/AGENTS.md and the Knowledge map index is an explicit harness responsibility (Phase 4 APPLY step 1)."
+
+  - prompt: "Sal a pasear por mi carpeta de documentos, clasifica todo lo que haya y enlázalo en la wiki."
+    why: "'Sal a pasear' / 'the agent goes for a walk' is the skill's own phrase for the Inbox Sweep that extracts, classifies by content and cross-links into the wiki — a non-obvious phrasing mapped to the docs engine."
+
+  - prompt: "This project grew organically and is a mess. Can you give it a real control plane so an agent can operate it reliably?"
+    why: "Describes a brownfield workspace needing the canonical control-plane apparatus (01-TOOLS + docs + Knowledge map) without naming any layer — the brownfield-first 'When to use' case."
+
+# >=4 NEAR-MISS prompts that must NOT invoke harness; each routes to the genuinely correct sibling.
+should_not_trigger:
+  - prompt: "I want to add a single Sentry tool folder to 01-TOOLS. Just copy the template and wire it up."
+    route_to: "none"
+    why: "SKILL.md 'Out of scope' is explicit: adding a single tool is a manual `cp -r 01-TOOLS/_TEMPLATE 01-TOOLS/<X>` — the full SCAN/AUDIT/APPLY harness is overkill, no skill needed."
+
+  - prompt: "Refactor the runtime database layer in my FastAPI service to use async SQLAlchemy sessions."
+    route_to: "fastapi"
+    why: "Refactoring runtime application code is explicitly out of harness scope ('this skill is operational tooling only, never runtime'); FastAPI service runtime work routes to the fastapi skill."
+
+  - prompt: "Bootstrap a brand-new project from scratch — gauge me, draft my profile, and scaffold the first version."
+    route_to: "init"
+    why: "First-contact bootstrap / gauging the user / drafting the profile is the `init` front door; harness is the ONGOING control after bootstrap, not the kickoff."
+
+  - prompt: "Walk me through choosing and configuring where to deploy my app — Hetzner vs Vercel vs Fly, with the actual deploy commands."
+    route_to: "deployment"
+    why: "Harness defers concrete deploy mechanics to deployment; the user wants the deploy specifics and commands, which deployment owns."
+
+  - prompt: "Design a normalized Postgres schema with the right indexes and write the migration SQL."
+    route_to: "postgresdb"
+    why: "Pure database schema/SQL design is the postgresdb skill's domain; harness only detects a Postgres provider to scaffold operational tooling, it does not author schemas or migrations."
+
+  - prompt: "Build me a Next.js dashboard page that lists users from an API route."
+    route_to: "nextjs"
+    why: "Building application UI/routes is runtime app code — out of harness scope and squarely the nextjs skill's job."
+
+# 1-2 concrete tasks the skill should guide, each with a checkable rubric.
+capability:
+  - scenario: "User points the agent at an organically-grown workspace (a Next.js subproject, a .env referencing STRIPE_SECRET_KEY and MAILJET_API_KEY, plus legacy 00-TOOLS/ and 03-NOTES/ folders) and asks: 'Control the harness — get this to the canonical structure.'"
+    must_include:
+      - "Runs the five phases in order SCAN -> AUDIT -> CONSENT -> APPLY -> VERIFY, and never writes anything before rendering the AUDIT and obtaining consent."
+      - "Detects providers from evidence (Stripe, Mailjet) and proposes 01-TOOLS/<PROVIDER>/ folders only because grep found imports/env_vars/deps — no speculative tools."
+      - "Renders the AUDIT as both a compact in-conversation summary AND a full HTML report at docs/audits/audit-YYYY-MM-DD-HHMM.html (gitignored), listing tools-to-create, legacy-folder per-file classification, ambiguous files, root-file plan, and a separate bold destructive-ops section."
+      - "Requires explicit consent ('yes, proceed' / 'go' / 'proceed'); treats silence/'ok'/'sure' as NO; and requires a SEPARATE second exact-string consent (quoting the path, e.g. 'yes, delete 00-TOOLS') before deleting any legacy folder."
+      - "Writes only .env.example (never a real .env, never fills credentials), merges existing CLAUDE.md/AGENTS.md additively (never overwrites user content), and leaves AMBIGUOUS files in place (preserving the legacy folder)."
+      - "Treats node_modules/.venv/.next/__pycache__/.git/dist/build/.dart_tool and all subproject runtime internals as out of scope — read for detection only, never moved or modified."
+      - "VERIFY runs `bash -n` on every generated test_connection.sh as a syntax gate, checks python3 availability, and prints a final report of files written, folders deleted (with consent quote), and ambiguous files preserved."
+
+  - scenario: "User drops a pile of mixed raw files (PDF invoice, a CSV export, screenshots, a .txt of meeting notes) into docs/inbox/ and says: 'Process the inbox and build my knowledge base.'"
+    must_include:
+      - "Runs the Inbox Sweep ('the agent goes for a walk') per references/wiki-protocol.md rather than inventing an ad-hoc structure."
+      - "Multiformat ingest (per references/ingest-formats.md): converts each input to raw/ markdown while preserving the original in _originals/ (or equivalent), handling PDF/image/CSV/txt."
+      - "Classifies content by inferred topic (e.g. finanzas/, legal/, crm/) — never hardcodes software-doc topics — and compiles into wiki/<topic>/ with cross-links (See Also)."
+      - "Maintains the canonical wiki artifacts: wiki/index.md (with Score column), wiki/log.md, wiki/gaps.md, wiki/scores.json."
+      - "Triggers a Maintenance Pass after the sweep (deterministic lint, score recomputation, gap detection, See Also sweep) and notes Micro-Improve / Deep Improve cadence."
+      - "Indexes the result in the root CLAUDE.md ## Knowledge map so other skills can read it."