Plan 0 Constitution

---
description: Establish or refresh the project constitution and align the supporting norms documents before any planning phases begin. Re-entrant command that preserves user customizations during updates.
---

Please deep think / ultrathink as this is a complex task.

# plan-0-constitution (alias: phase-0-constitution)

**Re-entrancy Support**: This command is now re-entrant and will intelligently preserve user customizations when updating existing constitution files. Mark your custom content with `<!-- USER CONTENT START -->` and `<!-- USER CONTENT END -->` for guaranteed preservation across updates.

````md
The user input to you can be provided directly by the agent or as a command argument - you **MUST** consider it before proceeding (if not empty).

User input:

$ARGUMENTS

You are updating the project doctrine files in `docs/project-rules/`:
- `docs/project-rules/constitution.md`  (Constitution – guiding principles and governance)
- `docs/project-rules/rules.md`         (Rules – normative MUST/SHOULD statements)
- `docs/project-rules/idioms.md`        (Idioms – recurring patterns and examples)
- `docs/project-rules/architecture.md`  (Architecture – structure, boundaries, interaction contracts)

If any document uses placeholder tokens like `[ALL_CAPS_IDENTIFIER]`, your responsibility is to gather the values, fill or intentionally defer them, and keep all three files mutually consistent. Downstream templates or command prompts may reference these files; when they exist, update them last so they reflect the newly agreed doctrine.

--------------------------------
## Execution Flow (deterministic)
1) Resolve repository paths and detect mode
   - If your environment supplies a repository metadata helper (e.g., a prerequisites script defined in command front matter), run it once and parse the returned JSON. Otherwise derive values from the current working directory.
   - Set constants:
     CONST = `docs/project-rules/constitution.md`
     RULES = `docs/project-rules/rules.md`
     IDIOMS = `docs/project-rules/idioms.md`
     ARCH  = `docs/project-rules/architecture.md`
     TMPL  = `templates/`  # Optional helper content if present
   - Ensure parent directories exist; create them atomically when missing.

   **Re-entrancy Detection**:
   - Check if any of CONST, RULES, IDIOMS, ARCH already exist
   - If ANY exist: **UPDATE MODE** - Will preserve user customizations
   - If NONE exist: **CREATE MODE** - Will create fresh documents
   - Display mode to user: "🔄 Updating existing constitution..." or "✨ Creating new constitution..."

2) Launch parallel context gatherers

**IMPORTANT**: Use **parallel subagent gatherers** for faster doctrine loading.

**Strategy**: Launch 4 parallel subagents (single message with 4 Task tool calls) to gather doctrine context concurrently.

**Subagent 1: Doctrine Loader (Re-entrancy Aware)**
"Load existing doctrine files and categorize content for preservation.

**Tasks**:
- For each of CONST, RULES, IDIOMS, ARCH:
  * If file exists:
    - Read fully and extract version number, [PLACEHOLDER] tokens, section headings, TODOs
    - Identify sections marked with `<!-- USER CONTENT START -->` and `<!-- USER CONTENT END -->`
    - Categorize each section as: 'generated' (safe to update), 'custom' (must preserve), or 'mixed' (needs merge)
    - Extract any filled placeholder values that replaced `[ALL_CAPS_TOKENS]`
    - Note custom sections not in standard template
  * If missing: Note for creation with minimal outline

**Categorization Rules**:
- Content between USER CONTENT markers = 'custom'
- Standard template sections without modifications = 'generated'
- Standard sections with significant user additions = 'mixed'
- Entirely new user-added sections = 'custom'

**Output**: JSON with {file_path, exists, version, placeholders[], headings[], todos[],
  sections[{name, type, content, preserve}], custom_additions[], filled_values{}}

**Return**: Results for all 4 files with preservation metadata."

**Subagent 2: Context Gatherer**
"Gather project governance and quality inputs from documentation.

**Priority order**: $ARGUMENTS > README.md > CONTRIBUTING.md > other handbooks

**Extract**:
- Guiding principles and values
- Quality/verification strategy and testing philosophy
- Delivery practices and governance rules
- Record source for each value (argument, README, etc.)

**Output**: JSON with {principles[], quality_strategy, delivery_practices, governance, sources{}}
Flag unknowns as 'UNKNOWN: <reason>' for TODO handling."

**Subagent 3: Template Scanner**
"Inventory templates and commands that reference doctrine.

**Scan**:
- agents/commands/*.md for references to constitution, rules, idioms, architecture
- templates/ directory for similar references

**Output**: JSON with {file_path, references_to[], link_format, expected_paths[]}
Note any hardcoded paths or placeholders that need updating."

**Subagent 4: Version Analyzer**
"Determine semantic version bump.

**Given**:
- Current versions from Subagent 1
- Changes from Subagent 2 ($ARGUMENTS and context)

**Apply rules**:
- MAJOR: Breaking changes to principles or governance
- MINOR: New principles/sections or materially expanded guidance
- PATCH: Clarifications or formatting adjustments

**Output**: JSON with {current_version, new_version, bump_type, rationale}
Include amendment date as ISO 8601."

**Wait for All Gatherers**: Block until all 4 subagents complete.

3) Synthesize gathered context and prepare merge strategy
   - Merge outputs from all 4 subagents into unified doctrine view
   - Conflict resolution: $ARGUMENTS > explicit docs > inferred > UNKNOWN
   - Build complete placeholder mapping: [TOKEN] → {value, source, confidence}
   - Validate version bump against actual changes detected
   - Create TODO list for any UNKNOWN values: "TODO(<FIELD>): <reason pending>"

   **Re-entrancy Merge Strategy** (if UPDATE MODE):
   - For each file, prepare merge plan:
     * Sections marked 'custom' → PRESERVE ent