Publish DevRunbook source

docs/00-product-vision.md

@@ -0,0 +1,125 @@
+# 00 — Product vision
+
+## Product thesis
+
+Software-development agents are capable of substantial work, but results still depend heavily on how a task is framed. Users repeatedly spend time restating repository rules, scope limits, validation commands, safety conditions and final-report expectations. Generic prompt libraries solve only the wording problem. They do not solve task contracting, repository adaptation, repeatability, quality evidence or organizational governance.
+
+DevRunbook turns a development intention into a structured execution contract.
+
+> **From intent to verified change.**
+
+The platform combines a versioned playbook, repository profile, user inputs, autonomy selection, risk controls and validation policy. It then renders a deterministic prompt or Run Pack that can be copied into Codex or, in later phases, handed to a controlled Codex integration.
+
+## Product category
+
+DevRunbook should be positioned as an **agentic development playbook platform**, not as:
+
+- a prompt marketplace;
+- a chat interface;
+- an IDE replacement;
+- a remote code-execution service;
+- a generic documentation wiki.
+
+Its closest mental models are an operational runbook system, a policy-aware task composer and a quality registry for reusable agent workflows.
+
+## Primary value proposition
+
+For an individual developer or technical operator:
+
+- stop rewriting the same instructions;
+- obtain a complete task with explicit done-when criteria;
+- adapt proven procedures to each repository;
+- choose how autonomous Codex may be;
+- export a prompt, AGENTS.md suggestion or structured Run Pack;
+- retain a history of exactly what was generated.
+
+For a team:
+
+- encode reviewable engineering standards;
+- publish approved playbook versions;
+- require safety and validation blocks;
+- share repository profiles and command conventions;
+- evaluate playbooks against fixtures;
+- prove which version and context produced a result.
+
+## North-star experience
+
+A user types:
+
+> “Clean up this TypeScript monorepo without changing behavior.”
+
+DevRunbook recognizes the likely task, proposes the **Repository Hygiene and Dead-Code Cleanup** playbook, loads the selected repository profile, detects that the project uses pnpm, Turborepo and Vitest, highlights protected directories, lets the user choose **Verify** autonomy, and generates a task containing:
+
+- pre-change inventory;
+- explicit behavioral-preservation constraints;
+- dependency and dead-code workflow;
+- package-specific validation commands;
+- failure-recovery rules;
+- a completion contract;
+- a structured final report.
+
+The user can inspect where every generated section came from and export it as a multi-file Run Pack.
+
+## Product principles
+
+### 1. Structured before clever
+
+The platform should prefer a clear task contract over magical prompt rewriting. AI-assisted suggestions may help select or populate a playbook, but the final output remains inspectable and deterministic.
+
+### 2. Verification is not optional decoration
+
+Implementation playbooks must define how success is demonstrated. “Make it work” is not an acceptance criterion.
+
+### 3. Context has provenance
+
+Every repository fact included in a generated task records whether it was manually entered, imported from a profile, observed through Gitea or inferred. Imported text is clearly delimited as untrusted evidence.
+
+### 4. Safe autonomy rather than false control
+
+The user chooses an autonomy level with concrete permissions and behavior, not a vague “agent mode” switch.
+
+### 5. Quality over catalog size
+
+A smaller set of reviewed and evaluated playbooks is preferable to thousands of near-duplicate community prompts.
+
+### 6. Local-first trust
+
+The reference product is self-hostable. A user can operate the library, profiles, composer and exports without sending repository content to an additional SaaS service.
+
+### 7. Honest capability boundaries
+
+The product must distinguish static guidance, imported evidence, actual evaluations and user feedback. It must not label a playbook “verified” merely because its text looks comprehensive.
+
+## Success metrics
+
+Initial product metrics:
+
+- median time from task selection to export;
+- percentage of generated tasks passing prompt lint without manual correction;
+- number of repeated uses per playbook;
+- number of follow-up prompts required after a generated task;
+- user-reported scope adherence;
+- percentage of generated tasks with complete validation evidence;
+- repository-profile reuse rate;
+- seed-catalog import and render success rate.
+
+Longer-term quality metrics:
+
+- fixture success by playbook version;
+- regression rate between playbook versions;
+- percentage of changes limited to declared scope;
+- false-positive and false-negative rates for audit playbooks;
+- rate of blocked unsafe exports;
+- reproducibility of generated output from stored snapshots.
+
+## Non-goals for the MVP
+
+- executing arbitrary repository commands;
+- cloning untrusted repositories into a privileged host;
+- acting as a full Git forge;
+- replacing code review;
+- guaranteeing security or compliance certification;
+- automatically publishing community content;
+- supporting every coding agent from day one;
+- introducing a vector database without demonstrated search need;
+- billing, public marketplace or complex SaaS tenancy.