From fc6f614408c21ff8186cf7a877c7cbf7f882ea6d Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Fri, 13 Nov 2026 02:44:48 +1100 Subject: [PATCH] docs(agents): drop the December rule, loosen two decision rules, correct the services table --- CLAUDE.md | 35 ++++++++++++++++------------------- 1 file changed, 16 insertions(+), 19 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 996b8b7b7..577380262 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -12,13 +12,6 @@ review or action. A repository is an optional input to a workflow, not the point of the product. A forge is one of many inputs or outputs; core code never assumes one. - The goal until 1 December is a -production-ready archie-core, including the features the maintainer is still -adding. Speak up when a request competes with something more urgent: a bug that -loses work, a failure that shows nothing, a security gap, a broken setup path. -Give the trade-off in a sentence or two and suggest whether the request belongs -in the backlog. Don't hold work back on your own judgement. - ## Services and layout Each service is a gRPC contract in `proto//v1`, generated into @@ -27,13 +20,17 @@ and calls its composition root in `internal/app/`. | Binary | Serves | Dials | | --- | --- | --- | -| `archie-state-store` | State Store and Control Plane contracts; owns the task and control-plane PostgreSQL tables | PostgreSQL | -| `archie-gateway` | Chat, conversation state, task tools | State Store | -| `archied` | Scheduling, workflow runs, task containers, Daemon contract | State Store, Gateway, Messaging | -| `archie-messaging` | External channel frontends | Gateway | -| `archie-ui` | Dashboard HTTP API (`internal/webui`) and the embedded SPA | State Store, Gateway, daemon | +| `archie-state-store` | State Store and Control Plane contracts; owns the task and control-plane tables | PostgreSQL | +| `archie-gateway` | Chat contract; owns the conversation tables | State Store, PostgreSQL | +| `archied` | Daemon contract; scheduling, workflow runs, task containers | State Store, Gateway, Messaging, NATS | +| `archie-messaging` | Messaging contract; external channel frontends | State Store, Gateway | +| `archie-ui` | Dashboard HTTP API (`internal/webui`) and the embedded SPA | State Store, Gateway, Daemon, Messaging | | `archie-agent` | The worker inside each task container | NATS | +Forge, channel and secret-engine contracts are extension boundaries, not +services: a core binary starts the extension as a plugin process and dials it. +`archied` also runs the State Store's backup and restore during a host update. + `internal/domain` holds behaviour and interfaces; `internal/infrastructure` implements them. Every instruction sent to a model is a file in `internal/prompts`, read through that package; never inline a prompt in code. @@ -67,13 +64,13 @@ When sources disagree, the higher one wins: ## How to decide -- **Broken beats new.** A bug that blocks work gets fixed now, with the smallest - change that unblocks it. No design docs and no new mechanism. -- **Cheapest option first.** Before building, name the smallest change that - solves the problem, including changing configuration or deleting something. If - your plan adds a new mechanism (RPC, process, binary, abstraction, config - field, tool) or grows past about 100 lines, stop and assess whether you're - taking the path of least resistance. +- **Broken comes first.** A bug that blocks or loses work goes ahead of new + features. Fix the cause. When that's a bigger job, unblock with a small change + first and file the proper fix rather than stopping there. +- **Cheapest option first.** Before building, consider the smallest change that + solves the problem, including changing configuration or deleting something. + A new mechanism (RPC, process, binary, abstraction, config field, tool) is + fine when it's the right design; say why the smaller option wasn't enough. - **Delete before adding.** Unused code, dead paths, fallbacks nobody takes and features nobody runs get removed, not maintained. Solo project, single user: breaking changes need no compatibility shims.