7.0 KiB
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) andspecs/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.