From f9d0ba9f63a648a0a6652a222d5693e3cbb521db Mon Sep 17 00:00:00 2001 From: SJ Lee Date: Sun, 24 May 2026 20:30:58 +0900 Subject: [PATCH 1/3] Clarify backlog-charter execution contract Fixes #148 --- skills/backlog-charter/SKILL.md | 34 ++++++++++++++++++++++++++++++--- 1 file changed, 31 insertions(+), 3 deletions(-) diff --git a/skills/backlog-charter/SKILL.md b/skills/backlog-charter/SKILL.md index ac877ae..7e10d9c 100644 --- a/skills/backlog-charter/SKILL.md +++ b/skills/backlog-charter/SKILL.md @@ -9,7 +9,35 @@ metadata: # Backlog Charter -Create and amend `CHARTER.md`, the opt-in project reference axis used to measure backlog work, sprint plans, and drift. This skill is rerunnable. Explicit modes win first (`create`, `amend`, `grill`, `reassess`); file-state routing applies only when no mode is specified: no repo-root `CHARTER.md` means create mode, and an existing repo-root `CHARTER.md` means amend mode. +Create and amend `CHARTER.md`, the opt-in project reference axis used to measure backlog work, sprint plans, and drift. This skill is rerunnable. + +## Execution Contract + +### Mode Router + +Explicit modes win first: + +| User intent | Mode | Boundary | +|-------------|------|----------| +| Create the project axis, baseline, charter, or first spec foundation | `create` | Only when repo-root `CHARTER.md` is absent, unless the user explicitly asks to replace it. | +| Update direction, objectives, decisions, or accepted charter wording | `amend` | Applies tier gates and may edit `CHARTER.md` after confirmation. | +| Create or refine `spec/capabilities.md`, capability contracts, Behaviors, or Hard Constraints | `grill` | Edits only the requested capability on rerun. | +| Check whether charter/capabilities/Learnings are stale or should change | `reassess` | Report-only; routes accepted fixes to amend, grill, or a Learning Action. | + +When no mode is specified, route by file state: no repo-root `CHARTER.md` means create mode, and an existing repo-root `CHARTER.md` means amend mode. If the request mixes diagnosis and edits, run `reassess` first unless the user explicitly asks to apply a known change. If the request could affect both `CHARTER.md` and `spec/capabilities.md`, ask one bounded routing question before editing. + +### Helper Scripts + +Resolve helper scripts from the installed `backlog-charter` skill directory, not from the target repo. In a source checkout, that means the local `scripts/` directory beside this `SKILL.md`; in an installed skill, first locate the skill directory and run the same script from there. If a helper is unavailable, report **Missing Evidence** and continue with bounded file reads. + +### Completion Contract + +End every mode with a short summary: + +- `create`: created files, unresolved assumptions, and the first suggested `grill` or `amend` follow-up. +- `amend`: accepted changes, refused/parked changes, proof cited for status advances, and size-check result. +- `grill`: capability blocks created or edited, predicates rejected or rewritten, constraints added, and follow-up Learning Actions if any. +- `reassess`: required report sections from the Reassess Mode dispatch contract, with one recommended next step. ## What CHARTER.md Is @@ -64,7 +92,7 @@ Apply the 3-tier discipline: - Tier 2 status advance: require proof for `active` → `validated` or `deferred`; cite a merged PR, passing check, or relay run whose Done Criteria match the predicate. Without proof, refuse the advance and flag it. - Tier 3 Decisions: append only. Never edit or delete an existing row; a reversal is a new row with `supersedes`. -After applying an accepted amendment, bump `last_amended` to today and increment `revision`. Then run `node skills/backlog-charter/scripts/check-size.js` to confirm the 5-minute-read property still holds; collapse long `deferred` lists or oversized Decisions rationale if the script warns. +After applying an accepted amendment, bump `last_amended` to today and increment `revision`. Then run `check-size.js` from the installed skill's `scripts/` directory to confirm the 5-minute-read property still holds; collapse long `deferred` lists or oversized Decisions rationale if the script warns. Amend mode can take a `backlog-triage` Alignment Check report as a seed of proposed changes. The report proposes; this skill applies through the gates. @@ -74,7 +102,7 @@ See `references/amendment.md` for deep challenge and proof-gate heuristics. Use grill mode to author `spec/capabilities.md`, the middle layer between `CHARTER.md` and the active sprint. Invoked as `backlog-charter grill` (greenfield: no `spec/capabilities.md` yet) or `backlog-charter grill ` (rerun: polish one capability without touching others). Capability slugs are strict routing handles used by sprint `component:` frontmatter; keep them lowercase and singular, then put nuance in Goal/Scope prose. -**On a brownfield repo** (existing code, no `spec/capabilities.md`), run `node skills/backlog-charter/scripts/extract-signals.js --json` first. It draws from README, CLAUDE.md/AGENTS.md, top-level source dirs, the last 100 commit messages, and `CHARTER.md` Objectives, and reports raw capability signals with draft Goal + draft Scope. Use the draft as interview seed only; grill mode still pressure-tests every admitted capability through the admission test and then pressure-tests every Behavior and Hard Constraint through the 3-axis test before commit. The script clusters by code organization (directory names, commit scopes), while real capabilities are functional contracts; expect grill mode to merge, split, or regroup raw signals rather than adopt them verbatim. The script never writes `spec/capabilities.md` itself — that decision belongs to grill. +**On a brownfield repo** (existing code, no `spec/capabilities.md`), run `extract-signals.js --json` from the installed skill's `scripts/` directory first. It draws from README, CLAUDE.md/AGENTS.md, top-level source dirs, the last 100 commit messages, and `CHARTER.md` Objectives, and reports raw capability signals with draft Goal + draft Scope. Use the draft as interview seed only; grill mode still pressure-tests every admitted capability through the admission test and then pressure-tests every Behavior and Hard Constraint through the 3-axis test before commit. The script clusters by code organization (directory names, commit scopes), while real capabilities are functional contracts; expect grill mode to merge, split, or regroup raw signals rather than adopt them verbatim. The script never writes `spec/capabilities.md` itself — that decision belongs to grill. `spec/capabilities.md` lives at the target repo root in `spec/`. Layout, mutation rules, and rationale are in [`docs/spec-system-design.md`](../../docs/spec-system-design.md). The single-file shape is intentional while the spec remains compact: target 5-10 capabilities, warn above 12 capabilities or 400 lines, and split only above 500 lines, above 15 capabilities, or when ownership boundaries demand separate review paths. From cd22e9be236b8a15b56ff9341ba0961348c47e14 Mon Sep 17 00:00:00 2001 From: SJ Lee Date: Sun, 24 May 2026 20:34:26 +0900 Subject: [PATCH 2/3] Clarify backlog-charter intent fallback --- skills/backlog-charter/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/backlog-charter/SKILL.md b/skills/backlog-charter/SKILL.md index 7e10d9c..f86027a 100644 --- a/skills/backlog-charter/SKILL.md +++ b/skills/backlog-charter/SKILL.md @@ -24,7 +24,7 @@ Explicit modes win first: | Create or refine `spec/capabilities.md`, capability contracts, Behaviors, or Hard Constraints | `grill` | Edits only the requested capability on rerun. | | Check whether charter/capabilities/Learnings are stale or should change | `reassess` | Report-only; routes accepted fixes to amend, grill, or a Learning Action. | -When no mode is specified, route by file state: no repo-root `CHARTER.md` means create mode, and an existing repo-root `CHARTER.md` means amend mode. If the request mixes diagnosis and edits, run `reassess` first unless the user explicitly asks to apply a known change. If the request could affect both `CHARTER.md` and `spec/capabilities.md`, ask one bounded routing question before editing. +When no mode is specified, route by intent first, then use file state only for generic charter requests: no repo-root `CHARTER.md` means create mode, and an existing repo-root `CHARTER.md` means amend mode. If the request mixes diagnosis and edits, run `reassess` first unless the user explicitly asks to apply a known change. If the request could affect both `CHARTER.md` and `spec/capabilities.md`, ask one bounded routing question before editing. ### Helper Scripts From 2ec450eafa768477d7af345f82cafc5280abdda2 Mon Sep 17 00:00:00 2001 From: SJ Lee Date: Sun, 24 May 2026 20:36:57 +0900 Subject: [PATCH 3/3] Pass target paths to backlog-charter helpers --- skills/backlog-charter/SKILL.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/skills/backlog-charter/SKILL.md b/skills/backlog-charter/SKILL.md index f86027a..580876f 100644 --- a/skills/backlog-charter/SKILL.md +++ b/skills/backlog-charter/SKILL.md @@ -28,7 +28,7 @@ When no mode is specified, route by intent first, then use file state only for g ### Helper Scripts -Resolve helper scripts from the installed `backlog-charter` skill directory, not from the target repo. In a source checkout, that means the local `scripts/` directory beside this `SKILL.md`; in an installed skill, first locate the skill directory and run the same script from there. If a helper is unavailable, report **Missing Evidence** and continue with bounded file reads. +Resolve helper scripts from the installed `backlog-charter` skill directory, not from the target repo. In a source checkout, that means the local `scripts/` directory beside this `SKILL.md`; in an installed skill, first locate the skill directory and run the same script from there. Always pass the target repo explicitly (`--path /CHARTER.md` or `--repo-root `) so helpers do not inspect the skill directory by accident. If a helper is unavailable, report **Missing Evidence** and continue with bounded file reads. ### Completion Contract @@ -92,7 +92,7 @@ Apply the 3-tier discipline: - Tier 2 status advance: require proof for `active` → `validated` or `deferred`; cite a merged PR, passing check, or relay run whose Done Criteria match the predicate. Without proof, refuse the advance and flag it. - Tier 3 Decisions: append only. Never edit or delete an existing row; a reversal is a new row with `supersedes`. -After applying an accepted amendment, bump `last_amended` to today and increment `revision`. Then run `check-size.js` from the installed skill's `scripts/` directory to confirm the 5-minute-read property still holds; collapse long `deferred` lists or oversized Decisions rationale if the script warns. +After applying an accepted amendment, bump `last_amended` to today and increment `revision`. Then run `check-size.js --path /CHARTER.md` from the installed skill's `scripts/` directory to confirm the 5-minute-read property still holds; collapse long `deferred` lists or oversized Decisions rationale if the script warns. Amend mode can take a `backlog-triage` Alignment Check report as a seed of proposed changes. The report proposes; this skill applies through the gates. @@ -102,7 +102,7 @@ See `references/amendment.md` for deep challenge and proof-gate heuristics. Use grill mode to author `spec/capabilities.md`, the middle layer between `CHARTER.md` and the active sprint. Invoked as `backlog-charter grill` (greenfield: no `spec/capabilities.md` yet) or `backlog-charter grill ` (rerun: polish one capability without touching others). Capability slugs are strict routing handles used by sprint `component:` frontmatter; keep them lowercase and singular, then put nuance in Goal/Scope prose. -**On a brownfield repo** (existing code, no `spec/capabilities.md`), run `extract-signals.js --json` from the installed skill's `scripts/` directory first. It draws from README, CLAUDE.md/AGENTS.md, top-level source dirs, the last 100 commit messages, and `CHARTER.md` Objectives, and reports raw capability signals with draft Goal + draft Scope. Use the draft as interview seed only; grill mode still pressure-tests every admitted capability through the admission test and then pressure-tests every Behavior and Hard Constraint through the 3-axis test before commit. The script clusters by code organization (directory names, commit scopes), while real capabilities are functional contracts; expect grill mode to merge, split, or regroup raw signals rather than adopt them verbatim. The script never writes `spec/capabilities.md` itself — that decision belongs to grill. +**On a brownfield repo** (existing code, no `spec/capabilities.md`), run `extract-signals.js --repo-root --json` from the installed skill's `scripts/` directory first. It draws from README, CLAUDE.md/AGENTS.md, top-level source dirs, the last 100 commit messages, and `CHARTER.md` Objectives, and reports raw capability signals with draft Goal + draft Scope. Use the draft as interview seed only; grill mode still pressure-tests every admitted capability through the admission test and then pressure-tests every Behavior and Hard Constraint through the 3-axis test before commit. The script clusters by code organization (directory names, commit scopes), while real capabilities are functional contracts; expect grill mode to merge, split, or regroup raw signals rather than adopt them verbatim. The script never writes `spec/capabilities.md` itself — that decision belongs to grill. `spec/capabilities.md` lives at the target repo root in `spec/`. Layout, mutation rules, and rationale are in [`docs/spec-system-design.md`](../../docs/spec-system-design.md). The single-file shape is intentional while the spec remains compact: target 5-10 capabilities, warn above 12 capabilities or 400 lines, and split only above 500 lines, above 15 capabilities, or when ownership boundaries demand separate review paths.