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.