# 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.