# DevRunbook implementation plan This is the authoritative build order. A later milestone may be explored for risk reduction, but it must not be declared complete before all earlier milestone gates pass. ## Milestone 0 — Baseline and repository contract **Objective:** establish a reproducible repository and confirm the specification is internally valid. Tasks: - inventory existing files, tooling and branches; - validate all JSON Schemas, example packages and 28 golden rendered prompts; - select current stable dependency versions and record them; - initialize the exact workspace and root command contract in `docs/40-bootstrap-repository-contract.md`; - configure every required root command, formatting, lint, typecheck, tests and production build; - add the root `.env.example` from `config/env.example`, typed configuration and secret-handling policy; - integrate the preferred Better Auth implementation and implement first-run ownership plus application-owned authorization according to documents 26 and 31; - create the initial database migration from `database/reference-schema.sql`, health endpoints and the first end-to-end vertical slice; - configure CI with the same mandatory checks as local development. Acceptance: - fresh install succeeds from documented commands and the first vertical slice persists across restart; - all baseline checks and reference fixture checks pass; - `/health/live` and `/health/ready` have defined behavior; - no application secret is committed; - `CURRENT_STATE.md` contains the established baseline. ## Milestone 1 — Domain core and Playbook Package ingestion **Objective:** implement the canonical content model before building the full UI. Tasks: - implement schema validation and semantic validation; - import built-in playbooks from the content directory; - store immutable playbook versions and searchable projections; - expose list, detail and validation APIs; - implement lifecycle states and compatibility metadata; - add content digest and duplicate-version protection; - import all 28 P0 packages from `content/playbooks/`; - validate the 72-entry roadmap catalog separately and never expose backlog entries as executable playbooks. Acceptance: - valid packages import idempotently; - invalid packages return actionable path-based errors; - published versions cannot be changed in place; - all 28 publishable P0 packages are indexed and cross-checked against the roadmap catalog; - unit and integration tests cover versioning and invalid input. ## Milestone 2 — Library Explorer and playbook detail **Objective:** deliver the first premium end-user experience. Tasks: - global shell, navigation, command palette and theme support; - library search, faceted filtering, sorting and saved favorites; - playbook cards and compact list view; - playbook detail with purpose, use cases, exclusions, risks, inputs, validation and history; - empty, loading, error and degraded states; - responsive and keyboard-complete behavior. Acceptance: - search and filters are reflected in the URL; - browser refresh preserves the view; - no-results states explain how to recover; - accessibility checks and representative keyboard flows pass; - content remains readable at narrow and wide desktop sizes. ## Milestone 3 — Repository profiles **Objective:** let users store reusable context without connecting a live repository. Tasks: - profile creation wizard and manual editing; - stack, commands, protected paths, policies and validation commands; - profile snapshots used by generated runs; - JSON/YAML import and export; - conflict and validation messaging; - repository workspace overview. Acceptance: - editing a profile does not alter historical generated runs; - invalid commands and paths are clearly identified; - profile export round-trips without data loss; - protected paths are visibly surfaced in the composer. ## Milestone 4 — Guided Composer and deterministic prompt engine **Objective:** turn a playbook plus context into a verifiable task contract. Tasks: - multi-step composer with autosaved draft; - input resolution, compatibility check and autonomy selection; - deterministic prompt block assembly; - untrusted-context boundaries and redaction; - prompt linting with blocking errors and warnings; - live preview, block outline and provenance inspector; - immutable generated-run snapshot and digest. Acceptance: - the same normalized inputs produce byte-identical output; - missing required inputs prevent generation; - repository text cannot inject system-level instructions; - every generated prompt contains mission, scope, constraints, workflow, validation, done-when and reporting sections unless the playbook type explicitly exempts one; - linter findings link to the relevant composer control. ## Milestone 5 — Export and Run Packs **Objective:** make generated output directly usable in Codex workflows. Tasks: - copy plain prompt; - export rendered Markdown; - generate Run Pack ZIP and manifest; - optional AGENTS.md recommendation export; - import and verify a previously generated Run Pack; - safe filenames, path traversal protection and size limits; - generation history and artifact download controls. Acceptance: - ZIPs contain only declared files; - manifest digests verify after export and re-import; - ZIP-slip and symlink tests pass; - clipboard and download actions have clear success/error feedback; - generated artifacts never include stored integration secrets. ## Milestone 6 — Gitea read-only integration **Objective:** create repository-aware profiles without allowing code changes. Tasks: - Gitea connection setup with version/capability detection; - encrypted token storage and connection test; - repository discovery and selection; - read-only metadata, file and governance inspection; - snapshot import into repository profiles; - health findings and recommended playbooks; - rate-limit, permission and unavailable-state handling. Acceptance: - minimal read-only permissions are documented; - no write endpoint is called; - tokens are redacted from logs and UI responses; - unsupported capabilities degrade individually; - snapshots retain source evidence and collection timestamp. ## Milestone 7 — Prompt Lab and quality system **Objective:** support professional authoring, review and evaluation. Tasks: - private playbook editor; - schema-aware YAML and Markdown editing; - lint, preview and test fixtures; - version comparison and changelog; - review status and quality matrix; - evaluation-case storage and result display; - import/export authoring workflow. Acceptance: - drafts cannot masquerade as validated content; - changing a published playbook creates a new version; - evaluation evidence is traceable to playbook version and fixture version; - editor errors are line/field specific; - a reviewer can reproduce the rendered prompt from stored inputs. ## Milestone 8 — Hardening, operations and release candidate **Objective:** prove that the platform is operable and safe to self-host. Tasks: - threat-model review and security tests; - structured logging, metrics and audit events; - database migration and rollback rehearsal; - backup and restore validation; - clean-room Docker and Unraid deployment test; - performance test using at least 10,000 indexed playbook versions; - browser regression suite for critical flows; - dependency, license and secret scans; - operator documentation and release notes. Acceptance: - all items in `docs/19-acceptance-criteria.md` pass or have an explicit accepted exception; - no critical/high unresolved security finding attributable to the product; - clean deployment and restore are evidenced; - production build and container health checks pass; - final handoff accurately states limitations and future milestones. ## Post-audit milestones The 2026-07-29 audit changes the immediate priority from feature expansion to product simplification, automation and trustworthy release evidence. The full roadmap, phase gates, metrics and audit mapping are normative in `docs/51-post-audit-product-roadmap.md`. Ordered delivery: 1. **Milestone 9 — Release-gate stabilization** 2. **Milestone 10 — Two-choice simple task flow** 3. **Milestone 11 — Scalable project selection and real identity** 4. **Milestone 12 — Plain-language navigation and localization** 5. **Milestone 13 — Continuous repository freshness** 6. **Milestone 14 — Accessibility and interaction regression** 7. **Milestone 15 — Human operations and deployment hardening** 8. **Milestone 16 — Post-audit release qualification** Only after Milestone 16 may strategic expansion proceed: - Milestone 17 — Codex-native exports; - Milestone 18 — controlled local execution bridge; - Milestone 19 — teams and governance; - Milestone 20 — multi-forge and ecosystem; - Milestone 21 — isolated evaluation runner. Vector search, public marketplace behavior, unreviewed AI publication, Kubernetes as a required target, arbitrary server-side execution, direct forge writes, automatic merging and billing remain deferred.