138 lines
7.0 KiB
Markdown
138 lines
7.0 KiB
Markdown
# 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.
|
||
|
||
- [X] T001 Create `docs/` constitution folder structure per plan (docs/)
|
||
- [X] T002 Create `docs/` playbooks subfolder for workflows (docs/playbooks/)
|
||
- [X] T003 Create `docs/` reference-map subfolder for indexes (docs/reference/)
|
||
- [X] 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.
|
||
|
||
- [X] T005 Draft constitution outline with required sections and precedence statement (docs/constitution.md)
|
||
- [X] T006 Populate secrets map structure and secureHost rules placeholder (docs/constitution.md)
|
||
- [X] T007 Add reference map skeleton covering modules, hosts, secrets, proxies, stylix (docs/reference/index.md)
|
||
- [X] 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
|
||
|
||
- [X] T009 [US1] Fill constitution scope, audience, repo overview (flake-parts, auto-imports, hosts/toggles, mainServer/proxy rules) (docs/constitution.md)
|
||
- [X] T010 [US1] Document coding conventions (no blank lines between blocks, comment discipline, factor duplication via functions/factories) (docs/constitution.md)
|
||
- [X] T011 [US1] Define canonical terminology and naming standards for modules, factories, options, toggles, servers, scripts, playbooks (docs/constitution.md)
|
||
- [X] T012 [US1] Document secrets map and secureHost behavior (certs/env/gallery/homepage/keys/wireguard/secrets) (docs/constitution.md)
|
||
- [X] T013 [US1] Enumerate module categories and active hosts with roles (docs/constitution.md)
|
||
- [X] T014 [US1] Add precedence/conflict resolution section (constitution over human docs for AI) (docs/constitution.md)
|
||
- [X] T015 [US1] Add maintenance triggers and update process (docs/constitution.md)
|
||
- [X] 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
|
||
|
||
- [X] T017 [US2] Write playbook for adding a NixOS module (docs/playbooks/add-module.md)
|
||
- [X] T018 [US2] Write playbook for adding a server module using mkserver (docs/playbooks/add-server.md)
|
||
- [X] T019 [US2] Write playbook for adding a script unit (docs/playbooks/add-script.md)
|
||
- [X] T020 [US2] Write playbook for adding a host toggle and host wiring (docs/playbooks/add-host-toggle.md)
|
||
- [X] T021 [US2] Write playbook for secrets entry mapping to files (docs/playbooks/add-secret.md)
|
||
- [X] T022 [US2] Fill reference map entries for module dirs, auto-import filters, proxy types, firewall generation, stylix schemes, hosts (docs/reference/index.md)
|
||
- [X] 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
|
||
|
||
- [X] T024 [US3] Add maintenance triggers list (new factory/helper, new secret category, new toggle, new host/module dir) (docs/constitution.md)
|
||
- [X] T025 [US3] Add update workflow/checklist for constitution, playbooks, reference map (docs/constitution.md)
|
||
- [X] T026 [US3] Add conflict-resolution steps and logging guidance in constitution (docs/constitution.md)
|
||
- [X] T027 [US3] Add quick audit checklist to reference map for drift detection (docs/reference/index.md)
|
||
- [X] 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.
|
||
|
||
- [X] 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)
|
||
- [X] T030 [P] Ensure discoverability ≤2 navigation steps from top-level docs (docs/)
|
||
- [X] T031 [P] Validate business-level, tech-agnostic language per FR-008 across all docs (docs/)
|
||
- [X] T032 [P] Update specs/001-ai-docs/research.md with any decisions made during authoring (specs/001-ai-docs/research.md)
|
||
- [X] T033 [P] Update specs/001-ai-docs/data-model.md if entities/fields changed (specs/001-ai-docs/data-model.md)
|
||
- [X] 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.
|