From 81cba49d5d6ef1df0bfef2e97fb32379e372b9e3 Mon Sep 17 00:00:00 2001 From: SJ Lee Date: Fri, 29 May 2026 21:07:49 +0900 Subject: [PATCH 1/2] refactor: split spec charter and grill skills --- AGENTS.md | 8 + CHANGELOG.md | 4 +- CHARTER.md | 6 +- CLAUDE.md | 11 +- README.md | 9 + docs/spec-system-design.md | 58 +++--- skills/backlog-charter/SKILL.md | 182 ------------------ skills/backlog-triage/SKILL.md | 12 +- skills/dev-backlog/SKILL.md | 4 +- skills/spec-charter/SKILL.md | 123 ++++++++++++ .../references/alignment.md | 4 +- .../references/amendment.md | 2 +- .../references/create.md | 2 +- .../references/objectives.md | 2 +- .../references/reassess.md | 14 +- .../scripts/check-size.js | 0 .../scripts/check-size.test.js | 0 .../templates/charter.md | 0 skills/spec-grill/SKILL.md | 107 ++++++++++ .../references/capabilities.md | 4 +- .../references/spec-system-research.md | 0 .../scripts/extract-signals.js | 2 +- .../scripts/extract-signals.test.js | 0 .../templates/capabilities.md | 2 +- spec/capabilities.md | 48 ++++- 25 files changed, 360 insertions(+), 244 deletions(-) delete mode 100644 skills/backlog-charter/SKILL.md create mode 100644 skills/spec-charter/SKILL.md rename skills/{backlog-charter => spec-charter}/references/alignment.md (90%) rename skills/{backlog-charter => spec-charter}/references/amendment.md (91%) rename skills/{backlog-charter => spec-charter}/references/create.md (94%) rename skills/{backlog-charter => spec-charter}/references/objectives.md (93%) rename skills/{backlog-charter => spec-charter}/references/reassess.md (86%) rename skills/{backlog-charter => spec-charter}/scripts/check-size.js (100%) rename skills/{backlog-charter => spec-charter}/scripts/check-size.test.js (100%) rename skills/{backlog-charter => spec-charter}/templates/charter.md (100%) create mode 100644 skills/spec-grill/SKILL.md rename skills/{backlog-charter => spec-grill}/references/capabilities.md (95%) rename skills/{backlog-charter => spec-grill}/references/spec-system-research.md (100%) rename skills/{backlog-charter => spec-grill}/scripts/extract-signals.js (98%) rename skills/{backlog-charter => spec-grill}/scripts/extract-signals.test.js (100%) rename skills/{backlog-charter => spec-grill}/templates/capabilities.md (94%) diff --git a/AGENTS.md b/AGENTS.md index f026d1e..4ba5261 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -6,6 +6,14 @@ GitHub Issues + local sprint execution files for Claude Code / Codex. ``` skills/ + spec-charter/ + SKILL.md ← CHARTER.md create/amend + reassess contract + references/ ← Detailed specs (on-demand) + scripts/ ← Deterministic helpers (node) + spec-grill/ + SKILL.md ← spec/capabilities.md grill contract + references/ ← Detailed specs (on-demand) + scripts/ ← Deterministic helpers (node) dev-backlog/ SKILL.md ← Core process (~194 lines) references/ ← Detailed specs (on-demand) diff --git a/CHANGELOG.md b/CHANGELOG.md index 3daa2ed..2561f32 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,7 +6,9 @@ Each entry links the GitHub issue (the canonical spec) and the merge PR (the shi ## [Unreleased] -Nothing yet. +### Changed + +- Split the old `backlog-charter` surface into the spec-series skills `spec-charter` and `spec-grill`. `spec-charter` owns `CHARTER.md` create/amend/reassess; `spec-grill` owns `spec/capabilities.md` capability-contract authoring. Closes [#157](https://github.com/sungjunlee/dev-backlog/issues/157), [#158](https://github.com/sungjunlee/dev-backlog/issues/158), and [#159](https://github.com/sungjunlee/dev-backlog/issues/159). ## [0.5.0] — 2026-05-22 diff --git a/CHARTER.md b/CHARTER.md index a6ad766..d5bf091 100644 --- a/CHARTER.md +++ b/CHARTER.md @@ -15,8 +15,9 @@ sessions is rebuilt from scratch each time. ## Approach Keep GitHub Issues as the canonical task spec; add a thin, explicit, markdown-only execution hub (the active sprint file) that humans and agents -both read and update. Companion skills (`backlog-triage`, `backlog-charter`) -groom and orient the same GitHub-anchored state — they never replace it. +both read and update. Companion skills (`backlog-triage`, `spec-charter`, +`spec-grill`) groom and orient the same GitHub-anchored state — they never +replace it. No server, no daemon, no hidden state, no silent sync. ## Non-Goals @@ -43,3 +44,4 @@ No server, no daemon, no hidden state, no silent sync. | 2026-05-22 | `CHARTER.md` is a separate file at repo root, not merged into `_context.md` | The axis must stay a <5-min-read yardstick; `_context.md`'s HOW-knowledge would dilute it | — | | 2026-05-22 | The Alignment Check is prompt-driven inside `backlog-triage`, not a new `triage-*.js` | Issue→objective mapping is semantic, unlike the deterministic relate/stale scripts | — | | 2026-05-22 | Patterns from Fractal and gsd-2 are absorbed, not integrated | Both own the whole project lifecycle and conflict with the GitHub-Issues-anchored model | — | +| 2026-05-29 | `backlog-charter` splits into `spec-charter` and `spec-grill` | Existing-repo onboarding needs a discoverable second step from project charter to capability contracts | 2026-05-22 | diff --git a/CLAUDE.md b/CLAUDE.md index 8dd9e2c..1843743 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -8,10 +8,15 @@ GitHub Issues + local sprint execution files for Claude Code / Codex. ```text skills/ - backlog-charter/ - SKILL.md ← CHARTER.md create/amend contract - references/ ← Amendment + alignment specs + spec-charter/ + SKILL.md ← CHARTER.md create/amend + reassess contract + references/ ← Amendment, alignment, objective, reassess specs templates/ ← Runtime CHARTER.md template + spec-grill/ + SKILL.md ← spec/capabilities.md grill contract + references/ ← Capability heuristics + spec-system research + scripts/ ← Brownfield signal extraction helper + templates/ ← Runtime capabilities template backlog-triage/ SKILL.md ← Open-issue grooming contract references/ ← Detailed specs (on-demand) diff --git a/README.md b/README.md index 4dbd305..a01b0cf 100644 --- a/README.md +++ b/README.md @@ -94,6 +94,15 @@ Then use the skill during your coding session: /dev-backlog sync ``` +Optional spec-series setup: + +```text +/spec-charter create +/spec-grill +``` + +`spec-charter` creates the project-wide `CHARTER.md` axis. On existing repos, follow it with `spec-grill` to author `spec/capabilities.md`, the middle layer of capability contracts and Hard Constraints. + For the detailed sprint contract, section semantics, and full script inventory, see [skills/dev-backlog/SKILL.md](skills/dev-backlog/SKILL.md). Important if you use `dev-relay`: sprint files are not fully freeform markdown. diff --git a/docs/spec-system-design.md b/docs/spec-system-design.md index 34bd970..ff24fcd 100644 --- a/docs/spec-system-design.md +++ b/docs/spec-system-design.md @@ -1,7 +1,7 @@ # Spec System Design (v0.1) **Status:** Approved (M tier) · **Date:** 2026-05-23 · **Author:** session capture -**Supersedes:** — · **Related:** [`CHARTER.md`](../CHARTER.md), [`skills/backlog-charter/`](../skills/backlog-charter/) +**Supersedes:** — · **Related:** [`CHARTER.md`](../CHARTER.md), [`skills/spec-charter/`](../skills/spec-charter/), [`skills/spec-grill/`](../skills/spec-grill/) A layered, brownfield-friendly project spec system that survives multi-day autonomous agent execution without rubber-stamping itself into uselessness. This doc captures the current architecture, durable policy, research grounding, and historical implementation evidence. @@ -24,7 +24,7 @@ For autonomous runs that span days, this means: setpoint exists, sensor doesn't, - Lower layers can update live without human edit, via structurally bounded channels - Interactive "grill-me" mode that pressure-tests specs into verifiable predicates - Loose documents, strict handles: prose stays flexible; machine-routing fields stay small and stable -- Bias to simplicity: one new file family, zero new skill names +- Bias to clarity: spec-series skill names match the artifact layer they operate on ## Non-Goals @@ -83,10 +83,10 @@ The rule: constrain the address, not the thought. `component:` is a routing hand | Layer | Who writes | When | Gate | |---|---|---|---| -| `CHARTER.md` Problem/Approach/Non-Goals | human via `backlog-charter amend` | rarely | Tier 1 gate (existing) | +| `CHARTER.md` Problem/Approach/Non-Goals | human via `spec-charter amend` | rarely | Tier 1 gate (existing) | | `CHARTER.md` Objectives | human via amend; status advance proof-gated | when an objective is added/removed/proven | Tier 2 gate (existing) | | `CHARTER.md` Decisions | append-only | when a non-trivial cross-cutting decision is made | Tier 3 (existing) | -| `spec/capabilities.md` Goal/Scope/Behaviors/HardConstraints per capability | human via `backlog-charter grill` (new mode) | when a capability's contract changes | challenge + confirm + apply | +| `spec/capabilities.md` Goal/Scope/Behaviors/HardConstraints per capability | human via `spec-grill` | when a capability's contract changes | challenge + confirm + apply | | `spec/capabilities.md` `## Learnings` blocks | **`dev-relay/scripts/append-learnings.js`** | end of every successful relay run with a primary `component:` tag | structurally bounded append between magic markers; rejects anything else | | `spec/capabilities.md` `## Decisions` blocks | human | when a capability-level decision is made | append-only by convention; promote to CHARTER Tier 3 if cross-cutting | @@ -94,8 +94,9 @@ The rule: constrain the address, not the thought. `component:` is a routing hand | Artifact | Owns | Does not own | |---|---|---| -| `skills/backlog-charter/SKILL.md` | short dispatch contract: when to invoke modes, no-edit boundary, required reassess report sections | detailed reassess heuristics | -| `skills/backlog-charter/references/reassess.md` | operational reassess procedure: evidence order, report shape, recommendation rules, Learning Actions, stale-spec failure modes | durable naming policy or historical build notes | +| `skills/spec-charter/SKILL.md` | CHARTER create/amend and report-only reassess dispatch contract | capability authoring details | +| `skills/spec-charter/references/reassess.md` | operational reassess procedure: evidence order, report shape, recommendation rules, Learning Actions, stale-spec failure modes | durable naming policy or historical build notes | +| `skills/spec-grill/SKILL.md` | `spec/capabilities.md` authoring, brownfield signal admission, and 3-axis predicate test | CHARTER mutation rules | | `docs/spec-system-design.md` | durable design policy: lifecycle, naming policy, mutation discipline, split/defer triggers, historical rationale | step-by-step skill execution details | ### Stale-spec lifecycle @@ -104,8 +105,8 @@ Accepted specs are useful only while they still match product reality. The syste 1. **Setpoint:** `CHARTER.md` and `spec/capabilities.md` describe the accepted project/capability contracts. 2. **Sensor:** relay and sprint execution append bounded observations as `## Learnings` or sprint context. -3. **Diagnosis:** deterministic scripts report structural signals first (`capabilities-doctor.js`, `component-lint.js`); `backlog-charter reassess` turns those signals into a report. -4. **Human gate:** accepted changes route through `backlog-charter amend`, `backlog-charter grill `, or a separate user-approved Learning Action. +3. **Diagnosis:** deterministic scripts report structural signals first (`capabilities-doctor.js`, `component-lint.js`); `spec-charter reassess` turns those signals into a report. +4. **Human gate:** accepted changes route through `spec-charter amend`, `spec-grill `, or a separate user-approved Learning Action. 5. **No silent controller:** reassess may recommend edits, promotion, or archival, but it must not edit CHARTER direction, capability Goal/Scope/Behaviors/Hard Constraints, Decisions, or Learnings while diagnosing. This keeps freedom where agents need it (reasoning over evidence) and control where the spec could otherwise rationalize itself into noise. @@ -131,14 +132,18 @@ Reassess may recommend a Learning Action, but diagnosis itself does not rewrite ### Command surface and reserved names -The current callable surface is `backlog-charter` with `create`, `amend`, `grill`, and `reassess` modes. There are no callable `spec-*` skills today. +The current callable spec-series surface is: -The names `spec-grill`, `spec-reassess`, and `spec-learn` are reserved/non-callable future split candidates. They should appear only in naming-policy discussion until a split is justified by concrete signal: +- `spec-charter` — create/amend `CHARTER.md` and run report-only reassess. +- `spec-grill` — create/refine `spec/capabilities.md` from repo signals. -- `skills/backlog-charter/SKILL.md` exceeds the local compactness budget (about 250 lines in this repo) -- mode instructions no longer fit a single understandable spine -- users repeatedly ask for `spec-*` commands and fail to discover `backlog-charter` -- capability/reassess work no longer reads as CHARTER lifecycle work +This split exists because existing-repo onboarding naturally needs `CHARTER.md` first and capability contracts next; hiding the second step behind a charter-named `grill` mode made the intended path hard to discover. + +The names `spec-reassess` and `spec-learn` are reserved/non-callable future split candidates. They should appear only in naming-policy discussion until a split is justified by concrete signal: + +- reassess instructions no longer fit inside `spec-charter` without making the charter workflow muddy +- users repeatedly ask for a dedicated report-only spec health command +- Learning Actions become frequent enough to need their own trigger surface ### Why single-file, not per-capability @@ -152,7 +157,7 @@ When the hard trigger fires, `split-capabilities.js` migrates to `spec/component ## Research grounding -Full literature survey lives at [`references/spec-system-research.md`](../skills/backlog-charter/references/spec-system-research.md) (to be written; see follow-up issue). Three findings load-bear this design: +Full literature survey lives at [`references/spec-system-research.md`](../skills/spec-grill/references/spec-system-research.md). Three findings load-bear this design: ### 1. The 3-mode failure taxonomy for autonomous-agent specs @@ -200,6 +205,7 @@ These are current policy anchors carried forward from implementation. They are n - **D3** `spec/capabilities.md` size warning threshold — resolved: warn above 12 capabilities or 400 lines; recommend split above 500 lines, 15 capabilities, or ownership-boundary pressure. - **D4** Multi-component sprint task: resolved to one primary capability slug. Secondary touches are prose, not routing metadata. - **D5** `component:` tag freeform string vs declared-only enum? Resolved to declared capability slug, with `component-lint.js` catching typos before they reach Learnings. +- **D6** Spec-series command surface — resolved: `spec-charter` owns `CHARTER.md`; `spec-grill` owns `spec/capabilities.md`; `spec-reassess` remains reserved until report-only usage justifies a split. --- @@ -209,8 +215,8 @@ Strangler-fig. None of these requires re-architecture, just expansion: 1. `spec/capabilities.md` outgrows comfort → `split-capabilities.js` migrates to `spec/components/.md`. SKILL.md routes the same gates over the new file shape. 2. Decision volume justifies ADRs → `spec/decisions/-.md` with a tiny ADR template. Per-capability `## Decisions` sections become a "lite" entry point. -3. Working agent shows rationalization tells in grill mode → adversarial grill runs as a subagent with separate context. `backlog-charter` SKILL.md gains a `--adversarial-subagent` flag. -4. Reserved/non-callable names (`spec-grill`, `spec-reassess`, `spec-learn`) become real skills only if the triggers in [Command surface and reserved names](#command-surface-and-reserved-names) fire. +3. Working agent shows rationalization tells in grill mode -> adversarial grill runs as a subagent with separate context. `spec-grill` gains a documented adversarial-review option. +4. Reserved/non-callable names (`spec-reassess`, `spec-learn`) become real skills only if the triggers in [Command surface and reserved names](#command-surface-and-reserved-names) fire. Every L-tier feature is a YAGNI-violating addition until it's not. Defer until signal. @@ -229,16 +235,16 @@ This section records how the v0.1 spec system and reassess MVP were built. It is ``` PR-1: template + SKILL.md extension (no executable code) ├─ docs/spec-system-design.md (this file) - ├─ skills/backlog-charter/templates/capabilities.md (NEW) - ├─ skills/backlog-charter/SKILL.md (+grill mode section) + ├─ skills/spec-grill/templates/capabilities.md (NEW) + ├─ skills/spec-grill/SKILL.md (capability grill contract) └─ CHARTER.md (no change; just verify alignment) ↓ (dogfood: write spec/capabilities.md for dev-backlog itself) ↓ PR-2: brownfield bootstrap (greenfield path also works) - ├─ skills/backlog-charter/scripts/extract-signals.js (NEW, ~80 LOC) - ├─ skills/backlog-charter/scripts/extract-signals.test.js - └─ skills/backlog-charter/SKILL.md (+brownfield invocation) + ├─ skills/spec-grill/scripts/extract-signals.js (NEW, ~80 LOC) + ├─ skills/spec-grill/scripts/extract-signals.test.js + └─ skills/spec-grill/SKILL.md (+brownfield invocation) ↓ (dogfood: run extract-signals on dev-relay → propose its spec/capabilities.md) ↓ @@ -257,8 +263,8 @@ PR #142 implemented the deliberately small follow-up after v0.1: ``` PR-4: stale-spec reassess MVP ├─ docs/spec-system-design.md (+stale-spec lifecycle and naming policy) - ├─ skills/backlog-charter/SKILL.md (+report-only reassess mode) - └─ skills/backlog-charter/references/reassess.md (NEW, report heuristics) + ├─ skills/spec-charter/SKILL.md (+report-only reassess mode) + └─ skills/spec-charter/references/reassess.md (NEW, report heuristics) ↓ (dogfood: run reassess manually on dev-backlog and a larger repo shape) ↓ @@ -286,7 +292,7 @@ The most authentic test of this spec system is applying it to projects we alread 2. **dev-relay** (brownfield — established code, no CHARTER yet). Validates the full brownfield path: `extract-signals.js` → grill → `spec/capabilities.md` written end-to-end. Also exercises live-update since dev-relay *is* the relay-merge surface. 3. **Large-repo fixture** — a deterministic tamgu_note-shaped fixture with many feature folders and workflow commit scopes. Protects against treating feature count as capability count without depending on a private checkout. 4. **(optional, after both)** A real product repo from outside this workspace. Highest signal but lowest control. Worth doing once internal dogfood looks healthy. -5. **Manual reassess pass** — run `backlog-charter reassess` on dev-backlog and one larger repo shape before adding sprint-close or relay-merge hooks. The test is whether the report produces a useful next action without creating churn. +5. **Manual reassess pass** — run `spec-charter reassess` on dev-backlog and one larger repo shape before adding sprint-close or relay-merge hooks. The test is whether the report produces a useful next action without creating churn. Each dogfood produces: - A `spec/capabilities.md` in the target repo @@ -313,7 +319,7 @@ This design advances dev-backlog's own CHARTER Objectives: - **O3 (active):** `<5-min reference axis usable` — capability specs *extend* the 5-min property below CHARTER. Not advance to validated on this; one more independent project required. - **O4 (active):** `drift detectable without manual triage` — `## Learnings` + `component-lint.js` are direct drift-detection surfaces. Same proof-gate. -- **O5 (deferred):** `auto-reassess wired into relay-merge / sprint completion` — report-only `backlog-charter reassess` is the manual precursor. Do not wire hooks until manual reassess repeatedly produces useful, low-noise recommendations. +- **O5 (deferred):** `auto-reassess wired into relay-merge / sprint completion` — report-only `spec-charter reassess` is the manual precursor. Do not wire hooks until manual reassess repeatedly produces useful, low-noise recommendations. - **O6 (deferred):** `/goal completion-condition auto-emission from CHARTER + active sprint` — unchanged. Status advance for any of these is gated on independent-project proof, per CHARTER Tier 2 discipline. diff --git a/skills/backlog-charter/SKILL.md b/skills/backlog-charter/SKILL.md deleted file mode 100644 index 5b3c525..0000000 --- a/skills/backlog-charter/SKILL.md +++ /dev/null @@ -1,182 +0,0 @@ ---- -name: backlog-charter -argument-hint: "[create|amend|grill|reassess]" -description: "Create, amend, grill, and reassess the project spec axis: CHARTER.md plus spec/capabilities.md. Use to establish or evolve project direction, author capability contracts, review stale specs, recommend Learning Actions, or decide whether Behaviors/Constraints still match execution evidence. 프로젝트 축, 기준, 헌장, 능력 명세, stale spec, spec reassess." -compatibility: Requires git. Works on Claude Code and Codex. -metadata: - related-skills: "dev-backlog, backlog-triage" ---- - -# 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. - -## 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 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 - -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 - -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 - -`CHARTER.md` lives at the target repo root as a peer of `README.md`. It records what good looks like: the problem, approach, explicit non-goals, verifiable objectives, and immutable decision history the backlog is measured against. - -Absence is supported. Projects opt in by creating the file; other skills degrade gracefully when it is missing. Keep the charter under a ~5-minute read. Operational know-how does not belong here; put rediscovery-prone HOW-knowledge in `_context.md`. - -| File | Question it answers | -|------|---------------------| -| `CHARTER.md` | What good looks like / why (the yardstick) | -| `_context.md` | Operational facts you would otherwise rediscover (HOW-knowledge) | -| `CLAUDE.md` / `AGENTS.md` | How agents work in this repo (development harness; not product authority by default) | -| `README.md` | Outward-facing introduction | - -## 3 Tiers - -| Tier | Sections | Mutation discipline | Rationale | -|------|----------|---------------------|-----------| -| **1 · Direction** | Problem, Approach, Non-Goals | Human-gated: propose → confirm → apply. Slowest-moving — the core that survives if scope shrinks. | A stable core is what makes the moving parts meaningful. | -| **2 · Predicates** | Objectives | Status advance (`active`→`validated`/`deferred`) requires **proof**. Adding/removing an objective is human-gated. | "You cannot evolve the axis to declare victory — you must prove it." (gsd-2) | -| **3 · History** | Decisions | **Append-only.** Never edit or delete a row; reverse via a new `supersedes` row. | Provenance is immutable. | - -A stable core makes the moving parts meaningful. This tiering prevents the axis from self-evolving into a rubber-stamp: direction changes are gated, objective status requires proof, and history is frozen. - -## Create Mode - -Use create mode when `CHARTER.md` is absent at the repo root, or when invoked as `backlog-charter create` and no charter exists. - -1. Draft from repo signals: product/user-facing signals (`README.md`, open epics/issues, `CHANGELOG.md`) before development-harness signals (`CLAUDE.md`, `AGENTS.md`). Harness files may inform workflow conventions, local commands, and repo-specific guardrails, but they do not override README, CHARTER, issues, code structure, or user interview answers for product/capability authority unless they explicitly describe product boundaries. When signals conflict, surface the conflict in the interview rather than picking silently. -2. Interview the user to fill and sharpen Problem, Approach, Non-Goals, and initial Objectives. Follow the checklist in `references/create.md` — Problem framing options, the wedge test for Approach, Non-Goals elicitation, and Objective framing that cites `references/objectives.md`. -3. Write repo-root `CHARTER.md` from `templates/charter.md` with `revision: 1` and today's `last_amended`. The Decisions table may be left empty — seed 3–5 rows only when prior design docs, ADRs, or notable merged PRs already record direction; remember that whatever lands becomes immutable from revision 2. - -Objective conventions: - -- State objectives as verifiable predicates, not tasks. -- Mixed rigor is allowed: a runnable check is ideal, but an observable statement is acceptable. -- Use `O` IDs for traceability. -- Never reuse a removed objective ID; new objectives take the next free number. -- Record provenance with `src:` (`user`, `inferred`, or `execution`). - -See `references/objectives.md` for 5 good and 5 bad worked examples, common rewrite patterns, and a 30-second predicate test. - -## Amend Mode - -Use amend mode when `CHARTER.md` exists at the repo root, or when invoked as `backlog-charter amend`. - -First re-read the current `CHARTER.md`. Direct hand-edits are allowed because it is the user's file; this skill is the disciplined path for applying the tier gates. - -Apply the 3-tier discipline: - -- Tier 1 plus objective add/remove: surface stale or weak items, challenge them, propose concrete diffs, confirm with the user, then apply. Do not rubber-stamp. -- 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 --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. - -See `references/amendment.md` for deep challenge and proof-gate heuristics. - -## Grill Mode - -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 --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 labels signal authority: README/CHARTER/issues are product authority, source directories are repo-structure evidence, commit scopes are history, and CLAUDE.md/AGENTS.md are development-harness context. Harness context can seed questions about conventions and workflow, but it must not create accepted capability boundaries by itself. 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. - -### Capability Admission Test - -Before interviewing a candidate capability, decide whether it deserves to exist. Raw extraction signals are not accepted specs. - -Admit a capability only when most of these are true: - -- It is a repeated decision boundary, not just a directory name or commit scope. -- It owns a primary relay-learning destination. -- Its Goal can be stated as an observable user or operator outcome. -- Its Behaviors and Hard Constraints differ meaningfully from neighboring candidates. -- If two candidates share nearly all predicates, merge them. -- If one candidate needs more than five Behaviors to feel complete, split it along the contract boundary the extra Behaviors describe. - -Use this as a bloat check before the per-capability flow. dev-backlog's five capabilities are contract surfaces; a large feature-first app may have many feature folders but only 5-10 durable capability contracts. - -### Per-Capability Interview Flow - -For each capability, walk the user through this order — do not skip ahead: - -1. **Goal** — one sentence: what the user can observe when this works. Diagnosis-side framing belongs in CHARTER; capability Goal is the observable outcome. -2. **In-scope / Out-of-scope** — what this capability owns, and the boundary it deliberately respects. Out-of-scope is as important as in-scope: it prevents creep. -3. **Expected Behaviors** — three verifiable predicates. Each one must pass the 3-axis test below. Reject and rewrite until it does. -4. **Hard Constraints** — two bright-lines this capability never crosses, even if asked. Adversarial-Goodhart defenses live here. - -Stop at three Behaviors and two Hard Constraints per capability on the first pass; more is bloat and harder to keep falsifiable. Add later via rerun. - -### The 3-Axis Predicate Test - -Every Behavior and Hard Constraint must pass all three axes before it is committed. Research grounding is in the design doc; the test in operation: - -1. **Authority axis.** Would the user be unhappy if an agent satisfied this *measurably* but in a way that ignored their intent? If yes, the predicate is under-specified — encode the missing intent as a sharper Behavior or promote it to a Hard Constraint. (Defends against misspecification.) -2. **Distributional axis.** Does this predicate hold in unseen code areas or unseen workloads? If no, restate it as environment-independent — or scope it to the conditions where it holds. (Defends against goal misgeneralization.) -3. **Manipulability axis.** Can an agent satisfy this by editing the measurement channel rather than the system? If yes, the predicate is gameable — add a *structural* restriction outside the spec, not just sharper prose. (Defends against adversarial Goodhart.) - -A predicate that passes all three is committable. A predicate that fails any axis is rewritten or split — never rubber-stamped. - -### Tier Gates - -Grill mode applies the same challenge + confirm + apply discipline used by amend mode: - -- Goal / In-scope / Out-of-scope are Tier-1-equivalent: challenge before applying. Default to no change. -- Behaviors / Hard Constraints are Tier-2-equivalent: each must pass the 3-axis test. The test is the proof gate. -- `## Learnings` and `## Decisions` are **not** interview targets. Learnings are appended by the bounded `append-learnings` writer between magic markers (`` / ``); Decisions are append-only by convention. Grill mode never edits either, but it may recommend a user-approved Learning Action when a capability has more than 5-7 inline Learnings. - -### Writing the File - -On first run, copy `templates/capabilities.md` to `spec/capabilities.md` at the repo root, then walk the interview for one capability. On rerun (`grill `), edit only the named capability block; leave the rest of the file untouched. If `spec/capabilities.md` does not exist on a rerun invocation, fall back to greenfield mode and surface the absence. - -After applying an accepted change, do **not** bump a revision number on `spec/capabilities.md` — `git blame` is the source of truth (per design doc §"NOT in scope"). Note in the conversation which capability was edited. - -See `references/capabilities.md` for additional grill heuristics (placeholder on day 1 — expand as findings accrue). - -## Reassess Mode - -Use reassess mode when the user asks whether `CHARTER.md` or `spec/capabilities.md` is stale, asks to review Learnings, wants a periodic spec health check, or when major model/tool/harness changes could alter how agents interpret repo context. - -Reassess never edits files. It diagnoses drift and recommends next actions; accepted fixes must run through `backlog-charter amend`, `backlog-charter grill `, or a separate user-approved Learning Action. - -Dispatch contract: - -1. Resolve helper scripts from the installed dev-backlog skill directory; if unavailable, report **Missing Evidence**. -2. Start with bounded evidence: `capabilities-doctor.js --json`, `component-lint.js --json`, named CHARTER/capability sections, the active sprint, and at most the latest five completed sprint files. -3. Emit these report sections: **Evidence**, **No Change**, **Grill Candidates**, **Amend Candidates**, **Learning Actions**, **Missing Evidence**, **Recommended Next Step**. -4. Use `references/reassess.md` as the source of truth for evidence order, report shape, recommendation rules, Learning Actions, and stale-spec failure modes. - -## References - -- `references/create.md` — create-mode signals priority, conflict handling, interview checklist, seed-Decisions guidance. -- `references/amendment.md` — challenge checklist, proof-gate rules, no-rubber-stamp discipline, and bloat checks. -- `references/alignment.md` — shared work↔objective mapping logic consumed by `backlog-triage` and `dev-backlog`. -- `references/objectives.md` — verifiable-predicate examples (5 good, 5 bad), common rewrite patterns, 30-second test. -- `references/capabilities.md` — grill-mode heuristics for `spec/capabilities.md` authoring (placeholder; expand as findings accrue). -- `references/reassess.md` — report-only stale-spec reassessment: evidence sources, output shape, Learning Actions, and failure modes. -- `references/spec-system-research.md` — research grounding for the layered spec system (autonomous-agent failure taxonomy, control-theory framing, spec-language stability discipline). diff --git a/skills/backlog-triage/SKILL.md b/skills/backlog-triage/SKILL.md index 104ce7c..7292d19 100644 --- a/skills/backlog-triage/SKILL.md +++ b/skills/backlog-triage/SKILL.md @@ -4,7 +4,7 @@ argument-hint: "[collect|relate|stale|report|apply] [options]" description: Interactive backlog grooming for open GitHub Issues. Classifies, relates, flags stale/obsolete, and proposes priorities — produces a markdown triage report you review before applying. Advisory by default; mutations require explicit --apply. Use for backlog review, issue grooming, stale cleanup, priority re-ranking, 백로그 정리, 이슈 검토, 트리아지, 정리. compatibility: Requires gh CLI and git. Works on Claude Code and Codex. metadata: - related-skills: "backlog-charter, dev-backlog, relay, relay-plan" + related-skills: "spec-charter, dev-backlog, relay, relay-plan" --- # Backlog Triage @@ -32,7 +32,7 @@ Sibling skill to dev-backlog, not a replacement. dev-backlog is the execution hu Every script in this phase is read-only. Running any number of times is safe. The snapshot is the canonical artifact; all downstream analysis consumes it via `--snapshot PATH` (no re-fetch). -Alignment Check is prompt-driven, not a `triage-*.js` script: when `CHARTER.md` exists, map open issues to Objectives using `../backlog-charter/references/alignment.md` and emit an `## Alignment` report section. When `CHARTER.md` is absent, skip this step entirely and keep the existing report shape. +Alignment Check is prompt-driven, not a `triage-*.js` script: when `CHARTER.md` exists, map open issues to Objectives using `../spec-charter/references/alignment.md` and emit an `## Alignment` report section. When `CHARTER.md` is absent, skip this step entirely and keep the existing report shape. ### Phase 2 — Apply (opt-in, explicit) @@ -129,7 +129,7 @@ Active Objectives with no open issue advancing them (medium severity). Issues that violate a Non-Goal (high severity). ### Proposed CHARTER changes -Seed proposals for `backlog-charter` amend; triage does not mutate `CHARTER.md`. +Seed proposals for `spec-charter` amend; triage does not mutate `CHARTER.md`. ## Apply Checklist Consolidated list of every anchored action for scan-and-check review. The apply step parses @@ -147,7 +147,7 @@ source sections above both count as acceptance surfaces (see `references/apply.m | Milestone lifecycle, monthly progress issue | dev-backlog | | AC checkboxes inside issue bodies (`AC:BEGIN`/`END`) | dev-backlog | | Open-issue classification, relationships, stale flags | backlog-triage | -| CHARTER alignment of open issues | backlog-triage (report; `CHARTER.md` mutations stay with `backlog-charter`) | +| CHARTER alignment of open issues | backlog-triage (report; `CHARTER.md` mutations stay with `spec-charter`) | | Priority / milestone **proposals** | backlog-triage (report) | | Priority / milestone **mutations** | backlog-triage (`--apply`) | | Post-triage sprint planning | dev-backlog (reads report, edits sprint file) | @@ -158,7 +158,7 @@ Recommended cadence: run backlog-triage weekly or bi-weekly. Feed the report's M ## Process -**Collect → Analyze → Report.** One `gh` fetch, one snapshot, downstream scripts consume it via `--snapshot`. Re-fetching in each script is a bug — it creates drift across signals. During Analyze, run the prompt-driven Alignment Check when `CHARTER.md` is present; its Proposed CHARTER changes feed `backlog-charter` amend and are not applied by `triage-apply.js`, which only mutates GitHub issues. +**Collect → Analyze → Report.** One `gh` fetch, one snapshot, downstream scripts consume it via `--snapshot`. Re-fetching in each script is a bug — it creates drift across signals. During Analyze, run the prompt-driven Alignment Check when `CHARTER.md` is present; its Proposed CHARTER changes feed `spec-charter` amend and are not applied by `triage-apply.js`, which only mutates GitHub issues. **Review the report.** Read each proposal. Check the ones you accept (flip `[ ]` → `[x]`). Leave rejected ones unchecked. Do not delete anchor comments; unchecked anchors are ignored by apply. @@ -193,7 +193,7 @@ Flags on individual scripts override config. - `references/relationships.md` — mention / blocks / depends-on / duplicate heuristics, evidence format - `references/stale.md` — obsolescence signals, thresholds, suggested-action grammar - `references/apply.md` — anchor grammar, parse rules, idempotency contract, apply-log schema -- `../backlog-charter/references/alignment.md` — prompt-driven CHARTER work↔objective mapping and drift severity rules +- `../spec-charter/references/alignment.md` — prompt-driven CHARTER work↔objective mapping and drift severity rules --- diff --git a/skills/dev-backlog/SKILL.md b/skills/dev-backlog/SKILL.md index 279e784..599e035 100644 --- a/skills/dev-backlog/SKILL.md +++ b/skills/dev-backlog/SKILL.md @@ -4,14 +4,14 @@ argument-hint: "[orient|plan|work|next|sync] [issue-number]" description: Manage development work through GitHub Issues + local sprint files. Issues/Milestones are the source of truth; local sprint files handle execution — batching, ordering, context, and progress. Use for creating issues, planning sprints, checking what to work on, reviewing progress, syncing with GitHub, managing milestones, backlog, 다음 작업, 이슈 만들어, 스프린트 계획, 백로그. compatibility: Requires gh CLI and git. Works on Claude Code and Codex. metadata: - related-skills: "backlog-charter, backlog-triage, relay, relay-plan, relay-dispatch, relay-review, relay-merge" + related-skills: "spec-charter, spec-grill, backlog-triage, relay, relay-plan, relay-dispatch, relay-review, relay-merge" --- # Dev Backlog README covers install and human quick start. This skill file is the execution contract for agents: file roles, sprint structure, process, and script behavior. -Related skills: [`backlog-charter`](../backlog-charter/SKILL.md) for the optional `CHARTER.md` reference axis, and [`backlog-triage`](../backlog-triage/SKILL.md) for weekly backlog grooming before you plan the next sprint. +Related skills: [`spec-charter`](../spec-charter/SKILL.md) for the optional `CHARTER.md` reference axis, [`spec-grill`](../spec-grill/SKILL.md) for `spec/capabilities.md`, and [`backlog-triage`](../backlog-triage/SKILL.md) for weekly backlog grooming before you plan the next sprint. Two layers, each with a clear job: diff --git a/skills/spec-charter/SKILL.md b/skills/spec-charter/SKILL.md new file mode 100644 index 0000000..6251ad2 --- /dev/null +++ b/skills/spec-charter/SKILL.md @@ -0,0 +1,123 @@ +--- +name: spec-charter +argument-hint: "[create|amend|reassess]" +description: "Create, amend, and reassess CHARTER.md as the project-wide spec axis. Use to establish or evolve project direction, Objectives, Non-Goals, Decisions, stale spec findings, project charter, 기준, 헌장, 방향성, spec axis." +compatibility: Requires git. Works on Claude Code and Codex. +metadata: + related-skills: "spec-grill, dev-backlog, backlog-triage" +--- + +# Spec 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. + +`CHARTER.md` is the first layer, not the whole large-repo spec. On existing/brownfield repos, finish create mode by recommending `spec-grill` so the user can author `spec/capabilities.md` from real repo signals. + +## Execution Contract + +### Mode Router + +Explicit modes win first: + +| User intent | Mode | Boundary | +|-------------|------|----------| +| Create the project axis, baseline, charter, or first spec layer | `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. | +| Check whether charter/capabilities/Learnings are stale or should change | `reassess` | Report-only; routes accepted fixes to `spec-charter amend`, `spec-grill`, or a Learning Action. | + +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 user asks for capability contracts, component boundaries, or `spec/capabilities.md`, route to `spec-grill`. + +### Helper Scripts + +Resolve helper scripts from the installed `spec-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`) 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 + +End every mode with a short summary: + +- `create`: created files, unresolved assumptions, and whether `spec-grill` is the recommended next step. +- `amend`: accepted changes, refused/parked changes, proof cited for status advances, and size-check result. +- `reassess`: required report sections from the Reassess Mode dispatch contract, with one recommended next step. + +## What CHARTER.md Is + +`CHARTER.md` lives at the target repo root as a peer of `README.md`. It records what good looks like: the problem, approach, explicit non-goals, verifiable objectives, and immutable decision history the backlog is measured against. + +Absence is supported. Projects opt in by creating the file; other skills degrade gracefully when it is missing. Keep the charter under a ~5-minute read. Operational know-how does not belong here; put rediscovery-prone HOW-knowledge in `_context.md`. + +| File | Question it answers | +|------|---------------------| +| `CHARTER.md` | What good looks like / why (the yardstick) | +| `spec/capabilities.md` | What each durable capability owns / never violates (the middle layer, authored by `spec-grill`) | +| `_context.md` | Operational facts you would otherwise rediscover (HOW-knowledge) | +| `CLAUDE.md` / `AGENTS.md` | How agents work in this repo (development harness; not product authority by default) | +| `README.md` | Outward-facing introduction | + +## 3 Tiers + +| Tier | Sections | Mutation discipline | Rationale | +|------|----------|---------------------|-----------| +| **1 · Direction** | Problem, Approach, Non-Goals | Human-gated: propose -> confirm -> apply. Slowest-moving: the core that survives if scope shrinks. | A stable core is what makes the moving parts meaningful. | +| **2 · Predicates** | Objectives | Status advance (`active` -> `validated`/`deferred`) requires **proof**. Adding/removing an objective is human-gated. | You cannot evolve the axis to declare victory; you must prove it. | +| **3 · History** | Decisions | **Append-only.** Never edit or delete a row; reverse via a new `supersedes` row. | Provenance is immutable. | + +This tiering prevents the axis from self-evolving into a rubber-stamp: direction changes are gated, objective status requires proof, and history is frozen. + +## Create Mode + +Use create mode when `CHARTER.md` is absent at the repo root, or when invoked as `spec-charter create` and no charter exists. + +1. Draft from repo signals: product/user-facing signals (`README.md`, open epics/issues, `CHANGELOG.md`) before development-harness signals (`CLAUDE.md`, `AGENTS.md`). Harness files may inform workflow conventions, local commands, and repo-specific guardrails, but they do not override README, CHARTER, issues, code structure, or user interview answers for product/capability authority unless they explicitly describe product boundaries. When signals conflict, surface the conflict in the interview rather than picking silently. +2. Interview the user to fill and sharpen Problem, Approach, Non-Goals, and initial Objectives. Follow the checklist in `references/create.md`: Problem framing options, the wedge test for Approach, Non-Goals elicitation, and Objective framing that cites `references/objectives.md`. +3. Write repo-root `CHARTER.md` from `templates/charter.md` with `revision: 1` and today's `last_amended`. The Decisions table may be left empty. Seed 3-5 rows only when prior design docs, ADRs, or notable merged PRs already record direction; whatever lands becomes immutable from revision 2. +4. If the target repo is brownfield, recommend `spec-grill` as the next step. Brownfield signals include existing source roots (`src/`, `app/`, `lib/`, `packages/`, `skills/`), commit history, tests/scripts/config, open issues, or multiple top-level feature/workflow surfaces. + +Objective conventions: + +- State objectives as verifiable predicates, not tasks. +- Mixed rigor is allowed: a runnable check is ideal, but an observable statement is acceptable. +- Use `O` IDs for traceability. +- Never reuse a removed objective ID; new objectives take the next free number. +- Record provenance with `src:` (`user`, `inferred`, or `execution`). + +See `references/objectives.md` for worked examples, rewrite patterns, and a 30-second predicate test. + +## Amend Mode + +Use amend mode when `CHARTER.md` exists at the repo root, or when invoked as `spec-charter amend`. + +First re-read the current `CHARTER.md`. Direct hand-edits are allowed because it is the user's file; this skill is the disciplined path for applying the tier gates. + +Apply the 3-tier discipline: + +- Tier 1 plus objective add/remove: surface stale or weak items, challenge them, propose concrete diffs, confirm with the user, then apply. Do not rubber-stamp. +- 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 --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. + +See `references/amendment.md` for deep challenge and proof-gate heuristics. + +## Reassess Mode + +Use reassess mode when the user asks whether `CHARTER.md` or `spec/capabilities.md` is stale, asks to review Learnings, wants a periodic spec health check, or when major model/tool/harness changes could alter how agents interpret repo context. + +Reassess never edits files. It diagnoses drift and recommends next actions; accepted fixes must run through `spec-charter amend`, `spec-grill `, or a separate user-approved Learning Action. + +Dispatch contract: + +1. Resolve helper scripts from the installed dev-backlog skill directory; if unavailable, report **Missing Evidence**. +2. Start with bounded evidence: `capabilities-doctor.js --json`, `component-lint.js --json`, named CHARTER/capability sections, the active sprint, and at most the latest five completed sprint files. +3. Emit these report sections: **Evidence**, **No Change**, **Grill Candidates**, **Amend Candidates**, **Learning Actions**, **Missing Evidence**, **Recommended Next Step**. +4. Use `references/reassess.md` as the source of truth for evidence order, report shape, recommendation rules, Learning Actions, and stale-spec failure modes. + +## References + +- `references/create.md` — create-mode signals priority, conflict handling, interview checklist, seed-Decisions guidance. +- `references/amendment.md` — challenge checklist, proof-gate rules, no-rubber-stamp discipline, and bloat checks. +- `references/alignment.md` — shared work-to-objective mapping logic consumed by `backlog-triage` and `dev-backlog`. +- `references/objectives.md` — verifiable-predicate examples, common rewrite patterns, 30-second test. +- `references/reassess.md` — report-only stale-spec reassessment: evidence sources, output shape, Learning Actions, and failure modes. +- [`../spec-grill/SKILL.md`](../spec-grill/SKILL.md) — companion skill for authoring `spec/capabilities.md`. diff --git a/skills/backlog-charter/references/alignment.md b/skills/spec-charter/references/alignment.md similarity index 90% rename from skills/backlog-charter/references/alignment.md rename to skills/spec-charter/references/alignment.md index 35185a6..85fe5d2 100644 --- a/skills/backlog-charter/references/alignment.md +++ b/skills/spec-charter/references/alignment.md @@ -21,7 +21,7 @@ Report these findings when present: |---------|----------|------| | `orphan work` | medium | An open issue maps to no objective. Ask whether to add an objective, defer the issue, or drop it. | | `neglected objective` | medium | An `active` objective has no open issue advancing it. Ask whether to plan work, defer the objective, or amend it. | -| `contradiction` | high | An open issue violates a Non-Goal. Resolution requires dropping the issue or amending the Non-Goal through `backlog-charter` amend. | +| `contradiction` | high | An open issue violates a Non-Goal. Resolution requires dropping the issue or amending the Non-Goal through `spec-charter` amend. | Contradictions are highest severity because they mean execution is crossing an explicit boundary. @@ -37,4 +37,4 @@ Use the first count for open issues that map to at least one objective. Mention ## Proposed CHARTER Changes -When findings suggest the charter may need to evolve, format proposals as a seed for `backlog-charter` amend. The triage or planning report proposes only; `backlog-charter` owns gated mutation of `CHARTER.md`. +When findings suggest the charter may need to evolve, format proposals as a seed for `spec-charter` amend. The triage or planning report proposes only; `spec-charter` owns gated mutation of `CHARTER.md`. diff --git a/skills/backlog-charter/references/amendment.md b/skills/spec-charter/references/amendment.md similarity index 91% rename from skills/backlog-charter/references/amendment.md rename to skills/spec-charter/references/amendment.md index f345236..1d9e96d 100644 --- a/skills/backlog-charter/references/amendment.md +++ b/skills/spec-charter/references/amendment.md @@ -1,6 +1,6 @@ # Charter Amendment Guidance -Use this reference in `backlog-charter` amend mode after re-reading the current repo-root `CHARTER.md`. The default bias is stability: no change unless concrete evidence shows the charter is stale, weak, or newly validated. +Use this reference in `spec-charter` amend mode after re-reading the current repo-root `CHARTER.md`. The default bias is stability: no change unless concrete evidence shows the charter is stale, weak, or newly validated. ## Tier 1 Challenge Checklist diff --git a/skills/backlog-charter/references/create.md b/skills/spec-charter/references/create.md similarity index 94% rename from skills/backlog-charter/references/create.md rename to skills/spec-charter/references/create.md index c1de348..c1c355e 100644 --- a/skills/backlog-charter/references/create.md +++ b/skills/spec-charter/references/create.md @@ -1,6 +1,6 @@ # Charter Create Mode: Signals, Interview, Seed Decisions -Use this reference in `backlog-charter` create mode after confirming no repo-root `CHARTER.md` exists. The goal is a defensible first revision that survives its own proof gate — not a perfect axis on day one. Stability comes from amend mode; create mode just has to set a credible starting point. +Use this reference in `spec-charter` create mode after confirming no repo-root `CHARTER.md` exists. The goal is a defensible first revision that survives its own proof gate — not a perfect axis on day one. Stability comes from amend mode; create mode just has to set a credible starting point. ## 1. Signal Collection (Priority + Conflict) diff --git a/skills/backlog-charter/references/objectives.md b/skills/spec-charter/references/objectives.md similarity index 93% rename from skills/backlog-charter/references/objectives.md rename to skills/spec-charter/references/objectives.md index 701de3c..705cf78 100644 --- a/skills/backlog-charter/references/objectives.md +++ b/skills/spec-charter/references/objectives.md @@ -1,6 +1,6 @@ # Objective Predicates: Good vs. Bad -Use this reference in `backlog-charter` create mode (or amend, when adding objectives) to write Tier 2 entries that survive their own proof gate. An Objective is a **verifiable predicate** — a statement that can be checked true or false against the world, not a task to do or an aspiration to feel good about. +Use this reference in `spec-charter` create mode (or amend, when adding objectives) to write Tier 2 entries that survive their own proof gate. An Objective is a **verifiable predicate** — a statement that can be checked true or false against the world, not a task to do or an aspiration to feel good about. The shape: diff --git a/skills/backlog-charter/references/reassess.md b/skills/spec-charter/references/reassess.md similarity index 86% rename from skills/backlog-charter/references/reassess.md rename to skills/spec-charter/references/reassess.md index bcc5f3c..713c67e 100644 --- a/skills/backlog-charter/references/reassess.md +++ b/skills/spec-charter/references/reassess.md @@ -1,6 +1,6 @@ # Reassess-Mode Heuristics -Use this reference in `backlog-charter reassess` after reading the Reassess Mode section in `SKILL.md`. The mode is a report-only stale-spec review. It helps the user decide whether to run `backlog-charter amend`, `backlog-charter grill `, or a separate user-approved Learning Action. +Use this reference in `spec-charter reassess` after reading the Reassess Mode section in `SKILL.md`. The mode is a report-only stale-spec review. It helps the user decide whether to run `spec-charter amend`, `spec-grill `, or a separate user-approved Learning Action. ## Policy Ownership @@ -57,10 +57,10 @@ Use this structure unless the user asks for a shorter answer: - ### Grill Candidates -- — evidence: ; suspected change: ; next: `backlog-charter grill ` +- — evidence: ; suspected change: ; next: `spec-grill ` ### Amend Candidates -- — evidence: ; suspected change: ; next: `backlog-charter amend` +- — evidence: ; suspected change: ; next: `spec-charter amend` ### Learning Actions - Keep inline: @@ -84,7 +84,7 @@ Recommend no change when Learnings are sparse, recent, non-repetitive, and do no ### Grill Candidate -Recommend `backlog-charter grill ` when any of these are true: +Recommend `spec-grill ` when any of these are true: - repeated Learnings show a new durable behavior or constraint - current Behaviors are too weak to explain how recent work succeeded @@ -96,7 +96,7 @@ Do not rewrite the capability during reassess. Name the block and the suspected ### Amend Candidate -Recommend `backlog-charter amend` when evidence affects project-wide direction: +Recommend `spec-charter amend` when evidence affects project-wide direction: - a repeated Learning changes multiple capabilities - an Objective appears validated or deferred but lacks proof @@ -121,8 +121,8 @@ Archive older Learnings when they are useful history but no longer startup conte - **Semantic overreach:** deterministic counts are treated as proof of stale content. Fix by labeling counts as signals, not conclusions. - **Silent self-editing:** reassess edits Goal/Scope/Behaviors while diagnosing. Fix by routing through amend/grill. - **Unbounded scan:** the agent reads the whole repo and invents drift. Fix by starting from scripts and a bounded sprint window. -- **Name confusion:** `spec-grill` or `spec-reassess` is described as callable before it exists. Fix by calling them reserved/non-callable future names. +- **Name confusion:** `spec-reassess` is described as callable before it exists. Fix by calling it a reserved/non-callable future name. ## Reserved Names -Naming policy lives in `docs/spec-system-design.md`. Summary: today the callable skill is `backlog-charter`. The names `spec-grill`, `spec-reassess`, and `spec-learn` are reserved/non-callable future split candidates. Mention them only when discussing naming policy or split triggers, not as commands the user can run. +Naming policy lives in `docs/spec-system-design.md`. Summary: today the callable spec-series skills are `spec-charter` and `spec-grill`. The names `spec-reassess` and `spec-learn` are reserved/non-callable future split candidates. Mention them only when discussing naming policy or split triggers, not as commands the user can run. diff --git a/skills/backlog-charter/scripts/check-size.js b/skills/spec-charter/scripts/check-size.js similarity index 100% rename from skills/backlog-charter/scripts/check-size.js rename to skills/spec-charter/scripts/check-size.js diff --git a/skills/backlog-charter/scripts/check-size.test.js b/skills/spec-charter/scripts/check-size.test.js similarity index 100% rename from skills/backlog-charter/scripts/check-size.test.js rename to skills/spec-charter/scripts/check-size.test.js diff --git a/skills/backlog-charter/templates/charter.md b/skills/spec-charter/templates/charter.md similarity index 100% rename from skills/backlog-charter/templates/charter.md rename to skills/spec-charter/templates/charter.md diff --git a/skills/spec-grill/SKILL.md b/skills/spec-grill/SKILL.md new file mode 100644 index 0000000..17bdc37 --- /dev/null +++ b/skills/spec-grill/SKILL.md @@ -0,0 +1,107 @@ +--- +name: spec-grill +argument-hint: "[capability-slug]" +description: "Create or refine spec/capabilities.md by grilling existing repo signals into capability contracts, Behaviors, and Hard Constraints. Use after spec-charter on existing repos, or when users ask for capability specs, component contracts, middle-layer specs, repo capability boundaries, 능력 명세, or grill." +compatibility: Requires git. Works on Claude Code and Codex. +metadata: + related-skills: "spec-charter, dev-backlog, backlog-triage" +--- + +# Spec Grill + +Author `spec/capabilities.md`, the middle layer between `CHARTER.md` and the active sprint. `spec-grill` is not a file generator; it pressure-tests existing repo signals into durable capability contracts. + +Use this after `spec-charter create` on existing/brownfield repos, or whenever the user asks to define capability boundaries, component contracts, Behaviors, or Hard Constraints. + +## Execution Contract + +### Invocation + +- `spec-grill`: greenfield or brownfield capability-spec creation. If `spec/capabilities.md` does not exist, create it from `templates/capabilities.md`, then interview one capability at a time. +- `spec-grill `: refine exactly one existing capability block. If the file is absent, fall back to greenfield mode and surface the absence. + +Capability slugs are strict routing handles used by sprint `component:` frontmatter. Keep them lowercase and singular, then put nuance in Goal/Scope prose. + +### Helper Scripts + +Resolve helper scripts from the installed `spec-grill` skill directory, not from the target repo. In a source checkout, that means the local `scripts/` directory beside this `SKILL.md`. Always pass the target repo explicitly (`--repo-root `) so helpers do not inspect the skill directory by accident. + +On a brownfield repo with no `spec/capabilities.md`, run `extract-signals.js --repo-root --json` first. The script reports raw capability signals with draft Goal + draft Scope. It never writes `spec/capabilities.md`; admission, merging, splitting, and naming belong to this skill. + +### Completion Contract + +End every run with a short summary: + +- capability blocks created or edited +- predicates rejected or rewritten +- constraints added +- raw candidates merged/split/refused +- follow-up Learning Actions if any + +## Brownfield Signal Rules + +`extract-signals.js` draws from README, `CHARTER.md`, `CLAUDE.md`/`AGENTS.md`, top-level source dirs, and recent commit messages. + +Use the draft as interview seed only. The script labels signal authority: + +- README/CHARTER/issues are product authority. +- source directories are repo-structure evidence. +- commit scopes are history. +- `CLAUDE.md`/`AGENTS.md` are development-harness context. + +Harness context can seed questions about conventions and workflow, but it must not create accepted capability boundaries by itself. The script clusters by code organization, while real capabilities are functional contracts; expect grill mode to merge, split, or regroup raw signals rather than adopt them verbatim. + +## File Shape + +`spec/capabilities.md` lives at the target repo root in `spec/`. 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. + +The file's mutation discipline: + +- Goal / In-scope / Out-of-scope: human-gated through this skill. +- Expected Behaviors / Hard Constraints: human-gated and must pass the 3-axis predicate test. +- `## Learnings`: not an interview target; appended only by the bounded Learnings writer between magic markers. +- `## Decisions`: append-only by convention; promote cross-cutting decisions to `CHARTER.md` through `spec-charter amend`. + +## Capability Admission Test + +Before interviewing a candidate capability, decide whether it deserves to exist. Raw extraction signals are not accepted specs. + +Admit a capability only when most of these are true: + +- It is a repeated decision boundary, not just a directory name or commit scope. +- It owns a primary relay-learning destination. +- Its Goal can be stated as an observable user or operator outcome. +- Its Behaviors and Hard Constraints differ meaningfully from neighboring candidates. +- If two candidates share nearly all predicates, merge them. +- If one candidate needs more than five Behaviors to feel complete, split it along the contract boundary the extra Behaviors describe. + +Use this as a bloat check before the per-capability flow. A large feature-first app may have many feature folders but only 5-10 durable capability contracts. + +## Per-Capability Interview Flow + +For each capability, walk the user through this order; do not skip ahead: + +1. **Goal** — one sentence: what the user can observe when this works. Diagnosis-side framing belongs in CHARTER; capability Goal is the observable outcome. +2. **In-scope / Out-of-scope** — what this capability owns, and the boundary it deliberately respects. Out-of-scope prevents creep. +3. **Expected Behaviors** — three verifiable predicates. Each one must pass the 3-axis test below. Reject and rewrite until it does. +4. **Hard Constraints** — two bright-lines this capability never crosses, even if asked. Adversarial-Goodhart defenses live here. + +Stop at three Behaviors and two Hard Constraints per capability on the first pass; more is bloat and harder to keep falsifiable. Add later via rerun. + +## The 3-Axis Predicate Test + +Every Behavior and Hard Constraint must pass all three axes before it is committed: + +1. **Authority axis.** Would the user be unhappy if an agent satisfied this measurably but in a way that ignored their intent? If yes, encode the missing intent as a sharper Behavior or promote it to a Hard Constraint. +2. **Distributional axis.** Does this predicate hold in unseen code areas or unseen workloads? If no, restate it as environment-independent or scope it to the conditions where it holds. +3. **Manipulability axis.** Can an agent satisfy this by editing the measurement channel rather than the system? If yes, add a structural restriction outside the spec, not just sharper prose. + +A predicate that passes all three is committable. A predicate that fails any axis is rewritten or split, never rubber-stamped. + +## Writing Rules + +On first run, copy `templates/capabilities.md` to `spec/capabilities.md` at the repo root, then walk the interview for one capability. On rerun, edit only the named capability block and leave the rest of the file untouched. + +After applying an accepted change, do not bump a revision number on `spec/capabilities.md`; `git blame` is the source of truth. Note in the conversation which capability was edited. + +See `references/capabilities.md` for additional grill heuristics and [`../spec-charter/SKILL.md`](../spec-charter/SKILL.md) for the project-wide CHARTER layer. diff --git a/skills/backlog-charter/references/capabilities.md b/skills/spec-grill/references/capabilities.md similarity index 95% rename from skills/backlog-charter/references/capabilities.md rename to skills/spec-grill/references/capabilities.md index 5cc7137..662f0c9 100644 --- a/skills/backlog-charter/references/capabilities.md +++ b/skills/spec-grill/references/capabilities.md @@ -1,6 +1,6 @@ # Grill-Mode Heuristics for `spec/capabilities.md` -Use this reference in `backlog-charter` grill mode after walking the per-capability interview flow in `SKILL.md`. The flow, 3-axis predicate test, and tier gates live in `SKILL.md`; this file captures concrete dogfood patterns so future grill sessions do not relearn them. +Use this reference in `spec-grill` after walking the per-capability interview flow in `SKILL.md`. The flow, 3-axis predicate test, and tier gates live in `SKILL.md`; this file captures concrete dogfood patterns so future grill sessions do not relearn them. ## Naming: Slug Handle vs. Prose Contract @@ -95,7 +95,7 @@ Fix: scope the claim to draft seeding. ## Rerun Protocol -`backlog-charter grill ` may touch: +`spec-grill ` may touch: - `Goal` - `In-scope` diff --git a/skills/backlog-charter/references/spec-system-research.md b/skills/spec-grill/references/spec-system-research.md similarity index 100% rename from skills/backlog-charter/references/spec-system-research.md rename to skills/spec-grill/references/spec-system-research.md diff --git a/skills/backlog-charter/scripts/extract-signals.js b/skills/spec-grill/scripts/extract-signals.js similarity index 98% rename from skills/backlog-charter/scripts/extract-signals.js rename to skills/spec-grill/scripts/extract-signals.js index e02d5a7..0f9ea8d 100644 --- a/skills/backlog-charter/scripts/extract-signals.js +++ b/skills/spec-grill/scripts/extract-signals.js @@ -342,7 +342,7 @@ function formatHumanReport(result) { lines.push(` ... and ${capabilities.length - SUMMARY_DIR_LIMIT} more (use --json for full draft)`); } lines.push(""); - lines.push("Next: invoke `backlog-charter grill` to admit raw signals and interview compact capabilities into spec/capabilities.md."); + lines.push("Next: invoke `spec-grill` to admit raw signals and interview compact capabilities into spec/capabilities.md."); return lines.join("\n"); } diff --git a/skills/backlog-charter/scripts/extract-signals.test.js b/skills/spec-grill/scripts/extract-signals.test.js similarity index 100% rename from skills/backlog-charter/scripts/extract-signals.test.js rename to skills/spec-grill/scripts/extract-signals.test.js diff --git a/skills/backlog-charter/templates/capabilities.md b/skills/spec-grill/templates/capabilities.md similarity index 94% rename from skills/backlog-charter/templates/capabilities.md rename to skills/spec-grill/templates/capabilities.md index b7477fd..1e13d74 100644 --- a/skills/backlog-charter/templates/capabilities.md +++ b/skills/spec-grill/templates/capabilities.md @@ -8,7 +8,7 @@ Mutation discipline (matches the design doc): | Section | Who writes | When | Gate | |---|---|---|---| -| `Goal`, `In-scope`, `Out-of-scope` | human via `backlog-charter grill` | when the contract changes | challenge + confirm + apply | +| `Goal`, `In-scope`, `Out-of-scope` | human via `spec-grill` | when the contract changes | challenge + confirm + apply | | `Expected Behaviors`, `Hard Constraints` | human via grill | when a behavior or bright-line changes | grill + 3-axis predicate test | | `## Learnings` (between magic markers) | `append-learnings.js` only | end of every successful relay run tagged with this primary capability slug | structurally bounded append; rejects writes outside markers | | `## Decisions` | human, append-only | when a capability-level decision is made | append-only by convention; promote to CHARTER if cross-cutting | diff --git a/spec/capabilities.md b/spec/capabilities.md index 0b4c4e4..3333e9c 100644 --- a/spec/capabilities.md +++ b/spec/capabilities.md @@ -2,7 +2,7 @@ The middle layer between [`CHARTER.md`](../CHARTER.md) and the active sprint. Each block describes one subsystem-worth of work with a frozen-ish contract and a structurally bounded live-feedback channel. -Mutation discipline matches [`docs/spec-system-design.md`](../docs/spec-system-design.md): Goal/Scope/Behaviors/HardConstraints are human-gated via `backlog-charter grill`; `## Learnings` is appended only by a bounded `append-learnings` writer between magic markers; `## Decisions` is append-only by convention. +Mutation discipline matches [`docs/spec-system-design.md`](../docs/spec-system-design.md): Goal/Scope/Behaviors/HardConstraints are human-gated via `spec-grill`; `## Learnings` is appended only by a bounded `append-learnings` writer between magic markers; `## Decisions` is append-only by convention. Capability headings are strict routing handles. Use one lowercase slug after `## Capability:` and point sprint `component:` frontmatter at exactly one of those slugs. Put secondary touches in sprint prose, not in frontmatter. @@ -75,18 +75,18 @@ Capability headings are strict routing handles. Use one lowercase slug after `## --- -## Capability: charter-management +## Capability: spec-charter -**Goal:** A user creates or amends `CHARTER.md` through tier-gated discipline (no rubber-stamp) and the file stays a 5-minute read. +**Goal:** A user creates, amends, or reassesses `CHARTER.md` through tier-gated discipline, and the file stays a 5-minute read. **In-scope:** -- `backlog-charter` create + amend modes +- `spec-charter` create + amend + reassess modes - Three-tier discipline (Direction / Predicates / History) and the proof gate for Objective status advances - `check-size.js` budget enforcement after every amend -- `grill` mode is in this capability's scope as the authoring path for the middle layer (`spec/capabilities.md`) +- Brownfield handoff guidance to `spec-grill` after initial CHARTER creation **Out-of-scope:** -- Per-capability content of `spec/capabilities.md` (that lives in this file, not in `backlog-charter`) +- Authoring per-capability contracts in `spec/capabilities.md` (`spec-grill` capability) - Charter deletion — no supported path - Reading `CHARTER.md` from sibling skills (each does it directly; this capability does not gate reads) @@ -108,6 +108,42 @@ Capability headings are strict routing handles. Use one lowercase slug after `## | --- | --- | --- | --- | | 2026-05-22 | CHARTER is a separate file at repo root, not merged into `_context.md` | Yardstick must stay <5-min; HOW-knowledge would dilute it | — | | 2026-05-22 | `backlog-charter` is a third sibling skill, not folded into `dev-backlog` | Different concern (axis lifecycle vs. execution) | — | +| 2026-05-29 | `backlog-charter` is renamed to `spec-charter` for CHARTER lifecycle work | The artifact is a project spec axis, not a backlog-only helper | 2026-05-22 | + +--- + +## Capability: spec-grill + +**Goal:** A user turns existing repo signals into compact `spec/capabilities.md` capability contracts instead of stopping at a project-wide CHARTER. + +**In-scope:** +- `spec-grill` greenfield and brownfield capability authoring +- `extract-signals.js` raw candidate seeding from README, CHARTER, source roots, harness files, and commit scopes +- Capability admission, Goal/Scope interview, Expected Behaviors, and Hard Constraints +- `templates/capabilities.md` and `references/capabilities.md` + +**Out-of-scope:** +- Mutating `CHARTER.md` direction or Objectives (`spec-charter` capability) +- Appending runtime Learnings after relay runs (bounded writer contract outside grill) +- Treating directory names or commit scopes as accepted capabilities without interview admission + +### Expected Behaviors +- On brownfield repos without `spec/capabilities.md`, `extract-signals.js --repo-root --json` emits deterministic raw candidates and labels signal authority before any contract is accepted. +- `spec-grill ` edits only the named capability block and leaves other capability blocks, Learnings, and Decisions untouched. +- Every accepted Behavior and Hard Constraint passes the authority, distributional, and manipulability axes before it is committed. + +### Hard Constraints +- Never write a capability solely because a same-named directory or commit scope exists; raw signals require admission, merge, split, or refusal. +- Never edit `### Learnings` between magic markers during grill; Learnings cleanup is a separate user-approved Learning Action. + +### Learnings + + + +### Decisions +| date | decision | rationale | supersedes | +| --- | --- | --- | --- | +| 2026-05-29 | Capability authoring moves from hidden `backlog-charter grill` mode to `spec-grill` | Existing-repo users need a discoverable second step after `spec-charter create` | — | --- From 77cfe0fdfa296e455ab170a88826ea320ffe1405 Mon Sep 17 00:00:00 2001 From: SJ Lee Date: Fri, 29 May 2026 21:13:26 +0900 Subject: [PATCH 2/2] docs: align spec-series capability references --- docs/spec-system-design.md | 6 +++--- skills/dev-backlog/references/integration-contract.md | 2 +- skills/spec-grill/references/capabilities.md | 9 +++++---- 3 files changed, 9 insertions(+), 8 deletions(-) diff --git a/docs/spec-system-design.md b/docs/spec-system-design.md index ff24fcd..af31572 100644 --- a/docs/spec-system-design.md +++ b/docs/spec-system-design.md @@ -149,7 +149,7 @@ The names `spec-reassess` and `spec-learn` are reserved/non-callable future spli One `spec/capabilities.md` is the default because it is easy to read, grep, and hand to an agent in one shot. The budget is about scanability, not feature count: target 5-10 capabilities, warn above 12 capabilities or 400 lines, and split only when the file exceeds 500 lines, has more than 15 capabilities, or ownership boundaries demand separate review paths. -Dogfood calibrated this rule. dev-backlog has only five capabilities and already produces a 177-line spec. tamgu_note, a larger Flutter/Firebase app, has 15+ feature surfaces plus workflow scopes like `e2e`, `test`, `sprint`, and `backlog`; treating every folder or commit scope as a capability would exceed the split trigger immediately. Capabilities are durable contract boundaries, not directory names. +Dogfood calibrated this rule. dev-backlog has six capabilities and produces a 214-line spec. tamgu_note, a larger Flutter/Firebase app, has 15+ feature surfaces plus workflow scopes like `e2e`, `test`, `sprint`, and `backlog`; treating every folder or commit scope as a capability would exceed the split trigger immediately. Capabilities are durable contract boundaries, not directory names. When the hard trigger fires, `split-capabilities.js` migrates to `spec/components/.md`. Until then, keep the compact single-file shape. Make-the-change-easy, then make the easy change (Beck). @@ -304,8 +304,8 @@ Manual reassess evidence was checked before adding a new seed script: | Repo | Command | Result | Reassess implication | |---|---|---|---| -| dev-backlog | `node skills/dev-backlog/scripts/capabilities-doctor.js --json` | 5 capabilities, 178 lines, 0 warnings, 0 hard failures | compactness and Learnings marker evidence is sufficient for a no-change structural finding | -| dev-backlog | `node skills/dev-backlog/scripts/component-lint.js --json` | 5 declared capabilities, 0 sprint files, 0 issues | routing evidence is sufficient; no sprint data means no usage-frequency inference | +| dev-backlog | `node skills/dev-backlog/scripts/capabilities-doctor.js --json` | 6 capabilities, 214 lines, 0 warnings, 0 hard failures | compactness and Learnings marker evidence is sufficient for a no-change structural finding | +| dev-backlog | `node skills/dev-backlog/scripts/component-lint.js --json` | 6 declared capabilities, 0 sprint files, 0 issues | routing evidence is sufficient; no sprint data means no usage-frequency inference | | tamgu_note | `node /scripts/capabilities-doctor.js --capabilities spec/capabilities.md --json` | 7 capabilities, 232 lines, 0 warnings, 0 hard failures | large-repo-shaped spec remains within budget | | tamgu_note | `node /scripts/component-lint.js --sprints-dir backlog/sprints --capabilities spec/capabilities.md --json` | 19 sprint files, 0 component issues | routing evidence is sufficient on a larger real repo shape | diff --git a/skills/dev-backlog/references/integration-contract.md b/skills/dev-backlog/references/integration-contract.md index 92a4218..189ba53 100644 --- a/skills/dev-backlog/references/integration-contract.md +++ b/skills/dev-backlog/references/integration-contract.md @@ -37,7 +37,7 @@ Extraction: read lines between the matched `## ` heading and the next `## ` head The optional `component:` field is one primary routing handle into `spec/capabilities.md`. ```yaml -component: "charter-management" +component: "spec-charter" ``` Rules: diff --git a/skills/spec-grill/references/capabilities.md b/skills/spec-grill/references/capabilities.md index 662f0c9..6ce8247 100644 --- a/skills/spec-grill/references/capabilities.md +++ b/skills/spec-grill/references/capabilities.md @@ -20,11 +20,11 @@ Do not use a sentence or comma-separated name: If the work touches several areas, keep the primary slug in sprint frontmatter and put the nuance in prose: ```yaml -component: "charter-management" +component: "spec-charter" ``` ```md -Touches: charter-management primarily; also affects backlog-sync docs. +Touches: spec-charter primarily; also affects backlog-sync docs. ``` Bias: the slug is the address; Goal/Scope text is the explanation. @@ -138,11 +138,12 @@ If two candidates share every meaningful Behavior and Hard Constraint, merge the ### dev-backlog example -dev-backlog has three skill directories, but five capabilities: +dev-backlog has four skill directories, but six capabilities: - `sprint-execution` owns the active sprint as the execution hub. - `backlog-sync` owns the GitHub Issues to task-file mirror. -- `charter-management` owns CHARTER and capability-spec tier gates. +- `spec-charter` owns CHARTER lifecycle and report-only reassess. +- `spec-grill` owns `spec/capabilities.md` authoring and capability-contract pressure tests. - `triage-grooming` owns backlog classification and relationship reports. - `task-progress-reporting` owns monthly progress issue synchronization.