95 lines
7.3 KiB
Markdown
95 lines
7.3 KiB
Markdown
# Feature Specification: AI-Facing Repository Constitution
|
||
|
||
**Feature Branch**: `001-ai-docs`
|
||
**Created**: 2026-01-30
|
||
**Status**: Draft
|
||
**Input**: User description: "I want to start by creating comprehensive documentation targeted to AI, this documentation should include the context of how this repository works the logic and rules (both written and unwritten), and the location of where use cases such as adding a new module, would go. The end goal will be to build a mcp with this documentation, but not yet."
|
||
|
||
## Clarifications
|
||
|
||
### Session 2026-01-30
|
||
|
||
- Q: How to handle conflicts between human-facing docs and the AI-facing constitution? → A: Constitution is authoritative for AI; if human docs disagree, update both with a recorded resolution.
|
||
|
||
## User Scenarios & Testing *(mandatory)*
|
||
|
||
### User Story 1 - AI reads the constitution (Priority: P1)
|
||
|
||
An AI assistant loads a single constitution document to understand repository-wide rules, conventions, and architecture so it can answer questions and generate correct changes without human context.
|
||
|
||
**Why this priority**: Without a trustworthy root document, AI-driven edits risk violating repo rules or duplicating code.
|
||
|
||
**Independent Test**: Provide only the constitution to an AI and ask for the steps to add a new server module; the AI should return steps that follow documented rules (e.g., use mkserver, no blank lines, secureHost gating).
|
||
|
||
**Acceptance Scenarios**:
|
||
|
||
1. **Given** the constitution is available, **When** an AI is asked to summarize how reverse proxies are chosen, **Then** it cites the documented proxy types and mainServer/IP rules.
|
||
2. **Given** the constitution is available, **When** an AI is asked where secrets for a new service go, **Then** it names the correct secrets file based on the documented mapping.
|
||
|
||
---
|
||
|
||
### User Story 2 - AI knows where to place use cases (Priority: P2)
|
||
|
||
An AI can locate and follow guidance on where to document workflows such as adding a module, host, or script, including which folder to use and what schema to follow.
|
||
|
||
**Why this priority**: Clear placement rules prevent scattered or conflicting AI-authored docs and keep automation predictable.
|
||
|
||
**Independent Test**: Ask an AI, “Where do I document adding a new NixOS server module?”; it should point to the specified `/docs` or `/specs` location and expected template sections.
|
||
|
||
**Acceptance Scenarios**:
|
||
|
||
1. **Given** the documentation set, **When** an AI searches for “add module” guidance, **Then** it finds the designated playbook location and the required fields to fill.
|
||
2. **Given** a new use case like “add new host toggle,” **When** the AI checks the structure, **Then** it identifies which section/template to extend and what metadata to capture.
|
||
|
||
---
|
||
|
||
### User Story 3 - AI maintains alignment over time (Priority: P3)
|
||
|
||
An AI or contributor can update the constitution and use-case docs when repo rules change, with explicit triggers and review checkpoints to keep AI guidance in sync with code.
|
||
|
||
**Why this priority**: Prevents drift between living code (e.g., new factories, proxy rules) and AI-consumable docs.
|
||
|
||
**Independent Test**: After a rule change (e.g., new secrets file category), the doc update path lists the trigger, target doc, and reviewer checklist without needing additional instructions.
|
||
|
||
**Acceptance Scenarios**:
|
||
|
||
1. **Given** a new helper is added to `parts/core.nix`, **When** the AI follows the maintenance rules, **Then** it updates the constitution and cross-references within one documented cycle.
|
||
2. **Given** conflicting rules are detected, **When** the AI follows conflict-resolution guidance, **Then** it defers to the constitution’s precedence rules and records the resolution location.
|
||
|
||
---
|
||
|
||
### Edge Cases
|
||
|
||
- When human-facing docs and the AI-facing constitution disagree, the constitution is authoritative for AI; reconcile by updating both docs and recording the resolution.
|
||
- What to do when a new module category appears that is not yet mapped in the doc structure.
|
||
- How to handle secureHost-off hosts where secret-driven guidance should be skipped or flagged.
|
||
- What to do when auto-imported modules are added accidentally (guidance on validation and rollback paths).
|
||
|
||
## Requirements *(mandatory)*
|
||
|
||
### Functional Requirements
|
||
|
||
- **FR-001**: Document a single source-of-truth constitution that explains repo architecture (flake-parts, auto-imported modules, hosts/toggles, secureHost, mainServer-driven proxy IP selection) and coding conventions (no blank lines between blocks, comment discipline, factor duplication into functions/factories).
|
||
- **FR-002**: Define terminology and naming standards for this repo (NixOS module vs factory, server options vs service config, toggle sets, host toggles, script units, dev shells) with canonical references to current files.
|
||
- **FR-003**: Specify the documentation IA: what lives in `/docs` vs `/specs`, where AI-facing use-case playbooks go, and how to reference them from the constitution.
|
||
- **FR-004**: Capture unwritten operational rules: secret file roles, secureHost gating, proxy type selection rules, mainServer meaning, uid/gid reproducibility goals, and host activity status.
|
||
- **FR-005**: Provide standard playbook outlines for common workflows (adding NixOS module, server module using mkserver, script unit, host toggle, secrets entry) including required metadata and links to relevant helpers.
|
||
- **FR-006**: Include maintenance triggers and process: when code changes (new factory/helper, new secret category, new toggle), which docs must be updated, and how conflicts are resolved with the constitution as the AI authority (update both human docs and constitution with the recorded decision).
|
||
- **FR-007**: Add a quick-reference index that maps core concerns to files/dirs (e.g., auto-import rules, proxies, firewall generation, stylix schemes, user toggles, secrets locations).
|
||
- **FR-008**: Ensure all required sections are written in business-level, technology-agnostic language suitable for AI ingestion, free of implementation steps.
|
||
|
||
### Key Entities *(include if feature involves data)*
|
||
|
||
- **Constitution**: The AI-facing source-of-truth document describing repo-wide rules, architecture, conventions, and precedence.
|
||
- **Use-case Playbooks**: Structured guides for repeatable workflows (add module/server/script/host/secrets), each with required fields and links back to the constitution.
|
||
- **Reference Map**: Index of repository paths and their responsibilities (modules categories, factories, hosts, secrets, proxies, toggles) used for navigation and validation.
|
||
|
||
## Success Criteria *(mandatory)*
|
||
|
||
### Measurable Outcomes
|
||
|
||
- **SC-001**: An AI with only these docs can describe the correct steps and file locations to add a new server module in under 2 minutes of reading time, matching existing patterns.
|
||
- **SC-002**: The constitution explicitly enumerates 100% of current module categories (apps, dev, scripts, servers, services, shell, network, users, nix), documents the root `patches/` directory, and lists active hosts (emacs, server, workstation, miniserver, galaxy, vps) with their roles.
|
||
- **SC-003**: Guidance includes the full secrets file map (certs/env/gallery/homepage/keys/wireguard/secrets) and secureHost behavior with no omissions when audited against the repository.
|
||
- **SC-004**: Playbook locations and required fields are discoverable via the documented index in ≤2 navigation steps from the top of the spec.
|