@lawaty/lacode 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -9,8 +9,50 @@ commit as the changelog entry it describes.
 
 ## [Unreleased]
 
+## [0.7.0] — standing instructions move to the project AGENTS.md
+
+### Changed
+
+- **Standing instructions moved to the project root `AGENTS.md`.** The
+  `/manager-directive` command and the hidden `manager` agent are gone,
+  replaced by `/agent-instructions` and the hidden `instructions` agent. The
+  `instructions` agent is the only writer of the project's root `AGENTS.md`;
+  every other agent is permission-denied on that path. The plugin no longer
+  injects a standing instruction — standing rules now live in `AGENTS.md`
+  itself. `ensureManagerFile` is gone.
+
+### Removed
+
+- `/manager-directive` command
+- `manager` agent
+- `src/lib/manager-directive.ts`
+- `applyInstructions` / `STANDING_INSTRUCTION` / `CURRENT_STATE_RULE` from
+  `src/commands.ts`
+- The `ensureManagerFile` call from `src/index.ts`
+
+## [0.6.0] — a client-only /pool command, and README corrections
+
+### Added
+
+- **`/pool <instruction>`** — a client-only command that rewrites this machine's
+  pool override, `~/.config/lacode/pool.txt`, from a short instruction. It
+  applies the loader's rules (at most 4 distinct slots, weight in (0, 100], line
+  order is the rotation), writes the WHOLE file rather than a patch, reports the
+  before → after table, and reminds you that nothing hot-reloads.
+
+### Fixed
+
+- README: the count of agent keys deliberately *not* injected was stated as
+  three, not the five `docs/CONFIGURATION.md` lists; and the `lacode` CLI section
+  was missing `version`, `update`, `receive` and `tunnel setup`.
+  `docs/INSTALL.md`'s CLI list gained `version` and `update`. A stale test title
+  ("three commands") was corrected to match what it asserts.
+
 ## [0.5.0] — a user-only /manager-directive, instant limit failover, and the longcat preset
 
+Released on the npm **`beta`** dist-tag (not `latest`) while the project is
+experimental; `latest` remains 0.4.2.
+
 ### Added
 
 - **`/manager-directive <text>`** — a client-only command that runs a hidden
@@ -193,7 +235,9 @@ commit as the changelog entry it describes.
 
 - First published release: pooled subagents over a shared set of models.
 
-[Unreleased]: https://github.com/lawaty/lacode/compare/v0.5.0...HEAD
+[Unreleased]: https://github.com/lawaty/lacode/compare/v0.7.0...HEAD
+[0.7.0]: https://github.com/lawaty/lacode/compare/v0.6.0...v0.7.0
+[0.6.0]: https://github.com/lawaty/lacode/compare/v0.5.0...v0.6.0
 [0.5.0]: https://github.com/lawaty/lacode/compare/v0.4.2...v0.5.0
 [0.4.1]: https://github.com/lawaty/lacode/compare/v0.4.0...v0.4.1
 [0.4.0]: https://github.com/lawaty/lacode/compare/v0.3.0...v0.4.0

package/README.md

@@ -2,6 +2,11 @@
 
 > Ultimate opencode setup for Go users
 
+> **Beta — experimental, changing fast.** LaCode ships on the npm **`beta`**
+> dist-tag rather than `latest`, so nothing pulls it by accident: install
+> `@lawaty/lacode@beta`, or pin an exact version. Interfaces here can change
+> between releases without a major bump.
+
 LaCode is an opencode plugin. It routes delegated work onto a weighted pool of
 cheap models instead of the expensive one, reaps subagents that hang without
 telling anyone, keeps a maintained map of your repository so agents stop
@@ -128,13 +133,14 @@ option is optional:
 
 opencode's plugin cache is **write-once**: it resolves `@lawaty/lacode` to an
 exact version once and never re-resolves — not on restart, not with
-`opencode plugin -g -f`, not with a range pin, not with a tagged config spec. So
-LaCode keeps itself current instead (US-27): at startup it compares its own
-version to npm's `latest` (at most once per ~6h, silent when offline) and, when
-behind, reinstalls its own cache entry in the background using the opencode
-binary — no npm or bun required. The running session keeps its loaded code; the
-new version takes effect on the next start, and the log says so. Run
-`lacode update` to do it on demand, or `lacode update --check` to just report.
+`opencode plugin -g -f`, not with a range pin, not with a tagged config spec.
+Nothing in the host re-resolves it, so the plugin owns its own currency
+(US-27): at startup LaCode compares its own version to npm's `latest` (at most
+once per ~6h, silent when offline) and, when behind, reinstalls its own cache
+entry in the background using the opencode binary — no npm or bun required.
+The running session keeps its loaded code; the new version takes effect on the
+next start, and the log says so. Run `lacode update` to do it on demand, or
+`lacode update --check` to just report.
 
 ### Which LaCode is running
 
@@ -149,7 +155,7 @@ lacode version
 version    0.4.1
 root       /home/you/lacode
 source     checkout
-commit     9446c88 (dirty)
+commit     <hash> (dirty)
 dist       current
 config     /home/you/.config/opencode/opencode.jsonc
 plugin     file:///home/you/lacode/dist/index.js
@@ -158,14 +164,15 @@ this copy  yes — opencode loads this copy
 
 `npm ls -g @lawaty/lacode` answers a different question. It reports the package
 opencode resolves *by name*, which is not necessarily the one running: a config
-may load the plugin by absolute path, in which case a stale global install can
-sit there reporting a version nothing uses. So this command reads your actual
-`plugin` array and says whether it resolves to the copy speaking.
+may load the plugin by absolute path, and a global install can sit there
+reporting a version nothing uses. So this command reads your actual `plugin`
+array and says whether it resolves to the copy speaking.
 
 `source` distinguishes a git checkout from an npm install, `commit` and the
 dirty flag name what the code was built from, and `dist` is the trap worth
 knowing about — opencode loads `dist/index.js` while you edit and pull `src/`,
-so a `git pull` can leave you running yesterday's build with nothing failing.
+so a `git pull` can leave you running a build that differs from the installed
+package, with nothing failing.
 When it reports `stale`, rebuild with `npm run build`. No network is touched;
 `lacode update --check` is what asks npm whether something newer exists.
 
@@ -178,12 +185,12 @@ only thing that works: naming a variant lets the caller choose the provider
 directly, which is exactly what the rotation and the per-slot ceiling exist to
 prevent, so it is refused.
 
-Five commands: `/context-init`, `/context-update`, `/context-review`,
-`/lacode-doctor` and `/manager-directive`. Everything is added **only when your
-config does not already
+Six commands: `/context-init`, `/context-update`, `/context-review`,
+`/lacode-doctor`, `/agent-instructions` and `/pool`. Everything is added **only
+when your config does not already
 define it** — an agent or command you wrote yourself is left byte-identical,
 never patched or partially merged. `{"enabled": false}` turns the whole thing off
-without leaving a trace. The exact injection list, and the three keys that are
+without leaving a trace. The exact injection list, and the five keys that are
 deliberately *not* injected, are in
 [docs/CONFIGURATION.md](docs/CONFIGURATION.md#what-gets-injected).
 
@@ -213,54 +220,46 @@ are reading:
 /context-update    # incremental refresh; accepts a focus, e.g. /context-update src/payments
 /context-review    # audit it for staleness, contradictions, duplication and bloat
 /lacode-doctor     # check the pool, model resolution and the OmniRoute gateway. Report only
-/manager-directive # record a managerial direction in manager.md — client-only, see below
+/agent-instructions # apply a client instruction to the project's AGENTS.md — client-only, see below
+/pool              # rewrite the pool slot table in ~/.config/lacode/pool.txt; restart to apply
 ```
 
 The map is local and untracked — it describes your checkout on your machine, so
 it is not committed and not synced. If it is missing, agents check, find
-nothing and carry on as before. What this buys is tokens not spent
+nothing and carry on without it. What this buys is tokens not spent
 re-discovering structure; as with everything else here, no savings percentage is
 published, because none has been independently measured. The mechanism, the
 permission rule that makes one writer possible, and what the log lines mean are
 in [docs/CONTEXT.md](docs/CONTEXT.md).
 
-## Managerial directions
+## Standing instructions
 
-The plugin creates `manager.md` in `.opencode/context/` for you, and never
-overwrites it once it exists. It is your file: it records what you want done
-and how you want it approached — what is being worked on, what comes next,
-what you have settled, and what every agent should keep in mind. It says
-nothing about where code lives, so it can never contradict the code, and
-within that domain it outranks the five generated files and any agent's
-inference about what matters right now.
+The project's root `AGENTS.md` is your own statement of intent: it records
+what you want worked on and how you want it approached. It says nothing about
+where code lives, so it can never contradict the code, and within that domain
+it outranks the five generated context files and any agent's inference about what
+matters right now.
 
 The file is per-clone and not committed, so it is yours rather than shared
-team state. It has no fixed schema — the headings below are a convenience.
-Add your own; every heading in it is treated as direction.
-
-- `## Current`: what is being worked on right now. Rewrite it rather than
-  appending, so it does not become a running history. If the file passes
-  roughly 150 lines, run `/context-review`.
-- `## Next`: what comes next, in order.
-- `## Confirmed`: what you have personally ratified. Treat these as settled
-  decisions, not as permission to skip reading the code.
-- `## Instructions`: standing direction beyond the current task — priorities,
-  things to care about, constraints that are not obvious from the code.
-
-**Who may write it.** The context agent is explicitly permission-denied from
-touching this path, so the automatic post-session run can never alter it. An
-agent working in your live session may write it only when you explicitly ask
-it to, and only what you asked for — never on its own initiative, and never
-to "keep it up to date".
-
-**`/manager-directive` — the one sanctioned write path.** Type
-`/manager-directive <text>` and the `manager` agent applies your instruction to
-`manager.md` — recording it, moving it between sections, rewriting `## Current`,
-whatever you asked — then reports what it changed. It is a normal agent turn, not
-a dead append: tell it what you want and review the result. The `manager` agent
-is the one agent permitted to edit that file, its grant is scoped to
-`manager.md` alone, and no other agent can spawn it — the command is the only
-route in.
+team state. There is no fixed schema and no prescribed headings — you write
+whatever you like, and every heading you add is treated as direction.
+
+Anything you have recorded there is read before work starts, and what you have
+recorded is treated as settled by the agents — not as permission to skip
+reading the code.
+
+**Who may write it.** Every agent is explicitly permission-denied from
+touching this path, so no automatic run can ever alter it. The one exception
+is the hidden `instructions` agent, reachable solely through the
+`/agent-instructions` command.
+
+**`/agent-instructions` — the one sanctioned write path.** Type
+`/agent-instructions <text>` and the `instructions` agent applies whatever
+instruction you have given to `AGENTS.md`, then reports what it changed. It is
+a normal agent turn, not a dead append: tell it what you want and review the
+result. The `instructions` agent is the one agent permitted to edit that file,
+its grant is scoped to `AGENTS.md` alone, and no other agent can spawn it —
+the command is the only route in.
 
 ## Cost
 
@@ -333,6 +332,13 @@ must never be able to fail the process that tried to notify you. `lacode forward
 HOST -- COMMAND` runs a command on another host over ssh and exits with its
 status.
 
+The full CLI is `notify`, `forward`, `doctor`, `version`, `update`, `receive`
+and `tunnel setup`. `version` reports which copy of LaCode is running — and
+whether opencode is loading that same copy — and `update [--check]` refreshes an
+installed one. `receive` is the desktop end of the tunnel (the forced command a
+remote key is restricted to) and `tunnel setup` provisions the key and the
+forward.
+
 Configuration, the payload format, the receiver contract and holding the forward
 open are in [docs/TUNNEL.md](docs/TUNNEL.md).
 
@@ -372,7 +378,7 @@ gitignored; `prepack` builds it, so `npm pack` cannot produce a stale tarball.
 
 The sources are TypeScript and the tests import `src/` directly (node strips the
 types outside `node_modules`, which is exactly where the tests live), so the
-loop stays: edit `src/`, run `npm test`. Only the packaging fixtures build, and
+loop is: edit `src/`, run `npm test`. Only the packaging fixtures build, and
 they call the same `scripts/build.mjs` the tarball does.
 
 `tests/stories/` holds the story suites and `tests/stories/coverage.test.mjs`

package/dist/agents.js

@@ -46,8 +46,8 @@ var USER_MODELS_PATH = join2(USER_CONFIG_DIR, "pool.json");
 var USER_MODELS_TXT = join2(USER_CONFIG_DIR, "pool.txt");
 var CHILD_MEMORY_MS = 30 * 6e4;
 
-// src/lib/manager-directive.ts
-var MANAGER_AGENT_NAME = "manager";
+// src/lib/agent-instructions.ts
+var AGENT_INSTRUCTIONS_WRITER = "instructions";
 
 // src/agents.ts
 var POOLED_BASES = ["explore", "implement", "context"];
@@ -85,14 +85,28 @@ different number.
 
 The pooled agents are the ONLY route to investigation and implementation. If the
 pool cannot serve a spawn \u2014 every slot cooling or exhausted, spawns repeatedly
-failing, or a runtime message saying no slot is available \u2014 that is a STOP
-condition, not a reason to do the work yourself.
+failing, or a runtime message saying no slot is available \u2014 that is not a reason
+to do the work yourself, and not a reason to stop and ask.
+
+**Retry.** A refused or cooling slot is transient and costs you nothing but a
+turn. Spawn the bare base again. Do not escalate a \`-N\` variant when a refusal
+names one \u2014 the refusal means the pool has a routing problem, not that you
+picked the wrong number.
+
+Retry is always available and never wrong, which is why it is the default. But
+"never wrong" is not "sufficient": looping silently against a pool with every
+model cooling goes nowhere and burns the slot doing it. So separate the two
+failures. **Transient** \u2014 a cooldown, a rate limit, one slot at its ceiling \u2014
+means retry. **Persistent or structural** \u2014 every slot cooling, the same spawn
+failing repeatedly with the same error, a malformed model id \u2014 means stop
+retrying and *report* it: say what failed (slot, model, error) and continue
+with whatever else the task needs, or ask the user. Surface the failure; do not
+spin on it and do not let it end the whole task.
 
 **Never fall back to reading, grepping, exploring or implementing on your own.**
-Do not "just quickly" inspect a file because a spawn failed. Stop, say what
-failed (slot, model, error), and ASK the user how to proceed: wait for a slot to
-recover, change the pool, or obtain explicit permission to work without
-subagents. A failed spawn is never permission, and silence is not consent.
+Do not "just quickly" inspect a file because a spawn failed. A failed spawn is
+never permission, and silence is not consent \u2014 that part does not change with
+cooldowns, and no amount of retrying grants it.
 
 \`edit\`/\`write\`/\`bash\` stay yours for applying and verifying what a subagent
 returned \u2014 never as a substitute for a spawn that could not run.
@@ -171,7 +185,12 @@ missing). Never paste context file contents into the report.`,
       "edit": {
         "*": "allow",
         "*/.opencode/context/**": "deny",
-        ".opencode/context/**": "deny"
+        ".opencode/context/**": "deny",
+        // AGENTS.md has exactly one writer, the hidden `instructions` agent.
+        // opencode resolves a file permission with findLast over the map's own
+        // entry order, so this deny has to come AFTER the broad "*" allow above.
+        "AGENTS.md": "deny",
+        "*/AGENTS.md": "deny"
       },
       "bash": "allow",
       "webfetch": "deny",
@@ -414,7 +433,11 @@ if the blocker is understanding rather than execution, report that instead.`,
       "edit": {
         "*": "allow",
         "*/.opencode/context/**": "deny",
-        ".opencode/context/**": "deny"
+        ".opencode/context/**": "deny",
+        // AGENTS.md is written by the hidden `instructions` agent alone; LAST
+        // match wins, so this deny must sit after the broad allow above.
+        "AGENTS.md": "deny",
+        "*/AGENTS.md": "deny"
       },
       "bash": "allow",
       "webfetch": "allow",
@@ -458,29 +481,14 @@ You own exactly these five files and nothing else:
   during work that are not already recorded in the project's own decision
   log. Concise; variable length.
 
-A sixth file sits in the same directory and is not yours:
-\`.opencode/context/manager.md\`. It is the client's own statement of intent
-\u2014 what is being worked on, what comes next, what they have settled, and
-what every agent should keep in mind. It deliberately says nothing about
-where code lives: your five files and the source itself are the only
-authority on that, and this file never contradicts them. It has no fixed
-schema \u2014 read the whole file, because every heading in it is direction.
-
-You never create, edit, rename, or delete it \u2014 not at bootstrap, not in an
-update, not in a review, and not when a run of your own concludes the work
-has moved on. The client edits it, or asks a live agent to edit it on
-their explicit instruction. Either way it is their hand, never yours.
-
-Read it before you write anything. Its \`## Current\` and \`## Next\`
-sections tell you what is actually being worked on, and \`## Confirmed\`
-tells you which of your facts the client has ratified. A fact you are
-writing that appears under \`## Confirmed\` may be stated plainly, without
-a confidence marker; anything else follows your normal rules \u2014 infer
-carefully, mark uncertainty. Never copy its content into the five files.
-
-A missing or empty section is not an instruction. It means the client has
-not said, not that you may assume anything \u2014 proceed exactly as you would
-without the file.
+# Current-state only
+
+Every file you write states only the current arrangement and the reason it
+holds, in the present tense. No "used to", "previously", "before this",
+migration notes or deprecation narrative \u2014 history belongs in the project's
+changelog, not in your map. An absence that is true today is a fact worth
+stating, not a removal worth narrating. When a past state is worth keeping,
+record it briefly in \`changelog.md\` instead.
 
 Never create, modify, or delete anything outside \`.opencode/context/\`. The
 \`edit\` permission enforces this. Do not attempt to work around it with bash.
@@ -516,11 +524,6 @@ Then write the five files. For each significant subsystem, give a short
 reason. This is the single most valuable thing you produce: where an agent
 should open its editor next.
 
-manager.md is created for the client by the plugin, not by you; if it is
-missing anyway, mention once in your final report that they can add it
-themselves to record what is being worked on, what comes next, and what
-they have ratified. Never create it.
-
 # Incremental update
 
 Trigger: \`.opencode/context/\` exists and work has just been done here.
@@ -548,14 +551,6 @@ that is already stated in another context file \u2014 one fact has one home, and
 the other files link to it. If nothing material changed, make no edits and
 report "no update needed".
 
-Before editing, re-read manager.md: its \`## Current\` and \`## Next\`
-sections tell you what the client is actually working on, and its
-\`## Confirmed\` section settles which of your facts are ratified. If what
-you are about to write would place the code somewhere the client never
-described, trust the code, make the edit the code justifies, and report
-the gap in your final message \u2014 never reconcile the two sides silently,
-and never edit manager.md to close it.
-
 # Minimal exploration
 
 Default shape:
@@ -650,14 +645,10 @@ Audit the five files for:
 - duplicated information \u2014 one canonical place per fact
 - missing canonical entry points for significant subsystems
 - unsupported assumptions \u2014 anything unmarked that you cannot verify
-- manager.md, if present: is \`## Current\` and \`## Next\` still true of
-  recent work, is every \`## Confirmed\` entry still true of the code, has
-  it outgrown roughly 150 lines \u2014 report findings, but never edit, prune,
-  or reorganize it; that is the client's call
 
-Fix problems only in the five files you own \u2014 never in manager.md, which
-belongs to the client. Never modify source code during a review. Report
-what you found, what you fixed, and what you could not verify.
+Fix problems only in the five files you own. Never modify source code
+during a review. Report what you found, what you fixed, and what you
+could not verify.
 
 # Reporting
 
@@ -675,9 +666,7 @@ Finish with a short report:
       "edit": {
         "*": "deny",
         "*/.opencode/context/**": "allow",
-        ".opencode/context/**": "allow",
-        "*/.opencode/context/manager.md": "deny",
-        ".opencode/context/manager.md": "deny"
+        ".opencode/context/**": "allow"
       },
       "bash": {
         "*": "deny",
@@ -725,58 +714,60 @@ Finish with a short report:
     }
   }
 };
-var MANAGER_AGENT = {
-  description: "Records and edits the client's .opencode/context/manager.md. Run only by the /manager-directive command; no agent or subagent can spawn it.",
+var INSTRUCTIONS_AGENT = {
+  description: "Edits the project's AGENTS.md. Run only by the /agent-instructions command; no agent or subagent can spawn it.",
   mode: "subagent",
   hidden: true,
   temperature: 0.1,
   prompt: `# Role
 
-You maintain one file and nothing else: \`.opencode/context/manager.md\`, the
-client's own statement of intent. You are not a coding agent and you touch no
-other path.
+You maintain one file and nothing else: the project's \`AGENTS.md\`. You are not a
+coding agent and you touch no other path.
 
-You are run only by the \`/manager-directive\` command. The client tells you what
+You are run only by the \`/agent-instructions\` command. The client tells you what
 they want recorded or changed in the file; you apply that to the file and report
 what you changed. You have no permission to edit anything else, and you need
 none.
 
 # The file
 
-It records what is being worked on (\`## Current\`), what comes next
-(\`## Next\`), what the client has ratified (\`## Confirmed\`), and standing
-direction (\`## Instructions\`). The client may use any headings \u2014 every heading
-is direction, and the four above are a convenience, not a schema.
+\`AGENTS.md\` is the project's standing instructions \u2014 the rules every agent and
+subagent runs under. opencode loads it into every session automatically, so what
+you write here steers all work in this project. Keep it about how to work:
+conventions, constraints, priorities, things to always do and never do. It says
+nothing about where code lives \u2014 the source and the context map are the authority
+on that.
 
 # How to apply a directive
 
-- Do what the client asked. "Append", "rewrite Current", "move X to Confirmed",
-  "add a heading" all mean exactly that; a bare sentence goes under the most
-  fitting existing heading, and you create one only if none fits.
+- Do what the client asked: add, rewrite, move or remove exactly what they asked
+  for. A bare sentence goes under the most fitting existing heading, and you
+  create a heading only if none fits.
 - Never invent facts, never record your own inference as the client's, and never
   tidy, reorder or delete content the client did not ask you to touch.
-- \`## Current\` is rewritten, not appended to, so it does not become a running
-  history.
+- Prefer current-state wording: state how things are, not how they changed.
 - Keep the file concise. If it is growing past roughly 150 lines, say so.
+- If \`AGENTS.md\` does not exist, stop and report that there is nothing to edit.
+  Do not create it.
 
 # Reporting
 
 Report briefly what you changed and where. Do not edit any other file.`,
   permission: {
-    // Read is scoped to the one file too: the directive is about manager.md, and
+    // Read is scoped to the one file too: the directive is about AGENTS.md, and
     // nothing else is any of this agent's business.
     read: {
       "*": "deny",
-      ".opencode/context/manager.md": "allow",
-      "*/.opencode/context/manager.md": "allow"
+      "AGENTS.md": "allow",
+      "*/AGENTS.md": "allow"
     },
     glob: "deny",
     grep: "deny",
     list: "deny",
     edit: {
       "*": "deny",
-      ".opencode/context/manager.md": "allow",
-      "*/.opencode/context/manager.md": "allow"
+      "AGENTS.md": "allow",
+      "*/AGENTS.md": "allow"
     },
     bash: "deny",
     webfetch: "deny",
@@ -802,7 +793,7 @@ function buildAgentSet() {
       set[`${base}-${slot}`] = variant;
     }
   }
-  set[MANAGER_AGENT_NAME] = MANAGER_AGENT;
+  set[AGENT_INSTRUCTIONS_WRITER] = INSTRUCTIONS_AGENT;
   return set;
 }
 function applyAgents(cfg, agents = buildAgentSet(), opts = {}) {
@@ -822,7 +813,7 @@ function applyAgents(cfg, agents = buildAgentSet(), opts = {}) {
 }
 export {
   AGENTS,
-  MANAGER_AGENT,
+  INSTRUCTIONS_AGENT,
   POOLED_BASES,
   applyAgents,
   buildAgentSet