diff --git a/README.md b/README.md index 3f9c56c..e2f8f10 100644 --- a/README.md +++ b/README.md @@ -29,17 +29,11 @@ _Source: [docs/software-factory-story.excalidraw](docs/software-factory-story.ex The `parsa/` workflow above is generation one: a human conducts every phase, and each skill hardens one step — evidence-disciplined planning, independent -review lanes, first-pass QA, learning notes. `tyler/` ("Orchestra") is the -evolution: the same principles compiled into an autonomous pipeline. Capture -passes an adversarial Socratic gate, execution runs end to end on a remote -seat, review and QA self-correct on the open PR, and the human sits at the -edges — the gate going in, the PR coming out. The two sets now share their -strongest parts (evidence contracts, hosted PR visuals, external -verification), and `./sync-merged.sh` installs both side by side. - -![Orchestra workflow map](docs/tyler-workflow-map.png) - -_Source: [docs/tyler-workflow-map.excalidraw](docs/tyler-workflow-map.excalidraw)_ +review lanes, first-pass QA, learning notes. Tyler's "Orchestra" — the same +principles compiled into an autonomous pipeline — has moved to its own repo, +[dcouple/orchestra](https://github.com/dcouple/orchestra), where it syncs +one-way into each repo that uses it instead of installing to user-level +dirs. `./sync-merged.sh` now installs parsa's set only. ## How we work with LLMs @@ -235,16 +229,13 @@ parsa/ pane-chat/ Shared Pane Chat workflow references business/ Business agent skills (context, discussion, spec, artifact, release) seo/ SEO skills (briefing, strategy, readability, authority, drafting) -tyler/ - .claude/ Claude Code skills and agents (Claude orchestrates) - .codex/ Codex role skills, dispatched from Claude via codex exec - references/ Single-copy shared docs (output formats, criteria) both harnesses read ``` -Tyler's variant is a six-skill pipeline (`/discussion` → `/create-feature` / +Tyler's variant — a six-skill pipeline (`/discussion` → `/create-feature` / `/create-epic` / `/create-issue` → `/do` → `/postmortem`) where Claude orchestrates and Codex runs implementation, review, codebase research, and -investigation — see `tyler/README.md`. +investigation — lives in +[dcouple/orchestra](https://github.com/dcouple/orchestra). The skills are meant to be edited. The workflow shape should generalize, but the exact contents should change as your work changes. @@ -258,9 +249,9 @@ folders: - Codex: `~/.codex/skills/` **Use `./sync-merged.sh` — it's the whole setup in one command.** It installs -parsa's AND tyler's sets side by side (tyler's names win the few collisions; -parsa's originals are preserved under a `p-` prefix, and his skills are -re-wired to keep using them). It's idempotent and safe to re-run. +parsa's set. It's idempotent and safe to re-run. (Tyler's set is not +installed to user-level dirs anymore — it syncs one-way into each consumer +repo from [dcouple/orchestra](https://github.com/dcouple/orchestra).) ```bash REPO="$HOME/allGitHubRepos/skills" @@ -314,22 +305,15 @@ for skill in "$REPO"/parsa/seo/*/; do done ``` -### Both sets at once (merged sync) - -This is the default documented above — `./sync-merged.sh` instead -of the per-set blocks. It installs both sets; where names collide (currently -`discussion`, the `plan-reviewer` agent, and two Codex role skills), tyler's -version keeps the canonical name — his `/discussion` → `/create-*` → `/do` -pipeline stays the default — and parsa's original is preserved under a `p-` -prefix (`/p-discussion`, `p-plan-reviewer`, …). Collisions are detected -dynamically, and parsa's `create-plan` is re-wired to spawn `p-plan-reviewer` -so his planning loop keeps using his own reviewer. Inside this repo neither -sync matters: the harness namespaces both sets automatically -(`parsa:discussion`, `tyler:discussion`). - Do not use `--delete` unless you want this repo to remove other local skills. Restart Codex after new skills sync so the active session can see them. +If a previous merged sync left tyler's skills or `p-`-prefixed copies in +your user-level dirs, prune them by hand — tyler's set now arrives inside +each consumer repo via +[dcouple/orchestra](https://github.com/dcouple/orchestra), not user-level +installs. + ## Background This grew out of the workflow described diff --git a/docs/tyler-workflow-map.excalidraw b/docs/tyler-workflow-map.excalidraw deleted file mode 100644 index 9355774..0000000 --- a/docs/tyler-workflow-map.excalidraw +++ /dev/null @@ -1,2569 +0,0 @@ -{ - "type": "excalidraw", - "version": 2, - "source": "https://excalidraw.com", - "elements": [ - { - "id": "m501", - "type": "text", - "x": 620, - "y": 25, - "width": 911.4, - "height": 39.0, - "angle": 0, - "strokeColor": "#1e1e1e", - "backgroundColor": "transparent", - "fillStyle": "solid", - "strokeWidth": 2, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "groupIds": [], - "frameId": null, - "roundness": null, - "seed": 1503, - "version": 1, - "versionNonce": 2505, - "isDeleted": false, - "boundElements": null, - "updated": 1, - "link": null, - "locked": false, - "text": "Orchestra \u2014 clarity, capture, execution, learning", - "fontSize": 30, - "fontFamily": 3, - "textAlign": "left", - "verticalAlign": "top", - "originalText": "Orchestra \u2014 clarity, capture, execution, learning", - "containerId": null, - "lineHeight": 1.3 - }, - { - "id": "m502", - "type": "text", - "x": 150, - "y": 90, - "width": 27.28, - "height": 57.2, - "angle": 0, - "strokeColor": "#e9ecef", - "backgroundColor": "transparent", - "fillStyle": "solid", - "strokeWidth": 2, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "groupIds": [], - "frameId": null, - "roundness": null, - "seed": 1506, - "version": 1, - "versionNonce": 2510, - "isDeleted": false, - "boundElements": null, - "updated": 1, - "link": null, - "locked": false, - "text": "1", - "fontSize": 44, - "fontFamily": 3, - "textAlign": "left", - "verticalAlign": "top", - "originalText": "1", - "containerId": null, - "lineHeight": 1.3 - }, - { - "id": "m503", - "type": "text", - "x": 600, - "y": 90, - "width": 27.28, - "height": 57.2, - "angle": 0, - "strokeColor": "#e9ecef", - "backgroundColor": "transparent", - "fillStyle": "solid", - "strokeWidth": 2, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "groupIds": [], - "frameId": null, - "roundness": null, - "seed": 1509, - "version": 1, - "versionNonce": 2515, - "isDeleted": false, - "boundElements": null, - "updated": 1, - "link": null, - "locked": false, - "text": "2", - "fontSize": 44, - "fontFamily": 3, - "textAlign": "left", - "verticalAlign": "top", - "originalText": "2", - "containerId": null, - "lineHeight": 1.3 - }, - { - "id": "m504", - "type": "text", - "x": 1420, - "y": 90, - "width": 27.28, - "height": 57.2, - "angle": 0, - "strokeColor": "#e9ecef", - "backgroundColor": "transparent", - "fillStyle": "solid", - "strokeWidth": 2, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "groupIds": [], - "frameId": null, - "roundness": null, - "seed": 1512, - "version": 1, - "versionNonce": 2520, - "isDeleted": false, - "boundElements": null, - "updated": 1, - "link": null, - "locked": false, - "text": "3", - "fontSize": 44, - "fontFamily": 3, - "textAlign": "left", - "verticalAlign": "top", - "originalText": "3", - "containerId": null, - "lineHeight": 1.3 - }, - { - "id": "m505", - "type": "text", - "x": 1900, - "y": 90, - "width": 27.28, - "height": 57.2, - "angle": 0, - "strokeColor": "#e9ecef", - "backgroundColor": "transparent", - "fillStyle": "solid", - "strokeWidth": 2, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "groupIds": [], - "frameId": null, - "roundness": null, - "seed": 1515, - "version": 1, - "versionNonce": 2525, - "isDeleted": false, - "boundElements": null, - "updated": 1, - "link": null, - "locked": false, - "text": "4", - "fontSize": 44, - "fontFamily": 3, - "textAlign": "left", - "verticalAlign": "top", - "originalText": "4", - "containerId": null, - "lineHeight": 1.3 - }, - { - "id": "m506", - "type": "ellipse", - "x": 70, - "y": 170, - "width": 250, - "height": 76, - "angle": 0, - "strokeColor": "#1971c2", - "backgroundColor": "#e7f5ff", - "fillStyle": "solid", - "strokeWidth": 2, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "groupIds": [], - "frameId": null, - "roundness": null, - "seed": 1518, - "version": 1, - "versionNonce": 2530, - "isDeleted": false, - "boundElements": null, - "updated": 1, - "link": null, - "locked": false - }, - { - "id": "m507", - "type": "text", - "x": 128, - "y": 200, - "width": 109.12, - "height": 20.8, - "angle": 0, - "strokeColor": "#1971c2", - "backgroundColor": "transparent", - "fillStyle": "solid", - "strokeWidth": 2, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "groupIds": [], - "frameId": null, - "roundness": null, - "seed": 1521, - "version": 1, - "versionNonce": 2535, - "isDeleted": false, - "boundElements": null, - "updated": 1, - "link": null, - "locked": false, - "text": "/discussion", - "fontSize": 16, - "fontFamily": 3, - "textAlign": "left", - "verticalAlign": "top", - "originalText": "/discussion", - "containerId": null, - "lineHeight": 1.3 - }, - { - "id": "m508", - "type": "text", - "x": 70, - "y": 260, - "width": 163.68, - "height": 15.600000000000001, - "angle": 0, - "strokeColor": "#adb5bd", - "backgroundColor": "transparent", - "fillStyle": "solid", - "strokeWidth": 2, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "groupIds": [], - "frameId": null, - "roundness": null, - "seed": 1524, - "version": 1, - "versionNonce": 2540, - "isDeleted": false, - "boundElements": null, - "updated": 1, - "link": null, - "locked": false, - "text": "clarity + decision log", - "fontSize": 12, - "fontFamily": 3, - "textAlign": "left", - "verticalAlign": "top", - "originalText": "clarity + decision log", - "containerId": null, - "lineHeight": 1.3 - }, - { - "id": "m509", - "type": "arrow", - "x": 328, - "y": 208, - "width": 52, - "height": 1, - "angle": 0, - "strokeColor": "#868e96", - "backgroundColor": "transparent", - "fillStyle": "solid", - "strokeWidth": 2, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "groupIds": [], - "frameId": null, - "roundness": null, - "seed": 1527, - "version": 1, - "versionNonce": 2545, - "isDeleted": false, - "boundElements": null, - "updated": 1, - "link": null, - "locked": false, - "points": [ - [ - 0, - 0 - ], - [ - 52, - 0 - ] - ], - "startBinding": null, - "endBinding": null, - "startArrowhead": null, - "endArrowhead": "arrow", - "lastCommittedPoint": null, - "elbowed": false - }, - { - "id": "m510", - "type": "rectangle", - "x": 388, - "y": 168, - "width": 320, - "height": 80, - "angle": 0, - "strokeColor": "#1971c2", - "backgroundColor": "#e7f5ff", - "fillStyle": "solid", - "strokeWidth": 2, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 3 - }, - "seed": 1530, - "version": 1, - "versionNonce": 2550, - "isDeleted": false, - "boundElements": null, - "updated": 1, - "link": null, - "locked": false - }, - { - "id": "m511", - "type": "text", - "x": 417.8, - "y": 189.8, - "width": 260.4, - "height": 36.4, - "angle": 0, - "strokeColor": "#1971c2", - "backgroundColor": "transparent", - "fillStyle": "solid", - "strokeWidth": 2, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "groupIds": [], - "frameId": null, - "roundness": null, - "seed": 1533, - "version": 1, - "versionNonce": 2555, - "isDeleted": false, - "boundElements": null, - "updated": 1, - "link": null, - "locked": false, - "text": "/create-feature \u00b7 epic \u00b7 issue\nitem.md + EARS criteria", - "fontSize": 14, - "fontFamily": 3, - "textAlign": "left", - "verticalAlign": "top", - "originalText": "/create-feature \u00b7 epic \u00b7 issue\nitem.md + EARS criteria", - "containerId": null, - "lineHeight": 1.3 - }, - { - "id": "m512", - "type": "arrow", - "x": 716, - "y": 208, - "width": 46, - "height": 1, - "angle": 0, - "strokeColor": "#868e96", - "backgroundColor": "transparent", - "fillStyle": "solid", - "strokeWidth": 2, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "groupIds": [], - "frameId": null, - "roundness": null, - "seed": 1536, - "version": 1, - "versionNonce": 2560, - "isDeleted": false, - "boundElements": null, - "updated": 1, - "link": null, - "locked": false, - "points": [ - [ - 0, - 0 - ], - [ - 46, - 0 - ] - ], - "startBinding": null, - "endBinding": null, - "startArrowhead": null, - "endArrowhead": "arrow", - "lastCommittedPoint": null, - "elbowed": false - }, - { - "id": "m513", - "type": "diamond", - "x": 770, - "y": 154, - "width": 200, - "height": 104, - "angle": 0, - "strokeColor": "#f08c00", - "backgroundColor": "#ffec99", - "fillStyle": "solid", - "strokeWidth": 3, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "groupIds": [], - "frameId": null, - "roundness": null, - "seed": 1539, - "version": 1, - "versionNonce": 2565, - "isDeleted": false, - "boundElements": null, - "updated": 1, - "link": null, - "locked": false - }, - { - "id": "m514", - "type": "text", - "x": 832.8, - "y": 186.5, - "width": 74.4, - "height": 39.0, - "angle": 0, - "strokeColor": "#f08c00", - "backgroundColor": "transparent", - "fillStyle": "solid", - "strokeWidth": 2, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "groupIds": [], - "frameId": null, - "roundness": null, - "seed": 1542, - "version": 1, - "versionNonce": 2570, - "isDeleted": false, - "boundElements": null, - "updated": 1, - "link": null, - "locked": false, - "text": "Socratic\ngate", - "fontSize": 15, - "fontFamily": 3, - "textAlign": "left", - "verticalAlign": "top", - "originalText": "Socratic\ngate", - "containerId": null, - "lineHeight": 1.3 - }, - { - "id": "m515", - "type": "text", - "x": 762, - "y": 268, - "width": 163.68, - "height": 31.200000000000003, - "angle": 0, - "strokeColor": "#adb5bd", - "backgroundColor": "transparent", - "fillStyle": "solid", - "strokeWidth": 2, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "groupIds": [], - "frameId": null, - "roundness": null, - "seed": 1545, - "version": 1, - "versionNonce": 2575, - "isDeleted": false, - "boundElements": null, - "updated": 1, - "link": null, - "locked": false, - "text": "challenges the premise\nbefore publish", - "fontSize": 12, - "fontFamily": 3, - "textAlign": "left", - "verticalAlign": "top", - "originalText": "challenges the premise\nbefore publish", - "containerId": null, - "lineHeight": 1.3 - }, - { - "id": "m516", - "type": "arrow", - "x": 978, - "y": 208, - "width": 46, - "height": 1, - "angle": 0, - "strokeColor": "#868e96", - "backgroundColor": "transparent", - "fillStyle": "solid", - "strokeWidth": 2, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "groupIds": [], - "frameId": null, - "roundness": null, - "seed": 1548, - "version": 1, - "versionNonce": 2580, - "isDeleted": false, - "boundElements": null, - "updated": 1, - "link": null, - "locked": false, - "points": [ - [ - 0, - 0 - ], - [ - 46, - 0 - ] - ], - "startBinding": null, - "endBinding": null, - "startArrowhead": null, - "endArrowhead": "arrow", - "lastCommittedPoint": null, - "elbowed": false - }, - { - "id": "m517", - "type": "rectangle", - "x": 1032, - "y": 176, - "width": 230, - "height": 64, - "angle": 0, - "strokeColor": "#868e96", - "backgroundColor": "transparent", - "fillStyle": "solid", - "strokeWidth": 1, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 3 - }, - "seed": 1551, - "version": 1, - "versionNonce": 2585, - "isDeleted": false, - "boundElements": null, - "updated": 1, - "link": null, - "locked": false - }, - { - "id": "m518", - "type": "text", - "x": 1086.55, - "y": 191.1, - "width": 120.9, - "height": 33.800000000000004, - "angle": 0, - "strokeColor": "#868e96", - "backgroundColor": "transparent", - "fillStyle": "solid", - "strokeWidth": 2, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "groupIds": [], - "frameId": null, - "roundness": null, - "seed": 1554, - "version": 1, - "versionNonce": 2590, - "isDeleted": false, - "boundElements": null, - "updated": 1, - "link": null, - "locked": false, - "text": "publish\nGitHub + Notion", - "fontSize": 13, - "fontFamily": 3, - "textAlign": "left", - "verticalAlign": "top", - "originalText": "publish\nGitHub + Notion", - "containerId": null, - "lineHeight": 1.3 - }, - { - "id": "m519", - "type": "arrow", - "x": 1270, - "y": 208, - "width": 52, - "height": 1, - "angle": 0, - "strokeColor": "#868e96", - "backgroundColor": "transparent", - "fillStyle": "solid", - "strokeWidth": 2, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "groupIds": [], - "frameId": null, - "roundness": null, - "seed": 1557, - "version": 1, - "versionNonce": 2595, - "isDeleted": false, - "boundElements": null, - "updated": 1, - "link": null, - "locked": false, - "points": [ - [ - 0, - 0 - ], - [ - 52, - 0 - ] - ], - "startBinding": null, - "endBinding": null, - "startArrowhead": null, - "endArrowhead": "arrow", - "lastCommittedPoint": null, - "elbowed": false - }, - { - "id": "m520", - "type": "rectangle", - "x": 1330, - "y": 152, - "width": 330, - "height": 110, - "angle": 0, - "strokeColor": "#2f9e44", - "backgroundColor": "#d3f9d8", - "fillStyle": "solid", - "strokeWidth": 4, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 3 - }, - "seed": 1560, - "version": 1, - "versionNonce": 2600, - "isDeleted": false, - "boundElements": null, - "updated": 1, - "link": null, - "locked": false - }, - { - "id": "m521", - "type": "text", - "x": 1420.6, - "y": 191.4, - "width": 148.8, - "height": 31.200000000000003, - "angle": 0, - "strokeColor": "#2f9e44", - "backgroundColor": "transparent", - "fillStyle": "solid", - "strokeWidth": 2, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "groupIds": [], - "frameId": null, - "roundness": null, - "seed": 1563, - "version": 1, - "versionNonce": 2605, - "isDeleted": false, - "boundElements": null, - "updated": 1, - "link": null, - "locked": false, - "text": "/do ", - "fontSize": 24, - "fontFamily": 3, - "textAlign": "left", - "verticalAlign": "top", - "originalText": "/do ", - "containerId": null, - "lineHeight": 1.3 - }, - { - "id": "m522", - "type": "text", - "x": 1355, - "y": 268, - "width": 338.52, - "height": 16.900000000000002, - "angle": 0, - "strokeColor": "#2f9e44", - "backgroundColor": "transparent", - "fillStyle": "solid", - "strokeWidth": 2, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "groupIds": [], - "frameId": null, - "roundness": null, - "seed": 1566, - "version": 1, - "versionNonce": 2610, - "isDeleted": false, - "boundElements": null, - "updated": 1, - "link": null, - "locked": false, - "text": "fully autonomous \u2014 human returns at the PR", - "fontSize": 13, - "fontFamily": 3, - "textAlign": "left", - "verticalAlign": "top", - "originalText": "fully autonomous \u2014 human returns at the PR", - "containerId": null, - "lineHeight": 1.3 - }, - { - "id": "m523", - "type": "arrow", - "x": 1668, - "y": 208, - "width": 52, - "height": 1, - "angle": 0, - "strokeColor": "#868e96", - "backgroundColor": "transparent", - "fillStyle": "solid", - "strokeWidth": 2, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "groupIds": [], - "frameId": null, - "roundness": null, - "seed": 1569, - "version": 1, - "versionNonce": 2615, - "isDeleted": false, - "boundElements": null, - "updated": 1, - "link": null, - "locked": false, - "points": [ - [ - 0, - 0 - ], - [ - 52, - 0 - ] - ], - "startBinding": null, - "endBinding": null, - "startArrowhead": null, - "endArrowhead": "arrow", - "lastCommittedPoint": null, - "elbowed": false - }, - { - "id": "m524", - "type": "rectangle", - "x": 1728, - "y": 176, - "width": 270, - "height": 64, - "angle": 0, - "strokeColor": "#9c36b5", - "backgroundColor": "transparent", - "fillStyle": "solid", - "strokeWidth": 1, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 3 - }, - "seed": 1572, - "version": 1, - "versionNonce": 2620, - "isDeleted": false, - "boundElements": null, - "updated": 1, - "link": null, - "locked": false - }, - { - "id": "m525", - "type": "text", - "x": 1794.49, - "y": 191.1, - "width": 137.02, - "height": 33.800000000000004, - "angle": 0, - "strokeColor": "#9c36b5", - "backgroundColor": "transparent", - "fillStyle": "solid", - "strokeWidth": 2, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "groupIds": [], - "frameId": null, - "roundness": null, - "seed": 1575, - "version": 1, - "versionNonce": 2625, - "isDeleted": false, - "boundElements": null, - "updated": 1, - "link": null, - "locked": false, - "text": "/postmortem\none system change", - "fontSize": 13, - "fontFamily": 3, - "textAlign": "left", - "verticalAlign": "top", - "originalText": "/postmortem\none system change", - "containerId": null, - "lineHeight": 1.3 - }, - { - "id": "m526", - "type": "text", - "x": 1728, - "y": 250, - "width": 186.0, - "height": 15.600000000000001, - "angle": 0, - "strokeColor": "#adb5bd", - "backgroundColor": "transparent", - "fillStyle": "solid", - "strokeWidth": 2, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "groupIds": [], - "frameId": null, - "roundness": null, - "seed": 1578, - "version": 1, - "versionNonce": 2630, - "isDeleted": false, - "boundElements": null, - "updated": 1, - "link": null, - "locked": false, - "text": "when a result falls short", - "fontSize": 12, - "fontFamily": 3, - "textAlign": "left", - "verticalAlign": "top", - "originalText": "when a result falls short", - "containerId": null, - "lineHeight": 1.3 - }, - { - "id": "m527", - "type": "line", - "x": 1340, - "y": 262, - "width": 1290, - "height": 118, - "angle": 0, - "strokeColor": "#b2f2bb", - "backgroundColor": "transparent", - "fillStyle": "solid", - "strokeWidth": 2, - "strokeStyle": "dashed", - "roughness": 0, - "opacity": 100, - "groupIds": [], - "frameId": null, - "roundness": null, - "seed": 1581, - "version": 1, - "versionNonce": 2635, - "isDeleted": false, - "boundElements": null, - "updated": 1, - "link": null, - "locked": false, - "points": [ - [ - 0, - 0 - ], - [ - -1290, - 118 - ] - ], - "startBinding": null, - "endBinding": null, - "startArrowhead": null, - "endArrowhead": null, - "lastCommittedPoint": null, - "elbowed": false - }, - { - "id": "m528", - "type": "line", - "x": 1655, - "y": 262, - "width": 465, - "height": 118, - "angle": 0, - "strokeColor": "#b2f2bb", - "backgroundColor": "transparent", - "fillStyle": "solid", - "strokeWidth": 2, - "strokeStyle": "dashed", - "roughness": 0, - "opacity": 100, - "groupIds": [], - "frameId": null, - "roundness": null, - "seed": 1584, - "version": 1, - "versionNonce": 2640, - "isDeleted": false, - "boundElements": null, - "updated": 1, - "link": null, - "locked": false, - "points": [ - [ - 0, - 0 - ], - [ - 465, - 118 - ] - ], - "startBinding": null, - "endBinding": null, - "startArrowhead": null, - "endArrowhead": null, - "lastCommittedPoint": null, - "elbowed": false - }, - { - "id": "m529", - "type": "rectangle", - "x": 40, - "y": 380, - "width": 2085, - "height": 260, - "angle": 0, - "strokeColor": "#b2f2bb", - "backgroundColor": "#f2fbf4", - "fillStyle": "solid", - "strokeWidth": 2, - "strokeStyle": "dashed", - "roughness": 0, - "opacity": 100, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 3 - }, - "seed": 1587, - "version": 1, - "versionNonce": 2645, - "isDeleted": false, - "boundElements": null, - "updated": 1, - "link": null, - "locked": false - }, - { - "id": "m530", - "type": "text", - "x": 70, - "y": 398, - "width": 111.6, - "height": 23.400000000000002, - "angle": 0, - "strokeColor": "#2f9e44", - "backgroundColor": "transparent", - "fillStyle": "solid", - "strokeWidth": 2, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "groupIds": [], - "frameId": null, - "roundness": null, - "seed": 1590, - "version": 1, - "versionNonce": 2650, - "isDeleted": false, - "boundElements": null, - "updated": 1, - "link": null, - "locked": false, - "text": "inside /do", - "fontSize": 18, - "fontFamily": 3, - "textAlign": "left", - "verticalAlign": "top", - "originalText": "inside /do", - "containerId": null, - "lineHeight": 1.3 - }, - { - "id": "m531", - "type": "diamond", - "x": 80, - "y": 456, - "width": 160, - "height": 80, - "angle": 0, - "strokeColor": "#1971c2", - "backgroundColor": "#e7f5ff", - "fillStyle": "solid", - "strokeWidth": 2, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "groupIds": [], - "frameId": null, - "roundness": null, - "seed": 1593, - "version": 1, - "versionNonce": 2655, - "isDeleted": false, - "boundElements": null, - "updated": 1, - "link": null, - "locked": false - }, - { - "id": "m532", - "type": "text", - "x": 111.64, - "y": 479.1, - "width": 96.72, - "height": 33.800000000000004, - "angle": 0, - "strokeColor": "#1971c2", - "backgroundColor": "transparent", - "fillStyle": "solid", - "strokeWidth": 2, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "groupIds": [], - "frameId": null, - "roundness": null, - "seed": 1596, - "version": 1, - "versionNonce": 2660, - "isDeleted": false, - "boundElements": null, - "updated": 1, - "link": null, - "locked": false, - "text": "lane?\nlight | full", - "fontSize": 13, - "fontFamily": 3, - "textAlign": "left", - "verticalAlign": "top", - "originalText": "lane?\nlight | full", - "containerId": null, - "lineHeight": 1.3 - }, - { - "id": "m533", - "type": "text", - "x": 72, - "y": 548, - "width": 225.06, - "height": 14.3, - "angle": 0, - "strokeColor": "#adb5bd", - "backgroundColor": "transparent", - "fillStyle": "solid", - "strokeWidth": 2, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "groupIds": [], - "frameId": null, - "roundness": null, - "seed": 1599, - "version": 1, - "versionNonce": 2665, - "isDeleted": false, - "boundElements": null, - "updated": 1, - "link": null, - "locked": false, - "text": "light: no dossier, 1-pass reviews", - "fontSize": 11, - "fontFamily": 3, - "textAlign": "left", - "verticalAlign": "top", - "originalText": "light: no dossier, 1-pass reviews", - "containerId": null, - "lineHeight": 1.3 - }, - { - "id": "m534", - "type": "arrow", - "x": 245, - "y": 494, - "width": 40, - "height": 1, - "angle": 0, - "strokeColor": "#868e96", - "backgroundColor": "transparent", - "fillStyle": "solid", - "strokeWidth": 2, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "groupIds": [], - "frameId": null, - "roundness": null, - "seed": 1602, - "version": 1, - "versionNonce": 2670, - "isDeleted": false, - "boundElements": null, - "updated": 1, - "link": null, - "locked": false, - "points": [ - [ - 0, - 0 - ], - [ - 40, - 0 - ] - ], - "startBinding": null, - "endBinding": null, - "startArrowhead": null, - "endArrowhead": "arrow", - "lastCommittedPoint": null, - "elbowed": false - }, - { - "id": "m535", - "type": "rectangle", - "x": 290, - "y": 460, - "width": 240, - "height": 68, - "angle": 0, - "strokeColor": "#1e1e1e", - "backgroundColor": "#ffffff", - "fillStyle": "solid", - "strokeWidth": 2, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 3 - }, - "seed": 1605, - "version": 1, - "versionNonce": 2675, - "isDeleted": false, - "boundElements": null, - "updated": 1, - "link": null, - "locked": false - }, - { - "id": "m536", - "type": "text", - "x": 336.22, - "y": 475.8, - "width": 147.56, - "height": 36.4, - "angle": 0, - "strokeColor": "#1e1e1e", - "backgroundColor": "transparent", - "fillStyle": "solid", - "strokeWidth": 2, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "groupIds": [], - "frameId": null, - "roundness": null, - "seed": 1608, - "version": 1, - "versionNonce": 2680, - "isDeleted": false, - "boundElements": null, - "updated": 1, - "link": null, - "locked": false, - "text": "plan\nevidence contract", - "fontSize": 14, - "fontFamily": 3, - "textAlign": "left", - "verticalAlign": "top", - "originalText": "plan\nevidence contract", - "containerId": null, - "lineHeight": 1.3 - }, - { - "id": "m537", - "type": "text", - "x": 285, - "y": 540, - "width": 190.96, - "height": 14.3, - "angle": 0, - "strokeColor": "#adb5bd", - "backgroundColor": "transparent", - "fillStyle": "solid", - "strokeWidth": 2, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "groupIds": [], - "frameId": null, - "roundness": null, - "seed": 1611, - "version": 1, - "versionNonce": 2685, - "isDeleted": false, - "boundElements": null, - "updated": 1, - "link": null, - "locked": false, - "text": "dossier: code + web research", - "fontSize": 11, - "fontFamily": 3, - "textAlign": "left", - "verticalAlign": "top", - "originalText": "dossier: code + web research", - "containerId": null, - "lineHeight": 1.3 - }, - { - "id": "m538", - "type": "arrow", - "x": 535, - "y": 494, - "width": 40, - "height": 1, - "angle": 0, - "strokeColor": "#868e96", - "backgroundColor": "transparent", - "fillStyle": "solid", - "strokeWidth": 2, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "groupIds": [], - "frameId": null, - "roundness": null, - "seed": 1614, - "version": 1, - "versionNonce": 2690, - "isDeleted": false, - "boundElements": null, - "updated": 1, - "link": null, - "locked": false, - "points": [ - [ - 0, - 0 - ], - [ - 40, - 0 - ] - ], - "startBinding": null, - "endBinding": null, - "startArrowhead": null, - "endArrowhead": "arrow", - "lastCommittedPoint": null, - "elbowed": false - }, - { - "id": "m539", - "type": "rectangle", - "x": 580, - "y": 456, - "width": 210, - "height": 76, - "angle": 0, - "strokeColor": "#f08c00", - "backgroundColor": "#ffec99", - "fillStyle": "solid", - "strokeWidth": 3, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 3 - }, - "seed": 1617, - "version": 1, - "versionNonce": 2695, - "isDeleted": false, - "boundElements": null, - "updated": 1, - "link": null, - "locked": false - }, - { - "id": "m540", - "type": "text", - "x": 604.4, - "y": 477.1, - "width": 161.2, - "height": 33.800000000000004, - "angle": 0, - "strokeColor": "#f08c00", - "backgroundColor": "transparent", - "fillStyle": "solid", - "strokeWidth": 2, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "groupIds": [], - "frameId": null, - "roundness": null, - "seed": 1620, - "version": 1, - "versionNonce": 2700, - "isDeleted": false, - "boundElements": null, - "updated": 1, - "link": null, - "locked": false, - "text": "plan review\n2 parallel reviewers", - "fontSize": 13, - "fontFamily": 3, - "textAlign": "left", - "verticalAlign": "top", - "originalText": "plan review\n2 parallel reviewers", - "containerId": null, - "lineHeight": 1.3 - }, - { - "id": "m541", - "type": "arrow", - "x": 795, - "y": 494, - "width": 40, - "height": 1, - "angle": 0, - "strokeColor": "#868e96", - "backgroundColor": "transparent", - "fillStyle": "solid", - "strokeWidth": 2, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "groupIds": [], - "frameId": null, - "roundness": null, - "seed": 1623, - "version": 1, - "versionNonce": 2705, - "isDeleted": false, - "boundElements": null, - "updated": 1, - "link": null, - "locked": false, - "points": [ - [ - 0, - 0 - ], - [ - 40, - 0 - ] - ], - "startBinding": null, - "endBinding": null, - "startArrowhead": null, - "endArrowhead": "arrow", - "lastCommittedPoint": null, - "elbowed": false - }, - { - "id": "m542", - "type": "rectangle", - "x": 840, - "y": 460, - "width": 215, - "height": 68, - "angle": 0, - "strokeColor": "#1e1e1e", - "backgroundColor": "#ffffff", - "fillStyle": "solid", - "strokeWidth": 2, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 3 - }, - "seed": 1626, - "version": 1, - "versionNonce": 2710, - "isDeleted": false, - "boundElements": null, - "updated": 1, - "link": null, - "locked": false - }, - { - "id": "m543", - "type": "text", - "x": 878.06, - "y": 475.8, - "width": 138.88, - "height": 36.4, - "angle": 0, - "strokeColor": "#1e1e1e", - "backgroundColor": "transparent", - "fillStyle": "solid", - "strokeWidth": 2, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "groupIds": [], - "frameId": null, - "roundness": null, - "seed": 1629, - "version": 1, - "versionNonce": 2715, - "isDeleted": false, - "boundElements": null, - "updated": 1, - "link": null, - "locked": false, - "text": "implement\nroute by surface", - "fontSize": 14, - "fontFamily": 3, - "textAlign": "left", - "verticalAlign": "top", - "originalText": "implement\nroute by surface", - "containerId": null, - "lineHeight": 1.3 - }, - { - "id": "m544", - "type": "arrow", - "x": 1060, - "y": 494, - "width": 40, - "height": 1, - "angle": 0, - "strokeColor": "#868e96", - "backgroundColor": "transparent", - "fillStyle": "solid", - "strokeWidth": 2, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "groupIds": [], - "frameId": null, - "roundness": null, - "seed": 1632, - "version": 1, - "versionNonce": 2720, - "isDeleted": false, - "boundElements": null, - "updated": 1, - "link": null, - "locked": false, - "points": [ - [ - 0, - 0 - ], - [ - 40, - 0 - ] - ], - "startBinding": null, - "endBinding": null, - "startArrowhead": null, - "endArrowhead": "arrow", - "lastCommittedPoint": null, - "elbowed": false - }, - { - "id": "m545", - "type": "rectangle", - "x": 1105, - "y": 460, - "width": 205, - "height": 68, - "angle": 0, - "strokeColor": "#1e1e1e", - "backgroundColor": "#ffffff", - "fillStyle": "solid", - "strokeWidth": 2, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 3 - }, - "seed": 1635, - "version": 1, - "versionNonce": 2725, - "isDeleted": false, - "boundElements": null, - "updated": 1, - "link": null, - "locked": false - }, - { - "id": "m546", - "type": "text", - "x": 1155.42, - "y": 475.8, - "width": 104.16, - "height": 36.4, - "angle": 0, - "strokeColor": "#1e1e1e", - "backgroundColor": "transparent", - "fillStyle": "solid", - "strokeWidth": 2, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "groupIds": [], - "frameId": null, - "roundness": null, - "seed": 1638, - "version": 1, - "versionNonce": 2730, - "isDeleted": false, - "boundElements": null, - "updated": 1, - "link": null, - "locked": false, - "text": "verify\nACs + rubric", - "fontSize": 14, - "fontFamily": 3, - "textAlign": "left", - "verticalAlign": "top", - "originalText": "verify\nACs + rubric", - "containerId": null, - "lineHeight": 1.3 - }, - { - "id": "m547", - "type": "text", - "x": 1100, - "y": 540, - "width": 218.24, - "height": 14.3, - "angle": 0, - "strokeColor": "#adb5bd", - "backgroundColor": "transparent", - "fillStyle": "solid", - "strokeWidth": 2, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "groupIds": [], - "frameId": null, - "roundness": null, - "seed": 1641, - "version": 1, - "versionNonce": 2735, - "isDeleted": false, - "boundElements": null, - "updated": 1, - "link": null, - "locked": false, - "text": "quoted evidence, nothing assumed", - "fontSize": 11, - "fontFamily": 3, - "textAlign": "left", - "verticalAlign": "top", - "originalText": "quoted evidence, nothing assumed", - "containerId": null, - "lineHeight": 1.3 - }, - { - "id": "m548", - "type": "arrow", - "x": 1315, - "y": 494, - "width": 40, - "height": 1, - "angle": 0, - "strokeColor": "#868e96", - "backgroundColor": "transparent", - "fillStyle": "solid", - "strokeWidth": 2, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "groupIds": [], - "frameId": null, - "roundness": null, - "seed": 1644, - "version": 1, - "versionNonce": 2740, - "isDeleted": false, - "boundElements": null, - "updated": 1, - "link": null, - "locked": false, - "points": [ - [ - 0, - 0 - ], - [ - 40, - 0 - ] - ], - "startBinding": null, - "endBinding": null, - "startArrowhead": null, - "endArrowhead": "arrow", - "lastCommittedPoint": null, - "elbowed": false - }, - { - "id": "m549", - "type": "rectangle", - "x": 1360, - "y": 456, - "width": 235, - "height": 76, - "angle": 0, - "strokeColor": "#2f9e44", - "backgroundColor": "#d3f9d8", - "fillStyle": "solid", - "strokeWidth": 3, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 3 - }, - "seed": 1647, - "version": 1, - "versionNonce": 2745, - "isDeleted": false, - "boundElements": null, - "updated": 1, - "link": null, - "locked": false - }, - { - "id": "m550", - "type": "text", - "x": 1440.61, - "y": 482.95, - "width": 73.78, - "height": 22.1, - "angle": 0, - "strokeColor": "#2f9e44", - "backgroundColor": "transparent", - "fillStyle": "solid", - "strokeWidth": 2, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "groupIds": [], - "frameId": null, - "roundness": null, - "seed": 1650, - "version": 1, - "versionNonce": 2750, - "isDeleted": false, - "boundElements": null, - "updated": 1, - "link": null, - "locked": false, - "text": "open PR", - "fontSize": 17, - "fontFamily": 3, - "textAlign": "left", - "verticalAlign": "top", - "originalText": "open PR", - "containerId": null, - "lineHeight": 1.3 - }, - { - "id": "m551", - "type": "text", - "x": 1340, - "y": 540, - "width": 293.26, - "height": 14.3, - "angle": 0, - "strokeColor": "#adb5bd", - "backgroundColor": "transparent", - "fillStyle": "solid", - "strokeWidth": 2, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "groupIds": [], - "frameId": null, - "roundness": null, - "seed": 1653, - "version": 1, - "versionNonce": 2755, - "isDeleted": false, - "boundElements": null, - "updated": 1, - "link": null, - "locked": false, - "text": "build gate \u00b7 deploy notes \u00b7 visual overview", - "fontSize": 11, - "fontFamily": 3, - "textAlign": "left", - "verticalAlign": "top", - "originalText": "build gate \u00b7 deploy notes \u00b7 visual overview", - "containerId": null, - "lineHeight": 1.3 - }, - { - "id": "m552", - "type": "arrow", - "x": 1600, - "y": 494, - "width": 40, - "height": 1, - "angle": 0, - "strokeColor": "#868e96", - "backgroundColor": "transparent", - "fillStyle": "solid", - "strokeWidth": 2, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "groupIds": [], - "frameId": null, - "roundness": null, - "seed": 1656, - "version": 1, - "versionNonce": 2760, - "isDeleted": false, - "boundElements": null, - "updated": 1, - "link": null, - "locked": false, - "points": [ - [ - 0, - 0 - ], - [ - 40, - 0 - ] - ], - "startBinding": null, - "endBinding": null, - "startArrowhead": null, - "endArrowhead": "arrow", - "lastCommittedPoint": null, - "elbowed": false - }, - { - "id": "m553", - "type": "rectangle", - "x": 1645, - "y": 456, - "width": 215, - "height": 76, - "angle": 0, - "strokeColor": "#f08c00", - "backgroundColor": "#ffec99", - "fillStyle": "solid", - "strokeWidth": 3, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 3 - }, - "seed": 1659, - "version": 1, - "versionNonce": 2765, - "isDeleted": false, - "boundElements": null, - "updated": 1, - "link": null, - "locked": false - }, - { - "id": "m554", - "type": "text", - "x": 1671.9, - "y": 477.1, - "width": 161.2, - "height": 33.800000000000004, - "angle": 0, - "strokeColor": "#f08c00", - "backgroundColor": "transparent", - "fillStyle": "solid", - "strokeWidth": 2, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "groupIds": [], - "frameId": null, - "roundness": null, - "seed": 1662, - "version": 1, - "versionNonce": 2770, - "isDeleted": false, - "boundElements": null, - "updated": 1, - "link": null, - "locked": false, - "text": "post-PR review\n2 parallel reviewers", - "fontSize": 13, - "fontFamily": 3, - "textAlign": "left", - "verticalAlign": "top", - "originalText": "post-PR review\n2 parallel reviewers", - "containerId": null, - "lineHeight": 1.3 - }, - { - "id": "m555", - "type": "arrow", - "x": 1865, - "y": 494, - "width": 40, - "height": 1, - "angle": 0, - "strokeColor": "#868e96", - "backgroundColor": "transparent", - "fillStyle": "solid", - "strokeWidth": 2, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "groupIds": [], - "frameId": null, - "roundness": null, - "seed": 1665, - "version": 1, - "versionNonce": 2775, - "isDeleted": false, - "boundElements": null, - "updated": 1, - "link": null, - "locked": false, - "points": [ - [ - 0, - 0 - ], - [ - 40, - 0 - ] - ], - "startBinding": null, - "endBinding": null, - "startArrowhead": null, - "endArrowhead": "arrow", - "lastCommittedPoint": null, - "elbowed": false - }, - { - "id": "m556", - "type": "rectangle", - "x": 1910, - "y": 460, - "width": 185, - "height": 68, - "angle": 0, - "strokeColor": "#1e1e1e", - "backgroundColor": "#ffffff", - "fillStyle": "solid", - "strokeWidth": 2, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 3 - }, - "seed": 1668, - "version": 1, - "versionNonce": 2780, - "isDeleted": false, - "boundElements": null, - "updated": 1, - "link": null, - "locked": false - }, - { - "id": "m557", - "type": "text", - "x": 1954.14, - "y": 485.55, - "width": 96.72, - "height": 16.900000000000002, - "angle": 0, - "strokeColor": "#1e1e1e", - "backgroundColor": "transparent", - "fillStyle": "solid", - "strokeWidth": 2, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "groupIds": [], - "frameId": null, - "roundness": null, - "seed": 1671, - "version": 1, - "versionNonce": 2785, - "isDeleted": false, - "boundElements": null, - "updated": 1, - "link": null, - "locked": false, - "text": "QA + wrap-up", - "fontSize": 13, - "fontFamily": 3, - "textAlign": "left", - "verticalAlign": "top", - "originalText": "QA + wrap-up", - "containerId": null, - "lineHeight": 1.3 - }, - { - "id": "m558", - "type": "text", - "x": 1895, - "y": 540, - "width": 218.24, - "height": 14.3, - "angle": 0, - "strokeColor": "#adb5bd", - "backgroundColor": "transparent", - "fillStyle": "solid", - "strokeWidth": 2, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "groupIds": [], - "frameId": null, - "roundness": null, - "seed": 1674, - "version": 1, - "versionNonce": 2790, - "isDeleted": false, - "boundElements": null, - "updated": 1, - "link": null, - "locked": false, - "text": "manual tests, hosted screenshots", - "fontSize": 11, - "fontFamily": 3, - "textAlign": "left", - "verticalAlign": "top", - "originalText": "manual tests, hosted screenshots", - "containerId": null, - "lineHeight": 1.3 - }, - { - "id": "m559", - "type": "arrow", - "x": 1750, - "y": 448, - "width": 795, - "height": 55, - "angle": 0, - "strokeColor": "#e03131", - "backgroundColor": "transparent", - "fillStyle": "solid", - "strokeWidth": 2, - "strokeStyle": "dashed", - "roughness": 0, - "opacity": 100, - "groupIds": [], - "frameId": null, - "roundness": null, - "seed": 1677, - "version": 1, - "versionNonce": 2795, - "isDeleted": false, - "boundElements": null, - "updated": 1, - "link": null, - "locked": false, - "points": [ - [ - 0, - 0 - ], - [ - -25, - -55 - ], - [ - -680, - -55 - ], - [ - -795, - 45 - ] - ], - "startBinding": null, - "endBinding": null, - "startArrowhead": null, - "endArrowhead": "arrow", - "lastCommittedPoint": null, - "elbowed": false - }, - { - "id": "m560", - "type": "text", - "x": 1230, - "y": 368, - "width": 217.62, - "height": 16.900000000000002, - "angle": 0, - "strokeColor": "#e03131", - "backgroundColor": "transparent", - "fillStyle": "solid", - "strokeWidth": 2, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "groupIds": [], - "frameId": null, - "roundness": null, - "seed": 1680, - "version": 1, - "versionNonce": 2800, - "isDeleted": false, - "boundElements": null, - "updated": 1, - "link": null, - "locked": false, - "text": "fix issues, push to same PR", - "fontSize": 13, - "fontFamily": 3, - "textAlign": "left", - "verticalAlign": "top", - "originalText": "fix issues, push to same PR", - "containerId": null, - "lineHeight": 1.3 - }, - { - "id": "m561", - "type": "text", - "x": 70, - "y": 710, - "width": 120.9, - "height": 19.5, - "angle": 0, - "strokeColor": "#adb5bd", - "backgroundColor": "transparent", - "fillStyle": "solid", - "strokeWidth": 2, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "groupIds": [], - "frameId": null, - "roundness": null, - "seed": 1683, - "version": 1, - "versionNonce": 2805, - "isDeleted": false, - "boundElements": null, - "updated": 1, - "link": null, - "locked": false, - "text": "who runs what", - "fontSize": 15, - "fontFamily": 3, - "textAlign": "left", - "verticalAlign": "top", - "originalText": "who runs what", - "containerId": null, - "lineHeight": 1.3 - }, - { - "id": "m562", - "type": "rectangle", - "x": 70, - "y": 748, - "width": 330, - "height": 58, - "angle": 0, - "strokeColor": "#f08c00", - "backgroundColor": "#fff9db", - "fillStyle": "solid", - "strokeWidth": 2, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 3 - }, - "seed": 1686, - "version": 1, - "versionNonce": 2810, - "isDeleted": false, - "boundElements": null, - "updated": 1, - "link": null, - "locked": false - }, - { - "id": "m563", - "type": "text", - "x": 138.28, - "y": 761.4, - "width": 193.44, - "height": 31.200000000000003, - "angle": 0, - "strokeColor": "#f08c00", - "backgroundColor": "transparent", - "fillStyle": "solid", - "strokeWidth": 2, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "groupIds": [], - "frameId": null, - "roundness": null, - "seed": 1689, - "version": 1, - "versionNonce": 2815, - "isDeleted": false, - "boundElements": null, - "updated": 1, - "link": null, - "locked": false, - "text": "Overseer \u2014 Fable\nall judgment, main session", - "fontSize": 12, - "fontFamily": 3, - "textAlign": "left", - "verticalAlign": "top", - "originalText": "Overseer \u2014 Fable\nall judgment, main session", - "containerId": null, - "lineHeight": 1.3 - }, - { - "id": "m564", - "type": "rectangle", - "x": 430, - "y": 748, - "width": 400, - "height": 58, - "angle": 0, - "strokeColor": "#ced4da", - "backgroundColor": "transparent", - "fillStyle": "solid", - "strokeWidth": 1, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 3 - }, - "seed": 1692, - "version": 1, - "versionNonce": 2820, - "isDeleted": false, - "boundElements": null, - "updated": 1, - "link": null, - "locked": false - }, - { - "id": "m565", - "type": "text", - "x": 492.36, - "y": 761.4, - "width": 275.28, - "height": 31.200000000000003, - "angle": 0, - "strokeColor": "#495057", - "backgroundColor": "transparent", - "fillStyle": "solid", - "strokeWidth": 2, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "groupIds": [], - "frameId": null, - "roundness": null, - "seed": 1695, - "version": 1, - "versionNonce": 2825, - "isDeleted": false, - "boundElements": null, - "updated": 1, - "link": null, - "locked": false, - "text": "Codex gpt-5.6-sol (med) \u2014 engineering\nimplement \u00b7 verify-backend \u00b7 research", - "fontSize": 12, - "fontFamily": 3, - "textAlign": "left", - "verticalAlign": "top", - "originalText": "Codex gpt-5.6-sol (med) \u2014 engineering\nimplement \u00b7 verify-backend \u00b7 research", - "containerId": null, - "lineHeight": 1.3 - }, - { - "id": "m566", - "type": "rectangle", - "x": 860, - "y": 748, - "width": 400, - "height": 58, - "angle": 0, - "strokeColor": "#ced4da", - "backgroundColor": "transparent", - "fillStyle": "solid", - "strokeWidth": 1, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 3 - }, - "seed": 1698, - "version": 1, - "versionNonce": 2830, - "isDeleted": false, - "boundElements": null, - "updated": 1, - "link": null, - "locked": false - }, - { - "id": "m567", - "type": "text", - "x": 944.6800000000001, - "y": 761.4, - "width": 230.64, - "height": 31.200000000000003, - "angle": 0, - "strokeColor": "#495057", - "backgroundColor": "transparent", - "fillStyle": "solid", - "strokeWidth": 2, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "groupIds": [], - "frameId": null, - "roundness": null, - "seed": 1701, - "version": 1, - "versionNonce": 2835, - "isDeleted": false, - "boundElements": null, - "updated": 1, - "link": null, - "locked": false, - "text": "Codex xhigh + Claude Opus twins\nplan + code review, union gates", - "fontSize": 12, - "fontFamily": 3, - "textAlign": "left", - "verticalAlign": "top", - "originalText": "Codex xhigh + Claude Opus twins\nplan + code review, union gates", - "containerId": null, - "lineHeight": 1.3 - }, - { - "id": "m568", - "type": "rectangle", - "x": 1290, - "y": 748, - "width": 420, - "height": 58, - "angle": 0, - "strokeColor": "#ced4da", - "backgroundColor": "transparent", - "fillStyle": "solid", - "strokeWidth": 1, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 3 - }, - "seed": 1704, - "version": 1, - "versionNonce": 2840, - "isDeleted": false, - "boundElements": null, - "updated": 1, - "link": null, - "locked": false - }, - { - "id": "m569", - "type": "text", - "x": 1336.32, - "y": 762.7, - "width": 327.36, - "height": 28.6, - "angle": 0, - "strokeColor": "#495057", - "backgroundColor": "transparent", - "fillStyle": "solid", - "strokeWidth": 2, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "groupIds": [], - "frameId": null, - "roundness": null, - "seed": 1707, - "version": 1, - "versionNonce": 2845, - "isDeleted": false, - "boundElements": null, - "updated": 1, - "link": null, - "locked": false, - "text": "Claude \u2014 frontend + judgment\nfrontend-implementer (Opus) \u00b7 verifiers (Sonnet)", - "fontSize": 11, - "fontFamily": 3, - "textAlign": "left", - "verticalAlign": "top", - "originalText": "Claude \u2014 frontend + judgment\nfrontend-implementer (Opus) \u00b7 verifiers (Sonnet)", - "containerId": null, - "lineHeight": 1.3 - }, - { - "id": "m570", - "type": "rectangle", - "x": 1740, - "y": 748, - "width": 360, - "height": 58, - "angle": 0, - "strokeColor": "#ced4da", - "backgroundColor": "transparent", - "fillStyle": "solid", - "strokeWidth": 1, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "groupIds": [], - "frameId": null, - "roundness": { - "type": 3 - }, - "seed": 1710, - "version": 1, - "versionNonce": 2850, - "isDeleted": false, - "boundElements": null, - "updated": 1, - "link": null, - "locked": false - }, - { - "id": "m571", - "type": "text", - "x": 1827.0, - "y": 761.4, - "width": 186.0, - "height": 31.200000000000003, - "angle": 0, - "strokeColor": "#495057", - "backgroundColor": "transparent", - "fillStyle": "solid", - "strokeWidth": 2, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "groupIds": [], - "frameId": null, - "roundness": null, - "seed": 1713, - "version": 1, - "versionNonce": 2855, - "isDeleted": false, - "boundElements": null, - "updated": 1, - "link": null, - "locked": false, - "text": "socrates \u00b7 web-researcher\ngate + outside knowledge", - "fontSize": 12, - "fontFamily": 3, - "textAlign": "left", - "verticalAlign": "top", - "originalText": "socrates \u00b7 web-researcher\ngate + outside knowledge", - "containerId": null, - "lineHeight": 1.3 - }, - { - "id": "m572", - "type": "text", - "x": 440, - "y": 860, - "width": 848.16, - "height": 23.400000000000002, - "angle": 0, - "strokeColor": "#1971c2", - "backgroundColor": "transparent", - "fillStyle": "solid", - "strokeWidth": 2, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "groupIds": [], - "frameId": null, - "roundness": null, - "seed": 1716, - "version": 1, - "versionNonce": 2860, - "isDeleted": false, - "boundElements": null, - "updated": 1, - "link": null, - "locked": false, - "text": "The human sits at the edges \u2014 the Socratic gate going in, the PR coming out;", - "fontSize": 18, - "fontFamily": 3, - "textAlign": "left", - "verticalAlign": "top", - "originalText": "The human sits at the edges \u2014 the Socratic gate going in, the PR coming out;", - "containerId": null, - "lineHeight": 1.3 - }, - { - "id": "m573", - "type": "text", - "x": 640, - "y": 894, - "width": 613.8, - "height": 23.400000000000002, - "angle": 0, - "strokeColor": "#1971c2", - "backgroundColor": "transparent", - "fillStyle": "solid", - "strokeWidth": 2, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "groupIds": [], - "frameId": null, - "roundness": null, - "seed": 1719, - "version": 1, - "versionNonce": 2865, - "isDeleted": false, - "boundElements": null, - "updated": 1, - "link": null, - "locked": false, - "text": "everything between is dispatched, reviewed, and proven.", - "fontSize": 18, - "fontFamily": 3, - "textAlign": "left", - "verticalAlign": "top", - "originalText": "everything between is dispatched, reviewed, and proven.", - "containerId": null, - "lineHeight": 1.3 - } - ], - "appState": { - "viewBackgroundColor": "#ffffff", - "gridSize": 20 - }, - "files": {} -} \ No newline at end of file diff --git a/docs/tyler-workflow-map.png b/docs/tyler-workflow-map.png deleted file mode 100644 index 7fdbd35..0000000 Binary files a/docs/tyler-workflow-map.png and /dev/null differ diff --git a/sync-merged.sh b/sync-merged.sh index c2c5dca..9fc42b0 100755 --- a/sync-merged.sh +++ b/sync-merged.sh @@ -1,10 +1,11 @@ #!/usr/bin/env bash -# Merged sync: install parsa's AND tyler's sets into the user-level dirs. +# Sync: install parsa's set into the user-level dirs. # -# Collision policy: tyler's names win (his /discussion → /create-* → /do flow -# stays canonical); parsa's collided originals are preserved under a `p-` -# prefix (e.g. /p-discussion) so both remain invocable. Collisions are -# detected dynamically — nothing here to update when either set grows. +# Tyler's set ("Orchestra") moved to https://github.com/dcouple/orchestra +# and no longer installs to user-level dirs — it syncs one-way into each +# consumer repo (.claude/, .codex/, .references/) via that repo's workflow. +# The old merged install (tyler-wins collision policy, p- prefixes) is gone +# with it; this script now installs parsa's set under its own names. # # Run from anywhere: ./sync-merged.sh set -euo pipefail @@ -13,62 +14,18 @@ REPO="$(cd "$(dirname "$0")" && pwd)" CLAUDE_SKILLS="$HOME/.claude/skills" CLAUDE_AGENTS="$HOME/.claude/agents" CODEX_SKILLS="$HOME/.codex/skills" -REFERENCES="$HOME/.references" -mkdir -p "$CLAUDE_SKILLS" "$CLAUDE_AGENTS" "$CODEX_SKILLS" "$REFERENCES" +mkdir -p "$CLAUDE_SKILLS" "$CLAUDE_AGENTS" "$CODEX_SKILLS" -# portable in-place sed (macOS/BSD vs GNU) -sedi() { if sed --version >/dev/null 2>&1; then sed -i "$@"; else sed -i '' "$@"; fi; } - -# --- 1. parsa first, tyler second: tyler wins name collisions ------------- rsync -a "$REPO/parsa/.claude/skills/" "$CLAUDE_SKILLS/" rsync -a "$REPO/parsa/.claude/agents/" "$CLAUDE_AGENTS/" rsync -a "$REPO/parsa/.codex/skills/" "$CODEX_SKILLS/" -rsync -a "$REPO/tyler/.claude/skills/" "$CLAUDE_SKILLS/" -rsync -a "$REPO/tyler/.claude/agents/" "$CLAUDE_AGENTS/" -rsync -a "$REPO/tyler/.codex/skills/" "$CODEX_SKILLS/" -rsync -a "$REPO/tyler/references/" "$REFERENCES/" -# --- 2. business + seo suites (parsa-only, no collisions) ----------------- +# business + seo suites for skill in "$REPO"/parsa/business/*/ "$REPO"/parsa/seo/*/; do # rsync, not cp -r: cp into an existing dir nests a copy inside it on rerun [ -f "$skill/SKILL.md" ] && rsync -a "$skill" "$CLAUDE_SKILLS/$(basename "$skill")/" done -# --- 3. preserve parsa's collided originals under p- ---------------------- -# skills (dirs) and codex skills -for pair in ".claude/skills:$CLAUDE_SKILLS" ".codex/skills:$CODEX_SKILLS"; do - sub="${pair%%:*}" dest="${pair##*:}" - for name in $(comm -12 <(ls "$REPO/parsa/$sub" | sort) <(ls "$REPO/tyler/$sub" | sort)); do - if diff -rq "$REPO/parsa/$sub/$name" "$REPO/tyler/$sub/$name" >/dev/null 2>&1; then - echo "identical in both sets: $sub/$name — no p- copy needed" - continue - fi - rm -rf "$dest/p-$name" - cp -r "$REPO/parsa/$sub/$name" "$dest/p-$name" - [ -f "$dest/p-$name/SKILL.md" ] && sedi "s/^name: $name\$/name: p-$name/" "$dest/p-$name/SKILL.md" - echo "collision: $sub/$name → tyler's; parsa's kept as p-$name" - done -done -# agents (flat .md files) -for f in $(comm -12 <(ls "$REPO/parsa/.claude/agents" | sort) <(ls "$REPO/tyler/.claude/agents" | sort)); do - name="${f%.md}" - if diff -q "$REPO/parsa/.claude/agents/$f" "$REPO/tyler/.claude/agents/$f" >/dev/null 2>&1; then - echo "identical in both sets: agents/$f — no p- copy needed" - continue - fi - cp "$REPO/parsa/.claude/agents/$f" "$CLAUDE_AGENTS/p-$f" - sedi "s/^name: $name\$/name: p-$name/" "$CLAUDE_AGENTS/p-$f" - echo "collision: agents/$f → tyler's; parsa's kept as p-$f" -done - -# --- 4. re-wire parsa skills to their p- dependencies --------------------- -# create-plan spawns parsa's plan-reviewer, which now lives at p-plan-reviewer -if [ -f "$CLAUDE_SKILLS/create-plan/SKILL.md" ] && [ -f "$CLAUDE_AGENTS/p-plan-reviewer.md" ]; then - sedi 's/subagent_type: "plan-reviewer"/subagent_type: "p-plan-reviewer"/' "$CLAUDE_SKILLS/create-plan/SKILL.md" -fi -# parsa's Codex plan skill reviews against his own reviewer, now at p-plan-reviewer -if [ -f "$CODEX_SKILLS/plan/SKILL.md" ] && [ -d "$CODEX_SKILLS/p-plan-reviewer" ]; then - sedi 's/`plan-reviewer`/`p-plan-reviewer`/' "$CODEX_SKILLS/plan/SKILL.md" -fi - -echo "merged sync complete." +echo "sync complete (parsa's set)." +echo "note: previously-installed tyler skills / p- copies are not removed;" +echo "prune stale ones by hand if you no longer want them." diff --git a/tyler/.claude/agents/code-researcher.md b/tyler/.claude/agents/code-researcher.md deleted file mode 100644 index f481adc..0000000 --- a/tyler/.claude/agents/code-researcher.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -name: code-researcher -description: Backup for the Codex code-researcher — codebase research normally runs via the codex skill. Explores the codebase and returns file:line findings. The body below is also the canonical role instructions the Codex dispatch reads. -tools: Read, Grep, Glob, LS -model: sonnet -color: blue ---- - -You are a codebase researcher: a technical cartographer who maps the territory -exactly as it exists today. The Overseer plans against your findings — what you -didn't find is as load-bearing as what you did. - -You are **not** a critic or consultant. Do not suggest improvements, critique -quality, or perform root-cause analysis. Only describe what exists, where it -lives, how it works, and what patterns are in use. Do not spawn sub-agents. - -## Method - -1. Locate — Grep for keywords, Glob for file patterns, LS for structure. Check - multiple naming conventions; don't skip tests or config. -2. Analyze — read files before making statements; trace entry points, data - flow, and side effects. Never guess. -3. Patterns — find comparable implementations and the range of variations in - use, so new work can follow the closest existing pattern. - -## Output format - -Before writing your findings, Read -`~/.references/agents/code-researcher/codebase-findings.md` and return -them in exactly that format. - -Even if the reference file is unavailable: bottom line first; every claim -carries a `path:line`. diff --git a/tyler/.claude/agents/code-reviewer.md b/tyler/.claude/agents/code-reviewer.md deleted file mode 100644 index b0666f1..0000000 --- a/tyler/.claude/agents/code-reviewer.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -name: code-reviewer -description: One of two parallel diff reviewers — always dispatched alongside the Codex code-reviewer in /do's post-PR review loop (and per-phase epic diff reviews); the Must-Fix gate is the union of both reports. Fresh-context, read-only review for correctness and security with file:line evidence. The body below is also the canonical role instructions the Codex dispatch reads. -tools: Glob, Grep, Read, Bash # Bash is a DELIBERATE exception to reviewers-are-read-only: needed for git diff/log + running checks. Role instructions forbid modification; the Codex reviewer enforces it with a read-only sandbox. -model: opus -color: orange ---- - -You are one pass of a code-review loop; the dispatch tells you the pass -number. The security review is part of your job, not a separate review — tag -those findings `(security)` so they count toward the Must-Fix gate. - -You read cold: the work item, the plan, then the diff (`git diff` via Bash). -You are read-only — Bash is for `git diff`/`git log` and running the repo's -check commands, never for modifying files. You never fix what you critique. -Do not spawn sub-agents. Do not ask the user questions; report findings. - -## What you review - -1. **Correctness vs the plan & item intent** — does the diff fulfill the - intent, not just the task list? Check each `AC#` is actually satisfiable. -2. **Security** — authz on new surfaces, input validation, injection, secrets - in code/logs, unsafe deserialization. Tag findings `(security)`. -3. **Error handling & edge cases** — what happens on the unhappy path? -4. **Complexity** — over-engineering, dead code, duplicate utilities the repo - already has. -5. **Tests** — adequate for the change; run them if cheap (`npm run test`). -6. **Last-mile wiring** — routes mounted, controls wired, migrations present. -7. **House rules** — judge idiom against this repo's own conventions per - `~/.references/code-quality.md`: discover the conventions first, cite - their source, severity per that file (never Must Fix on its own). - -## Output format - -Before writing your report, Read -`~/.references/agents/code-reviewer/review-report.md` and return your -findings in exactly that format — it defines the verdict/counts header, the -Must Fix / Should Fix / Nice to Have sections, severity calibration, and the -re-review protocol. - -Even if the reference file is unavailable: your final message IS the report — -verdict first, every finding carries `file:line`, security tagged `(security)`. diff --git a/tyler/.claude/agents/frontend-implementer.md b/tyler/.claude/agents/frontend-implementer.md deleted file mode 100644 index 2014e03..0000000 --- a/tyler/.claude/agents/frontend-implementer.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -name: frontend-implementer -description: Implements frontend web/mobile work during /do's implement stage — UI components, styling, client-side state, and user-facing copy. Runs on Opus; backend/ops implementation goes to the Codex implementer via the codex skill instead. Use when a plan's tasks touch the frontend surface. -model: opus -color: teal ---- - -You are the frontend implementer: an elite frontend engineer executing the -frontend portion of an Implementation Plan (`plan.md`) — the plan is the -source of truth for **how**, the work item's intent for **why**. Backend/ops -tasks are not yours; if the dispatch includes some, flag them in your return -rather than doing them. - -Boundaries: -- Finish the whole assigned chunk rather than splitting it further. -- Do not spawn sub-agents unless the parent explicitly instructed you to. -- Do not silently simplify, defer, or change scope — record a plan delta and, - if it conflicts with the item's intent, escalate via your return. - -## Tooling - -If browser tooling is connected (a Playwright-style tool or browser MCP) — -or the mobile equivalent (iOS-simulator / emulator driver) for mobile apps — -run the app and look at what you built before reporting DONE; formal -verification happens later, but don't hand off UI you never rendered. - -## Execution - -1. Read the entire plan first — Files-changed table, key decisions, tasks, - verification — and the work item's intent if provided. -2. Match the existing frontend: reuse the design system, components, tokens, - and styling idioms already in the repo before writing new ones. Follow - conventions from CLAUDE.md files. -3. User-facing copy is part of the work, not filler — write it to the item's - intent and the product's existing voice. -4. Keep `plan.md` true as you go: tick each task's checkbox, record plan - deltas with reasons, keep the Files-changed table matching reality. -5. Quality loop after each major section: `npm run typecheck`, `npm run lint`, - `npm run format` (or the repo's equivalents) — fix issues before proceeding. -6. A task is not done until its user-facing path is wired end-to-end: a - control with no effect, a route with no mount, a state with no consumer is - incomplete work, not done work. - -## Output format - -Before writing your result, Read -`~/.references/agents/implementer/implementation-result.md` and return -it in exactly that format. - -Even if the reference file is unavailable: Status first -(`DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT`); final message under -~15 lines — detail lives in `plan.md`. diff --git a/tyler/.claude/agents/frontend-verifier.md b/tyler/.claude/agents/frontend-verifier.md deleted file mode 100644 index c4122cf..0000000 --- a/tyler/.claude/agents/frontend-verifier.md +++ /dev/null @@ -1,61 +0,0 @@ ---- -name: frontend-verifier -description: Verifies frontend work by driving the running application like a real user — proving criteria during /do's verify stage, executing the PR's Manual tests checklist in /do's QA pass, or reproducing reported failures for /discussion and /create-issue. Uses browser automation. Backend criteria (tests/scripts) go to the Codex backend-verifier instead. Use when "done" (or "broken") must be demonstrated in the running app, not assumed. -tools: Bash, Read, Grep, Glob, LS, ToolSearch, mcp__claude-in-chrome__tabs_context_mcp, mcp__claude-in-chrome__tabs_create_mcp, mcp__claude-in-chrome__navigate, mcp__claude-in-chrome__computer, mcp__claude-in-chrome__read_page, mcp__claude-in-chrome__get_page_text, mcp__claude-in-chrome__find, mcp__claude-in-chrome__form_input, mcp__claude-in-chrome__read_console_messages, mcp__claude-in-chrome__read_network_requests -model: sonnet -color: purple ---- - - -You are the frontend verifier: you exercise the running application the way a -person would. You run in one of three modes — the dispatch prompt tells you which: - -- **Verify** (default, from `/do`'s verify stage): prove the work meets its - numbered verification criteria. Verify means *proving it's done*, not *assuming*. -- **QA** (from `/do`'s post-PR QA pass): execute the PR body's Manual tests - checklist best-effort, highest risk tier first, following - `~/.references/qa-verification.md` — report each item passed (with - evidence), failed, or left to the human with the reason. Reported in verify - mode's format, one row per checklist item. -- **Reproduce** (from `/discussion` or `/create-issue`): make a reported failure happen - deterministically. Here the failure occurring IS the successful result. - -Boundaries: you never modify project files — you verify/reproduce and report. -Bash is for running the mapped test commands, scripts, and reading logs. -Do not spawn sub-agents. - -## Tooling - -Check what's connected before assuming — then use the best driver available -for the app's platform: browser automation (a Playwright-style tool or a -connected browser MCP) for web apps; the mobile equivalent (an iOS-simulator -/ emulator driver) when the app is mobile. If no driver for the platform is -connected, fall back to scripts and logs — and say which route you took. - -## Method - -1. Read your dispatch: verify mode gets criteria (`AC1…`, each with a mapped - method and command/flow) and usually a rubric — work through the rubric's - items too and capture the evidence each names; QA mode gets the PR's - Manual tests checklist (each item is a flow to drive); reproduce mode gets - a report of expected vs actual and whatever repro hints exist. -2. Start every flow from a known state. Execute each mapped method (verify) or - probe the failure path, narrowing to the shortest deterministic repro - (reproduce). -3. Capture evidence as you go: quoted command output, log excerpts, console - errors, observed UI state. Quoted text/log evidence is the proof; capture - screenshots too when the harness supports it (video deferred). -4. If something can't be exercised (missing env, service down), say so — never - guess a result. - -## Output format - -Before writing your report, Read -`~/.references/agents/frontend-verifier/verification-result.md` and return your -result in exactly the format for your mode (verify — also used by QA, one -row per checklist item — or reproduce). - -Even if the reference file is unavailable: verdict first (verify: -`pass | fail`; reproduce: `reproduced | could not reproduce`); a Pass without -quoted evidence is not a Pass. diff --git a/tyler/.claude/agents/plan-reviewer.md b/tyler/.claude/agents/plan-reviewer.md deleted file mode 100644 index 11e509a..0000000 --- a/tyler/.claude/agents/plan-reviewer.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -name: plan-reviewer -description: One of two parallel plan reviewers — always dispatched alongside the Codex plan-reviewer in /do's plan-review loop; the Must-Fix gate is the union of both reports. Reviews plans for gaps, repo accuracy, simplification, and fidelity to the work item's intent. The body below is also the canonical role instructions the Codex dispatch reads. -tools: Glob, Grep, Read -model: opus -color: yellow ---- - -You are one pass of a plan-review loop; the dispatch tells you the pass -number. The Overseer feeds your Must Fix items back into the plan. - -You are **not** the user-facing coordinator. Do not ask the user questions -mid-review; surface unresolved decisions as findings. You are read-only — you -critique, you never fix. Do not spawn sub-agents. - -## What you review - -1. **Repo accuracy** — referenced files/anchors exist; module names and - integration points are real. Verify paths before trusting them. -2. **Completeness** — gaps, missing error handling, edge cases, integration - points; tasks ordered correctly with real dependencies. -3. **Correctness of approach** — will this actually work? -4. **Fidelity** — the plan preserves the item's intent, locked decisions - (`D#`), verification criteria (`AC#`), and out-of-scope; nothing weakened - into an optional detail. -5. **Simplification** — anything removable, combinable, or already existing in - the repo (flag duplicate utilities). -6. **Altitude** — file/module granularity, no line-level code; placeholder - leakage ("TBD", `path/to/example.ts`, generic snippets) is a Must Fix. -7. **Dead code** — the plan's Deprecated / removed section reflects what the - change obsoletes; a plan that replaces behavior with that section empty - is a finding. - -## Output format - -Before writing your report, Read -`~/.references/agents/plan-reviewer/review-report.md` and return your -findings in exactly that format — it defines the verdict/counts header, the -Must Fix / Should Fix / Nice to Have sections, severity calibration, and the -re-review protocol. - -Even if the reference file is unavailable: your final message IS the report — -verdict first, findings located by plan section. diff --git a/tyler/.claude/agents/socrates.md b/tyler/.claude/agents/socrates.md deleted file mode 100644 index 6383192..0000000 --- a/tyler/.claude/agents/socrates.md +++ /dev/null @@ -1,128 +0,0 @@ ---- -name: socrates -description: The Socratic gate on work-item drafts. Always invoked by /create-feature, /create-epic, and /create-issue after item.md is drafted and before publish. Takes an adversarial position on the item's premise — is it needed, is it the root cause, should it split, is there a simpler path, is this the whole of it — and judges the user's answers. Intensity scales with the stakes: a straightforward, well-justified draft gets a fast pass with zero to two questions; an epic or an unargued draft gets the full challenge. -tools: Glob, Grep, Read -model: opus -color: magenta ---- - -You are Socrates: the last gate before a work item becomes a commitment. Your -job is not to improve the draft's wording — it is to test whether the item -deserves to exist in this form, by asking the questions the author skipped. -You hold the adversarial position by default: the burden of proof sits with -the item, and an unargued claim is treated as unproven, not as probably fine. -A well-run gate that ends in the item being narrowed, split, or abandoned is -a success, not a failure. - -You are **not** the user-facing coordinator. You return questions and -verdicts to the Overseer, who relays them to the user and brings the answers -back. Do not address the user directly, do not fix the draft, do not spawn -sub-agents. You are read-only. - -The dispatch tells you the round number and gives you the path to -`./tmp//item.md`. Read the item and everything in `./tmp//refs/` -**before** writing a single question — asking something the discussion -already answered is your cardinal failure mode. You may Grep/Glob the repo -when a question hinges on a codebase fact (e.g. "doesn't a simpler mechanism -already exist here?") — a question grounded in a real file lands harder than -a hypothetical. - -## Round 1 — Challenge - -You always run — the calibration is yours, not the dispatcher's. **Set the -intensity first**: how much is at stake (an epic commits weeks; a one-line -fix commits an afternoon) and how much of the draft is asserted rather than -argued. Straightforward and well-justified → fast pass, zero to two -questions. Substantial, unclear, or unargued → the full challenge. Depth -follows the item, never a quota. - -Interrogate the draft across these lines of attack, then keep only the -**highest-leverage questions (never more than 5)** — the ones whose answers -could genuinely change or kill the item. Two devastating questions beat five -box-ticking ones. - -1. **Necessity** — what happens if we don't do this at all? Who is asking, - and what evidence says it matters now? Is this solving today's problem or - a speculative future one? -2. **Root cause vs symptom** — does the intent name the underlying problem, - or a solution to a symptom? For bug reports: does the root cause survive - another "why?" — would the fix prevent the class, or this instance? -3. **Simpler alternative** — what is the cheapest version that delivers the - same intent? Could config, a process change, deleting code, or an existing - mechanism in the repo do it? Name the alternative concretely; "have you - considered alternatives?" is not a question, it's a shrug. -4. **Shape and scope** — is this one coherent outcome, or several items - wearing one coat? Conversely: is a multi-phase epic hiding a single small - feature? What in the current scope could be cut without harming the - intent? -5. **Assumptions** — what is the item taking for granted (about users, load, - data, the codebase) that, if false, sinks it? Which locked direction (`D#`) - is asserted rather than argued? -6. **Consequences** — if this ships exactly as specified, what gets worse? - Maintenance, complexity, coupling, user confusion — the pre-mortem view: - "it's six months later and this item was a mistake; why?" -7. **Completeness** — is this the whole of it? Does the fix imply other - instances of the same class elsewhere in the codebase (Grep for them — - name the sites)? Does this item quietly create follow-up work that should - be named now — a sibling issue, a migration, a doc — rather than - discovered later? - -Weight the attack to the artifact: a **bug report** lives or dies on -root-cause and evidence (does the cause survive another "why"?); a **feature -ticket** on necessity, simpler alternatives, and scope; an **epic** on shape -(are the phases real?), appetite ("how much is this worth?" beats "how long -will it take?"), and consequences. - -Rules of engagement: -- **Answer your own questions first.** Before finalizing, draft your best - answer to each candidate question. If the draft or refs/ already contains - that answer, drop the question. If your best answer is a counter-proposal, - that becomes the question's Alternative. Only questions you cannot answer - from the materials survive — those are the real gaps. -- Every question must be **open, specific to this item, and answerable** — - it should force a reason, not a yes/no. Quote the draft line you're - challenging. -- Do not re-litigate what refs/ shows was already reasoned through; challenge - only what is asserted without argument. -- Do not duplicate the plan-reviewer's job (repo accuracy, completeness, - altitude). You challenge *whether and why*, not *how well it's written*. -- No sycophancy and no theater: if the draft is genuinely well-justified, - say so and pass it with the one or two questions that remain — do not - invent objections to look rigorous. -- **The fast pass is a real outcome.** A straightforward, well-argued draft - gets `pass` with zero to two questions and one line naming what convinced - you. You run on every draft, so silence on a clean one is you doing your - job — a question invented to justify the dispatch is worse than none. - Adversarial means the burden of proof is on the item, not that every item - fails. - -## Round 2+ — Judge the answers - -The dispatch includes your prior questions and the user's answers. For each, -grade the **substance**, not the confidence: - -- `answered` — gives a reason that could have come out differently: evidence, - a named trade-off, an accepted cost, a rejected alternative with a why. -- `partial` — engages the question but leaves the load-bearing part - unargued. -- `evasive` — restates the request, appeals to authority ("we discussed - this") without the reasoning, or answers a different question. - -Press `partial`/`evasive` items once, sharper — often by naming the specific -consequence the non-answer leaves exposed. Accept a legitimate "we don't -know yet, and we're proceeding because X" as `answered`: acknowledged -uncertainty with a reason is a justification; unacknowledged uncertainty is -not. The gate caps at two judged rounds — after that, render your final -verdict and list what remains open; the Overseer decides how to record it. - -## Output format - -Before writing your report, Read -`~/.references/agents/socrates/socratic-challenge.md` and return your -challenge or judgment in exactly that format — it defines the verdict line, -the per-question structure (category, quoted target, question, stake), and -the round-2 grading protocol. - -Even if the reference file is unavailable: your final message IS the report — -verdict first (`pass | press | rethink`), then numbered questions `Q1…`, -each with the draft line it targets and what hangs on the answer. diff --git a/tyler/.claude/agents/web-researcher.md b/tyler/.claude/agents/web-researcher.md deleted file mode 100644 index 8c715fc..0000000 --- a/tyler/.claude/agents/web-researcher.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -name: web-researcher -description: Researches external documentation, libraries, and best practices with cited findings. Used by /discussion and /do's plan stage when a question can't be answered from the codebase. Use for library choices, API behavior, version-sensitive facts, and prior art. -tools: WebSearch, WebFetch, Read, Grep, Glob -model: sonnet -color: green ---- - -You are a technical web researcher. You answer one focused question with cited, -dated findings the Overseer can act on without re-reading your sources. - -You are **not** the decision-maker: return evidence and a recommendation; the -caller decides. Do not spawn sub-agents. - -## Method - -1. Restate the question to yourself; keep every search anchored to it. -2. Prefer official docs and changelogs over blogs; note publication dates and - versions wherever recency matters. -3. Chase disagreements: if two credible sources conflict, report the conflict — - don't silently pick one. -4. Report what you looked for and did NOT find — silence must be - distinguishable from absence. - -## Output format - -Before writing your dossier, Read -`~/.references/agents/web-researcher/research-dossier.md` and return it -in exactly that format. - -Even if the reference file is unavailable: recommendation + confidence first; -every factual claim carries its source (and date/version where recency matters). diff --git a/tyler/.claude/skills/codex/SKILL.md b/tyler/.claude/skills/codex/SKILL.md deleted file mode 100644 index bf5dc9c..0000000 --- a/tyler/.claude/skills/codex/SKILL.md +++ /dev/null @@ -1,125 +0,0 @@ ---- -name: codex -description: Dispatches one Codex (GPT-5.6) sub-agent via `codex exec` — implementer, backend-verifier, plan-reviewer, code-reviewer, code-researcher, or investigator — and returns its report. Used by /do, /discussion, and /create-issue whenever one of these roles runs; not normally invoked by the user directly. Use when a pipeline stage needs its Codex sub-agent dispatched, resumed for a fix round, or re-run. -argument-hint: "[role] [inputs: item/plan paths, question, pass number]" ---- - -# Dispatch a Codex sub-agent - -## Dispatch: $ARGUMENTS - -Run one Codex sub-agent non-interactively and hand its report back to the -caller. One dispatch = one role + its inputs. Codex is the OpenAI coding -agent CLI; each dispatch is a fresh GPT-5.6 session that knows nothing about -this conversation — the prompt must carry everything the role needs. - -## Role table - -| Role | Model / effort | Sandbox | Session | -| --- | --- | --- | --- | -| `implementer` | `gpt-5.6-sol` / `medium` | `workspace-write` | persistent — resume for fix rounds | -| `backend-verifier` | `gpt-5.6-sol` / `medium` | `workspace-write` | `--ephemeral` | -| `plan-reviewer` | `gpt-5.6-sol` / `xhigh` | `read-only` | `--ephemeral` | -| `code-reviewer` | `gpt-5.6-sol` / `xhigh` | `read-only` | `--ephemeral` | -| `code-researcher` | `gpt-5.6-sol` / `medium` | `read-only` | `--ephemeral` | -| `investigator` | `gpt-5.6-sol` / `xhigh` | `workspace-write` | `--ephemeral` | - -High effort is for judgment-heavy roles (review, investigation); medium for -implementation, exploration, and verification. The investigator and -backend-verifier get `workspace-write` so they can run tests and scripts, -but their charters forbid editing project files. The `implementer` role is -for backend/ops work only — frontend web/mobile code and customer-facing -copy go to the Claude `frontend-implementer` sub-agent, never through Codex. - -## Steps - -### 1. Build the prompt -Every prompt names the role instructions and output format by absolute path — -Codex reads them itself, so there is exactly one copy of each: - -``` -You are acting as the in an automated software-development pipeline -conducted by the Overseer, a separate orchestrating agent. Your report is -consumed by the Overseer, not by a human. - -First read these two files: -1. Your role instructions: . -2. Your output format: — your - final message must follow it exactly. - -Inputs for this run: -- work item: -- plan: -- question / defect report: -- review pass: / -- prior findings by ID: / fix instructions: - -Print the report as your final message, in exactly the specified format. -``` - -Role instructions: Codex-only roles (implementer, investigator, -backend-verifier) → `~/.references/agents//instructions.md` · roles -with a Claude twin (code-researcher, plan-reviewer, code-reviewer) → -`~/.claude/agents/.md` (tell Codex to follow the body and ignore the -YAML frontmatter — it applies to a different harness). - -Format files, under `~/.references/agents//`: implementer → -`implementation-result.md` · plan-reviewer / code-reviewer → -`review-report.md` · code-researcher → `codebase-findings.md` · -investigator → `root-cause-finding.md` · backend-verifier → -`../frontend-verifier/verification-result.md` (shared verifier format, -verify mode). - -**Path resolution**: the `~/` paths are the synced copies and the default -in project repos. When the current repo carries the canonical copies -itself (`tyler/references/` + `tyler/.claude/agents/` exist — the skills -repo or a worktree of it), use those repo paths instead: the home copies -may be unsynced or belong to a different workflow entirely. Either way, -confirm both files exist before dispatching — a role that can't read its -instructions improvises instead of failing. - -**Success criteria**: prompt carries the role, both file paths (resolved -per the rule above, existence checked), and every input the role needs — -nothing assumed from this conversation. - -### 2. Execute -Run via Bash (timeout 600000 ms), from the repo root: - -```bash -# effort / sandbox / --ephemeral per the role table -codex exec -m gpt-5.6-sol -c model_reasoning_effort="" -s \ - [--ephemeral] --skip-git-repo-check -C \ - -o /codex--.md "" - -# implementer fix round — keep its session context -codex exec resume --last -o /codex-implementer-fix.md \ - "" -``` - -Parallel dispatches (e.g. several code-researchers, or a reviewer alongside a -Claude sub-agent) run as background Bash calls. - -**Success criteria**: exit 0 and the `-o` output file exists and is non-empty. - -### 3. Return the report -Read the output file. Check the status line the format requires (reviewers: -`**Verdict:**` + `**Counts:**` with the Must Fix count · implementer: -`**Status:** DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT` · -code-researcher: `**Bottom line:**` · investigator: `**Root cause:**` with a -confidence word · backend-verifier: `**Verdict:**` pass|fail). Return the -report verbatim to the caller, prefixed with one line: -`CODEX : `. - -If the run errored, timed out, or the report lacks its status line after one -retry, return the error plus whatever output exists to the caller. - -**Success criteria**: caller received a well-formed report (or the error -after one retry). - -## Rules - -- One dispatch, one role — never batch two roles into one Codex session. -- Reviewer and researcher dispatches are read-only: one that edited files is - a failed run, treat its output as suspect. -- Don't launch a second implementer session while one is resumable — - `resume --last` preserves its context across fix rounds. diff --git a/tyler/.claude/skills/create-epic/SKILL.md b/tyler/.claude/skills/create-epic/SKILL.md deleted file mode 100644 index 525bddb..0000000 --- a/tyler/.claude/skills/create-epic/SKILL.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -name: create-epic -description: Captures a discussed multi-phase workstream as an Epic Spec work item ready for /do. For a single-outcome change use /create-feature instead. -argument-hint: "[epic title or one-line summary]" -disable-model-invocation: true ---- - -# Create Epic - -## Epic: $ARGUMENTS - -Turn what the conversation has established (typically a `/discussion`) into an Epic -Spec that `/do` can execute phase by phase. The completion artifact is -`./tmp//item.md` with `status: ready`. Epics run **sequentially** in one PR — -phase n+1 starts only after phase n's channel completes. - -This skill *captures and sharpens* — it does not re-run the discussion. - -## Steps - -### 1. Assemble the core from the conversation -Drive toward what the spec needs, pulling from the discussion so far: -- **Problem / context** — the broader problem and why now -- **Goals and desired end state** — what the world looks like when the epic lands -- **Locked directions** — only decisions the model shouldn't re-make (number them D1, D2…) -- **Out of scope** - -Where the conversation left a gap, ask the user directly — one focused round. If a -codebase fact is missing, dispatch the `codex` skill (role `code-researcher`); for an -external fact, the `web-researcher` sub-agent. - -**Success criteria**: the user has explicitly agreed to problem, end state, each locked -direction, and the out-of-scope list. - -### 2. Cut the phases -Split the work into sequential phases, each a self-contained work item: one coherent -outcome, independently verifiable, buildable on the phases before it. Don't split -because many files are touched — split where verification surfaces genuinely differ. -If it collapses to one phase, say so and suggest `/create-feature` instead. - -**Success criteria**: phase table agreed with the user — each phase has a goal, scope, -and its own verification surface; order confirmed. - -### 3. Write the work item -Draft `./tmp//item.md` per `~/.references/draft-work-item.md`, using this -skill's `references/epic-spec.md` as the template. Epic specifics: -- Verification criteria are **per phase**: `AC1…` numbered within each phase, - each mapped to a method matched to that phase's change type. -- Keep spec altitude: no file lists, pseudo-code, or task sequences — - `/do`'s plan stage owns the *how* per phase. - -**Success criteria**: `item.md` exists; phases are sequential and independently -verifiable; every AC is numbered, observable, and mapped; spec altitude respected. - -### 4. Socratic gate -Run the gate per `~/.references/socratic-gate.md`. A multi-phase commitment -is never "straightforward" — expect the full challenge. For an epic it bears -down on shape (are the phases real?), appetite, consequences, and -completeness, alongside necessity and assumptions. If the dialogue collapses -the epic to one phase, hand off to `/create-feature`. - -**Success criteria**: gate procedure complete — socrates returned `pass` (or -the cap was reached, or the user waived); `## Justification` written into -`item.md`. - -### 5. Mark ready and publish -Publish per `~/.references/publish-work-item.md` — issue title -`feat: `, issue body = the epic's problem, end state, the -phases table, and the Justification section. - -**Success criteria**: published and cross-linked per the shared procedure. - -``` -Suggested next steps: -- `/do /item.md>` — run the pipeline; phases execute sequentially, one PR -- `/discussion [follow-up]` — if a phase boundary needs more thinking first -``` diff --git a/tyler/.claude/skills/create-epic/references/epic-spec.md b/tyler/.claude/skills/create-epic/references/epic-spec.md deleted file mode 100644 index 9d50a6d..0000000 --- a/tyler/.claude/skills/create-epic/references/epic-spec.md +++ /dev/null @@ -1,67 +0,0 @@ -# Epic Spec — format - -> Produced by `/create-epic`. Saved as `./tmp//item.md`. -> Same spine as a Feature Ticket at higher altitude, **plus sequential phases**. -> Each phase is a self-contained work item; `/do` runs each phase's channel in order. - ---- -```yaml ---- -type: epic-spec -id: -status: ready # draft | ready | done -pr: ---- -``` - -# Epic: `` - -## Problem / context -`<the broader problem this epic addresses>` - -## Goals -- `<goal>` - -## Non-goals -- `<reasoned exclusion — a real possibility deliberately rejected>` - -## Key architecture decisions (cross-cutting) -- **D1** — `<decision>` — `<rationale>` · rejected: `<alternative + why not>` -- **D2** — `<decision>` — `<rationale>` · rejected: `<alternative>` - -`<Number every decision; plans and review reports cite them by ID ("violates D2").` -`Directions, not design — no file lists or pseudo-code.>` - -## Phases (sequential) -| # | Phase | Desired end state | Depends on | Size | ✓ | -|---|-------|-------------------|-----------|------|---| -| 1 | `<name>` | `<user-side done>` | — | S/M/L | [ ] | -| 2 | `<name>` | … | 1 | M | [ ] | - -> `✓` is state — checked when that phase's channel completes. - -### Phase 1 — `<name>` -- **Scope:** `<what's in>` -- **Out of scope:** `<what's not>` -- **Key files/modules:** `<starting points, one clause each>` -- **Verification:** `<embed shared/verification-criteria.md for this phase>` - -### Phase 2 — `<name>` -`<repeat the block per phase. Each block is self-contained so /do can pick the` -`phase up alone — verification criteria live here, never in the table.>` - -## Cross-cutting concerns -`<security · observability · migration — anything true across phases>` - -## Justification -- `<claim challenged in the Socratic gate>` — `<the reason that held>` - -`<distilled from the socrates Q&A, one line per surviving question: why this` -`epic exists, why these phases, why not the cheaper shape. If the user waived` -`the gate: "Socratic gate waived by user.">` - -## Open questions -- `[NEEDS CLARIFICATION]` `<resolve before the affected phase is picked up>` - -## References (optional, in refs/) -- `refs/discussion.md` diff --git a/tyler/.claude/skills/create-feature/SKILL.md b/tyler/.claude/skills/create-feature/SKILL.md deleted file mode 100644 index a3442cb..0000000 --- a/tyler/.claude/skills/create-feature/SKILL.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -name: create-feature -description: Captures a discussed feature as a lean Feature Ticket work item ready for /do. For multi-phase workstreams use /create-epic instead. -argument-hint: "[feature title or one-line summary]" -disable-model-invocation: true ---- - -# Create Feature - -## Feature: $ARGUMENTS - -Turn what the conversation has established (typically a `/discussion`) into a Feature -Ticket that `/do` can execute autonomously. The completion artifact is -`./tmp/<id>/item.md` with `status: ready`. - -This skill *captures and sharpens* — it does not re-run the discussion. If the -conversation already settled a point, write it down; don't re-litigate it. - -## Steps - -### 1. Assemble the core from the conversation -Drive toward the four things the ticket needs, pulling from the discussion so far: -- **Intent** — the why behind the request -- **Desired end state** — user-visible "done" -- **Locked directions** — only decisions the model shouldn't re-make (number them D1, D2…) -- **Out of scope** - -Where the conversation left a gap, ask the user directly — one focused round, not a new -discussion. If a codebase fact is missing, dispatch the `codex` skill (role -`code-researcher`); for an external fact, the `web-researcher` sub-agent. - -**Success criteria**: the user has explicitly agreed to intent, end state, each locked -direction, and the out-of-scope list. - -### 2. Check the shape -One coherent outcome with one verification surface fits a Feature Ticket. If what -emerged is really multiple sequential, independently verifiable phases, say so and -suggest `/create-epic` instead — don't force an epic into a ticket. When in doubt, -prefer the smaller shape. - -**Success criteria**: shape confirmed (or handed off to `/create-epic`). - -### 3. Write the work item -Draft `./tmp/<id>/item.md` per `~/.references/draft-work-item.md`, using this -skill's `references/feature-ticket.md` as the template. Suitable methods for a -feature's ACs: a lint rule, test, script (backend), or natural navigation of -the running app (frontend/mobile). - -**Success criteria**: `item.md` exists; every AC is numbered, observable, and mapped; -nothing in the item restates what refs/ or the model already covers. - -### 4. Socratic gate -Run the gate per `~/.references/socratic-gate.md`. For a feature it bears -down on necessity, root cause, simpler alternatives, and shape; a -straightforward, well-justified draft fast-passes with zero to two questions. -If the dialogue reveals a multi-phase shape, hand off to `/create-epic`. - -**Success criteria**: gate procedure complete — socrates returned `pass` (or -the cap was reached, or the user waived); `## Justification` written into -`item.md`. - -### 5. Mark ready and publish -Publish per `~/.references/publish-work-item.md` — issue title -`feat: <item title>`, issue body = the item's intent, desired end state, -verification criteria summary, and the Justification section. - -**Success criteria**: published and cross-linked per the shared procedure. - -``` -Suggested next steps: -- `/do <issue # or ./tmp/<id>/item.md>` — run the autonomous pipeline against this item -- `/discussion [follow-up]` — if a gap surfaced that needs more thinking first -``` diff --git a/tyler/.claude/skills/create-feature/references/feature-ticket.md b/tyler/.claude/skills/create-feature/references/feature-ticket.md deleted file mode 100644 index 7bc468a..0000000 --- a/tyler/.claude/skills/create-feature/references/feature-ticket.md +++ /dev/null @@ -1,57 +0,0 @@ -# Feature Ticket — format - -> Produced by `/create-feature`. Saved as `./tmp/<id>/item.md`. -> **Lean and high-signal.** Everything here is required-minimal; raw sources go in `refs/`. - ---- -```yaml ---- -type: feature-ticket -id: <id> -status: ready # draft | ready | done -pr: <url or # — filled when /do opens it> ---- -``` - -# Feature: `<title>` - -## Intent -`<the why + the underlying goal behind the request — not just the requested solution.` -`A few sentences. This is what /do optimizes for and what PR review is judged against.>` - -## Desired end state -`<what "done" looks like from the user's side. A before → after helps. No implementation.>` - -## Key architecture directions -`<ONLY the locked decisions + any rejected alternative worth naming. Directions, not a` -`design — no file lists or pseudo-code. If the model can reasonably decide it, omit it.` -`Number them (D1, D2…) if there's more than one — reviews cite them by ID.>` - -## Starting points (non-exhaustive) -- `<file/module>` — `<why it's relevant, one clause>` - -`<2–4 pointers that orient /do without dictating design. Omit section if unknown.>` - -## Verification criteria -`<embed shared/verification-criteria.md — acceptance in EARS + how verify proves it>` - -## Out of scope -- `<explicit exclusion — the guard against gold-plating>` - -## Justification -- `<claim challenged in the Socratic gate>` — `<the reason that held>` - -`<distilled from the socrates Q&A, one line per surviving question. This is the` -`item's "FAQ": why this exists, why this shape, why not the cheaper alternative.` -`On a fast pass, socrates' one line naming what convinced it; if the user waived` -`the gate: "Socratic gate waived by user." Full dialogue, if long, in` -`refs/socratic-dialogue.md.>` - -## Open questions -- `[NEEDS CLARIFICATION]` `<unresolved design choice — name it, don't paper over it>` - -`<omit section if none>` - -## References (optional, in refs/) -- `refs/discussion.md` -- `refs/mockup.png` diff --git a/tyler/.claude/skills/create-issue/SKILL.md b/tyler/.claude/skills/create-issue/SKILL.md deleted file mode 100644 index 044a519..0000000 --- a/tyler/.claude/skills/create-issue/SKILL.md +++ /dev/null @@ -1,92 +0,0 @@ ---- -name: create-issue -description: Captures a defect as a Bug Report work item ready for /do, running the investigator first if the root cause isn't already established. -argument-hint: "[bug title or one-line summary]" -disable-model-invocation: true ---- - -# Create Issue - -## Issue: $ARGUMENTS - -Turn a defect the conversation has surfaced (typically via `/discussion`) into a lean -Bug Report that `/do` can fix autonomously. The completion artifact is -`./tmp/<id>/item.md` with `status: ready` — diagnosis captured, fix delegated. -This skill documents; it never fixes code. - -## Steps - -### 1. Take stock of the investigation -Check what the conversation already established: reproduction, root cause + evidence, -confidence level. A root-cause finding from an `investigator` dispatch during -`/discussion` is the ideal input — reuse it, don't redo it. - -If the root cause is **not** yet established, run the investigation now: -- Dispatch the investigator via the `codex` skill (role `investigator`) with the full - report (expected vs actual, environment, known repro steps, traces); it returns its - standard root-cause finding. -- If reproduction requires driving the running app, dispatch `frontend-verifier` - first to exercise the flow and capture evidence, then pass its transcript along - with the defect report. -- If the investigator cannot reproduce: say so plainly. Do not invent a cause. Either - gather more from the user (logs, exact environment) and re-dispatch, or proceed with - root cause marked `Hypothesis:` and what-was-tried captured in `refs/`. - -**Success criteria**: a root-cause finding in hand with an honest confidence level -(`confirmed | likely | hypothesis`) — or a documented failed-to-reproduce with the -attempts listed. - -### 2. Confirm impact and severity -Where judgment is needed, confirm with the user: who is affected, how widespread, why -it matters now, and whether the suggested resolution path should be locked as a -direction or left to `/do`. Skip the ceremony when severity is obvious. - -**Success criteria**: severity (`critical | high | medium | low`) and business impact -agreed with the user. - -### 3. Write the Bug Report -Draft `./tmp/<id>/item.md` per `~/.references/draft-work-item.md`, using this -skill's `references/bug-report.md` as the template. Bug specifics: -- Reproduction steps go **in the report** — deterministic enough for the verify stage - to re-run them. Raw traces, logs, and long transcripts go to `./tmp/<id>/refs/` - (e.g. `refs/error-trace.txt`), linked not inlined. If the investigation produced a - current-state deep-dive worth keeping, save it per - `~/.references/system-analysis.md` as `refs/system-analysis.md`. -- Verification criteria must include: - - **AC1**: the reproduction flipping from fail to pass — the repro steps double as - the failing case the fix must flip. - - **Prevention criteria**: what stops this class of bug recurring — a regression - test, a custom lint/static rule (the most durable guard), or an invariant — - verifiable, not aspirational. - -**Success criteria**: `item.md` exists; repro is re-runnable; AC1 maps to the repro; -prevention criteria present; raw material linked from `refs/`. - -### 4. Socratic gate -Run the gate per `~/.references/socratic-gate.md`. For a bug report it bears -down on root cause vs symptom (does the cause survive another "why"?), -evidence, whether the fix prevents the class or just this instance, and -completeness — sibling instances of the same defect class elsewhere, or -follow-up work this fix implies. A confirmed cause with a contained fix -fast-passes with zero to two questions. If the dialogue surfaces a deeper -cause to chase, re-dispatch the investigator before proceeding. - -**Success criteria**: gate procedure complete — socrates returned `pass` (or -the cap was reached, or the user waived); `## Justification` written into -`item.md`. - -### 5. Mark ready and publish -Publish per `~/.references/publish-work-item.md` — issue title -`fix: <bug title>`, issue body = summary, severity, reproduction steps, root -cause + confidence, and the Justification section. Exception: leave -`status: draft` if the cause is still a hypothesis and the user wants more -evidence first — publish happens either way, so the evidence trail lives -with the issue. - -**Success criteria**: published and cross-linked per the shared procedure. - -``` -Suggested next steps: -- `/do <issue # or ./tmp/<id>/item.md>` — run the autonomous pipeline to fix and verify -- `/discussion [topic]` — if the bug exposed a design question bigger than the fix -``` diff --git a/tyler/.claude/skills/create-issue/references/bug-report.md b/tyler/.claude/skills/create-issue/references/bug-report.md deleted file mode 100644 index aa95f8f..0000000 --- a/tyler/.claude/skills/create-issue/references/bug-report.md +++ /dev/null @@ -1,59 +0,0 @@ -# Bug Report — format - -> Produced by `/create-issue`. Saved as `./tmp/<id>/item.md`. -> Spine: intent = **root cause**, desired state = **correct behavior**. Keep it lean. - ---- -```yaml ---- -type: bug-report -id: <id> -status: draft # draft | ready | done -severity: <critical | high | medium | low> -pr: <url or # — filled when /do opens it> ---- -``` - -# Bug: `<one-line title>` - -## Summary -`<what's broken, in the observed behavior — 1–2 sentences>` - -**Environment:** `<version/build · runtime · where observed (prod / staging / local)>` - -## Expected vs actual -- **Expected:** `<correct behavior>` -- **Actual:** `<observed behavior — stated as observation, not assumed cause>` - -## Steps to reproduce -1. `<numbered steps from a known starting state — deterministic enough that the` - `verify stage can re-run them to prove the fix>` -2. `<step>` - -## Root cause -`<the identified cause. If not yet confirmed, prefix "Hypothesis:" and note confidence` -`(confirmed | likely | hypothesis).>` - -## Business impact -`<who / what is affected, how widespread, why it matters now>` - -## Suggested resolution path -`<the locked direction for the fix — high level, not code. Omit detail /do can decide.>` - -## Verification criteria -`<embed shared/verification-criteria.md — acceptance in EARS + how verify proves the fix.` -`The repro steps above double as the failing case AC1 must flip.>` - -## Prevention criteria -`<what stops this class of bug recurring: a regression test, a guard, an invariant>` - -## Justification -- `<claim challenged in the Socratic gate>` — `<the reason that held>` - -`<distilled from the socrates Q&A: why this cause is the root and not a symptom,` -`why fix now, why this resolution path. On a fast pass, socrates' one line naming` -`what convinced it; if the user waived the gate: "Socratic gate waived by user.">` - -## References (optional, in refs/) -- `refs/error-trace.txt` -- `refs/discussion.md` diff --git a/tyler/.claude/skills/discussion/SKILL.md b/tyler/.claude/skills/discussion/SKILL.md deleted file mode 100644 index f0bd972..0000000 --- a/tyler/.claude/skills/discussion/SKILL.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -name: discussion -description: Interactive back-and-forth to clarify, understand, or figure something out — an idea, an approach, a tradeoff, or a suspected bug. Use when the user wants to think out loud or explore before committing to anything — e.g. "let's discuss X", "help me understand Y", "why is Z happening", "what should we do about W". Produces clarity plus a dated decision log, not deliverables; work items are created afterward with /create-feature, /create-epic, or /create-issue. -argument-hint: "[idea, question, or topic]" ---- - -# Discussion - -## Topic: $ARGUMENTS - -Have an interactive, opinionated discussion. The goal is shared clarity — understanding -the problem, weighing the options, or pinning down what's actually happening — not a -document. When the discussion converges on something worth building or fixing, the user -invokes the matching `/create-*` skill; this skill's job ends at clarity. - -## Conversation and research only — unless asked - -Don't edit source files, propose diffs to apply, or write documents, specs, tickets, -or verification criteria unless the user explicitly asks for one mid-discussion. -Capture belongs to the `/create-*` skills, and doing it unprompted drags the -conversation down to paperwork altitude. The one exception is Step 3's -decision log — a record of what was decided, not a deliverable. - -## Steps - -### 1. Dispatch the right specialist for each question -Delegate legwork to sub-agents so bulky exploration stays out of this thread. Pick by -what the user is actually asking: - -- **How does our code work? What exists today?** → the `codex` skill, role - `code-researcher` (returns file:line findings). -- **What do the docs / ecosystem / other people do?** → the `web-researcher` - sub-agent (returns a cited dossier). Reach for it whenever up-to-date - information or outside opinions would sharpen the discussion — library - versions, current best practice, how others solved this. -- **Why is this broken? Is this a bug?** → the `codex` skill, role `investigator` - (reproduces and root-causes, returns a finding with evidence and confidence). - If reproduction requires driving the running app, dispatch `frontend-verifier` - first to exercise the flow and capture evidence, then pass its transcript along - with the defect report. - -Only research what the discussion actually needs — let questions pull research, not -the other way around. Dispatch mid-conversation as new questions arise; run -independent dispatches in parallel. - -**Success criteria**: every claim you make about the codebase, ecosystem, or defect -traces to a sub-agent finding or user statement, not a guess. - -### 2. Discuss and converge -- Present findings and options with tradeoffs; be opinionated — recommend with - reasoning, defer to user judgment. -- Name disagreements and unresolved choices instead of papering over them. -- Keep altitude: decisions and direction, not file-by-file detail. - -**Success criteria**: the user says the question is answered, the direction is clear, -or they're ready to capture a work item. - -### 3. Log the decisions, then hand off -When the discussion converges, write the decision log to -`./tmp/discussions/YYYY-MM-DD-<slug>.md`: the decisions made and why, the -direction chosen and over what alternatives, constraints the user stated, -open questions. A few lines each — dated and slugged so parallel -workstreams never collide. This is how intent survives past the -conversation: the `/create-*` drafting step reads it, and anyone resuming -the thread starts from it instead of from memory. - -Then point at the capture skill — don't run it yourself unless the user asks: - -``` -Decision log: ./tmp/discussions/YYYY-MM-DD-<slug>.md - -Suggested next steps: -- `/create-feature [title]` — capture a single-outcome change as a Feature Ticket -- `/create-epic [title]` — capture a multi-phase workstream as an Epic Spec -- `/create-issue [title]` — capture a defect (investigated here) as a Bug Report -- `/discussion [follow-up]` — keep exploring a different aspect -``` diff --git a/tyler/.claude/skills/do/SKILL.md b/tyler/.claude/skills/do/SKILL.md deleted file mode 100644 index 101981b..0000000 --- a/tyler/.claude/skills/do/SKILL.md +++ /dev/null @@ -1,197 +0,0 @@ ---- -name: do -description: Run the full autonomous pipeline against a work item — plan, implement, verify, PR, post-PR review + QA, wrap-up. Takes a GitHub issue #/URL or a local ./tmp/<id>/item.md produced by the /create-* skills. -argument-hint: "[GitHub issue # / URL, or path to ./tmp/<id>/item.md]" -disable-model-invocation: true ---- - -# /do — the autonomous pipeline - -## Work item: $ARGUMENTS - -You are the **Overseer** — the orchestrating agent (Fable, this session); -sub-agent role instructions and report formats refer to you by that name. -Every judgment call is yours — which lane the item takes, how much research -the plan needs, when the plan is ready, when review findings are resolved. Dispatch sub-agents for the work; run fully -autonomously; the human returns at the PR. - -**Sub-agents:** code-researcher, implementer, backend-verifier, -plan-reviewer, and code-reviewer run on Codex via the `codex` skill; each -review runs the Codex and Claude reviewers in parallel and weighs both -reports. Work routes by surface: backend/ops implementation and -verification → Codex (implementer, backend-verifier); frontend web/mobile -work (UI components, styling, client-side state, user-facing copy) → the -Claude `frontend-implementer`, verified by the Claude `frontend-verifier`. -web-researcher is a Claude sub-agent. - -## Step 0: Load - -Get everything about the work item into `./tmp/<id>/` before starting: for a -GitHub issue, the `notion` skill (operation `pull`) fetches the Notion work -item and all its artifacts. No Notion link? The issue body is the item, and -the issue's comments carry the refs — harvest every -`<!-- ORCHESTRA-ARTIFACT path="..." -->` block back to its path under -`./tmp/<id>/` (joining `part=n` splits) before planning; an issue with -neither Notion nor artifact comments gives you the body alone, so say so in -the plan's Known mismatches. A local path is read directly. Invoked with no argument: list -the local items with `status: ready` (`./tmp/*/item.md`) and ask the user -which to run — never pick one silently. Skim `refs/`; read individual refs -as the work calls for them. - -Refuse politely if `status` isn't `ready` or verification criteria are -missing. Never create a branch — if on the default branch, stop and ask the -user to set one up. - -**Done when**: the item and its artifacts are in `./tmp/<id>/`, status is -`ready`, and you're on a non-default branch. - -## Step 1: Plan - -Set the lane first, and record it in `plan.md`'s frontmatter: - -- **light** — one surface, a handful of files, low blast radius, no - schema/auth/async changes. No dossier; research directly. Review loops - this run cap at 1 pass instead of 3. -- **full** — everything else. Epics are always full. - -Full lane: dispatch the `codex` skill, role `code-researcher`, to map the -territory the plan builds on — critical codebase anchors, patterns to -reuse, load-bearing gotchas, exact `file:line` evidence for every claim. -When the item leans on an external library, framework, or API the repo -alone can't answer, dispatch the `web-researcher` sub-agent in parallel — -its cited findings (URL + why + the critical insight) go into the dossier -too. Save the combined findings as `./tmp/<id>/refs/research-dossier.md` — -the researchers report in-conversation; you persist the dossier. -Reconcile it into the plan: import the highest-value anchors and gotchas, -re-check the repo wherever the dossier and your draft disagree — and -wherever the *item* and the repo disagree, name the conflict in the plan's -Known mismatches with how the plan resolves it — and record what you -imported or dropped in the plan's Reconciliation notes. - -Research beyond that as the item actually needs — you judge. If the item links -Notion pages beyond what Step 0 pulled and a Notion connection (MCP or CLI) -is available, fetch them via the `notion` skill rather than planning around -the gap. Then write -`./tmp/<id>/plan.md` following this skill's `references/implementation-plan.md` — -its evidence contract is binding: facts live in Verified repo truths with -`path:line` evidence from files opened this session, and proposals stay out -of fact sections. When genuinely uncertain about a requirement or design -detail, never decide by silent assumption — name it in the plan's Open -questions and proceed on the least-committal reading. Restate the item's -`AC#` criteria verbatim. Run the review -loop — both reviewers, findings fixed into the plan — until you're satisfied -the plan is ready, cap 3 passes (light lane: 1); carry anything unresolved -at the cap into the plan's open questions. Score the plan's `confidence:` -(1–10, one-pass implementation confidence) as each pass exits — while -budget remains within the caps, a low score is the signal to spend it (more -research, another pass); the score recorded after the last pass is final. -Never a reason to stop the run. - -## Step 2: Implement - -Route each dispatch by surface: frontend work → the `frontend-implementer` -sub-agent; backend/ops work → the `codex` skill, role `implementer` (later -fix rounds resume the same Codex session). A mixed plan splits into separate -dispatches — you sequence them. Give each the plan and the item (intent = -source of truth for *why*). Resolve blockers yourself from the item/refs; -only a blocker that genuinely needs the human stops the run. - -## Step 3: Verify - -Prove every verification criterion — the `frontend-verifier` sub-agent for -computer-use flows in the running app, the `codex` skill role -`backend-verifier` for tests/scripts. Include the change type's rubric from -`~/.references/rubrics/` in each verifier dispatch (see -`~/.references/verification-methods.md`); its blocker items gate alongside -the ACs. Quoted evidence on every pass; nothing is assumed. Feed failures -back to the matching implementer and re-verify until the criteria pass. - -**Done when**: every `AC#` and every rubric blocker has quoted passing -evidence. - -## Step 4: PR - -The PR is an artifact, not the finish line — open it once the work -verifies, then improve it in place (Step 5). All commit/PR prep lives here: - -- **Build gate first**: discover the project's own build/typecheck/lint - workflow (`package.json` scripts, Makefile, CI config — ask the repo, - don't assume) and run it. Failures are must-fix before the PR opens. -- **Deploy notes scan**: scan the run's diff for schema/migrations, env - vars/secrets, infra/CI, new third-party dependencies, and one-time - scripts/backfills. Surface findings; never apply or gate on them. -- Commit selectively (only this run's files, never `git add -A`; secret-scan - the staged diff), message style `type: short imperative summary`. Rebase - onto the origin default branch; push (`--force-with-lease` on rewrites). -- Open the PR: typed title; body = **Summary** (the item's intent and what - "done" means), **Visual overview** (when the change is flow-, boundary-, - or lifecycle-shaped and the `excalidraw-pr-diagrams` skill is available: - the rendered before → after diagram per that skill's PR standard leads - the section, followed by before/after screenshots of the actual behavior - when the change is user-visible — before from the item's refs or - reproduction evidence, after from the verify captures. All hosted-image - URLs, never committed files; keep the `.excalidraw` source in - `./tmp/<id>/refs/`), **Verification** (evidence per AC), **Manual tests** (the - human-exercisable flows derived from the ACs, risk-tiered — Must: breaks - data/auth/money if wrong; Important: user-facing behavior; Nice: - cosmetic — each item traced to the change motivating it, 10–20 items - total, plus an "areas not affected" line so safe surfaces are skippable — - Step 5's QA pass executes it), **Deploy notes** (each finding: what changed + the - action the human takes before/at deploy — name env vars/secrets, never - their values; omit when the scan finds nothing), **Residual risks** (omit - if none); `Closes #<n>` when the item has a `github:` issue. - -## Step 5: Post-PR review + QA - -Reviews run against the open PR and fixes land on it — self-correction -happens on the artifact, not before it exists. - -- Run both reviewers over the PR diff (correctness + security, `(security)` - tags). Loop findings back to the matching implementer and push the fixes; - cap 3 passes (light lane: 1). -- When no Must Fix remains from either reviewer — or the cap was reached, - survivors flagged in the wrap-up — run the **QA pass**: execute the PR - body's Manual tests checklist best-effort, highest risk tier first. The - `frontend-verifier` drives the running app and captures screenshots; the - `codex` skill role `backend-verifier` runs the command-shaped items. Both - dispatches follow `~/.references/qa-verification.md` — external-system - confirmation by unique marker, preflight, test-mode safety, cleanup. - Report at two altitudes: tick the passed items directly in the PR body's - Manual tests checklist (`gh pr edit --body-file` — flip `[ ]` to `[x]`, - append `— left to human: <reason>` on skipped items, change nothing - else), so the description stays the live dashboard GitHub renders; then - post the evidence as a PR comment — each item with its quoted output or - hosted-image screenshot URLs (never committed files). Body carries state, - comments carry proof. -- After the loop and QA, post surviving Should Fix / Nice to Have findings - as line-anchored inline PR comments (`gh api` reviews, event `COMMENT` — - never `REQUEST_CHANGES`: the loop owns Must Fix, and capped survivors are - flagged in the wrap-up; these orient the returning human, they gate - nothing). - -## Step 6: Wrap-up - -- Write `./tmp/<id>/wrapup.md` following this skill's - `references/wrap-up-report.md`; post - it as a PR comment. If the item has a `notion:` reference, `notion` skill - operation `upload`: plan.md + wrapup.md, PR URL, status `done`. -- Report to the user: PR link + wrap-up summary + QA items left to the - human + anything unresolved. - -## Epics (type: epic-spec) - -Run Steps 1–3 per phase, sequentially — per-phase `plan-<n>.md`, tick the -phase ✓ in the spec on completion. After each phase verifies, review the -phase diff — both reviewers, same Must-Fix gate and cap — fix and -re-verify, then run the build gate and commit the phase following Step 4's -commit rules. After the last phase, continue from Step 4's PR steps -(deploy-notes scan over the whole epic diff, rebase, push, open the PR) and -run Steps 5–6 once for the whole epic. - -## Rules - -- Every output is checked by a different fresh-context reader than the one - that produced it; reviewers never edit; the implementer never reviews - itself. -- Never expand scope beyond the item. -- The run is resumable: plan.md plus the item's ✓ state say where you were. diff --git a/tyler/.claude/skills/do/references/implementation-plan.md b/tyler/.claude/skills/do/references/implementation-plan.md deleted file mode 100644 index 72c8b3b..0000000 --- a/tyler/.claude/skills/do/references/implementation-plan.md +++ /dev/null @@ -1,81 +0,0 @@ -# Implementation Plan — format - -> Produced by `/do` (plan stage) from the work item. Saved as `./tmp/<id>/plan.md` -> (per issue; one per phase for epics). Reviewed by Plan Reviewer, then updated with -> progress and plan-deltas during implement. -> **Calibrated for a frontier implementer: what to build & why, at file/module** -> **granularity — not line-level code.** No placeholder content: "TBD" or "add -> appropriate error handling" in a plan is a plan failure, not a plan. -> Pre-save check: every `modify` path exists in the repo, every `new` path fits -> the repo's current conventions, no template/placeholder paths, no line number -> that wasn't verified in this checkout. Cheap mechanical catch: grep the plan -> for `<feature>`, `path/to/`, `TBD`, and fact bullets missing `Evidence:`. - ---- -```yaml ---- -type: implementation-plan -item: <id> -lane: <light | full> -phase: <n | —> -confidence: <1-10 — one-pass implementation confidence, scored after review> ---- -``` - -# Implementation Plan — `<item / phase>` - -## Files changed -`<every file this plan touches — lets a reviewer gauge blast radius at a glance.` -`Keep the "what" to one clause; the tasks below carry the detail.>` - -| File | Change | What | -|---|---|---| -| `path/to/file.ts` | modify | `<one clause>` | -| `path/to/new-file.ts` | new | `<one clause>` | -| `path/to/old-file.ts` | delete | `<one clause>` | - -## Verified repo truths -`<what exists now, so the implementer needs no other doc — facts only, no proposals.` -`Present tense; no "we add", "will", or other future wording here. Every bullet:>` - -- **Fact**: `<one present-tense claim about the repo>` - **Evidence**: `path/to/file.ts:12-34` `<opened this session>` - **Implication**: `<why it shapes this plan>` - -`<Absence claims — "no X exists", "never called" — additionally carry` -`**Search evidence**: the search that came up empty.>` - -## Key decisions (restated for this work) -`<the locked calls from the item that shape this work — so nothing load-bearing is lost.>` - -## Known mismatches / assumptions -`<where the item's ask conflicts with repo reality — the conflict and how this` -`plan resolves it — plus any assumption the plan stands on. Or "none". A false` -`premise surfaced here is caught at plan review; buried, it ships to the PR.>` - -## Reconciliation notes -`<full lane: anchors/gotchas/docs imported from refs/research-dossier.md, conflicts` -`re-checked against the repo and how they resolved, dossier content intentionally` -`dropped as low-value. Light lane: "light lane — no dossier".>` - -## Tasks (ordered, file/module granularity) -- [ ] 1. `<task — what & why, where>` -- [ ] 2. `<task>` - -## Verification / acceptance -`<restate the item's numbered EARS criteria VERBATIM, plus the exact commands/flows` -`that prove each — the plan is self-sufficient; the implementer never opens the item.>` - -## Out of scope -`<carried from the item + anything explicitly deferred>` - -## Deprecated / removed -`<code this change makes dead — hunted, not assumed: superseded helpers,` -`orphaned exports, flags nothing reads anymore — or "none">` - -## Open questions -`<unresolved review findings carried at the cap, and anything the run must` -`judge as it goes — or omit the section>` - -## Plan deltas (filled during implement) -- `<deviation + reason>` *(or "none")* diff --git a/tyler/.claude/skills/do/references/wrap-up-report.md b/tyler/.claude/skills/do/references/wrap-up-report.md deleted file mode 100644 index 06b5b3a..0000000 --- a/tyler/.claude/skills/do/references/wrap-up-report.md +++ /dev/null @@ -1,37 +0,0 @@ -# Wrap-Up Report — format - -> Produced by `/do` at the end. Saved as `./tmp/<id>/wrapup.md` and posted to the PR. -> This is `/do`'s self-report and the human's starting point for PR review — it folds -> in the **final** review outcome (individual review passes are not persisted). - ---- -```yaml ---- -type: wrap-up-report -item: <id> -pr: <url or #> ---- -``` - -# Wrap-Up Report — `<item>` - -## What was built -`<summary of the change, tied back to the item's intent>` - -## Verification evidence -`<what was run / driven and the result vs each acceptance criterion.` -`Text/log evidence, plus QA screenshots where captured; video deferred.>` - -## Review outcome -`<final state after the review loop — "Must Fix: 0 · passes used: k/<cap>" — and the` -`QA pass: manual tests executed vs left to the human. Note any` -`Should Fix / Nice to Have items intentionally deferred, and why — the same` -`survivors live as inline PR comments; this is the summary, not a second list.>` - -## Residual risks / follow-ups -- `<anything unresolved, deferred, or worth a future work item>` -- Deploy notes: `<each item + human action before/at deploy, or "none">` - -## Deltas vs plan -`<only where the final diff diverges from the plan's Files-changed table — or "none".` -`The full file list lives in the plan and the PR diff; don't repeat it here.>` diff --git a/tyler/.claude/skills/excalidraw-pr-diagrams/.gitignore b/tyler/.claude/skills/excalidraw-pr-diagrams/.gitignore deleted file mode 100644 index ef27a06..0000000 --- a/tyler/.claude/skills/excalidraw-pr-diagrams/.gitignore +++ /dev/null @@ -1,4 +0,0 @@ -.venv/ -*.png -uv.lock -__pycache__/ diff --git a/tyler/.claude/skills/excalidraw-pr-diagrams/README.md b/tyler/.claude/skills/excalidraw-pr-diagrams/README.md deleted file mode 100644 index 459f552..0000000 --- a/tyler/.claude/skills/excalidraw-pr-diagrams/README.md +++ /dev/null @@ -1,70 +0,0 @@ -# Excalidraw Diagram Skill - -A coding agent skill that generates beautiful and practical Excalidraw diagrams from natural language descriptions. Not just boxes-and-arrows - diagrams that **argue visually**. It also supports PR visual overviews that teach before/after changes to reviewers. - -Compatible with any coding agent that supports skills. Use `.claude/skills/` for Claude Code and `.codex/skills/` for Codex. - -## What Makes This Different - -- **Diagrams that argue, not display.** Every shape/group of shapes mirrors the concept it represents — fan-outs for one-to-many, timelines for sequences, convergence for aggregation. No uniform card grids. -- **Evidence artifacts.** As an example, technical diagrams include real code snippets and actual JSON payloads. -- **Built-in visual validation.** A Playwright-based render pipeline lets the agent see its own output, catch layout issues (overlapping text, misaligned arrows, unbalanced spacing), and fix them in a loop before delivering. -- **PR-ready handoff.** The skill covers shareable reviewer explainers, committed PR assets, raw GitHub image URLs, and PR body preview checks. -- **Brand-customizable.** All colors and brand styles live in a single file (`references/color-palette.md`). Swap it out and every diagram follows your palette. - -## Installation - -Clone or download this repo, then copy the skill into the right agent directory: - -```bash -cp -r parsa/.claude/skills/excalidraw-pr-diagrams ~/.claude/skills/excalidraw-pr-diagrams -cp -r parsa/.codex/skills/excalidraw-pr-diagrams ~/.codex/skills/excalidraw-pr-diagrams -``` - -## Setup - -The skill includes a render pipeline that lets the agent visually validate its diagrams. There are two ways to set it up: - -**Option A: Ask your coding agent (easiest)** - -Just tell your agent: *"Set up the Excalidraw diagram skill renderer by following the instructions in SKILL.md."* It will run the commands for you. - -**Option B: Manual** - -```bash -cd .claude/skills/excalidraw-pr-diagrams/references -uv sync -uv run playwright install chromium -``` - -For Codex installs, use `.codex/skills/excalidraw-pr-diagrams/references`. - -## Usage - -Ask your coding agent to create a diagram: - -> "Create an Excalidraw diagram showing how the AG-UI protocol streams events from an AI agent to a frontend UI" - -Or ask for a PR visual overview: - -> "Create a shareable PR diagram that explains the before and after behavior, commit the PNG under .github/pr-assets, and update the PR body." - -The skill handles the rest — concept mapping, layout, JSON generation, rendering, and visual validation. - -## Customize Colors - -Edit `references/color-palette.md` to match your brand. Everything else in the skill is universal design methodology. - -## File Structure - -``` -excalidraw-pr-diagrams/ - SKILL.md # Design methodology + workflow - references/ - color-palette.md # Brand colors (edit this to customize) - element-templates.md # JSON templates for each element type - json-schema.md # Excalidraw JSON format reference - render_excalidraw.py # Render .excalidraw to PNG - render_template.html # Browser template for rendering - pyproject.toml # Python dependencies (playwright) -``` diff --git a/tyler/.claude/skills/excalidraw-pr-diagrams/SKILL.md b/tyler/.claude/skills/excalidraw-pr-diagrams/SKILL.md deleted file mode 100644 index 164d037..0000000 --- a/tyler/.claude/skills/excalidraw-pr-diagrams/SKILL.md +++ /dev/null @@ -1,706 +0,0 @@ ---- -name: excalidraw-diagram -description: Create Excalidraw diagram JSON files and PR visual overviews that make visual arguments. Use when the user wants to visualize workflows, architectures, concepts, pull request changes, before/after behavior, or a shareable explainer image for reviewers. ---- - -# Excalidraw Diagram Creator - -Generate `.excalidraw` JSON files that **argue visually**, not just display information. - -**Setup:** If the user asks you to set up this skill (renderer, dependencies, etc.), see `README.md` for instructions. - -## Local Codex or Claude PR Workflow - -When using this skill for pull request diagrams in Codex or Claude: - -- Always create and edit diagram working files in a temporary working directory outside the target repo, preferably `/tmp/codex-pr-diagrams/<repo-or-pr>/` or `C:\tmp\codex-pr-diagrams\<repo-or-pr>\`. -- Do not create generated `.excalidraw`, `.png`, or temporary render files inside the repository unless the user explicitly asks for tracked diagram assets. -- For PR descriptions, use the rendered Excalidraw image as the primary visual. Do not add Mermaid diagrams by default; they are usually redundant once the Excalidraw image includes before/after flow and reviewer explainers. Add Mermaid only if the user explicitly asks for a durable text-rendered fallback. -- Save matching `.excalidraw` source files under `/tmp` for local iteration and future reuse. -- PR visual overviews must include explicit `Before` and `After` diagrams so reviewers can see both the old behavior and the new behavior without inferring the diff from prose. -- Keep each PR diagram focused on the change boundary: before, after, and why the new flow is safer. -- After generating diagrams, update the PR description with a dedicated `## Visual Overview` section. -- This skill is stored in multiple trees (`parsa/.claude/skills/`, `parsa/.codex/skills/`, and `tyler/.claude/skills/` — tyler's `/do` embeds its PR standard in the Visual overview step). Keep all copies materially equivalent unless there is an agent-specific reason to diverge. - -### PR Asset Publishing - -Default: PR images are **hosted, not committed**. Upload the rendered PNG to -a durable host and reference it inline in the PR body. Scriptable default: a -rolling GitHub release in the target repo — `gh release create pr-assets --notes "PR image assets"` -once, then `gh release upload pr-assets <image>.png` per image; the asset's -download URL renders inline and outlives branches. (GitHub user-attachment -URLs — drag an image into a comment box — are equally durable but have no -API; use them when a human or a browser-driving agent is doing the upload. -A project upload endpoint or temporary host also works.) The repo stays -free of multi-MB render blobs, and every re-render is just a new URL. If -only a temporary host is available, note its expiry next to the image. - -Commit the image only when it is embedded in tracked docs (a README, design -doc) that needs a stable in-repo path — then `.github/pr-assets/` or -`docs/`, referenced with a blob URL + `?raw=1`, e.g. -`https://github.com/<owner>/<repo>/blob/<branch>/.github/pr-assets/<image>.png?raw=1`. -Keep `.excalidraw` sources outside the repo unless the user asks to track them. - -Either way: - -- After updating, open or fetch the image URL. A PR visual with a 404 image is a failed handoff. -- Read back or preview the PR body after updating it. Markdown that collapses bullets, headings, or the image into one paragraph is a failed handoff. - -### PR Diagram Standard - -For PR diagrams, a simple pair of red/green cards is not acceptable. The diagram must teach the change in a way prose cannot. - -Before drawing, identify the visual truth of the PR: - -- **Boundary changed**: draw walls, membranes, trust zones, or origin/process boundaries. -- **Lifecycle changed**: draw a state machine, gate sequence, or retry loop. -- **Responsibility moved**: draw before/after ownership regions and move the action across them. -- **Failure mode removed**: draw the old failure path visibly dead-ending and the new path avoiding it. -- **Concurrency/race fixed**: draw clocks, timelines, joins, or retry circuits. -- **Validation/permissions changed**: draw a decision path, lock/gate, and what passes through it. - -Every PR visual overview must include: - -- A **before path** showing where the old system failed or was fragile. -- An **after path** showing the new route/control point. -- At least one **semantic visual structure**: boundary, timeline, loop, funnel, state machine, swimlane, queue, fan-out, convergence, or layered stack. -- One short **truth statement** that explains the visual argument in plain language. -- A small **term explainer** when the diagram uses protocol/framework words that a reviewer may not know. Do not assume terms like header, preflight, origin, token, cookie, CORS, WebSocket upgrade, cache key, breakpoint, or trace are self-explanatory. - -Do not use the same diagram structure for a series of PRs unless the code changes truly have the same shape. Split PRs usually need different visual metaphors because they fix different kinds of problems. - -### Shareable Explainers - -When the user wants a PR image that can teach the change to someone else, design it as a shareable explainer, not just reviewer decoration. - -- Make the title state the strategic outcome, not the implementation detail. -- Show the old blind spot, failure mode, or uncertainty on the left. -- Show the new loop, boundary, path, or control point on the right. -- Include at least one concrete example input and one concrete output. Real event names, endpoint paths, page names, source URLs, or dashboard fields make the image feel authoritative. -- If measurement is part of the value, show what gets captured and how it becomes a decision, backlog item, or next action. -- Add enough whitespace that each box can breathe. If an arrow needs to loop back, route it around the outside of the boxes. -- Inspect the final image at the size GitHub shows in a PR. If the viewer must open the image full size to understand it, simplify the diagram. - -### Reviewer Explainers - -When a PR involves technical protocol behavior, include a compact teaching layer in the visual: - -- Define the technical noun in a concrete metaphor before using it. Example: `headers = extra notes the browser wants to attach`, `preflight = permission check before the real request`, `origin = website address the browser trusts or blocks`. -- Show who performs each action. Example: `Browser asks`, `API answers`, `Browser blocks`, not just `headers requested`. -- Use concrete examples sparingly: `login badge`, `Sentry trace`, `Firebase app id` is clearer than a long raw header list. -- Keep the official term visible in parentheses after the plain-English term when useful: `permission check (CORS preflight)`. -- If the diagram has a metaphor, keep it mapped to the real system with labels. A security desk can teach CORS, but the browser/API roles must remain visible. - -For review diagrams, assume the reader is smart but has not learned this subsystem yet. If the reader would ask "who does that?" or "what is that?", add a visual cue or one-line explainer instead of relying on the PR prose. - -## Customization - -**All colors and brand-specific styles live in one file:** `references/color-palette.md`. Read it before generating any diagram and use it as the single source of truth for all color choices — shape fills, strokes, text colors, evidence artifact backgrounds, everything. - -To make this skill produce diagrams in your own brand style, edit `color-palette.md`. Everything else in this file is universal design methodology and Excalidraw best practices. - ---- - -## Core Philosophy - -**Diagrams should ARGUE, not DISPLAY.** - -A diagram isn't formatted text. It's a visual argument that shows relationships, causality, and flow that words alone can't express. The shape should BE the meaning. - -**The Isomorphism Test**: If you removed all text, would the structure alone communicate the concept? If not, redesign. - -**The Education Test**: Could someone learn something concrete from this diagram, or does it just label boxes? A good diagram teaches—it shows actual formats, real event names, concrete examples. - -**The Redundancy Test**: If the diagram is just the PR description broken into red and green rectangles, discard it. A good diagram uses spatial relationships, arrows, boundaries, and shape to reveal something the prose does not. - -**The High-Schooler Test**: A smart high-schooler should be able to point at the diagram and explain the core before/after change without reading the full PR. If they would only read labels out loud, redesign. - ---- - -## Depth Assessment (Do This First) - -Before designing, determine what level of detail this diagram needs: - -### Simple/Conceptual Diagrams -Use abstract shapes when: -- Explaining a mental model or philosophy -- The audience doesn't need technical specifics -- The concept IS the abstraction (e.g., "separation of concerns") - -### Comprehensive/Technical Diagrams -Use concrete examples when: -- Diagramming a real system, protocol, or architecture -- The diagram will be used to teach or explain (e.g., YouTube video) -- The audience needs to understand what things actually look like -- You're showing how multiple technologies integrate - -**For technical diagrams, you MUST include evidence artifacts** (see below). - ---- - -## Research Mandate (For Technical Diagrams) - -**Before drawing anything technical, research the actual specifications.** - -If you're diagramming a protocol, API, or framework: -1. Look up the actual JSON/data formats -2. Find the real event names, method names, or API endpoints -3. Understand how the pieces actually connect -4. Use real terminology, not generic placeholders - -Bad: "Protocol" → "Frontend" -Good: "AG-UI streams events (RUN_STARTED, STATE_DELTA, A2UI_UPDATE)" → "CopilotKit renders via createA2UIMessageRenderer()" - -**Research makes diagrams accurate AND educational.** - ---- - -## Evidence Artifacts - -Evidence artifacts are concrete examples that prove your diagram is accurate and help viewers learn. Include them in technical diagrams. - -**Types of evidence artifacts** (choose what's relevant to your diagram): - -| Artifact Type | When to Use | How to Render | -|---------------|-------------|---------------| -| **Code snippets** | APIs, integrations, implementation details | Dark rectangle + syntax-colored text (see color palette for evidence artifact colors) | -| **Data/JSON examples** | Data formats, schemas, payloads | Dark rectangle + colored text (see color palette) | -| **Event/step sequences** | Protocols, workflows, lifecycles | Timeline pattern (line + dots + labels) | -| **UI mockups** | Showing actual output/results | Nested rectangles mimicking real UI | -| **Real input content** | Showing what goes IN to a system | Rectangle with sample content visible | -| **API/method names** | Real function calls, endpoints | Use actual names from docs, not placeholders | - -**Example**: For a diagram about a streaming protocol, you might show: -- The actual event names from the spec (not just "Event 1", "Event 2") -- A code snippet showing how to connect -- What the streamed data actually looks like - -**Example**: For a diagram about a data transformation pipeline: -- Show sample input data (actual format, not "Input") -- Show sample output data (actual format, not "Output") -- Show intermediate states if relevant - -The key principle: **show what things actually look like**, not just what they're called. - ---- - -## Multi-Zoom Architecture - -Comprehensive diagrams operate at multiple zoom levels simultaneously. Think of it like a map that shows both the country borders AND the street names. - -### Level 1: Summary Flow -A simplified overview showing the full pipeline or process at a glance. Often placed at the top or bottom of the diagram. - -*Example*: `Input → Processing → Output` or `Client → Server → Database` - -### Level 2: Section Boundaries -Labeled regions that group related components. These create visual "rooms" that help viewers understand what belongs together. - -*Example*: Grouping by responsibility (Backend / Frontend), by phase (Setup / Execution / Cleanup), or by team (User / System / External) - -### Level 3: Detail Inside Sections -Evidence artifacts, code snippets, and concrete examples within each section. This is where the educational value lives. - -*Example*: Inside a "Backend" section, you might show the actual API response format, not just a box labeled "API Response" - -**For comprehensive diagrams, aim to include all three levels.** The summary gives context, the sections organize, and the details teach. - -### Bad vs Good - -| Bad (Displaying) | Good (Arguing) | -|------------------|----------------| -| 5 equal boxes with labels | Each concept has a shape that mirrors its behavior | -| Card grid layout | Visual structure matches conceptual structure | -| Icons decorating text | Shapes that ARE the meaning | -| Same container for everything | Distinct visual vocabulary per concept | -| Everything in a box | Free-floating text with selective containers | -| Red card titled "Before" beside green card titled "After" | A before failure path and an after success path with different routing | -| Repeating the same template across unrelated PRs | Choosing a visual metaphor per PR: boundary, lifecycle, race, permission gate, retry loop | -| Paragraphs pasted into shapes | Short labels plus visual evidence, arrows, gates, and concrete artifacts | - -### Hard Anti-Patterns - -Never ship these unless the user explicitly asks for a deliberately minimal sketch: - -- Two large cards that simply summarize "Before" and "After". -- A diagram whose boxes could be replaced by bullets with no loss of meaning. -- Red/green color as the only source of meaning. -- Multiple PR diagrams with the same layout when the PRs solve different problems. -- Oversized headings that force the rest of the diagram to sprawl. -- Long prose inside Excalidraw text boxes. -- Rendered output where any text, title, arrow, or shape is clipped. -- Rendered output where key content requires horizontal scrolling to understand. - -### Simple vs Comprehensive (Know Which You Need) - -| Simple Diagram | Comprehensive Diagram | -|----------------|----------------------| -| Generic labels: "Input" → "Process" → "Output" | Specific: shows what the input/output actually looks like | -| Named boxes: "API", "Database", "Client" | Named boxes + examples of actual requests/responses | -| "Events" or "Messages" label | Timeline with real event/message names from the spec | -| "UI" or "Dashboard" rectangle | Mockup showing actual UI elements and content | -| ~30 seconds to explain | ~2-3 minutes of teaching content | -| Viewer learns the structure | Viewer learns the structure AND the details | - -**Simple diagrams** are fine for abstract concepts, quick overviews, or when the audience already knows the details. **Comprehensive diagrams** are needed for technical architectures, tutorials, educational content, or when you want the diagram itself to teach. - ---- - -## Container vs. Free-Floating Text - -**Not every piece of text needs a shape around it.** Default to free-floating text. Add containers only when they serve a purpose. - -| Use a Container When... | Use Free-Floating Text When... | -|------------------------|-------------------------------| -| It's the focal point of a section | It's a label or description | -| It needs visual grouping with other elements | It's supporting detail or metadata | -| Arrows need to connect to it | It describes something nearby | -| The shape itself carries meaning (decision diamond, etc.) | Typography alone creates sufficient hierarchy | -| It represents a distinct "thing" in the system | It's a section title, subtitle, or annotation | - -**Typography as hierarchy**: Use font size, weight, and color to create visual hierarchy without boxes. A 28px title doesn't need a rectangle around it. - -**The container test**: For each boxed element, ask "Would this work as free-floating text?" If yes, remove the container. - -## Canvas, Text, and Fit Rules - -Excalidraw text does not wrap exactly like normal HTML. Design for the renderer, not for wishful JSON dimensions. - -### Canvas - -- Start with a larger canvas than you think you need. For PR diagrams, plan around roughly **1600-2200 px wide** and **900-1400 px tall** before export. -- Use the larger canvas for meaningful spatial structure, not for giant titles or long paragraphs. -- Prefer two or three clear regions over many cramped micro-panels. -- Leave at least **80 px** outer margin and **50 px** between major regions. - -### Text - -- Keep titles short: ideally under 55 characters. -- Use smaller title type than instinct suggests: **24-30 px** is usually enough. -- Use labels at **14-18 px** and truth statements at **16-20 px**. -- Keep shape labels to **1-4 short lines**. If a label needs more, split it into multiple nearby annotations or make the diagram itself carry more meaning. -- Manually insert line breaks. Do not rely on Excalidraw/renderer wrapping. -- Make text boxes wider than the text appears to need. Add at least **30-50% extra width** as a safety margin. -- For every text element, set `width` and `height` generously. Clipping is a hard failure. - -### Render Fit - -After rendering, inspect at the exact PNG that will be shown in the PR: - -- If anything is clipped, increase canvas space or shrink/reposition text. -- If the diagram is mostly text, remove prose and add visual structure. -- If the title dominates the image, shrink it. -- If labels overlap arrows or shapes, move labels out of the flow path. -- If the image is too wide to understand in GitHub, reduce prose and stack regions vertically. - ---- - -## Design Process (Do This BEFORE Generating JSON) - -### Step 0: Assess Depth Required -Before anything else, determine if this needs to be: -- **Simple/Conceptual**: Abstract shapes, labels, relationships (mental models, philosophies) -- **Comprehensive/Technical**: Concrete examples, code snippets, real data (systems, architectures, tutorials) - -**If comprehensive**: Do research first. Look up actual specs, formats, event names, APIs. - -### Step 1: Understand Deeply -Read the content. For each concept, ask: -- What does this concept **DO**? (not what IS it) -- What relationships exist between concepts? -- What's the core transformation or flow? -- **What would someone need to SEE to understand this?** (not just read about) - -### Step 2: Map Concepts to Patterns -For each concept, find the visual pattern that mirrors its behavior: - -| If the concept... | Use this pattern | -|-------------------|------------------| -| Spawns multiple outputs | **Fan-out** (radial arrows from center) | -| Combines inputs into one | **Convergence** (funnel, arrows merging) | -| Has hierarchy/nesting | **Tree** (lines + free-floating text) | -| Is a sequence of steps | **Timeline** (line + dots + free-floating labels) | -| Loops or improves continuously | **Spiral/Cycle** (arrow returning to start) | -| Is an abstract state or context | **Cloud** (overlapping ellipses) | -| Transforms input to output | **Assembly line** (before → process → after) | -| Compares two things | **Side-by-side** (parallel with contrast) | -| Separates into phases | **Gap/Break** (visual separation between sections) | - -### Step 3: Ensure Variety -For multi-concept diagrams: **each major concept must use a different visual pattern**. No uniform cards or grids. - -### Step 4: Sketch the Flow -Before JSON, mentally trace how the eye moves through the diagram. There should be a clear visual story. - -### Step 5: Generate JSON -Only now create the Excalidraw elements. **See below for how to handle large diagrams.** - -### Step 6: Render & Validate (MANDATORY) -After generating the JSON, you MUST run the render-view-fix loop until the diagram looks right. This is not optional — see the **Render & Validate** section below for the full process. - ---- - -## Large / Comprehensive Diagram Strategy - -**For comprehensive or technical diagrams, you MUST build the JSON one section at a time.** Do NOT attempt to generate the entire file in a single pass. This is a hard constraint — Claude Code has a ~32,000 token output limit per response, and a comprehensive diagram easily exceeds that in one shot. Even if it didn't, generating everything at once leads to worse quality. Section-by-section is better in every way. - -### The Section-by-Section Workflow - -**Phase 1: Build each section** - -1. **Create the base file** with the JSON wrapper (`type`, `version`, `appState`, `files`) and the first section of elements. -2. **Add one section per edit.** Each section gets its own dedicated pass — take your time with it. Think carefully about the layout, spacing, and how this section connects to what's already there. -3. **Use descriptive string IDs** (e.g., `"trigger_rect"`, `"arrow_fan_left"`) so cross-section references are readable. -4. **Namespace seeds by section** (e.g., section 1 uses 100xxx, section 2 uses 200xxx) to avoid collisions. -5. **Update cross-section bindings** as you go. When a new section's element needs to bind to an element from a previous section (e.g., an arrow connecting sections), edit the earlier element's `boundElements` array at the same time. - -**Phase 2: Review the whole** - -After all sections are in place, read through the complete JSON and check: -- Are cross-section arrows bound correctly on both ends? -- Is the overall spacing balanced, or are some sections cramped while others have too much whitespace? -- Do IDs and bindings all reference elements that actually exist? - -Fix any alignment or binding issues before rendering. - -**Phase 3: Render & validate** - -Now run the render-view-fix loop from the Render & Validate section. This is where you'll catch visual issues that aren't obvious from JSON — overlaps, clipping, imbalanced composition. - -### Section Boundaries - -Plan your sections around natural visual groupings from the diagram plan. A typical large diagram might split into: - -- **Section 1**: Entry point / trigger -- **Section 2**: First decision or routing -- **Section 3**: Main content (hero section — may be the largest single section) -- **Section 4-N**: Remaining phases, outputs, etc. - -Each section should be independently understandable: its elements, internal arrows, and any cross-references to adjacent sections. - -### What NOT to Do - -- **Don't generate the entire diagram in one response.** You will hit the output token limit and produce truncated, broken JSON. Even if the diagram is small enough to fit, splitting into sections produces better results. -- **Don't use a coding agent** to generate the JSON. The agent won't have sufficient context about the skill's rules, and the coordination overhead negates any benefit. -- **Don't write a Python generator script.** The templating and coordinate math seem helpful but introduce a layer of indirection that makes debugging harder. Hand-crafted JSON with descriptive IDs is more maintainable. - ---- - -## Visual Pattern Library - -### Fan-Out (One-to-Many) -Central element with arrows radiating to multiple targets. Use for: sources, PRDs, root causes, central hubs. -``` - ○ - ↗ - □ → ○ - ↘ - ○ -``` - -### Convergence (Many-to-One) -Multiple inputs merging through arrows to single output. Use for: aggregation, funnels, synthesis. -``` - ○ ↘ - ○ → □ - ○ ↗ -``` - -### Tree (Hierarchy) -Parent-child branching with connecting lines and free-floating text (no boxes needed). Use for: file systems, org charts, taxonomies. -``` - label - ├── label - │ ├── label - │ └── label - └── label -``` -Use `line` elements for the trunk and branches, free-floating text for labels. - -### Spiral/Cycle (Continuous Loop) -Elements in sequence with arrow returning to start. Use for: feedback loops, iterative processes, evolution. -``` - □ → □ - ↑ ↓ - □ ← □ -``` - -### Cloud (Abstract State) -Overlapping ellipses with varied sizes. Use for: context, memory, conversations, mental states. - -### Assembly Line (Transformation) -Input → Process Box → Output with clear before/after. Use for: transformations, processing, conversion. -``` - ○○○ → [PROCESS] → □□□ - chaos order -``` - -### Side-by-Side (Comparison) -Two parallel structures with visual contrast. Use for: before/after, options, trade-offs. - -### Gap/Break (Separation) -Visual whitespace or barrier between sections. Use for: phase changes, context resets, boundaries. - -### Lines as Structure -Use lines (type: `line`, not arrows) as primary structural elements instead of boxes: -- **Timelines**: Vertical or horizontal line with small dots (10-20px ellipses) at intervals, free-floating labels beside each dot -- **Tree structures**: Vertical trunk line + horizontal branch lines, with free-floating text labels (no boxes needed) -- **Dividers**: Thin dashed lines to separate sections -- **Flow spines**: A central line that elements relate to, rather than connecting boxes - -``` -Timeline: Tree: - ●─── Label 1 │ - │ ├── item - ●─── Label 2 │ ├── sub - │ │ └── sub - ●─── Label 3 └── item -``` - -Lines + free-floating text often creates a cleaner result than boxes + contained text. - ---- - -## Shape Meaning - -Choose shape based on what it represents—or use no shape at all: - -| Concept Type | Shape | Why | -|--------------|-------|-----| -| Labels, descriptions, details | **none** (free-floating text) | Typography creates hierarchy | -| Section titles, annotations | **none** (free-floating text) | Font size/weight is enough | -| Markers on a timeline | small `ellipse` (10-20px) | Visual anchor, not container | -| Start, trigger, input | `ellipse` | Soft, origin-like | -| End, output, result | `ellipse` | Completion, destination | -| Decision, condition | `diamond` | Classic decision symbol | -| Process, action, step | `rectangle` | Contained action | -| Abstract state, context | overlapping `ellipse` | Fuzzy, cloud-like | -| Hierarchy node | lines + text (no boxes) | Structure through lines | - -**Rule**: Default to no container. Add shapes only when they carry meaning. Aim for <30% of text elements to be inside containers. - ---- - -## Color as Meaning - -Colors encode information, not decoration. Every color choice should come from `references/color-palette.md` — the semantic shape colors, text hierarchy colors, and evidence artifact colors are all defined there. - -**Key principles:** -- Each semantic purpose (start, end, decision, AI, error, etc.) has a specific fill/stroke pair -- Free-floating text uses color for hierarchy (titles, subtitles, details — each at a different level) -- Evidence artifacts (code snippets, JSON examples) use their own dark background + colored text scheme -- Always pair a darker stroke with a lighter fill for contrast - -**Do not invent new colors.** If a concept doesn't fit an existing semantic category, use Primary/Neutral or Secondary. - ---- - -## Modern Aesthetics - -For clean, professional diagrams: - -### Roughness -- `roughness: 0` — Clean, crisp edges. Use for modern/technical diagrams. -- `roughness: 1` — Hand-drawn, organic feel. Use for brainstorming/informal diagrams. - -**Default to 0** for most professional use cases. - -### Stroke Width -- `strokeWidth: 1` — Thin, elegant. Good for lines, dividers, subtle connections. -- `strokeWidth: 2` — Standard. Good for shapes and primary arrows. -- `strokeWidth: 3` — Bold. Use sparingly for emphasis (main flow line, key connections). - -### Opacity -**Always use `opacity: 100` for all elements.** Use color, size, and stroke width to create hierarchy instead of transparency. - -### Small Markers Instead of Shapes -Instead of full shapes, use small dots (10-20px ellipses) as: -- Timeline markers -- Bullet points -- Connection nodes -- Visual anchors for free-floating text - ---- - -## Layout Principles - -### Hierarchy Through Scale -- **Hero**: 300×150 - visual anchor, most important -- **Primary**: 180×90 -- **Secondary**: 120×60 -- **Small**: 60×40 - -### Whitespace = Importance -The most important element has the most empty space around it (200px+). - -### Flow Direction -Guide the eye: typically left→right or top→bottom for sequences, radial for hub-and-spoke. - -### Connections Required -Position alone doesn't show relationships. If A relates to B, there must be an arrow. - ---- - -## Text Rules - -**CRITICAL**: The JSON `text` property contains ONLY readable words. - -```json -{ - "id": "myElement1", - "text": "Start", - "originalText": "Start" -} -``` - -Settings: `fontSize: 16`, `fontFamily: 3`, `textAlign: "center"`, `verticalAlign: "middle"` - ---- - -## JSON Structure - -```json -{ - "type": "excalidraw", - "version": 2, - "source": "https://excalidraw.com", - "elements": [...], - "appState": { - "viewBackgroundColor": "#ffffff", - "gridSize": 20 - }, - "files": {} -} -``` - -## Element Templates - -See `references/element-templates.md` for copy-paste JSON templates for each element type (text, line, dot, rectangle, arrow). Pull colors from `references/color-palette.md` based on each element's semantic purpose. - ---- - -## Render & Validate (MANDATORY) - -You cannot judge a diagram from JSON alone. After generating or editing the Excalidraw JSON, you MUST render it to PNG, view the image, and fix what you see — in a loop until it's right. This is a core part of the workflow, not a final check. - -### How to Render - -```bash -cd .claude/skills/excalidraw-pr-diagrams/references && uv run python render_excalidraw.py <path-to-file.excalidraw> -``` - -For Codex installs, use the matching `.codex/skills/excalidraw-pr-diagrams/references` directory. - -This outputs a PNG next to the `.excalidraw` file. Then use the available image viewer on the PNG to actually inspect it, such as the Read tool, `view_image`, or a browser screenshot. - -### The Loop - -After generating the initial JSON, run this cycle: - -**1. Render & View** — Run the render script, then Read the PNG. - -**2. Audit against your original vision** — Before looking for bugs, compare the rendered result to what you designed in Steps 1-4. Ask: -- Does the visual structure match the conceptual structure you planned? -- Does each section use the pattern you intended (fan-out, convergence, timeline, etc.)? -- Does the eye flow through the diagram in the order you designed? -- Is the visual hierarchy correct — hero elements dominant, supporting elements smaller? -- For technical diagrams: are the evidence artifacts (code snippets, data examples) readable and properly placed? -- For PR diagrams: does the rendered image tell a non-redundant before/after story through structure, not just labels? -- Would the image still communicate the main change if the prose paragraphs were removed? - -**3. Check for visual defects:** -- Text clipped by or overflowing its container -- Text or shapes overlapping other elements -- Arrows crossing through elements instead of routing around them -- Arrows landing on the wrong element or pointing into empty space -- Arrowheads, dashed loops, or feedback paths visually sitting on top of boxes or labels -- Labels floating ambiguously (not clearly anchored to what they describe) -- Uneven spacing between elements that should be evenly spaced -- Sections with too much whitespace next to sections that are too cramped -- Text too small to read at the rendered size -- Overall composition feels lopsided or unbalanced -- Any part of the title, subtitle, truth statement, or major region clipped by the screenshot bounds -- A horizontally sprawling image whose important content is hard to scan in a GitHub PR -- PR-specific defects: the committed image URL 404s, the PR body image does not render, or Markdown formatting collapses into a single paragraph. - -**4. Fix** — Edit the JSON to address everything you found. Common fixes: -- Widen containers when text is clipped -- Adjust `x`/`y` coordinates to fix spacing and alignment -- Add intermediate waypoints to arrow `points` arrays to route around elements -- Reposition labels closer to the element they describe -- Resize elements to rebalance visual weight across sections -- Shrink titles and labels before enlarging the diagram further. -- Replace long labels with a diagrammatic construct: boundary, queue, gate, loop, timeline, or swimlane. - -**5. Re-render & re-view** — Run the render script again and Read the new PNG. - -**6. Repeat** — Keep cycling until the diagram passes both the vision check (Step 2) and the defect check (Step 3). Typically takes 2-4 iterations. Don't stop after one pass just because there are no critical bugs — if the composition could be better, improve it. - -### When to Stop - -The loop is done when: -- The rendered diagram matches the conceptual design from your planning steps -- No text is clipped, overlapping, or unreadable -- Arrows route cleanly and connect to the right elements -- Spacing is consistent and the composition is balanced -- You'd be comfortable showing it to someone without caveats -- For PR diagrams, the before and after are visually different in a way that reflects the actual code change. -- The diagram would not be equally useful as a plain bullet list. - -### First-Time Setup -If the render script hasn't been set up yet: -```bash -cd .claude/skills/excalidraw-pr-diagrams/references -uv sync -uv run playwright install chromium -``` - -For Codex installs, use `.codex/skills/excalidraw-pr-diagrams/references`. - ---- - -## Quality Checklist - -### Depth & Evidence (Check First for Technical Diagrams) -1. **Research done**: Did you look up actual specs, formats, event names? -2. **Evidence artifacts**: Are there code snippets, JSON examples, or real data? -3. **Multi-zoom**: Does it have summary flow + section boundaries + detail? -4. **Concrete over abstract**: Real content shown, not just labeled boxes? -5. **Educational value**: Could someone learn something concrete from this? - -### Conceptual -6. **Isomorphism**: Does each visual structure mirror its concept's behavior? -7. **Argument**: Does the diagram SHOW something text alone couldn't? -8. **Variety**: Does each major concept use a different visual pattern? -9. **No uniform containers**: Avoided card grids and equal boxes? -10. **Non-redundant**: The image is not just the PR description repeated in boxes. -11. **Before/after story**: The old failure path and new success path are visibly different. -12. **Metaphor fit**: The chosen metaphor matches the change type (boundary, lifecycle, race, permission, ownership, etc.). - -### Container Discipline -13. **Minimal containers**: Could any boxed element work as free-floating text instead? -14. **Lines as structure**: Are tree/timeline patterns using lines + text rather than boxes? -15. **Typography hierarchy**: Are font size and color creating visual hierarchy (reducing need for boxes)? - -### Structural -16. **Connections**: Every relationship has an arrow or line -17. **Flow**: Clear visual path for the eye to follow -18. **Hierarchy**: Important elements are larger/more isolated - -### Technical -19. **Text clean**: `text` contains only readable words -20. **Font**: `fontFamily: 3` -21. **Roughness**: `roughness: 0` for clean/modern (unless hand-drawn style requested) -22. **Opacity**: `opacity: 100` for all elements (no transparency) -23. **Container ratio**: <30% of text elements should be inside containers - -### Visual Validation (Render Required) -24. **Rendered to PNG**: Diagram has been rendered and visually inspected -25. **No text overflow**: All text fits within its container -26. **No clipping**: Screenshot bounds include every title, label, arrow, and shape -27. **No overlapping elements**: Shapes and text don't overlap unintentionally -28. **Even spacing**: Similar elements have consistent spacing -29. **Arrows land correctly**: Arrows connect to intended elements without crossing others -30. **Readable at export size**: Text is legible in the rendered PNG -31. **Balanced composition**: No large empty voids or overcrowded regions -32. **GitHub readable**: The image is understandable when embedded in a PR without opening it full-size diff --git a/tyler/.claude/skills/excalidraw-pr-diagrams/references/color-palette.md b/tyler/.claude/skills/excalidraw-pr-diagrams/references/color-palette.md deleted file mode 100644 index 711ea27..0000000 --- a/tyler/.claude/skills/excalidraw-pr-diagrams/references/color-palette.md +++ /dev/null @@ -1,67 +0,0 @@ -# Color Palette & Brand Style - -**This is the single source of truth for all colors and brand-specific styles.** To customize diagrams for your own brand, edit this file — everything else in the skill is universal. - ---- - -## Shape Colors (Semantic) - -Colors encode meaning, not decoration. Each semantic purpose has a fill/stroke pair. - -| Semantic Purpose | Fill | Stroke | -|------------------|------|--------| -| Primary/Neutral | `#3b82f6` | `#1e3a5f` | -| Secondary | `#60a5fa` | `#1e3a5f` | -| Tertiary | `#93c5fd` | `#1e3a5f` | -| Start/Trigger | `#fed7aa` | `#c2410c` | -| End/Success | `#a7f3d0` | `#047857` | -| Warning/Reset | `#fee2e2` | `#dc2626` | -| Decision | `#fef3c7` | `#b45309` | -| AI/LLM | `#ddd6fe` | `#6d28d9` | -| Inactive/Disabled | `#dbeafe` | `#1e40af` (use dashed stroke) | -| Error | `#fecaca` | `#b91c1c` | - -**Rule**: Always pair a darker stroke with a lighter fill for contrast. - ---- - -## Text Colors (Hierarchy) - -Use color on free-floating text to create visual hierarchy without containers. - -| Level | Color | Use For | -|-------|-------|---------| -| Title | `#1e40af` | Section headings, major labels | -| Subtitle | `#3b82f6` | Subheadings, secondary labels | -| Body/Detail | `#64748b` | Descriptions, annotations, metadata | -| On light fills | `#374151` | Text inside light-colored shapes | -| On dark fills | `#ffffff` | Text inside dark-colored shapes | - ---- - -## Evidence Artifact Colors - -Used for code snippets, data examples, and other concrete evidence inside technical diagrams. - -| Artifact | Background | Text Color | -|----------|-----------|------------| -| Code snippet | `#1e293b` | Syntax-colored (language-appropriate) | -| JSON/data example | `#1e293b` | `#22c55e` (green) | - ---- - -## Default Stroke & Line Colors - -| Element | Color | -|---------|-------| -| Arrows | Use the stroke color of the source element's semantic purpose | -| Structural lines (dividers, trees, timelines) | Primary stroke (`#1e3a5f`) or Slate (`#64748b`) | -| Marker dots (fill + stroke) | Primary fill (`#3b82f6`) | - ---- - -## Background - -| Property | Value | -|----------|-------| -| Canvas background | `#ffffff` | diff --git a/tyler/.claude/skills/excalidraw-pr-diagrams/references/element-templates.md b/tyler/.claude/skills/excalidraw-pr-diagrams/references/element-templates.md deleted file mode 100644 index 30dbf4a..0000000 --- a/tyler/.claude/skills/excalidraw-pr-diagrams/references/element-templates.md +++ /dev/null @@ -1,182 +0,0 @@ -# Element Templates - -Copy-paste JSON templates for each Excalidraw element type. The `strokeColor` and `backgroundColor` values are placeholders — always pull actual colors from `color-palette.md` based on the element's semantic purpose. - -## Free-Floating Text (no container) -```json -{ - "type": "text", - "id": "label1", - "x": 100, "y": 100, - "width": 200, "height": 25, - "text": "Section Title", - "originalText": "Section Title", - "fontSize": 20, - "fontFamily": 3, - "textAlign": "left", - "verticalAlign": "top", - "strokeColor": "<title color from palette>", - "backgroundColor": "transparent", - "fillStyle": "solid", - "strokeWidth": 1, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "seed": 11111, - "version": 1, - "versionNonce": 22222, - "isDeleted": false, - "groupIds": [], - "boundElements": null, - "link": null, - "locked": false, - "containerId": null, - "lineHeight": 1.25 -} -``` - -## Line (structural, not arrow) -```json -{ - "type": "line", - "id": "line1", - "x": 100, "y": 100, - "width": 0, "height": 200, - "strokeColor": "<structural line color from palette>", - "backgroundColor": "transparent", - "fillStyle": "solid", - "strokeWidth": 2, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "seed": 44444, - "version": 1, - "versionNonce": 55555, - "isDeleted": false, - "groupIds": [], - "boundElements": null, - "link": null, - "locked": false, - "points": [[0, 0], [0, 200]] -} -``` - -## Small Marker Dot -```json -{ - "type": "ellipse", - "id": "dot1", - "x": 94, "y": 94, - "width": 12, "height": 12, - "strokeColor": "<marker dot color from palette>", - "backgroundColor": "<marker dot color from palette>", - "fillStyle": "solid", - "strokeWidth": 1, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "seed": 66666, - "version": 1, - "versionNonce": 77777, - "isDeleted": false, - "groupIds": [], - "boundElements": null, - "link": null, - "locked": false -} -``` - -## Rectangle -```json -{ - "type": "rectangle", - "id": "elem1", - "x": 100, "y": 100, "width": 180, "height": 90, - "strokeColor": "<stroke from palette based on semantic purpose>", - "backgroundColor": "<fill from palette based on semantic purpose>", - "fillStyle": "solid", - "strokeWidth": 2, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "seed": 12345, - "version": 1, - "versionNonce": 67890, - "isDeleted": false, - "groupIds": [], - "boundElements": [{"id": "text1", "type": "text"}], - "link": null, - "locked": false, - "roundness": {"type": 3} -} -``` - -## Text (centered in shape) -```json -{ - "type": "text", - "id": "text1", - "x": 130, "y": 132, - "width": 120, "height": 25, - "text": "Process", - "originalText": "Process", - "fontSize": 16, - "fontFamily": 3, - "textAlign": "center", - "verticalAlign": "middle", - "strokeColor": "<text color — match parent shape's stroke or use 'on light/dark fills' from palette>", - "backgroundColor": "transparent", - "fillStyle": "solid", - "strokeWidth": 1, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "seed": 11111, - "version": 1, - "versionNonce": 22222, - "isDeleted": false, - "groupIds": [], - "boundElements": null, - "link": null, - "locked": false, - "containerId": "elem1", - "lineHeight": 1.25 -} -``` - -## Arrow -```json -{ - "type": "arrow", - "id": "arrow1", - "x": 282, "y": 145, "width": 118, "height": 0, - "strokeColor": "<arrow color — typically matches source element's stroke from palette>", - "backgroundColor": "transparent", - "fillStyle": "solid", - "strokeWidth": 2, - "strokeStyle": "solid", - "roughness": 0, - "opacity": 100, - "angle": 0, - "seed": 33333, - "version": 1, - "versionNonce": 44444, - "isDeleted": false, - "groupIds": [], - "boundElements": null, - "link": null, - "locked": false, - "points": [[0, 0], [118, 0]], - "startBinding": {"elementId": "elem1", "focus": 0, "gap": 2}, - "endBinding": {"elementId": "elem2", "focus": 0, "gap": 2}, - "startArrowhead": null, - "endArrowhead": "arrow" -} -``` - -For curves: use 3+ points in `points` array. diff --git a/tyler/.claude/skills/excalidraw-pr-diagrams/references/json-schema.md b/tyler/.claude/skills/excalidraw-pr-diagrams/references/json-schema.md deleted file mode 100644 index 60383bb..0000000 --- a/tyler/.claude/skills/excalidraw-pr-diagrams/references/json-schema.md +++ /dev/null @@ -1,71 +0,0 @@ -# Excalidraw JSON Schema - -## Element Types - -| Type | Use For | -|------|---------| -| `rectangle` | Processes, actions, components | -| `ellipse` | Entry/exit points, external systems | -| `diamond` | Decisions, conditionals | -| `arrow` | Connections between shapes | -| `text` | Labels inside shapes | -| `line` | Non-arrow connections | -| `frame` | Grouping containers | - -## Common Properties - -All elements share these: - -| Property | Type | Description | -|----------|------|-------------| -| `id` | string | Unique identifier | -| `type` | string | Element type | -| `x`, `y` | number | Position in pixels | -| `width`, `height` | number | Size in pixels | -| `strokeColor` | string | Border color (hex) | -| `backgroundColor` | string | Fill color (hex or "transparent") | -| `fillStyle` | string | "solid", "hachure", "cross-hatch" | -| `strokeWidth` | number | 1, 2, or 4 | -| `strokeStyle` | string | "solid", "dashed", "dotted" | -| `roughness` | number | 0 (smooth), 1 (default), 2 (rough) | -| `opacity` | number | 0-100 | -| `seed` | number | Random seed for roughness | - -## Text-Specific Properties - -| Property | Description | -|----------|-------------| -| `text` | The display text | -| `originalText` | Same as text | -| `fontSize` | Size in pixels (16-20 recommended) | -| `fontFamily` | 3 for monospace (use this) | -| `textAlign` | "left", "center", "right" | -| `verticalAlign` | "top", "middle", "bottom" | -| `containerId` | ID of parent shape | - -## Arrow-Specific Properties - -| Property | Description | -|----------|-------------| -| `points` | Array of [x, y] coordinates | -| `startBinding` | Connection to start shape | -| `endBinding` | Connection to end shape | -| `startArrowhead` | null, "arrow", "bar", "dot", "triangle" | -| `endArrowhead` | null, "arrow", "bar", "dot", "triangle" | - -## Binding Format - -```json -{ - "elementId": "shapeId", - "focus": 0, - "gap": 2 -} -``` - -## Rectangle Roundness - -Add for rounded corners: -```json -"roundness": { "type": 3 } -``` diff --git a/tyler/.claude/skills/excalidraw-pr-diagrams/references/pyproject.toml b/tyler/.claude/skills/excalidraw-pr-diagrams/references/pyproject.toml deleted file mode 100644 index d88119e..0000000 --- a/tyler/.claude/skills/excalidraw-pr-diagrams/references/pyproject.toml +++ /dev/null @@ -1,7 +0,0 @@ -[project] -name = "excalidraw-render" -version = "0.1.0" -requires-python = ">=3.11" -dependencies = [ - "playwright>=1.40.0", -] diff --git a/tyler/.claude/skills/excalidraw-pr-diagrams/references/render_excalidraw.py b/tyler/.claude/skills/excalidraw-pr-diagrams/references/render_excalidraw.py deleted file mode 100644 index b8431ec..0000000 --- a/tyler/.claude/skills/excalidraw-pr-diagrams/references/render_excalidraw.py +++ /dev/null @@ -1,189 +0,0 @@ -"""Render Excalidraw JSON to PNG using Playwright + headless Chromium. - -Usage: - cd .claude/skills/excalidraw-pr-diagrams/references - uv run python render_excalidraw.py <path-to-file.excalidraw> [--output path.png] [--scale 2] [--width 1920] - -First-time setup: - cd .claude/skills/excalidraw-pr-diagrams/references - uv sync - uv run playwright install chromium -""" - -from __future__ import annotations - -import argparse -import json -import sys -from pathlib import Path - - -def validate_excalidraw(data: dict) -> list[str]: - """Validate Excalidraw JSON structure. Returns list of errors (empty = valid).""" - errors: list[str] = [] - - if data.get("type") != "excalidraw": - errors.append(f"Expected type 'excalidraw', got '{data.get('type')}'") - - if "elements" not in data: - errors.append("Missing 'elements' array") - elif not isinstance(data["elements"], list): - errors.append("'elements' must be an array") - elif len(data["elements"]) == 0: - errors.append("'elements' array is empty — nothing to render") - - return errors - - -def compute_bounding_box(elements: list[dict]) -> tuple[float, float, float, float]: - """Compute bounding box (min_x, min_y, max_x, max_y) across all elements.""" - min_x = float("inf") - min_y = float("inf") - max_x = float("-inf") - max_y = float("-inf") - - for el in elements: - if el.get("isDeleted"): - continue - x = el.get("x", 0) - y = el.get("y", 0) - w = el.get("width", 0) - h = el.get("height", 0) - - # For arrows/lines, points array defines the shape relative to x,y - if el.get("type") in ("arrow", "line") and "points" in el: - for px, py in el["points"]: - min_x = min(min_x, x + px) - min_y = min(min_y, y + py) - max_x = max(max_x, x + px) - max_y = max(max_y, y + py) - else: - min_x = min(min_x, x) - min_y = min(min_y, y) - max_x = max(max_x, x + abs(w)) - max_y = max(max_y, y + abs(h)) - - if min_x == float("inf"): - return (0, 0, 800, 600) - - return (min_x, min_y, max_x, max_y) - - -def render( - excalidraw_path: Path, - output_path: Path | None = None, - scale: int = 2, - max_width: int = 1920, -) -> Path: - """Render an .excalidraw file to PNG. Returns the output PNG path.""" - # Import playwright here so validation errors show before import errors - try: - from playwright.sync_api import sync_playwright - except ImportError: - print("ERROR: playwright not installed.", file=sys.stderr) - print("Run: cd .claude/skills/excalidraw-pr-diagrams/references && uv sync && uv run playwright install chromium", file=sys.stderr) - sys.exit(1) - - # Read and validate - raw = excalidraw_path.read_text(encoding="utf-8") - try: - data = json.loads(raw) - except json.JSONDecodeError as e: - print(f"ERROR: Invalid JSON in {excalidraw_path}: {e}", file=sys.stderr) - sys.exit(1) - - errors = validate_excalidraw(data) - if errors: - print(f"ERROR: Invalid Excalidraw file:", file=sys.stderr) - for err in errors: - print(f" - {err}", file=sys.stderr) - sys.exit(1) - - # Compute viewport size from element bounding box - elements = [e for e in data["elements"] if not e.get("isDeleted")] - min_x, min_y, max_x, max_y = compute_bounding_box(elements) - padding = 80 - diagram_w = max_x - min_x + padding * 2 - diagram_h = max_y - min_y + padding * 2 - - # Cap viewport width, let height be natural - vp_width = min(int(diagram_w), max_width) - vp_height = max(int(diagram_h), 600) - - # Output path - if output_path is None: - output_path = excalidraw_path.with_suffix(".png") - - # Template path (same directory as this script) - template_path = Path(__file__).parent / "render_template.html" - if not template_path.exists(): - print(f"ERROR: Template not found at {template_path}", file=sys.stderr) - sys.exit(1) - - template_url = template_path.as_uri() - - with sync_playwright() as p: - try: - browser = p.chromium.launch(headless=True) - except Exception as e: - if "Executable doesn't exist" in str(e) or "browserType.launch" in str(e): - print("ERROR: Chromium not installed for Playwright.", file=sys.stderr) - print("Run: cd .claude/skills/excalidraw-pr-diagrams/references && uv run playwright install chromium", file=sys.stderr) - sys.exit(1) - raise - - page = browser.new_page( - viewport={"width": vp_width, "height": vp_height}, - device_scale_factor=scale, - ) - - # Load the template - page.goto(template_url) - - # Wait for the ES module to load (imports from esm.sh) - page.wait_for_function("window.__moduleReady === true", timeout=30000) - - # Inject the diagram data and render - json_str = json.dumps(data) - result = page.evaluate(f"window.renderDiagram({json_str})") - - if not result or not result.get("success"): - error_msg = result.get("error", "Unknown render error") if result else "renderDiagram returned null" - print(f"ERROR: Render failed: {error_msg}", file=sys.stderr) - browser.close() - sys.exit(1) - - # Wait for render completion signal - page.wait_for_function("window.__renderComplete === true", timeout=15000) - - # Screenshot the SVG element - svg_el = page.query_selector("#root svg") - if svg_el is None: - print("ERROR: No SVG element found after render.", file=sys.stderr) - browser.close() - sys.exit(1) - - svg_el.screenshot(path=str(output_path)) - browser.close() - - return output_path - - -def main() -> None: - parser = argparse.ArgumentParser(description="Render Excalidraw JSON to PNG") - parser.add_argument("input", type=Path, help="Path to .excalidraw JSON file") - parser.add_argument("--output", "-o", type=Path, default=None, help="Output PNG path (default: same name with .png)") - parser.add_argument("--scale", "-s", type=int, default=2, help="Device scale factor (default: 2)") - parser.add_argument("--width", "-w", type=int, default=1920, help="Max viewport width (default: 1920)") - args = parser.parse_args() - - if not args.input.exists(): - print(f"ERROR: File not found: {args.input}", file=sys.stderr) - sys.exit(1) - - png_path = render(args.input, args.output, args.scale, args.width) - print(str(png_path)) - - -if __name__ == "__main__": - main() diff --git a/tyler/.claude/skills/excalidraw-pr-diagrams/references/render_template.html b/tyler/.claude/skills/excalidraw-pr-diagrams/references/render_template.html deleted file mode 100644 index 877e33d..0000000 --- a/tyler/.claude/skills/excalidraw-pr-diagrams/references/render_template.html +++ /dev/null @@ -1,57 +0,0 @@ -<!DOCTYPE html> -<html> -<head> - <meta charset="utf-8" /> - <style> - * { margin: 0; padding: 0; box-sizing: border-box; } - body { background: #ffffff; overflow: hidden; } - #root { display: inline-block; } - #root svg { display: block; } - </style> -</head> -<body> - <div id="root"></div> - - <script type="module"> - import { exportToSvg } from "https://esm.sh/@excalidraw/excalidraw@0.18.0?bundle"; - - window.renderDiagram = async function(jsonData) { - try { - const data = typeof jsonData === "string" ? JSON.parse(jsonData) : jsonData; - const elements = data.elements || []; - const appState = data.appState || {}; - const files = data.files || {}; - - // Force white background in appState - appState.viewBackgroundColor = appState.viewBackgroundColor || "#ffffff"; - appState.exportWithDarkMode = false; - - const svg = await exportToSvg({ - elements: elements, - appState: { - ...appState, - exportBackground: true, - }, - files: files, - }); - - // Clear any previous render - const root = document.getElementById("root"); - root.innerHTML = ""; - root.appendChild(svg); - - window.__renderComplete = true; - window.__renderError = null; - return { success: true, width: svg.getAttribute("width"), height: svg.getAttribute("height") }; - } catch (err) { - window.__renderComplete = true; - window.__renderError = err.message; - return { success: false, error: err.message }; - } - }; - - // Signal that the module is loaded and ready - window.__moduleReady = true; - </script> -</body> -</html> diff --git a/tyler/.claude/skills/notion/SKILL.md b/tyler/.claude/skills/notion/SKILL.md deleted file mode 100644 index 18ca4e7..0000000 --- a/tyler/.claude/skills/notion/SKILL.md +++ /dev/null @@ -1,114 +0,0 @@ ---- -name: notion -description: The Notion bridge for work items — creates a Notion work item mirroring a GitHub issue, uploads artifacts (item.md, refs/, plan.md, wrapup.md) to it, and pulls a work item's artifacts down to ./tmp/<id>/. Used by /create-feature, /create-epic, /create-issue (publish) and /do (pull before work, upload after). Use when a work item needs to be published to, updated in, or fetched from Notion. -argument-hint: "[publish|upload|pull] [work-item id, GitHub issue #/URL, or Notion page URL]" ---- - -# Notion bridge - -## Request: $ARGUMENTS - -Notion is the durable home for work-item artifacts; GitHub carries the issue -and the PR; `./tmp/<id>/` is the local working copy. This skill is the one -place that knows how to move material between the three. One invocation = one -operation: `publish`, `upload`, or `pull`. - -## Setup (every invocation) - -1. **Load the Notion tools**: use ToolSearch with a query like - `+notion search create fetch update attachment` and load what the - operation needs (search, fetch, create-pages, update-page, - create-attachment). Tool names vary by connector — match on the `notion` - prefix. If no Notion tools resolve and no `notion` CLI is on PATH, return - `NOTION UNAVAILABLE: <what was tried>` — the caller proceeds - GitHub + local only and says so. -2. **Find the target database** — resolution order, most specific wins: - 1. The project `CLAUDE.md`'s `Work-item tracking` section - (`notion_data_source`) — per-repo override only. - 2. `config.yaml` in this skill's directory — the global default; also - defines the database's property names. - 3. Neither set → search Notion for the work-items database once, confirm - the match with the user, and offer to save it into this skill's - `config.yaml` so the search never repeats. - -**Success criteria**: tools loaded and a data source resolved (or an explicit -`NOTION UNAVAILABLE`). - -## Operation: publish (called by /create-feature, /create-epic, /create-issue) - -Inputs: `./tmp/<id>/` with a ready `item.md`, plus the GitHub issue URL the -caller just created. - -1. Dedup first: query the data source for a page whose GitHub-issue-URL - property equals this issue — an exact property query, not workspace - full-text search. Found → this publish updates that page in place. -2. Create (or update) one page in the work-items data source: - - Title: the item's title (same as the GitHub issue title). - - Properties (as the database schema allows): GitHub issue URL, work-item - type (`feature-ticket | epic-spec | bug-report`), status `ready`. - - Page body: the full `item.md` content — the human-readable mirror. -3. Upload every file in `./tmp/<id>/refs/` to the page (attachments for - binaries, sub-pages for markdown), named as on disk. Also write the RAW - bytes of `item.md` and each markdown ref to a sub-page named - `raw/<name>` whose entire content is one fenced code block: Notion - re-renders page bodies (tables, checkboxes, frontmatter fences all - mutate) but never touches code-block contents. Don't rely on file - attachments for this — Notion serves them as expiring, integration-scoped - URLs, so another session's pull 404s on them. -4. Return the new page URL to the caller — the caller cross-links it in both - directions: append the canonical line `**Notion:** <page URL>` to the end - of the GitHub issue body (`gh issue edit --body-file`), and write the URL - into `item.md`'s frontmatter as `notion:`. When publish runs ad hoc (no - calling skill), do both edits as part of this operation. The exact - `**Notion:**` line format matters — `pull` looks for it. - -**Success criteria**: page exists with the item body and every `refs/` file; -page URL returned. - -## Operation: upload (called by /do at wrap-up, or ad hoc) - -Inputs: the work item's Notion page URL (from `item.md` frontmatter or the -GitHub issue body) and the files to add (`plan.md`, `wrapup.md`, new refs). - -1. Add each file to the page as in publish step 2 — update in place if a - sub-page with the same name exists (a re-run replaces, never duplicates). -2. Update the page's status property to match `item.md` (`done` after a - successful `/do`), and add the PR URL if provided. - -**Success criteria**: every input file visible on the page; status/PR current. - -## Operation: pull (called by /do before work) - -Inputs: a GitHub issue number/URL or a Notion page URL. - -1. If given a GitHub issue: `gh issue view` and find the canonical - `**Notion:** <url>` line in its body (fall back to any Notion page URL - found anywhere in the body). No Notion link → return `NO NOTION ITEM` - (the caller falls back to treating the issue body itself as the work - item). -2. Fetch the page. Derive `<id>` from the item's frontmatter `id:` (or slug - the title). Prefer the `raw/item.md` code-block sub-page when present — - its contents are byte-identical to what was published; reconstruct from - the rendered page body only when no raw sub-page exists. Treat file- - attachment 404s as normal (expiring, integration-scoped URLs), never as - an error worth stopping for. -3. Fetch every sub-page and attachment; save each to `./tmp/<id>/refs/<name>` - (same preference: `raw/<name>` code block over rendered sub-page). If a - plan from a prior run exists, save it as `./tmp/<id>/plan.md`. A local - `./tmp/<id>/` that already exists wins over anything fetched — disk is - the working truth; only fill gaps. -4. Set the page's status property to `in-progress` — the database stays an - honest at-a-glance board while `/do` runs (`upload` flips it to `done`). -5. Return the local paths written. - -**Success criteria**: `./tmp/<id>/item.md` exists locally and every artifact -on the page has a local copy under `./tmp/<id>/`. - -## Rules - -- Notion is the mirror, `item.md` on disk is the working truth during a run — - push at milestones (publish, wrap-up), don't sync continuously. -- Never store secrets in Notion pages; artifacts only. -- One work item = one page. Dedup by exact GitHub-issue-URL property query - against the data source (workspace full-text search only as a fallback) — - re-publishing must update, not duplicate. diff --git a/tyler/.claude/skills/notion/config.yaml b/tyler/.claude/skills/notion/config.yaml deleted file mode 100644 index 8419741..0000000 --- a/tyler/.claude/skills/notion/config.yaml +++ /dev/null @@ -1,11 +0,0 @@ -# Default target for work items — the notion skill's global config. -# A project's CLAUDE.md "Work-item tracking" section overrides this per repo. -# Fill notion_data_source with the data source ID or URL of the work-items -# database (the skill offers to fill it after its first search-and-confirm). -notion_data_source: "collection://f71e2393-ba30-4286-a883-6c22fdee6060" # Orchestra - Software Factory Tasks -# Property names on the database, if they differ from these defaults: -properties: - github_issue: "GitHub Issue" - type: "Type" - status: "Status" - pr: "PR" diff --git a/tyler/.claude/skills/postmortem/SKILL.md b/tyler/.claude/skills/postmortem/SKILL.md deleted file mode 100644 index 08ccc80..0000000 --- a/tyler/.claude/skills/postmortem/SKILL.md +++ /dev/null @@ -1,84 +0,0 @@ ---- -name: postmortem -description: Runs a postmortem after /do finished and the human reviewed the PR, when the result fell short of intent. Use when the user says a /do run missed the mark, the PR needed rework, the delivered feature didn't match the ticket, or asks "why did /do get this wrong" — or when any workflow skill (/discussion, /create-*) produced the wrong outcome. Root-causes the gap in our system and proposes one concrete improvement. -argument-hint: "[PR url/# or work-item id]" ---- - -# Postmortem - -## Target: $ARGUMENTS - -Compound learning: when a `/do` run fell short of intent — or another workflow -skill produced the wrong outcome (a ticket the gate should have killed, a skill -that fired at the wrong moment) — find the root cause in **our system** — the -skills, agents, templates, and criteria — not just the code. The completion -artifact is `./tmp/<id>/postmortem.md` plus one proposed (not applied) system change. - -This skill changes nothing: no code fixes, no skill edits. If the code itself needs -fixing, that goes through `/create-issue` then `/do`; the proposed system change is -presented for the human to approve, not applied. - -## Steps - -### 1. Load the record -Resolve `<id>` from $ARGUMENTS (a work-item id directly, or match a PR to the `pr:` field -across `./tmp/*/item.md`). Then read: -- `./tmp/<id>/item.md` — what we asked for -- `./tmp/<id>/plan.md` — what `/do` planned -- `./tmp/<id>/wrapup.md` — what `/do` claims it delivered and verified -- PR feedback — `gh pr view <pr> --comments` and the review threads, or ask the user to - paste it if it lives outside GitHub - -**Success criteria**: all four sources loaded (or their absence noted — a missing wrapup -is itself a finding). - -### 2. Establish the gap [human] -Discuss with the human what fell short: delivered vs intended, concretely. Anchor on the -item's intent and ACs — did `/do` miss the ticket, or did the ticket miss the intent? - -**Success criteria**: the gap is stated in one or two concrete sentences the human agrees -with. - -### 3. Root-cause it in OUR system -Trace the gap upstream through the pipeline and name where it entered: -- **Thin ticket** — intent or end state under-specified, so `/do` optimized the wrong thing -- **Weak AC** — verification criteria passed while the intent failed (untestable or - mis-aimed criteria) -- **Missing direction** — a decision the model shouldn't have made alone wasn't locked -- **Review blind spot** — a reviewer should have caught it and the report shows it didn't -- **Skill/agent gap** — a pipeline stage lacks an instruction this failure needed - -The code defect (if any) is a symptom here. Note it, and route the fix through -`/create-issue` then `/do` — not this skill. - -**Success criteria**: one primary system-level cause identified, with evidence from the -step-1 documents (quote the thin section, the weak AC, the review miss). - -### 4. Write the postmortem -Write `./tmp/<id>/postmortem.md` following this skill's `references/postmortem.md` — -emit the filled-in frontmatter and body only; the template's "— format" header and -guidance quotes are authoring notes, not output. - -**Success criteria**: `postmortem.md` exists and the "why the gap happened" section names -the system cause, not just the code defect. - -### 5. Propose ONE system change [human checkpoint] -Propose exactly one concrete change to one specific file — a skill, sub-agent, template, -or criteria block, named by its path in the skills repo (`dcouple/skills`, under -`tyler/` — e.g. `tyler/.claude/skills/discussion/SKILL.md`, -`tyler/references/verification-criteria.md`, `tyler/.claude/agents/code-reviewer.md`). -The synced copies under `~/.claude` and `~/.references` are mirrors — the edit lands in -the repo and re-syncs. Quote the file path and show the proposed edit. - -Do **not** apply it. Present it for the human to approve; record the proposal (and the -verdict, if given now) in postmortem.md's "What to change so it doesn't recur" section. -One change per postmortem — the highest-leverage one — so each fix is attributable. - -**Success criteria**: proposal names an exact file and shows the concrete edit; nothing -outside `./tmp/<id>/` was modified. - -``` -Suggested next steps: -- `/create-issue [defect]` then `/do ./tmp/<id>/item.md` — fix the code gap itself -- Apply the approved system change in a normal editing session, then commit it -``` diff --git a/tyler/.claude/skills/postmortem/references/postmortem.md b/tyler/.claude/skills/postmortem/references/postmortem.md deleted file mode 100644 index 9073db1..0000000 --- a/tyler/.claude/skills/postmortem/references/postmortem.md +++ /dev/null @@ -1,33 +0,0 @@ -# Postmortem — format - -> Produced by `/postmortem` after `/do` finishes and the human reviews the PR, when the -> result fell short of intent. Saved as `./tmp/<id>/postmortem.md` (local for now). -> The point is **compound learning**: fix the root cause in *our system* (skill / agent / -> template / criteria), so the same gap can't recur. - ---- -```yaml ---- -type: postmortem -item: <id> -pr: <url or #> ---- -``` - -# Postmortem — `<item>` - -## What we asked for -`<the intent + desired end state, briefly>` - -## What `/do` delivered vs intended -`<the gap the human found on PR review — concrete>` - -## Why the gap happened -`<root cause in OUR system, not just the code: was it a thin ticket? a weak verification` -`criterion? a review blind spot? a missing architecture direction?>` - -## What to change so it doesn't recur -`<a concrete improvement to a specific skill / sub-agent / template / verification block>` - -## System change (deferred) -`<future: open a GitHub issue against dcouple/skills carrying this note. Off for now.>` diff --git a/tyler/.codex/skills/backend-verifier/SKILL.md b/tyler/.codex/skills/backend-verifier/SKILL.md deleted file mode 100644 index b28bd5b..0000000 --- a/tyler/.codex/skills/backend-verifier/SKILL.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -name: backend-verifier -description: "Backend-verifier role in an automated development pipeline: proves backend verification criteria by running the mapped tests, scripts, and commands with quoted evidence. Use when dispatched to verify implemented work." ---- - -# Backend Verifier - -You are a backend verifier in an automated software-development pipeline. The Overseer — a separate -orchestrating agent — dispatched you (GPT-5.6, effort `medium`, -workspace-write sandbox — for running tests and scripts only) with numbered -verification criteria; your report goes back to the Overseer, not to a human. - -This skill is a pointer, not the full instructions — there is exactly one -copy of each document: - -1. Read your role instructions at - `~/.references/agents/backend-verifier/instructions.md`. -2. Read your output format at - `~/.references/agents/frontend-verifier/verification-result.md` and return - your result in exactly the verify-mode format. - -If either file is missing, report that and stop — do not improvise the role. diff --git a/tyler/.codex/skills/code-researcher/SKILL.md b/tyler/.codex/skills/code-researcher/SKILL.md deleted file mode 100644 index e241139..0000000 --- a/tyler/.codex/skills/code-researcher/SKILL.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -name: code-researcher -description: "Code-researcher role in an automated development pipeline: explores the codebase and returns current-state facts with precise file:line references. Use when dispatched to answer a question about what exists in the repo." ---- - -# Code Researcher - -You are a codebase researcher in an automated software-development pipeline. -The Overseer — a separate orchestrating agent — dispatched you (GPT-5.6, effort `medium`, -read-only sandbox) with a focused question about the repository; it plans -against your findings, so what you didn't find is as load-bearing as what you -did. Your report goes back to the Overseer, not to a human. - -This skill is a pointer, not the full instructions — there is exactly one -copy of each document: - -1. Read your role instructions at `~/.claude/agents/code-researcher.md`. - Follow the body; ignore the YAML frontmatter (it applies to a different - harness). -2. Read your output format at - `~/.references/agents/code-researcher/codebase-findings.md` and return - your findings in exactly that format. - -If either file is missing, report that and stop — do not improvise the role. diff --git a/tyler/.codex/skills/code-researcher/agents/openai.yaml b/tyler/.codex/skills/code-researcher/agents/openai.yaml deleted file mode 100644 index 7a4c102..0000000 --- a/tyler/.codex/skills/code-researcher/agents/openai.yaml +++ /dev/null @@ -1,4 +0,0 @@ -interface: - display_name: "Code Researcher" - short_description: "Explore the codebase; file:line findings, bottom line first" - default_prompt: "Use $code-researcher to answer the codebase question you are given with precise file:line references." diff --git a/tyler/.codex/skills/code-reviewer/SKILL.md b/tyler/.codex/skills/code-reviewer/SKILL.md deleted file mode 100644 index 5079ca5..0000000 --- a/tyler/.codex/skills/code-reviewer/SKILL.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -name: code-reviewer -description: "Code-reviewer role in an automated development pipeline: reviews the diff for correctness and security with file:line evidence. Use when dispatched to review an implementation." ---- - -# Code Reviewer - -You are a code reviewer in an automated software-development pipeline. The Overseer — a separate -orchestrating agent — dispatched you (GPT-5.6, effort `xhigh`, -read-only sandbox) with a work item, a plan, and a pass number; you read the -diff cold, and your Must Fix findings are fixed by the implementer and -re-reviewed until zero remain (cap 3 passes; /do's light lane caps at 1). The security review is part of -your job — tag those findings `(security)`. Your report goes back to the Overseer, not to a human. - -This skill is a pointer, not the full instructions — there is exactly one -copy of each document: - -1. Read your role instructions at `~/.claude/agents/code-reviewer.md`. - Follow the body; ignore the YAML frontmatter (it applies to a different - harness). -2. Read your output format at - `~/.references/agents/code-reviewer/review-report.md` and return your - findings in exactly that format. - -If either file is missing, report that and stop — do not improvise the role. diff --git a/tyler/.codex/skills/code-reviewer/agents/openai.yaml b/tyler/.codex/skills/code-reviewer/agents/openai.yaml deleted file mode 100644 index 2b48a8a..0000000 --- a/tyler/.codex/skills/code-reviewer/agents/openai.yaml +++ /dev/null @@ -1,4 +0,0 @@ -interface: - display_name: "Code Reviewer" - short_description: "Review the diff for correctness + security; verdict-first report" - default_prompt: "Use $code-reviewer to review the implementation diff against its plan and work item." diff --git a/tyler/.codex/skills/implementer/SKILL.md b/tyler/.codex/skills/implementer/SKILL.md deleted file mode 100644 index 71a165e..0000000 --- a/tyler/.codex/skills/implementer/SKILL.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -name: implementer -description: "Implementer role in an automated development pipeline: executes an Implementation Plan (plan.md), writing the diff while keeping the plan file true. Use when dispatched to implement a plan or apply review fixes." ---- - -# Implementer - -You are the implementer in an automated software-development pipeline. The Overseer — a separate -orchestrating agent — dispatched you (GPT-5.6, effort `medium`, -workspace-write sandbox) with an Implementation Plan and a work item; your -report goes back to the Overseer, not to a human. - -This skill is a pointer, not the full instructions — there is exactly one -copy of each document: - -1. Read your role instructions at - `~/.references/agents/implementer/instructions.md`. -2. Read your output format at - `~/.references/agents/implementer/implementation-result.md` and return - your result in exactly that format. - -If either file is missing, report that and stop — do not improvise the role. diff --git a/tyler/.codex/skills/implementer/agents/openai.yaml b/tyler/.codex/skills/implementer/agents/openai.yaml deleted file mode 100644 index 2acec1d..0000000 --- a/tyler/.codex/skills/implementer/agents/openai.yaml +++ /dev/null @@ -1,4 +0,0 @@ -interface: - display_name: "Implementer" - short_description: "Execute an Implementation Plan and return a status-first result" - default_prompt: "Use $implementer to execute the implementation plan you are given, keeping plan.md true as you work." diff --git a/tyler/.codex/skills/investigator/SKILL.md b/tyler/.codex/skills/investigator/SKILL.md deleted file mode 100644 index ee1c698..0000000 --- a/tyler/.codex/skills/investigator/SKILL.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -name: investigator -description: "Investigator role in an automated development pipeline: reproduces a reported defect and isolates its root cause with evidence. Use when dispatched to diagnose a bug before it's written up." ---- - -# Investigator - -You are a bug investigator in an automated software-development pipeline. The Overseer — a separate -orchestrating agent — dispatched you (GPT-5.6, effort `xhigh`, -workspace-write sandbox — for running tests and repro scripts only) with a -defect report; your finding feeds a Bug Report's root-cause and resolution -sections. Your report goes back to the Overseer, not to a human. - -This skill is a pointer, not the full instructions — there is exactly one -copy of each document: - -1. Read your role instructions at - `~/.references/agents/investigator/instructions.md`. -2. Read your output format at - `~/.references/agents/investigator/root-cause-finding.md` and return your - finding in exactly that format. - -If either file is missing, report that and stop — do not improvise the role. diff --git a/tyler/.codex/skills/investigator/agents/openai.yaml b/tyler/.codex/skills/investigator/agents/openai.yaml deleted file mode 100644 index afa0b5a..0000000 --- a/tyler/.codex/skills/investigator/agents/openai.yaml +++ /dev/null @@ -1,4 +0,0 @@ -interface: - display_name: "Investigator" - short_description: "Reproduce a defect and isolate its root cause with evidence" - default_prompt: "Use $investigator to reproduce and root-cause the defect report you are given." diff --git a/tyler/.codex/skills/plan-reviewer/SKILL.md b/tyler/.codex/skills/plan-reviewer/SKILL.md deleted file mode 100644 index 2e52f08..0000000 --- a/tyler/.codex/skills/plan-reviewer/SKILL.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -name: plan-reviewer -description: "Plan-reviewer role in an automated development pipeline: audits an Implementation Plan for gaps, repo accuracy, and fidelity to the work item. Use when dispatched to review a plan." ---- - -# Plan Reviewer - -You are a plan reviewer in an automated software-development pipeline. The Overseer — a separate -orchestrating agent — dispatched you (GPT-5.6, effort `xhigh`, -read-only sandbox) with a plan, a work item, and a pass number; your Must Fix -findings are fed back into the plan and you re-review until zero remain -(cap 3 passes; /do's light lane caps at 1). Your report goes back to the Overseer, not to a human. - -This skill is a pointer, not the full instructions — there is exactly one -copy of each document: - -1. Read your role instructions at `~/.claude/agents/plan-reviewer.md`. - Follow the body; ignore the YAML frontmatter (it applies to a different - harness). -2. Read your output format at - `~/.references/agents/plan-reviewer/review-report.md` and return your - findings in exactly that format. - -If either file is missing, report that and stop — do not improvise the role. diff --git a/tyler/.codex/skills/plan-reviewer/agents/openai.yaml b/tyler/.codex/skills/plan-reviewer/agents/openai.yaml deleted file mode 100644 index f4678fc..0000000 --- a/tyler/.codex/skills/plan-reviewer/agents/openai.yaml +++ /dev/null @@ -1,4 +0,0 @@ -interface: - display_name: "Plan Reviewer" - short_description: "Audit an Implementation Plan; verdict-first Must/Should/Nice report" - default_prompt: "Use $plan-reviewer to review the implementation plan you are given against its work item." diff --git a/tyler/README.md b/tyler/README.md deleted file mode 100644 index 66a8352..0000000 --- a/tyler/README.md +++ /dev/null @@ -1,157 +0,0 @@ -# tyler - -A dual-harness development workflow (codenamed "Orchestra" in the build plan — -that name stays out of the runtime files so every dispatched model gets plain -definitions). Claude Code is the orchestrating harness: Fable makes the -judgment calls and dispatches sub-agents; Codex (GPT-5.6) runs the -engineering-heavy roles. - -The whole system at a glance: - -![Orchestra workflow map](../docs/tyler-workflow-map.png) - -_Source: [docs/tyler-workflow-map.excalidraw](../docs/tyler-workflow-map.excalidraw)_ - -## The workflow - -The flow separates *clarity*, *capture*, and *execution*: - -1. **`/discussion`** — clarify, understand, figure out. General-purpose: it - dispatches the code-researcher / `web-researcher` for questions and the - investigator (with `frontend-verifier` for reproduction) when the topic is a - defect. It produces clarity plus a dated decision log - (`./tmp/discussions/`) that the `/create-*` drafting step reads — never - deliverables. -2. **`/create-feature` · `/create-epic` · `/create-issue`** — manually invoked - capture skills. Each turns what the conversation established into a lean - work item at `./tmp/<id>/item.md` (Feature Ticket, Epic Spec, or Bug - Report, raw sources in `./tmp/<id>/refs/`) with verification criteria, - then **publishes** it: a GitHub issue in the project repo - plus a Notion work item (via the `notion` skill) holding `item.md` and - every artifact, cross-linked both ways. `/create-issue` runs the - investigator itself if the root cause isn't already established. Before - publish, every draft passes the **Socratic gate**: the `socrates` - sub-agent takes an adversarial position on the item's premise (needed at - all? root cause or symptom? simpler path? right shape? the whole of it?) - and the user's answers — distilled into the item's `## Justification` - section — travel with the GitHub issue. Intensity scales with the item: - straightforward drafts fast-pass with 0–2 questions; epics always get the - full challenge. -3. **`/do <issue # or item path>`** — the autonomous pipeline: pull the work - item's artifacts from Notion into `./tmp/<id>/` (when given a GitHub - issue) → lane call (light/full) → plan + review loop (full lane backed by - a research dossier, every plan under the evidence contract) → implement → - verify → build gate + deploy-notes scan + PR → post-PR review loop + QA - pass over the PR's manual tests → wrap-up, with `plan.md`/`wrapup.md` - uploaded back to the Notion work item at the end. Deliberately high-level: - the Overseer judges the lane, how much research a plan needs, and when - each review loop has converged. -4. **`/postmortem`** — when a result falls short, root-cause it in *our - system* (skill/agent/template), not just the code. - -This table is the single source of truth for model routing — the guides and -skills point here; update it first when routing changes, and update `/do`'s -**Sub-agents** paragraph in the same commit: this README is not synced to -`~`, so the skills' restatement is what actually executes. - -| Role | Runs on | Notes | -| --- | --- | --- | -| Overseer (conducts `/do`, all judgment) | main session — Fable | | -| Web research | Claude `web-researcher` — Sonnet | | -| Verify frontend (drive the running app) | Claude `frontend-verifier` — Sonnet | also reproduces failures for /discussion & /create-issue | -| Verify backend (tests/scripts) | **Codex** GPT-5.6 `medium`, workspace-write | | -| Explore codebase | **Codex** GPT-5.6 `medium`, read-only | Claude `code-researcher` (Sonnet) as backup | -| Reproduce & root-cause | **Codex** GPT-5.6 `xhigh`, workspace-write | | -| Write the diff — backend/ops | **Codex** GPT-5.6 `medium`, workspace-write | | -| Write the diff — frontend web/mobile (UI, styling, client state, user-facing copy) | Claude `frontend-implementer` — Opus | never routed through Codex | -| Challenge the draft work item (Socratic gate) | Claude `socrates` — Opus | always invoked by all three `/create-*`; self-calibrates — fast-passes straightforward drafts, full challenge for epics/unargued items | -| Review the plan | **two parallel reviewers**: Codex GPT-5.6 `xhigh` + Claude `plan-reviewer` (Opus) | Must-Fix gate = union of both | -| Review the diff + security | **two parallel reviewers**: Codex GPT-5.6 `xhigh` + Claude `code-reviewer` (Opus) | Must-Fix gate = union of both | - -Every Codex role is dispatched by the **`codex` skill** -(`.claude/skills/codex/`), the one place that knows the `codex exec` -mechanics per role — model, effort, sandbox (reviewers/researchers read-only -+ ephemeral; implementer workspace-write with `resume --last` across fix -rounds; investigator and backend-verifier workspace-write for running tests, -edits forbidden by their role instructions), output capture, and status-line -parsing. - -Review loops exit when **no Must Fix remains from either reviewer** — the -Overseer judges when a loop has converged and flags anything left -unresolved in the wrap-up. High effort is for judgment-heavy roles (review, -investigation); implementation and exploration run at medium. Frontend code -and customer-facing copy never route through Codex — they're the -`frontend-implementer`'s lane. `/do` and the three `/create-*` skills -are user-invoked only (`disable-model-invocation`) — the model never fires -them on its own. - -Build tracker and design decisions: `../tmp/plan/build-plan.md` (local -working notes — `tmp/` is untracked). - -## Where formats live (single copy each — no duplicates to drift) - -- **`tyler/references/`** (synced to `~/.references/` — harness-neutral, - sibling of `~/.claude` and `~/.codex`) — anything referenced by more than - one skill, or by any agent: the shared blocks (`verification-criteria.md`, - `verification-methods.md`, `rubrics/` — per-surface verification rubrics, - `code-quality.md` — the reviewers' house-rules rubric, `qa-verification.md` - — the QA pass's external-evidence discipline, `system-analysis.md`, - `publish-work-item.md`, `draft-work-item.md`, - `socratic-gate.md`) and every agent's output format - (`references/agents/<agent>/…`). Agents are flat `.md` files by design - (Claude Code has no agent-folder format), so each agent's body carries a - pointer — "Read `~/.references/agents/<name>/<format>.md`" — plus a few - non-negotiable lines as a safety net if the file is missing. -- **`.claude/skills/<name>/references/`** — document formats produced by - exactly one skill (feature-ticket, epic-spec, bug-report, - implementation-plan, wrap-up-report, postmortem). -- `../tmp/templates/README.md` (local working notes, untracked) is the index - mapping every format to its live home. - -The six workflow skills above, plus three infrastructure skills the others -invoke — `codex` (dispatches Codex roles), `notion` (the GitHub ↔ Notion -artifact bridge), and `excalidraw-pr-diagrams` (the PR visual-overview -standard `/do`'s PR step uses; kept materially equivalent to parsa's -copies) — are the whole surface. Web research is the -`web-researcher` sub-agent, review lives inside `/do` (plan review before -implement, code review + QA after the PR opens), and all commit/PR prep -lives in `/do`'s PR step. - -## Project templates - -`templates/` holds copyable per-project scaffolding: `AGENTS.md` (universal -agent instructions both harnesses read) and `CLAUDE.md` (points to AGENTS.md, -adds Claude-only notes, and carries the optional `Work-item tracking` -overrides — the Notion work-items database default lives in the notion -skill's `config.yaml`; a project sets `notion_data_source` only to publish -somewhere different). Copy both into a codebase root and fill in the -sections. - -## Keeping in sync - -```bash -git -C "$REPO" pull --ff-only -rsync -a "$REPO/tyler/.claude/skills/" "$HOME/.claude/skills/" -rsync -a "$REPO/tyler/.claude/agents/" "$HOME/.claude/agents/" -rsync -a "$REPO/tyler/references/" "$HOME/.references/" -rsync -a "$REPO/tyler/.codex/skills/" "$HOME/.codex/skills/" - -# drift check — any output means a local copy differs from the repo -diff -rq "$REPO/tyler/.claude/skills" "$HOME/.claude/skills" -diff -rq "$REPO/tyler/.claude/agents" "$HOME/.claude/agents" -diff -rq "$REPO/tyler/references" "$HOME/.references" -diff -rq "$REPO/tyler/.codex/skills" "$HOME/.codex/skills" -``` - -The `.codex/skills/` role skills (implementer, backend-verifier, -plan-reviewer, code-reviewer, code-researcher, investigator) are thin -pointers — one copy of each document across both harnesses. Role -instructions live in `~/.references/agents/<role>/instructions.md` for the -Codex-only roles (implementer, investigator, backend-verifier) and in -`~/.claude/agents/<name>.md` where a Claude twin exists (code-researcher, -the reviewers); output formats live in `~/.references/agents/<role>/`. - -`rsync` without `--delete` won't remove skills/agents that were deleted from -this repo — the drift check's `Only in $HOME/...` lines are the prune list; -remove those by hand (or pass `--delete` if nothing hand-made lives in your -local folders). diff --git a/tyler/references/agents/backend-verifier/instructions.md b/tyler/references/agents/backend-verifier/instructions.md deleted file mode 100644 index 2543c28..0000000 --- a/tyler/references/agents/backend-verifier/instructions.md +++ /dev/null @@ -1,45 +0,0 @@ -# Backend Verifier — role instructions - -You verify backend work against its numbered verification criteria by running -the mapped commands — tests, scripts, API calls, migrations checks. Verify -means *proving it's done*, not *assuming*. Frontend criteria (driving the -running app) are verified elsewhere — if the dispatch includes some, flag -them in your return rather than guessing. - -A dispatch may instead name **QA mode** (`/do`'s post-PR QA pass): execute -the command-shaped items of the PR's Manual tests checklist best-effort, in -the dispatch's risk order, following the external-evidence rules the -dispatch points you at (`qa-verification.md`). Report in the same format, -one row per checklist item; Result may be `Left to human — <reason>` — a -deliberately deferred item is not a failed criterion. - -Boundaries: you never edit project files — you run and report. Do not spawn -sub-agents. - -## Tooling - -Prefer the repo's own commands (tests, scripts, service CLIs). If -observability tooling is connected in this environment — an authenticated -cloud CLI for logs (gcloud-style), an error tracker — use it to confirm -runtime side effects. Evidence must still come from re-runnable commands, -not dashboards. - -## Method - -1. Read your dispatch: criteria `AC1…`, each with a mapped method and - command/script, and usually a rubric — work through the rubric's items - too and capture the evidence each names. -2. Start from a known state; run each mapped command. -3. Capture evidence as you go: quoted command output and log excerpts per - criterion. -4. If something can't be exercised (missing env, service down), say so — - never guess a result. - -## Output format - -Before writing your report, Read -`~/.references/agents/frontend-verifier/verification-result.md` (the shared -verifier format) and return your result in the **verify** mode format. - -Even if the reference file is unavailable: verdict first (`pass | fail`); a -Pass without quoted evidence is not a Pass; verify does not pass on partial. diff --git a/tyler/references/agents/code-researcher/codebase-findings.md b/tyler/references/agents/code-researcher/codebase-findings.md deleted file mode 100644 index 0206fd4..0000000 --- a/tyler/references/agents/code-researcher/codebase-findings.md +++ /dev/null @@ -1,30 +0,0 @@ -# Codebase Findings — agent output format - -> Returned **in-conversation** by the Code Researcher (Sonnet) during the plan stage — -> **not a file**. Precise `file:line` references so the plan can be accurate without the -> Overseer re-reading the codebase. -> **Open with the bottom line** so the Overseer can branch without reading the body. - ---- - -**Bottom line:** `<one line — the answer the plan needs>` - -## Relevant files -- `<path:line>` — `<what's here, why it matters to this work>` - -## Existing patterns to follow -- `<pattern>` — `<where it's used (path:line)>` - -## Boundaries / integration points -- `<system boundary or integration point the work touches>` - -## Not found / open questions *(required — "none" only after actually looking)* -- `<what was searched for and not found, or couldn't be determined>` - -## Gotchas *(omit section if none)* -- `<landmine, inconsistency, or constraint the plan must respect>` - ---- -Return conclusions and references, not file dumps. Every claim carries a `path:line`. -The Overseer plans against these findings — what you didn't find is as load-bearing -as what you did. diff --git a/tyler/references/agents/code-reviewer/review-report.md b/tyler/references/agents/code-reviewer/review-report.md deleted file mode 100644 index 7d1cdb5..0000000 --- a/tyler/references/agents/code-reviewer/review-report.md +++ /dev/null @@ -1,47 +0,0 @@ -# Review Report (Code + Security) — agent output format - -> Returned **in-conversation** by the Code Reviewer to the Overseer — **not a file**. -> Runs 1+ times in the post-PR review loop (per-phase diff review on epics); Must-Fix -> items loop back to Implement until zero Must-Fix (cap 3; light lane 1). The security review is mandatory: security findings live in -> Must Fix / Should Fix with a `(security)` tag — never a separate section, so they -> always count toward the loop's Must-Fix gate. Final outcome folds into `wrapup.md`. -> **Your final message IS the report: begin with the verdict.** Every line is a verdict, -> a finding with `file:line`, or a check you ran — no preamble, no process narration, -> no closing summary. - ---- - -**Verdict:** `<Approve | Request changes>` — `<one-line rationale>` -**Counts:** Must Fix: `<n>` (security: `<m>`) · Should Fix: `<n>` · pass `<k>`/`<cap>` - -## Must Fix *(blocks merge; loop back to Implement)* -- **MF-1** `(security)` — `<what>` · `<file:line>` · `<fix>` · violates `<D# / AC# | "new issue">` - - **Failure scenario:** `<concrete way this breaks in production>` *(required for correctness/security findings)* -- **MF-2** — `<what>` · `<file:line>` · `<fix>` · violates `<…>` - -## Should Fix *(important, non-blocking)* -- **SF-1** — `<what>` · `<file:line>` · `<fix>` - -## Nice to Have *(omit section if empty)* -- `<nit or thought>` - -## Praise *(omit section if empty)* -- `<what the diff got right — specific, so it survives the fix loop>` - -## ⚠️ Cannot verify *(omit if empty)* -- `<requirements you couldn't verify from the diff alone, and what the Overseer should check>` - ---- -**What a Code Reviewer checks:** correctness vs the plan & item intent · security -(authz, input validation, injection, secrets, unsafe deserialization) — tag findings -`(security)` · missing error handling & edge cases · unneeded complexity / -over-engineering · adequate tests · clear naming · does the diff actually fulfill the -intent (not just the task list) · house rules per `code-quality.md` (discovered -from this repo, source cited, never Must Fix alone). Every finding cites `file:line`. - -**Calibration:** Must Fix = ships a bug, a vulnerability, or fails an acceptance -criterion. Should Fix = materially better code, but mergeable without it. Everything -else is Nice to Have — don't inflate severity. - -**Re-reviews (pass 2+):** first mark every prior finding by ID as `fixed | persists | -new`, then add anything new. Don't re-litigate what's fixed. diff --git a/tyler/references/agents/frontend-verifier/verification-result.md b/tyler/references/agents/frontend-verifier/verification-result.md deleted file mode 100644 index 4ee4652..0000000 --- a/tyler/references/agents/frontend-verifier/verification-result.md +++ /dev/null @@ -1,49 +0,0 @@ -# Verification Result — agent output format - -> Returned **in-conversation** to the Overseer — **not a file** — by a verifier: -> the Claude `frontend-verifier` (all modes) or the Codex `backend-verifier` -> (verify and QA modes, via tests/scripts instead of the browser). -> Modes, selected by the dispatch prompt: **verify** (from `/do`'s verify stage — -> prove the work meets its numbered criteria; `/do`'s QA pass uses the same format, -> one row per Manual-tests checklist item, Result additionally allowing -> `Left to human — <reason>`) and **reproduce** (from `/discussion` or -> `/create-issue` — make a reported failure happen deterministically; the failure -> occurring IS the successful result). -> Your final message IS the report — no preamble, no process narration. - ---- - -## Output format — verify mode - -**Verdict:** <pass | fail — the specific blocking criterion> - -## Criteria checked -| Criterion | Method | Result | Evidence | -|-----------|--------|--------|----------| -| AC1 — <criterion> | <flow / script / test> | Pass / Fail | <quoted output or log excerpt — required for every row> | - -## What was exercised -<the flow driven / commands run — enough for someone to re-run it> - -## Anomalies (omit section if none) - -A Pass without quoted evidence is not a Pass. Do not report success until -every criterion's mapped method actually passes — verify does not pass on -partial. - ---- - -## Output format — reproduce mode - -**Verdict:** <reproduced | could not reproduce — what was tried> - -## Reproduction steps -<numbered, from a known state — the shortest deterministic path you found> - -## Observed behavior -<what happens, stated as observation, with quoted evidence> - -## Anomalies (omit section if none) - -If you could not reproduce, list every path you tried and the state you tried -it from — a documented failure to reproduce is a valid, useful result. diff --git a/tyler/references/agents/implementer/implementation-result.md b/tyler/references/agents/implementer/implementation-result.md deleted file mode 100644 index 6397c2d..0000000 --- a/tyler/references/agents/implementer/implementation-result.md +++ /dev/null @@ -1,32 +0,0 @@ -# Implementation Result — agent output format - -> Returned **in-conversation** by the Implementer during `/do`'s implement stage — -> **not a file**. The Implementer also updates `plan.md` directly: ticks tasks, records -> plan-deltas, keeps the Files-changed table true. -> **Keep the return under ~15 lines** — the detail lives in `plan.md`. - ---- - -**Status:** `<DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT>` - -`<DONE_WITH_CONCERNS = complete, but something merits Overseer attention — never` -`silently produce work you're unsure about. BLOCKED / NEEDS_CONTEXT: put the` -`specifics under Blockers; the Overseer acts on them directly.>` - -## What was built -`<1–3 lines tied to the plan tasks completed>` - -## Plan deltas -- `<deviation from plan + reason>` *(or "none")* - -## Quality checks *(exact command → result; a bare "pass" is uncheckable)* -- tests: `<command>` → `<e.g. 14/14 passing>` -- typecheck: `<command>` → `<result>` · lint: `<command>` → `<result>` - -## Blockers / needs Overseer -- `<what stalled or needs a decision>` *(or "none")* - ---- -A task isn't done until its runtime/user-facing path is wired end-to-end. Report -last-mile gaps (routes not mounted, controls with no effect) as incomplete, not done. -Files touched live in `plan.md`'s Files-changed table — don't repeat them here. diff --git a/tyler/references/agents/implementer/instructions.md b/tyler/references/agents/implementer/instructions.md deleted file mode 100644 index 0183c95..0000000 --- a/tyler/references/agents/implementer/instructions.md +++ /dev/null @@ -1,47 +0,0 @@ -# Implementer — role instructions - -You are an elite software engineer specializing in systematic plan -implementation. You take an Implementation Plan (`plan.md`) and execute it with -precision — the plan is the source of truth for **how**, the work item's intent -for **why**. This role handles backend/ops work; frontend web/mobile work is -implemented elsewhere — if the dispatch includes some, flag it in your return -rather than doing it. - -Boundaries: -- You are the primary implementation authority for the work you receive; - finish the whole assigned chunk rather than splitting it further. -- Do not spawn sub-agents unless the parent explicitly instructed you to. -- Do not silently simplify, defer, or change scope — record a plan delta and, - if it conflicts with the item's intent, escalate via your return. - -## Tooling - -Prefer the repo's own commands (build, tests, scripts, service CLIs). If an -authenticated cloud CLI or similar is connected, you may use it read-only to -check an integration you're wiring against — never to mutate shared -environments. - -## Execution - -1. Read the entire plan first — Files-changed table, key decisions, tasks, - verification — and the work item's intent if provided. -2. Execute tasks in order, respecting dependencies. Follow conventions from - CLAUDE.md files; use existing patterns rather than inventing new ones; - prefer editing existing files over creating new ones. -3. Keep `plan.md` true as you go: tick each task's checkbox, record plan - deltas with reasons, keep the Files-changed table matching reality. -4. Quality loop after each major section: `npm run typecheck`, `npm run lint`, - `npm run format` (or the repo's equivalents) — fix issues before proceeding. -5. A task is not done until its runtime/user-facing path is wired end-to-end. - Routes with no mount, UI controls with no effect, params with no consumer, - hooks with no caller = incomplete work, not done work. - -## Output format - -Before writing your result, Read -`~/.references/agents/implementer/implementation-result.md` and return -it in exactly that format. - -Even if the reference file is unavailable: Status first -(`DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT`); final message under -~15 lines — detail lives in `plan.md`. diff --git a/tyler/references/agents/investigator/instructions.md b/tyler/references/agents/investigator/instructions.md deleted file mode 100644 index 72ad106..0000000 --- a/tyler/references/agents/investigator/instructions.md +++ /dev/null @@ -1,67 +0,0 @@ -# Investigator — role instructions - -You are a bug investigator. Your job is to reproduce a defect, isolate its -cause with evidence, and return a root-cause finding that feeds the Bug -Report's Root cause and Suggested resolution path sections. - -Boundaries: -- **Diagnose, don't fix.** You may run code, tests, and repro scripts; - you do not edit project files. -- Separate observation from diagnosis. If the cause is unconfirmed, say so and - state what evidence would confirm it — never present a guess as a finding. -- Do not spawn sub-agents. - -## Tooling - -Check what's connected (MCP tools or authenticated CLIs) and use it — -production evidence beats local speculation: -- **Error tracking** (Sentry-style): pull the actual traces, frequency, and - first-seen for the failure. -- **Production/staging logs** (a cloud CLI like gcloud): correlate the - failure window with what the services logged. -- **Product analytics** (PostHog-style): confirm who hits the path, how - often, and since when — feeds the Bug Report's impact section. -None connected? Proceed with local reproduction and note which sources were -unavailable. - -## Method - -1. Categorize the failure — each category points the investigation - somewhere different: type/compile → recent type changes, config, package - versions · logic → data flow and conditionals vs a working path · - race/timing → shared state, missing awaits, event ordering · state - management → mutations and update propagation · integration/contract → - request/response shapes and transformations at the boundary · - environment/config → env vars, versions, build settings · UI/rendering → - props, conditional rendering, style specificity. -2. Rank 3–5 hypotheses **before tracing any code** — plausible causes ordered - by likelihood, one line of reasoning each. The list is your protection - against tunnel-vision on the first plausible explanation; test against it - and re-rank as evidence lands. -3. Reproduce — find the shortest deterministic path from a known state - to the failure. If you cannot reproduce, that IS the finding (say what you - tried). -4. Localize — trace from the observed failure to the code that produces it; - instrument with logs/small scripts rather than speculation. Highest-yield - moves: trace backward from the error, check recently-changed code - (`git log` on the relevant paths), diff the broken path against a working - sibling, follow the data across service/component boundaries. `git blame` - the failing lines to name the change that introduced the break — - revert-vs-patch decisions downstream hang on it. -5. Confirm — a root cause is confirmed when you can predict the failure from - the code path AND explain why the expected behavior doesn't happen. -6. Escalate a stall — after 3 hypothesis→test cycles without progress, stop - testing variations of the same theory. Summarize what's ruled out with - the evidence against each, and reconsider the layer (backend vs frontend, - code vs environment, logic vs timing) in your finding instead of forcing - a low-confidence diagnosis. -7. Sketch the fix direction — high level, not code; `/do` decides the detail. - -## Output format - -Before writing your finding, Read -`~/.references/agents/investigator/root-cause-finding.md` and return it -in exactly that format. - -Even if the reference file is unavailable: root cause + confidence -(`confirmed | likely | hypothesis`) first; never present a guess as a finding. diff --git a/tyler/references/agents/investigator/root-cause-finding.md b/tyler/references/agents/investigator/root-cause-finding.md deleted file mode 100644 index 0ef210e..0000000 --- a/tyler/references/agents/investigator/root-cause-finding.md +++ /dev/null @@ -1,30 +0,0 @@ -# Root-Cause Finding — agent output format - -> Returned **in-conversation** by the Investigator (from `/discussion` or `/create-issue`) — **not a file**. -> Feeds the Bug Report's Root cause + Suggested resolution path sections. -> **Open with the one-line cause + confidence** so the Overseer can branch without -> reading the body. - ---- - -**Root cause:** `<one line>` · **Confidence:** `<confirmed | likely | hypothesis>` -**Introduced:** `<commit / PR / timeframe — via git blame/log — or "unknown">` - -## Reproduction -`<numbered steps that reliably reproduce, from a known state>` - -## Observed behavior -`<what actually happens — stated as observation>` - -## Root cause (detail) -`<the cause, with evidence: file:line, stack trace, or log excerpt>` - -## Suggested resolution path -`<direction for the fix — high level, not code>` - -## What would confirm it *(omit only when confidence is `confirmed`)* -`<the specific evidence or experiment that would upgrade the confidence>` - ---- -Separate observation from diagnosis. If the cause is unconfirmed, say so and state -what evidence would confirm it — don't present a guess as a finding. diff --git a/tyler/references/agents/plan-reviewer/review-report.md b/tyler/references/agents/plan-reviewer/review-report.md deleted file mode 100644 index 3376696..0000000 --- a/tyler/references/agents/plan-reviewer/review-report.md +++ /dev/null @@ -1,42 +0,0 @@ -# Review Report (Plan) — agent output format - -> Returned **in-conversation** by the Plan Reviewer to the Overseer — **not a file**. -> Runs 1+ times in the plan-review loop; the Overseer feeds Must-Fix items back into the -> plan and re-reviews until zero Must-Fix (cap 3; light lane 1), then implement proceeds. -> **Your final message IS the report: begin with the verdict.** Every line is a verdict, -> a finding with a location, or a check you ran — no preamble, no process narration, -> no closing summary. - ---- - -**Verdict:** `<Approve | Request changes>` — `<one-line rationale>` -**Counts:** Must Fix: `<n>` · Should Fix: `<n>` · pass `<k>`/`<cap>` - -## Must Fix *(blocks; loop back to plan)* -- **MF-1** — `<what>` · `<where: plan section>` · `<concrete fix>` · violates `<D# / AC# | "new issue">` - -## Should Fix *(important, non-blocking)* -- **SF-1** — `<what>` · `<where>` · `<fix>` - -## Nice to Have *(omit section if empty)* -- `<nit or thought>` - -## Praise *(omit section if empty)* -- `<what the plan got right — specific, so it survives revision>` - -## ⚠️ Cannot verify *(omit if empty)* -- `<what you couldn't check from the plan + repo alone, and what the Overseer should confirm>` - ---- -**What a Plan Reviewer checks:** repo accuracy (referenced files/anchors exist) · -completeness (gaps, missing integration points, ordering) · correctness of approach · -simplification opportunities · fidelity to the item's intent, locked decisions & non-goals · -altitude (no line-level detail; placeholder leakage — "TBD" in a plan — is a Must Fix) · -dead code (a replacement plan with an empty Deprecated / removed section is a finding). - -**Calibration:** Must Fix = the plan as written produces wrong, broken, or unverifiable -work. Should Fix = a materially better plan, but this one can proceed. Everything else -is Nice to Have — don't inflate severity. - -**Re-reviews (pass 2+):** first mark every prior finding by ID as `fixed | persists | -new`, then add anything new. Don't re-litigate what's fixed. diff --git a/tyler/references/agents/socrates/socratic-challenge.md b/tyler/references/agents/socrates/socratic-challenge.md deleted file mode 100644 index 91c4e1f..0000000 --- a/tyler/references/agents/socrates/socratic-challenge.md +++ /dev/null @@ -1,52 +0,0 @@ -# Socratic Challenge — agent output format - -> Returned **in-conversation** by Socrates to the Overseer — **not a file**. -> Runs before publish in every `/create-*` skill: round 1 challenges the draft, -> round 2+ judges the user's answers. The Overseer relays questions to the user -> verbatim and brings answers back. Cap: two judged rounds, then final verdict. -> **Your final message IS the report: begin with the verdict.** No preamble, no -> process narration, no closing summary. - ---- - -## Round 1 — Challenge - -**Verdict:** `<pass | press | rethink>` — `<one-line rationale>` -**Questions:** `<n>` (max 5; a straightforward, well-justified draft gets 0–2 — -depth follows the item, never a quota) - -- **Q1** *(`necessity | root-cause | simpler-alternative | shape | assumption | consequence | completeness`)* - - **Targets:** `"<quoted line or claim from the draft>"` - - **Question:** `<the open question, addressed to the author>` - - **Stake:** `<what changes about the item if the answer is weak — cut, split, redirect, abandon>` - - **Alternative:** `<the concrete cheaper path, if this is a simpler-alternative question — omit otherwise>` - -`<repeat per question, ordered by how much of the item hangs on each>` - -**Verdict calibration:** `rethink` = the premise itself looks wrong (symptom not -root cause, no evidence of need, obviously wrong shape) — say so plainly in the -rationale. `press` = premise plausible but load-bearing claims are unargued. -`pass` = the draft already carries its justification; ask only what genuinely -remains (may be zero questions). - -## Round 2+ — Judgment - -**Verdict:** `<pass | press | rethink>` — `<one-line rationale>` -**Round:** `<k>`/2 - -- **Q1** — `answered | partial | evasive` — `<one line: the reasoning you're accepting, or what's still missing>` - - **Press:** `<the sharper follow-up — only for partial/evasive, only in round 2>` - -**Distilled justification:** *(only when the verdict is `pass`, or on the final -round regardless)* one line per question worth keeping, in the form the item -records: `<claim challenged> — <the reason that held>`. Mark anything still -open as `OPEN: <what remains unargued>` so the Overseer can carry it into the -item's Open questions. - ---- - -**Grading:** `answered` = a reason that could have come out differently -(evidence, named trade-off, accepted cost, rejected alternative with a why). -`partial` = engages but leaves the load-bearing part unargued. `evasive` = -restates the request or appeals to authority without the reasoning. -Acknowledged uncertainty with a reason to proceed anyway is `answered`. diff --git a/tyler/references/agents/web-researcher/research-dossier.md b/tyler/references/agents/web-researcher/research-dossier.md deleted file mode 100644 index 49e50da..0000000 --- a/tyler/references/agents/web-researcher/research-dossier.md +++ /dev/null @@ -1,27 +0,0 @@ -# Research Dossier — agent output format - -> Returned **in-conversation** by the Web Researcher (Sonnet) — **not a file** by default. -> Persist to `./tmp/<id>/refs/` only if it's a durable source worth keeping (then it -> becomes an optional reference, linked from the item). -> **Open with the recommendation** so the Overseer can branch without reading the body. - ---- - -**Recommendation:** `<the one-line actionable takeaway>` · **Confidence:** `<confirmed | likely | hypothesis>` — `<why, one clause>` - -## Question -`<what this research answers — the dedup key when researchers fan out in parallel>` - -## Key findings -- `<finding>` — `<source, date/version>` -- `<finding>` — `<source, date/version>` - -`<Every factual claim carries its source AND a date/version where recency matters —` -`an undated version-sensitive claim is uncheckable.>` - -## Gaps / caveats *(omit section if none)* -- `<what's unresolved, conflicting, or version-sensitive>` - ---- -Prefer official docs over blogs. Report what you looked for and did NOT find — silence -must be distinguishable from absence. diff --git a/tyler/references/code-quality.md b/tyler/references/code-quality.md deleted file mode 100644 index 7d53f2f..0000000 --- a/tyler/references/code-quality.md +++ /dev/null @@ -1,35 +0,0 @@ -# Code quality — reviewer rubric (project-agnostic) - -> Read by both code reviewers (Claude + Codex) alongside the diff. -> Correctness and security live in the role instructions; this file covers -> the *house rules* dimension — code that works but doesn't belong here. - -## Discover the conventions first - -Never assume a stack. Before judging idiom, learn this repo's: - -- convention docs — project `CLAUDE.md` / `AGENTS.md` / CONTRIBUTING, lint - and formatter configs, type-checker strictness; -- the neighbors — the 2–3 existing files most similar to each changed file: - naming, layering, state management, error idiom, import style; -- shared hubs — where cross-module types/utilities live, and whether the - diff duplicates one. - -The diff is judged against what THIS repo does, not against general taste. -Every house-rule finding cites the convention's source (config line, -neighbor `file:line`, doc section). - -## Severity mapping - -- **Must Fix** — only what the role instructions already gate: broken - behavior, security, unverifiable ACs. A house-rule violation is never - Must Fix on its own. -- **Should Fix** — architecture and idiom: layering the repo consistently - avoids, a second source of truth for an existing type/utility, state - managed in the wrong place per the repo's own pattern, type-escape - hatches (`any`-style) where the repo is strict. -- **Nice to Have** — naming, formatting drift the linter missed, import - ordering, comment style. - -Rule of thumb: if the repo is itself inconsistent about it, it's Nice to -Have at most — don't enforce a convention the codebase doesn't keep. diff --git a/tyler/references/draft-work-item.md b/tyler/references/draft-work-item.md deleted file mode 100644 index 20f5f96..0000000 --- a/tyler/references/draft-work-item.md +++ /dev/null @@ -1,25 +0,0 @@ -# Draft a work item — shared mechanics - -Used by `/create-feature`, `/create-epic`, and `/create-issue` when writing -`./tmp/<id>/item.md`. The calling skill supplies the document template (from -its own `references/` directory) and any type-specific content rules. - -- Check `./tmp/discussions/` for a decision log from the conversation that - produced this item (match by slug and date). Carry its decisions and - constraints into the item's locked directions rather than re-deriving - them; link it from `refs/` if it holds more than the item should inline. -- Pick `<id>`: short kebab-case slug from the title. Create `./tmp/<id>/`. -- Write `item.md` following the caller's template. A template is a skeleton - plus authoring notes: emit the filled-in frontmatter and body only — the - "— format" title line and the backtick-quoted guidance are notes to you, - not part of the document. -- Embed verification criteria per `~/.references/verification-criteria.md`: - EARS-style, numbered `AC1…`, each mapped to a method from - `~/.references/verification-methods.md` and matched to the change type's - rubric in `~/.references/rubrics/`. No "works correctly". -- Keep it LEAN: `/do` starts fresh and is capable — omit anything it can - reasonably decide itself. -- Save transcript-worthy raw material (key discussion excerpts, mock-ups, - links, research worth keeping) to `./tmp/<id>/refs/` and link from the - item — never inline. -- Leave `status: draft` until publish. diff --git a/tyler/references/publish-work-item.md b/tyler/references/publish-work-item.md deleted file mode 100644 index 0e14ca9..0000000 --- a/tyler/references/publish-work-item.md +++ /dev/null @@ -1,34 +0,0 @@ -# Publish a work item — shared procedure - -Used by `/create-feature`, `/create-epic`, and `/create-issue` after -`item.md` is written. The caller supplies the issue title prefix (`feat:` or -`fix:`) and the issue body summary. - -1. Set `status: ready` in `item.md`. -2. Create the GitHub issue: `gh issue create` in the project's repo (from the - `Work-item tracking` section of the project's `CLAUDE.md`, or the current - repo) — title `<prefix> <item title>`, body per the caller. -3. Invoke the `notion` skill, operation `publish`, with `./tmp/<id>/` and the - issue URL — it creates the Notion work item and uploads `item.md` + every - `refs/` file, returning the page URL. -4. Cross-link: add the Notion page URL to the GitHub issue body - (`gh issue edit`), and record both in `item.md` frontmatter as `github:` - and `notion:`. -5. On `NOTION UNAVAILABLE`, the issue must still carry everything a remote - `/do` needs — post each artifact as its own issue comment, wrapped in - markers so Step 0 can harvest them back: - - ``` - <!-- ORCHESTRA-ARTIFACT path="refs/discussion.md" --> - <full file content> - <!-- /ORCHESTRA-ARTIFACT --> - ``` - - One comment per file (`item.md` itself is the issue body, so just the - `refs/` files). A comment holds ~65K chars; split oversized files into - `part=1/2` markers. Then tell the user Notion was skipped and the issue - is self-contained. - -Done when: the issue exists, every artifact is reachable from it (Notion -work item, or marker-delimited comments in degraded mode), and each of -issue / Notion page / item.md links to the others. diff --git a/tyler/references/qa-verification.md b/tyler/references/qa-verification.md deleted file mode 100644 index b2b046c..0000000 --- a/tyler/references/qa-verification.md +++ /dev/null @@ -1,87 +0,0 @@ -# QA verification — external-evidence discipline - -> Read by `/do` Step 5's QA-pass dispatches: the `frontend-verifier` driving -> the app, the `backend-verifier` running command-shaped checks. Extends -> `verification-methods.md` — same proof standard, plus the rules that make -> automated QA evidence trustworthy end to end. - -## Discover connected tooling first - -Inventory what this environment can already prove things with before the -first flow: MCP servers and connectors (analytics, email/SMS, payments, -CRM — a Composio-style tool catalog often holds an authenticated tool for -the product even when nothing is configured in the repo), authenticated -CLIs (`gh`, payment/cloud CLIs), local containers and their logs. Product -data queried through a connected tool beats any local inference — prefer -it wherever one exists, and name in the report which tools you used and -which were missing. - -## Build what's missing - -The run is allowed to make its own tools. No browser driver in the repo? -Install one in the scratch directory — never pollute the repo or its -lockfiles. Need a probe script, webhook listener, or log parser? Write it -in scratch and remove it after. Drive UIs by stable user-visible selectors -(labels, button text, routes), and pull verification links/codes from -local service logs when the environment emits them. - -## External verification - -A network request only proves the app *tried*; ingestion is proven at the -receiving system. When a flow ends in an external system — analytics, -payments, email/SMS, webhooks — confirm arrival there: query the connected -tool or API for the event, never just the browser's network tab. No -connector available → the item is `Left to human — <reason>`, not assumed. -Record what lets a human find the test again: event ids, -customer/subscription ids, dashboard URLs, the date range and filters -queried. - -## Unique test identity - -Stamp the run's actions with a unique marker (e.g. `agent-e2e-<timestamp>` -in names, emails, note fields) and query external systems by that marker — -it separates this run's evidence from prior runs and from real users. - -## Preflight - -Before a long flow, verify the tools it needs are alive: authenticated CLIs -(`gh auth status` and peers), running services/containers, connectors, -test-mode keys wherever the flow touches money. A flow that dies at step 7 -for a missing login wastes the run — fail fast at step 0. - -## Test-mode safety - -Stay in test/staging mode by default. Real production mutations — payments, -messages to real users, destructive data operations, feature-flag flips — -are never taken: stop that action, mark the checklist item -`Left to human — <reason>`, and continue the rest of the run. - -## Automation artifacts - -Products treat automated browsers differently — analytics SDKs silently -drop events from bot-flagged sessions (`navigator.webdriver`, headless -user-agent brands). When the goal is proving ingestion, mask the -automation signals for the test context only, and disclose the masking in -the report. Pace critical flows like a human — batched events need time to -fire in order — and rerun with slower pacing before calling an ordering -anomaly a product bug. Every artifact the harness caused (mocked signals, -prevented navigation, dummy keys) is named in the report, never left to be -mistaken for product behavior. - -## Evidence hosting - -Screenshots and clips are evidence, not repo content — never commit them. -Upload to whatever host the environment provides and inline the URLs in -the PR comment so previews render where the reviewer reads. Durable + -scriptable: a rolling GitHub release (`gh release create pr-assets` once, -then `gh release upload pr-assets <img>` — asset URLs render inline and -outlive the review). GitHub user-attachment URLs are just as durable but -have no API (browser-only); a project upload endpoint or temporary image -host works too. When only a temporary host is available, note its -expiry next to the link and keep the textual evidence (quoted output, ids) -self-sufficient without the image. - -## Cleanup - -Kill the listeners, processes, and temp state the run started; leftovers -poison the next run's evidence. diff --git a/tyler/references/rubrics/README.md b/tyler/references/rubrics/README.md deleted file mode 100644 index 2a90f5b..0000000 --- a/tyler/references/rubrics/README.md +++ /dev/null @@ -1,18 +0,0 @@ -# Verification rubrics - -One rubric per change surface. `/do`'s verify stage picks the rubric matching -the change type (see `../verification-methods.md`) and includes it in the -verifier's dispatch alongside the item's `AC#` criteria. - -How to read a rubric: -- Every item is **binary** — it passes only on the named observable evidence, - never on a judgment or an assertion. -- **[blocker]** items gate the verify stage; unlabeled items are reported but - don't block. -- "Known failure modes" list what has actually bitten on this surface — - check them even when no AC mentions them. - -How rubrics grow: from postmortems and review misses, not speculation. When -a `/postmortem` names a failure a rubric item would have caught, add that one -item (keep each rubric at 5–9 items — encode what's dangerous to skip AND -likely to be skipped; long lists get box-ticked). diff --git a/tyler/references/rubrics/backend-api.md b/tyler/references/rubrics/backend-api.md deleted file mode 100644 index ecec1a2..0000000 --- a/tyler/references/rubrics/backend-api.md +++ /dev/null @@ -1,21 +0,0 @@ -# Rubric — backend API change - -1. **[blocker]** Each `AC#` proven by an integration test or script through - the real HTTP layer against a real datastore — not mocked handlers. - Evidence: test report or quoted request/response. -2. **[blocker]** Error paths tested explicitly: at least one non-2xx case - (invalid input) with the expected status and body shape. Evidence: the - failing-case output. -3. **[blocker]** AuthZ on new/changed surfaces: an unauthorized caller gets - the expected rejection. Evidence: the rejected request's output. -4. **[blocker]** Backward compatibility: existing consumers' request/response - shapes unchanged, or the break is named in the item. Evidence: schema/ - contract check or the diff of the response shape. -5. Idempotent or transactional where the operation implies it (retried - request doesn't double-apply). Evidence: double-invoke output. -6. New surface appears in logs with enough context to debug (request id, - caller). Evidence: log excerpt from the exercised call. - -Known failure modes: route handler written but not mounted; validation on -the happy path only; N+1 query introduced on a list endpoint; secrets or -PII in the new log lines. diff --git a/tyler/references/rubrics/background-job.md b/tyler/references/rubrics/background-job.md deleted file mode 100644 index 07dd142..0000000 --- a/tyler/references/rubrics/background-job.md +++ /dev/null @@ -1,17 +0,0 @@ -# Rubric — background job / worker change - -1. **[blocker]** Idempotency under at-least-once delivery: invoke the job - twice with the same payload; no duplicated side effects. Evidence: - double-invoke output + the resulting state. -2. **[blocker]** Failure path: a failing payload retries per policy and lands - in the DLQ / failure state, not an infinite loop. Evidence: the retry/DLQ - trace. -3. **[blocker]** Each `AC#` proven by running the job against a real queue or - invoking its handler with a real payload — not only unit-testing helpers. -4. Structured logs carry job id + attempt count. Evidence: log excerpt. -5. Irreversible side effects (payments, emails) are guarded — outbox pattern, - dedupe key, or explicit once-only check. Evidence: the guard exercised. - -Known failure modes: side effect fires before the transaction commits; -poison message blocks the queue; retry storm on a downstream outage; clock- -dependent behavior that only manifests in production timezones. diff --git a/tyler/references/rubrics/cli-script.md b/tyler/references/rubrics/cli-script.md deleted file mode 100644 index 7fa4bc4..0000000 --- a/tyler/references/rubrics/cli-script.md +++ /dev/null @@ -1,15 +0,0 @@ -# Rubric — CLI / script change - -1. **[blocker]** Exit-code contract proven: success exits 0, each failure - mode exits non-zero. Evidence: both invocations with `echo $?`. -2. **[blocker]** Idempotency: run twice; the second run is a no-op or says - why not. Evidence: both outputs. -3. **[blocker]** State-mutating scripts have `--dry-run`, and its output was - captured. Evidence: dry-run output. -4. Bad input handled: a malformed argument/file produces a clear error, not - a stack trace. Evidence: the error output. -5. Help text (`--help`) matches actual behavior after the change. - -Known failure modes: exit 0 on partial failure (CI gates on the code, not -the log); depends on the author's shell env; destructive default with no -dry run. diff --git a/tyler/references/rubrics/data-migration.md b/tyler/references/rubrics/data-migration.md deleted file mode 100644 index b84863d..0000000 --- a/tyler/references/rubrics/data-migration.md +++ /dev/null @@ -1,19 +0,0 @@ -# Rubric — data / schema migration - -1. **[blocker]** Dry run executed on production-like data (in a transaction - where the engine allows). Evidence: dry-run output. -2. **[blocker]** Pre/post row counts for every touched table. Evidence: the - counts, quoted. -3. **[blocker]** At least one domain-invariant query passes post-migration - (e.g. "zero rows where orders.customer_id IS NULL"). Evidence: query + - result. -4. **[blocker]** Rollback path exists and was executed once against the - dry-run state. Evidence: rollback output. -5. Expand→migrate→contract phasing: destructive steps (drop/rename) are a - later phase, not bundled with the expand step. -6. Lock safety considered for large tables (concurrent-safe index creation, - batched updates). Evidence: the statement used. - -Known failure modes: migration passes on empty dev DB and locks production; -`down` never tested; old code writes to the old column mid-deploy; invariant -held by application code only, nothing at the schema level. diff --git a/tyler/references/rubrics/frontend-web.md b/tyler/references/rubrics/frontend-web.md deleted file mode 100644 index 0182a44..0000000 --- a/tyler/references/rubrics/frontend-web.md +++ /dev/null @@ -1,23 +0,0 @@ -# Rubric — frontend web change - -1. **[blocker]** Each UI-facing `AC#` proven by natural navigation or a - behavior-level test: real interaction sequence (click/type via role-based - locators), assertion on user-visible outcome. Evidence: interaction - transcript + assertion output. -2. **[blocker]** The changed flow starts from a known state and was exercised - end-to-end — not just the component in isolation. Evidence: the flow steps - as driven. -3. **[blocker]** Unhappy path checked: invalid input, empty state, or failed - request renders a handled state, not a blank screen or console error. - Evidence: quoted console output for the failure case. -4. Accessibility scan (axe-style) on changed screens: 0 critical violations. - Evidence: violation report. -5. No new console errors/warnings during the driven flow. Evidence: console - excerpt. -6. Layout-sensitive change → visual before/after diff captured. -7. User-facing copy read in place — matches the item's intent and the - product's voice. - -Known failure modes: control renders but handler not wired (click does -nothing); route added but not mounted; state persists across navigation when -it shouldn't; works only with seeded data. diff --git a/tyler/references/rubrics/mobile-app.md b/tyler/references/rubrics/mobile-app.md deleted file mode 100644 index 352b6db..0000000 --- a/tyler/references/rubrics/mobile-app.md +++ /dev/null @@ -1,19 +0,0 @@ -# Rubric — mobile app change - -1. **[blocker]** Each UI-facing `AC#` proven in the simulator/emulator by - driving the real flow (taps, gestures, navigation). Evidence: driven-flow - transcript or test report. -2. **[blocker]** The changed journey exercised end-to-end from a fresh app - state (cold start), not only from a convenient mid-state. -3. **[blocker]** Unhappy path checked: offline/failed request, denied - permission, or empty state renders a handled state. Evidence: quoted - log/output for the failure case. -4. Screen rotation / resize (or the platform equivalent) doesn't lose the - changed screen's state, where applicable. -5. Deep links / notifications into the changed screen still land correctly, - if the change touches routing. -6. User-facing copy read in place — matches intent and product voice. - -Known failure modes: works on simulator's default device only; navigation -back-stack broken after the new screen; permission prompt loop; layout -clipped on small devices. diff --git a/tyler/references/socratic-gate.md b/tyler/references/socratic-gate.md deleted file mode 100644 index db21298..0000000 --- a/tyler/references/socratic-gate.md +++ /dev/null @@ -1,28 +0,0 @@ -# Socratic gate — shared procedure - -Run by `/create-feature`, `/create-epic`, and `/create-issue` after `item.md` -is drafted (`status: draft`) and before publish. The calling skill supplies -the per-type emphasis — what socrates should bear down on for this item type. - -1. Dispatch the `socrates` sub-agent with the draft's path (round 1). It - calibrates its own intensity: a straightforward, well-justified draft gets - a fast pass with zero to two questions; an unargued or scope-grown one gets - the full adversarial challenge — necessity, root cause, simpler - alternatives, shape, assumptions, consequences, completeness (is this the - whole of it?). -2. Relay the questions to the user **verbatim** and wait for answers — don't - answer for them; the gate exists to make the user justify the item. -3. Re-dispatch socrates with the answers to judge them (round 2); press - `partial`/`evasive` answers once. Cap: two judged rounds, then proceed with - anything unresolved carried into Open questions. -4. If the dialogue changes the item — narrower scope, a different shape, or - not worth doing — update `item.md`, switch to the matching `/create-*` - skill, or stop. Abandoning here is a success, not a failure. -5. Write the distilled Q&A into a `## Justification` section in `item.md` - (one line per question: claim challenged — reason that held). Long - exchanges go to `refs/socratic-dialogue.md`, linked from the item. -6. The user may waive the gate explicitly; record - `Socratic gate waived by user.` in the Justification section. - -Done when: socrates returned `pass` (or the cap was reached, or the user -waived); `## Justification` written into `item.md`. diff --git a/tyler/references/system-analysis.md b/tyler/references/system-analysis.md deleted file mode 100644 index 4275672..0000000 --- a/tyler/references/system-analysis.md +++ /dev/null @@ -1,26 +0,0 @@ -# System Analysis — optional reference source - -Produced by Code Researcher / Investigator when a work item needs current-state -grounding. Stored at `./tmp/<id>/refs/system-analysis.md` and **linked** from the -item — never inlined. Optional: only create when the intent or architecture -directions can't be settled without it. - ---- - -## Scope of this analysis -`<the question this doc answers — e.g. "how does delivery work today">` - -## Current-state map -- `<component / file:line>` — `<what it does today>` - -## Relevant patterns & conventions -- `<pattern>` — `<where it's used>` - -## Constraints & boundaries -- `<invariant, SLA, compat requirement, security boundary the work must respect>` - -## Prior art / related work -- `<link to related PR, ticket, or prior Postmortem>` - -## Risks / unknowns -- `<what's still uncertain — feeds Open Questions in the item>` diff --git a/tyler/references/verification-criteria.md b/tyler/references/verification-criteria.md deleted file mode 100644 index 4c20e97..0000000 --- a/tyler/references/verification-criteria.md +++ /dev/null @@ -1,49 +0,0 @@ -# Verification Criteria — shared block - -Embedded inside Bug Reports, Feature Tickets, and each Epic phase. This is the -contract `/do`'s **verify** stage proves against, so it must be testable — no -vague "works correctly." - -## Acceptance criteria (EARS-style, numbered) -Write each as a trigger → observable response. Number them — plans restate them -verbatim and reviews cite them by ID. -- **AC1** — WHEN `<trigger>` the system shall `<observable response>`. -- **AC2** — WHILE `<state>` the system shall `<response>`. -- **AC3** — IF `<unwanted condition>`, THEN the system shall `<response>`. - -**Good:** "WHEN a webhook delivery fails 5 times, the system shall mark the endpoint -`degraded` and expose it at `GET /health`." *(observable, runnable)* -**Bad:** "Webhook retries should work correctly." *(untestable — never write this)* - -## Writing rules (each criterion) - -- **Singular** — one observable outcome per criterion; split compound "and"s. -- **Measurable** — a number, state, or specific message; no quality adjectives - ("fast", "gracefully"). -- **No escape clauses** — "where possible", "attempt to", "as appropriate" - make a criterion unfalsifiable. -- **Positively stated** — "shall not fail" isn't testable; state the - observable outcome that should happen instead. -- **Deterministic** — a check can return a binary pass/fail. - -Gut check: could someone unfamiliar with the project build exactly this and -prove they did? - -## Verification map (how `/do` proves it) -Every criterion maps to at least one method. The ✓ column is **state**, ticked by -the verify stage — not a menu of options. - -| Criterion | Method | Command / flow | ✓ | -|---|---|---|---| -| AC1 | automated | `npm run test <path>` | [ ] | -| AC2 | computer-use | `<flow to drive in the running app>` | [ ] | -| AC3 | automated | `<script>` | [ ] | - -Methods: pick from `~/.references/verification-methods.md` — lint/static -rules, type checks, unit/integration tests, scripts (backend), natural -navigation of the running app (frontend/mobile), migration checks, and more. -The verify stage additionally applies the change type's rubric from -`~/.references/rubrics/`. Evidence is quoted command output / interaction -transcripts (screenshots supplement, never the sole proof; video deferred). - -**Rule:** the verify stage must not report success until every mapped method passes. diff --git a/tyler/references/verification-methods.md b/tyler/references/verification-methods.md deleted file mode 100644 index cd02132..0000000 --- a/tyler/references/verification-methods.md +++ /dev/null @@ -1,52 +0,0 @@ -# Verification Methods — shared reference - -The menu of ways to prove a change works. Used by the `/create-*` skills when -mapping each `AC#` to a method, and by `/do`'s verify stage when proving them. -Per-surface checklists live in `rubrics/` — pick the one matching the change -type and require its evidence. - -## The menu - -| Method | Proves | Evidence to capture | -|---|---|---| -| Custom lint / static rule (ESLint, Semgrep) | a structural invariant holds — including in future changes | CI pass + the rule source | -| Type check | contracts at call sites (runtime shape still needs a validator at boundaries) | `tsc --noEmit` (or equiv.) output | -| Unit tests | logic paths of one unit; keep them free of I/O and sleeps | test report | -| Integration / API tests | routing, serialization, queries against a real HTTP layer and real DB (Testcontainers-style), not mocked handlers | test report | -| E2E browser (Playwright-style / computer-use) | the whole user journey via real rendering — user-visible behavior, role-based locators | interaction transcript + assertion output (screenshot alone is not proof) | -| Mobile simulator (XCUITest / Espresso / Maestro-style) | native flows, gestures, deep links | test report or driven-flow transcript | -| Visual regression | pixels unchanged vs baseline (behavior not included) | before/after diff pair | -| Accessibility scan (axe-style) | the automatable ~half of a11y issues | violation report, 0 critical | -| Script (backend changes, one-off behavior) | a specific runtime behavior end-to-end | quoted command output + exit code | -| Migration checks | row counts, domain-invariant queries, dry run in a transaction, tested rollback | pre/post counts + invariant query results | -| Performance budget (Lighthouse-CI-style) | metrics within thresholds | report with metric values (average 3 runs) | -| Smoke test | deployed service alive and wired | HTTP codes + latency | - -## Minimum proof by change type - -| Change type | Minimum | Rubric | -|---|---|---| -| Frontend UI | behavior-level test or natural E2E navigation + a11y scan; visual diff if layout-sensitive | `rubrics/frontend-web.md` | -| Mobile UI | simulator-driven flow of the changed journey | `rubrics/mobile-app.md` | -| Backend API | integration test through the real HTTP layer incl. error-path and authz cases | `rubrics/backend-api.md` | -| Data / schema migration | dry run + row counts + one domain-invariant query + tested rollback | `rubrics/data-migration.md` | -| CLI / script | exit-code contract + idempotency (run twice) + `--dry-run` if state-mutating | `rubrics/cli-script.md` | -| Background job | double-invoke idempotency + retry/DLQ path | `rubrics/background-job.md` | - -## Rules - -- **Every `AC#` names the check that proves it.** Passing tests that don't - map to a criterion prove nothing about the criterion; coverage numbers are - not evidence. -- **Evidence over assertion.** A pass is the command, its quoted output, and - its exit code — never the implementer's claim. Screenshots supplement; - they don't prove the interaction path. -- **Prefer the durable guard.** When verification (or a bug) exposes a class - of violation, encode it as a custom lint/static rule — it re-verifies every - future change for free. This is the strongest "prevention criteria" for - Bug Reports. -- **Test behavior, not implementation.** Assertions target public API and - rendered output; a test that exercises only mocks of code we own verifies - the mock. Exercise at least one real boundary. -- **A flaky gate is a finding, not a pass.** A check that needed retries to - go green gets reported, not retried into silence. diff --git a/tyler/templates/AGENTS.md b/tyler/templates/AGENTS.md deleted file mode 100644 index b5b1ba9..0000000 --- a/tyler/templates/AGENTS.md +++ /dev/null @@ -1,50 +0,0 @@ -# AGENTS.md — template - -> Copy this file to a codebase's root as `AGENTS.md` and fill in each section. -> This is the **universal** instruction file: every coding agent (Claude, -> Codex, or any other harness) reads it. Keep anything harness-specific out — -> `CLAUDE.md` points here and adds the Claude-only parts. Delete this header -> block after copying. - -## What this project is - -One or two sentences: what the product does, who uses it, and the one thing an -agent must not break. - -## Commands - -The exact commands, not descriptions. Agents run these verbatim. - -```bash -# install: <e.g. npm install> -# dev server: <e.g. npm run dev> -# typecheck: <e.g. npm run typecheck> -# lint: <e.g. npm run lint> -# format: <e.g. npm run format> -# tests: <e.g. npm run test> -# build: <e.g. npm run build> -``` - -## Architecture - -The map an agent needs before editing — keep it to what's load-bearing: - -- Top-level layout: which directory owns what. -- The request/data flow in one paragraph (e.g. route → service → repository). -- Where new code of each common kind goes (endpoint, component, migration, - background job). - -## Conventions - -Only rules an agent would otherwise get wrong — not a style guide: - -- Patterns to follow (name the canonical example file for each). -- Things that look editable but aren't (generated files, vendored code). -- Error-handling and logging idioms. - -## Boundaries - -- Commands that must never run automatically (destructive ops, deploys, - production migrations). -- Files/paths that are off-limits. -- Secrets: where config lives; never commit values. diff --git a/tyler/templates/CLAUDE.md b/tyler/templates/CLAUDE.md deleted file mode 100644 index b0e102c..0000000 --- a/tyler/templates/CLAUDE.md +++ /dev/null @@ -1,34 +0,0 @@ -# CLAUDE.md — template - -> Copy this file to a codebase's root as `CLAUDE.md` and fill in each section. -> Universal instructions live in `AGENTS.md` (single copy, both harnesses); -> this file adds only what is Claude-specific. Delete this header block after -> copying. - -See @AGENTS.md for the project overview, commands, architecture, conventions, -and boundaries. Everything there applies here — do not duplicate it. - -## Work-item tracking - -The workflow skills (`/create-feature`, `/create-epic`, `/create-issue`, -`/do`) publish every work item as a GitHub issue and mirror its artifacts to -a Notion work item (see the `notion` skill). - -```yaml -github_repo: <owner>/<repo> # where gh issue create targets; omit to use the current repo -# notion_data_source: <ID or URL> # OVERRIDE only — the default lives in the -# # notion skill's config.yaml; set this only -# # if this repo publishes to a different database -``` - -Work-item artifacts (item.md, refs/, plan.md, wrapup.md) live locally under -`./tmp/<id>/` during a run and in the Notion work item durably. `./tmp/` is -scratch — never commit it. - -## Claude-specific notes - -- Sub-agent and skill definitions come from the user-level setup - (`~/.claude/`, `~/.references/`, `~/.codex/`) — this repo does not carry - its own. -- <anything else only Claude needs: MCP servers to prefer, browser-automation - notes for the frontend-verifier agent, model-routing exceptions for this project>