Implementation Plan: AI-Facing Repository Constitution

Branch: 001-ai-docs | Date: 2026-01-30 | Spec: specs/001-ai-docs/spec.md Input: Feature specification from /specs/001-ai-docs/spec.md

Note: This template is filled in by the /speckit.plan command. See .specify/templates/commands/plan.md for the execution workflow.

Summary

Document an AI-facing constitution and use-case playbooks that explain repository rules, architecture, and workflows (e.g., adding modules/hosts/scripts/secrets), with clear information architecture for /docs and /specs. Approach: synthesize current repo conventions (flake-parts, auto-imports, toggles, secrets map, proxy rules), define authoritative precedence (constitution for AI), and provide quick-start guidance plus reference mapping for AI tools.

Technical Context

Language/Version: N/A (documentation artifacts)
Primary Dependencies: N/A (static markdown)
Storage: Repo files under /docs and /specs
Testing: Manual validation against checklist and repo conventions
Target Platform: AI assistants (Cursor/MCP) consuming repository docs
Project Type: Documentation set
Performance Goals: Docs discoverable within ≤2 navigation steps as per spec
Constraints: Follow repo conventions (no blank lines between code blocks, minimal comments, factor duplication into shared functions in examples)
Scale/Scope: Covers all module categories and active hosts; includes constitution, reference map, and workflow playbooks

Constitution Check

GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.

Constitution in .specify/memory/constitution.md is a placeholder; default gate is adherence to repo conventions captured in the feature spec (no duplicate code without functions/factories, no blank lines between blocks, minimal comments).
Plan activities are documentation-only and respect these conventions. Gate: PASS (no violations).
Post-design re-check: PASS (generated docs/templates only).

Project Structure

Documentation (this feature)

specs/[###-feature]/
├── plan.md              # This file (/speckit.plan command output)
├── research.md          # Phase 0 output (/speckit.plan command)
├── data-model.md        # Phase 1 output (/speckit.plan command)
├── quickstart.md        # Phase 1 output (/speckit.plan command)
├── contracts/           # Phase 1 output (/speckit.plan command)
└── tasks.md             # Phase 2 output (/speckit.tasks command - NOT created by /speckit.plan)

Source Code (repository root)

docs/                    # Human/AI-facing constitutional docs (to be added)
specs/
└── 001-ai-docs/         # Feature-specific planning and outputs
    ├── plan.md
    ├── research.md
    ├── data-model.md
    ├── quickstart.md
    └── contracts/       # Documentation contracts/templates for AI use-cases

Structure Decision: Documentation-first; all outputs live under specs/001-ai-docs/ with future AI-facing constitution placed in docs/. No application code changes in this plan.

Complexity Tracking

Fill ONLY if Constitution Check has violations that must be justified

Violation	Why Needed	Simpler Alternative Rejected Because
[e.g., 4th project]	[current need]	[why 3 projects insufficient]
[e.g., Repository pattern]	[specific problem]	[why direct DB access insufficient]

3.7 KiB Raw Blame History