Spec-Driven

Spec-Driven Process: The Constitution

two rules, what each bounds, and what they deliberately permit

Process Behavior C++ Rust C# Python
Synopsis:
This page documents Constitution.md, the 21-line document that governs Spec_driven_TextFinder/ and overrides the defaults an assistant would otherwise apply. It carries two rules.
  • All code creation and modification derives from the Spec*.md and *Structure.md files in the project. Change the code by changing a specification first.
  • No file outside the project is modified, and no archive directory is read, without an explicit request naming it.
The rules matter less for what they forbid than for what they deliberately permit.
  • General language knowledge stays available; outside example code does not.
  • A sibling implementation inside this project may serve as an example, but only where a user prompt asks for it, and the thread that took that route says so.
  • An ambiguous specification is a question to ask, not a gap to fill.
 Both rules reached this form by amendment and compression, and the record is here.
  • Section 6 reproduces Constitution.md in full.
  • Section 7 carries the two prompt conversations that produced it.

1.  Two Rules

Constitution.md governs Spec_driven_TextFinder/ and its children, and overrides the defaults an assistant would otherwise apply. It carries two rules and five notes, and the whole document runs 21 lines. Section 6 below reproduces it.
  1. Spec-driven code. All code creation and modification in the project derives from the Spec*.md and *Structure.md files in the project directory or any subdirectory, matched case-insensitively. Changing the code starts with changing the spec or the structure. Example code, sample implementations, and other projects outside this one are excluded as sources. An implementation already in this project may serve as an example for a later one where a user prompt asks for it.
  2. Stay inside. No file outside Spec_driven_TextFinder/ is modified without an explicit request naming it, and no archive directory is read, wherever it sits.
 The two rules answer two different failure modes. Rule 1 stops the code and the specifications from drifting apart. Rule 2 stops work on this project from reaching the rest of the site repository.

2.  What Rule 1 Bounds

Rule 1 names two file patterns rather than one. The second, *Structure.md, arrived by amendment: the C++ structure document had grown an interface declaration, and declaring the Output base class in a structure document while rule 1 named only Spec*.md would have made the code derive from something the rule did not authorize. Three ways out were on the table - amend the rule, move the interface into a spec file, or have each spec file cite the structure document - and the one-line amendment won on token cost. The rule binds modification as tightly as creation. A small edit to working code is not exempt: the edit starts as an edit to a document. That is what the twelve-item review in Prompts_Fix_Constitution.md settled, item 8, and it is the reason a defect found while building shows up in the records as a specification change first. What rule 1 excludes is outside example code. Every component specification in this tree was written without reading another TextFinder, and the C++ sources were written from those specifications alone. A second amendment drew the line where the project's own implementations sit. Rule 1 read "example code" without qualification at first, which made a later language thread's only lawful source its own specifications - and the Rust sources were in fact written with the C++ implementation in view. Two ways out were available: treat that as a departure to disclose, or say what the rule had never settled, that a sibling inside this project is not the outside example the rule excludes. The second won, and it was written as a permission rather than a method: a thread may be written from its specifications alone, or from those specifications with a sibling in view. The permission is gated on the prompt. A user request opens the second route and nothing else does, so the first route is what an assistant takes by default and the specifications are the only source until a prompt says otherwise. Writing it that way keeps the choice where the two limits below can be applied to it: a route taken silently is a route nobody weighed. Two limits keep that permission from swallowing the rule. The specifications remain the authority, so where a sibling and a specification disagree the specification wins and the sibling carries the defect. And an ambiguity is still a question to ask rather than a gap to fill from what the sibling did, for the reason Section 5 gives: copying a sibling's answer settles a specification question in code, where the next implementation cannot find it.

3.  What Rule 2 Bounds

Rule 2 draws a write boundary at the project directory and a narrower read boundary outside it. Reading outside is permitted for four things only: standard toolchains, the project CLAUDE.md, auto-memory, and git status and history. Any other outside read needs explicit permission, which then lasts the session. The four exemptions are not concessions so much as recognitions. A toolchain lives outside the project by definition, so a rule that forbade reading it would forbid building. The other three the harness loads before an assistant acts, so a rule that forbade them would be violated before the first turn. The archive prohibition is stated separately and is absolute: no archive directory is read, inside the project or outside it, without an explicit request naming it. That rule has teeth here. The superseded page structure sits in archive/Page_Structure.md, and archive is also the first of the 11 default skip-list names in Spec_TextFinder.md §3.2, so TextFinder prunes it during traversal for an unrelated reason and the demonstration counts drop when a document moves there.

4.  What the Rules Permit

Three permissions carry more weight than their wording suggests.
  • General language knowledge stays available. Idioms, standard libraries, and toolchains are fair game; outside example code is not. Without that distinction the rule would forbid writing idiomatic C++ at all, since the idiom was learned somewhere. The line falls between knowing that std::expected models a fallible return and copying a parser that uses it.
  • A sibling implementation is available on request. A language thread takes its specifications alone, or its specifications with a finished sibling in view where a user prompt asks for it, and both satisfy rule 1. Neither the assistant nor the rule picks the second route, which is what keeps the specifications on trial: an implementation written from them alone tests whether they are sufficient, and one written from a sibling does not. A note adds the one duty the route carries - a thread that took it says so on its Process page, since which route a thread took is process evidence.
  • No code lives in the top directory. All code sits in child directories, which is why the language-idiom permission is phrased as applying to work in those children. The top directory holds documents only.
 One note covers the failure case. Material read in error is discarded as context - not used to inform code or decisions - and the error is disclosed. The wording says plainly that discarding applies to the context and that the source files themselves are untouched, a clarification the user asked for in Turn 8.

5.  An Ambiguity Is a Question

The last note is the one that shaped the project's working method: if a Spec*.md or *Structure.md is ambiguous, ask - do not fill gaps from external sources. The prompt records show the effect. Drafting the project specification drew an 18-item review; the C++ structure document drew 12 items; the Cmdline spec drew 12; the Dirnav spec drew 13; the Entry spec drew 13; and once all five specifications existed, reading them together drew 15 more. Each list was returned without edits, the user answered item by item, and the answers were applied in one pass. That is the shape a "no filling gaps" rule forces: the questions accumulate into a review rather than dissolving into guesses. It also shapes where a rule lands. Ten of the Dirnav review's thirteen items changed emitted output, so each went into the project specification rather than the C++ one - a rule that changes what a user sees binds all four implementations, and leaving it in one language's document would have let the others diverge.

6.  Constitution.md

The document in full. It reached this form by compression: an earlier draft ran about 430 words across five sections, and the user asked whether alternate phrasing could cut the token count while preserving both intents. It could, to about 180 words, by merging the two scope sections into one rule, folding read, write, edit, create, and delete into "modify", and moving precedence and violation handling into one-line notes.
Constitution.md
# Constitution

Rules for `Spec_driven_TextFinder/` and its children. Override defaults on conflict.

## Two Rules

1. **Spec-driven code.** All code creation and modification in this project must derive from `Spec*.md` and `*Structure.md` files (case-insensitive) in this directory or any subdirectory. To change code, change the spec or structure first. Do not copy, pattern-match, or draw from example code, sample implementations, or other projects outside this one. General language knowledge — idioms, standard libraries, toolchains — is fine; outside example code is not.

   **If requested by user prompt, a sibling implementation may serve as an example.** An implementation already in this project sits inside the boundary rule 2 draws, so a later language thread may be written from its own specifications alone, or — where a prompt asks for it — from those specifications with a sibling implementation in view. Both routes satisfy this rule, and the first is the default: absent such a request, the specifications are the only source.

   Two limits hold on the second route. The specifications remain the authority, so where a sibling and a specification disagree the specification wins and the sibling carries the defect. And an ambiguity is still a question to ask rather than a gap to fill from what the sibling did: copying a sibling's answer settles a specification question in code, where the next implementation cannot find it.

2. **Stay inside.** Do not modify any file outside `Spec_driven_TextFinder/` without an explicit user request naming the file. Reading outside is permitted only for: standard toolchains, project `CLAUDE.md`, auto-memory, and git status/history. Other outside reads require explicit permission, which lasts the session. Do not read any `archive` directory or its contents, wherever it sits, inside this directory or outside it, without an explicit user request naming it.

## Notes

- No code lives in this top directory; all code is in child directories.
- `Prompts_*.md` files document the design process; they are not inputs to code.
- If a `Spec*.md` or `*Structure.md` is ambiguous, ask — do not fill gaps from external sources.
- A thread written with a sibling implementation in view says so on its Process page. Which route a thread took is process evidence.
- If outside material is read in error, discard that context (do not use it to inform code or decisions) and disclose. The source files themselves are untouched.

7.  Prompt Records

The two conversations that produced Constitution.md, in full. The first records the original draft; the second records the twelve-item review, the twelve decisions, the compression, and the clarification that followed.
Prompts_Constitution.md 
# Prompts and Replies — Constitution Development

This file records the prompts and replies exchanged while drafting [Constitution.md](Constitution.md).

---

## Turn 1

### User

> create Constitution.md that prohibits reading or editing files above this directory with explicit command to do so. All code generation comes from Spec*.md files without using other sample code.

### Assistant

Checked the directory for existing markdown files, then created [Constitution.md](Constitution.md) with three sections:

- **Scope Boundary** — prohibited reading or editing files above `Spec_driven_TextFinder/` without explicit per-path permission, and prohibited reading any `archive` directory or its contents, wherever it sits, inside this directory or outside it. Defined "above" to include sibling projects, parent folders, repo root, and user/system paths. Clarified that implicit relevance, prior context, and memory entries do not count as permission.
- **Code Generation Source** — required all generated code to derive solely from `Spec*.md` files in this directory. Forbade consulting or pattern-matching against sample code, reference implementations, other projects in the repository, or code snippets outside `Spec*.md`. Directed the assistant to ask for clarification rather than fill gaps from external sources. Noted that `Prompts_*.md` files could be read for task instructions but were not code sources.
- **Precedence** — stated these rules take precedence over global instructions, project `CLAUDE.md`, and auto-memory when they conflict within this directory.
Prompts_Fix_Constitution.md 
# Prompts and Replies — Constitution Refinement

This file records the prompts and replies exchanged while refining [Constitution.md](Constitution.md) after its initial draft. Turn 1 (initial creation) is recorded in [Prompts_Constitution.md](Prompts_Constitution.md).

---

## Turn 2

### User

> Prompts*.md are for documenting Spec-Driven design, not to be used for creating or editing code

### Assistant

Edited the `Prompts_*.md` bullet in [Constitution.md](Constitution.md) to state that these files document the Spec-Driven design process, must not be used as input for creating or editing code, and are neither code sources, spec sources, nor clarifications of specs.

---

## Turn 3

### User

> are there any ambiguities or improvements needed for Constitution.md

### Assistant

Reviewed [Constitution.md](Constitution.md) and listed twelve items across three groups, without editing. Awaited user decisions.

**Scope Boundary ambiguities:**

1. "Above" is imprecise — sibling projects and user/system paths are not literally "above." Suggested "outside."
2. Toolchain access — `cargo`, `rustc`, `dotnet`, `python` read from paths outside this directory. Silent on whether standard toolchains are exempt.
3. Passive context vs. active tool use — the harness auto-loads global `CLAUDE.md`, project `CLAUDE.md`, memory index, and git status before the assistant acts. Rule as written conflicts with that.
4. Memory system — the memory directory is outside this directory. Constitution as written forbids access. Intentional?
5. Web fetches and documentation lookups — not addressed.
6. "Explicit permission" duration — per-turn, per-file, or session-wide?

**Code Generation Source ambiguities:**

7. Existing code in this directory — silent on reading self-generated code for later modification.
8. Modifying vs. generating — silent on whether the spec-only rule applies to small edits.
9. Language knowledge baked into the model — "do not import conventions, idioms" could be read to forbid language idioms entirely.
10. Case sensitivity of `Spec*.md` — silent.

**Structural:**

11. Precedence outside this directory — silent on whether the Constitution binds work performed elsewhere in the same session.
12. Failure mode — no rule for material read in error.

---

## Turn 4

### User

Provided decisions on all twelve items:

> 1. use outside throughout
> 2. Toolchains should be used where applicable even if outside this directory
> 3. allow reading project claude.md, memory index, and git status
> 4. allow reading memory system
> 5. allow for language information but not for examining example code
> 6. allow for duration of session
> 7. there will be no code in this directory, only in its children
> 8. all modifications should come from modifications to the Spec*.md files, not from unspecified direct changes to code.
> 9. Import conventions and idioms when creating or editing code in child directories.  There will be no code in this top directory.
> 10. Use case insensitivity for spec file names and patterns.
> 11. constitution binds only work in this directory and its children.  However, all such changes should be authorized by me before implementing.
> 12. discard

### Assistant

Rewrote [Constitution.md](Constitution.md) applying all twelve decisions. New structure: Scope of This Constitution, Scope Boundary (with Permitted Reads Outside subsection), Code Generation and Modification Source, Violation Handling, Precedence. "Above" replaced with "outside" throughout. Added a permitted-reads list (toolchains, project `CLAUDE.md`, memory system, git). Added session-duration permissions, case-insensitive `Spec*.md` glob, spec-first modification rule, language-idioms-allowed clause, and a discard-on-violation clause.

---

## Turn 5

### User

> create Prompts_Constitution.md with the first prompt and your results

### Assistant

Read [Prompts_Spec_TextFinder.md](Prompts_Spec_TextFinder.md) to match its format, then created [Prompts_Constitution.md](Prompts_Constitution.md) documenting Turn 1 only — the original creation prompt and the initial three-section draft.

---

## Turn 6

### User

> The intent of Constitution.md is to ensure that: 1) all code creations and modifications for this project are derived from Spec*.md files and 2) no code outside Spec_driven_TextFinder is modified without a specific request to do so.  Can the number of tokens used be significantly reduced by alternate phrasing?

### Assistant

Yes. Proposed a compressed draft (~180 words vs. ~430 previously) preserving both intents. Merged "Scope of This Constitution" and "Scope Boundary" into a single rule; folded read/write/edit/create/delete into "modify"; consolidated the permitted-reads list into one sentence; moved Precedence and Violation Handling into one-line entries under Notes. Preserved both core intents, spec-first modification, session-duration permissions, case-insensitive `Spec*.md`, permitted-reads list, `Prompts_*.md` exclusion, discard-on-violation, and precedence. Asked before applying.

---

## Turn 7

### User

> yes

### Assistant

Replaced [Constitution.md](Constitution.md) with the compressed version.

---

## Turn 8

### User

> In the last Notes item clarify that only context is being discarded

### Assistant

Edited the final Notes bullet to state that discarding applies to the read context (not used to inform code or decisions) and that the source files themselves are untouched.

---

## Turn 9

### User

> create Prompts_Fix_Constitution.md with all the prompts and replies after the first

### Assistant

Created this file, [Prompts_Fix_Constitution.md](Prompts_Fix_Constitution.md), documenting Turns 2 through 9. User prompts are quoted verbatim. Assistant replies are summarized from the actual responses; tool calls are noted as effects rather than transcribed.