[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-83980":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":8,"htmlUrl":8,"language":9,"languages":8,"totalLinesOfCode":8,"stars":10,"forks":11,"watchers":12,"openIssues":13,"contributorsCount":13,"subscribersCount":13,"size":13,"stars1d":14,"stars7d":15,"stars30d":15,"stars90d":13,"forks30d":13,"starsTrendScore":16,"compositeScore":17,"rankGlobal":8,"rankLanguage":8,"license":8,"archived":18,"fork":18,"defaultBranch":19,"hasWiki":18,"hasPages":18,"topics":20,"createdAt":8,"pushedAt":8,"updatedAt":21,"readmeContent":22,"aiSummary":8,"trendingCount":13,"starSnapshotCount":13,"syncStatus":14,"lastSyncTime":23,"discoverSource":24},83980,"harness-engineering-demo","coleam00\u002Fharness-engineering-demo","coleam00",null,"Python",58,21,52,0,2,5,9,45.03,false,"main",[],"2026-06-12 04:01:42","# Harness Engineering Demo\n\nCompanion repo for the YouTube video **\"What is Harness Engineering?\"**\n\nA minimal, real **harness** built with the primitives already inside Claude Code —\nno framework required. It wraps the [Schedulr](https:\u002F\u002Fgithub.com\u002Fcoleam00\u002Fschedulr)\nbrownfield app with a **PIV loop** (Plan → Implement → Validate) so you can see\nwhat \"building your own harness\" actually looks like in production.\n\n> **Harness engineering** = building the context and workflows that wrap a coding\n> agent — the ecosystem it operates in — so it works the way *you* work: your\n> processes enforced, your standards applied, building like another engineer on\n> your team instead of a clever stranger guessing at your codebase.\n\n---\n\n## What's in here\n\n| Piece | What it shows |\n|-------|--------------|\n| `CLAUDE.md` + `.claude\u002Fcontext\u002F` | Rules + on-demand context derived from the real codebase (the \"AI Layer\") |\n| `.claude\u002Fskills\u002Fplan\u002FSKILL.md` | PIV step 1: analyze codebase + ticket, write `plans\u002F\u003Cfeature>-plan.md` |\n| `.claude\u002Fskills\u002Fimplement\u002FSKILL.md` | PIV step 2: read plan, execute tasks, run per-task validation, write `reports\u002F\u003Cfeature>-implementation-report.md` |\n| `.claude\u002Fskills\u002Fvalidate\u002FSKILL.md` | PIV step 3: run the full gate (ruff + mypy + pytest + tsc + vitest) |\n| `.claude\u002Fskills\u002Freview\u002FSKILL.md` | PIV step 4: delegate diff to the code-reviewer sub-agent, write `reports\u002F\u003Cfeature>-review.md` |\n| `.claude\u002Fagents\u002Fcode-reviewer.md` | Sub-agent that reviews diffs against CLAUDE.md rules using codebase-search MCP tools |\n| `.claude\u002Fhooks\u002Fpost_tool_use_lint.py` | PostToolUse hook: runs ruff (Python) or `tsc --noEmit` typecheck (TS) after every file edit |\n| `.claude\u002Fhooks\u002Fstop_validate.py` | Stop hook: blocks Claude from stopping until ruff + pytest are green |\n| `.claude\u002Fhooks\u002Fsecurity_guard.py` | PreToolUse hook: denies reading\u002Fediting\u002Fwriting any real `.env` and recursive directory deletion (rm -rf, rmdir, find -delete, git clean -d) |\n| `.claude\u002Fsettings.json` | Wires both hooks into Claude Code |\n| `.mcp.json` | Registers the `codebase-search` MCP server (AST-based symbol navigation) |\n| `tooling\u002Fmcp\u002Fcodebase_search.py` | FastMCP server exposing `where_is`, `find_references`, `outline` over the project's Python AST |\n| `tooling\u002Fpyproject.toml` | Isolated uv project declaring the `mcp` dependency for the tooling layer |\n| `ralph\u002Fralph.sh` + `ralph\u002Fralph.py` | The Ralph loop: strings headless Claude sessions together by re-feeding a spec each iteration |\n| `app\u002F` | Schedulr brownfield app (FastAPI + Next.js) — what the harness operates on |\n\n---\n\n## The two halves of a harness\n\n1. **Within a session (the AI Layer):** `CLAUDE.md`, context modules, commands, hooks — everything that shapes how Claude behaves inside one Claude Code session.\n2. **Across sessions (orchestration):** plan in one session → implement+validate in another → review in a third. Handed off via markdown files in `plans\u002F` and `reports\u002F`. Automated with the Ralph loop.\n\n---\n\n## Setup\n\nYou can let the agent do this. In a fresh Claude Code session, just ask it to read this section and get the app running. Or run it yourself:\n\n```bash\n# Prerequisites: Claude Code CLI, uv (Python), npm (Node 20+)\ncd app && docker compose up -d                                        # Postgres on host port 5433\ncd app\u002Fbackend && uv sync --extra dev && uv run alembic upgrade head  # backend deps + migrations\ncd app\u002Ffrontend && npm install                                        # frontend deps\n```\n\n## Running the PIV loop\n\nThe loop is two commands. Validation is not a step you run, it is enforced for you: `\u002Fimplement` validates each task as it goes, and the Stop hook blocks the agent from finishing until the full gate is green. That is what makes the loop self-validating.\n\n**0. Let the agent set up the app.** In a fresh Claude Code session at the repo root:\n\n```\nRead the README and get the app running for me: Postgres, backend deps, frontend deps, and migrations.\n```\n\n**1. Plan**\n\n```\n\u002Fplan \"add your feature request here\"\n```\n\nClaude reads the codebase, loads the relevant `.claude\u002Fcontext\u002F` modules, and writes `plans\u002F\u003Cfeature-slug>-plan.md`.\n\n**2. Implement**\n\n```\n\u002Fimplement plans\u002Fyour-plan.md\n```\n\nClaude reads the plan, executes each task with per-task validation, and writes `reports\u002F\u003Cfeature-slug>-implementation-report.md`. When it finishes, the Stop hook runs the full gate (ruff + mypy + pytest + tsc + vitest) and blocks until it is green.\n\n> `\u002Fvalidate` still exists if you want to run the gate explicitly (it is the same gate the Stop hook runs), but you do not need to call it as part of the loop.\n\n---\n\n## Hooks\n\nHooks run automatically, no invocation needed. Three are wired in `.claude\u002Fsettings.json`:\n\n- **PostToolUse lint** runs ruff (or a TS typecheck) after every file edit.\n- **Stop gate** blocks the agent from finishing until ruff + pytest are green. This is the hook that makes the PIV loop self-validating.\n- **PreToolUse security guard** denies access to real `.env` files and recursive deletes, even under `--dangerously-skip-permissions`.\n\n\u003Cdetails>\n\u003Csummary>Full hook details\u003C\u002Fsummary>\n\n**PostToolUse (static check):** After every `Edit`\u002F`Write`\u002F`MultiEdit`, `.claude\u002Fhooks\u002Fpost_tool_use_lint.py` runs:\n- Python files under `app\u002Fbackend\u002F` run `uv run ruff check \u003Cfile>`\n- TS\u002FTSX files under `app\u002Ffrontend\u002F` run `npx tsc --noEmit` (typecheck; this brownfield app has no ESLint configured, and `next lint` would prompt interactively)\n\nNon-blocking (always exits 0), so it surfaces issues without stopping work. Binaries are resolved via `shutil.which` so it works under Windows cmd.exe too.\n\n**Stop (validate gate):** Before Claude ends its turn, `.claude\u002Fhooks\u002Fstop_validate.py` runs ruff + pytest. If either fails it prints a JSON block decision and Claude is asked to fix the issue. It checks `stop_hook_active` in the hook JSON to avoid infinite loops.\n\n**PreToolUse (security guard):** Before any tool runs, `.claude\u002Fhooks\u002Fsecurity_guard.py` hard-denies two things:\n- Reading, editing, or writing a real `.env` file. It covers the Read\u002FEdit\u002FWrite\u002FMultiEdit\u002FNotebookEdit tools, Bash commands (cat, grep, sed, awk, xxd, base64, `python -c`, `source`\u002F`.`, `cp`, `find -exec cat`, obfuscated globs like `.e*` and `.??v`), and Glob\u002FGrep file targeting. Template files (`.env.example`, `.sample`, `.template`, `.dist`, `.defaults`) stay allowed so config scaffolding still works.\n- Recursive directory deletion: `rm -r`\u002F`-rf`\u002F`-fr`\u002F`-Rf`\u002F`--recursive`, `rmdir`, `find -delete`, `find -exec rm`, and `git clean -d`. Single-file `rm` is still allowed.\n\nIt returns a PreToolUse `permissionDecision: deny` with a reason (exit 0) so Claude gets the explanation and adapts, and fails open on malformed input so it can never brick a session. It still fires under `--dangerously-skip-permissions`, so it holds even during unattended Ralph runs.\n\n\u003C\u002Fdetails>\n\n---\n\n## Ralph loop\n\nRalph strings together headless Claude sessions, re-feeding a spec to a fresh `claude -p` process each iteration until a `DONE.txt` sentinel appears. It commits after each iteration, so every step is reversible.\n\n```bash\npython ralph\u002Fralph.py             # in-place (sandbox \u002F dedicated branch only)\npython ralph\u002Fralph.py --worktree  # self-isolating: Ralph makes its own worktree + branch\n```\n\nSee **`ralph\u002Fexample-run\u002F`** for a complete captured run of the CSV-export spec: the spec it was given, the iteration log, the fix plan with every spec item checked off, and the code it produced. Point here for what a finished loop looks like.\n\n\u003Cdetails>\n\u003Csummary>Full Ralph details (spec format, flags, worktree mode, parallel runs, guardrails)\u003C\u002Fsummary>\n\n**Example spec:** `ralph\u002FPROMPT.md` instructs Claude to add CSV export (SCH-142), with 8 verifiable spec items.\n\n```bash\n# From repo root\npython ralph\u002Fralph.py             # Python driver (cross-platform)\nbash ralph\u002Fralph.sh               # Bash driver (Linux\u002FmacOS)\n\n# Tune limits\nRALPH_MAX_ITER=10 RALPH_ITER_TIMEOUT=900 python ralph\u002Fralph.py\n\n# Self-isolating: Ralph creates its OWN worktree + branch and runs there\npython ralph\u002Fralph.py --worktree --branch ralph\u002Fcsv-export --cleanup\n\n# Parallel agents: several isolated runs at once, each its own branch + database\npython ralph\u002Fralph.py --worktree --branch ralph\u002Ffeature-a --db-isolate &\npython ralph\u002Fralph.py --worktree --branch ralph\u002Ffeature-b --db-isolate &\n```\n\nSee `ralph\u002FREADME.md` for full documentation, the worktree mode, and the parallel\u002FDB-isolation pattern.\n\n**Important:** `--dangerously-skip-permissions` is used by Ralph to allow unattended file writes. Run Ralph in a sandbox or dedicated worktree, never on your main branch. The `--worktree` flag gives you that isolation automatically.\n\n**Credit note (2026-06-15):** `claude -p` draws from a separate Agent SDK credit pool, not your interactive Claude Code subscription.\n\n\u003C\u002Fdetails>\n\n---\n\n## Repo layout\n\n```\nharness-engineering-demo\u002F\n├── CLAUDE.md                      # Global rules (the AI Layer)\n├── .mcp.json                      # Registers codebase-search MCP server\n├── .claude\u002F\n│   ├── settings.json              # Hook wiring\n│   ├── agents\u002F\n│   │   └── code-reviewer.md       # Sub-agent: reviews diffs against CLAUDE.md rules\n│   ├── skills\u002F\n│   │   ├── plan\u002FSKILL.md          # \u002Fplan skill (PIV step 1)\n│   │   ├── implement\u002FSKILL.md     # \u002Fimplement skill (PIV step 2)\n│   │   ├── validate\u002FSKILL.md      # \u002Fvalidate skill (PIV step 3)\n│   │   └── review\u002FSKILL.md        # \u002Freview skill (PIV step 4 — sub-agent delegation)\n│   ├── context\u002F\n│   │   ├── architecture.md        # Module map + add-resource pattern\n│   │   ├── auth.md                # JWT vs legacy session\n│   │   ├── codebase-search.md     # MCP tool descriptions (where_is \u002F find_references \u002F outline)\n│   │   ├── export-pattern.md      # ExportService protocol + CSV escaping\n│   │   ├── testing.md             # pytest + vitest patterns\n│   │   └── timezones.md           # TimezoneAwareTime + UTC storage rules\n│   └── hooks\u002F\n│       ├── post_tool_use_lint.py  # PostToolUse: lint on edit\n│       ├── stop_validate.py       # Stop: validation gate\n│       └── security_guard.py      # PreToolUse: block .env access + recursive deletes\n├── tooling\u002F\n│   ├── pyproject.toml             # Isolated uv project for tooling deps (mcp)\n│   └── mcp\u002F\n│       └── codebase_search.py     # FastMCP AST server: where_is \u002F find_references \u002F outline\n├── plans\u002F                         # \u002Fplan outputs land here\n├── reports\u002F                       # \u002Fimplement + \u002Freview outputs land here\n├── ralph\u002F\n│   ├── PROMPT.md                  # Example spec (CSV export)\n│   ├── ralph.sh                   # Bash loop driver\n│   ├── ralph.py                   # Python loop driver (cross-platform)\n│   ├── example-run\u002F               # A complete captured run (reference): log, fix plan, produced code\n│   └── README.md                  # Ralph documentation\n└── app\u002F                           # Schedulr brownfield app\n    ├── backend\u002F                   # FastAPI + SQLAlchemy 2.0, Python 3.12, uv\n    ├── frontend\u002F                  # Next.js 15 App Router, TypeScript\n    └── docker-compose.yml         # Postgres 16 (host 5433)\n```\n","2026-06-11 04:11:57","CREATED_QUERY"]