75 lines
3.7 KiB
Markdown
75 lines
3.7 KiB
Markdown
# 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] |
|