@joenandez/academy 0.4.0-rc.1

package/.claude-plugin/marketplace.json

@@ -0,0 +1,14 @@
+{
+  "name": "academy-local",
+  "description": "Local marketplace for the Academy v3 plugin",
+  "owner": {
+    "name": "Joe Fernandez"
+  },
+  "plugins": [
+    {
+      "name": "academy",
+      "source": ".",
+      "description": "Academy v3 — portable AI agents."
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,6 @@
+{
+  "name": "academy",
+  "description": "Academy v3 — portable AI agents.",
+  "version": "0.4.0-rc.1",
+  "hooks": "./hooks/hooks.json"
+}

package/CHANGELOG.md

@@ -0,0 +1,46 @@
+# Changelog
+
+This project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+The heading at the top of this file is the version in `package.json`.
+
+## 0.4.0-rc.1 — 2026-08-31
+
+First release candidate, and the first Academy artifact that can be installed
+rather than cloned.
+
+### Added
+
+- **A published client contract at `contract_version` 1.** Every command
+  answers a JSON envelope: `{ contract_version, ok, command, ... }` on stdout
+  with exit 0, or `{ contract_version, ok: false, command, error }` on stderr
+  with exit 1. Exit status is 0 if and only if `ok` is true.
+- **`doctor`** — the discovery command. It reports the supported contracts, the
+  build version, the package root, the agents root, the event log path, the
+  published command list, runtime availability, and health counts.
+- **Fifteen published error codes**, each reachable from outside the binary and
+  each documented in the integration guide.
+- **An append-only event log**, so a client can follow lifecycle changes it did
+  not make.
+- **`docs/integration-guide.md`** — the whole published contract, written for an
+  author of a client that drives Academy without reading Academy's source.
+- **A client conformance suite** in `conformance/`. It imports no Academy
+  source, asserts only what a client can observe, and runs against any build
+  through `ACADEMY_BIN`.
+- **Release tooling.** `scripts/release-check.mjs` is a read-only readiness
+  gate, `scripts/publish-tree.mjs` generates the public tree from an allow-list,
+  and `.agents/skills/release/SKILL.md` is the release procedure.
+
+### Changed
+
+- **Academy is client-agnostic.** No identifier in the source names a specific
+  client product, with one documented exception: the memory sync bridge in
+  `hooks/memory_bridge.mjs`, which is off unless `ACADEMY_MEMORY_BRIDGE=1`.
+- **Package identity is `@joenandez/academy`.** The unscoped `academy` name is
+  taken on the registry. The command is still `academy`.
+- **Every path a command reports is absolute and normalised**, so a client can
+  key an agent on `dir` across every record for that agent.
+
+### Removed
+
+- The Subspace-specific framing in `README.md`. Academy is described on its own
+  terms, with the memory bridge named as the single exception.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joe Fernandez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,209 @@
+# Academy
+
+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.
+
+**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.
+
+## Install
+
+```bash
+git clone https://github.com/joenandez/academy.git
+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:
+
+```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.
+
+## Create and run an agent
+
+```bash
+academy create kai            # scaffold ~/.academy/agents/kai/
+academy run kai               # launch Claude Code against the current project
+academy run kai --agent codex -- exec "say hello"
+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.
+
+`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.
+
+## The eight 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.
+
+| Surface | Contains | Soft cap |
+| --- | --- | --- |
+| `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.
+
+## 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.
+
+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/`.
+
+## Commands
+
+Fourteen 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 sessions [--agent <name>] [--json]
+academy events --since <seq> [--logid <id>] [--json]
+academy create <name> [--json]
+academy hire                         # interactive
+academy hire --spec <file> [--json]  # headless
+academy rename <old> <new> [--json]
+academy archive <name> [--json]
+academy unarchive <name> [--json]
+academy delete <name> [--json]
+academy migrate [--dry-run] [--json]
+```
+
+`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.
+
+## 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.
+
+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:
+
+```bash
+node --test conformance/*.test.mjs                          # this build
+ACADEMY_BIN=/path/to/academy node --test conformance/*.test.mjs   # any build
+```
+
+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.
+
+## Academy is client-agnostic, with one documented exception
+
+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.
+
+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.
+
+## Layout
+
+```
+academy/
+├── .claude-plugin/           # plugin + marketplace manifests
+├── bin/academy               # CLI entry
+├── 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
+└── hooks/
+    ├── hooks.json            # lifecycle hook config
+    └── memory_bridge.mjs     # the one client-specific file, off by default
+```
+
+## 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.
+
+## Licence
+
+MIT. See [`LICENSE`](LICENSE). Changes are recorded in
+[`CHANGELOG.md`](CHANGELOG.md).

package/bin/academy

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import('../scripts/agent.mjs');

package/conformance/README.md

@@ -0,0 +1,60 @@
+# Academy client conformance suite
+
+This suite checks that an Academy build implements the client contract. It is
+written for authors of clients that drive Academy, not for Academy's own
+developers: it never imports Academy source and asserts only what a client can
+observe — the response envelope, the exit status, and the published error codes.
+
+## Run it
+
+```sh
+# against the build in this package
+node --test conformance/*.test.mjs
+
+# against any other build
+ACADEMY_BIN=/usr/local/bin/academy node --test conformance/*.test.mjs
+```
+
+`ACADEMY_BIN` is the path of the Academy launcher to test. Unset, the suite
+drives the `bin/academy` beside this directory. Point it at a global install, an
+unpacked tarball, or a source checkout — the assertions are the same.
+
+Requirements: Node 18 or later, a POSIX shell, and nothing else. No packages are
+installed and no test framework is used.
+
+## What it asserts
+
+| File | Asserts |
+| --- | --- |
+| `discovery.test.mjs` | `doctor --json` — the published command list, the payload keys, the version rule, and the one state answered `ok:false` |
+| `identity.test.mjs` | Every agent-addressed command refuses an out-of-root agents root and an out-of-root agent directory, and writes nothing outside the root |
+| `error-codes.test.mjs` | An invocation for each of the fifteen published error codes |
+| `envelope.test.mjs` | The envelope and the exit rule across every published command, on success and on failure |
+
+## Safety
+
+Every test builds its own throwaway install: a fresh temporary `HOME`, a fresh
+temporary `AGENTS_ROOT`, and a `PATH` built from nothing. Values already
+exported into your shell are **not** inherited by the build under test. The
+suite drives the full lifecycle, including `delete`, `archive`, `rename` and
+`migrate`, and can reach no agent outside its own temporary directories.
+
+## Stubs
+
+Two executables Academy uses are stubbed, because neither is part of the
+response contract and a client author must not need either installed:
+
+- `helm-tasks` — the scheduler Academy registers each agent's nightly job with.
+  Academy resolves it from `PATH`, or from `ACADEMY_HELM_TASKS_BIN`. Without it,
+  `create`, `delete`, `rename` and `archive` answer `runtime_unavailable`.
+- `claude` — the runtime `hire --spec` drives. Academy resolves it from `PATH`,
+  or from `ACADEMY_CLAUDE_BIN`.
+
+The scheduler stub is also the only way to reach `unschedule_failed` and
+`unschedule_failed_restore_blocked` from outside the binary.
+
+## Reading a failure
+
+Each assertion prints the exit status and both streams of the invocation that
+produced it, so a failure names the command, the envelope it returned, and the
+field that disagreed.

package/conformance/discovery.test.mjs

@@ -0,0 +1,140 @@
+// Discovery — what a client learns before it renders anything.
+//
+// `doctor --json` is the one call a client may make against an Academy it knows
+// nothing about. Everything else in this suite is driven from what it answers.
+
+import assert from 'node:assert/strict';
+import { existsSync, rmSync, symlinkSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { join } from 'node:path';
+import test from 'node:test';
+import { academy, assertFailure, assertSuccess, createHost, hireAgent } from './harness.mjs';
+
+// The frozen answer at contract_version 1, in order. A client may key on the
+// order, so this is asserted by equality rather than by membership.
+const PUBLISHED_COMMANDS = [
+  'doctor',
+  'list',
+  'inspect',
+  'tokens',
+  'budget',
+  'sessions',
+  'events',
+  'create',
+  'hire',
+  'rename',
+  'archive',
+  'unarchive',
+  'delete',
+  'migrate',
+];
+
+// Commands an Academy build may implement but must not publish. A client that
+// found one here would build on a surface with no contract behind it.
+const UNPUBLISHED_COMMANDS = ['notes', 'nightly', 'clean', 'root', 'run', 'destroy'];
+
+// The payload keys, in order, after the three envelope keys.
+const DOCTOR_PAYLOAD_KEYS = [
+  'contracts',
+  'version',
+  'packageRoot',
+  'agentsRoot',
+  'eventLog',
+  'commands',
+  'runtimes',
+  'errors',
+];
+
+// `errors[]` is a health channel, not the error channel: it names a degraded
+// part of an install and how much of it there is. None of the fifteen failure
+// codes may appear here.
+const HEALTH_CODES = ['unowned_agents', 'invalid_runtime_agents', 'unattributable_sessions'];
+
+test('doctor publishes the whole command set, in order', () => {
+  const host = createHost();
+
+  const payload = assertSuccess(academy(host, ['doctor', '--json']), 'doctor');
+
+  assert.deepEqual(payload.commands, PUBLISHED_COMMANDS);
+  for (const command of UNPUBLISHED_COMMANDS) {
+    assert.equal(payload.commands.includes(command), false, `${command} must not be published`);
+  }
+});
+
+test('doctor answers with exactly the published payload keys', () => {
+  const host = createHost();
+
+  const payload = assertSuccess(academy(host, ['doctor', '--json']), 'doctor');
+
+  assert.deepEqual(Object.keys(payload), [
+    'contract_version',
+    'ok',
+    'command',
+    ...DOCTOR_PAYLOAD_KEYS,
+  ]);
+  assert.deepEqual(payload.contracts, [1]);
+  assert.equal(typeof payload.packageRoot, 'string');
+  assert.equal(typeof payload.agentsRoot, 'string');
+  assert.equal(typeof payload.eventLog, 'string');
+  assert.deepEqual(Object.keys(payload.runtimes).sort(), ['claude_code', 'codex']);
+  for (const runtime of Object.values(payload.runtimes)) {
+    assert.equal(typeof runtime.available, 'boolean');
+  }
+});
+
+// Two builds with different capabilities must never report the same version. A
+// checkout names its own commit as semver build metadata; an install has no
+// checkout to name and reports the published version bare.
+test('doctor reports build metadata only for a checkout', () => {
+  const host = createHost();
+
+  const payload = assertSuccess(academy(host, ['doctor', '--json']), 'doctor');
+
+  assert.equal(typeof payload.version, 'string');
+  assert.notEqual(payload.version, '');
+  if (describesItsOwnCheckout(host, payload.packageRoot)) {
+    assert.match(payload.version, /^[^+]+\+[0-9A-Za-z-]+$/);
+  } else {
+    assert.equal(payload.version.includes('+'), false);
+  }
+});
+
+function describesItsOwnCheckout(host, packageRoot) {
+  if (!existsSync(join(packageRoot, '.git'))) return false;
+  return spawnSync('git', ['--version'], { env: host.env, encoding: 'utf8' }).status === 0;
+}
+
+// A degraded component is not a failure. A client calls doctor before it renders
+// anything, so an install with repairable faults must still be usable.
+test('a degraded install stays ok:true and exits 0', () => {
+  const host = createHost();
+  hireAgent(host, 'kai');
+  rmSync(join(host.agentsRoot, 'kai', '.academy-agent.json'));
+
+  const result = academy(host, ['doctor', '--json']);
+
+  const payload = assertSuccess(result, 'doctor');
+  assert.equal(result.status, 0);
+  assert.deepEqual(payload.errors, [{ code: 'unowned_agents', count: 1 }]);
+  for (const entry of payload.errors) assert.equal(HEALTH_CODES.includes(entry.code), true);
+});
+
+// The one state doctor answers with ok:false: every agent-addressed command
+// would fail on this root, so a client told ok:true would render an interface
+// whose first call fails. The payload still ships, beside the error.
+test('doctor is ok:false only when the agents root fails its audit', () => {
+  const host = createHost();
+  symlinkSync(host.outside, host.agentsRoot);
+
+  const result = academy(host, ['doctor', '--json']);
+
+  const envelope = assertFailure(result, 'doctor', 'unsafe_agent_path');
+  assert.deepEqual(Object.keys(envelope), [
+    'contract_version',
+    'ok',
+    'command',
+    ...DOCTOR_PAYLOAD_KEYS,
+    'error',
+  ]);
+  assert.deepEqual(envelope.commands, PUBLISHED_COMMANDS);
+});