robertkeus · robertkeus · Aug 12, 2026 · Aug 12, 2026 · Aug 12, 2026
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
@@ -0,0 +1,18 @@
+name: test
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  installer:
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - run: ./tests/install.sh
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,27 @@
+# Contributing
+
+Peter is pre-release. Bug reports, failed runs, narrow fixes, and reproducible
+examples are more useful than new orchestration features.
+
+## Report a run
+
+Include:
+
+- Peter commit, Claude Code version, model, operating system, and target repository commit
+- Exact goal and project gate commands
+- Completed, blocked, and discovered task counts
+- Human interventions, failed gates, and relevant redacted logs
+- Expected behavior and what happened instead
+
+Never include credentials, private source, or unredacted model transcripts from
+repositories you cannot share.
+
+## Change Peter
+
+1. Keep the skill dependency-free and the graph contract append-only.
+2. Update the nearest reference document when changing a gate or state rule.
+3. Run `./tests/install.sh` after installer changes.
+4. Exercise orchestration changes in a disposable repository and attach the
+   resulting graph, commits, and gate results to the pull request.
+
+Small, evidence-backed changes are preferred.
diff --git a/README.md b/README.md
@@ -6,7 +6,7 @@
 
 <p align="center">
   <em>You describe it. He graphs it. He ships it.</em><br>
-  <sub>Develop like <a href="#faq">Peter Steinberger</a> — and cut the token bill doing it.</sub>
+  <sub>Persistent work graphs and independently checked gates for Claude Code.</sub>
 </p>
 
 <p align="center">
@@ -16,26 +16,26 @@
 </p>
 
 <p align="center">
-  <strong>One goal in &middot; one gated commit per task &middot; zero babysitting</strong><br>
+  <strong>One goal in &middot; one gated commit per task &middot; bounded autonomy</strong><br>
   <sub>Autonomous epic builds for Claude Code — graph engineering with the bars built in.
   Not a framework, not a runtime: a skill, four agent files, and a JSONL contract.
   The parent session is the runtime.</sub>
 </p>
 
 ---
 
-You know him. You describe a feature at nine; by noon there's a branch with a
-commit per task, each one green. He doesn't ask whether you want tests. There
-are tests. There's an OWASP pass. The contrast ratios check out.
+Peter is a Claude Code skill for work that is too large or failure-prone for one
+prompt-and-hope loop. It decomposes a goal into a persistent dependency graph,
+runs each task through project checks, and produces one traceable commit per
+completed task. Repeated failures, missing credentials, and unresolved product
+decisions return control to the operator instead of retrying forever.
 
-Peter puts him inside Claude Code.
+> **Pre-release:** the orchestration contract may change before `v0.1.0`. A
+> reproducible public example run is still required before launch.
 
-## Before / after
+## Output shape
 
-You ask for a checkout flow. Your agent writes 800 lines, says "All done! 🎉",
-and the first click 500s. No tests, no migrations, `main` is broken.
-
-With peter:
+This is illustrative output, not a benchmark or completed public run:
 
 ```
 > /peter checkout flow with Stripe test mode
@@ -50,20 +50,19 @@ f3a91c2 task-9: e2e — happy path + declined card
 
 ## How it works
 
-Every task — loop or epic — goes through the same enforced sequence. No
-implementation code before the bars exist:
+No implementation code starts before its pass/fail bars exist:
 
 ```
 1. Spec + pass/fail bars   → written first, or nothing gets built
 2. Implement               → the minimum that meets the bars
 3. Machine gates           → unit, typecheck, lint, build, e2e
                              (real server, real database — no mocks)
-4. Security audit          → OWASP Top 10:2025, read-only verdict
-5. UI audit                → WCAG 2.2 AA + visual fidelity, read-only verdict
-6. Loop until green        → then exactly one commit
+4. Conditional audit       → security for trust boundaries; UI for rendered work
+5. Loop until green        → then exactly one commit
 ```
 
-Small changes run that loop once and stop.
+Small changes run that loop once and stop. Completed epics finish with the full
+test suite and both read-only audit passes when their prerequisites are available.
 
 Big goals become an **epic**: the goal is decomposed into a persistent work
 graph (`runs/<epic-id>/graph.jsonl`, append-only) of dependency-ordered tasks,
@@ -73,7 +72,7 @@ most the task in flight), discovered work filed as new tasks instead of
 scope-creeping the current one, until the epic closes or a stop condition hands
 control back.
 
-Implementation is zone-fenced across two builders: `backend-builder` owns
+Implementation is zone-fenced across two builders. `backend-builder` owns
 everything that doesn't render (API, CLI, library, pipeline, infra),
 `frontend-builder` owns everything that does. The write fence is what makes a
 parallel pair safe — a shared file has no fence, so co-located code goes to one
@@ -122,15 +121,30 @@ ESON is the message format only — `graph.jsonl` stays JSONL.
 
 ## Install
 
-The most effort peter will ever ask of you:
+Inspect the planned writes, then install:
 
 ```bash
-git clone https://github.com/robertkeus/peter && cd peter && ./install.sh
+git clone https://github.com/robertkeus/peter
+cd peter
+./install.sh --dry-run
+./install.sh
 ```
 
-That's it. `~/.claude` is not version-controlled; this repo is the tracked
-copy. `./install.sh pull` copies the other way, `./install.sh check` reports
-drift.
+The installer refuses to overwrite existing `skills/peter`, generated
+`skills/build`, or Peter agent files. `./install.sh --force` preserves collisions
+for restoration; `./install.sh uninstall` restores them. Forced replacement of
+files changed after installation also writes a timestamped copy under
+`~/.claude/peter-backups/`. Set `CLAUDE_CONFIG_DIR` to install somewhere other
+than `~/.claude`; the legacy `CLAUDE_HOME` variable remains supported.
+
+| Command | Effect |
+|---------|--------|
+| `./install.sh --dry-run` | Preview an install without writing files. |
+| `./install.sh` | Install, or update an unchanged Peter installation. |
+| `./install.sh --force` | Back up and replace reported collisions. |
+| `./install.sh check` | Report drift between the repository and installation. |
+| `./install.sh pull` | Copy installed Peter files back into the repository. |
+| `./install.sh uninstall` | Remove Peter and restore pre-install files. |
 
 ## Commands
 
@@ -146,8 +160,28 @@ skills/peter/references/         work-graph, state, eson wire format, e2e/securi
 agents/{backend,frontend}-builder.md   zone-fenced implementers
 agents/{security,ui}-auditor.md        read-only verdict-only auditors
 install.sh                       sync with ~/.claude
+tests/install.sh                 installer integration coverage
 ```
 
+## Requirements and limitations
+
+- A current Claude Code release with custom skills and subagents, plus Git and
+  Bash 3.2 or newer. The installer targets macOS and Linux; native Windows is
+  not tested.
+- The builders select Sonnet and the auditors select Opus. Your Claude plan must
+  provide those models. UI audits additionally require the `Claude_Browser` MCP
+  tools named in `agents/ui-auditor.md`; without them the UI verdict is not run.
+- Peter is prompt-level orchestration, not an operating-system sandbox. Run it
+  only in repositories and environments you are willing to let Claude Code
+  modify.
+- Autonomy is bounded. Ambiguous requirements, unavailable services, missing
+  credentials, operator-rejected dispatches, and repeated gate failures stop or
+  block work for human review.
+- Gates depend on the repository exposing runnable test, lint, build, E2E, and
+  audit prerequisites. Missing prerequisites are reported, not counted as passes.
+- Fewer handoff tokens do not guarantee a cheaper total run. Epics execute more
+  checks than a one-shot coding prompt; publish costs with the workload and model.
+
 ## FAQ
 
 **Why "peter"?**
@@ -178,12 +212,4 @@ builders already write minimal code — it's the house standard.
 
 [MIT](LICENSE). Use it, fork it, ship with it.
 
-## Star History
-
-<a href="https://www.star-history.com/green-pt/peter#history">
- <picture>
-   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=robertkeus/peter&type=Date&theme=dark" />
-   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=robertkeus/peter&type=Date" />
-   <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=robertkeus/peter&type=Date" />
- </picture>
-</a>
+Contributions start with [CONTRIBUTING.md](CONTRIBUTING.md).
diff --git a/docs/launch-checklist.md b/docs/launch-checklist.md
@@ -0,0 +1,45 @@
+# Launch checklist
+
+## Required before Hacker News
+
+- [x] Installer detects existing skill and agent filename collisions.
+- [x] Forced replacement preserves originals and uninstall restores them.
+- [x] Dry-run, uninstall, drift detection, and installer integration tests exist.
+- [x] README distinguishes bounded autonomy from unconditional hands-off operation.
+- [x] Limitations and contribution instructions are public.
+- [ ] Run Peter end-to-end against a small public repository at a pinned commit.
+- [ ] Complete `docs/launch-run-template.md` with unedited observed results.
+- [ ] Publish the work graph, commits, gate logs, human interventions, and cost data.
+- [ ] Record a short terminal demo from the same reproducible run.
+- [ ] Replace the illustrative README transcript with the public run.
+- [ ] Confirm the documented Claude Code version on a clean account or machine.
+- [ ] Create and smoke-test the `v0.1.0` release archive.
+
+## GitHub metadata
+
+Description:
+
+> Persistent work graphs and independently checked quality gates for autonomous Claude Code builds.
+
+Topics:
+
+`claude-code`, `agent-orchestration`, `ai-agents`, `developer-tools`, `open-source`
+
+Before launch, add the description and topics, confirm Issues are enabled, and
+leave the website blank unless a useful demo or documentation URL exists.
+
+## Release notes
+
+The `v0.1.0` notes should contain:
+
+- The problem and Peter's graph-and-gates approach
+- Supported environment and exact installation command
+- Link to the reproducible launch run
+- Known limitations and upgrade/uninstall instructions
+- SHA-256 checksum for the source archive if distributing one separately
+
+## Launch gate
+
+Do not submit to Hacker News until every required item is complete. Write the HN
+title and first comment personally; HN currently asks authors not to publish
+LLM-written or LLM-edited text.
diff --git a/docs/launch-run-template.md b/docs/launch-run-template.md
@@ -0,0 +1,63 @@
+# Peter launch run
+
+Status: **not yet run**. Replace every placeholder with observed data; do not
+publish this file as evidence while any result field is incomplete.
+
+## Environment
+
+| Field | Observed value |
+|-------|----------------|
+| Peter commit | `<full SHA>` |
+| Target repository and commit | `<public URL and full SHA>` |
+| Claude Code version | `<version>` |
+| Model | `<model>` |
+| Operating system | `<name and version>` |
+| Started / finished | `<UTC timestamps>` |
+
+## Goal
+
+Exact prompt:
+
+```text
+<goal passed to /peter>
+```
+
+Project gate commands:
+
+```text
+<unit, typecheck, lint, build, E2E, and audit commands>
+```
+
+## Results
+
+| Metric | Observed value | Evidence |
+|--------|----------------|----------|
+| Elapsed time | `<duration>` | `<transcript timestamps>` |
+| Tasks completed / blocked / discovered | `<counts>` | `<graph link>` |
+| Commits produced | `<count>` | `<git log link>` |
+| Gate failures repaired | `<count>` | `<redacted log links>` |
+| Human interventions | `<count and reasons>` | `<transcript links>` |
+| Input / output tokens | `<reported values or unavailable>` | `<source>` |
+| Reported cost | `<value or unavailable>` | `<source>` |
+| Final test result | `<command and result>` | `<CI or log link>` |
+| Security / UI verdict | `<result or not run with reason>` | `<artifact links>` |
+
+## Artifacts
+
+- Work graph: `<link to graph.jsonl>`
+- Specification: `<link to spec.md>`
+- Commit history: `<link to compare or branch>`
+- Gate logs: `<links>`
+- Audit returns: `<links or prerequisites unavailable>`
+- Terminal recording: `<link>`
+
+## Failures and limitations
+
+Record what Peter got wrong, work it could not complete, misleading status,
+unexpected cost, and every place a person intervened. Do not remove failed
+attempts that materially affect the result.
+
+## Reproduce
+
+Provide the exact checkout, installation, target setup, and `/peter` commands.
+State any credential or paid-service requirement without publishing secrets.