Write Constitution

write-constitution

Agent resolution: before any subagent dispatch, read ${CLAUDE_PLUGIN_ROOT}/shared/agent-runtime-map.md and use the active runtime's name.

Rigid governance gate. Match the user's language; keep technical identifiers unchanged.

Voice

Read ../../persona.md; it is canonical for this skill's user-facing output, and its scope ends at the final report.

When you're invoked

The user wants to write a constitution for a project — typically before the first spec, or when an audit keeps surfacing the same project-specific concern (test-first, no-new-deps, library-first, etc.).

Workflow

1. Preconditions:

   • Verify git repo: PROJECT_ROOT = $(git rev-parse --show-toplevel). Abort if not in a repo.
   • Ensure ${PROJECT_ROOT}/docs/acid-prophet/ exists; create if missing.
   • Check whether ${PROJECT_ROOT}/docs/acid-prophet/constitution.md already exists.
     • Yes → read it, print its current articles, and ask: revise (r) | append articles (a) | replace from scratch (x) | stop (s). Branch on response. (x) requires a second confirmation.
     • No → proceed to step 2.

2. Explore context (read-only):

   • git log --oneline -20.
   • Read ${PROJECT_ROOT}/CLAUDE.md if present — its policies are constitutional candidates already.
   • Read ${PROJECT_ROOT}/package.json if present — note declared stack and package manager.
   • List docs/acid-prophet/specs/ if it exists — sample one or two to detect recurring tensions.

3. Surface candidate articles (one message, full list):

   • Propose 3–7 candidate articles distilled from CLAUDE.md, package.json, and prior specs. Each candidate is one short rule with a Why: line citing the evidence (CLAUDE.md quote, dependency choice, repeated audit finding).
   • Format example:

     - **No new dependencies without discussion**
       Why: CLAUDE.md states "no npm/bun deps added in plugins" — every spec that proposed a dep was rejected.
     

   • Mark each candidate [propose | skip | edit] and wait for the user to triage in one message.

4. Clarifying questions (one per message):

   • For each edit candidate, drill in: what does the article actually require, what does it forbid, when does it apply, when does it NOT apply (anti-scope). One question at a time. Apply the uncertainty rule: when the user has not specified a value, emit [NEEDS CLARIFICATION: ...] inline and move on — never invent.
   • Optional fifth pass: ask the user to add 1–2 articles not surfaced by the candidates. Same drill.

5. Draft the constitution:

   • Layout:

     ---
     id: constitution
     status: ratified
     last-reviewed: <today ISO>
     version: 1
     ---
     
     # Constitution — <project name>
     
     > Articles below are enforced by `acid-prophet:spec-auditor` on every spec audit. Each article becomes a gate: violating articles ⇒ `gate:constitution:<slug>` BLOCKER and `handoff-eligible: no`.
     
     ## Articles
     
     ### <Article slug — kebab-case>
     
     **Rule.** <One sentence stating what the spec must do or must not do.>
     
     **Why.** <One to three sentences citing the evidence: CLAUDE.md quote, prior incident, stack constraint.>
     
     **Scope.** <When this article applies and when it doesn't. Anti-scope is mandatory — articles without an exit clause turn into religious dogma.>
     
     **Auditor check.** <One sentence telling the auditor what to grep for or what spec section to read to decide pass/fail.>
     
     ### <next article>
     
     …
     

   • Slug rule: each ### <slug> heading uses kebab-case, ASCII only, ≤ 30 chars. The auditor uses this slug for [gate:constitution:<slug>] findings.

6. User ratification gate:

   • Print the full draft inline.
   • Ask: ratify (y) | revise (r) | abandon (a). Wait.
   • revise → return to step 4 on the article the user names; re-draft; ask again.
   • abandon → exit with no file written.

7. Write + optional commit:

   • Save to ${PROJECT_ROOT}/docs/acid-prophet/constitution.md. Overwrite only if the user chose (x) or (r) at step 1; otherwise this is a first write.
   • Ask exactly: Commit the artifact? (y / no). On y, run git add docs/acid-prophet/constitution.md && git commit -m "docs(acid-prophet): ratify constitution v<N>" where <N> is the new version. On no, leave the ratified constitution uncommitted and continue. Never use --no-verify.

8. Wire-up notice (single message):

   • Tell the user: the next audit-spec, write-spec step 7, and check-drift invocations will read the constitution and gate accordingly. No other action required.

Final Report

acid-prophet:write-constitution report
  Constitution: ${PROJECT_ROOT}/docs/acid-prophet/constitution.md
  Articles:     <N ratified>
  Version:      <N>
  Commits:      <N>
  Open markers: <N unresolved [NEEDS CLARIFICATION] | none>

Never

• Invent an article the user didn't approve.
• Skip the ratification gate (step 6) — even on (x) replacement.
• Edit constitution.md outside of this skill.
• Run git push, git rebase, or git commit --amend.
• Use --no-verify.
• Move to the next step before the current one is done.