# 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

<!--
  ACTION REQUIRED: Replace the content in this section with the technical details
  for the project. The structure here is presented in advisory capacity to guide
  the iteration process.
-->

**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)

```text
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)

```text
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] |