Constitution

A product has a vision. A repo usually builds only part of it. The constitution writes down which part, and — more usefully — what this repo must never grow into.

Two files, and the difference between them matters:

• .aidlc/context/vision-source.md — the vision document's text, extracted and hashed. Machine-written, never hand-edited.
• .aidlc/context/constitution.md — what this repo owns and what it is forbidden to do, each line citing the vision statement it came from. Drafted by this skill, owned by the user.

The vision is imported. The constitution is a judgement about the vision, and judgement is why this is a skill and not just a command.

First run

Step 1 — Import the vision document

Ask for the path if the user has not given one. Then:

aidlc constitution import <path>

.docx, .md, .markdown and .txt are read directly. For a PDF, a Google Doc, or anything else: read it yourself, save a markdown copy next to the original, and import that — the command tells you the same thing if you try.

The command prints one line per statement, each with a V- id derived from that statement's own text. Those ids are the vocabulary for everything below.

If anything in the extracted text looks like a credential — an API key, a token, a password, a connection string — say so, and do not let it reach .aidlc/context/vision-source.md. Ask the user to remove it from the source document and re-import. The snapshot is committed; the vision document may not be.

Step 2 — Read the repo, not just the document

The vision says what the product is. Only the code says what this repo does. Read .aidlc/context/architecture.md if it exists, then look at the top-level layout and the entry points. You are deciding one thing: which slice of the vision this repo carries.

Step 3 — Draft the constitution

Write .aidlc/context/constitution.md:

---
generated_by: aidlc-constitution
generated_at: <ISO 8601 UTC>
vision_source: <path as imported>
---
# Constitution — <repo or component name>

## Mandate

One paragraph, plain words: which part of the product this repo owns, and which
parts belong to something else.

## In scope

- IN-1 [V-a1b2c3d4]: <what this repo builds>
- IN-2 [V-e5f6a7b8, V-11223344]: <another>

## Prohibitions

- NOT-1 [V-99887766]: <what this repo must never do>
- NOT-2 [V-a1b2c3d4]: <another>

## Amendments

<empty on the first run>

Four rules that make the file usable later:

1. Every entry cites at least one V- id. An entry with no citation is an opinion someone had, and a re-run cannot tell whether the vision still supports it. If you cannot find a supporting statement, that is a finding — say so and leave the entry out.
2. IN- and NOT- ids are assigned once. Never renumbered, never reused. An entry that no longer holds is recorded in Amendments with a date and a reason, not deleted — a deleted prohibition and one that never existed look identical.
3. A prohibition is a sentence someone can be shown. "No customer PII in this service" is checkable. "Keep it simple" is not.
4. Derive, do not invent. A prohibition the vision does not support is your opinion wearing the document's authority.

Step 4 — Hand it back

Show the Mandate and the Prohibitions and ask the user to correct them. They will know things the document does not say. Their corrections are the point — and step 2 of the re-run flow exists to protect them.

When the vision is updated

The user replaces the vision document and re-runs this skill. Never rewrite .aidlc/context/constitution.md from the new vision in one step: a human's correction to a derived line and a genuine change in the vision are indistinguishable once overwritten, and if corrections do not survive nobody makes them twice.

Step 1 — Ask what moved

aidlc constitution check

It reports statement ids added and removed relative to the snapshot. An edited statement appears as one of each, because ids come from content. It also names every constitution entry citing a removed id — those are the entries at risk, and it exits 0 either way. This is advisory. It never fails a phase.

Step 2 — Propose, do not apply

A constitution update has no instance, so its questions go to .aidlc/questions/constitution-update-<YYYY-MM-DD>.md — one question per change, following the Question Protocol in the overview skill:

# Constitution update — <date>

Vision source: <path> (<n> statements added, <m> removed)

## Should NOT-2 still stand, now that the statement it cites is gone?

**Why it matters:** NOT-2 is a boundary this repo is held to. Left citing a
statement the vision no longer carries, it is enforced without a source.

**What the repo already says:** `.aidlc/constitution.md` NOT-2 cites V-99887766.
The vision no longer says: "<old statement text>"
It now says: "<new statement text, if there is a successor>"

1. Re-cite NOT-2 against V-<new id>, wording unchanged — the boundary survives, only its source moves.
2. Reword NOT-2: <proposed wording> — the boundary narrows to what the vision now supports.
3. Retire NOT-2 — the repo may do this again, with nothing recording that it once must not.
4. Leave NOT-2 as it is — it becomes a deliberate local rule the vision never carried.

**Recommended:** 1, when a successor statement exists — the boundary was agreed
on its own merits and a re-citation is the smallest change that keeps it sourced.

**If you say nothing:** NOT-2 is left as it is and the drift is recorded in
Amendments, so the next reader sees an unsourced rule rather than a silent one.

[Answer]:

Offer the leave-as-it-is option every time. "The vision changed and this repo's boundary did not" is a common and correct answer.

Step 3 — Apply only what is checked

Then re-import so the snapshot matches the vision the decisions were made against:

aidlc constitution import <path>

Append one line to Amendments for every applied change — date, entry id, what changed, why. Amendments are how the next reader tells a deliberate local rule from a stale derivation. Record each answer in the question file and leave it in place — it is the record of what was asked and decided.

Consulting the constitution

Reading it during other work is not this skill's job — the overview skill carries that rule, and the requirements, design and roadmap skills point at it. This skill writes the file; they read it.

Exit criteria

• .aidlc/context/vision-source.md exists and its source_path names a real file.
• .aidlc/context/constitution.md has a Mandate, at least one prohibition, and a cited V- id on every entry.
• On a re-run: every proposed change was either applied or explicitly declined, and each applied one has an Amendments line.