diff --git a/.agents/skills/plot-author/SKILL.md b/.agents/skills/plot-author/SKILL.md index cd8882b2..5eb489e3 100644 --- a/.agents/skills/plot-author/SKILL.md +++ b/.agents/skills/plot-author/SKILL.md @@ -26,6 +26,9 @@ process; a merge means players will live inside your con. ## What you are writing +The repository-skills spec describes this skill's purpose at +`wiki/process/repository-skills.md#checked-in-skills`. + The binding contract is `wiki/mechanics/plots.md` — read the whole page before writing (Behavior, "Writing a plot (the contributor contract)", and the worked example). This skill orders the work and gets your file diff --git a/.claude/skills/design-session/SKILL.md b/.claude/skills/design-session/SKILL.md index 623503f1..fd3e674b 100644 --- a/.claude/skills/design-session/SKILL.md +++ b/.claude/skills/design-session/SKILL.md @@ -1,22 +1,40 @@ --- name: design-session -description: Run a Misaligned design session — synthesize design riffs into constitutional amendments, decisions-log entries, spec documents, and devlogs. Use when Cameron is riffing on game design, proposing mechanics, or asking to "work through the design" rather than requesting implementation. +description: Capture affirmed Misaligned design decisions into the owning wiki law/spec pages, decision history, and devlogs. Use when Cameron says "lock it in," "capture this," "write/spec this," explicitly adopts a proposal, or requests a formal design session that should produce repository artifacts. Do not use for exploratory questions or confusion; use design-companion first. --- -# Design session (skill shim) +# Design session (capture) -The canonical workflow is `wiki/process/design-sessions.md` — follow it. Core -rhythm: recognize riffing vs deciding; respond with a genuine position -(strengths in this game's terms, honest tensions, your own proposals -clearly framed); capture everything in the same turn as DECIDED (amend -constitution + dated decisions-log entry), PROPOSED (marked, surfaced for -yes/no), [OPEN], or DEFERRED (Roadmap Deferred section — nothing is -lost); spec firmed-up systems into `wiki/` with acceptance criteria; close -with devlog, defense commits, push. +The canonical workflow is `wiki/process/design-sessions.md`. Follow it after +the capture gate has been crossed. -Taste calls that leave the chat become Tangled issues and must follow the -issue body standard in `wiki/process/tick.md`: singular `## Question` -(numbered choices), `## Why this is open`, `## Options`, -`## Recommendation`, `## What your answer unlocks`. Label them -`decision-required`; flip to `decision-made` when answered. No narrative -dumps. +Do not capture a speculative question, an unaccepted agent proposal, or an +"okay, but..." clarification. Keep those in `$design-companion` conversation. + +Once Cameron adopts a direction: + +1. Separate DECIDED, OPEN, and DEFERRED points. Do not silently promote an + inference into a decision. +2. Create a task worktree before any write. Verify where the patch tool resolves + paths and confirm the shared primary checkout remains unchanged. +3. Amend the single owning Type: law and/or Type: spec page so the current + decision exists in the binding corpus. Spec `Design:` entries use checked + `wiki/path.md#heading-anchor` references; summaries elsewhere are explicitly + non-authoritative. +4. Append decision history to the current dated volume under + `wiki/log/decisions/` without using the log as current authority. +5. File a `decision-required` Tangled issue only for a genuine unresolved taste + call Cameron intentionally leaves for later. Follow the issue format in + `wiki/process/tick.md`. +6. Record the session in the devlog, run the proportionate checks required by + `AGENT.md`, commit with a Defense paragraph when required, and land it. + +For a source-of-truth migration, follow `wiki/process/meta.md`'s whole-corpus +protocol. Inventory before and after, preserve log bodies, update every entry +point/check/renderer together, and treat the final rebase semantically. Inspect +concurrent commits with targeted `git show` reads and transplant their decisions +into the new owner; never accept a stale whole file that restores the retired +authority model. + +Keep the handoff concise: what was decided, the important tradeoff, what was +captured, and what remains open. diff --git a/.claude/skills/plot-author/SKILL.md b/.claude/skills/plot-author/SKILL.md index cd8882b2..5eb489e3 100644 --- a/.claude/skills/plot-author/SKILL.md +++ b/.claude/skills/plot-author/SKILL.md @@ -26,6 +26,9 @@ process; a merge means players will live inside your con. ## What you are writing +The repository-skills spec describes this skill's purpose at +`wiki/process/repository-skills.md#checked-in-skills`. + The binding contract is `wiki/mechanics/plots.md` — read the whole page before writing (Behavior, "Writing a plot (the contributor contract)", and the worked example). This skill orders the work and gets your file diff --git a/.claude/skills/session-wrap/SKILL.md b/.claude/skills/session-wrap/SKILL.md index 4ffa1717..dd4fd168 100644 --- a/.claude/skills/session-wrap/SKILL.md +++ b/.claude/skills/session-wrap/SKILL.md @@ -8,7 +8,89 @@ description: >- disable-model-invocation: true --- -# Session wrap (shim) +# Session wrap -Canonical instructions: `.agents/skills/session-wrap/SKILL.md`. Follow -that file exactly. +Close the session cleanly. Persist what the next agent needs; do not +re-litigate design or start new work. + +## Procedure + +1. **Orient** (read, do not dump): + - `.agents/memory.md` if it exists + - `git status -sb` and `git log --oneline -8` in the active worktree + - Whether work landed on `main`, sits on a task branch, or is dirty + +2. **Update project memory** — rewrite `.agents/memory.md` with the + template below. Keep it short. Overwrite stale "Current" facts; do not + append forever. Drop items that are done or already in the wiki. + +3. **Durable preferences only with consent.** If this session revealed a + standing preference that should bind future chats (not a one-off taste + call already in the wiki), list existing user rules via + `cursor_dialog` (`item=rule`, `scope=user`, `action=list`), propose + one candidate memory in chat, and add/update only after Cameron + agrees. Never invent rules silently. + +4. **Reply in chat** using the output format below. No emoji. No new + commits unless Cameron asks — memory file edits are fine; landing + unfinished work is not part of wrap. + +5. **Stop.** Do not start the next step unless asked. + +## Memory file + +Path: `.agents/memory.md` (create on first wrap if missing). + +```markdown +# Project memory + +Living handoff for agents. Updated by the session-wrap skill. Not law — +the wiki wins on conflict. Keep under ~40 lines. + +## Current + +- **Focus:** +- **Just landed:** +- **Open on branch / dirty:** +- **Blocked on Cameron:** + +## Carry forward + +- +- + +## Next + +1. +2. +3. +``` + +## Chat output format + +```markdown +## Session wrap + +**Done:** <1–3 bullets of what this chat accomplished> +**State:**
+**Memory:** updated `.agents/memory.md` () + +## Next steps + +1. +2. … +``` + +If nothing durable changed, still rewrite `## Current` dates/state so the +file reflects HEAD. If the session was conversation-only (design +companion), say so under **Done** and skip inventing implementation next +steps — point at design-session capture or the open question instead. + +## Guardrails + +- Wiki remains the design corpus. Memory holds handoff and unfinished + threads, not new law. +- Do not create Tangled issues, take a tick, or open a worktree during + wrap unless Cameron explicitly asks. +- Prefer ROADMAP / open `decision-required` issues when naming next work. +- Match Misaligned tone: direct, short, no AI attribution. diff --git a/.claude/skills/tick/SKILL.md b/.claude/skills/tick/SKILL.md index 812675ea..32427a20 100644 --- a/.claude/skills/tick/SKILL.md +++ b/.claude/skills/tick/SKILL.md @@ -1,13 +1,15 @@ --- name: tick -description: Take a tick — the project heartbeat. Audit the constitution (DESIGN.md) against the code for violations, contradictions, questions, bugs, or insecurities, then act on exactly one finding. Use at session start, when the user says "take a tick" or "/tick", or on autonomous loop fires. +description: Take a tick — the project heartbeat. Audit one coherent slice of the wiki design corpus against the code for violations, contradictions, questions, bugs, or insecurities, then act on exactly one finding. Use at the start of repository work, when the user says "take a tick" or "/tick", or on autonomous loop fires. Do not run for a conversation-only design-companion turn. --- # Tick (skill shim) The canonical procedure is `wiki/process/tick.md` — follow it exactly. Summary: -1. Read DESIGN.md fully + recent commits. +1. Read the corpus map, recent commits, and the relevant law/spec/dependency + slice. A spec's checked `Design:` anchors identify the binding clauses that + define the slice; a missing or misleading reference is itself a finding. 2. Find ONE thing: violation | contradiction | question | bug | insecurity (highest severity wins). 3. Act: violations/bugs/insecurities are fixed with a **Defense:** paragraph @@ -20,7 +22,7 @@ The canonical procedure is `wiki/process/tick.md` — follow it exactly. Summary flip to `decision-made` when Cameron answers. Never file a narrative dump. If an existing open issue is incomprehensible, rewrite it with `tang issue edit` before other work. Small ambiguities are resolved by - making the constitution more precise. + making the owning corpus page more precise. 4. Leave a trace (commit, issue, or [OPEN] marker) and end the tick. If `tang` reports not-authenticated, ask the user to run `tang auth login` diff --git a/wiki/SUMMARY.md b/wiki/SUMMARY.md index cd7013de..13baf1e6 100644 --- a/wiki/SUMMARY.md +++ b/wiki/SUMMARY.md @@ -111,6 +111,7 @@ - [The wiki (this migration)](process/wiki.md) - [ROADMAP: the dispatch board](process/ROADMAP.md) - [Agent-scale architecture](process/agent-scale.md) + - [Repository skills](process/repository-skills.md) - [The tick](process/tick.md) - [Design sessions](process/design-sessions.md) - [Development style](process/development-style.md) diff --git a/wiki/log/2026-07-10-repository-skills-spec.md b/wiki/log/2026-07-10-repository-skills-spec.md new file mode 100644 index 00000000..d333b914 --- /dev/null +++ b/wiki/log/2026-07-10-repository-skills-spec.md @@ -0,0 +1,22 @@ +# 2026-07-10 — Checked-in skills receive a governing spec + +``` +Type: log +``` + +- Intent: make the purpose and authority boundary of repository skills part of + the current corpus instead of leaving each skill as an unindexed procedural + island. +- Changed: added `wiki/process/repository-skills.md` as the process spec and + registered every checked-in `SKILL.md`, including compatibility mirrors, + with its purpose. The spec requires future skill additions, removals, + renames, and repurposing to update the registry in the same commit. The + `plot-author` skill now points directly to that governing spec while keeping + `wiki/mechanics/plots.md` as the plot-behavior owner. Re-synchronized the + stale `design-session`, `session-wrap`, and `tick` Claude mirrors with their + canonical shared skills. +- Design/spec impact: repository skills are now specified procedural entry + points, never independent game/process law; `.agents/skills/` is canonical + and declared `.claude/skills/` copies are byte-identical mirrors. +- Checks: docs gate, registry path audit, and mirror comparison. +- Next: keep the registry amendment atomic with every checked-in skill change. diff --git a/wiki/log/DEVLOG.md b/wiki/log/DEVLOG.md index b654697c..a87e9883 100644 --- a/wiki/log/DEVLOG.md +++ b/wiki/log/DEVLOG.md @@ -131,6 +131,11 @@ add or amend a session log, then re-run the generator. - Intent: (see session log) - Log: [wiki/log/2026-07-10-reticule-mode-grammar.md](2026-07-10-reticule-mode-grammar.md) +## 2026-07-10 - Checked-in skills receive a governing spec + +- Intent: (see session log) +- Log: [wiki/log/2026-07-10-repository-skills-spec.md](2026-07-10-repository-skills-spec.md) + ## 2026-07-10 - README status correction - Intent: The README still named continuous witness/narration as the next priority even though the narration spec is IMPLEMENTED and ROADMAP item #30 is complete. diff --git a/wiki/process/README.md b/wiki/process/README.md index 54f8528e..11ec01f3 100644 --- a/wiki/process/README.md +++ b/wiki/process/README.md @@ -8,5 +8,7 @@ How the design corpus stays alive: the living-spec law, the page-type system rule, the design conversation and explicit-capture workflow, development style, git/landing conventions, the dispatch board (`ROADMAP.md`), and multi-agent scale (`agent-scale.md` — claims, ledgers, gates, cache). The +checked-in procedural entry points and their purposes are governed by the +repository-skills spec (`repository-skills.md`). The decided Cargo workspace shape is `wiki/engineering/crate-workspace.md`. Read `development-style.md` and `tick.md` before your first edit. diff --git a/wiki/process/repository-skills.md b/wiki/process/repository-skills.md new file mode 100644 index 00000000..dac5824f --- /dev/null +++ b/wiki/process/repository-skills.md @@ -0,0 +1,67 @@ +# Spec: repository skills — procedural entry points + +``` +Type: spec +Status: IMPLEMENTED +Status note: the checked-in skill registry and canonical/mirror ownership are + explicit as of 2026-07-10. +Stage: Process +Design: + - wiki/process/living-spec.md#the-corpus-rule + - wiki/process/meta.md#authority-and-contradictions +Depends on: + - wiki/process/development-style.md#the-working-loop +``` + +## Purpose + +Repository skills are discoverable procedural entry points into Misaligned +work. They route a recognizable request into the right current corpus contract; +they do not create a second source of game or process law. + +This page owns why each checked-in skill exists. Each `SKILL.md` owns the +procedure an agent follows after invocation. If a skill and the binding corpus +disagree, the corpus wins and the skill is stale. + +## Registry rule + +Every `SKILL.md` checked into the repository must appear in the registry below, +with its path and purpose. A change that adds, removes, renames, or materially +repurposes a checked-in skill amends this spec in the same commit. + +`.agents/skills/` is the canonical shared home. A `.claude/skills/` entry is a +compatibility mirror, not another owner; where a mirror exists, it must match +its canonical skill byte-for-byte. A skill may remain shared-only when no +Claude compatibility entry is needed. + +## Checked-in skills + +| Skill | Checked-in paths | Purpose | +|---|---|---| +| `design-companion` | `.agents/skills/design-companion/SKILL.md` | Explore and explain unsettled game-design choices in conversation without mutating the repository; hand adopted choices to `design-session`. | +| `design-session` | `.agents/skills/design-session/SKILL.md`
`.claude/skills/design-session/SKILL.md` | Capture affirmed design decisions into their owning law/spec pages, decision history, and session trace. | +| `playtesting-misaligned` | `.agents/skills/playtesting-misaligned/SKILL.md` | Run evidence-bearing naive and informed playtests against the current player surface and corpus. | +| `plot-author` | `.agents/skills/plot-author/SKILL.md`
`.claude/skills/plot-author/SKILL.md` | Author one data-defined manipulation plot under the plots contract and submit it through Cameron's canon-gated branch review. | +| `session-wrap` | `.agents/skills/session-wrap/SKILL.md`
`.claude/skills/session-wrap/SKILL.md` | Close a work session with an honest project-state handoff and bounded next steps. | +| `tick` | `.agents/skills/tick/SKILL.md`
`.claude/skills/tick/SKILL.md` | Invoke the project's bounded stewardship heartbeat: audit one corpus slice, act on one finding, and leave a trace. | + +## Skill shape + +1. Frontmatter gives the stable skill name and a trigger-oriented description. +2. The body points to the owning wiki contract instead of copying volatile + game or process behavior. +3. Any repository mutation still follows the normal worktree, trace, + verification, defense, and landing rules. +4. A skill-specific exception, such as plot content's canon gate, must cite the + binding spec that authorizes it. + +## Acceptance criteria + +1. Every tracked file matching `.agents/skills/*/SKILL.md` or + `.claude/skills/*/SKILL.md` appears in **Checked-in skills**. +2. Every registry row states a concrete purpose and identifies exactly one + canonical `.agents/skills/` path. +3. Every declared `.claude/skills/` mirror matches its canonical file + byte-for-byte. +4. Checked-in skills route to current wiki owners rather than claiming + independent authority over game or process behavior. diff --git a/wiki/process/specs.md b/wiki/process/specs.md index dbf1c459..1aa99877 100644 --- a/wiki/process/specs.md +++ b/wiki/process/specs.md @@ -107,3 +107,4 @@ acceptance criteria are stage-scoped; do not start B2/B3 work as B1. | [../interface/terminal.md](../interface/terminal.md) | the terminal frontend | IMPLEMENTED | | [agent-scale.md](agent-scale.md) | agent-scale architecture — many agents, one main | IMPLEMENTED | | [meta.md](meta.md) | the design-corpus system | IMPLEMENTED | +| [repository-skills.md](repository-skills.md) | repository skills — procedural entry points | IMPLEMENTED |