jac/so-many-crows
1
0 Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

Merge pull request #54 from jacisjake/docs/handoff-2026-10-28

Browse Source 
docs(handoff): state after epics A–E
This commit was merged in pull request #54.
This commit is contained in:
jacisjake authored and GitHub committed 2026-10-28 09:24:14 -06:00
2 parents 51b0a7e763 bad0602199
commit 74da01805a
1 file changed
+15 -11
Download Patch File Download Diff File Expand all files Collapse all files
CLAUDE.md
+15 -11
View File
@@ -1,6 +1,6 @@
# So Many Crows: handoff for the next agent # So Many Crows: handoff for the next agent
Read this whole file before changing anything. It is the single source of truth for where the project stands, why it is built this way, and what comes next. Last updated 2026-10-27: same day, the roadmap pivoted toward the chatroom spec (section 8) — the pivot came from `CHATROOM_SPEC.md`, `GROKBOT_NOTES.md` and `JEV_STRATEGIES.md`. Read this whole file before changing anything. It is the single source of truth for where the project stands, why it is built this way, and what comes next. Last updated 2026-10-28: chatroom epics A–E are merged (section 8); the pivot came 2026-10-27 from `CHATROOM_SPEC.md`, `GROKBOT_NOTES.md` and `JEV_STRATEGIES.md`. The repo now has a GitHub remote (`jacisjake/so-many-crows`) and lives by the epic flow: issues/PRs in project board 1, one PR per task with falsifiable red→green tests.
## 1. What this is ## 1. What this is
@@ -8,7 +8,7 @@ So Many Crows is a multi-agent app for one owner, Smokey (Jacob Madsen). You han
**That pipeline is what runs today, but the direction has changed** (2026-10-27): the target is a conversation-driven chatroom where crows claim work in a nest, two new roles appear (assistant crow, Chief of Staff crow), and Jev audits expectations and nudges stalled work. Read `CHATROOM_SPEC.md` (the design, with `[decided]`/`[proposed]` marks), `GROKBOT_NOTES.md` (its evidence base) and `JEV_STRATEGIES.md` (what the classifier can do). The pipeline isn't deleted — it stays the working app until chatroom work replaces it, and nests, the trust ledger, guardrails, SSE, personas and the flight log all carry over. **That pipeline is what runs today, but the direction has changed** (2026-10-27): the target is a conversation-driven chatroom where crows claim work in a nest, two new roles appear (assistant crow, Chief of Staff crow), and Jev audits expectations and nudges stalled work. Read `CHATROOM_SPEC.md` (the design, with `[decided]`/`[proposed]` marks), `GROKBOT_NOTES.md` (its evidence base) and `JEV_STRATEGIES.md` (what the classifier can do). The pipeline isn't deleted — it stays the working app until chatroom work replaces it, and nests, the trust ledger, guardrails, SSE, personas and the flight log all carry over.
Working copy: `~/Projects/so-many-crows` on Smokey's Mac (Apple silicon, macOS). There is **no Git remote yet** (see section 8). Do not confuse it with `~/Projects/crows`, an unrelated older folder: never touch it. Working copy: `~/Projects/so-many-crows` on Smokey's Mac (Apple silicon, macOS). Remote: `git@github.com:jacisjake/so-many-crows.git` (main is protected by convention, not settings: land via PR merge). Do not confuse it with `~/Projects/crows`, an unrelated older folder: never touch it.
## 2. How to work with Smokey ## 2. How to work with Smokey
@@ -108,9 +108,10 @@ UI development: run the server, then `cd ui && npm run dev` (Vite proxies `/api`
Guardrail defaults (`guardrails.go`): 5 crows in flight, murder of 3, 20 items per list, 2,000 characters per item, 4 subtasks, 20,000 tokens per item, 100,000 per list, 60-second crow timeout, promote after 10, 5 requests per minute, cooldown 30 seconds doubling to 1 hour, 2 banter calls per list, and (chatroom) a **3-nudge loop guard per expectation** — after three nudges with no new content from the crow, the harness stops and summarizes to the owner (CHATROOM_SPEC.md section 7). Guardrail defaults (`guardrails.go`): 5 crows in flight, murder of 3, 20 items per list, 2,000 characters per item, 4 subtasks, 20,000 tokens per item, 100,000 per list, 60-second crow timeout, promote after 10, 5 requests per minute, cooldown 30 seconds doubling to 1 hour, 2 banter calls per list, and (chatroom) a **3-nudge loop guard per expectation** — after three nudges with no new content from the crow, the harness stops and summarizes to the owner (CHATROOM_SPEC.md section 7).
## 6. Verified state (2026-10-27) ## 6. Verified state (2026-10-28)
- All 31 tests pass with `-race`. - All 113 tests pass with `-race`.
- Chatroom epics A–E merged (issues #3–#45 closed): nest loop with Jev-first kind tagging; dispatch modes solo/conspiracy/split with first-claim arbitration, invited lenses, divergence nudges, @Elder synthesis and trust-gated speaking; Quill (assistant: status from nest history, relay, `ask_owner` fail-safe decisions); Boss (spins registry crows under `MaxSpunCrows`, creates nests); Sentry watchdog (above-band Jev noul verdicts flag + quarantine; reinstate/retire escalate through `ask_owner`; Sentry earns `triage/watch` trust). New roles decided and shipped: **Quill** (assistant crow), **Boss** (Chief of Staff). Live wiring so far is proven with mock/scripted brains and fake Jev servers only.
- Live test with real keys: Jev triaged "Should we launch a CLI or a web app first" as murder (91%) and analysis (100%) in 195 ms; Hugin, Munin and Corvina answered on three different free models; the Elder merged in character; after a rejection, Soot generated: *"Hugin, another grand scheme foiled? Perhaps the CLI is the tiny bird worth chasing."* Total 6,257 tokens. - Live test with real keys: Jev triaged "Should we launch a CLI or a web app first" as murder (91%) and analysis (100%) in 195 ms; Hugin, Munin and Corvina answered on three different free models; the Elder merged in character; after a rejection, Soot generated: *"Hugin, another grand scheme foiled? Perhaps the CLI is the tiny bird worth chasing."* Total 6,257 tokens.
- UI end-to-end tested headless at desktop and phone widths: nests, borrowing, approvals, reactions, prank cooldown, banter asides. No console errors. - UI end-to-end tested headless at desktop and phone widths: nests, borrowing, approvals, reactions, prank cooldown, banter asides. No console errors.
- **Not yet done:** Smokey has not yet used the app himself through `start.command` with real crows. It still matters (section 8, step 6), but the chatroom work leads now. - **Not yet done:** Smokey has not yet used the app himself through `start.command` with real crows. It still matters (section 8, step 6), but the chatroom work leads now.
@@ -130,14 +131,17 @@ Guardrail defaults (`guardrails.go`): 5 crows in flight, murder of 3, 20 items p
The roadmap pivoted (2026-10-27): the chatroom spec is now the direction. Do one step at a time. Show the result. Ask before starting the next. **Contracts first** still applies: change `EVENTS.md` before UI or server code for any chatroom message kind or event. The roadmap pivoted (2026-10-27): the chatroom spec is now the direction. Do one step at a time. Show the result. Ask before starting the next. **Contracts first** still applies: change `EVENTS.md` before UI or server code for any chatroom message kind or event.
1. **Resolve the spec's open blockers before code** (Smokey decides, not the agent): message-kind tagging (Jev can tag it — see `JEV_STRATEGIES.md` strategy 1), the nudge loop guard (nudges count against the nest budget; a miss must not restart work forever), first-claim-wins arbitration when two crows claim at once, and Sentry/Elder's fate (spec open question 4). Done since the pivot (epics A–E, 2026-10-28): spec blockers resolved; nest conversation loop (spec step 1); dispatch (modes, arbitration, conspiracy, divergence, Elder, trust gates, guardrails — including the `Flock.reserve` fix, saturated flocks now honor context); assistant crow Quill (step 2); Boss + Sentry watchdog (step 4's orchestration halves).
2. **Chatroom build plan step 1** (`CHATROOM_SPEC.md` section 12): one nest, owner plus two crows, event-driven; `say`, `request`, `claim`, `deliver` with @-addressing; mock brain first, live models after it works.
3. **The assistant crow** as the owner's default chat, relaying into the nest.
4. **The expectation ledger plus nudges**, two checks first (promise kept, single owner), Jev questions per `JEV_STRATEGIES.md`. The "log-only experiment" there (kind + who-responds, no acting) can run beside current pipeline traffic to collect calibration data.
5. **The COS crow** spinning up crows on request. Then opt-in debate mode, then visible budgets.
6. **Smokey's first hands-on session** with the current pipeline stays worth supporting — if he runs `start.command`, watch the Terminal and `./crows log` and fix what he hits (1,000-a-day free-model limit).
Paused by the pivot (resume only if Smokey asks): provider comparison beyond pinning a model (the pinned `CROWS_MODEL` stays); CLI banter printing; review queue for "regular" trust; threads; Rive; web-search capability; login; GitHub; GCP. GitHub note for when it happens: Smokey creates an empty repo `jacisjake/so-many-crows`, commit email must be `150986568+jacisjake@users.noreply.github.com`. Next, in order:
1. **The expectation ledger plus nudges** (spec step 3, `CHATROOM_SPEC.md` section 7): extraction into a ledger, the first two checks (promise kept, single owner), Jev questions per `JEV_STRATEGIES.md`; the 3-loop guard already exists — this gives it something to watch. The "log-only experiment" (kind + who-responds, no acting) can run beside nest traffic to collect calibration data.
2. **Live-model chatroom session**: drive Quill relay → conspiracy → nudge → Boss spin-up → Sentry flag → reinstate end to end with real models before demoing to Smokey (mock-only today).
3. **Opt-in debate mode** (spec step 5, section 8) — first tasks of an Epic F.
4. **Visible budgets** in the UI (spec step 6, section 9). UI rules apply: screenshots at ~400px and desktop.
5. **Smokey's first hands-on session** with the current pipeline stays worth supporting — if he runs `start.command`, watch the Terminal and `./crows log` and fix what he hits (1,000-a-day free-model limit).
Paused (resume only if Smokey asks): provider comparison beyond pinning a model (the pinned `CROWS_MODEL` stays); CLI banter printing; review queue for "regular" trust; threads; Rive; web-search capability; login; GCP. GitHub happened: remote `jacisjake/so-many-crows`, commit email must stay `150986568+jacisjake@users.noreply.github.com`.
## 9. Conventions ## 9. Conventions