| name | agile:rules:constitution |
| description | Authoring tool for the GSB Federated Constitution Architecture (master + common/services/workers/frontend domain constitutions in .agile/rules/). Creates new domain constitutions, adds/removes/redefines principles, refines wording, validates compliance, compares domains, detects drift, and reconciles the registry. Orchestrates a six-agent expert team (researcher, investigator, thinker, grounder, critic, reviewer) so no constitutional change ships without multi-perspective review. Use this skill whenever the user wants to create, update, refine, enhance, validate, list, compare, detect, or sync a constitution; whenever they mention "constitution", "principle", "MASTER:", "WORKER:", "SERVICES:", "FRONTEND:", "COMMON:", "EPIC:", "amendment", "ratify", "governance", "policy", or "guardrail" in the context of the .agile/rules/ corpus; whenever they ask to add or change project-wide standards/policies/regulations; or whenever they want to bump a constitution version. Also use proactively after any change that affects the inheritance chain (e.g., domain constitutions still pointing at a stale master version). |
| user-invocable | true |
| disable-model-invocation | false |
| allowed-tools | Read, Edit, Write, Glob, Grep, Bash, Agent, Skill, TaskCreate, TaskList, TaskGet, TaskUpdate, AskUserQuestion, SlashCommand |
Agile Rules Constitution
Authoring and governance tool for the GSB Federated Constitution Architecture.
This skill is the complement to agile-constitution-check — that skill is the
non-user-invocable compliance gate; this one is the user-invocable authoring tool.
Together they form the read/write halves of the constitution system: check reads,
constitution authors. Updates happen here; enforcement happens there.
Federation Architecture
.agile/rules/
├── constitution.md # MASTER (MASTER:I…, EPIC:I-III)
├── index.md # Registry (versions, principle counts, ratification dates)
├── common/constitution.md # COMMON:I-XIII inherits master
├── services/constitution.md # SERVICES:I-XVIII inherits master
├── workers/constitution.md # WORKER:I-XII inherits master
└── frontend/constitution.md # FRONTEND:I-IX inherits master
Precedence: Master > Domain > Feature spec > Code.
Sub-Commands
| Command | Effect | Version bump | Agents |
|---|
create --domain <new> | New domain constitution | initial 1.0.0 | all six |
update --domain <d> | Add / remove / redefine principle | MAJOR or MINOR | all six |
enhance --domain <d> | Expand existing principle | MINOR | all six |
refine --domain <d> | Wording / typo fix | PATCH | researcher + critic + reviewer |
validate [--domain <d>] | Compliance check (read-only) | none | reviewer |
list | Registry display (read-only) | none | none |
compare <d1> <d2> | Principle diff (read-only) | none | researcher |
detect [path] | Domain detection (read-only) | none | none |
sync | Reconcile drift across files + index + inheritance | none | investigator + reviewer |
For a deeper reference of each command, see references/command-reference.md.
Six-Agent Expert Team
Authoring commands dispatch the team via the Agent tool, using the prompt
templates in agents/. Each agent has one job; together they form a
defense-in-depth review.
| Agent | File | Role | Stops the change? |
|---|
| Researcher | agents/researcher.md | Reads current state | No |
| Investigator | agents/investigator.md | Maps blast radius (every file that references the change) | No, but feeds others |
| Thinker | agents/thinker.md | Drafts principle text + version bump | Proposes only |
| Grounder | agents/grounder.md | Verifies legitimacy (authority, precedence, inheritance) | YES — BLOCKED halts |
| Critic | agents/critic.md | Adversarial review (vague language, edge cases, missing rationale) | YES — REJECT halts |
| Reviewer | agents/reviewer.md | Final gate (versioning, frontmatter, SIR, propagation) | YES — FAIL halts |
If any of grounder/critic/reviewer halts, no file is written. The skill
reports blockers to the user and exits cleanly. Re-dispatching the thinker is
allowed; the team re-runs against the revised proposal.
User Input
$ARGUMENTS
You MUST parse the user's command from $ARGUMENTS before proceeding. The
first token is the sub-command; subsequent tokens are flags and values.
Hard Gates
These cannot be bypassed:
- Reviewer veto: If the reviewer issues
FAIL, no file is written.
- Master amendment acknowledgement:
update --domain master must capture
an explicit user acknowledgement (via AskUserQuestion) before dispatching
the team. Skipping this is a grounder BLOCKED finding.
- Lockstep ripple: Master amendments must update inheritance refs in all
four domain constitutions in the same change set.
- Sync Impact Report: Every command that writes a constitution prepends a
Sync Impact Report (per
templates/sync-impact-report-template.md).
- Anti-pattern coverage: Removing a principle that an anti-pattern cites
in
.claude/rules/anti-patterns/gsb-lessons-learned.md requires updating
the catalog in the same change set.
Phase Flow
Phase 1 — Parse and Pre-flight
- Parse
$ARGUMENTS into <sub-command> and flags. If unrecognized, print
the sub-commands table and exit.
- For commands that take
--domain, validate the domain name against the
registry. For create, validate it is not yet registered.
- Run
scripts/constitution-detect.sh --json <pwd> to capture the working
context. Useful for inferring which constitution is being edited when the
user is sloppy with --domain.
- Run
scripts/registry-sync.sh --json to load current versions, principle
counts, ratification dates. Cache the result for downstream agents.
Phase 2 — Authoring Path Selection
Based on the sub-command, choose the path:
- list, detect, compare — produce read-only output, no team needed.
- validate — dispatch reviewer only.
- refine — dispatch researcher + critic + reviewer.
- create, update, enhance — full team.
- sync — investigator + reviewer.
Phase 3 — Master Amendment Gate (only when applicable)
If the sub-command is update --domain master, enhance --domain master, or
create --domain <new> (which affects the federation map), use
AskUserQuestion to capture explicit acknowledgement:
"This change affects every domain team and every active epic. Are you ready
to proceed?"
Record the answer in the session state. Forward it to the grounder.
Phase 4 — Capture User Intent
Use AskUserQuestion (or read prior conversation) to capture a one-paragraph
description of the intended change. This becomes the {{user_intent}} input
to every agent prompt template.
Phase 5 — Dispatch the Team
For each agent in the chosen path, populate its prompt template (substituting
the {{...}} placeholders) and dispatch via the Agent tool. The recipe
files for each command live in references/command-reference.md.
The dispatch order is research-then-propose-then-judge:
- Researcher (always first; output feeds everyone)
- Investigator (parallel with researcher when possible)
- Thinker (consumes researcher + investigator output)
- Grounder + Critic (parallel; both consume thinker proposal)
- Reviewer (last; consumes everything)
Use subagent_type per the agent files — researcher and investigator
use Explore, thinker uses clean-architect or general-purpose, grounder
uses general-purpose, critic uses code-reviewer, reviewer uses
agile-validator.
Phase 6 — Reviewer Verdict Handling
| Verdict | Action |
|---|
| PASS | Proceed to write. |
| PASS_WITH_FOLLOWUPS | Proceed to write. Create one TaskCreate entry per follow-up. |
| FAIL | Do not write. Report blockers verbatim to the user. Offer to re-dispatch the thinker with the critic's required edits. |
Phase 7 — Writes (only on PASS)
In one logical change set:
- Prepend the Sync Impact Report to the target constitution file (HTML
comment block, per
templates/sync-impact-report-template.md).
- Apply the principle text edits (using
Edit against the existing file, or
Write for create).
- For master amendments only: edit the
**Inherits**: Master v<X.Y.Z> line
in all four domain constitution files.
- Update
.agile/rules/index.md (regenerated from scripts/registry-sync.sh --markdown).
- Update any templates listed in the investigator's propagation table.
- Update
.claude/rules/anti-patterns/gsb-lessons-learned.md if the change
touches a cited principle.
Phase 8 — Confirmation Output
Print a concise summary:
✓ <domain> constitution amended: v<old> → v<new>
✓ Added/removed: <principle IDs>
✓ Propagation: <N> templates, <N> rules, <N> anti-patterns updated
ℹ Follow-ups queued: <count>
Triggers (when to invoke this skill)
Invoke whenever the user mentions any of:
- "constitution", "amendment", "ratify", "governance", "policy", "guardrail", "regulation", "rule of the project"
- A principle ID (
MASTER:V, WORKER:VII, FRONTEND:I, etc.)
- A version bump on
.agile/rules/* files
- "Add a project-wide standard", "Update the rules", "Refine the constitution"
- The slash command
/agile:rules:constitution
Also invoke proactively when:
- Reading the index reveals stale inheritance refs (run
scripts/detect-stale-inheritance.sh)
- A nightly drift check has flagged mismatch between constitution files and
the registry
- An epic implementation has produced an anti-pattern that warrants
ratification as a master principle
When NOT to Invoke
- Compliance checking of an existing artifact — that's
agile-constitution-check.
- Drafting a feature spec — that's
agile-epic-brainstorm / agile-epic-plan.
- Modifying
.claude/rules/* (compact rules) without touching .agile/rules/*
— those are independent; coordinate through /agile:rules:constitution
only when the change must ripple into the constitution.
References (load on demand)
Templates (used at runtime)
Scripts (self-contained, see scripts/)
| Script | Purpose |
|---|
constitution-detect.sh | Domain detection (CLI: --domain-only, --json) |
extract-principles.sh | Parse principle IDs from a constitution file (--json, --count) |
semver-bump.sh | Compute next version (major | minor | patch) |
validate-versions.sh | Compare frontmatter version to index registry |
validate-principle-counts.sh | Compare actual principle count to index declaration |
detect-stale-inheritance.sh | Flag domains whose **Inherits** line is behind master |
registry-sync.sh | Regenerate index registry data from current files |
All scripts are read-only and self-contained — they do not modify any file
under .agile/rules/. Writes are performed only by the SKILL.md flow after
the reviewer issues PASS.
Samples (worked examples)
Examples
List the registry
/agile:rules:constitution list
Runs scripts/registry-sync.sh --markdown. No team dispatched.
Detect domain for a path
/agile:rules:constitution detect workers/batch
Runs scripts/constitution-detect.sh. Returns domain, master file + version,
domain file + version, principle prefix.
Validate a domain
/agile:rules:constitution validate --domain services
Dispatches reviewer only. Produces a per-principle pass/fail report (sample
in samples/sample-validation-report.md).
Refine wording
/agile:rules:constitution refine --domain frontend
Lighter path: researcher + critic + reviewer. Always PATCH bump. Walkthrough
in samples/sample-refinement.md.
Add a master principle
/agile:rules:constitution update --domain master
Full team. Requires acknowledgement gate. MAJOR or MINOR bump. Walkthrough
in samples/sample-master-amendment.md.
Detect drift
/agile:rules:constitution sync
Investigator scans for inheritance drift; reviewer issues a remediation
plan. User confirms each proposed inheritance-ref bump before write.
