harness-learn

**Safety:** This skill only reads files. It does not modify code, run builds, or start services. # Harness Onboarding Walk a newcomer through harness engineering in three layers: the concept, this project's harness, and a hands-on walkthrough. **Invoke with:** `/harness-learn` --- ## Layer 1: The Concept Present this conversationally — not as a lecture. Adapt to who you're talking to (ask if they're a developer, PM, or agent new to this repo). ### What harness engineering is > When AI agents work on software, they tend to drift — skipping verification, losing context between sessions, producing inconsistent quality. Harness engineering gives them a disciplined, phased workflow instead. > > Every task follows focused phases — each with explicit instructions, real commands, and an exit gate. A universal engine loops through them automatically. ### How it works ``` You invoke the launcher: /implement "Add dark mode" ↓ Launcher creates a state file and hands off to the engine ↓ Engine loops through phase skills: [phase 1] → [phase 2] → ... → [phase N] → COMPLETE ↓ Each phase is a focused 40-140 line skill that: - Knows exactly what to do (real commands, not placeholders) - Has a checklist the engine validates before advancing - Records progress to a conversation file (survives session drops) ``` ### Why phases matter A single big prompt ("implement this feature, test it, create a PR") loses agent attention by the end. By phase 7, the agent has forgotten phase 2's instructions. Phase skills keep each turn focused — the agent sees one phase at a time. ### The improvement loop The harness gets better with use: ``` /harness-setup (discover your workflow, generate skills) ↓ Real work (/implement on actual tasks) ↓ /harness-retro (review what happened, fix skill gaps) ↓ Back to /harness-setup or next round of work ``` Pause here. Ask: > "That's the general concept. Want me to show you how it works specifically on this project?" --- ## Layer 2: This Project's Harness Read the project's harness files and present them in order. ### Step 1: Read the harness Read these files (skip any that don't exist): 1. `HARNESS.md` — overview and architecture 2. `.harness/lifecycle.md` — the discovered workflow 3. `CLAUDE.md` (or `.cursorrules`, `GEMINI.md`) — the Harness Context section 4. List all phase skills in the project's skill directory (`harness-*` and the launcher) ### Step 2: Present the workflow > "Here's how this project ships software:" Show the lifecycle as a table: | Phase | Owner | What happens | Key command | Gate | | ------------------- | ----- | ------------ | ----------- | ---- | | [from lifecycle.md] | | | | | Then show the profiles: > "Not every task goes through all phases:" | Profile | When to use | Which phases | | ------------------- | ----------- | ------------ | | [from lifecycle.md] | | | ### Step 3: Walk through each phase For each agent-owned phase, read the phase skill and explain: > **[Phase name]** — [one sentence on what it does] > > - Produces: [artifact] > - Verified by: [method] > - Key commands: `[actual commands from the skill]` > - Gate: [what must be true to proceed] > - Checklist: [items the engine validates] For human-owned gates, explain: > **[Phase name]** — This is where YOU step in. > > - The engine stops and waits for your approval. > - You [what the human does — review PR, test UI, approve deploy]. > - When you approve, the engine continues to the next phase. ### Step 4: Show a real example (if available) Check `.harness/conversations/` for past implementation records. If any exist, pick the most recent completed one and narrate: > "Here's what happened the last time someone used this harness:" > > - Task: [from conversation file] > - Profile: [profile used] > - Phases completed: [list with durations if available] > - What was produced: [commits, PR, evidence] > - Any friction: [issues from the conversation file] If `.harness/retros/` has retro records, mention: > "The harness has been through [N] retro rounds. Recent improvements: [list changes from retros]" If no conversation files exist: > "This harness hasn't been used yet — no past examples to show. Want to do a dry run?" --- ## Layer 3: Hands-On Walkthrough Ask: > "Want to try a dry run? Pick a task (or I'll suggest one) and I'll walk you through what each phase WOULD do — without actually running it." If they say yes: 1. Ask for a task description (or suggest a small one from the backlog if PM tool is available) 2. Determine which profile would apply 3. For each phase in that profile, explain what the agent WOULD do: - "In the **[phase]** phase, the agent would [action]. It would run `[command]` and check that [gate condition]." - Show what the state file would look like at each transition 4. Point out where human gates would pause the workflow 5. At the end: "That's the full lifecycle. Ready to try it for real? Run `/implement [task]`" If they say no: > "No problem. When you're ready, run `/implement` with a task description to start. The engine handles the rest." --- ## Adapt to the Audience - **Developer new to the repo:** Focus on the commands and where their code goes in the workflow. Skip philosophy. - **PM or non-technical:** Focus on the phases, gates, and what they'll see (PRs, status updates). Skip commands. - **Agent joining a team:** Focus on the state file, conversation recording, and escalation rules. They need to know when to stop and ask. - **Someone who's used harnesses before:** Skip Layer 1, go straight to Layer 2. Ask at the start: > "Before we start — are you a developer, PM, or agent? And have you seen a harness workflow before?" This shapes how deep each layer goes.