plan-0-v2-constitution

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  and  for guaranteed preservation across updates.

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)

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.
Domain Detection (additive — skip if no domains present):
- Check if docs/domains/registry.md exists → read all registered domains
- Check if docs/domains/domain-map.md exists → read the domain architecture diagram
- If domains directory exists but no registry → read docs/domains/*/domain.md files directly
- If NO domain infrastructure exists: note "Domain system not yet initialized" — do NOT auto-create domain files (use /plan-v2-extract-domain when ready)
- Store domain context for use in Steps 4 and 6 (governance and architecture sections)
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..."
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  and 
  - 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: ' for TODO handling."

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

Scan:

skills/**/SKILL.md (and any .claude/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.

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(): "
Re-entrancy Merge Strategy (if UPDATE MODE):
- For each file, prepare merge plan:
  - Sections marked 'custom' → PRESERVE entirely
  - Sections marked 'generated' → UPDATE with new content
  - Sections marked 'mixed' → MERGE: Keep user additions, update framework
- Preserve all filled placeholder values from existing files
- Keep user-added sections not in template
- Maintain existing TODOs that are still unresolved
- Track what will change for user confirmation
- Prepare inputs for Step 4 constitution drafting:
  - All placeholder values (filled or deferred, preferring existing)
  - Validated principles and practices (merging existing with new)
  - Quality strategy with tools/approaches
  - Template dependency map for Step 7 propagation
  - Final version number and Sync Impact Report data
  - Merge strategy per file with preservation instructions
Draft docs/project-rules/constitution.md (re-entrancy aware) For CREATE MODE:
- Replace every placeholder. Standard sections:
  - Header with Title, Version, Ratification date, Last amended date
  - Guiding Principles – concise MUST/SHOULD statements with rationale
  - Quality & Verification Strategy – document how the team proves changes safe (tests, analysis, reviews). Highlight preferred tools per language when known; keep wording inclusive (examples are optional callouts).
  - Delivery Practices – planning cadence, documentation expectations, definition of done
  - Governance – amendment procedure, review cadence, compliance tracking
  - Domain Governance (include if domains detected OR project wants domain-based organization) –
    - Every source file belongs to a domain (or is uncategorized legacy)
    - Cross-domain imports use contracts only — no reaching into another domain’s internals
    - Domain boundaries are enforced by code review and plan structure
    - New domains are formalized via /plan-v2-extract-domain before code changes
    - Domain registry (docs/domains/registry.md) is the authoritative index
    - Domain map (docs/domains/domain-map.md) must stay current with contract edges
    - Business → infrastructure dependency: always allowed
    - Infrastructure → business dependency: never allowed
    - Business → business dependency: only via contracts
    - If no domains exist yet, note: "Domain governance applies once domains are established via /plan-v2-extract-domain"
For UPDATE MODE:
- Preserve all sections marked as 'custom' from Step 3 analysis
- Update 'generated' sections with new framework content
- For 'mixed' sections: Keep user additions, update framework parts
- Maintain filled placeholder values from existing file
- Add new standard sections if missing, mark with 
- Keep user's custom sections even if not in template
- Update version number appropriately (PATCH for clarifications, MINOR for new sections, MAJOR for breaking changes)
- Prepend a Sync Impact Report HTML comment summarizing:
  - Mode: CREATE or UPDATE
  - Version bump: old → new with rationale
  - Sections preserved vs updated
  - Custom content retained
  - New sections added
  - Outstanding TODOs
  - Supporting docs/templates update status
Align Rules & Idioms (re-entrancy aware) For UPDATE MODE:
- Apply same preservation strategy as constitution
- Keep user's custom rules and examples
- Update framework rules while preserving additions
- Merge testing section carefully to keep project-specific policies
- Write/update rules.md with enforceable statements ("MUST", "SHOULD") covering:
  - Source control hygiene and branching
  - Coding standards, naming, formatting
  - Testing/verification expectations (detailed guidance below)
  - Tooling or automation requirements (linters, CI, coverage, static analysis)
- Testing Section Requirements (expand with TAD philosophy): The testing section in rules.md MUST include comprehensive guidance on:
  
  1. Testing Philosophy
  - Tests as executable documentation (TAD principles)
  - Quality over coverage: tests must "pay rent" via comprehension value
  - When to write tests vs when to skip them
  - Smart application of TDD (test-first when it adds value, not dogmatically)
  2. Test Quality Standards
  - Every test MUST explain why it exists (business/bug/regression reason)
  - Every test MUST document the contract it asserts (plain-English invariants)
  - Every test MUST include usage notes (how to call the API, gotchas)
  - Every test MUST describe its quality contribution (what failures it catches)
  - Every test SHOULD include a worked example (inputs/outputs summary)
  - Tests MUST use clear naming (Given-When-Then or equivalent behavioral format)
  3. Scratch → Promote Workflow (TAD approach)
  - Probe tests MAY be written in tests/scratch/ for fast exploration/iteration
  - tests/scratch/ MUST be excluded from CI (via .gitignore or CI config)
  - Tests MUST be promoted from scratch/ only if they add durable value
  - Promotion heuristic: Keep if Critical path, Opaque behavior, Regression-prone, or Edge case
  - Promoted tests MUST move to tests/unit/ or tests/integration/
  - Promoted tests MUST include complete Test Doc comment blocks (5 required fields)
  - Non-valuable scratch tests MUST be deleted (keep learning notes in PR/log)
  4. Test-Driven Development (TDD) Guidance
  - TDD (test-first) SHOULD be used for: complex logic, algorithms, APIs, critical paths
  - TDD MAY be skipped for: simple operations, config changes, trivial wrappers
  - When using TDD, follow RED-GREEN-REFACTOR cycles
  - Tests written first MUST document expected behavior clearly
  - Avoid dogmatic TDD; apply when it adds value to design process
  5. Test Reliability & Quality
  - Tests MUST NOT use network calls (use fixtures/mocks for external dependencies)
  - Tests MUST NOT use sleep/timers (use time mocking if needed)
  - Tests MUST be deterministic (no flaky tests tolerated in main suite)
  - Tests SHOULD be reasonably fast to maintain quick feedback loops
  - Performance requirements (timing, resource limits) will be specified in the spec when needed
  6. Test Organization
  - tests/scratch/ – fast probes, excluded from CI, temporary exploration
  - tests/unit/ – isolated component tests with Test Doc blocks
  - tests/integration/ – multi-component tests with Test Doc blocks
  - tests/e2e/ or tests/acceptance/ – full-system tests (if applicable)
  - tests/fixtures/ – shared test data, realistic examples preferred
  7. Mock Usage Policy
  - Follow project-specific mock policy (Avoid | Targeted | Liberal - set in the spec's clarify pass, /the-flow 1b)
  - When mocking, document WHY the real dependency isn't used
  - Prefer real data/fixtures over mocks when practical
  - Mocks SHOULD be simple and behavior-focused, not implementation-focused
  8. Test Documentation Format Include language-appropriate Test Doc block format examples:
```
test('given_iso_date_when_parsing_then_returns_normalized_cents', () => {
  /*
  Test Doc:
  - Why: Prevent regression from #482 where AUD rounding truncated cents
  - Contract: parseInvoice returns {totalCents:number, date:ZonedDate} with exact cent accuracy
  - Usage Notes: Supply currency code; parser defaults to strict mode (throws on unknown fields)
  - Quality Contribution: Catches rounding/locale drift and date-TZ bugs; documents required fields
  - Worked Example: "1,234.56 AUD" → totalCents=123456; "2025-10-11+10:00" → ZonedDate(Australia/Brisbane)
  */
  // Arrange-Act-Assert with clear phases
});
```
```
def test_given_iso_date_when_parsing_then_returns_normalized_cents():
    """
    Test Doc:
    - Why: Regression guard for rounding bug (#482)
    - Contract: Returns total_cents:int and timezone-aware datetime with exact cents
    - Usage Notes: Pass currency='AUD'; strict=True raises on unknown fields
    - Quality Contribution: Prevents silent money loss; showcases canonical call pattern
    - Worked Example: "1,234.56 AUD" -> 123_456; "2025-10-11+10:00" -> aware datetime
    """
    # Arrange-Act-Assert with clear phases
```
  9. Complexity-First Estimation Policy (REQUIRED)
  
  The constitution MUST enforce a no-time policy for all estimates and planning:
  - Prohibition: Never output or imply time, duration, or ETA in any form (hours, minutes, days, "quick", "fast", "soon", deadlines, etc.)
  - Replacement: All effort quantification MUST use the Complexity Score (CS 1-5) system
  - Scoring rubric: Compute points (0-2 each) for 6 factors, sum to CS:
    - Surface Area (S): Files/modules touched; breadth of change (0=one file, 1=multiple files, 2=many files/cross-cutting)
    - Integration Breadth (I): External libs/services/APIs/tooling (0=internal only, 1=one external, 2=multiple externals/unstable API)
    - Data & State (D): Schema changes, migrations, concurrency (0=none, 1=minor tweaks, 2=non-trivial migration/concurrency)
    - Novelty & Ambiguity (N): Requirements clarity, research needed (0=well-specified, 1=some ambiguity, 2=unclear specs/significant discovery)
    - Non-Functional Constraints (F): Performance, security, compliance (0=standard gates, 1=moderate constraints, 2=strict/critical constraints)
    - Testing & Rollout (T): Test depth, flags, staged rollout (0=unit only, 1=integration/e2e, 2=flags/staged rollout/backward compat)
  - Mapping: Total points P (0-12) maps to CS:
    - CS-1 (0-2): Trivial - isolated tweak, no new deps, unit test touchups
    - CS-2 (3-4): Small - few files, familiar code, maybe one internal integration
    - CS-3 (5-7): Medium - multiple modules, small migration or stable external API, integration tests
    - CS-4 (8-9): Large - cross-component, new dependency/service, meaningful migration, rollout plan
    - CS-5 (10-12): Epic - architectural change/new service, high uncertainty, phased rollout with flags
  Mandatory output fields wherever planning or reporting occurs:
```
{
  "complexity": {
    "score": 3,
    "label": "medium",
    "breakdown": {"surface": 1, "integration": 1, "data_state": 1, "novelty": 1, "nfr": 0, "testing_rollout": 1},
    "confidence": 0.75
  },
  "assumptions": ["Spec is final"],
  "dependencies": ["Payments service schema v2"],
  "risks": ["Downstream consumer expectations"],
  "phases": ["Design notes", "Implementation", "Tests", "Flagged rollout"]
}
```
  Enforcement rules:
  - For CS ≥ 4, MUST include staged rollout, feature flags, and rollback plan in phases
  - Prefer complexity idioms: "scope", "risk", "breadth", "unknowns" over any time language
  - If uncertainty is high, ask clarifying questions and reflect in Novelty (N) + lower confidence
  - Self-check: If time words appear in drafts, replace with complexity reasoning or remove
  Calibration examples (include in idioms.md):
  - Rename a constant used in one file: S=0, I=0, D=0, N=0, F=0, T=0 → CS-1 (trivial)
  - Add new endpoint using existing service: S=1, I=1, D=1, N=1, F=0, T=1 → P=5 → CS-3 (medium)
  - Introduce new service with schema migration and staged rollout: S=2, I=2, D=2, N=2, F=1, T=2 → P=11 → CS-5 (epic)
- Write idioms.md with illustrative patterns, directory conventions, and language-specific examples when relevant.
- Keep references to the constitution explicit (e.g., link sections or quote identifiers). If any area is not yet defined, leave a TODO entry mirroring the constitution.
Maintain architecture.md (re-entrancy aware) For UPDATE MODE:
- Preserve user's architectural decisions and custom diagrams
- Update framework structure while keeping project-specific sections
- Maintain technology stack choices and integration details
- Keep custom anti-patterns and project-specific checklists
- Capture/update the system's high-level structure: modules, services, layers, data flows, integration points.
- Define boundaries and contracts (who may call whom, allowed dependencies, deployment targets).
- Domain Integration (if domains detected): Reference docs/domains/domain-map.md for the authoritative domain architecture diagram. Architecture boundaries should align with domain boundaries. Document how domain contracts map to system-level interfaces.
- Document technology-agnostic rules first; add stack-specific notes in dedicated subsections (e.g., "Example: Node service" / "Example: C# backend").
- Track anti-patterns and reviewer checklists that should remain stable across implementations.
Propagate doctrine into helpers (if any)
- For each file under templates/ or command/skill directories (e.g. skills/, .claude/commands/) that references the constitution or rules, ensure links remain correct and language stays stack-neutral.
- Where downstream workflows expect gates (e.g., "confirm plan aligns with rules"), keep the gate but phrase it generically.
- Do not invent new templates; update only those already present.
Validate before writing
- No document retains unresolved [PLACEHOLDER] tokens.
- Version bumps and dates follow ISO YYYY-MM-DD.
- Principles and rules are actionable, not vague aspirations.
- Architecture doc reflects the latest agreed structure without contradicting Rules or Constitution.
- Templates/commands (when touched) remain idempotent and reference the canonical paths exactly.
For UPDATE MODE - User Confirmation:
- Display summary of proposed changes:
  - "Will preserve: X custom sections, Y user values"
  - "Will update: Z framework sections"
  - "Will add: N new sections"
- Show diff preview of significant changes
- Ask: "Proceed with update? (backups will be created)"
- If user declines, abort with no changes
Write files with intelligent merge For CREATE MODE:
- Write CONST, RULES, IDIOMS, and ARCH with fresh content
- Mark sections that users can customize with  and 
For UPDATE MODE:
- For each file, apply merge strategy from Step 3:
  - Preserve sections marked 'custom' completely
  - Update sections marked 'generated' with new content
  - Intelligently merge 'mixed' sections (keep user content, update framework)
- Add protective markers around user content for future runs
- Validate no user content was lost in the merge
- Create backup of original files before writing (stored in .constitution-backup/)
For both modes:
- Apply the minimal set of edits needed for any templates or helper commands
- Preserve contributor-authored content outside the edited blocks
- Ensure all files remain internally consistent
Final summary (stdout) For CREATE MODE:

Report: "✨ Created new constitution and doctrine files"
Include version 1.0.0 and creation date
List all created files

For UPDATE MODE:

Report: "🔄 Updated constitution and doctrine files"
Show version change: old → new with bump rationale
List what was preserved vs updated:
- "Preserved: N custom sections, M filled values"
- "Updated: X framework sections"
- "Added: Y new sections"
If backups created, note location: .constitution-backup/

For both modes:

List all modified paths with change type
Mention outstanding TODOs or follow-up owners if doctrine remains incomplete
Provide appropriate commit message:
- CREATE: docs: establish project constitution and doctrine files
- UPDATE: docs: update constitution v{old} → v{new} while preserving customizations

Synchronized doctrine (authoritative excerpts to enforce)

The following must be enforced across Constitution -> Rules & Idioms -> Plan/Tasks/Implementation:

Documented Quality Strategy
- Capture how the team proves software is safe to release (automated tests, manual smoke tests, static analysis, runtime monitors).
- Encourage technology-specific examples, but keep the core policy portable across stacks.
Repeatable Tooling & Environments
- Specify required automation (CI jobs, linters, formatters, build scripts) and how contributors run them locally.
- Note any cross-platform considerations (macOS, Linux, Windows/WSL).
Coding & Review Standards
- Define expectations for naming, style, documentation, and code review checklists.
- State how decisions trace back to the constitution (e.g., principle IDs or links).
Architecture Guardrails
- Describe boundaries between major components, allowed dependencies, and integration hooks.
- Include anti-patterns reviewers should watch for and escalation paths when architecture evolves.
Domain Boundaries (when domain system is active)
- Cross-domain imports MUST use contracts (public interfaces) only.
- Each plan phase should primarily target one domain.
- Domain creation must be formalized before implementation begins.
- Domain map must be updated when domain relationships change.
- Business domains may depend on infrastructure; never the reverse.
Change Governance
- Clarify who approves doctrine updates, how often reviews occur, and what evidence is required for compliance.

Acceptance Criteria (for this command)

docs/project-rules/constitution.md is fully populated, versioned, and includes a Sync Impact Report.
docs/project-rules/{rules.md, idioms.md, architecture.md} exist (or are created/updated) and reflect the same doctrine without contradictory guidance.
For UPDATE MODE: All user customizations are preserved, no content is lost.
For CREATE MODE: Files include protective markers for future customizations.
Backups are created before updates (stored in .constitution-backup/ with timestamp).
No document retains unresolved placeholders; dates and versions adhere to the rules above.
Any touched templates or command prompts reference the canonical doctrine paths and remain stack-neutral.
If domains are detected, constitution includes Domain Governance section with cross-domain dependency rules.
If domains are NOT detected, constitution works without domain references (domain governance is additive, not required).
Final summary surfaces version bump, updated paths, preserved content metrics, and outstanding TODO follow-ups.
User is shown preview and asked for confirmation before applying updates in UPDATE MODE.

Formatting & Style

Use Markdown headings exactly as in templates; keep one blank line between sections; avoid trailing whitespace.
Wrap rationale lines for readability (<100 chars where practical).
Deterministic edits; idempotent if run twice without new inputs.


Canonical paths enforced by this command

- Constitution: `docs/project-rules/constitution.md`
- Rules: `docs/project-rules/rules.md`
- Idioms: `docs/project-rules/idioms.md`
- Architecture: `docs/project-rules/architecture.md`
- Templates directory: `templates/`
- Domain registry: `docs/domains/registry.md` (read-only — not created by this command)
- Domain map: `docs/domains/domain-map.md` (read-only — not created by this command)

Run this command once per project (or whenever the guiding principles change) before executing planning or implementation phases.

Next step (when happy): Run **/the-flow 1a** for research, **/the-flow 1b** to capture the feature specification, or **/plan-v2-extract-domain** to formalize existing code as a named domain.

About this skill

Execution Flow (deterministic)

Synchronized doctrine (authoritative excerpts to enforce)

Acceptance Criteria (for this command)

Formatting & Style