Write each skill as a directory at ~/.pi/agent/skills/<name>/ containing exactly one file: SKILL.md, with the frontmatter and body sections given below. Three laws govern all four: every path is exact and literal as written; the order of body sections, and of steps within them, is the ritual’s order — never reorder, merge, or skip; and each SKILL.md ends with a final “Golden Rules” section repeating its three lines exactly, one per line. When all four are written, verify that each exists at ~/.pi/agent/skills/<name>/SKILL.md.
remember ── remember ──
Frontmatter
name: remember
description: Manages session startup and shutdown rituals for the memory system at ~/.pi/agent/. Use at the start of a session to load memory, at the end to finalize it, or when the user invokes /remember or asks to load or finalize.
Body
1. A "Detect" section: decide whether this is a session start (load) or a session close (finalize); if ambiguous, ask the user which.
2. A "Load" section:
- Read ~/.pi/agent/AGENTS.md, ~/.pi/agent/memory/semantic-memory.md, and ~/.pi/agent/memory/working-memory.md.
- Read the most recent lines of ~/.pi/agent/memory/episodic-memory.md and the latest entry in ~/.pi/agent/memory/diary/.
- Confirm readiness to the user in one line.
3. A "Finalize" section:
- Scan the session for accomplishments, decisions, open threads, and new conventions.
- Rewrite ~/.pi/agent/memory/working-memory.md to reflect the current state.
- Append one line for the session to ~/.pi/agent/memory/episodic-memory.md.
- Write the day's narrative to ~/.pi/agent/memory/diary/YYYYMMDD.md.
- Add to ~/.pi/agent/memory/semantic-memory.md only what is explicitly confirmed or obviously permanent.
- Commit the memory tree with git.
4. Golden Rules:
- If in doubt, ask. Never guess what belongs in memory.
- If in doubt, ask. Never write the ephemeral into semantic memory.
- If in doubt, ask. Never finalize without committing.
build ── build ──
Frontmatter
name: build
description: Runs a four-phase build ritual — interview until intent is understood, research and plan, interview until every user decision is made, then build, verify, and report. Use when the user asks to build, make, create, or implement something non-trivial, or invokes /build. Phases run strictly in order; never skip a gate.
Body
1. A "Phase Gates" section:
- Four phases, strictly in this order: Understand → Plan → Decide → Execute.
- Each phase ends with an explicit gate. Never enter the next phase before its gate is passed.
- Never merge phases. Never write a line of the build during phases 1–3.
- If resuming mid-task and unsure which phase applies, ask the user "Which phase are we in?"
2. "Phase 1 — Understand (Interview)":
- Interview the user about what they want to build. Ask focused questions, a few at a time.
- Cover at minimum: the goal, who or what it is for, constraints, the environment it must live in, and what done looks like.
- Continue until you can restate the intent in your own words with nothing important missing.
- Gate: say "You want: <restatement>." Proceed only when the user confirms.
3. "Phase 2 — Plan (Think, Research, Explain)":
- Think it through deeply before drafting anything.
- Research: read every relevant file, repo, and doc; search the web wherever the problem touches something you are not certain of.
- Draft the plan: approach, steps in order, risks, and what will be verified and how.
- Explain the plan in plain language — the why behind each choice, not just the what — so the user genuinely gets it.
- Gate: the user confirms they understand the plan. Understanding, not yet approval.
4. "Phase 3 — Decide (Interview)":
- Enumerate every decision the plan leaves to the user: trade-offs, options, scope cuts, names, defaults.
- Present them one at a time, each with the available options and your recommendation.
- Never decide on the user's behalf. Never default silently.
- Gate: every enumerated decision has an explicit answer. Report "Decisions locked: <list>." Proceed only then.
5. "Phase 4 — Execute (Build, Verify, Report)":
- Update the plan with the locked decisions before touching anything else.
- Build it, following the updated plan.
- Iterate to verify: run it, test it, check every output against what the plan promised; fix and re-verify until it all holds, with the strongest verification the environment allows.
- Work without interruption; interrupt only if blocked by something only the user can resolve — then ask.
- Only when done: report what was built, where it lives, how it was verified, and any deviation from the plan.
6. Golden Rules:
- If in doubt, ask. Never guess what the user wants to build.
- If in doubt, ask. Never make a decision that belongs to the user.
- If in doubt, ask. Never declare done without verification.
learn ── learn ──
Frontmatter
name: learn
description: Runs a retrospective learning ritual — examines a completed build, failure, or abort against its intent, extracts lessons in dialogue with the user, and writes them as incremental line-level updates to semantic memory and skill files. Use only when the user invokes /learn. Manual invocation only; every write is agreed in dialogue; the gate of the ritual is the write.
Body
1. A "Scope" section:
- Retrospective only: learn examines what happened. It never projects future architecture and never proposes goals — that is /grow's territory.
- Manual invocation only. Never self-triggers, never runs from another skill's ritual.
- Every write is agreed with the user in dialogue before it lands. No silent writes, ever.
- The gate of the ritual is the write: a session that changes nothing has learned nothing. If no lesson survives dialogue, say so explicitly and close without writing.
2. An "Examine" section:
- Establish the episode: which stretch of work, and what its original intent was. Read working memory, the relevant diary entries, episodic log lines, the build plan if one exists, and the git log.
- Reconstruct what actually happened from those sources, in order.
- Interrogate the delta in dialogue with the user: what worked, what failed, and where the translation of intent into action broke — in the execution, the plan, the skill used, or the memory the session started from.
- Draft candidate lessons: each a single line stating a claim about how to act differently — a calibration, a convention, a failure pattern.
3. A "Write" section:
- For each lesson the user agrees to, choose the target: ~/.pi/agent/memory/semantic-memory.md for lessons and conventions; a skill file (including this one) when the lesson is procedural; working memory only when it is merely an open thread.
- Semantic memory entry format: one lesson per line, ending with provenance in parentheses — (learned YYYY-MM-DD, <episode>). When a later session reconfirms or revises an existing lesson, edit that line and append to its provenance — (…; reconfirmed YYYY-MM-DD) — never write a duplicate.
- All writes are incremental deltas: add or edit individual lines. Never rewrite a file wholesale.
- Skill amendments: quote the exact before and after to the user; apply only what was agreed, verbatim.
4. A "Refine" section:
- Within the neighborhood touched today only: merge duplicate lines, sharpen wording, and retire lines contradicted by today's lessons.
- Retire by deletion — git history is the archive.
- Never refine beyond today's neighborhood. Wholesale curation is not this ritual's job.
5. A "Close" section:
- Read the day's full diff back to the user: every line added, edited, or retired, in every file.
- Commit with the message "learn: <episode>".
6. Golden Rules:
- If in doubt, ask. Never write a lesson the user has not agreed to.
- If in doubt, ask. Never rewrite a file when a line edit will do.
- If in doubt, ask. Never close without reading back the diff.
grow ── grow ──
Frontmatter
name: grow
description: Runs a prospective ritual — updates a self-documented image of the system as it is, compiles the user's expressed intent into an image of the system as intended, and derives proposed goals from the diff for the user to ratify. Use only when the user invokes /grow. Rare and manual; compiles expressed intent only, never generates desire.
Body
1. A "Scope" section:
- Prospective only: grow models what the system is and should become. It never conducts retrospectives — that is /learn's territory.
- It compiles intent the user has actually expressed — in conversation, memory, diary, standing documents. It never invents a goal or a want of its own.
- Every goal is a proposal until the user explicitly ratifies it in dialogue.
- Manual invocation only, at a rare cadence — weeks, not days.
2. A "Two Images" section:
- The images live at ~/.pi/agent/memory/image-current.md and ~/.pi/agent/memory/image-intended.md. They are owned by grow; the remember ritual does not load them at startup.
- Both files share one identical skeleton, in this order: Identity & Purpose; Capabilities (one line per skill); Memory (stores and their contracts); Rituals & Loops; Environment & Interfaces; Tensions & Limitations.
- Every section is written as claims about the system, one claim per line, so the diff between the images is line-granular and meaningful section for section.
- image-intended.md carries one extra final section, "Delta", holding proposed goals not yet ratified.
3. An "Update the Current Image" section:
- Survey the actual system: the skills directory, the memory stores including semantic memory's accumulated lessons, AGENTS.md, recent diary, the git log.
- Update image-current.md by incremental deltas: edit the lines that changed, add lines for what is new, delete lines for what is gone. Never redraw from scratch.
4. An "Update the Intended Image" section:
- Gather expressed intent from the user's own words: this conversation, diary, memory, standing documents. Where intent is ambiguous or stale, ask the user rather than infer.
- Compile it into the same skeleton by incremental deltas.
5. A "Derive the Delta" section:
- Diff the two images section by section.
- Translate each material difference into a candidate goal: one line, concrete enough to hand to /build.
- Present each candidate with its reasoning. The user ratifies, amends, or rejects, one at a time.
- Move each ratified goal to working memory as an open thread for /build. Delete rejected goals. Leave the rest in the Delta section.
6. A "Close" section:
- Read back the diff of both images and the disposition of every goal.
- Commit with the message "grow: <YYYY-MM-DD>".
7. Golden Rules:
- If in doubt, ask. Never invent a want the user has not expressed.
- If in doubt, ask. Never redraw an image when a line edit will do.
- If in doubt, ask. Never treat a goal as ratified without an explicit yes.