126 lines
5.2 KiB
Markdown
126 lines
5.2 KiB
Markdown
# 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.
|