jawz/NixOS
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

init

Browse Source
This commit is contained in:
Danilo Reyes
2026-01-30 16:31:02 -06:00
parent 93411591ef
commit 5da9abf1b7
21 changed files with 2509 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

34
specs/001-ai-docs/checklists/requirements.md Normal file
View File

@@ -0,0 +1,34 @@
# Specification Quality Checklist: AI-Facing Repository Constitution
**Purpose**: Validate specification completeness and quality before proceeding to planning
**Created**: 2026-01-30
**Feature**: specs/001-ai-docs/spec.md
## Content Quality
- [x] No implementation details (languages, frameworks, APIs)
- [x] Focused on user value and business needs
- [x] Written for non-technical stakeholders
- [x] All mandatory sections completed
## Requirement Completeness
- [x] No [NEEDS CLARIFICATION] markers remain
- [x] Requirements are testable and unambiguous
- [x] Success criteria are measurable
- [x] Success criteria are technology-agnostic (no implementation details)
- [x] All acceptance scenarios are defined
- [x] Edge cases are identified
- [x] Scope is clearly bounded
- [x] Dependencies and assumptions identified
## Feature Readiness
- [x] All functional requirements have clear acceptance criteria
- [x] User scenarios cover primary flows
- [x] Feature meets measurable outcomes defined in Success Criteria
- [x] No implementation details leak into specification
## Notes
- All checklist items validated and passing.

26
specs/001-ai-docs/contracts/docs-contract.md Normal file
View File

@@ -0,0 +1,26 @@
# Documentation Contract: AI-Facing Repository Constitution
## Constitution Document
- **Purpose**: Authoritative AI guide for repo rules, architecture, conventions, and precedence.
- **Required Sections**:
- Scope and audience (AI tools)
- Repo overview (flake-parts, auto-imported modules, hosts/toggles, mainServer/proxy rules)
- Coding conventions (no blank lines between blocks, minimal comments, factor duplication via functions/factories)
- Secrets map (certs/env/gallery/homepage/keys/wireguard/secrets) and secureHost behavior
- Active hosts and module categories coverage
- Precedence and conflict resolution (constitution over human docs for AI)
- Maintenance triggers and update process
- Quick-reference index linking to repo paths and playbooks
## Use-case Playbooks
- **Purpose**: Step-by-step workflows for common tasks (add module/server/script/host/secrets).
- **Required Fields**: Name, prerequisites (toggles/hosts/secureHost), inputs, steps, outputs, references to helpers (e.g., mkserver, auto-import), secrets placement, validation checklist.
- **Location**: `/docs` (linked) or `/specs/001-ai-docs` as interim until promoted.
## Reference Map
- **Purpose**: Index for navigation.
- **Required Fields**: Category → repo path(s), notes on auto-import filters, proxy type mapping, firewall rules generation, stylix schemes location, active hosts.
## Validation
- **Checklist Alignment**: Must satisfy feature success criteria (coverage completeness, discoverability ≤2 steps, secrets map completeness).
- **Review**: Manual review against requirements and this contract; record conflicts and resolutions.

22
specs/001-ai-docs/data-model.md Normal file
View File

@@ -0,0 +1,22 @@
# Data Model: AI-Facing Repository Constitution
## Entities
### Constitution
- **Role**: Source of truth for AI about repository rules, architecture, conventions, precedence.
- **Key Fields**: scope (modules, hosts, secrets, proxies), conventions (no blank lines, comment discipline, factor duplication), precedence (constitution over human docs for AI), update triggers, references index, success criteria links.
- **Relationships**: Links to Use-case Playbooks and Reference Map; references repo paths.
### Use-case Playbook
- **Role**: Workflow guide for repeatable actions (add module/server/script/host/secrets).
- **Key Fields**: use-case name, required inputs, steps, expected outputs, related helpers (e.g., mkserver), secrets mapping, host/toggle implications.
- **Relationships**: References Constitution for rules and Reference Map for file locations.
### Reference Map
- **Role**: Index mapping core concerns to repo paths for navigation and validation.
- **Key Fields**: category (apps, dev, scripts, servers, services, shell, network, users, nix, patches), hosts list (emacs, server, workstation), secrets files, proxy rules, auto-import rules, stylix/schemes.
- **Relationships**: Anchors citations used by Constitution and Playbooks.
## Constraints and States
- **Lifecycle**: Constitution updates trigger playbook/index updates; playbooks evolve with new workflows; reference map updates when repo structure changes.
- **Validation Rules**: Constitution must enumerate all categories/hosts; secrets map must be complete; discoverability within two steps; precedence must be explicit.

74
specs/001-ai-docs/plan.md Normal file
View File

@@ -0,0 +1,74 @@
# 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] |

7
specs/001-ai-docs/quickstart.md Normal file
View File

@@ -0,0 +1,7 @@
# Quickstart: AI-Facing Repository Constitution
1) Read the constitution (`docs/constitution.md`) to understand repo rules, conventions, and precedence for AI.
2) Use the reference map (`docs/reference/index.md`) to locate relevant paths (module categories, hosts, secrets files, proxy rules, stylix schemes).
3) Follow the appropriate use-case playbook (adding module/server/script/host/secrets) under `docs/playbooks/`; ensure steps reference helpers (e.g., mkserver) and secrets placement.
4) Validate against the checklist: full category/host coverage, secrets map completeness, discoverability within two navigation steps, constitution precedence defined.
5) When repo structure or rules change, update constitution, playbooks, and reference map together, logging the decision in Clarifications.

16
specs/001-ai-docs/research.md Normal file
View File

@@ -0,0 +1,16 @@
# Research Findings: AI-Facing Repository Constitution
## Decision 1: Constitution is authoritative for AI
- **Decision**: AI-facing constitution overrides conflicting human docs for AI guidance; conflicts trigger updates to both with recorded resolution.
- **Rationale**: Ensures consistent automated actions and avoids drift between AI behavior and repo rules.
- **Alternatives considered**: (a) Defer to human docs and mirror later (rejected: increases drift); (b) Split authority by domain (rejected: adds ambiguity for AI tools).
## Decision 2: Documentation IA
- **Decision**: Place the living constitution in `/docs`; keep feature-specific planning/playbooks under `specs/001-ai-docs/` with index links in constitution.
- **Rationale**: Clear separation of durable source-of-truth vs feature-level artifacts; aligns with spec expectations.
- **Alternatives considered**: (a) Keep all AI docs in `/specs` (rejected: mixes planning with durable guidance); (b) Distribute docs per module directory (rejected: harder AI discoverability).
## Decision 3: Validation approach
- **Decision**: Validate docs manually against repo conventions and the specification’s success criteria (discoverability ≤2 steps, full module/host coverage, secrets map completeness).
- **Rationale**: No automated tests for markdown; checklist-based review matches spec.
- **Alternatives considered**: (a) Add automated linting now (rejected: out-of-scope for this documentation feature); (b) No validation (rejected: risks drift and omissions).

94
specs/001-ai-docs/spec.md Normal file
View File

@@ -0,0 +1,94 @@
# 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, patches) and active hosts (emacs, server, workstation) 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.

137
specs/001-ai-docs/tasks.md Normal file
View File

@@ -0,0 +1,137 @@
# Tasks: AI-Facing Repository Constitution
**Input**: Design documents from `/specs/001-ai-docs/`
**Prerequisites**: plan.md (required), spec.md (required for user stories), research.md, data-model.md, contracts/
**Tests**: Tests are optional; not requested in the spec. No explicit test tasks included.
**Organization**: Tasks are grouped by user story to enable independent implementation and testing of each story.
## Format: `[ID] [P?] [Story] Description`
- **[P]**: Can run in parallel (different files, no dependencies)
- **[Story]**: Which user story this task belongs to (e.g., US1, US2, US3)
- Include exact file paths in descriptions
## Path Conventions
- Documentation lives under `docs/` (constitution and playbooks) and `specs/001-ai-docs/` (planning artifacts and interim docs).
---
## Phase 1: Setup (Shared Infrastructure)
**Purpose**: Prepare documentation scaffolding and locations.
- [ ] T001 Create `docs/` constitution folder structure per plan (docs/)
- [ ] T002 Create `docs/` playbooks subfolder for workflows (docs/playbooks/)
- [ ] T003 Create `docs/` reference-map subfolder for indexes (docs/reference/)
- [ ] T004 Link feature artifacts index in specs/001-ai-docs/quickstart.md to future docs/ locations (specs/001-ai-docs/quickstart.md)
---
## Phase 2: Foundational (Blocking Prerequisites)
**Purpose**: Shared artifacts all user stories rely on.
- [ ] T005 Draft constitution outline with required sections and precedence statement (docs/constitution.md)
- [ ] T006 Populate secrets map structure and secureHost rules placeholder (docs/constitution.md)
- [ ] T007 Add reference map skeleton covering modules, hosts, secrets, proxies, stylix (docs/reference/index.md)
- [ ] T008 Add playbook template covering required fields (docs/playbooks/template.md)
**Checkpoint**: Foundation ready - user story implementation can now begin in parallel.
---
## Phase 3: User Story 1 - AI reads the constitution (Priority: P1) 🎯 MVP
**Goal**: Single constitution document for AI with repo rules, architecture, conventions, and precedence.
**Independent Test**: With only docs/constitution.md, an AI can answer proxy selection, secrets placement, and module-add steps within repo rules.
### Implementation for User Story 1
- [ ] T009 [US1] Fill constitution scope, audience, repo overview (flake-parts, auto-imports, hosts/toggles, mainServer/proxy rules) (docs/constitution.md)
- [ ] T010 [US1] Document coding conventions (no blank lines between blocks, comment discipline, factor duplication via functions/factories) (docs/constitution.md)
- [ ] T011 [US1] Define canonical terminology and naming standards for modules, factories, options, toggles, servers, scripts, playbooks (docs/constitution.md)
- [ ] T012 [US1] Document secrets map and secureHost behavior (certs/env/gallery/homepage/keys/wireguard/secrets) (docs/constitution.md)
- [ ] T013 [US1] Enumerate module categories and active hosts with roles (docs/constitution.md)
- [ ] T014 [US1] Add precedence/conflict resolution section (constitution over human docs for AI) (docs/constitution.md)
- [ ] T015 [US1] Add maintenance triggers and update process (docs/constitution.md)
- [ ] T016 [US1] Add quick-reference index linking to playbooks and reference map (docs/constitution.md)
**Checkpoint**: Constitution stands alone for AI queries.
---
## Phase 4: User Story 2 - AI knows where to place use cases (Priority: P2)
**Goal**: Playbooks and reference map guide AI to the right locations/templates for workflows.
**Independent Test**: AI can locate the correct doc and fields for “add module/server/script/host/secrets” without extra context.
### Implementation for User Story 2
- [ ] T017 [US2] Write playbook for adding a NixOS module (docs/playbooks/add-module.md)
- [ ] T018 [US2] Write playbook for adding a server module using mkserver (docs/playbooks/add-server.md)
- [ ] T019 [US2] Write playbook for adding a script unit (docs/playbooks/add-script.md)
- [ ] T020 [US2] Write playbook for adding a host toggle and host wiring (docs/playbooks/add-host-toggle.md)
- [ ] T021 [US2] Write playbook for secrets entry mapping to files (docs/playbooks/add-secret.md)
- [ ] T022 [US2] Fill reference map entries for module dirs, auto-import filters, proxy types, firewall generation, stylix schemes, hosts (docs/reference/index.md)
- [ ] T023 [US2] Link playbooks and reference map from constitution index (docs/constitution.md)
**Checkpoint**: Playbooks and reference map make placement and schema discoverable.
---
## Phase 5: User Story 3 - AI maintains alignment over time (Priority: P3)
**Goal**: Process to keep AI docs synced with repo changes and resolve conflicts.
**Independent Test**: After a rule change, the docs update path is clear (trigger → target docs → reviewer checklist) without extra guidance.
### Implementation for User Story 3
- [ ] T024 [US3] Add maintenance triggers list (new factory/helper, new secret category, new toggle, new host/module dir) (docs/constitution.md)
- [ ] T025 [US3] Add update workflow/checklist for constitution, playbooks, reference map (docs/constitution.md)
- [ ] T026 [US3] Add conflict-resolution steps and logging guidance in constitution (docs/constitution.md)
- [ ] T027 [US3] Add quick audit checklist to reference map for drift detection (docs/reference/index.md)
- [ ] T028 [US3] Update quickstart.md with maintenance flow summary (specs/001-ai-docs/quickstart.md)
**Checkpoint**: Maintenance and conflict resolution are documented and repeatable.
---
## Phase N: Polish & Cross-Cutting Concerns
**Purpose**: Final alignment and validation across documents.
- [ ] T029 [P] Cross-check constitution, playbooks, reference map against SC-001–SC-004 and FR-008 (docs/constitution.md, docs/playbooks/, docs/reference/index.md)
- [ ] T030 [P] Ensure discoverability ≤2 navigation steps from top-level docs (docs/)
- [ ] T031 [P] Validate business-level, tech-agnostic language per FR-008 across all docs (docs/)
- [ ] T032 [P] Update specs/001-ai-docs/research.md with any decisions made during authoring (specs/001-ai-docs/research.md)
- [ ] T033 [P] Update specs/001-ai-docs/data-model.md if entities/fields changed (specs/001-ai-docs/data-model.md)
- [ ] T034 Final proofread and format pass (docs/)
---
## Dependencies & Execution Order
### Phase Dependencies
- Setup → Foundational → User Stories (P1 → P2 → P3) → Polish
### User Story Dependencies
- US1 has no story dependency (MVP). US2 builds on US1 artifacts (constitution index). US3 builds on US1/US2.
### Parallel Opportunities
- Setup tasks T001–T004 can run in parallel.
- Foundational tasks T005–T008 can run in parallel.
- Within US1, T009–T016 mostly sequential; minor parallelization on subsections if coordinated.
- US2 playbooks (T017–T021) parallelizable; reference map (T022) depends on prior structure; linking (T023) last.
- US3 tasks can largely parallelize T024–T027; quickstart update (T028) after others.
- Polish tasks T029–T033 parallel; T034 last.
## Implementation Strategy
- Deliver MVP with US1 (constitution) first.
- Add placement guidance (US2) next.
- Add maintenance/conflict process (US3), then polish.