DevRunbook-Public/docs/01-product-requirements.md

# 01 — Product requirements

## Scope definition

The MVP provides a complete path from curated playbook discovery to repository-aware prompt export. Direct Codex execution, team approvals and public community distribution are later phases.

## Functional requirements

### Library and discovery

- **FR-LIB-001:** Index all valid built-in and private playbook versions.
- **FR-LIB-002:** Search title, summary, tags, category, problem statement and supported stacks.
- **FR-LIB-003:** Filter by category, lifecycle, risk tier, autonomy support, playbook type, stack and quality status.
- **FR-LIB-004:** Sort by relevance, recently updated, title and quality status.
- **FR-LIB-005:** Persist search and filter state in the URL.
- **FR-LIB-006:** Allow personal favorites and collections.
- **FR-LIB-007:** Show why a playbook matches a repository or query.
- **FR-LIB-008:** Prevent deprecated playbooks from appearing as default recommendations.

### Playbook detail

- **FR-DET-001:** Show purpose, expected outcome and explicit non-goals.
- **FR-DET-002:** Show required and optional inputs.
- **FR-DET-003:** Show supported modes and autonomy levels.
- **FR-DET-004:** Show risk tier, guardrails, validation and completion contract.
- **FR-DET-005:** Show compatible stacks and known limitations.
- **FR-DET-006:** Show version, lifecycle, changelog and quality evidence.
- **FR-DET-007:** Allow a user to start composition with or without a repository profile.

### Repository profiles

- **FR-REP-001:** Create profiles manually without connecting a forge.
- **FR-REP-002:** Store languages, frameworks, package managers, services, databases and deployment types.
- **FR-REP-003:** Store setup, lint, typecheck, test, build and smoke-test commands.
- **FR-REP-004:** Store protected paths, excluded paths and policy constraints.
- **FR-REP-005:** Store source metadata and evidence timestamp.
- **FR-REP-006:** Version profile snapshots for generated runs.
- **FR-REP-007:** Import and export a schema-validated profile.
- **FR-REP-008:** Allow manual overrides without destroying source observations.

### Composer

- **FR-COM-001:** Resolve playbook inputs through a guided form.
- **FR-COM-002:** Select a repository profile or operate profile-free.
- **FR-COM-003:** Select work mode and autonomy level.
- **FR-COM-004:** Select or confirm scope and protected paths.
- **FR-COM-005:** Preview generated output continuously.
- **FR-COM-006:** Explain the provenance of each generated block.
- **FR-COM-007:** Validate required inputs and compatibility before export.
- **FR-COM-008:** Run prompt lint and distinguish errors from warnings.
- **FR-COM-009:** Autosave a draft locally or server-side.
- **FR-COM-010:** Produce deterministic output from normalized inputs.

### Prompt and Run Pack output

- **FR-OUT-001:** Copy plain prompt text.
- **FR-OUT-002:** Download Markdown.
- **FR-OUT-003:** Generate a ZIP Run Pack with manifest and digests.
- **FR-OUT-004:** Optionally generate AGENTS.md recommendations without overwriting an existing file.
- **FR-OUT-005:** Store an immutable run snapshot.
- **FR-OUT-006:** Re-render a historical run without silently using a newer playbook version.
- **FR-OUT-007:** Re-import a Run Pack and verify its manifest.
- **FR-OUT-008:** Ensure safe filenames and prevent archive traversal.

### Content authoring

- **FR-AUT-001:** Import a Playbook Package from a directory or ZIP.
- **FR-AUT-002:** Validate structural and semantic rules.
- **FR-AUT-003:** Edit private drafts in a schema-aware editor.
- **FR-AUT-004:** Render examples with test input sets.
- **FR-AUT-005:** Publish by creating an immutable semantic version.
- **FR-AUT-006:** Compare versions and require a changelog.
- **FR-AUT-007:** Deprecate without deleting historical versions.
- **FR-AUT-008:** Export a complete package for Git review.

### Gitea integration

- **FR-GIT-001:** Configure a Gitea base URL and token.
- **FR-GIT-002:** Test connectivity and discover server version/capabilities.
- **FR-GIT-003:** List accessible repositories with pagination.
- **FR-GIT-004:** Import repository metadata and selected governance evidence.
- **FR-GIT-005:** Read relevant files through a bounded allowlist and size limits.
- **FR-GIT-006:** Create a timestamped repository snapshot.
- **FR-GIT-007:** Recommend playbooks based on observable gaps.
- **FR-GIT-008:** Remain strictly read-only in the first implementation.

### Quality and evaluations

- **FR-QUA-001:** Lint playbooks and rendered prompts.
- **FR-QUA-002:** Store evaluation cases tied to exact versions.
- **FR-QUA-003:** Show quality dimensions separately rather than one unexplained percentage.
- **FR-QUA-004:** Distinguish authored claims from executed evidence.
- **FR-QUA-005:** Mark stale evidence when its environment or fixture changes.
- **FR-QUA-006:** Block “Validated” status without required evidence.

### Administration and audit

- **FR-ADM-001:** Show integration health and background-job failures.
- **FR-ADM-002:** Record security-relevant audit events.
- **FR-ADM-003:** Allow export and deletion of user-owned data.
- **FR-ADM-004:** Configure retention for generated artifacts and logs.
- **FR-ADM-005:** Expose backup and restore guidance.

## Non-functional requirements

### Reliability

- Generated runs must reference immutable playbook and profile snapshots.
- Import operations must be idempotent.
- A failed background import must not leave a partially published version.
- The app must remain usable when Gitea is unavailable.

### Performance targets

Reference targets on a modest self-hosted system:

- library search P95 below 500 ms with 10,000 indexed playbook versions;
- playbook detail P95 below 400 ms excluding first cold start;
- prompt composition below 250 ms for ordinary packages;
- first meaningful page content below 2.5 seconds on a typical local network;
- ZIP generation below 3 seconds for a standard Run Pack under 5 MB.

These are engineering targets, not user-facing guarantees. Performance tests must record hardware and data shape.

### Security

- integration secrets encrypted at rest;
- secret values never returned after initial storage;
- strict server-side authorization for every workspace resource;
- imported archives and paths treated as hostile;
- no arbitrary command execution in the MVP;
- external URLs validated against SSRF controls;
- sensitive values redacted from logs and generated prompts;
- content security policy and secure cookie defaults.

### Privacy

- no repository content sent to third parties by the reference implementation unless the operator explicitly configures such a service later;
- configurable data retention;
- clear evidence of what Gitea data was imported;
- delete and export workflows for personal data;
- no telemetry by default in self-hosted mode.

### Accessibility and UX

- target WCAG 2.2 AA behavior;
- full keyboard operation for core flows;
- visible focus states;
- reduced-motion support;
- no color-only meaning;
- responsive behavior from laptop to ultrawide screens;
- all destructive actions require explicit confirmation and explain consequences.

### Maintainability

- strict TypeScript and schema validation;
- domain logic outside UI and transport layers;
- documented migrations;
- no circular package dependencies;
- stable adapter interfaces for forge and agent integrations;
- tests at domain, persistence, API and browser-flow levels.

## MVP release boundary

Included:

- single installation with personal workspace support;
- built-in and private playbooks;
- repository profiles;
- composer and exports;
- Run Pack history;
- local authentication;
- optional read-only Gitea integration;
- quality/lint basics;
- Docker/Unraid deployment.

Deferred:

- organization billing;
- public community marketplace;
- direct write operations to Gitea;
- direct Codex code execution;
- multi-agent orchestration;
- scheduled audits;
- public SaaS multitenancy;
- GitHub and GitLab connectors;
- vector search.