Skill: sanketsao/prd-for-agents (version 1.0.0)

--- name: prd-for-agents description: > Use this skill whenever an agent or user asks to write, draft, create, or produce a PRD, product requirements document, product spec, or feature spec — especially when the output will be consumed by an AI coding agent, developer agent, or multi-agent pipeline rather than a human PM. Also trigger when asked to "write requirements for X", "spec out X", "define what needs to be built for X", or "create a handoff doc for Developer". This skill produces agent-optimized PRDs that include quantitative success metrics, user stories, open questions, risks, dependencies, and a sequenced build order that a Developer agent can execute directly without clarification. Always use this skill in preference to writing a PRD from scratch — it enforces completeness gaps that generic PRDs miss. --- # PRD for Agents Produces industry-standard, agent-optimized Product Requirements Documents. Built for turning a vision or idea into a specification that AI agents can build from directly — structured, complete, and executable without the agent needing to ask clarifying questions. ## When to Use This Skill - Writing a new PRD for any project or feature - Reviewing or upgrading an existing PRD for completeness - Preparing a handoff document from Architect → Developer agent - Publishing a PRD to GitHub for community or open-source projects ## Output Structure Every PRD produced by this skill follows this exact section order. Load `references/prd-sections.md` for detailed guidance on each section. Load `references/prd-examples.md` for annotated examples of each section done well. ``` 1. Header Block 2. Problem Statement 3. Target Users & Jobs-to-be-Done 4. User Stories 5. Feature List (MVP + Post-MVP) 6. Acceptance Criteria 7. Quantitative Success Metrics 8. Data Schema / API Contracts 9. File & Folder Structure 10. Agent Build Order (sequenced) 11. Phase Map (for projects with >5 features) 12. Assumptions 13. Open Questions 14. Dependencies 15. Risks 16. Out of Scope ``` --- ## Quick Reference: The Gaps Most PRDs Miss These eight sections are present in industry-standard PRDs but missing from most agent-generated ones. Always include all eight. ### 1. User Stories Format: `As a [user type], I want to [action], so that [outcome].` Each story must be independently testable. Pair every Feature (F1, F2…) with at least one user story. See `references/prd-sections.md#user-stories`. ### 2. Quantitative Success Metrics Every metric must have a number, a unit, and a date. ❌ "Dashboard is fast" ✅ "Dashboard loads in < 2s on a 10-project workspace by 2026-06-01" See `references/prd-sections.md#success-metrics`. ### 3. Dependencies List what this project requires that it does not own: - External APIs or services - Other projects or features that must ship first - Infrastructure (runtime, database, auth) - People or approvals Format: `| Dependency | Type | Owner | Required By | Risk if Late |` ### 4. Open Questions Unresolved decisions that could change scope or design. Each question needs: - The question itself - Who owns the answer - A deadline (or "before Developer starts") - Impact if unresolved Format: `| # | Question | Owner | Deadline | Impact if Unresolved |` **Routing rule:** Any OQ with deadline "before Developer starts" must be resolved by Main before this PRD is approved. Tag the PRD submission `#CLARIFY` if any such OQs exist. Do not route to Developer until all are resolved. ### 5. Risks Threats to delivery, quality, or adoption. Each risk needs a likelihood, impact, and mitigation. Format: `| Risk | Likelihood | Impact | Mitigation |` ### 6. Agent Build Order A numbered sequence of tasks in the order a Developer agent should execute them. This is the most critical section for agent handoff — without it, Developer agents pick up tasks out of order and create integration failures. Format: `| Step | Task | Feature | Complexity | Depends On |` ### 7. Assumptions Beliefs the Architect holds as true that have not been explicitly confirmed by Main. Different from Open Questions — assumptions have a working answer, they just need confirmation before they corrupt downstream work silently. Format: `| # | Assumption | Confidence | Confirm With | Impact if Wrong |` **Routing rule:** Any assumption with confidence < High, or any assumption whose "Impact if Wrong" would change architecture or scope, must be confirmed by Main before PRD approval. Tag the PRD submission `#CLARIFY` if any such assumptions exist. ### 8. Phase Map Required for projects with more than 5 MVP features. Breaks the build into phases so Developer works on Phase 1 only, while Main can validate that the overall sequence makes sense before committing to Phase 1 architecture. Format: `| Phase | Scope summary | Depends On | Target | Status |` **Routing rule:** Main must validate the Phase Map before Developer starts Phase 1. Key question Main must answer: "Does Phase 1 deliver standalone value, and would Phase 2+ requirements change the Phase 1 architecture?" If yes — revise before build. --- ## PRD Completeness Checklist Run this checklist before marking a PRD as ready for Developer handoff. A PRD missing any ✅ item should be sent back to Architect. ### Structure - [ ] Header block includes: Project, Version, Status, Author, Approved By, Date - [ ] Problem statement supported by evidence or data, not just assertion - [ ] Target users defined as roles with jobs-to-be-done, not just names - [ ] Every MVP feature has at least one user story - [ ] Every user story has a corresponding acceptance criterion - [ ] Post-MVP items are explicitly listed (not just "future work") ### Metrics - [ ] Every success metric has a numeric target - [ ] Every success metric has a unit (seconds, %, count, etc.) - [ ] Every success metric has a target date or milestone - [ ] North Star metric is identified (the one metric that matters most) ### Handoff Readiness (Agent-Specific) - [ ] Data schema or API contracts are defined (even if minimal) - [ ] File and folder structure is specified - [ ] Agent build order is present and sequenced - [ ] No task in the build order depends on an unresolved open question - [ ] All dependencies are listed with owners and risk flags ### Risk & Uncertainty - [ ] Assumptions section present with confidence levels and impact if wrong - [ ] Any assumption with confidence < High flagged for Main confirmation - [ ] Open questions section present (state "None" explicitly if empty) - [ ] Any OQ with deadline "before Developer starts" flagged with #CLARIFY - [ ] Risks section present with mitigations - [ ] If >5 MVP features: Phase Map present and validated by Main ### PRD Review Loop When Main responds to #CLARIFY submissions, Architect must: - **Confirms as-is** → mark resolved, no PRD change, continue to approval - **Scoped correction** (changes specific sections) → update affected sections, increment version x.y, re-run checklist on changed sections, re-submit - **Broad correction** (changes architecture, scope, or phase structure) → full PRD revision, increment version x+1.0, full re-submit - **Max 3 loops** — if unresolved after 3 iterations, escalate to human operator --- ## Writing Principles These principles apply regardless of project type or domain. **Start with the problem, not the solution.** The problem statement should be provable without the proposed solution existing. If removing the feature list makes the problem statement collapse, rewrite it. **Requirements describe what, not how.** "The system sends a confirmation email" ✅ "The system uses SendGrid to send a confirmation email" ❌ (that's architecture) **One requirement = one thing.** If an acceptance criterion contains "and", split it into two criteria. **Testability is mandatory.** Every acceptance criterion must be verifiable by QA without human judgment. "The UI is clean" is not testable. "All form fields have labels accessible to screen readers" is testable. **Metrics need baselines.** A target without a baseline is unmeasurable. If no baseline exists, state "Baseline to be established in first two weeks of development." --- ## Reference Files | File | Load When | |------|-----------| | `references/prd-sections.md` | Writing or reviewing any PRD section in detail | | `references/prd-examples.md` | Need annotated examples of well-written sections | --- ## Common Commands ``` # Draft a new PRD from a brief "Write a PRD for [project/feature description]" # Upgrade an existing PRD "Review this PRD for completeness gaps" → run checklist above # Handoff readiness check "Is this PRD ready for Developer?" → run Handoff Readiness + Risk & Uncertainty checklists # Clarify submission (when OQs or assumptions need Main resolution) "Submit this PRD for clarification" → tag #CLARIFY, list unresolved items for Main # Specific section help "Write the user stories for this PRD" → load references/prd-sections.md#user-stories "Write success metrics for this PRD" → load references/prd-sections.md#success-metrics "Write the assumptions for this PRD" → load references/prd-sections.md#assumptions "Write the phase map for this PRD" → load references/prd-sections.md#phase-map ```

path: references/prd-examples.md
content: # PRD Examples Reference

Annotated examples of each PRD section done well. Use these as models when writing or reviewing.
All examples use a fictional "Agent Ledger" project — a file-based PSA tracking system for multi-agent foundries.

---

## Problem Statement — Good Example

> The Product Foundry operates with multiple AI agents executing work across concurrent
> projects. Without a structured tracking layer, three compounding problems emerge.
>
> **Gap 1 — No operational record.** Agents start fresh each session with no shared
> awareness of what was done, by whom, or what comes next. In 3 of 5 observed sessions,
> Developer repeated work Architect had already completed. Estimated waste: 30–60 minutes
> per project per week.
>
> **Gap 2 — No cross-project visibility.** An agent starting a new session cannot
> understand what is happening across the Foundry — only within a single project folder.
> The operator has no aggregated readiness signal.
>
> **Gap 3 — No cost awareness.** Token costs accumulate with no attribution to projects
> or features. After a 4-hour session, the operator cannot answer "what did that cost and
> what was it for?"

**Why this works:**
- Three specific, named gaps (not one vague problem)
- Evidence: "3 of 5 observed sessions" — observable, not assumed
- Quantified impact: "30–60 minutes per project per week"
- Each gap is independently real — removing one doesn't invalidate the others

---

## User Stories — Good Examples

```markdown
### US-01 — Session Resumption
**As a** Developer Agent,
**I want to** read a Session Log entry that summarises what was done last session,
**so that** I can resume work in under 30 seconds without re-reading all task history.

**Acceptance:** Given a TRACKING.md with a Session Log entry, Developer can identify
the correct next task without reading any other section.
**Feature:** F8 — Session Handoff Notes
**Priority:** Must Have

---

### US-02 — Cross-Project Visibility
**As a** Product Owner (Human),
**I want to** open one file (DASHBOARD.md) and see the status of all active projects,
**so that** I can do a morning review in under 2 minutes without opening individual project folders.

**Acceptance:** DASHBOARD.md contains all active projects, each with current task status
and assigned agent, updated within the same session as the last status change.
**Feature:** F5 — Dashboard View
**Priority:** Must Have

---

### US-03 — Cost Attribution
**As a** Product Owner (Human),
**I want to** see how many hours each agent has logged against each project,
**so that** I can evaluate which projects are consuming the most agent time and adjust priorities.

**Acceptance:** Agent Summary table in TRACKING.md shows total hours per agent,
reconciling with the sum of individual time log entries (within ±0.1 hours).
**Feature:** F9 — Agent Summary
**Priority:** Should Have
```

**Why these work:**
- Role is specific ("Developer Agent" not just "user")
- "So that" states an outcome, not a feature
- Acceptance line is one sentence and binary (pass/fail)
- Each maps to a numbered feature

---

## Quantitative Success Metrics — Good Example

```markdown
| Metric | Baseline | Target | Target Date | Measurement Method |
|--------|----------|--------|-------------|-------------------|
| ⭐ Agent cold-start context time | ~5 min (re-read all files) | < 30 seconds | 2026-06-01 | Time from session start to first task action, measured across 10 sessions |
| Dashboard staleness (time since last update) | Not tracked | Same session as last status change | 2026-06-01 | Check Last Updated timestamp vs most recent TRACKING.md edit |
| Orphaned tasks (tasks with no parent capability) | Not tracked | 0 per project | 2026-06-01 | Count tasks without a `## Capability:` parent in TRACKING.md |
| Time log tables with correct Total rows | Not tracked | ≥ 95% | 2026-06-01 | Count tables with `\| **Total** \|` row / total tables |
| Dependency violations (blocked task started without clearing) | Not tracked | 0 per sprint | Per sprint review | QA flags during review; count in QA-REPORT.md |
```

**Why this works:**
- ⭐ marks the North Star metric
- Every metric has a number AND a unit AND a date
- Baselines are honest — "Not tracked" with a plan is fine
- Measurement method explains *how* to verify, not just what to measure
- Metrics are outcomes (agent behavior, system state), not outputs (features shipped)

---

## Dependencies — Good Example

```markdown
| Dependency | Type | Owner | Required By | Risk if Late |
|------------|------|-------|-------------|--------------|
| Ollama runtime (local) | Service | Developer machine | Step 1 | Developer agent cannot run local models; all builds fail |
| OpenClaw `read` and `edit` tools | API | OpenClaw gateway | Step 1 | Agents cannot read or write TRACKING.md; entire system non-functional |
| Python 3.x | Library | Developer machine | Step 6 (reporting scripts) | Post-MVP scripts cannot run; MVP unaffected |
| Main agent approval of PRD | Approval | Sanket Sao | Before Developer starts | Developer cannot begin; project stalls |
| `_template/` project scaffold | Feature | Architect (this project) | Step 2 | Developer cannot bootstrap new projects; must create files manually |
```

**Why this works:**
- Every dependency has an owner — no ambiguity about who's responsible
- "Required By" is specific (step number, not just "early")
- "Risk if Late" states the exact downstream impact on the build order

---

## Open Questions — Good Example

```markdown
| # | Question | Owner | Deadline | Impact if Unresolved |
|---|----------|-------|----------|----------------------|
| OQ-1 | Should DASHBOARD.md live at workspace root or inside projects/? Current ARCHITECTURE.md says workspace root but some agents have been writing to projects/DASHBOARD.md. | Architect | Before Developer starts Step 3 | Developer creates file in wrong location; all agents point to different paths |
| OQ-2 | Should the Agent Summary table be manually updated by Architect (current spec) or auto-calculated from time log totals by a script (post-MVP)? If script, should it run at session end as a hook? | Sanket Sao | Before Developer starts Step 7 | If script, adds Step 7a to build order and requires Python dependency |
| ~~OQ-3~~ | ~~Should `On Hold` projects appear in DASHBOARD.md?~~ — **Resolved:** Yes, in a separate section. 2026-04-29. | — | — | — |
```

**Why this works:**
- OQ-1 is specific: names the exact conflict and where it appears
- OQ-2 shows how an open question can branch the build order — critical for agents
- OQ-3 shows resolved format — keep resolved questions for traceability, but strike them through
- Every open question has a deadline tied to a build step, not a calendar date

---

## Risks — Good Example

```markdown
| Risk | Likelihood | Impact | Mitigation |
|------|-----------|--------|------------|
| Local model (gemma4, qwen3.5) fails to correctly format TRACKING.md table syntax | High | High | Include exact table format examples in Architect handoff notes; QA validates all tables in first pass |
| Two agent sessions write to TRACKING.md simultaneously, causing data loss | Low | High | Assign one task per agent at a time (enforced by DASHBOARD.md Active Agents block); Architect reviews for conflicts at session start |
| DASHBOARD.md becomes stale because Architect forgets to regenerate | High | Medium | Add DASHBOARD.md regeneration to Architect's session-end checklist in AGENTS.md; timestamp makes staleness visible |
| File grows too large for local model context window (>50 tasks in one TRACKING.md) | Low (MVP) | Medium | Document 50-task soft limit; post-MVP: split by capability into separate files |
| QA agent misidentifies a logic flaw as a bug, routing to Developer instead of Architect | Medium | Medium | Require QA to include PRD section reference in every escalation tag; Architect reviews all #BUG escalations that touch schema or data model |
```

**Why this works:**
- Risks are specific to *this* system and *these* agents — not generic
- Mitigations are concrete actions with an owner implied
- Likelihood × Impact framing helps prioritize which risks to address first
- Agent-specific risks (local model formatting failures, context window limits) are included

---

## Agent Build Order — Good Example

```markdown
| Step | Task | Feature | Complexity | Depends On |
|------|------|---------|------------|------------|
| 1 | Create `_template/` directory with blank TRACKING.md, PRD.md, VISION.md, MILESTONES.md, STATUS.md, CHANGELOG.md | F6 | S | — |
| 2 | Write TRACKING.md v2 schema with all required fields (Priority, Target Date, Owner, Blockers, Session, Total rows) | F1–F4 | M | Step 1 |
| 3 | Create DASHBOARD.md at workspace root with Foundry Summary, Active Agents, per-project, and Blocked Tasks sections | F5, F10 | M | Step 2 |
| 4 | Add Session Log section to TRACKING.md template (append-only, one row per session) | F8 | S | Step 2 |
| 5 | Add Agent Summary section to TRACKING.md template (per-agent hours + task counts) | F9 | S | Step 2 |
| 6 | Validate all v2 schema fields are present in TRACKING.md and DASHBOARD.md | F1–F5 | S | Steps 3–5 |
| 7 | Update CHANGELOG.md to document v2 schema upgrade | — | S | Step 6 |
| 8 | Update STATUS.md with completed tasks and session log entry | — | S | Step 7 |
```

**Why this works:**
- Foundation first: template scaffold (Step 1) before any content (Step 2+)
- Each step is completable in a single agent session (no multi-hour L tasks without reason)
- Dependencies are explicit — no guessing what must come first
- Steps 6–8 are housekeeping steps (validate, changelog, status) — included, not assumed
- Complexity is honest — M for files that touch multiple sections, S for single-section work


path: references/prd-sections.md
content: # PRD Sections Reference

Detailed guidance for every section in the prd-architect template.

## Table of Contents
1. [Header Block](#1-header-block)
2. [Problem Statement](#2-problem-statement)
3. [Target Users & Jobs-to-be-Done](#3-target-users--jobs-to-be-done)
4. [User Stories](#4-user-stories)
5. [Feature List](#5-feature-list)
6. [Acceptance Criteria](#6-acceptance-criteria)
7. [Success Metrics](#7-success-metrics)
8. [Data Schema & API Contracts](#8-data-schema--api-contracts)
9. [File & Folder Structure](#9-file--folder-structure)
10. [Agent Build Order](#10-agent-build-order)
11. [Dependencies](#11-dependencies)
12. [Open Questions](#12-open-questions)
13. [Risks](#13-risks)
14. [Out of Scope](#14-out-of-scope)

---

## 1. Header Block

Metadata that identifies the document and its state.

```markdown
# PRD — [Project Name]
**Project:** [Name]
**Version:** [1.0, 2.0, etc.]
**Status:** Draft | In Review | Approved | Superseded
**Author:** [Agent or person who wrote it]
**Approved By:** [Product Owner name — leave blank until approved]
**Date:** YYYY-MM-DD
**GitHub:** [repo URL if applicable]
```

**Rules:**
- Version increments on any structural change (new features, removed scope)
- Status must be `Approved` before Developer agent starts work
- Never delete old versions — use CHANGELOG.md to track changes

---

## 2. Problem Statement

The single most important section. Defines why this product exists.

**Structure:**
1. Current state (what is broken or missing today)
2. Impact (who is affected and how badly)
3. Evidence (data, observations, or user research that proves the problem)
4. Gap statement (what is missing that would solve it)

**Rules:**
- Must be provable without the proposed solution existing
- Must name specific users who experience the problem
- Should include at least one data point or observation as evidence
- Max 3 paragraphs — if you need more, the problem is not yet clear

**Anti-patterns:**
❌ "Users need a better way to track projects" (vague, no evidence)
❌ "We should build a dashboard because dashboards are useful" (solution-first)
✅ "Agents start each session with no shared awareness of project state.
   In 3 of 5 observed sessions, Developer repeated work that Architect had
   already completed, because there was no shared tracking file. This adds
   an estimated 30–60 minutes of redundant work per project per week."

---

## 3. Target Users & Jobs-to-be-Done

Who uses this and what they need to accomplish.

**Format:**
```markdown
| User | Job-to-be-Done | Frequency |
|------|----------------|-----------|
| [Role] | [When X, I need to Y, so I can Z] | Daily/Weekly/Per-project |
```

**Rules:**
- Use roles, not names ("Architect Agent", not "Alice")
- Jobs-to-be-done follow the format: "When [trigger], I need to [action], so I can [outcome]"
- Include frequency — it affects prioritization
- For agent-targeted PRDs, always include both agent users AND the human operator

---

## 4. User Stories

Testable expressions of requirements from the user's perspective.

**Format:**
```markdown
### US-01 — [Short Title]
**As a** [user role],
**I want to** [action or capability],
**so that** [outcome or value].

**Acceptance:** [one-line testable criterion that proves this story is done]
**Feature:** F[n] — links to feature list
**Priority:** Must Have | Should Have | Nice to Have
```

**Rules:**
- Every MVP feature (F1, F2…) must have at least one user story
- Each story must be independently testable
- "Acceptance" line is a one-sentence summary — full criteria go in Section 6
- Stories should describe outcomes, not UI specifics
- If a story requires more than 3 days of work, split it

**MoSCoW priority definitions:**
- **Must Have:** Product does not function without this
- **Should Have:** Significant value loss without this, but workarounds exist
- **Nice to Have:** Desirable but not delivery-blocking

---

## 5. Feature List

What the product does, organized by MVP and Post-MVP.

**Format:**
```markdown
### 🟢 MVP Scope

#### F1 — [Feature Name]
[2-3 sentence description of what this feature does and why it's needed]
- Sub-capability 1
- Sub-capability 2

### 🔵 Post-MVP (Out of Scope for V1)
- [Feature name] — [one-line rationale for deferral]
```

**Rules:**
- Features are numbered F1, F2… — referenced by user stories and acceptance criteria
- Each feature description answers: what does it do, not how it works
- Post-MVP items must be explicitly listed — "we'll add more later" is not acceptable
- If a feature has sub-capabilities, list them as bullets
- Complexity estimate (S/M/L) is optional but helpful for Developer agent

---

## 6. Acceptance Criteria

Testable conditions that define when each feature is complete.

**Format:**
```markdown
### F1 — [Feature Name]
- [ ] [Specific, testable condition]
- [ ] [Specific, testable condition]
```

**Rules:**
- Every criterion must be binary — pass or fail, no judgment calls
- Avoid "should" — use "must" or state the condition directly
- Each criterion covers exactly one thing (no "and")
- QA agent uses these as its test cases — write them for QA, not for humans
- If a criterion requires setup or context, add a note: `(requires project with 3+ tasks)`

**Testability test:** Can QA verify this criterion without asking a human what "good" looks like?
- ❌ "Dashboard looks clean and professional"
- ✅ "Dashboard renders without horizontal scroll on a 1280px viewport"
- ✅ "All table columns have header labels"

---

## 7. Success Metrics

How we know the product is working after it ships.

**Format:**
```markdown
| Metric | Baseline | Target | Target Date | Measurement Method |
|--------|----------|--------|-------------|-------------------|
| [What] | [Current state or "TBD — establish in week 1"] | [Number + unit] | [Date or milestone] | [How to measure] |
```

**Rules:**
- Every metric needs: a number, a unit, and a date
- Baseline is required — state "TBD" with a plan if it doesn't exist yet
- North Star metric must be identified (mark with ⭐)
- Metrics should be outcomes (user behavior, system performance), not outputs (features shipped)
- For agent-targeted products: include agent performance metrics, not just user metrics

**Metric categories to consider:**
- **Performance:** latency, throughput, uptime
- **Quality:** error rate, test coverage, defect escape rate
- **Adoption:** active users, feature usage rate, retention
- **Efficiency:** time-on-task, steps-to-complete, support tickets
- **Agent-specific:** cold-start context time, handoff accuracy, session continuity rate

---

## 8. Data Schema & API Contracts

The structure of data the product creates, reads, or exchanges.

**When to include:**
- Any time data is persisted (files, databases, APIs)
- Any time two agents or systems exchange structured data
- Any time a Developer agent needs to know what shape data takes

**Format for file-based schema:**
```markdown
### [File or Record Name]
\`\`\`markdown
**Field:** Value type and constraints
**Field:** Value type and constraints
\`\`\`
```

**Format for API contracts:**
```markdown
### POST /endpoint
**Request:**
\`\`\`json
{ "field": "type — description" }
\`\`\`
**Response:**
\`\`\`json
{ "field": "type — description" }
\`\`\`
**Errors:** 400 if X, 404 if Y
```

**Rules:**
- Define allowed values for enum fields explicitly
- Note which fields are required vs optional
- For file-based systems, show a complete example, not just field names
- Version the schema if it may change (Schema v1, v2…)

---

## 9. File & Folder Structure

The layout of files and directories the Developer agent will create.

**Format:**
```markdown
\`\`\`
project-root/
├── src/
│   ├── [file] — [purpose]
│   └── [file] — [purpose]
├── [file] — [purpose]
└── [file] — [purpose]
\`\`\`
```

**Rules:**
- Every file listed must have a one-line purpose description
- Distinguish between files the Developer creates vs files that already exist
- For agent foundry projects, include workspace files (TRACKING.md, PRD.md) in the tree
- If structure is large, show only the top 2 levels and describe subdirectories

---

## 10. Agent Build Order

The sequence in which a Developer agent should implement features.

**This is the most important section for agent handoff.** Without a build order,
Developer agents pick up tasks in the wrong sequence and create integration failures
that QA cannot resolve without design escalation.

**Format:**
```markdown
| Step | Task | Feature | Complexity | Depends On |
|------|------|---------|------------|------------|
| 1 | [Specific task description] | F[n] | S/M/L | — |
| 2 | [Specific task description] | F[n] | S/M/L | Step 1 |
```

**Complexity definitions:**
- **S (Small):** < 1 hour, single file, no integration
- **M (Medium):** 1–4 hours, multiple files, some integration
- **L (Large):** 4+ hours, cross-cutting concern, significant integration

**Rules:**
- Foundation before features (data models before UI, schema before logic)
- Independent tasks before dependent ones
- Each step should be completable in a single agent session
- If a step depends on an unresolved open question, flag it: `⚠ blocked by OQ-[n]`
- Total steps should map to a realistic session count for the Developer agent

---

## 11. Dependencies

External things this project requires that it does not own.

**Format:**
```markdown
| Dependency | Type | Owner | Required By | Risk if Late |
|------------|------|-------|-------------|--------------|
| [Name] | API / Library / Service / Approval / Feature | [Owner] | [Step or date] | [Impact] |
```

**Dependency types:**
- **API:** External service the product calls (Anthropic, Ollama, GitHub, etc.)
- **Library:** npm/pip package the code imports
- **Service:** Running infrastructure (gateway, database, auth)
- **Approval:** Human sign-off required before proceeding
- **Feature:** Another project feature that must ship first
- **Data:** Dataset or seed data required for the feature to function

**Rules:**
- If a dependency has no owner, escalate to Main before Developer starts
- Note the version or API version where relevant
- "Risk if Late" should be specific: "Developer cannot start Step 4" not just "delay"

---

## 12. Open Questions

Unresolved decisions that could change scope or design.

**Format:**
```markdown
| # | Question | Owner | Deadline | Impact if Unresolved |
|---|----------|-------|----------|----------------------|
| OQ-1 | [Question] | [Role] | [Date or "before Dev starts"] | [What changes] |
```

**Rules:**
- Every open question needs an owner — questions without owners never get answered
- Deadline should be "before Developer starts Step N" for agent-pipeline clarity
- If an open question is resolved, update to: `~~OQ-1~~ — Resolved: [answer] ([date])`
- A PRD with unresolved OQs that affect build order is NOT ready for Developer handoff
- If there are no open questions, state explicitly: `No open questions as of [date]`

---

## 13. Risks

Threats to delivery, quality, or adoption.

**Format:**
```markdown
| Risk | Likelihood | Impact | Mitigation |
|------|-----------|--------|------------|
| [Risk description] | High/Med/Low | High/Med/Low | [Specific action to reduce risk] |
```

**Risk categories to consider:**
- **Technical:** Model capability limits, tool call failures, file conflicts
- **Scope:** Feature creep, unclear requirements, changing priorities
- **Dependency:** External API changes, library deprecations, blocked approvals
- **Agent-specific:** Local model tool-call failures, streaming bugs, context window limits
- **Adoption:** Users not understanding the system, poor documentation

**Rules:**
- Mitigation must be a specific action, not "monitor closely"
- High likelihood + High impact risks should block Developer start until mitigated
- For agent foundry projects, always include a risk for local model capability limits

---

## 14. Out of Scope

Explicit list of things this version does NOT include.

**Format:**
```markdown
- [Item] — [one-line rationale]
```

**Rules:**
- List things that were considered and explicitly deferred, not just random exclusions
- This section protects against scope creep — if it's not listed, it's open to debate
- Reference Post-MVP features here so they're findable in one place
- For agent-targeted PRDs, explicitly state infrastructure constraints:
  "No database, server, or API layer — file-based storage only"


path: README.md
content: # prd-for-agents

> A PRD skill that turns your vision or idea into a specification AI agents can build from directly.

[![ClawHub](https://img.shields.io/badge/ClawHub-prd--for--agents-blue)](https://clawhub.ai/sanketsao/prd-for-agents)
[![License: MIT-0](https://img.shields.io/badge/License-MIT--0-green)](https://spdx.org/licenses/MIT-0.html)
[![OpenClaw](https://img.shields.io/badge/OpenClaw-compatible-orange)](https://openclaw.ai)

---

## What This Is

Most PRD templates are written by human product managers for engineering teams. This skill is different — it produces PRDs based on a vision or idea to be directly consumed by AI agents that are building.

The result is a complete, structured PRD that any agent can pick up and execute without needing clarification from the person who had the original idea.

---

## The Problem It Solves

When you tell your vision or idea to an agent, the builder or developer agent needs more detail at specification level. A raw idea is not enough — the agent needs to know what to build, in what order, what assumptions to validate, and what questions to resolve before writing a line of code.

`prd-for-agents` addresses that gap. It takes a vision and produces a specification structured for agent execution — with the sections that generic PRD templates skip but agents critically need.

---

## Key Additions Over Standard PRD Templates

| Section | Why Agents Need It |
|---------|-------------------|
| **Agent Build Order** | Sequenced task list with complexity and dependencies — builder agent executes in order without guessing |
| **Assumptions** | Beliefs embedded in the vision that need confirmation before build starts — prevents silent scope corruption |
| **Open Questions** | Unresolved decisions with owners and deadlines — flags what must be answered before building begins |
| **Phase Map** | For larger ideas — breaks scope into phases so the agent builds Phase 1 only, with sequence validated upfront |
| **Quantitative Metrics** | Every metric has a number, unit, and date — agent or human can verify without subjective judgment |
| **User Stories** | One per feature, independently testable — maps directly to acceptance criteria the agent checks against |

---

## Routing Rules (for Multi-Agent Pipelines)

When using this skill in a pipeline with an orchestrator or approver agent, built-in routing logic handles the review loop:

- **`#CLARIFY`** — if any Open Question is marked "before build starts", or any Assumption has confidence < High, the PRD should route to an approver agent or human for resolution before the builder starts
- **PRD Review Loop** — responses are classified as Confirms / Scoped Change / Broad Change, each triggering a different update depth (no change / section update / full revision)
- **Max 3 loops** — if unresolved after 3 iterations, escalate to the human operator
- **Phase Map gate** — approver validates phase sequence before Phase 1 begins

These rules are baked into the completeness checklist, not just documentation. If you are running a single-agent setup, treat these as self-review checkpoints before starting the build.

---

## File Structure

```
prd-for-agents/
├── SKILL.md                          ← Main skill file (always loaded)
└── references/
    ├── prd-sections.md               ← Detailed guidance for all 16 sections
    └── prd-examples.md               ← Annotated examples using a real project
```

---

## Installation

**Via ClawHub CLI:**
```bash
openclaw skills install prd-for-agents
```

**Manual:**
```bash
git clone https://github.com/sanketsao/prd-for-agents
cp -r prd-for-agents ~/.openclaw/skills/
```

---

## Usage

Once installed, your agent will use this skill automatically when asked to write a PRD. You can also invoke it explicitly:

```
"Write a PRD for [vision or idea]"
"Review this PRD for completeness gaps"
"Is this PRD ready for the builder agent?"
"Write the assumptions section for this PRD"
"Create a phase map for this PRD"
```

---

## PRD Output Structure

Every PRD produced by this skill follows this section order:

1. Header Block
2. Problem Statement
3. Target Users & Jobs-to-be-Done
4. User Stories
5. Feature List (MVP + Post-MVP)
6. Acceptance Criteria
7. Quantitative Success Metrics
8. Data Schema / API Contracts
9. File & Folder Structure
10. Agent Build Order
11. Phase Map *(for projects with >5 features)*
12. Assumptions
13. Open Questions
14. Dependencies
15. Risks
16. Out of Scope

---

## Completeness Checklist

Before any PRD is handed to a Developer agent, it must pass:

- [ ] All assumptions listed with confidence level and impact if wrong
- [ ] All success metrics have a number, unit, and target date
- [ ] Agent build order present and sequenced (no circular dependencies)
- [ ] No Open Question marked "before Developer starts" left unresolved
- [ ] Phase Map present and Main-validated for projects with >5 features
- [ ] Every MVP feature has at least one user story and one acceptance criterion

---

## Who This Is For

- **Anyone using AI agents to build software** — solo builders, indie hackers, small teams
- **OpenClaw users** running multi-agent setups with separate planner and builder agents
- **Product managers and founders** who want to hand a vision to an agent and get a build-ready spec back
- **Anyone tired of agents asking clarifying questions mid-build** because the original brief wasn't detailed enough

---

## Background

Built as part of the [Product Foundry](https://thebuildereconomist.substack.com) — a multi-agent OpenClaw setup for building software products with AI agents. The insight was simple: agents fail mid-build not because they can't code, but because the specification they were handed was missing the details they needed. This skill closes that gap.

---

## License

MIT-0 — free to use, modify, and redistribute. No attribution required.

---

## Author

[Sanket Sao](https://linkedin.com/in/sanketsao) · [The Builder Economist](https://thebuildereconomist.substack.com)


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)