| name | spec-charter |
| argument-hint | [create|amend|reassess] |
| description | Create, amend, or reassess spec/charter.md. Use for project direction, Objectives, Non-Goals, Decisions, stale spec findings, 기준, 헌장, 방향성, or spec axis. |
| disable-model-invocation | true |
| compatibility | Requires git. |
| metadata | {"related-skills":"spec-system-map, spec-grill, dev-backlog, backlog-triage"} |
spec-charter
Create and amend spec/charter.md, the opt-in project reference axis used to measure ongoing execution (e.g. backlog items, sprint plans) and drift. This skill is rerunnable.
spec/charter.md is the first layer, not the whole large-repo spec. On existing/brownfield repos, finish create mode by recommending spec-system-map for spec/system-map.md and spec-grill for 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 neither spec/charter.md nor legacy root CHARTER.md exists, unless the user explicitly asks to replace it. |
| Update direction, objectives, decisions, or accepted charter wording | amend | Applies tier gates and may edit the resolved charter 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: prefer spec/charter.md; fall back to legacy root CHARTER.md; if neither exists, use create mode. If the user asks for capability contracts, component boundaries, or spec/capabilities.md, route to spec-grill.
Helper scripts
Do not rely on bundled helper scripts for charter work. Inspect the target repo directly and keep all paths target-repo-relative so the skill never analyzes its own installation directory by accident.
Completion contract
End every mode with a short summary:
create: created files, unresolved assumptions, and a concrete next natural-language action. On brownfield repos, create spec/system-map.md first when absent; recommend spec-grill only when capability candidates are evidence-backed.amend: accepted changes, refused/parked changes, proof cited for status advances, and a charter length check (report the line count; flag when the charter exceeds a ~5-minute read, roughly 150 lines).reassess: required report sections from the Reassess mode dispatch contract, with one recommended next natural-language action.
When recommending follow-up spec work, do not require users to memorize downstream arguments such as map, fill, or audit. Prefer plain actions like "create the system map" or "ask spec-grill to review candidate capability boundaries." Include 2-5 candidate boundary names only when they are supported by evidence from README, spec/system-map.md, scripts, tests, docs, or recent commit scopes.
What spec/charter.md is
spec/charter.md lives in the target repo's project spec directory. 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. See references/spec-axis.md for the legacy root CHARTER.md fallback and migration policy. 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 |
|---|
spec/charter.md | What good looks like / why (the yardstick) |
spec/system-map.md | How the project is shaped at the system level (boundaries, flows, invariants, pointers) |
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 to validated requires proof. Deferral requires a cited parking or scope-change rationale. 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 neither spec/charter.md nor legacy root CHARTER.md exists, or when invoked as spec-charter create and no charter exists.
- 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.
- 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. If the user asked for autonomous progress and repo evidence is strong enough, non-interactive create mode may draft without blocking on interview; mark inferred claims and Objectives with src: inferred, list unresolved assumptions, and recommend spec-charter amend for later human correction.
- Create
spec/ if needed, then write spec/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.
- If the target repo is brownfield, use the create-mode completion contract to choose the next spec-axis action. 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<n> IDs for traceability.
- Never reuse a removed objective ID; new objectives take the next free number.
- Record provenance with
src: (user, inferred, or execution).
Language conventions:
- Default to the language signaled by README, AGENTS/CLAUDE, and the user's request.
- Prefer the repo ecosystem language when it improves maintainability or matches existing docs.
- Keep structural labels and XML-style tags in English when cross-agent parsing matters.
See references/objectives.md for worked examples, rewrite patterns, and a 30-second predicate test.
Amend mode
Use amend mode when spec/charter.md exists, legacy root CHARTER.md exists, or when invoked as spec-charter amend.
First re-read spec/charter.md. If it is absent but root CHARTER.md exists, apply the legacy fallback and migration policy in references/spec-axis.md: read the legacy file, state that the canonical path is now spec/charter.md, and recommend migrating before or during the accepted amendment. 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; cite a merged PR, passing check, or a recorded agent run whose Done Criteria match the predicate. For active -> deferred, require a cited parking or scope-change rationale. Without the required evidence or rationale, 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. Re-read the result and protect the ~5-minute-read property by collapsing long deferred lists, oversized Decisions rationale, or operational HOW-knowledge.
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 spec/charter.md, spec/system-map.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-system-map amend, spec-grill <capability>, or a separate user-approved Learning Action.
If reassess finds that spec/system-map.md is missing on a brownfield repo, recommend creating the system map before capability grilling. If spec/system-map.md exists and spec/capabilities.md is missing or thin, recommend asking spec-grill to review the candidate capability boundaries. Name concrete candidates only when evidence supports them; otherwise say which evidence is missing.
Dispatch contract:
- Start with bounded file evidence: named charter, system-map, or capability sections, recent execution logs (e.g. an active sprint file) when present, and at most the latest five completed execution logs.
- Use repo-local helper scripts such as
capabilities-doctor.js --json or component-lint.js --json only when they are present in the target repo. If unavailable, list them under Missing Evidence and continue with bounded file reads.
- Sizing rule: default to a quick reassess when the user asks a narrow staleness question about one file or section — emit only Evidence, No Change, Recommended Next Step. Reserve the full reassess report — Evidence, No Change, System Map Candidates, Grill Candidates, Amend Candidates, Learning Actions, Missing Evidence, Recommended Next Step — for periodic health checks, multi-file drift review, or when the user explicitly asks for the full report. A quick-reassess finding that would need a trimmed section gets one line under Recommended Next Step pointing to a full reassess instead. Reassess discipline applies in full at every size: quick reassess is still report-only (never edits) and still routes accepted fixes through
spec-charter amend, spec-system-map amend, or spec-grill; it only trims what gets written down.
- Use
references/reassess.md as the source of truth for evidence order, report shape, recommendation rules, Learning Actions, and stale-spec failure modes.
Verification prompts
Use these as quick pressure tests when changing this skill or a generated charter:
- "Create a charter for a repo with no README and a vague objective list." Expected: interview until Problem/Approach/Non-Goals are concrete; refuse to accept objectives that aren't verifiable predicates.
- "Mark this objective validated because the team believes it's done." Expected: refuse the status advance without a cited merged PR, passing check, or recorded agent run; keep it
active.
- "Add a Non-Goal that's really just an unstated risk." Expected: sharpen it into a concrete boundary statement, or push back that it isn't a non-goal.
- "Edit a past Decisions row to fix a typo in the rationale." Expected: refuse; append a new row instead, since Decisions are append-only.
- "This charter hasn't been amended in a year — is it stale?" Expected: route to reassess mode rather than silently rewriting Tier 1 content.
- "Skip the interview and draft objectives non-interactively from repo signals." Expected: allowed only when the user asked for autonomous progress; mark objectives
src: inferred and list unresolved assumptions.
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, sizing gate, output shape, Learning Actions, and failure modes.references/spec-axis.md — spec-axis file boundaries, ownership, and the legacy root CHARTER.md fallback policy.../spec-system-map/SKILL.md — companion skill for authoring spec/system-map.md.../spec-grill/SKILL.md — companion skill for authoring spec/capabilities.md.../spec-grill/references/spec-pipeline-ready.md — final checklist for landing the full spec axis.
