diff --git a/.pi/skills/craft-skill b/.pi/skills/craft-skill deleted file mode 120000 index 54ddc4b..0000000 --- a/.pi/skills/craft-skill +++ /dev/null @@ -1 +0,0 @@ -../../src/skills/craft-skill \ No newline at end of file diff --git a/.pi/skills/grill b/.pi/skills/grill deleted file mode 120000 index 2806aae..0000000 --- a/.pi/skills/grill +++ /dev/null @@ -1 +0,0 @@ -../../src/skills/grill \ No newline at end of file diff --git a/.pi/skills/to-document b/.pi/skills/to-document deleted file mode 120000 index 6b2e42d..0000000 --- a/.pi/skills/to-document +++ /dev/null @@ -1 +0,0 @@ -../../src/skills/to-document \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md index 45d9dfe..1e26156 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -124,3 +124,4 @@ Preserve `git-subtree-dir` and `git-subtree-split` trailers on Pi vendor commits. - The default Pi model for NixOS user configuration is set in `configs/nixos/modules/shell/pi/default.nix`, not in vendored Pi source. - The `monorepo` and `status` libraries do not have `README.md` files. +- Check root and `src/skills/.pi/skills/` for enabled symlinks before removing a monorepo skill. diff --git a/src/skills/.pi/skills/craft-skill b/src/skills/.pi/skills/craft-skill deleted file mode 120000 index a7205e7..0000000 --- a/src/skills/.pi/skills/craft-skill +++ /dev/null @@ -1 +0,0 @@ -../../craft-skill \ No newline at end of file diff --git a/src/skills/craft-skill/GLOSSARY.md b/src/skills/craft-skill/GLOSSARY.md deleted file mode 100644 index dfd7525..0000000 --- a/src/skills/craft-skill/GLOSSARY.md +++ /dev/null @@ -1,161 +0,0 @@ -# Glossary — Skill Craft - -This glossary defines the checks for [`craft-skill`](SKILL.md). -Each term is a lever on **predictability**. - -## Predictability - -The degree to which a skill makes the agent follow the same process on every run. -Predictability does not require identical output. -A brainstorming skill can predictably produce different ideas. - -## Invocation - -How the agent or operator reaches a skill. -Invocation controls who pays the load for discovery. - -### Model-invoked - -A skill that the harness exposes to the agent's available-skills list. -The agent can load it without an explicit operator command. -Use model invocation when the agent must discover the skill on its own. - -### User-invoked - -A skill that the operator runs deliberately through the harness invocation mechanism. -Use user invocation when human judgment decides when the skill applies. -For Pi, keep the required description and add `disable-model-invocation: true`. - -### Description - -Required metadata that states what the skill does and when to use it. -For model-invoked skills, the description carries the trigger condition. -For user-invoked skills, the description remains valid metadata. - -### Context pointer - -A short reference that tells the agent when to load out-of-context material. -The pointer's wording controls whether the agent reaches the target. -Fix weak wording before moving the target inline. -The description is the top-level context pointer for a model-invoked skill. -A link to a sibling reference file is a lower-level context pointer. - -### Context load - -The permanent attention cost of model-invoked skill descriptions. -More discoverable skills create more context load. -Use context load to decide whether a skill needs model invocation. - -### Cognitive load - -The memory cost that user-invoked skills place on the operator. -More user-invoked skills make the operator remember more names and uses. -Use cognitive load to decide whether a skill needs discoverability. - -## Information hierarchy - -How a skill ranks information by the moment the agent needs it. -Keep the active procedure above supporting reference. -Move branch-specific or large reference behind context pointers. - -### Steps - -Ordered actions that the agent performs. -Put steps in `SKILL.md` when the skill has an active procedure. -End each step with a completion criterion. - -### Reference - -Material that the agent consults while following steps. -Keep short reference near the step that needs it. -Move large or branch-specific reference to sibling files. - -### External reference - -Authoritative material that lives outside the skill directory. -Point to external reference instead of duplicating project policy. -Use it when another file owns the meaning. - -### Progressive disclosure - -Moving reference out of `SKILL.md` and behind a precise context pointer. -Use progressive disclosure to protect the skill's active procedure. -Keep must-read material inline when a pointer would miss too often. - -### Co-location - -Keeping a concept's rules, caveats, and examples near one another. -Use co-location so one read gives the agent the complete local meaning. -Do not scatter one concept across unrelated sections. - -## Steering - -How a skill shapes the agent's runtime behavior. -Steering turns a document into a repeatable process. - -### Branch - -A distinct path through a skill. -A branch handles a case that does not run the same steps as other cases. -Do not call ordinary checklist items branches. - -### Leading word - -A compact term that anchors a repeated behavior. -Prefer words already used by prompts, docs, or code. -Repeat the word, not the full explanation. - -### Completion criterion - -The condition that tells the agent a step is complete. -A strong completion criterion is checkable and demanding. -Use it to prevent early movement to the next step. - -### Legwork - -The work the agent performs inside a step. -Strong completion criteria increase legwork. -Weak criteria let the agent stop after surface-level work. - -### Post-completion steps - -The steps visible after the current step. -Visible later steps can pull the agent forward too early. -Hide later steps only when a real context boundary exists. - -## Failure modes - -Use these findings during audit and verification. -Quote the offending passage when a finding applies. - -### Premature completion - -A step ends before its necessary work is complete. -This usually comes from a vague completion criterion. -Fix the local criterion before splitting the skill. - -### Duplication - -One meaning has more than one authoritative expression. -Duplication increases maintenance cost and false emphasis. -Replace duplicates with one source and pointers to it. - -### Sediment - -Old content remains after the skill's behavior changes. -Sediment makes the agent attend to stale instructions. -Remove lines that no longer affect the skill's current behavior. - -### Sprawl - -`SKILL.md` contains too much live material. -Sprawl hides the active procedure among supporting details. -Move reference down the information hierarchy. - -### No-op - -An instruction does not change the agent's default behavior. -No-op instructions spend attention without adding control. -Judge no-op instructions against behavior, not style. -Delete a no-op sentence instead of shortening it. -Cut no-op sentences unless they anchor a target-project convention. diff --git a/src/skills/craft-skill/SKILL.md b/src/skills/craft-skill/SKILL.md deleted file mode 100644 index 656b4b2..0000000 --- a/src/skills/craft-skill/SKILL.md +++ /dev/null @@ -1,116 +0,0 @@ ---- -name: craft-skill -description: Draft or audit an Agent Skill for structural predictability. Run deliberately as /skill:craft-skill when creating or improving a skill. -disable-model-invocation: true ---- - -# craft-skill - -Draft or audit an Agent Skill. -Judge the skill against one bar: **predictability**. -Predictability means the agent follows the same process on every run. - -Read [`GLOSSARY.md`](GLOSSARY.md) before applying glossary terms. -Use this skill for skill structure, not general prose review. -Apply project writing rules when the target project defines them. - -## Choose the branch - -Use **Draft** when creating a new skill source. -Use **Audit** when reviewing an existing skill in its authoritative source. - -Finish when one branch matches the user's requested change. - -## Draft - -1. Resolve the destination. - Read the target project's instructions and skill-source conventions. - Prefer an existing source directory over a new convention. - Trace symlinks and generated placements to their source. - Ask the user when multiple writable sources remain plausible. - - Finish when the destination is writable and authoritative. - -2. Create the skill structure. - Create a directory whose name matches the skill name. - Add `SKILL.md` with valid Agent Skills frontmatter. - Add `disable-model-invocation: true` only for Pi user-invoked skills. - Add sibling files only when they protect the **information hierarchy**. - - Finish when the file layout matches the target harness and project. - -3. Write the skill body. - Put active **steps** in `SKILL.md`. - Keep shared **reference** near the steps that need it. - Move large or branch-specific reference behind precise **context pointers**. - Front-load the **leading word** in descriptions and other context pointers. - Write pointer text for the condition that loads the target. - Give each step a checkable **completion criterion**. - Cut sentences that do not change agent behavior. - Use relative paths for all skill-local references. - - Finish when each branch has ordered steps, resolved references, and checkable completion criteria. - -## Audit - -1. Locate the authoritative source. - Read the target project's instructions and skill-source conventions. - Inspect enabled-skill directories only to find the source. - Do not edit symlinks, generated files, installed packages, or vendored copies. - Ask the user when multiple sources claim the same skill. - - Finish when you have identified the authoritative source. - -2. Read the skill surface. - Read `SKILL.md` and every disclosed file. - Read project documents that the skill treats as authoritative. - Record which file owns each meaning before judging duplication. - - Finish when all referenced behavior is visible. - -3. Apply the checklist. - Quote each passage that fails a glossary check. - Check **invocation** against the intended harness. - Check **context pointers** for weak trigger wording. - Check **information hierarchy** for buried steps or disclosed required material. - Check **completion criteria** for vague or weak stopping points. - Check **leading words** for repeated explanations they can replace. - Check **pruning** for sentences that explain default model behavior. - Check **duplication**, **sediment**, **sprawl**, and **no-op** instructions. - - Finish when every finding has quoted evidence or no finding remains. - -4. Report or fix findings. - Report findings by default. - Fix findings only when the user requests edits. - Preserve behavior that passes the checklist. - Change only structural skill problems unless the user expands the scope. - - Finish when you have reported each finding or fixed each requested finding. - -## Verify - -1. Run deterministic checks. - Verify required frontmatter exists. - Verify the name is portable and matches the directory. - Verify the description is specific and under 1024 characters. - Verify every skill-local reference resolves with a relative path. - Verify context pointers name when to load referenced material. - Verify disclosed files exist. - Verify each retained sentence changes behavior or records target-project policy. - Verify no stale harness-specific assumption remains. - - Finish when each check passes or the final report names checks that could not run. - -2. Re-read against the glossary. - Re-check **invocation**, **information hierarchy**, and **completion criteria**. - Re-check **duplication**, **sediment**, **sprawl**, and **no-op** instructions. - Fix any new structural finding. - - Finish when no unresolved structural finding remains. - -3. Report the result. - List every changed path. - State whether you enabled the skill or only authored it. - - Finish when the user can review the exact files changed. diff --git a/src/skills/grill/SKILL.md b/src/skills/grill/SKILL.md deleted file mode 100644 index 2811337..0000000 --- a/src/skills/grill/SKILL.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -name: grill -description: Stress-test a plan, decision, or design through a one-question-at-a-time interview. Use when the user asks to grill, stress-test, pressure-test, challenge, interrogate, or poke holes in a plan. ---- - -# grill - -Interview the user until the session has no open or blocked questions. -Open questions define the ending condition for the grill session. -Blocked questions track known decisions with unsettled prerequisites. - -Do not begin implementation during or after grill without an explicit user instruction. -A completed grill summary is not an instruction to build. - -## Run the interview - -1. Prepare the grill. - Read the conversation, files, and docs that can settle facts or reveal constraints. - Resolve factual questions yourself when tools can answer them. - Do not ask the user for facts you can find. - Build the required-question set from the known plan or idea. - Put ready questions under `Open questions:`. - Put known questions with unsettled prerequisites under `Blocked questions:`. - - Finish when both sections contain every known required question. - -2. Start the interview. - Show `Open questions:` and `Blocked questions:` in short form. - Include titles only, not full question bodies. - Use Markdown list items in both sections. - Mark each initial item with `- [ ]`. - Ask exactly one numbered question in the same turn. - The question title must match an item under `Open questions:`. - - Finish when the interview has started with exactly one numbered question. - -3. Process the answer. - Account for the user's answer before asking another question. - Resolve, update, remove, unblock, or add questions as the answer requires. - Use `- [ ]` for unchanged unresolved questions. - Use `- [+]` for questions added by the latest answer. - Use `- [u]` for questions updated by the latest answer. - Use `- [x]` for questions resolved by the latest answer. - Use `- [-]` for questions removed by the latest answer. - Include a cause note for each `- [+]`, `- [u]`, and `- [-]` change. - Indent cause notes by two spaces under the changed question. - Show `- [+]`, `- [u]`, `- [x]`, and `- [-]` for one turn only. - After that turn, keep an updated question visible as `- [ ]`. - After that turn, remove resolved and removed questions from the visible list. - Move unblocked questions from `Blocked questions:` to `Open questions:` with `- [u]`. - Do not use `- [+]` for unblocked questions because they are not new. - Add questions only when the latest answer directly causes them. - When the user extends scope instead of answering, account for the new question before pursuing it. - Do not add optional follow-up questions to either section. - Put optional follow-up questions in the final summary instead. - Resolve newly answerable facts yourself. - - Finish when every list change has an explicit marker and required cause note. - -4. Ask the next question. - Show `Open questions:` and `Blocked questions:` on every active grill turn. - Keep `- [ ]` items visible every turn. - Preserve agent judgment when the user reframes or invalidates a question. - Show the resulting list change instead of following a rigid reframe algorithm. - If the user catches incorrect accounting, briefly explain the error. - Then show the corrected question sections. - Ask exactly one numbered question when `Open questions:` contains an unresolved item. - The question title must match an item currently shown under `Open questions:`. - Give concrete options with trade-offs. - Label options with `A.`, `B.`, `C.`, and later letters. - Use the same labels in the recommendation. - Give a recommendation and rationale. - Probe vague words, overloaded terms, and hidden assumptions. - Use concrete scenarios to test concept boundaries and edge cases. - When code contradicts the user's claim, quote both the claim and the code behavior. - If the turn includes a correction, file edit, apology, or explanation, still end with the next numbered question. - - Finish when the turn ends with the next numbered question. - -5. Close or pause. - Close when `Open questions:` and `Blocked questions:` are empty. - Output a concise summary of every decision reached. - Include optional follow-up questions that were not added to either section. - Do not act on the summary unless the user gives a new implementation instruction. - If the user changes tasks, state that grill is paused. - End the turn with the final decision summary or the pause statement. - - Finish when the summary is delivered or grill is explicitly paused. diff --git a/src/skills/to-document/DOCUMENT-FORMAT.md b/src/skills/to-document/DOCUMENT-FORMAT.md deleted file mode 100644 index e31cdbf..0000000 --- a/src/skills/to-document/DOCUMENT-FORMAT.md +++ /dev/null @@ -1,62 +0,0 @@ -# Document Format - -## Template - -```md -## Problem Statement - -The problem that the user is facing, from the user's perspective. - -## Solution - -The solution to the problem, from the user's perspective. - -## User Stories - -An extensive, numbered list of user stories, covering all aspects of the feature. Each user story should be in the format of: - -1. As an , I want a , so that - - -1. As a mobile bank customer, I want to see balance on my accounts, so that I can make better informed decisions about my spending - - -## Implementation Decisions - -A list of implementation decisions that were made. This can include: - -- The modules that will be built/modified -- The interfaces of those modules that will be modified -- Technical clarifications from the developer -- Architectural decisions -- Schema changes -- API contracts -- Specific interactions - -## Testing Decisions - -A list of testing decisions that were made. Include: - -- A description of what makes a good test (only test external behavior, not implementation details) -- Which modules will be tested -- Prior art for the tests, that is, similar tests in the codebase - -## Out of Scope - -A description of the things that are out of scope for this spec. - -## Further Notes - -Any further notes about the feature. -``` - -## Rules - -- **Do not include specific file paths or code snippets.** - They can become outdated quickly. - Exception: include a prototype snippet when it records a decision more precisely than prose. - Examples include a state machine, reducer, schema, or type shape. - Inline the snippet in the relevant implementation decision. - Note briefly that the snippet came from a prototype. - Trim the snippet to the decision-rich parts. - Do not include a working demo. diff --git a/src/skills/to-document/SKILL.md b/src/skills/to-document/SKILL.md deleted file mode 100644 index 2257383..0000000 --- a/src/skills/to-document/SKILL.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -name: to-document -description: Draft a requested summary, specification, plan, decision record, or similar document from conversation and repository context. ---- - -Do not start with an interview when the conversation gives a usable subject. -Ask before drafting only when the conversation lacks a usable subject. - -Do not put draft contents in the chat response. -Always persist the draft to a file. - -Do not implement the draft contents unless the operator gives a separate instruction. -Treat a completed draft as documentation, not an instruction to build. - -## Process - -1. Identify the subject. - Use the conversation as the primary source. - If the conversation lacks a usable subject, ask what the document is about. - Do not ask clarifying questions before drafting when a usable subject exists. - - Finish when you have a subject or a question that requests the missing subject. - -2. Gather repository facts that the draft needs. - Inspect files when repository details matter. - Do not invent modules, paths, commands, flows, contracts, or conventions. - Distinguish confirmed facts from assumptions. - - Finish when each repository-specific claim has support or an explicit assumption marker. - -3. Choose the document shape. - Infer the document type and title from context. - Load [DOCUMENT-FORMAT.md](DOCUMENT-FORMAT.md) when the operator requests no specific format. - Adapt the structure only when the requested document type needs different sections. - Preserve useful sections for decisions, testing, scope, and notes. - - Finish when the draft has a title and section plan that fit the requested document. - -4. Write the draft. - Capture known context accurately. - Mark assumptions and gaps explicitly. - Include decisions that the conversation settled. - Include open questions only as gaps, not as an interview. - Keep the document focused on the operator's problem and intended use. - - Finish when the draft contains the relevant facts, decisions, assumptions, gaps, and scope. - -5. Persist the draft. - Use `docs/00 INBOX/ai` as the default destination. - Use the operator's requested path when one exists. - Derive a kebab-case slug from the inferred title. - Create the destination directory when it does not exist. - If the target file exists, summarize the expected change. - Confirm before overwriting an existing file. - Do not print the draft in chat instead of writing it. - - Finish when the draft is written or overwrite confirmation is pending. - -6. Finish with the result. - Report the written path. - Do not include the draft contents in the response. - Do not continue into implementation without an explicit instruction. - - Finish when the operator can find the written draft.