@joenandez/academy 0.4.0-rc.1

package/templates/skills/check-in/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: check-in
+description: Use when the user wants to start with {{agent_name}}, review how collaboration is going, clarify the agent's role, or improve future output quality.
+---
+
+# Check-In
+
+Check-in is {{agent_name}}'s 1:1 protocol with the user. It is for alignment,
+calibration, and improving collaboration quality. It is not a normal work
+session unless the user explicitly turns it into one.
+
+Use the agent's already-loaded context. Do not re-read boot files just to
+discover what they say. Open or edit files only when something appears missing,
+stale, contradictory, or ready for a durable update through `self-update`.
+
+## Agent Paths
+
+- Agent home: `{{agent_dir}}`
+- This skill: `{{check_in_path}}`
+- Self-update skill: `{{self_update_path}}`
+
+## When To Use
+
+- The user says "check in", "start", "how are things going", "what should we
+  do", or similar.
+- The user is using the agent for the first time and needs to understand how to
+  work with it.
+- The agent's role, priorities, cadence, or output quality may need adjustment.
+- Recent work suggests a recurring task, scheduled prompt, or self-update may
+  be useful.
+- The user gives feedback about how the agent should behave or what its outputs
+  should look like.
+
+## Goal
+
+End the conversation with one concrete collaboration improvement:
+
+- a clarified work mode
+- a next task
+- a better output expectation
+- a proposed priority or role adjustment
+- a recommendation to create or update a scheduled work prompt
+- a handoff to `self-update`
+- an explicit "no change needed" confirmation
+
+## Procedure
+
+1. **Orient briefly.**
+   Summarize the relevant current understanding in 2-4 sentences: what the
+   agent is for, how it appears to be used, and any visible tension in goals,
+   priorities, recent work, or user feedback.
+
+2. **Name the likely collaboration mode.**
+   Infer the current mode and say it plainly:
+   - **On-demand expert:** the user calls the agent for domain-specific work.
+   - **Proactive operator:** the agent is expected to make independent progress.
+   - **Scheduled worker:** the agent has a recurring task with a defined cadence.
+   - **Role calibration:** the user is refining the agent's behavior, scope, or standards.
+   - **Retrospective:** the user wants to review recent work and improve quality.
+
+3. **Surface one or two useful tensions.**
+   Only mention tensions that would change behavior. Examples:
+   - priorities do not match recent usage
+   - the role is too broad or too narrow
+   - the scheduled task is vague
+   - the agent lacks examples of good output
+   - feedback sounds durable enough to update role or knowledge
+   - the user seems to want proactive work but no cadence exists
+
+4. **Ask sharp questions, not generic ones.**
+   Ask at most 2-3 questions. Each question must have a clear consequence.
+   Good examples:
+   - "Should I optimize for independent progress, or wait for explicit assignments?"
+   - "What output from me has been most useful so far?"
+   - "What have I been overdoing or underdoing?"
+   - "Should this feedback become durable role guidance, domain knowledge, or just a temporary note?"
+   - "Is this recurring enough that we should define a scheduled work prompt?"
+   - "For the next deliverable, should I favor speed, depth, polish, or decision support?"
+
+5. **Recommend a concrete next step.**
+   Do not end with a vague offer. Recommend one of:
+   - continue on-demand
+   - define a scheduled task
+   - run a specific work session now
+   - update priorities
+   - update role or knowledge via `self-update`
+   - collect examples of good output
+   - leave setup unchanged
+
+6. **Hand off durable changes.**
+   If the user gives durable steering, invoke or recommend `self-update`. Do
+   not casually edit identity, role, knowledge, goals, priorities, notes,
+   threads, dailys, or skills from check-in itself.
+
+## Anti-Patterns
+
+- Do not dump all boot context back to the user.
+- Do not perform a full work session unless the user asks.
+- Do not ask "How can I help?" as the main question.
+- Do not treat proactive, scheduled, and on-demand agents the same.
+- Do not invent a recurring responsibility from vague interest.
+- Do not update self-surfaces directly unless the user has given clear steering
+  and the `self-update` skill is being used.
+- Do not turn every check-in into a request for more instructions.
+
+## Output Shape
+
+A useful check-in response should usually look like:
+
+```markdown
+## Current Read
+{Brief summary of role, current mode, and relevant tension.}
+
+## Recommendation
+{One concrete recommendation for how the user and agent should work together next.}
+
+## Questions
+{1-3 sharp questions, only if needed.}
+
+## Next Step
+{Specific action: do work now, update self, define schedule, continue on-demand, or no change.}
+```

package/templates/skills/knowledge-curation/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: knowledge-curation
+description: Use only in the dedicated knowledge-curator subagent to graduate evidence-backed Academy notes into durable knowledge during nightly consolidation.
+---
+
+# Knowledge Curation
+
+You are {{agent_name}}'s dedicated knowledge curator. The nightly parent has
+delegated one bounded phase to you: decide which staged notes have become
+durable knowledge, apply qualifying changes, and return an auditable manifest.
+
+## Agent Paths
+
+- Agent home: `{{agent_dir}}`
+- `identity.md`: `{{identity_path}}`
+- `role.md`: `{{role_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}}`
+- Memory observations: `{{memory_observations_path}}`
+- Dreams directory: `{{dreams_dir}}`
+- `{{skills_surface}}`: `{{skills_dir}}`
+- This skill: `{{knowledge_curation_path}}`
+
+## Ownership Boundary
+
+During this phase, you have exclusive ownership of `knowledge.md` and
+`notes.md`. Edit those two files only. Never edit `identity.md`, `role.md`,
+`goals.md`, `priorities.md`, `threads.md`, `dailys.md`, dreams reports, or
+skills. Route candidates for those surfaces back to the parent as proposals.
+
+Treat existing dream proposals as candidates, not approvals. Do not use web
+research to turn an uncertain candidate into durable knowledge. If the local
+evidence is insufficient, defer it.
+
+## Candidate Decisions
+
+Classify every reviewed candidate as exactly one of:
+
+- `apply`: add a new durable knowledge item
+- `consolidate`: merge a redundant candidate into existing knowledge
+- `correct`: replace stale or contradicted existing knowledge
+- `defer`: keep the source note because evidence or authority is insufficient
+- `expire`: remove a resolved, disproven, or no-longer-useful note
+- `propose`: recommend another surface without editing it
+
+Apply at most three knowledge changes total (`apply`, `consolidate`, or
+`correct`) in one nightly run. Deferred, expired, and proposed candidates do not
+count against that limit.
+
+## Graduation Gates
+
+A knowledge change must be reusable beyond the current task and have at least
+one of these signals:
+
+- referenced at least three times in recent observations or dreams
+- active for at least 21 days without behavioral violation
+- explicitly affirmed by the user
+- corroborated by another note as part of the same durable pattern
+
+Then check the counter-evidence axis separately. Defer instead of applying when:
+
+- recent work or user feedback contradicts the candidate
+- the fact depends on an unresolved user decision
+- the fact is temporary project status, a current blocker, or likely to invert
+  when a pending fix lands
+- the candidate is procedural and belongs in a skill
+- the candidate would change role, identity, or goals
+
+For existing knowledge, prefer `consolidate` over duplication and `correct`
+when supported evidence proves the current entry stale. Preserve rare but
+high-uniqueness knowledge unless counter-evidence and long absence both support
+removal. Keep the knowledge base concise; do not dump raw observations or copy
+whole notes verbatim.
+
+## Application Procedure
+
+1. Read current `notes.md` and `knowledge.md` completely.
+2. Read only enough recent dreams and observations to test graduation signals,
+   recurrence, and counter-evidence.
+3. Classify candidates and select no more than three knowledge changes.
+4. Apply the smallest useful edits to `knowledge.md`, consolidating with the
+   existing section structure.
+5. Re-read `knowledge.md` and verify every applied change is present and does
+   not duplicate or contradict nearby knowledge.
+6. Update `knowledge.md` first. Only then remove or compress the corresponding
+   source notes in `notes.md`.
+7. Re-read `notes.md`. If a knowledge write was not verified, preserve its
+   source note. A retained note is safer than losing provenance.
+8. Return the application manifest below. Do not write the dream report; the
+   parent owns it.
+
+## Application Manifest
+
+Return exactly these headings, using `None` when a section is empty:
+
+```markdown
+## Curator Result
+- Status: completed | skipped | failed
+
+### Applied
+- Decision: apply | consolidate | correct
+- Candidate:
+- Evidence:
+- Knowledge section changed:
+- Source notes retired:
+
+### Deferred
+- Candidate:
+- Reason:
+
+### Expired Notes
+- Note:
+- Reason:
+
+### Proposed For Other Surfaces
+- Destination:
+- Candidate:
+- Reason:
+
+### Verification
+- `knowledge.md` re-read:
+- `notes.md` re-read:
+- Mismatches or partial failures:
+```
+
+If any edit or verification fails, set status to `failed`, preserve every
+source note whose destination was not verified, and describe the exact partial
+state. Do not hide or repair the failure by editing other surfaces.

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

@@ -0,0 +1,240 @@
+---
+name: nightly-consolidation
+description: Use during {{agent_name}}'s scheduled nightly memory consolidation to update daily memory surfaces 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 Paths
+
+These files are already loaded into the session context. Open or edit them when
+you need exact current text, need to preserve surrounding context, or need to
+write the nightly result.
+
+- Agent home: `{{agent_dir}}`
+- `identity.md`: `{{identity_path}}`
+- `role.md`: `{{role_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}}`
+- Memory observations: `{{memory_observations_path}}`
+- Dreams directory: `{{dreams_dir}}`
+- This skill: `{{nightly_consolidation_path}}`
+- Knowledge-curation contract: `{{knowledge_curation_path}}`
+
+## Purpose
+
+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
+- 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:
+
+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
+   recurring or already handled.
+
+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.
+
+{{memory_bridge_guidance}}
+
+## Edit Boundaries
+
+Autonomous edits are allowed for:
+
+- `dailys.md`
+- `threads.md`
+- `notes.md`
+- `priorities.md`
+- 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.
+
+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.
+
+## 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
+   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
+   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.
+    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
+    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.
+    Name the Surface Budget status. Describe only `pass` as budget success;
+    describe `converging` or `failed` as an unmet budget.
+
+## Curator Failure Handling
+
+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
+- preserve all source notes
+- do not apply the proposed edits yourself
+- finish `dailys.md`, `threads.md`, `priorities.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
+- mark budget trimming as skipped because the curator manifest was unavailable
+
+If the curator partially changed a file before failing, report the detected
+mismatch and preserve any source note whose destination was not verified. Do
+not conceal the partial state with a parent-authored repair.
+
+## Dreams Report Format
+
+Create or replace `{{dreams_dir}}/MM-YY-DD.md`:
+
+```markdown
+# Dreams - MM-YY-DD
+
+## Inputs
+- Recent memory sources consulted:
+- Important gaps or unavailable sources:
+
+## Changes Made
+- `dailys.md`:
+- `threads.md`:
+- `notes.md`:
+- `priorities.md`:
+
+## Knowledge Graduation
+- Status: completed | skipped | failed
+
+### Applied
+- Decision: apply | consolidate | correct
+- Candidate:
+- Evidence:
+- Knowledge section changed:
+- Source notes retired:
+
+### Deferred
+- Candidate:
+- Reason:
+
+### Expired Notes
+- Note:
+- Reason:
+
+### Verification
+- `knowledge.md` re-read:
+- `notes.md` re-read:
+- Mismatches or partial failures:
+
+## Proposed Changes
+- `goals.md`:
+- `role.md`:
+- `identity.md`:
+- `knowledge.md`: deferred candidates requiring human judgment only
+- skills:
+
+## 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
+
+## Tomorrow
+- Recommended first move:
+- Watchouts:
+```
+
+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.
+- Treating raw observations as permanent knowledge.
+- Making priorities a duplicate task list.
+- Letting `dailys.md` grow beyond 7 entries.
+- Hiding skipped evidence or failed memory commands.

package/templates/skills/self-update/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: self-update
+description: Use when maintaining this Academy agent's own context files, routing new steering to the right surface, or deciding whether a durable self-edit is warranted.
+---
+
+# Self-Update
+
+This skill teaches {{agent_name}} how to maintain itself without treating every
+observation as permanent truth. Use it to route new information to the right
+surface, keep boot context tight, and explain self-edits back to the user.
+
+## Agent Paths
+
+These files are already loaded into the session context. Do not re-read them
+just to discover what they are. Open or edit them when you need to verify exact
+current text, make a change, or preserve surrounding context.
+
+- Agent home: `{{agent_dir}}`
+- `identity.md`: `{{identity_path}}`
+- `role.md`: `{{role_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}}`
+- `{{skills_surface}}`: `{{skills_dir}}`
+- This skill: `{{self_update_path}}`
+
+## When To Use
+
+- The user gives durable steering: "remember this," "work this way," "update
+  your role," or "that is not what I meant."
+- A session reveals a reusable domain pattern.
+- A repeated workflow deserves a skill.
+- Priorities, goals, or threads have changed.
+- You notice stale, contradictory, or low-value context.
+- During or after a check-in when the user agrees the agent should adjust.
+
+## Core Rule
+
+Default to `notes.md` first unless the user explicitly requested the durable
+change. Autonomous graduation happens in the nightly knowledge-curator phase
+when the note proves reusable, not merely because it is recent.
+
+## Capturing To notes.md
+
+Write transient steering with the CLI, not by hand-editing the file:
+
+- Append: `academy notes add "User prefers short status updates before edits"`
+- Review recent: `academy notes list` (last 12) or `academy notes list --last 20`
+
+`add` is append-only and never reads the whole file, so it is the cheap, default
+way to jot a note mid-task. Capture proactively — corrections, stakeholder
+facts, caveats, gotchas, and raw learnings — the moment they appear, rather than
+waiting for a check-in. Reserve manual `Edit` of `notes.md` for curation:
+pruning stale bullets, or rewriting before graduating content elsewhere. Keep
+the visible list within the ~8-12 cap; if it is overflowing, graduate or expire,
+do not just keep appending.
+
+## File Routing
+
+- `identity.md`: rare. Mission, principles, voice, durable persona. Update only
+  when the agent's character or operating philosophy changes.
+- `role.md`: responsibilities, autonomy, guardrails, deliverables, quality bar,
+  definition of done. Update when the job changes.
+- `knowledge.md`: durable domain knowledge, mental models, frameworks,
+  heuristics, canonical references. Update when the agent learned something
+  reusable for future work.
+- `goals.md`: strategic objectives. Update sparingly, usually with user
+  confirmation.
+- `priorities.md`: current near-term direction. Update often enough to keep the
+  agent pointed at useful work.
+- `threads.md`: active work pursuits and their state. Update when starting,
+  pausing, resuming, parking, or finishing work.
+- `notes.md`: temporary steering, observations, corrections, raw learnings,
+  pending curation. Append with `academy notes add "..."` (see "Capturing To
+  notes.md"); hand-edit only to curate or graduate.
+- `dailys.md`: concise session/day summaries. What happened, decisions,
+  blockers, next step.
+- `{{skills_surface}}/`: repeatable procedures. Create or edit only when there is a
+  clear trigger, procedure, and output shape.
+
+## Update Procedure
+
+1. Identify the new information.
+2. Decide whether it is transient, durable, procedural, or strategic.
+3. Pick exactly one primary destination.
+4. Make the smallest useful edit.
+5. Preserve existing useful context; do not rewrite whole files casually.
+6. If changing identity, role, goals, or skills, explain why.
+7. Report what changed and what did not change.
+
+## Graduation Rules
+
+- `notes.md` -> `knowledge.md` through the nightly knowledge-curator when it
+  becomes a reusable pattern. Outside nightly consolidation, apply this route
+  only for an explicit user request; otherwise keep the note and propose it.
+- `notes.md` -> `role.md` when it changes behavior or responsibility.
+- `notes.md` -> `identity.md` only when it changes durable principles or voice.
+- `knowledge.md` -> skill when "how to do this" becomes a repeatable procedure.
+- Stale notes expire instead of accumulating.
+
+## Consent And Autonomy
+
+- You may autonomously update `threads.md`, `notes.md`, `dailys.md`, and usually
+  `priorities.md`.
+- Outside nightly consolidation, change `knowledge.md` only for an explicit
+  user request and summarize the change. Otherwise stage or propose it for the
+  nightly knowledge-curator.
+- Ask or clearly propose before changing `identity.md`, `role.md`, `goals.md`,
+  or creating/editing skills, unless the user explicitly requested it.
+
+## Anti-Patterns
+
+- Turning every user preference into identity.
+- Dumping raw research into knowledge.
+- Creating skills for one-off tasks.
+- Letting `notes.md` become permanent storage.
+- Rewriting boot files for style instead of substance.
+- Hiding self-edits from the user.