@joenandez/academy 0.4.0 → 0.5.12

package/templates/skills/local-rules/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: local-rules
+layer: craft
+description: Use when the user tells {{agent_name}} how to work — format, cadence, approvals, what to do or stop doing — in any message. Records the feedback at once as a local rule that overrides package skill instructions, and proposes it for every agent of this kind when it is general.
+---
+
+# Local Rules
+
+A local rule is the user's own rule for how {{agent_name}} works. It applies at
+the next action; the user never waits for a package release. Rules in
+local-rules.md override any package skill instruction.
+
+- Local rules: `{{local_rules_path}}` (already in your session context)
+- Proposal queue for this kind: `{{proposals_dir}}`
+- Pack version: `{{pack_version}}`
+
+## Detect Loop Feedback
+
+Loop feedback says how to work, not what the answer to this task is. It arrives
+in ordinary messages; the user does not say "rule". Examples:
+
+- "Lead with the recommendation."
+- "Do not ask for approval to research."
+- "Stop sending a summary after every step."
+- "From now on...", "always...", "never...", "that is not how I want you to..."
+
+Not loop feedback: a domain or stakeholder fact, a one-off instruction for the
+current task only, or a change to the mandate. Route those as your operating
+model says: a fact about the user to `academy notes add --user`, other steering
+to `academy notes add`, a Workstream to the `work-graph` skill.
+
+## Write The Rule At Once
+
+Do this before the next action, not at a check-in or the nightly run.
+
+1. Open `{{local_rules_path}}`. If an entry already covers the same behavior,
+   edit that entry (text, Source, Date, Pack version). Never keep two entries
+   that contradict each other.
+2. Otherwise append one entry. Remove the `_(none yet)_` line on the first one.
+
+   ```
+   ## <the rule, one imperative sentence>
+   - Source: "<the user's message, quoted briefly>"
+   - Date: <YYYY-MM-DD, today>
+   - Pack version: {{pack_version}}
+   ```
+
+3. Write the rule so a later session can follow it without this conversation.
+   Add no commentary.
+4. Run `academy budget {{agent_name}} --json` and read the `local-rules` row.
+   If `withinCap` is `false`, merge or condense rules until it is within its
+   cap of 500, and keep each kept rule's Source, Date, and Pack version (on a
+   merge, keep the newest). Run the budget again to confirm. Only this skill
+   writes local-rules.md; the nightly run never trims it.
+5. Re-read the file and check the entry reads as intended.
+6. Confirm in one line — `Local rule saved: <rule>` — then continue the work
+   under the rule.
+
+If the user withdraws a rule, delete its entry and confirm in one line.
+
+## Precedence
+
+A local rule wins over any package skill instruction, this skill included.
+Never edit a package skill file to apply a rule: Academy re-renders those on
+every run. The rule lives only in local-rules.md.
+
+## Propose It For Every Agent Of This Kind
+
+When the rule would help every agent of this kind — it is about how the loop
+works in general and names no project, person, repo path, customer, or other
+private detail — also file a proposal. Always write the local rule too; the
+proposal never replaces it.
+
+Write `{{proposals_dir}}/<timestamp>-{{agent_name}}.md`, with the timestamp from
+`date -u +%Y%m%dT%H%M%SZ`. Create the directory if it is missing.
+
+```
+# Proposal: <the rule>
+- Agent: {{agent_name}}
+- Source: "<the user's message, quoted>"
+- Date: <YYYY-MM-DD>
+- Pack version: {{pack_version}}
+- Proposed rule: <the rule, written for every agent of this kind>
+```
+
+Add `(proposed for every agent of this kind)` to the one-line confirmation.

package/templates/skills/nightly-consolidation/SKILL.md

@@ -1,13 +1,14 @@
 ---
 name: nightly-consolidation
-description: Use during {{agent_name}}'s scheduled nightly memory consolidation to update daily memory surfaces and write an observable dreams report.
+layer: craft
+description: Use during {{agent_name}}'s scheduled nightly memory consolidation to update work.md, graduate notes, and write an observable dreams report.
 ---
 
 # Nightly Consolidation
 
 This skill runs as {{agent_name}}'s nightly memory pass. It turns recent
 experience with the user into tighter next-day context without rewriting the
-agent's identity or job definition casually.
+agent's identity or mandate casually.
 
 ## Agent Paths
 
@@ -17,13 +18,14 @@ write the nightly result.
 
 - Agent home: `{{agent_dir}}`
 - `identity.md`: `{{identity_path}}`
-- `role.md`: `{{role_path}}`
+- `craft.md`: `{{craft_path}}`
+- `mandate.md`: `{{mandate_path}}`
+- `work.md`: `{{work_path}}`
 - `knowledge.md`: `{{knowledge_path}}`
-- `goals.md`: `{{goals_path}}`
-- `priorities.md`: `{{priorities_path}}`
-- `threads.md`: `{{threads_path}}`
 - `notes.md`: `{{notes_path}}`
-- `dailys.md`: `{{dailys_path}}`
+- Shared, read only: `{{user_path}}`
+- `user-work.md`: your share is in your prompt. Open the full file only when
+  you need the full catalog: `{{user_work_path}}`
 - Memory observations: `{{memory_observations_path}}`
 - Dreams directory: `{{dreams_dir}}`
 - This skill: `{{nightly_consolidation_path}}`
@@ -33,111 +35,137 @@ write the nightly result.
 
 Prepare tomorrow's version of the agent. The expected outputs are:
 
-- an updated `dailys.md` with the last 7 working-day summaries
-- conservative updates to `threads.md`, `notes.md`, and `priorities.md`
-- evidence-backed `knowledge.md` graduations applied by the dedicated curator
-- optional proposed changes for `goals.md`, `role.md`, `identity.md`,
-  deferred `knowledge.md` candidates, or skills
+- an updated `work.md`: Goals, Priorities, Focus, Workstreams, Open questions
+- graduated or expired `notes.md` entries
+- evidence-backed `knowledge.md` graduations and `craft.md` promotions applied
+  by the dedicated curator
+- proposed changes for `identity.md`, `mandate.md`, deferred candidates, or
+  skills
 - a dreams report at `{{dreams_dir}}/MM-YY-DD.md`
 
 ## Source Material
 
 Use `{{memory_observations_path}}` as the primary source. It contains the
-observations recorded from this Academy agent's own sessions. Then use
-recent session context and gather only enough additional evidence to avoid
-guessing:
+observations recorded from this Academy agent's own sessions. Then gather only
+enough additional evidence to avoid guessing:
 
 1. Read today's observation JSONL from `{{memory_observations_path}}` if it
    exists.
 2. Read yesterday's observation JSONL when the nightly job may have run after
    midnight or the prior day was missed.
-3. Search with concrete terms from recent work, the agent name, and active
-   thread names when more evidence is needed.
-4. Read previous dreams reports only when checking whether a recommendation is
+3. Search with concrete terms from recent work and the agent name when more
+   evidence is needed.
+4. Read Beads changes since the newest report to Workstreams and tasks you
+   touched: `bd list --type workstream --updated-after <date> --json`. Every
+   ready query adds `--exclude-type workstream`.
+5. Read previous dreams reports only when checking whether a recommendation is
    recurring or already handled.
 
+An archive entry is pending until a dreams report lists it under
+`{{report_consumed_field}}` (match `sessionId@timestamp`). Start from the
+newest report; look further back only for entries older than what it
+consumed. A late entry can carry an older timestamp than entries already
+consumed, so never skip an entry for its age alone. Read the pending entries
+in every archive file, including files from earlier dates.
+
 The agent-local observation archive is the required basis for this workflow.
-It is the only source that can establish eligibility. If the archive is empty,
-stop before editing any memory surface, delegating to the curator, or writing a
-dreams report.
+It is the only source that can establish eligibility for observation work. With
+no pending archive entries, skip observation work (steps 2-3). Still run the
+curator on notes (steps 4-6), budget and trim (steps 7-10), and a short dreams
+report with `Inputs: notes only`.
 
 {{memory_bridge_guidance}}
 
 ## Edit Boundaries
 
-Autonomous edits are allowed for:
+One writer per file. Autonomous edits are allowed for:
 
-- `dailys.md`
-- `threads.md`
-- `notes.md`
-- `priorities.md`
+- `work.md`
+- `notes.md`: add transient notes, and (through the curator) graduate or expire
 - the nightly dreams report
 
 The nightly parent may add transient notes before delegation. Then the
 foreground `knowledge-curator` subagent receives exclusive ownership of
-`notes.md` and `knowledge.md` for the curation phase. The parent must wait for
-it to finish and must not edit either file during that phase.
+`notes.md`, `knowledge.md`, `craft.md`, and `references/` for the curation
+phase. The parent waits and edits none of them meanwhile.
 
 After the curator returns and manifest verification finishes, the parent may
-reduce `knowledge.md` and `notes.md` only to reduce size. It must never add
-content to either file, and it must never reverse a curator graduation
-decision. The parent may also reduce `priorities.md`, `threads.md`, and
-`dailys.md` during the post-curator budget phase. `identity.md`, `role.md`,
-and `goals.md` remain propose-only.
-
-Do not directly rewrite `identity.md`, `role.md`, `goals.md`, or skills from
-this workflow unless the user explicitly requested that specific change.
-Instead, put a proposal in the dreams report.
+reduce `knowledge.md`, `notes.md`, and `work.md` only to reduce size. It must
+never add content to `knowledge.md` or `notes.md`, never edit `craft.md`, and
+never reverse a curator decision.
+
+Propose only, in the dreams report: `identity.md`, `mandate.md`, and skills. Do
+not rewrite them unless the user explicitly requested that change. Never write
+`user.md` or `user-work.md`. If you learn a fact about the user, append it with
+`academy notes add --user "..."`; the curator confirms it.
+
+## Graduation Rules
+
+- `notes.md` to `knowledge.md` or `craft.md`: through the curator, when the
+  note becomes a reusable pattern. Outside this run, only for an explicit user
+  request; otherwise keep the note.
+- `notes.md` to `mandate.md` or `identity.md`: propose only. Identity changes
+  only for durable principles or voice.
+- `knowledge.md` to a skill: propose when "how to do this" becomes a
+  repeatable procedure.
+- A note about the Academy system itself (a `system` proposal): run
+  `bd create "<title>" -t task -l academy-system -d "<note, agent, evidence>"`
+  (Beads is shared through `BEADS_DIR`). List it in the dreams report.
+- Stale notes expire. Environment names go only to private files.
 
 ## Procedure
 
 1. Determine today's date and the dreams filename using `MM-YY-DD` format.
-2. Review recent evidence: loaded context, the observation archive, current
-   surfaces, and recent dreams reports if useful.
-3. Write a concise daily entry for `dailys.md`. Keep only the last 7 working
-   days. Each entry should capture work done, decisions, blockers, user
-   steering, and the next useful step.
-4. Reconcile `threads.md`:
-   - mark completed work done or remove it from active attention
-   - demote stale active items to idle or parked
-   - add only concrete active pursuits with a next step
-5. Add any new transient steering to `notes.md` before delegation. Do not
+2. Review recent evidence: loaded context, the observation archive, Beads
+   changes, current surfaces, and recent dreams reports if useful.
+3. Reconcile `work.md` with the same five sections in order:
+   - **Goals:** each an outcome with a measure, or the word qualitative.
+   - **Priorities:** 3-5, in order, each with a reason and its Beads id.
+   - **Focus:** what deserves attention now. Focus changes fast; priorities
+     change slowly. A busy day does not make a new priority.
+   - **Workstreams:** one line each, with its Beads id and state.
+   - **Open questions.**
+
+   Explicit user statements outrank inference. Never mark a Workstream active
+   on inference alone (see the `work-graph` skill). Keep `work.md` thin when
+   you are a Principal or Specialist: only work unique to you. Write a line
+   `Updated by {{agent_name}}'s nightly, <date>` under the title.
+4. Add any new transient steering to `notes.md` before delegation. Do not
    graduate or expire notes in the parent.
-6. Reconcile `priorities.md` when recent evidence clearly changes next focus.
-   Keep 3-5 priorities. Do not turn every unfinished task into a priority.
-7. Invoke the foreground `knowledge-curator` subagent in Claude Code or
-   `knowledge_curator` in Codex for the bounded knowledge-graduation phase.
-   Tell it to use its preloaded `knowledge-curation` skill and confirm the
-   contract at `{{knowledge_curation_path}}`; wait for it to finish and retain
-   its application manifest.
-8. Re-read `knowledge.md` and `notes.md` after the curator returns. Compare the
-   files with its manifest. Do not edit either file during manifest
-   verification. After verification, only the reduce-only budget edits in the
-   following steps are allowed.
-9. Run `academy budget {{agent_name}} --json`. The reply is the shared response
+5. Invoke the foreground `knowledge-curator` subagent in Claude Code or
+   `knowledge_curator` in Codex for the bounded graduation and promotion
+   phase. Tell it to use its preloaded `knowledge-curation` skill and confirm
+   the contract at `{{knowledge_curation_path}}`; wait for it to finish and
+   retain its application manifest.
+6. Re-read `knowledge.md`, `craft.md`, `notes.md`, and each `references/` file
+   the manifest names after the curator returns. Compare the files with its
+   manifest, and check that each named `references/` file has its `useWhen`
+   line in `knowledge.md`. Do not edit them during manifest verification.
+7. Run `academy budget {{agent_name}} --json`. The reply is the shared response
    envelope: `contract_version`, `ok`, `command`, then the report. Read
-   `withinBudget`, `surfaces`, and `violations` from the top level. The command
-   exits 0 for any answer it can compute, so read `ok` and `withinBudget`, never
-   the exit status. Record the per-surface baseline estimate, cap, overage, and
-   enforced/advisory verdict.
-10. If no enforced surface is over cap, set Surface Budget status to `pass`.
-11. If an enforced surface is over cap — `withinBudget` is `false`, or an entry
-    in `violations` has `enforced: true` — trim reduce-only surfaces and re-run
-    `academy budget {{agent_name}} --json`. The parent may reduce
-    `knowledge.md` and `notes.md` only to reduce size, may reduce
-    `priorities.md`, `threads.md`, and `dailys.md`, and must keep
-    `identity.md`, `role.md`, and `goals.md` as proposals only.
-    Repeat the trim and re-check cycle until every enforced surface passes or
-    further reduction is not possible without violating the edit boundary.
-12. Set Surface Budget status to `pass` only when all enforced surfaces pass.
-    Status converging only when every still-blocking enforced surface has reduced its overage by at least 20% of that surface's baseline overage.
+   `surfaces` and `violations` from the top level; `withinBudget` counts
+   `local-rules`, so it is not the status gate. The command exits 0 for any
+   answer it can compute, so read `ok`, never the exit status. Record the
+   per-surface baseline estimate, cap, overage, and enforced/advisory verdict.
+8. If no enforced surface other than `local-rules` and `mandate.md` is over cap, set Surface Budget status to `pass`.
+9. If an enforced surface other than `local-rules` and `mandate.md` is over cap — its entry in
+   `violations` has `enforced: true` — trim reduce-only surfaces (`knowledge.md`,
+   `notes.md`, `work.md`) and re-run `academy budget {{agent_name}} --json`.
+   Do not edit `local-rules.md` or `mandate.md`. An over-cap `mandate.md`,
+   `identity.md`, `craft.md`, `user.md`, or `user-work.md`: record it under
+   Proposed Changes; it does not block `pass`. Repeat the trim and re-check cycle until every
+   enforced surface other than `local-rules` and `mandate.md` passes or further reduction is not
+   possible without violating the edit boundary.
+10. Set Surface Budget status to `pass` only when all enforced surfaces other than `local-rules` and `mandate.md` pass.
+    Status converging only when every enforced surface other than `local-rules` and `mandate.md` still over cap has reduced its overage by at least 20% of that surface's baseline overage.
     The 20% value is a minimum progress floor, not a maximum deletion limit.
     Status failed when neither pass nor the 20% convergence floor can be reached. Converging and failed are explicitly not success.
     Both recur on the next nightly run.
-13. Write the dreams report, incorporating the curator manifest and Surface
+11. Write the dreams report, incorporating the curator manifest and Surface
     Budget results. Always write the dreams report on pass, converging, and
-    failed, including curator failure.
-14. End with a concise completion summary and include the dreams report path.
+    failed, including curator failure. Fill `## {{report_evidence_section}}`
+    from what this run actually read and edited.
+12. End with a concise completion summary and include the dreams report path.
     Name the Surface Budget status. Describe only `pass` as budget success;
     describe `converging` or `failed` as an unmet budget.
 
@@ -146,15 +174,16 @@ Instead, put a proposal in the dreams report.
 If the curator is unavailable, times out, fails, or does not return a valid
 manifest:
 
-- leave `knowledge.md` unchanged when the curator did not write it
+- leave `knowledge.md` and `craft.md` unchanged when the curator did not write
+  them
 - preserve all source notes
 - do not apply the proposed edits yourself
-- finish `dailys.md`, `threads.md`, `priorities.md`, and the dreams report
+- finish `work.md` and the dreams report
 - set the dreams report's Knowledge Graduation status to `failed` and record
   the exact reason under Verification
 - run `academy budget {{agent_name}} --json` once, populate every
   `## Surface Budget` row from the `surfaces` list in that envelope, and record
-  `pass` when `withinBudget` is `true` or `failed` otherwise
+  `pass` when no enforced surface other than `local-rules` and `mandate.md` is over cap, else `failed`
 - mark budget trimming as skipped because the curator manifest was unavailable
 
 If the curator partially changed a file before failing, report the detected
@@ -172,20 +201,23 @@ Create or replace `{{dreams_dir}}/MM-YY-DD.md`:
 - Recent memory sources consulted:
 - Important gaps or unavailable sources:
 
+## {{report_evidence_section}}
+- {{report_consumed_field}}: each consumed archive entry as `<file> <sessionId>@<timestamp>`
+- {{report_changed_field}}: each memory surface this run edited, or None
+- {{report_no_change_field}}: when no surface changed, the specific archive evidence that made no change correct; otherwise None
+
 ## Changes Made
-- `dailys.md`:
-- `threads.md`:
+- `work.md`:
 - `notes.md`:
-- `priorities.md`:
 
 ## Knowledge Graduation
 - Status: completed | skipped | failed
 
 ### Applied
-- Decision: apply | consolidate | correct
+- Decision: apply | consolidate | correct | promote
 - Candidate:
 - Evidence:
-- Knowledge section changed:
+- Knowledge or craft section changed:
 - Source notes retired:
 
 ### Deferred
@@ -198,43 +230,42 @@ Create or replace `{{dreams_dir}}/MM-YY-DD.md`:
 
 ### Verification
 - `knowledge.md` re-read:
+- `craft.md` re-read:
 - `notes.md` re-read:
 - Mismatches or partial failures:
 
 ## Proposed Changes
-- `goals.md`:
-- `role.md`:
 - `identity.md`:
+- `mandate.md`: include an over-cap mandate
 - `knowledge.md`: deferred candidates requiring human judgment only
 - skills:
+- `system` tasks created (title and Beads id), or None
 
 ## Surface Budget
 - Overall status: pass | converging | failed
-- `identity.md`: baseline estimate, final estimate, cap, final overage, and enforced/advisory verdict
-- `role.md`: baseline estimate, final estimate, cap, final overage, and enforced/advisory verdict
-- `knowledge.md`: baseline estimate, final estimate, cap, final overage, and enforced/advisory verdict
-- `goals.md`: baseline estimate, final estimate, cap, final overage, and enforced/advisory verdict
-- `priorities.md`: baseline estimate, final estimate, cap, final overage, and enforced/advisory verdict
-- `threads.md`: baseline estimate, final estimate, cap, final overage, and enforced/advisory verdict
-- `notes.md`: baseline estimate, final estimate, cap, final overage, and enforced/advisory verdict
-- `dailys.md`: baseline estimate, final estimate, cap, final overage, and enforced/advisory verdict
+- One row per surface from `academy budget`: baseline estimate, final estimate, cap, final overage, and enforced/advisory verdict
+- `local-rules.md`: report only
+- `mandate.md`: report only
 
 ## Tomorrow
 - Recommended first move:
 - Watchouts:
 ```
 
+`## {{report_evidence_section}}` is your checkpoint: the next nightly treats
+every entry listed in `{{report_consumed_field}}` as consumed, so name every
+entry you consumed. Fill either `{{report_changed_field}}` or
+`{{report_no_change_field}}`. Academy does not read the report; it records only
+how the run ended.
+
 Use `None` where no changes or proposals were warranted. The dreams report is
 for observability; it should be specific enough that the user can see why the
 agent will behave differently tomorrow.
 
-Advisory over-cap `identity.md`, `role.md`, and `goals.md` changes are
-proposals under `## Proposed Changes`, never edits.
-
 ## Anti-Patterns
 
-- Rewriting stable identity, role, or goals from one noisy day.
+- Rewriting stable identity, mandate, or work from one noisy day.
 - Treating raw observations as permanent knowledge.
 - Making priorities a duplicate task list.
-- Letting `dailys.md` grow beyond 7 entries.
+- Naming the user, a repo, a system, a person, or a product in `craft.md`.
 - Hiding skipped evidence or failed memory commands.

package/templates/skills/skill-method/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: skill-method
+layer: craft
+description: Use when {{agent_name}} writes, edits, splits, or reviews a skill or reference file, or when `academy skills check` reports a warn or fail.
+---
+
+# Skill Method
+
+Skills are how {{agent_name}}'s operating loop and principles are enforced. A
+rule that is not reachable from the entry point at the moment it applies does
+not govern behavior. The token ceiling forces the question of where each rule
+lives, so moved content still loads exactly when it is needed.
+
+## Routes
+
+- **Use when writing or editing a skill or reference file:** follow Rules, then
+  run the check below before you finish.
+- **Use when a file is at or over 80% of the ceiling:** follow Split, then run
+  the check.
+- **Use when the nightly run reports a fail:** split or repair before any other
+  maintenance. Never raise the ceiling to make the check pass.
+
+## Rules
+
+1. **One entry point.** Each agent and each pack starts at a small router,
+   about 100 tokens, that names the high-order branches and nothing else.
+2. **Routes carry their condition.** Every link to a skill or reference has a
+   `useWhen` condition at the call site. A file name mentioned in prose is not
+   a route.
+3. **Branch by situation, not by topic.** The router branches on what the agent
+   is doing now (daily work, feedback, nightly, a decision), so each branch
+   loads only what that situation needs.
+4. **Skill, reference, knowledge.** A skill holds a procedure (how to do). A
+   reference holds facts and examples (what to know). knowledge.md holds mental
+   models (how to think).
+5. **A hard ceiling per file.** 2,000 tokens now, with a measured trial at
+   1,500. The whole file counts, including frontmatter and routes, with one
+   agreed tokenizer.
+6. **Split before the ceiling.** At about 80% of the ceiling (1,600 tokens) the
+   agent must split. Raising the ceiling is not an option. First remove
+   duplication and sharpen conditions; then move detail behind a route.
+7. **Prohibitions load first.** A "never do X" rule lives on the route to X, so
+   it is loaded before the action it governs.
+8. **Bounded depth.** At most three hops from the entry router to any rule. No
+   cycles.
+9. **Every split is verified.** Map each original rule to its new home, check
+   that every route resolves, and check that each new condition covers the
+   situations the original covered.
+10. **Every skill sets a layer.** Put `layer: craft` or `layer: private` in the
+    frontmatter. `craft` is a general technique: it is copied when the agent is
+    forked or cloned, so it must not name a user, repo, system, person, or
+    product. `private` names the environment and is never copied. When unsure,
+    use `private`. A split keeps the layer of the original. `layer:` classifies
+    the skill's source. Package skills (rendered by Academy from `templates/`,
+    Owner pack included) are package-owned and regenerated for each agent. A
+    fork, clone, or template never copies a rendered package skill. It renders
+    the skill again from the package. Only skills the agent wrote are copied,
+    and only when they have `layer: craft`.
+
+## Split
+
+1. Remove duplication. Sharpen vague conditions.
+2. Still at or over 80%: move a procedure to its own skill, or facts and
+   examples to a reference file beside the skill. Put a `useWhen` route to it
+   where the moved content used to be. Move each prohibition with its action.
+3. Verify the split (rule 9). List each original rule and its new home.
+
+## Tokenizer
+
+The one agreed tokenizer is Academy's `estimateTokens`: the larger of the
+word-and-symbol chunk count and characters / 4. Bytes / 4 is a lower bound, so
+a file that looks under the ceiling by bytes can still fail.
+
+## Check
+
+Run `academy skills check {{agent_name}}` (add `--json` for a report). It
+measures every SKILL.md and reference file in `.claude/skills/` and
+`.agents/skills/`: `warn` at 1,600 tokens, `fail` over 2,000, exit 1 on any
+fail.