DevRunbook-Public/IMPLEMENTATION_PLAN.md

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.