From 974f5ea2c9e88f1c02500155a7e71558982d6619 Mon Sep 17 00:00:00 2001 From: Roone Date: Tue, 29 Sep 2026 12:22:33 -0600 Subject: [PATCH 1/2] Carry the scope skill in the repo, readable by Codex and Claude Code alike Co-Authored-By: Claude Opus 5.5 (1M context) --- .agents/skills/scope/SKILL.md | 74 +++++++++++++++++++++++++++++++++++ .claude/skills | 1 + .gitignore | 3 +- AGENTS.md | 1 + 4 files changed, 78 insertions(+), 1 deletion(-) create mode 100644 .agents/skills/scope/SKILL.md create mode 120000 .claude/skills diff --git a/.agents/skills/scope/SKILL.md b/.agents/skills/scope/SKILL.md new file mode 100644 index 0000000..2efd3b8 --- /dev/null +++ b/.agents/skills/scope/SKILL.md @@ -0,0 +1,74 @@ +--- +name: scope +description: Clarify a PR, a Horizon comment, or a loose idea into decisions and a PR description before any code. Use for "/scope 8", "/scope rlm", "let's scope", "think through", "grill me", "what are we building". +--- + +# scope + +Work is scoped before it is built. The output is decisions, written into the +record that carries them: a PR description, or a Horizon comment. No issues, +no prose spec; the skeleton commit that follows is the spec of custody. + +## Target + +Resolve the argument before the first question: + +- **A number** (`/scope 8`): that PR. If it is the Horizon PR, the words + after the number name a comment (`/scope 7 rlm`). +- **Words** (`/scope rlm`): the Horizon comment whose title matches them, + loosely. Two matches: ask which. +- **Nothing, or a loose idea**: no target yet. Check Horizon for a comment + that already covers it before making a new one. + +The Horizon PR is the repo's parking lot: never merged, one comment per +future PR in the description template. The repo's AGENTS.md names its +number; otherwise it is the open draft titled "Horizon". + +## Read first + +Read the target in full (PR description and comments, or the Horizon +comment), then the repo's AGENTS.md and CODE.md. Questions start from what +is already written; anything the conversation settles differently from the +text gets named. + +## Rounds + +Scoping is a conversation, not a step toward automation. The questions are +where what cannot be stabilized becomes visible; asking beats assuming, and +each question gives its context from first principles. + +1. Name the destination first: what done looks like, in one or two lines. + It fixes scope; every question serves it. +2. Work in rounds. A round is every question askable now without guessing + at an unheard answer. Number each, give one recommended answer, wait. +3. Facts are yours to fetch; decisions are the user's. Look it up before + asking. Never answer your own question. +4. Where's best, not least disruptive. When a proposal conflicts with what's + on disk or in the record, say so and say which should win. Conversation + outranks disk. +5. Nouns go into CODE.md's vocabulary as they settle, one line each. Call + out a noun the moment its meaning drifts. +6. Stop when the frontier is empty. + +## Write back + +Restate what settled, then write it into the target in the repo's +description template: **What this PR does**, **What this PR does not do**, +**Merge requirements**. + +- **A PR**: rewrite its description. +- **A Horizon comment**: edit it in place. If it is ready to build, say so; + on the user's go, open its PR (branch, worktree, first commit, draft) with + the comment as its description, then delete the comment. +- **No target**: a new Horizon comment, or a new draft PR if the user says + it is next. + +Scoping ends at a clarified description. Stubs and code are the next step. + +Question format: + +``` +❓ **Q1** - **title**: body, with choices if there are any + +➡️ recommended answer +``` diff --git a/.claude/skills b/.claude/skills new file mode 120000 index 0000000..2b7a412 --- /dev/null +++ b/.claude/skills @@ -0,0 +1 @@ +../.agents/skills \ No newline at end of file diff --git a/.gitignore b/.gitignore index 8106cf5..2b78652 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,4 @@ .DS_Store target/ -.claude/ +.claude/* +!.claude/skills diff --git a/AGENTS.md b/AGENTS.md index 0223ea3..d2ab609 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,6 +4,7 @@ Public artifacts — commits, code, docs, descriptions — carry "Roone" only, n # CONTEXT Read these root-level files: `README.md` (what this is), `CODE.md` (method, vocabulary, languages). +Skills live in `.agents/skills/` (Codex); `.claude/skills` links there (Claude Code), as `CLAUDE.md` links to this file. Every time you create or discover a new AGENTS.md, paste its path here: # COMMUNICATION From 23ffdbc8eaf8bc64b5cf398c09b1cbf873eadb7c Mon Sep 17 00:00:00 2001 From: Roone Date: Tue, 29 Sep 2026 12:26:01 -0600 Subject: [PATCH 2/2] Make the repo's skill cead's own: slice, the method's first step Co-Authored-By: Claude Opus 5.5 (1M context) --- .agents/skills/scope/SKILL.md | 74 -------------------------------- .agents/skills/slice/SKILL.md | 79 +++++++++++++++++++++++++++++++++++ 2 files changed, 79 insertions(+), 74 deletions(-) delete mode 100644 .agents/skills/scope/SKILL.md create mode 100644 .agents/skills/slice/SKILL.md diff --git a/.agents/skills/scope/SKILL.md b/.agents/skills/scope/SKILL.md deleted file mode 100644 index 2efd3b8..0000000 --- a/.agents/skills/scope/SKILL.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -name: scope -description: Clarify a PR, a Horizon comment, or a loose idea into decisions and a PR description before any code. Use for "/scope 8", "/scope rlm", "let's scope", "think through", "grill me", "what are we building". ---- - -# scope - -Work is scoped before it is built. The output is decisions, written into the -record that carries them: a PR description, or a Horizon comment. No issues, -no prose spec; the skeleton commit that follows is the spec of custody. - -## Target - -Resolve the argument before the first question: - -- **A number** (`/scope 8`): that PR. If it is the Horizon PR, the words - after the number name a comment (`/scope 7 rlm`). -- **Words** (`/scope rlm`): the Horizon comment whose title matches them, - loosely. Two matches: ask which. -- **Nothing, or a loose idea**: no target yet. Check Horizon for a comment - that already covers it before making a new one. - -The Horizon PR is the repo's parking lot: never merged, one comment per -future PR in the description template. The repo's AGENTS.md names its -number; otherwise it is the open draft titled "Horizon". - -## Read first - -Read the target in full (PR description and comments, or the Horizon -comment), then the repo's AGENTS.md and CODE.md. Questions start from what -is already written; anything the conversation settles differently from the -text gets named. - -## Rounds - -Scoping is a conversation, not a step toward automation. The questions are -where what cannot be stabilized becomes visible; asking beats assuming, and -each question gives its context from first principles. - -1. Name the destination first: what done looks like, in one or two lines. - It fixes scope; every question serves it. -2. Work in rounds. A round is every question askable now without guessing - at an unheard answer. Number each, give one recommended answer, wait. -3. Facts are yours to fetch; decisions are the user's. Look it up before - asking. Never answer your own question. -4. Where's best, not least disruptive. When a proposal conflicts with what's - on disk or in the record, say so and say which should win. Conversation - outranks disk. -5. Nouns go into CODE.md's vocabulary as they settle, one line each. Call - out a noun the moment its meaning drifts. -6. Stop when the frontier is empty. - -## Write back - -Restate what settled, then write it into the target in the repo's -description template: **What this PR does**, **What this PR does not do**, -**Merge requirements**. - -- **A PR**: rewrite its description. -- **A Horizon comment**: edit it in place. If it is ready to build, say so; - on the user's go, open its PR (branch, worktree, first commit, draft) with - the comment as its description, then delete the comment. -- **No target**: a new Horizon comment, or a new draft PR if the user says - it is next. - -Scoping ends at a clarified description. Stubs and code are the next step. - -Question format: - -``` -❓ **Q1** - **title**: body, with choices if there are any - -➡️ recommended answer -``` diff --git a/.agents/skills/slice/SKILL.md b/.agents/skills/slice/SKILL.md new file mode 100644 index 0000000..6f3d0de --- /dev/null +++ b/.agents/skills/slice/SKILL.md @@ -0,0 +1,79 @@ +--- +name: slice +description: Scope a cead PR or Horizon comment into its slice of the spec and a PR description, before any spec, Lean or Rust. Use for "/slice 13", "/slice agent", "scope this PR", "what's this PR's slice". +--- + +# slice + +A cead PR takes a slice of the spec (CODE.md, Method). This skill settles +that slice: decisions written into the PR description, before the spec +commit, the Lean, the skeleton or any code. + +Slicing is a conversation, not a step toward automation. The questions are +where what cannot be stabilized becomes visible; asking beats assuming, and +each question gives its context from first principles. + +## Target + +- **A number** (`/slice 13`): that PR. `/slice 7 WORDS`: the Horizon comment + whose title matches. +- **Words** (`/slice agent`): the Horizon comment whose title matches them, + loosely. Two matches: ask which. +- **Nothing**: ask what the work is; check Horizon (#7) for a comment that + covers it before making a new one. + +## Read first + +The target in full (description and comments), AGENTS.md, CODE.md, and the +parts of `spec/cead.tla` and `spec/Cead/` the target touches. Questions +start from what is written; anything the conversation settles differently +gets named. + +## Rounds + +1. Name the destination in one or two lines, and the slice: the spec's + actions and properties this PR makes real. +2. Work in rounds. A round is every question askable now without guessing + at an unheard answer. Number each, give one recommendation, frame it as + a commitment ("approving this means..."), wait. +3. Facts are yours to fetch; decisions are Roone's. Look it up before asking. +4. Every round covers what applies: + - **Spec:** does the slice change what `spec/cead.tla` says? Then that + change is the PR's first commit. The spec is never looser than the + system. + - **Lean:** which pure functions must a skeptic trust (what signs, + verifies, admits or renders)? Each gets a Lean spec and a + differential test. + - **Shape:** modules, types and custody, agreed before the skeleton. + - **Nouns:** each settles into CODE.md's table with its type's home. + Terms come from OSTEP or object-capability security; flag a noun the + moment it drifts. + - **Thesis:** does the design keep context offloaded to state and + sub-calls programmatic, every model call locally in distribution? + - **Dependencies:** one crate at a time, standard and mainline only. + - **Structure:** crates, binaries, files only when a requirement + demands them. +5. Where's best, not least disruptive. When a proposal conflicts with the + record, say which should win. Conversation outranks disk; evidence + outranks both. +6. Stop when the frontier is empty. + +## Write back + +Restate what settled, then write it into the target: a `Spec:` line naming +the slice, then **What this PR does**, **What this PR does not do**, +**Merge requirements**. + +- **A PR**: rewrite its description. +- **A Horizon comment**: edit it in place. On Roone's go, open its PR + (branch named for the change, worktree, first commit, draft) with the + comment as its description, then delete the comment. + +Slicing ends at a clarified description. The spec commit, Lean, skeleton and +fill follow, each shown before it is built. + +``` +❓ **Q1** - **title**: body, with choices if there are any + +➡️ recommended answer +```