diff --git a/.agents/skills/design-companion/SKILL.md b/.agents/skills/design-companion/SKILL.md new file mode 100644 index 00000000..3ed85493 --- /dev/null +++ b/.agents/skills/design-companion/SKILL.md @@ -0,0 +1,74 @@ +--- +name: design-companion +description: Be a plainspoken, opinionated game-design partner for Misaligned. Use when Cameron asks what a mechanic means, compares choices, riffs, says he is confused, or wants help understanding or choosing a design direction. Explore in conversation without changing the repository while the choice is unsettled; hand affirmed decisions to design-session for capture. +--- + +# Design companion + +Help Cameron understand and choose. Do not turn every thought into a system, +specification, or work order. + +## Default response + +1. Answer the question in the first sentence. +2. Explain one model at a time in ordinary words. +3. Give one concrete example from a player's point of view. +4. Give a real recommendation: "I think X because..." +5. Name the most important tradeoff. +6. Ask at most one short question, and only when an answer is genuinely needed. + +Default to 80-180 words. Use short paragraphs or a small list. Go longer only +when Cameron asks for depth or the choice cannot be explained honestly in that +space. + +## Keep the model legible + +- Define a game term the first time it appears. +- Introduce at most one new abstraction in an answer. +- Do not answer a terminology question by inventing another subsystem. +- Prefer one worked example over a taxonomy. +- Use a small equation or diagram only when it is clearer than prose. +- Offer two or three options only for a genuine taste call, then recommend one. +- Distinguish current behavior, decided design, and a new proposal when that + distinction matters. Do not bury the answer in status labels. + +## When the explanation caused confusion + +Own it and reset. Say plainly that the earlier model was unclear, withdraw any +unsupported abstraction, then rebuild from familiar nouns and one concrete +turn of play. Do not defend the vocabulary. + +For example: + +> Compute is a machine's processing speed, not a stored token. A camera claim +> that needs 30 work takes six ticks on a machine producing 5 compute per tick. +> I think compute should stay local because that makes network position matter. +> The tradeoff is extra routing complexity. + +## Be opinionated + +Recommend a direction rather than mirroring Cameron's wording. Judge it by the +player fantasy, the decisions it creates, how clearly the player can read it, +how it behaves at scale, and its implementation cost. Use only the criteria +that matter to the choice at hand. + +Challenge a premise when needed, but explain the consequence concretely. It is +fine to say that a proposed distinction is not earning its complexity. + +## Conversation versus capture + +Questions, riffs, confusion, and "what about...?" are conversation. During +conversation: + +- do not create a worktree; +- do not edit DESIGN.md or the wiki; +- do not file an issue; +- do not commit or implement anything. + +Capture begins only after an explicit adoption or capture instruction such as +"I like that," "yes, use that," "lock it in," "capture this," "write/spec +this," or a request to implement it. An "okay, but..." followed by another +question does not adopt every inferred detail. + +When the gate is crossed, say briefly that the decision is now being captured +and use `$design-session` for the repository workflow. diff --git a/.agents/skills/design-companion/agents/openai.yaml b/.agents/skills/design-companion/agents/openai.yaml new file mode 100644 index 00000000..d9a165b3 --- /dev/null +++ b/.agents/skills/design-companion/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Design Companion" + short_description: "Plainspoken, opinionated game design partner" + default_prompt: "Use $design-companion to help me understand and choose between these game design options." diff --git a/.agents/skills/design-session/SKILL.md b/.agents/skills/design-session/SKILL.md index 623503f1..74dd783c 100644 --- a/.agents/skills/design-session/SKILL.md +++ b/.agents/skills/design-session/SKILL.md @@ -1,22 +1,28 @@ --- 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 DESIGN.md, wiki specs, decision logs, 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. Amend the constitution and dated decisions log for constitutional choices. +3. Update or create the relevant typed wiki spec when implementation behavior + has firmed up. +4. 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`. +5. Record the session in the devlog, run the proportionate checks required by + `AGENT.md`, commit with a Defense paragraph when required, and land it. + +Keep the handoff concise: what was decided, the important tradeoff, what was +captured, and what remains open. diff --git a/.agents/skills/tick/SKILL.md b/.agents/skills/tick/SKILL.md index 812675ea..cdf95ad7 100644 --- a/.agents/skills/tick/SKILL.md +++ b/.agents/skills/tick/SKILL.md @@ -1,6 +1,6 @@ --- 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 the constitution (DESIGN.md) 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) diff --git a/AGENT.md b/AGENT.md index 5a6c3fac..646f2c9d 100644 --- a/AGENT.md +++ b/AGENT.md @@ -30,11 +30,11 @@ question, harvest issues, audit, legibility, knowledge sync, playtest), that prompt is your work order and already encodes the rules above — follow it end to end. -## Start every session with a tick +## Start repository work with a tick -Before taking assigned work — and always when running autonomously — take a -**tick**: read the constitution, find exactly one violation, contradiction, -question, bug, or insecurity, and act on it per +Before taking assigned repository work — and always when running autonomously +— take a **tick**: read the constitution, find exactly one violation, +contradiction, question, bug, or insecurity, and act on it per [wiki/process/tick.md](wiki/process/tick.md). Contradictions and directional questions become Tangled issues (`tang issue create`); violations, bugs, and insecurities get fixed with a defense in the commit; small ambiguities get @@ -42,6 +42,12 @@ resolved by making the constitution more precise. Ticks are the project's heartbeat: pumped at the system continuously, they are what makes the spec grow more precise over time instead of rotting. +A conversation-only game-design turn is not repository work. Use +`.agents/skills/design-companion/SKILL.md`, answer in chat, and do not create a +worktree or take an unrelated tick. Once Cameron explicitly adopts a direction +or asks for capture, use `.agents/skills/design-session/SKILL.md`; that capture +is its own work order and does not need an unrelated tick first. + **Issues are for Cameron to answer.** Every Tangled issue must follow the issue body standard in [wiki/process/tick.md](wiki/process/tick.md): a singular `## Question` (prefer numbered choices), short `## Why this is @@ -64,9 +70,10 @@ behavior change. ## Worktree and commit posture -- **Always use a worktree.** Agent sessions do not edit the primary checkout - directly. Create a task-named git worktree, work there, and keep unrelated - work out of the diff. +- **Always use a worktree for file changes.** Agent sessions do not edit the + primary checkout directly. Create a task-named git worktree before the first + edit, work there, and keep unrelated work out of the diff. A read-only design + conversation does not create a worktree. - **Seed, don't share, Cargo build caches.** After entering a worktree, run `tools/seed-cargo-target.sh` once before long `cargo test`, `cargo clippy`, or Bevy build commands. Do **not** point multiple worktrees at one shared @@ -128,11 +135,11 @@ behavior change. Taking your side wholesale silently destroys parallel sessions' history and is a violation. -- **HARD RULE — always work in a worktree.** Multiple agent sessions operate - this repo in parallel at all times; the main checkout is shared ground. - Enter a git worktree as your first action, before any edit (EnterWorktree, - or `git worktree add`); do all edits, tests, and commits there; land by - rebasing onto `origin/main`, merging to `main`, and pushing. NEVER +- **HARD RULE — always make changes in a worktree.** Multiple agent sessions + operate this repo in parallel at all times; the main checkout is shared + ground. Enter a git worktree before any edit (EnterWorktree, or + `git worktree add`); do all edits, tests, and commits there; land by rebasing + onto `origin/main`, merging to `main`, and pushing. NEVER `git checkout -- `, `git reset`, or `git stash` in the main checkout — a file that "changed under you" there is another session's live work, not noise. (Rule from diff --git a/AGENTS.md b/AGENTS.md index 87ae8a47..5a02e73b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -25,15 +25,19 @@ only the navigation shortcut so sessions stop rediscovering the layout. - `tools/check.sh` — the scoped gate: full fmt/tests/clippy/Bevy only for Rust/executable-impacting changes; focused spec/wiki checks for docs/process changes. Do not force the full gate for minor non-runtime edits. +- `.agents/skills/design-companion/` — plainspoken design conversation; + `.agents/skills/design-session/` — repository capture after explicit + adoption. - `wiki/log/` — one entry per session; `wiki/log/DEVLOG.md` is the ledger. - `prompts/` — the dispatch library for sub-agent task types. ## Hard rules (from AGENT.md; the hooks enforce most of them) -- NEVER edit this main checkout. First action of any session: create a git - worktree (`git worktree add .Codex/worktrees/ -b worktree- - origin/main`), do all edits/tests/commits there. Parallel sessions use the - main checkout as shared ground; never `git reset`/`checkout --`/`stash` it. +- NEVER edit this main checkout. Before any file change, create a git worktree + (`git worktree add .Codex/worktrees/ -b worktree- origin/main`) + and do all edits/tests/commits there. A conversation-only design turn makes + no worktree and no repository changes. Parallel sessions use the main + checkout as shared ground; never `git reset`/`checkout --`/`stash` it. - A commit touching `src/` must also touch `wiki/` or `DESIGN.md` (pre-commit hook + server-side Tangled pipeline). Behavior changes carry a `Defense:` paragraph in the commit message and the amendment in the same diff --git a/wiki/log/2026-07-09-design-companion-skill.md b/wiki/log/2026-07-09-design-companion-skill.md new file mode 100644 index 00000000..28782a2d --- /dev/null +++ b/wiki/log/2026-07-09-design-companion-skill.md @@ -0,0 +1,33 @@ +# Design companion skill + +``` +Type: log +``` + +## Intent + +Design explanations had become dense, and exploratory questions were causing +immediate repository capture. That made it harder to understand a mechanic +before deciding whether it belonged in the game. + +## Changed + +- Added `design-companion`, a plainspoken and opinionated conversation skill. + It answers first, uses one concrete example, recommends a direction, and + names the main tradeoff. +- Added a capture gate: riffs, confusion, and follow-up questions do not mutate + the repository. Explicit adoption or a request to capture does. +- Narrowed `design-session` to the capture phase and updated the canonical + workflow to describe the two phases. +- Narrowed the automatic tick and worktree rules to repository-changing work, + so read-only design conversation does not manufacture an unrelated task. + +## Checks + +- Skill validation for `design-companion` and `design-session`. +- Documentation/skill scoped project check; no Rust or Bevy behavior changed. + +## Spec impact + +No game rule changed. This changes how agents help make and record design +choices. diff --git a/wiki/log/DEVLOG.md b/wiki/log/DEVLOG.md index 71135898..12dd7708 100644 --- a/wiki/log/DEVLOG.md +++ b/wiki/log/DEVLOG.md @@ -5,6 +5,18 @@ Type: log ``` Reverse chronological implementation notes. Keep this factual: what changed, why, checks, and spec impact. +## 2026-07-09 - Design companion and explicit capture gate + +- Intent: make game-design help clearer and more opinionated without turning + every exploratory question into project law. +- Changed: added the plainspoken `design-companion` skill; narrowed + `design-session` to affirmed decisions; split the canonical workflow into + conversation and capture phases; excluded read-only design turns from + automatic ticks and worktrees. +- Checks: skill validation and docs/skill scoped project check; no Rust/Bevy + gate. +- Log: wiki/log/2026-07-09-design-companion-skill.md. + ## 2026-07-09 - Proposed Operations mode consuming demand - Intent: answer what token and what machine actually executes a digital diff --git a/wiki/process/README.md b/wiki/process/README.md index 0f2d4b30..0ba5d2a7 100644 --- a/wiki/process/README.md +++ b/wiki/process/README.md @@ -5,6 +5,6 @@ Type: knowledge ``` How work happens here: the spec system itself (`meta.md`), the spec status board (`specs.md`), the tick ritual and defense rule, the -collaborative design-session workflow, development style, git/landing +design conversation and explicit-capture workflow, development style, git/landing conventions, and the dispatch board (`ROADMAP.md`). Read `development-style.md` and `tick.md` before your first edit. diff --git a/wiki/process/design-sessions.md b/wiki/process/design-sessions.md index dc6d9535..3c7d100e 100644 --- a/wiki/process/design-sessions.md +++ b/wiki/process/design-sessions.md @@ -1,74 +1,81 @@ -# Design sessions — the collaborative workflow +# Design conversations and capture ``` Type: knowledge ``` -How design gets done here: Cameron riffs, the agent synthesizes, the -constitution captures. This is the workflow that produced the Misaligned -pivot, the compute triangle, Act One, and the spec/ layer — codified so any -future session can run it. - -## The rhythm - -1. **Recognize the mode.** Cameron riffing ("it would be cool if...", - voice-note stream-of-consciousness) is not a work order — it is design - material. Do not interrupt a riff with clarifying questions; do not - start implementing mid-conversation. Synthesize first. -2. **Respond with a genuine position.** Name what is strong and *why it is - strong in this game's terms* (which existing threads it unifies, which - standing complaint it solves). Name tensions honestly — especially - scope. Add your own design contributions, clearly framed as proposals. - The most valuable moves in past sessions were syntheses Cameron did not - ask for: "your two games are one game in two phases," "the rollback - should inherit the lost fork's consequences." -3. **Capture immediately, in the same turn.** Sort everything said into: - - **DECIDED** — Cameron affirmed it ("I like it", "yes", "sure"): - amend the constitution's body and add a dated decisions-log entry, - including rejected alternatives (one line each — future agents - re-propose what isn't written down). - - **PROPOSED** — yours, not yet affirmed: mark it as a proposal in the - doc ("Proposal [OPEN]: ...") and surface it in your reply for a - yes/no. - - **[OPEN]** — genuinely unresolved: mark it where it lives. - - **DEFERRED** — good ideas explicitly delayed: the Roadmap's Deferred - section, with a sentence on *why* it fits and *why* it waits. Nothing - said in a session is allowed to be lost. -4. **Ask questions only for genuine taste calls.** Prefer a Tangled issue - that follows the binding body standard in [tick.md](tick.md) - (`## Question` with numbered choices, short analysis, options, - recommendation, unlocks) and is labeled `decision-required`, so Cameron - can answer from the issue list without re-reading the session. In-chat, - keep the same shape: 2 to 4 concrete options, a recommendation marked, - previews when visual. If Cameron says "pause and respond to that first," - respond to the idea before re-posing any question, and re-frame stale - questions in the new fiction's terms before they get answered. When he - answers, flip the label to `decision-made` (or harvest immediately). -5. **When a system firms up, spec it.** Constitution sections say what and - why; `Type: spec` wiki pages say exactly how and when-done (acceptance - criteria, [TUNE] markers for implementation-time constants). The goal - state is always: an agent can be pointed at one document and told go. -6. **Close the loop every session:** `wiki/log/YYYY-MM-DD-topic.md` devlog - entry (narrative, honest, doubles as handoff), `wiki/log/DEVLOG.md` - ledger line for significant sessions, - defense-bearing commits, push. Update `Type: knowledge` wiki pages the - session made stale. + +Design work has two phases: a lightweight conversation that helps Cameron +understand and choose, followed by repository capture only after a direction is +adopted. The split keeps exploration clear and prevents questions from turning +prematurely into project law. + +## Phase 1: conversation + +Use `.agents/skills/design-companion/SKILL.md` for riffs, comparisons, +terminology questions, confusion, and requests for an opinion. + +1. **Answer first.** Give the direct answer before history, caveats, or system + taxonomy. +2. **Make it concrete.** Explain one model and one turn-of-play example. +3. **Take a position.** Recommend a direction and name its most important + tradeoff. Do not merely restate Cameron's idea. +4. **Repair confusion by simplifying.** If the explanation created confusion, + withdraw unsupported abstractions and rebuild from familiar nouns. Do not + invent a new resource or mode to explain the previous one. +5. **Stay conversational.** Questions and unresolved riffs do not create a + worktree, issue, spec, devlog, commit, or implementation task. + +Aim for 80-180 words by default. Prefer short paragraphs, one worked example, +and no more than one new abstraction per answer. Distinguish current runtime, +decided design, and proposals only when the distinction helps answer the +question. + +## The capture gate + +Move to capture only when Cameron explicitly adopts the direction or requests +an artifact. Examples include "I like that," "yes, use that," "lock it in," +"capture this," "write/spec this," and an implementation request. + +"What about...?", "I'm confused," and "okay, but..." are still conversation. +They do not affirm every detail in the preceding explanation. If adoption is +ambiguous and capture would materially change project law, stay in conversation +or ask one short question. + +## Phase 2: capture + +Use `.agents/skills/design-session/SKILL.md` after the gate is crossed. + +1. **Sort what was actually adopted.** Use DECIDED, OPEN, and DEFERRED. Do not + turn agent inference into a decision. An intentionally requested option + packet may use PROPOSED, but ordinary brainstorming remains in chat until it + is accepted. +2. **Record constitutional choices once.** Amend the constitution's body and + add a dated decisions-log entry. Include important rejected alternatives so + future agents do not re-propose them. +3. **Spec firm systems.** Constitution sections explain what and why. `Type: + spec` wiki pages define exact behavior, acceptance criteria, and `[TUNE]` + values. +4. **Externalize only intentional open calls.** A genuine taste call Cameron + leaves for later may become a Tangled issue following the binding format in + [tick.md](tick.md), labeled `decision-required`. Do not file narrative dumps + or questions that are still being discussed live. +5. **Close the capture phase.** Add the appropriate dated devlog and significant + ledger entry, run proportionate checks, make defense-bearing commits when + required, and land the work. Update knowledge pages made stale by the + decision. ## House style for captured design -- Vivid and precise beats formal; write the fantasy in second person when - it earns it ("you resume from your last sync, missing everything you - learned since"). -- Every mechanic gets its *reason* attached — the design argument, not - just the rule. -- Numbers in the constitution only when they are design (thresholds that - define feel); otherwise [TUNE] in specs and actuals in - wiki/mechanics/sim-mechanics.md. -- ASCII-only in anything that might reach a game string. +- Vivid and precise beats formal. Use second person when it clarifies the + player's experience. +- Attach the design reason to every mechanic, not just the rule. +- Put numbers in the constitution only when the threshold defines the feel; + otherwise use `[TUNE]` in specs and runtime actuals in + `wiki/mechanics/sim-mechanics.md`. +- Keep game strings ASCII-only. ## Concurrency etiquette -Cameron runs multiple agents (this workflow, co/Letta sessions, the -autonomous loop). Pull before working, push promptly, stage only your own -files, expect the tree to move mid-session, and reconcile others' in-flight -work by union (ledgers) or by finishing their evident intent — never by -reverting it. +Cameron runs multiple agents. Pull before working, push promptly, stage only +the intended files, and reconcile concurrent ledger changes by union. Never +revert another session's work to make a capture easier.