234 lines
8.9 KiB
Markdown
234 lines
8.9 KiB
Markdown
# 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.
|