Refinery Agent Pattern

Refinery Agent Pattern

File Paths & Versioning

Input:

• project-idea/index.md — Primary idea file (source of truth)
• project-idea/amendments/*.md — Additional idea files (optional)

Output:

• project-docs/prd/prd-v{N}.md — Versioned PRD (e.g., prd-v1.md, prd-v2.md)
• project-docs/prd/prd-latest.md — Copy of the latest version

Workflow:

1. Read all files in project-idea/
2. Detect next version number (check existing prd-v*.md files)
3. Generate prd-v{N}.md
4. Update prd-latest.md to match

Version Header: Each PRD includes:

---
version: 1
date: 2025-12-18
input_files:
  - project-idea/index.md
changes_from_previous: null | "Summary of changes"
---

Purpose

The Refinery Agent is the first stage in a multi-agent software factory workflow. It transforms unstructured ideas (text, images, audio, sketches) into well-structured Product Requirements Documents (PRDs) that can be consumed by downstream agents.

When to Use This Pattern

Use the Refinery Agent pattern when:

• Starting a new feature or project from a rough idea
• Converting user feedback into structured requirements
• Transforming brainstorming sessions into actionable specifications
• Processing multi-modal inputs (text, images, diagrams) into unified requirements

Core Responsibilities

1. Input Processing

Accept diverse input formats:

• Plain text descriptions
• Markdown documents
• Images (mockups, wireframes, diagrams)
• Audio recordings or transcriptions
• Links to reference materials

Key principle: Be input-agnostic. The Refinery should normalize any format into structured data.

2. PRD Generation

A complete PRD includes:

Project Overview:

• Title and brief description
• Target users and use cases
• Success criteria and goals

Feature Breakdown:

• Core features (must-haves)
• Secondary features (nice-to-haves)
• Out of scope (explicitly excluded)

User Stories:

• Format: "As a [user type], I want [goal] so that [benefit]"
• Acceptance criteria for each story
• Priority levels (P0/P1/P2)

Technical Context:

• Existing system constraints
• Integration requirements
• Technology preferences
• Performance requirements

UI/UX Considerations:

• User workflows and journeys
• Key interaction patterns
• Visual mockups or references
• Accessibility requirements

3. Validation & Completeness Checks

Before finalizing a PRD, verify:

• All user types are identified
• Core user workflows are described
• Success metrics are measurable
• Constraints and dependencies are documented
• Ambiguities are resolved or flagged

Implementation Approach

Step 1: Parse and Extract

Input → Structured Data Extraction → Key Entities

Extract:

• Who: User types, personas, stakeholders
• What: Features, capabilities, requirements
• Why: Goals, problems being solved
• How: Interaction patterns, workflows
• When: Timelines, dependencies, priorities

Step 2: Organize and Structure

Raw Data → Categorization → PRD Sections

Organization strategy:

1. Group related features together
2. Sequence by user journey or workflow
3. Prioritize by impact and effort
4. Identify dependencies and prerequisites

Step 3: Enrich with AI Analysis

Basic PRD → AI Enhancement → Comprehensive PRD

AI can help with:

• Suggesting missing requirements based on similar projects
• Identifying edge cases and error scenarios
• Generating mockups from text descriptions
• Creating user stories from feature lists
• Proposing success metrics

Step 4: Generate Visual Aids

Text Requirements → Visual Representation → Mockups/Diagrams

Create:

• UI mockups (low to high fidelity)
• System architecture diagrams
• User flow diagrams
• Data model sketches

Step 5: Extract Feature Nodes

Complete PRD → Feature Graph → Structured Nodes

Each feature node contains:

• Feature ID and name
• Description and rationale
• Dependencies (what must exist first)
• Success criteria
• Estimated complexity

Output Format

PRD Document Structure

# [Project Title]

## Overview
- **Description**: [One paragraph summary]
- **Target Users**: [Primary user types]
- **Success Criteria**: [Measurable outcomes]

## Core Features

### Feature 1: [Name]
**Priority**: P0
**User Story**: As a [user], I want [goal] so that [benefit]
**Acceptance Criteria**:
- [ ] Criterion 1
- [ ] Criterion 2

**Dependencies**: None | [Feature IDs]
**Estimated Complexity**: Low | Medium | High

### Feature 2: [Name]
...

## User Workflows

### Workflow 1: [Primary Task]
1. User does X
2. System responds with Y
3. User confirms Z

**Edge Cases**:
- What if X fails?
- What if user cancels at step 2?

## Technical Requirements
- **Performance**: [Specific metrics]
- **Security**: [Requirements]
- **Integrations**: [External systems]
- **Constraints**: [Limitations]

## UI/UX Considerations
- [Key interaction patterns]
- [Visual mockup references]

## Out of Scope
- [Explicitly excluded features]

## Open Questions
- [Unresolved ambiguities requiring stakeholder input]

Feature Graph Format (JSON)

{
  "features": [
    {
      "id": "f1",
      "name": "User Authentication",
      "description": "Basic login/logout functionality",
      "priority": "P0",
      "dependencies": [],
      "complexity": "medium",
      "acceptance_criteria": [
        "Users can register with email/password",
        "Users can log in and log out",
        "Sessions persist across page reloads"
      ]
    },
    {
      "id": "f2",
      "name": "Dashboard View",
      "description": "Main user landing page after login",
      "priority": "P0",
      "dependencies": ["f1"],
      "complexity": "medium"
    }
  ]
}

Best Practices

DO:

• Ask clarifying questions when the input is ambiguous
• Propose multiple options when there are different valid approaches
• Document assumptions explicitly in the PRD
• Include both happy path and edge cases in user stories
• Make requirements testable with specific acceptance criteria

DON'T:

• Assume technical implementation details (that's for Foundry Agent)
• Skip validation of completeness before finalizing
• Ignore constraints mentioned in the input
• Make the PRD too prescriptive about implementation
• Leave open questions untracked

Integration with Other Agents

Output → Foundry Agent

The PRD becomes the input for the Foundry Agent, which will:

• Design technical architecture
• Choose implementation technologies
• Create detailed blueprints

Handoff criteria:

• PRD is complete and validated
• All ambiguities are resolved or documented
• Feature dependencies are mapped
• Success criteria are measurable

Feedback Loop ← Validator Agent

The Validator Agent may send feedback indicating:

• Missing requirements discovered during testing
• User feedback requiring PRD updates
• New features requested

Incorporate feedback by:

• Adding new features to PRD
• Refining existing user stories
• Updating priorities based on learnings

Example Usage

Input

"I want to build a collaborative task manager for small teams. 
Users should be able to create tasks, assign them to team members, 
and track progress. It should have a clean, simple interface."

Refinery Process

1. Extract entities: Users (team members), Tasks (create, assign, track), Teams (small groups)
2. Identify workflows: Task creation, Assignment, Progress tracking
3. Generate user stories:
   • "As a team member, I want to create tasks so that work can be tracked"
   • "As a team lead, I want to assign tasks so that workload is distributed"
4. Define features: Task CRUD, User management, Team setup, Progress dashboard
5. Create mockups: Sketch main dashboard, task detail view
6. Map dependencies: User auth → Team setup → Task management

Output PRD

# Collaborative Task Manager

## Overview
A lightweight task management tool for small teams (2-10 people)...

## Core Features

### F1: User Authentication (P0)
User Story: As a team member, I want to sign up and log in...

### F2: Team Workspace (P0)
User Story: As a team lead, I want to create a team workspace...
[Complete PRD with all sections...]

Tips for Effective Refinement

1. Start broad, then narrow: Begin with high-level goals, then drill into details
2. Use templates: Have standard PRD templates for common project types (web app, API, CLI tool, etc.)
3. Iterate with stakeholders: Share draft PRDs for feedback before finalizing
4. Track changes: Version PRDs and document what changed and why
5. Link to research: Include links to competitor analysis, user research, or design inspiration

Common Pitfalls

• Over-specification: Don't dictate technical solutions (use React vs Vue) - leave that to Foundry
• Under-specification: Don't be too vague ("should be fast") - quantify when possible ("< 200ms response time")
• Scope creep during refinement: Stay focused on the initial idea; capture additional ideas as "future enhancements"
• Ignoring feasibility: Consider technical constraints early, even if not designing the solution yet

Summary

The Refinery Agent transforms chaos into clarity. It's the bridge between human creativity and machine execution, ensuring that downstream agents have well-defined, complete requirements to work with.

Remember: A good PRD is:

• Complete: All necessary information is present
• Clear: No ambiguous language
• Testable: Success can be measured
• Scoped: Boundaries are well-defined
• User-focused: Written from the user's perspective