@joenandez/academy 0.4.0-rc.1 → 0.5.12

package/README.md

@@ -1,27 +1,17 @@
+
 # Academy
 
-Portable, workspace-aware AI agents, and a published JSON contract that lets a
-client product drive them.
+Portable, workspace-aware AI agents, and a published JSON contract that lets a client product drive them.
 
-An Academy agent is a directory of Markdown, not a framework object. Eight boot
-surfaces describe who the agent is and what it is working on. Academy compiles
-them into one system prompt and launches the agent through Claude Code or Codex
-against whatever project you are in. Every command also answers JSON, so a
-desktop app, a web service, or another CLI can render and manage agents without
-reading Academy's source.
+An Academy agent is a directory of Markdown, not a framework object. Nine boot surfaces describe who the agent is and what it is working on. Academy compiles them into one system prompt and launches the agent through Claude Code or Codex against whatever project you are in. Every command also answers JSON, so a desktop app, a web service, or another CLI can render and manage agents without reading Academy's source.
 
-**Status: `0.4.0-rc.1`, contract version 1.** Academy is not on the npm registry
-yet. Install it from a checkout, as below.
+**Status:** `0.4.0-rc.1`**, contract version 1.** Academy is not on the npm registry yet. Install it from a checkout, as below.
 
 ## Requirements
 
 - **Node.js 18 or later.** The CLI is pure ESM Node with no npm dependencies.
-- **`helm-tasks`** on your `PATH` — the scheduler Academy registers each agent's
-  nightly consolidation job with. This is a hard dependency of the agent
-  lifecycle: without it `create`, `hire --spec`, `delete`, `rename`, and
-  `archive` fail with `runtime_unavailable`. Read commands are unaffected.
-- **A runtime.** `claude` for Claude Code, `codex` for Codex. You need the one
-  you intend to launch. `doctor` reports which are available.
+- `tldr-agents` — Academy registers each agent's nightly consolidation job through `tldr-agents tasks`. Academy resolves the front door from `SUBSPACE_TLDR_AGENTS_BIN`, the Claude plugin registry, or the canonical tldr fallback install. This is a hard dependency of the agent lifecycle: without it `create`, `hire --spec`, `start`, `stop`, `delete`, and `archive` fail with `runtime_unavailable`. Read commands are unaffected.
+- **A runtime.** `claude` for Claude Code, `codex` for Codex. You need the one you intend to launch. `doctor` reports which are available.
 
 ## Install
 
@@ -31,17 +21,13 @@ cd academy
 npm link          # makes `academy` available globally
 ```
 
-There is no build step and no `npm install`. Then confirm the link resolved and
-read the version Academy reports for itself:
+There is no build step and no `npm install`. Then confirm the link resolved and read the version Academy reports for itself:
 
 ```bash
 academy doctor --json
 ```
 
-`doctor` is the discovery command and the version source; there is no
-`academy --version`. Its payload names the supported contract versions, the
-build version, the package root, the agents root, the event log, the published
-command list, runtime availability, and health counts.
+`doctor` is the discovery command and the version source; there is no `academy --version`. Its payload names the supported contract versions, the build version, the package root, the agents root, the event log, the published command list, runtime availability, and health counts.
 
 ## Create and run an agent
 
@@ -53,157 +39,120 @@ academy list
 academy inspect kai --json
 ```
 
-Agents live at `~/.academy/agents/<name>/` by default. Set `AGENTS_ROOT` to put
-them anywhere else; two installs with different roots are fully independent.
+Agents live at `~/.academy/agents/<name>/` by default. Set `AGENTS_ROOT` to put them anywhere else; two installs with different roots are fully independent.
 
-`academy hire` is the interactive alternative to `create`: it runs a domain
-research flow and writes all eight surfaces for you. `academy hire --spec
-<file> --json` does the same headlessly from a JSON specification.
+`academy hire` is the interactive alternative to `create`: it runs a domain research flow and writes the agent's surfaces for you. `academy hire --spec <file> --json` does the same headlessly from a JSON specification.
 
-## The eight boot surfaces
+## The nine boot surfaces
 
-Each agent directory holds eight editable Markdown files. `academy create` and
-every `academy run` compile them into
-`.academy/generated/academy-system-prompt.md` — roughly 5–6k tokens combined.
+Every kind compiles the same nine Markdown files. `academy create` and every `academy run` compile them into `.academy/generated/academy-system-prompt.md`. The operating model comes first in that prompt. Academy appends it to the runtime's own prompt (Claude Code: `--append-system-prompt <text>`; Codex: `developer_instructions`). `docs/academy-work-model.md` describes the model.
 
-| Surface | Contains | Soft cap |
+| Surface | Contains | Cap (tokens) |
 | --- | --- | --- |
-| `identity.md` | Values, character, voice, persona | ~400 |
-| `role.md` | Job, responsibilities, deliverable shape | ~400 |
-| `knowledge.md` | Domain expertise, frameworks, patterns | ~1500–2500 |
-| `goals.md` | Strategic objectives (cap 3) | ~150 |
-| `priorities.md` | Weekly direction (3–5 visible) | ~250 |
-| `threads.md` | Active work pursuits | ~700 |
-| `notes.md` | Micro-steering staging area | ~500 |
-| `dailys.md` | Last 7 working days | ~1000 |
-
-`academy tokens <name>` estimates the compiled prompt by surface, and
-`academy budget <name>` reports which surfaces are over their cap.
+| `identity.md` | Name, persona, voice, relationships | 400 |
+| `craft.md` | Method, principles, definition of done (no environment names) | 600 |
+| `mandate.md` | Job, scope, limits, environment (the user writes it) | 600 |
+| `work.md` | Goals, priorities, focus, Workstreams | 500 for a Principal, 1000 for other kinds |
+| `knowledge.md` | What the agent learned here | 2500 |
+| `notes.md` | Steering not yet in another file | 500 |
+| `local-rules.md` | The user's rules for this agent | 500 |
+| `user.md` | Who the user is (shared, curator writes it) | 1000 |
+| `user-work.md` | The user's goals, priorities, Workstreams (shared, curator writes it) | 1000 |
+
+`academy tokens <name>` estimates the compiled prompt by surface, and `academy budget <name>` reports which surfaces are over their cap. Every cap except `identity` and `craft` is enforced: `budget` reports an enforced surface over its cap, and plain `academy budget` then exits 1 (`--json` exits 0). The totals are 7,600 for a Principal and 8,100 for the others.
 
 ## Skills
 
-Skills are Academy's one extension primitive, and the same file shape serves
-both "a competency the agent has" and "how to use this tool". Academy renders
-them for Claude Code under `.claude/skills/` and for Codex under
-`.agents/skills/`, from one source.
+Skills are Academy's one extension primitive, and the same file shape serves both "a competency the agent has" and "how to use this tool". Academy renders them for Claude Code under `.claude/skills/` and for Codex under `.agents/skills/`, from one source.
 
-Four universal skills ship with every agent: `check-in`, `self-update`,
-`nightly-consolidation`, and `knowledge-curation`. Nightly consolidation
-delegates evidence-backed graduation of notes into knowledge to a bounded
-knowledge-curator subagent and writes its report under `dreams/`.
+Six universal skills ship with every agent: `check-in`, `work-graph`, `nightly-consolidation`, `knowledge-curation`, `local-rules`, and `skill-method`. Owners add the Owner pack, and the curator adds `user-nightly`. Nightly consolidation delegates evidence-backed graduation of notes into knowledge to a bounded knowledge-curator subagent and writes its report under `dreams/`.
 
 ## Commands
 
-Fourteen commands are contract. `doctor` publishes the list, and a client should
-read it from there rather than hard-coding it.
+Sixteen commands are contract. `doctor` publishes the list, and a client should read it from there rather than hard-coding it.
 
 ```bash
 academy doctor [--json]              # discovery, health, and the version source
 academy list [--json]                # every agent, plus the archived ones
 academy inspect <name> [--json]      # one agent
 academy tokens <name> [--json]       # compiled prompt size by surface
-academy budget <name> [--json]       # surfaces over their soft cap
+academy budget <name> [--json]       # surfaces over their cap
 academy sessions [--agent <name>] [--json]
 academy events --since <seq> [--logid <id>] [--json]
-academy create <name> [--json]
+academy create [<name>] [--json]    # no name: the next default for the kind
 academy hire                         # interactive
 academy hire --spec <file> [--json]  # headless
-academy rename <old> <new> [--json]
+academy rename <old> <new> [--json]  # changes the name only; no job changes
 academy archive <name> [--json]
 academy unarchive <name> [--json]
 academy delete <name> [--json]
 academy migrate [--dry-run] [--json]
+academy start <name> [--mandate <file>] [--json]  # register jobs; an Owner needs a signed mandate
+academy stop <name> [--json]         # delete the jobs; the files stay
 ```
 
-`run`, `nightly`, `notes`, `clean`, and `root` also work and are deliberately
-not contract: `run` spawns with inherited stdio and can never emit an envelope,
-`nightly` is called by the scheduler, and the rest are conveniences for a
-person. See §6 of the integration guide.
+`run`, `nightly`, `notes`, `clean`, and `root` also work and are deliberately not contract: `run` spawns with inherited stdio and can never emit an envelope, `nightly` is called by the scheduler, and the rest are conveniences for a person.
 
 ## For client authors
 
-Everything a client may depend on is in
-[`docs/integration-guide.md`](docs/integration-guide.md): the response envelope,
-the exit rule, the compatibility floor, all fourteen published commands, the
-fifteen error codes, the event log, the agent directory layout, and an explicit
-list of what is **not** contract. Anything not in that document is internal and
-may change in any release.
+A client should discover Academy through `academy doctor --json`, which names the supported contract versions and the published command list, and should read that list rather than hard-coding it.
 
-The shape in one line: success is JSON on stdout with exit 0, failure is JSON on
-stderr with exit 1, and exit status is 0 if and only if `ok` is true.
+The shape in one line: success is JSON on stdout with exit 0, failure is JSON on stderr with exit 1, and exit status is 0 if and only if `ok` is true.
 
 ```json
 { "contract_version": 1, "ok": true, "command": "doctor", "version": "0.4.0-rc.1" }
 ```
 
-Academy ships a conformance suite for client authors. It imports no Academy
-source and asserts only what a client can observe:
+## Academy is client-agnostic, with one documented exception
 
-```bash
-node --test conformance/*.test.mjs                          # this build
-ACADEMY_BIN=/path/to/academy node --test conformance/*.test.mjs   # any build
-```
+No identifier in Academy's source names a specific client product, with exactly one deliberate exception: **the memory sync bridge**, `hooks/memory_bridge.mjs`. It copies observation memory from one specific host product into an agent's `memory/observations/` for nightly consolidation. It is **always on**: every scaffolded agent carries its tool permission and nightly guidance, and the Stop hook always tries the copy. Outside that host it does nothing, because it copies only when the host's own environment keys and observations directory exist.
 
-Every test builds its own throwaway install with a fresh temporary `HOME` and
-`AGENTS_ROOT`, so it can drive the full lifecycle without reaching any agent on
-the machine running it. `conformance/README.md` explains each file.
+Treat it as an exception, not as a pattern. It is not a plugin point and not a template for a second client.
 
-## Academy is client-agnostic, with one documented exception
+## Roque in agent sessions
+
+Academy ships Roque, a hook that keeps a long session on track across compaction. Every Academy agent session loads it. Claude sessions load it with `--plugin-dir`. Codex sessions get two hook groups in `~/.codex/hooks.json`.
 
-No identifier in Academy's source names a specific client product, with exactly
-one deliberate exception: **the memory sync bridge**,
-`hooks/memory_bridge.mjs`. It copies observation memory from one specific host
-product into an agent's `memory/observations/` for nightly consolidation, and it
-is **off unless `ACADEMY_MEMORY_BRIDGE=1` is set**. Unset, a scaffolded agent
-names no client at all — no client-named environment key is read, no
-client-named tool permission is written, and no client-named prose appears in
-any skill.
+- At 75% and 90% of the compaction point, Roque adds a hint. The hint tells the agent to keep a state file at `.roque/state/<session>.md` in the project.
+- After compaction, Roque gives the state file content back to the agent.
+- For Claude, Roque saves each compaction summary under `~/.roque`.
+- Each Claude agent session has a compaction window of 430000 tokens. Set `CLAUDE_CODE_AUTO_COMPACT_WINDOW` before `academy run` to use another value. Codex sessions keep the user's Codex config.
+- To turn Roque off in one project, create the file `.roque/off` there.
+- To use Roque in normal Claude sessions, run `claude plugin install roque@academy-local`.
 
-Treat it as an exception, not as a pattern. It is not a plugin point and not a
-template for a second client. Integration guide §12 has the full statement.
+Roque changes are made in the Roque repository. They ship with the Academy release: the release runs `npm run sync:roque`, which tests Roque `main` and copies the build to `hooks/roque/`. Do not edit `hooks/roque/roque.js` by hand.
 
 ## Layout
 
-```
+```plaintext
 academy/
 ├── .claude-plugin/           # plugin + marketplace manifests
 ├── bin/academy               # CLI entry
+├── scripts/agent.mjs         # CLI dispatcher
 ├── scripts/cli/              # CLI implementation
-├── scripts/release-check.mjs # read-only release readiness gate
-├── scripts/publish-tree.mjs  # allow-list publish tree generator
 ├── skills/hire/SKILL.md      # the hire skill
-├── templates/skills/         # universal skills copied into every agent
-├── conformance/              # client conformance suite
-├── docs/integration-guide.md # the published client contract
+├── templates/                # universal skills and subagents copied into every agent
 └── hooks/
     ├── hooks.json            # lifecycle hook config
-    └── memory_bridge.mjs     # the one client-specific file, off by default
+    └── memory_bridge.mjs     # the one client-specific file, always on
 ```
 
 ## Design notes
 
-- **No adapters.** External CLIs are used as-is. A missing capability is a
-  feature request against that project, not glue here.
-- **Skills are the unifying primitive.** One file shape for competencies and for
-  tool documentation, rendered for both runtimes from one source.
-- **Generated system prompt.** The eight surfaces stay editable Markdown.
-  Compilation at launch is local file IO only; the slow work stays nightly.
-- **Lifecycle hooks only.** Hooks are for runtime side effects, not for startup
-  context transport.
-- **Portable plugin layout.** Each agent has a `.claude-plugin/` symlink to this
-  package, so running Claude Code inside the agent directory keeps Academy's
-  lifecycle hooks available.
-
-## Releasing
-
-`node scripts/release-check.mjs` is the read-only readiness gate. It mutates
-nothing, packs into a temporary directory, asserts the packed file list against
-the declared published surface, runs the conformance suite against the unpacked
-tarball, and proves `git status --porcelain` is byte-identical before and after.
-`.agents/skills/release/SKILL.md` is the release procedure and calls it from
-every mode.
+- **No adapters.** External CLIs are used as-is. A missing capability is a feature request against that project, not glue here.
+- **Skills are the unifying primitive.** One file shape for competencies and for tool documentation, rendered for both runtimes from one source.
+- **Generated system prompt.** The nine surfaces stay editable Markdown. Compilation at launch is local file IO only; the slow work stays nightly.
+- **Lifecycle hooks only.** Hooks are for runtime side effects, not for startup context transport.
+- **Portable plugin layout.** Each agent has a `.claude-plugin/` symlink to this package, so running Claude Code inside the agent directory keeps Academy's lifecycle hooks available.
+
+## Contributing
+
+Academy is open source under the MIT licence. You can read the source, use it, fork it, and change it for your own needs.
+
+Academy is not open to contributions, and pull requests are not accepted. This repository is generated from a private repository at each release, so a change made here cannot be merged.
+
+Issues are welcome. If you find a bug or have an idea, open an issue.
 
 ## Licence
 
-MIT. See [`LICENSE`](LICENSE). Changes are recorded in
-[`CHANGELOG.md`](CHANGELOG.md).
+MIT. See `LICENSE`. Changes are recorded in `CHANGELOG.md`.

package/hooks/backstory/.claude-plugin/plugin.json

@@ -0,0 +1,11 @@
+{
+  "name": "backstory",
+  "version": "0.1.0",
+  "description": "Automatic observation memory for Claude Code: captures what each turn accomplished, stores it locally in SQLite/FTS5, and brings it back at session start and on demand. Also Capture: typed, tagged project knowledge the agent saves and looks up, in its own store.",
+  "author": {
+    "name": "Joe Fernandez",
+    "email": "joe@bycodename.com"
+  },
+  "license": "MIT",
+  "keywords": ["memory", "observations", "context", "sqlite", "fts5", "knowledge"]
+}

package/hooks/backstory/SOURCE

@@ -0,0 +1,2 @@
+f71ddb76f8c09bef78d455d6dca3d30c2327020f
+dirty: true

package/hooks/backstory/bin/backstory

@@ -0,0 +1,9 @@
+#!/bin/sh
+# Backstory's one CLI; Claude Code puts the plugin's bin/ on PATH. Knowledge commands go to the
+# knowledge bundle; setup, admin, and observation recall commands go to the memory bundle.
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+case "$1" in
+  search|load|capture|tags|history|inspect|registry) BUNDLE=knowledge ;;
+  *) BUNDLE=memory ;;
+esac
+exec node "$SCRIPT_DIR/../scripts/$BUNDLE.mjs" "$@"

package/hooks/backstory/hooks/hooks.json

@@ -0,0 +1,45 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume|clear|compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/memory.mjs\" hook --host claude --event SessionStart"
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/memory.mjs\" hook --host claude --event UserPromptSubmit"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/memory.mjs\" hook --host claude --event Stop"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/tool-tick.mjs\" --host claude"
+          }
+        ]
+      }
+    ]
+  }
+}