init

specs/001-ai-docs/tasks.md

@@ -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.