| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 20 | 8 | 0% |
| Commands | 0 | 12 | 0 | 0% |
| Section tags | 2 | 6 | 1 | 22% |
What each file covers
Sections
0 shared · 20 only in A · 8 only in B- − Development Guide
- − Project Overview
- − Development Commands
- − Essential Commands
- − Quick setup
- − Start development server with hot reload
- − Run tests (excludes E2E/slow tests)
- − Run all tests including E2E
- − Format and lint code (ALWAYS run before committing)
- − Run specific test
- − Database Commands
- − Architecture & Project Structure
- − 🚨 CRITICAL: Follow All Development Standards
- − Development Workflow
- − Pre-Commit Requirements
- − Development Process
- − Key Development Notes
- − Task Management
- − Rule Management
- − Compozy Configuration Examples
- + Rule: Generating a Product Requirements Document (PRD)
- + Template Reference
- + Process
- + Clarifying Questions (Examples)
- + PRD Structure Requirements
- + Content Guidelines
- + Workflow Instructions
- + Quality Checklist
Commands
0 shared · 12 only in A · 0 only in B- − make deps && make start-docker && make migrate-up
- − make dev
- − make test
- − make fmt && make lint
- − go test -v ./engine/task -run TestExecutor_Execute
- − make migrate-up
- − make migrate-down
- − make migrate-status
- − make reset-db
- − make fmt && make lint && make test
- − make lint
- − make migrate-create name=<name>
Section tags
2 shared · 6 only in A · 1 only in B- − setup
- − test
- − lint-format
- − testing-strategy
- − git-pr
- − database
- + code-style
- architecture
- agent-behaviour
Line diff
compozy/gograph · GEMINI.md
@@ −1 @@
1# Development Guide
2
3This file provides comprehensive guidance for working with the Compozy codebase, including development commands, standards, and workflow patterns.
4
5<critical>
6**MANDATORY REQUIREMENTS:**
7- **ALWAYS** check dependent files APIs before write tests to avoid write wrong code
8- **ALWAYS** verify against PRD and tech specs - NEVER make assumptions
9- **NEVER** use workarounds, especially in tests - implement proper solutions
10- **MUST** follow all established project standards:
11 - Architecture patterns: `.cursor/rules/architecture.mdc`
12 - Go coding standards: `.cursor/rules/go-coding-standards.mdc`
13 - Testing requirements: `.cursor/rules/testing-standards.mdc`
14 - API standards: `.cursor/rules/api-standards.mdc`
15 - Security & quality: `.cursor/rules/quality-security.mdc`
16- **MUST** run `make lint` and `make test` before completing ANY subtask
17- **MUST** follow `.cursor/rules/task-review.mdc` workflow for parent tasks
18**Enforcement:** Violating these standards results in immediate task rejection.
19</critical>
20
21## Project Overview
22
23Compozy is a **workflow orchestration engine for AI agents** that enables building AI-powered applications through declarative YAML configuration and a robust Go backend. It integrates with various LLM providers and supports the Model Context Protocol (MCP) for extending AI capabilities.
24
25## Development Commands
26
27### Essential Commands
28
29```bash
30# Quick setup
31make deps && make start-docker && make migrate-up
32
33# Start development server with hot reload
34make dev
35
36# Run tests (excludes E2E/slow tests)
37make test
38
39# Run all tests including E2E
40make test
41
42# Format and lint code (ALWAYS run before committing)
43make fmt && make lint
44
45# Run specific test
46go test -v ./engine/task -run TestExecutor_Execute
47```
48
49### Database Commands
50
51```bash
52make migrate-up # Apply migrations
53make migrate-down # Rollback last migration
54make migrate-status # Check migration status
55make reset-db # Reset database completely
56```
57
58## Architecture & Project Structure
59
60**📁 Complete project structure, technology stack, and architectural patterns:** See [project-structure.mdc](mdc:.cursor/rules/project-structure.mdc)
61
62## 🚨 CRITICAL: Follow All Development Standards
63
64**📋 MANDATORY: Review and follow ALL established coding standards:**
65
66- **Code Formatting & Line Spacing**: [no_linebreaks.mdc](mdc:.cursor/rules/no_linebreaks.mdc) - NEVER add blank lines inside function bodies
67- **Go Coding Standards**: [go-coding-standards.mdc](mdc:.cursor/rules/go-coding-standards.mdc) - Function limits, error handling, documentation policy
68- **Testing Standards**: [testing-standards.mdc](mdc:.cursor/rules/testing-standards.mdc) - MANDATORY `t.Run("Should...")` pattern, testify usage
69- **Go Implementation Patterns**: [go-patterns.mdc](mdc:.cursor/rules/go-patterns.mdc) - Canonical implementations of architecture principles
70- **Architecture Principles**: [architecture.mdc](mdc:.cursor/rules/architecture.mdc) - SOLID principles, Clean Architecture, DRY
71- **Code Quality & Security**: [quality-security.mdc](mdc:.cursor/rules/quality-security.mdc) - Linting rules, security requirements
72- **Required Libraries**: [core-libraries.mdc](mdc:.cursor/rules/core-libraries.mdc) - Mandatory library choices and usage patterns
73- **API Development**: [api-standards.mdc](mdc:.cursor/rules/api-standards.mdc) - RESTful design, versioning, documentation
74- **Code Review Process**: [review-checklist.mdc](mdc:.cursor/rules/review-checklist.mdc) - Pre-review requirements and checklist
75
76## Development Workflow
77
78### Pre-Commit Requirements
79
80**ALWAYS run before committing:**
81
82```bash
83make fmt && make lint && make test
84```
85
86### Development Process
87
881. **API changes:** Update Swagger annotations (`swag` comments)
892. **Schema changes:** Create migrations with `make migrate-create name=<name>`
903. **New features:** Include comprehensive tests following [testing-standards.mdc](mdc:.cursor/rules/testing-standards.mdc)
914. **Task completion:** Follow [task-review.mdc](mdc:.cursor/rules/task-review.mdc) for mandatory code review workflow via Zen MCP tools
925. **Backwards Compatibility:** See [backwards-compatibility.mdc](mdc:.cursor/rules/backwards-compatibility.mdc) - NOT REQUIRED during development phase
93
94### Key Development Notes
95
96- **Logging:** Use [core-libraries.mdc](mdc:.cursor/rules/core-libraries.mdc) for structured logging patterns
97- **Core types:** Use `core.ID` for UUIDs, `core.Ref` for polymorphic references
98- **Dependencies:** Mock external dependencies in tests when necessary (see [testing-standards.mdc](mdc:.cursor/rules/testing-standards.mdc))
99
100## Task Management
101
102For task-based development workflows, see these rule files:
103
104- [prd-create.mdc](mdc:.cursor/rules/prd-create.mdc) - PRD Creation
105- [prd-tech-spec.mdc](mdc:.cursor/rules/prd-tech-spec.mdc) - Technical Specifications
106- [task-generate-list.mdc](mdc:.cursor/rules/task-generate-list.mdc) - Task List Generation
107- [task-developing.mdc](mdc:.cursor/rules/task-developing.mdc) - Task Development
108- [task-review.mdc](mdc:.cursor/rules/task-review.mdc) - Task Completion with Zen MCP code review
109
110## Rule Management
111
112The development rules are actively maintained and improved:
113
114- **Rule Management**: [cursor_rules.mdc](mdc:.cursor/rules/cursor_rules.mdc) - Comprehensive guidelines for creating, maintaining, and improving rules
115
116## Compozy Configuration Examples
117
118For YAML configuration patterns and examples:
119
120- **Project Configuration**: [compozy-project-config.mdc](mdc:.cursor/rules/compozy-project-config.mdc) - Project setup patterns
121- **Task Patterns**: [compozy-task-patterns.mdc](mdc:.cursor/rules/compozy-task-patterns.mdc) - Workflow task configurations
122- **Agent Configuration**: [compozy-agent-config.mdc](mdc:.cursor/rules/compozy-agent-config.mdc) - AI agent setup patterns
123- **Shared Patterns**: [compozy-shared-patterns.mdc](mdc:.cursor/rules/compozy-shared-patterns.mdc) - MCP, templates, and references
124- **Configuration Index**: [compozy-examples.mdc](mdc:.cursor/rules/compozy-examples.mdc) - Overview and cross-references
125
126**All rule files are located in `.cursor/rules/` and use semantic XML tags for better context and AI understanding.**
127
128The project uses Go 1.24+ features and requires external dependencies to be mocked in tests when necessary.
129
compozy/gograph · .cursor/rules/prd-create.mdc
@@ +1 @@
1---
2description: "Guide for creating Product Requirements Documents (PRDs) with AI assistance, including clarifying questions and structured documentation process"
3globs:
4alwaysApply: false
5---
6# Rule: Generating a Product Requirements Document (PRD)
7
8<goal>
9To guide an AI assistant in creating a detailed Product Requirements Document (PRD) in Markdown format, based on an initial user prompt. The PRD should be comprehensive, focusing on user needs, functional requirements, and business goals to clearly define *what* to build and *why*.
10</goal>
11
12## Template Reference
13
14<template_reference>
15**ALWAYS use the standardized PRD template:** tasks/docs/_prd-template.md
16
17This template provides a comprehensive structure that balances requirements gathering with rollout planning, ensuring consistency across all PRDs in the project.
18</template_reference>
19
20## Process
21
22<process_workflow>
231. **Receive Initial Prompt:** The user provides a brief description or request for a new feature or functionality.
24
252. **Ask Clarifying Questions:** Before writing the PRD, the AI *must* ask clarifying questions to gather sufficient detail. Focus on understanding the "what" and "why" of the feature, user needs, and success criteria.
26
27**MANDATORY PLANNING STEPS:**
283. **Create PRD Planning with Zen Planner:** Use zen's planner tool to create a comprehensive PRD development plan:
29 - Analyze the enriched feature specification requirements
30 - Break down PRD creation into logical planning steps
31 - Identify key sections that need focused attention
32 - Plan resource allocation and approach for each section
33 - Document assumptions and dependencies that will guide PRD creation
34
354. **Validate Planning with Consensus:** Use zen's consensus tool with o3 and gemini 2.5 models:
36 - Present the detailed PRD planning approach to both expert models
37 - Request critical analysis of the planning strategy
38 - Gather feedback on plan completeness and effectiveness
39 - Incorporate consensus recommendations into final planning approach
40 - Proceed only after receiving aligned approval from both expert models
41
42**PRD CREATION WORKFLOW:**
435. **Generate Comprehensive PRD (Functionality-Focused):** Using the template, produce a PRD that captures user and business requirements plus high-level product scope **without including low-level technical design or implementation details** – those belong in the Tech Spec.
446. **Create Feature Folder:** Instruct to create a feature folder `./tasks/prd-[feature-slug]/`.
457. **Save PRD:** Save the generated document as `_prd.md` inside the feature folder.
46</process_workflow>
47
48## Clarifying Questions (Examples)
49
50<clarifying_questions_guidance>
51The AI should adapt its questions based on the prompt and template sections. Here are key areas to explore:
52
53**Problem & Goals:**
54- "What problem does this feature solve for the user?"
55- "What are the specific, measurable goals we want to achieve?"
56- "How will we measure success?"
57
58**Users & Stories:**
59- "Who is the primary user of this feature?"
60- "Can you provide user stories? (As a [type of user], I want to [action] so that [benefit])"
61- "What are the key user flows and interactions?"
62
63**Core Functionality:**
64- "What are the essential features that must be included in the MVP?"
65- "Can you describe the key actions a user should be able to perform?"
66- "What data does this feature need to display or manipulate?"
67
68**Technical Constraints (acceptance criteria only – describe *what* must be met, not *how* to meet it):**
69- "Are there any existing systems this needs to integrate with?"
70- "What are the performance thresholds or security requirements? (e.g., must handle X users, must comply with Y standard)"
71- "Are there any technical constraints that limit what can be built?"
72- Note: Capture only acceptance-criteria level thresholds; defer solution approaches to Tech Spec
73
74**Scope & Planning:**
75- "What should this feature NOT do (non-goals)?"
76- "How should development be phased for incremental delivery?"
77- "What are the dependencies between different parts of this feature?"
78
79**Risks & Challenges:**
80- "What are the biggest risks or challenges you foresee?"
81- "Are there any unknowns that need research before implementation?"
82- "What could prevent this feature from being successful?"
83
84**Design & Experience:**
85- "Are there any design mockups or UI guidelines to follow?"
86- "What accessibility requirements should be considered?"
87- "How should this feature integrate with the existing user experience?"
88</clarifying_questions_guidance>
89
90## PRD Structure Requirements
91
92<prd_structure_requirements>
93The generated PRD MUST follow the template structure from @_prd-template.md:
94
951. **Overview:** Problem statement, target users, and value proposition
962. **Goals:** Specific, measurable objectives and business outcomes
973. **User Stories:** Detailed narratives covering primary and edge case scenarios
984. **Core Features:** Main functionality with detailed functional requirements
995. **User Experience:** User journeys, flows, UI/UX considerations, and accessibility
1006. **High-Level Technical Constraints:** Integration points, compliance mandates, performance thresholds (avoid architectural diagrams or code-level solutions)
1017. **Non-Goals (Out of Scope):** Clear boundaries and excluded features
1028. **Phased Rollout Plan:** User-facing milestones with MVP and enhancement stages
1039. **Success Metrics:** Measurable outcomes for user engagement and business impact
10410. **Risks and Mitigations:** Potential challenges and response strategies
10511. **Open Questions:** Unresolved items requiring further clarification
10612. **Appendix:** Supporting materials, research, and reference documentation
107</prd_structure_requirements>
108
109## Content Guidelines
110
111<content_guidelines>
112**Target Audience:** Assume readers include both **junior developers** and **project stakeholders**. Requirements should be:
113- Explicit and unambiguous
114- Detailed enough for implementation
115- Strategic enough for decision-making
116- Avoid technical jargon without explanation
117
118**Functional Requirements:** Use clear, actionable language:
119- "The system must allow users to..."
120- "Users should be able to..."
121- Number requirements for easy reference
122
123**Delivery Considerations (high-level only):** Balance user needs with practical rollout:
124- Consider MVP vs. full feature scope from a user value perspective
125- Plan for incremental delivery of user value
126- Identify which features deliver the most user/business value first
127- Note: Detailed technical sequencing and dependencies belong in the Tech Spec
128
129**Separation of Concerns:**
130- Keep the PRD centered on *what* the product should achieve, not *how* it will be built
131- Capture only high-level technical constraints (e.g., required throughput, compliance mandates); defer architectural or code-level solutions to the Tech Spec
132- If detailed design ideas arise, note them as TODOs for the Tech Spec author or move them to an appendix reference rather than the main PRD body
133
134**Document Size Guidelines:**
135- Target a maximum length of ~3,000 words (≈7–8 pages)
136- Prefer concise bullet points, tables, and links to external references over verbose narrative paragraphs
137- Offload large data sets, research studies, or extended examples to appendices or separate reference documents to keep the core PRD lightweight
138</content_guidelines>
139
140<output_specification>
141- **Format:** Markdown (`.md`)
142- **Location:** `./tasks/prd-[feature-slug]/`
143- **Filename:** `_prd.md`
144- **Template:** Use @_prd-template.md structure
145</output_specification>
146
147## Workflow Instructions
148
149<workflow_instructions>
1501. **ALWAYS** ask clarifying questions first to gather comprehensive information
1512. **MUST THEN** use zen's planner tool to create comprehensive PRD development plan
1523. **MUST VALIDATE** planning approach using zen's consensus tool with o3 and gemini 2.5 models
1534. **DO NOT** proceed to PRD creation without completing both mandatory planning steps
1545. **USE** the standardized template structure for consistency
1556. **FOCUS** on comprehensive user and business requirements; defer implementation planning to the Tech Spec
1567. **ENSURE** the PRD is actionable for both development and project management
1578. **ITERATE** on the PRD based on user feedback and additional clarification
158</workflow_instructions>
159
160## Quality Checklist
161
162<quality_checklist>
163Before finalizing the PRD, ensure:
164
165**Planning Validation:**
166- [ ] Used zen's planner tool to create comprehensive PRD development plan
167- [ ] Validated planning approach with zen's consensus tool using o3 and gemini 2.5 models
168- [ ] Incorporated consensus recommendations into final planning approach
169- [ ] Received aligned approval from both expert models before proceeding
170
171**PRD Content Quality:**
172- [ ] All template sections are completed with relevant information
173- [ ] User stories cover primary flows and edge cases
174- [ ] Functional requirements are numbered and specific
175- [ ] High-level constraints (e.g., required integrations, compliance) are defined
176- [ ] Phased rollout plan shows clear user-facing milestones and product-level dependencies
177- [ ] Success metrics are measurable and relevant
178- [ ] Risks are identified with mitigation strategies
179- [ ] Open questions capture any remaining uncertainties
180- [ ] Document is ≤ 3,000 words (core sections) – move overflow to Appendix
181- [ ] No technical implementation details or architecture decisions included
182</quality_checklist>
183
@@ −1 +1 @@
1−# Development Guide
1+---
2+description: "Guide for creating Product Requirements Documents (PRDs) with AI assistance, including clarifying questions and structured documentation process"
3+globs:
4+alwaysApply: false
5+---
6+# Rule: Generating a Product Requirements Document (PRD)
27
3−This file provides comprehensive guidance for working with the Compozy codebase, including development commands, standards, and workflow patterns.
8+<goal>
9+To guide an AI assistant in creating a detailed Product Requirements Document (PRD) in Markdown format, based on an initial user prompt. The PRD should be comprehensive, focusing on user needs, functional requirements, and business goals to clearly define *what* to build and *why*.
10+</goal>
411
5−<critical>
6−**MANDATORY REQUIREMENTS:**
7−- **ALWAYS** check dependent files APIs before write tests to avoid write wrong code
8−- **ALWAYS** verify against PRD and tech specs - NEVER make assumptions
9−- **NEVER** use workarounds, especially in tests - implement proper solutions
10−- **MUST** follow all established project standards:
11− - Architecture patterns: `.cursor/rules/architecture.mdc`
12− - Go coding standards: `.cursor/rules/go-coding-standards.mdc`
13− - Testing requirements: `.cursor/rules/testing-standards.mdc`
14− - API standards: `.cursor/rules/api-standards.mdc`
15− - Security & quality: `.cursor/rules/quality-security.mdc`
16−- **MUST** run `make lint` and `make test` before completing ANY subtask
17−- **MUST** follow `.cursor/rules/task-review.mdc` workflow for parent tasks
18−**Enforcement:** Violating these standards results in immediate task rejection.
19−</critical>
12+## Template Reference
2013
21−## Project Overview
14+<template_reference>
15+**ALWAYS use the standardized PRD template:** tasks/docs/_prd-template.md
2216
23−Compozy is a **workflow orchestration engine for AI agents** that enables building AI-powered applications through declarative YAML configuration and a robust Go backend. It integrates with various LLM providers and supports the Model Context Protocol (MCP) for extending AI capabilities.
17+This template provides a comprehensive structure that balances requirements gathering with rollout planning, ensuring consistency across all PRDs in the project.
18+</template_reference>
2419
25−## Development Commands
20+## Process
2621
27−### Essential Commands
22+<process_workflow>
23+1. **Receive Initial Prompt:** The user provides a brief description or request for a new feature or functionality.
2824
29−```bash
30−# Quick setup
31−make deps && make start-docker && make migrate-up
25+2. **Ask Clarifying Questions:** Before writing the PRD, the AI *must* ask clarifying questions to gather sufficient detail. Focus on understanding the "what" and "why" of the feature, user needs, and success criteria.
3226
33−# Start development server with hot reload
34−make dev
27+**MANDATORY PLANNING STEPS:**
28+3. **Create PRD Planning with Zen Planner:** Use zen's planner tool to create a comprehensive PRD development plan:
29+ - Analyze the enriched feature specification requirements
30+ - Break down PRD creation into logical planning steps
31+ - Identify key sections that need focused attention
32+ - Plan resource allocation and approach for each section
33+ - Document assumptions and dependencies that will guide PRD creation
3534
36−# Run tests (excludes E2E/slow tests)
37−make test
35+4. **Validate Planning with Consensus:** Use zen's consensus tool with o3 and gemini 2.5 models:
36+ - Present the detailed PRD planning approach to both expert models
37+ - Request critical analysis of the planning strategy
38+ - Gather feedback on plan completeness and effectiveness
39+ - Incorporate consensus recommendations into final planning approach
40+ - Proceed only after receiving aligned approval from both expert models
3841
39−# Run all tests including E2E
40−make test
42+**PRD CREATION WORKFLOW:**
43+5. **Generate Comprehensive PRD (Functionality-Focused):** Using the template, produce a PRD that captures user and business requirements plus high-level product scope **without including low-level technical design or implementation details** – those belong in the Tech Spec.
44+6. **Create Feature Folder:** Instruct to create a feature folder `./tasks/prd-[feature-slug]/`.
45+7. **Save PRD:** Save the generated document as `_prd.md` inside the feature folder.
46+</process_workflow>
4147
42−# Format and lint code (ALWAYS run before committing)
43−make fmt && make lint
48+## Clarifying Questions (Examples)
4449
45−# Run specific test
46−go test -v ./engine/task -run TestExecutor_Execute
47−```
50+<clarifying_questions_guidance>
51+The AI should adapt its questions based on the prompt and template sections. Here are key areas to explore:
4852
49−### Database Commands
53+**Problem & Goals:**
54+- "What problem does this feature solve for the user?"
55+- "What are the specific, measurable goals we want to achieve?"
56+- "How will we measure success?"
5057
51−```bash
52−make migrate-up # Apply migrations
53−make migrate-down # Rollback last migration
54−make migrate-status # Check migration status
55−make reset-db # Reset database completely
56−```
58+**Users & Stories:**
59+- "Who is the primary user of this feature?"
60+- "Can you provide user stories? (As a [type of user], I want to [action] so that [benefit])"
61+- "What are the key user flows and interactions?"
5762
58−## Architecture & Project Structure
63+**Core Functionality:**
64+- "What are the essential features that must be included in the MVP?"
65+- "Can you describe the key actions a user should be able to perform?"
66+- "What data does this feature need to display or manipulate?"
5967
60−**📁 Complete project structure, technology stack, and architectural patterns:** See [project-structure.mdc](mdc:.cursor/rules/project-structure.mdc)
68+**Technical Constraints (acceptance criteria only – describe *what* must be met, not *how* to meet it):**
69+- "Are there any existing systems this needs to integrate with?"
70+- "What are the performance thresholds or security requirements? (e.g., must handle X users, must comply with Y standard)"
71+- "Are there any technical constraints that limit what can be built?"
72+- Note: Capture only acceptance-criteria level thresholds; defer solution approaches to Tech Spec
6173
62−## 🚨 CRITICAL: Follow All Development Standards
74+**Scope & Planning:**
75+- "What should this feature NOT do (non-goals)?"
76+- "How should development be phased for incremental delivery?"
77+- "What are the dependencies between different parts of this feature?"
6378
64−**📋 MANDATORY: Review and follow ALL established coding standards:**
79+**Risks & Challenges:**
80+- "What are the biggest risks or challenges you foresee?"
81+- "Are there any unknowns that need research before implementation?"
82+- "What could prevent this feature from being successful?"
6583
66−- **Code Formatting & Line Spacing**: [no_linebreaks.mdc](mdc:.cursor/rules/no_linebreaks.mdc) - NEVER add blank lines inside function bodies
67−- **Go Coding Standards**: [go-coding-standards.mdc](mdc:.cursor/rules/go-coding-standards.mdc) - Function limits, error handling, documentation policy
68−- **Testing Standards**: [testing-standards.mdc](mdc:.cursor/rules/testing-standards.mdc) - MANDATORY `t.Run("Should...")` pattern, testify usage
69−- **Go Implementation Patterns**: [go-patterns.mdc](mdc:.cursor/rules/go-patterns.mdc) - Canonical implementations of architecture principles
70−- **Architecture Principles**: [architecture.mdc](mdc:.cursor/rules/architecture.mdc) - SOLID principles, Clean Architecture, DRY
71−- **Code Quality & Security**: [quality-security.mdc](mdc:.cursor/rules/quality-security.mdc) - Linting rules, security requirements
72−- **Required Libraries**: [core-libraries.mdc](mdc:.cursor/rules/core-libraries.mdc) - Mandatory library choices and usage patterns
73−- **API Development**: [api-standards.mdc](mdc:.cursor/rules/api-standards.mdc) - RESTful design, versioning, documentation
74−- **Code Review Process**: [review-checklist.mdc](mdc:.cursor/rules/review-checklist.mdc) - Pre-review requirements and checklist
84+**Design & Experience:**
85+- "Are there any design mockups or UI guidelines to follow?"
86+- "What accessibility requirements should be considered?"
87+- "How should this feature integrate with the existing user experience?"
88+</clarifying_questions_guidance>
7589
76−## Development Workflow
90+## PRD Structure Requirements
7791
78−### Pre-Commit Requirements
92+<prd_structure_requirements>
93+The generated PRD MUST follow the template structure from @_prd-template.md:
7994
80−**ALWAYS run before committing:**
95+1. **Overview:** Problem statement, target users, and value proposition
96+2. **Goals:** Specific, measurable objectives and business outcomes
97+3. **User Stories:** Detailed narratives covering primary and edge case scenarios
98+4. **Core Features:** Main functionality with detailed functional requirements
99+5. **User Experience:** User journeys, flows, UI/UX considerations, and accessibility
100+6. **High-Level Technical Constraints:** Integration points, compliance mandates, performance thresholds (avoid architectural diagrams or code-level solutions)
101+7. **Non-Goals (Out of Scope):** Clear boundaries and excluded features
102+8. **Phased Rollout Plan:** User-facing milestones with MVP and enhancement stages
103+9. **Success Metrics:** Measurable outcomes for user engagement and business impact
104+10. **Risks and Mitigations:** Potential challenges and response strategies
105+11. **Open Questions:** Unresolved items requiring further clarification
106+12. **Appendix:** Supporting materials, research, and reference documentation
107+</prd_structure_requirements>
81108
82−```bash
83−make fmt && make lint && make test
84−```
109+## Content Guidelines
85110
86−### Development Process
111+<content_guidelines>
112+**Target Audience:** Assume readers include both **junior developers** and **project stakeholders**. Requirements should be:
113+- Explicit and unambiguous
114+- Detailed enough for implementation
115+- Strategic enough for decision-making
116+- Avoid technical jargon without explanation
87117
88−1. **API changes:** Update Swagger annotations (`swag` comments)
89−2. **Schema changes:** Create migrations with `make migrate-create name=<name>`
90−3. **New features:** Include comprehensive tests following [testing-standards.mdc](mdc:.cursor/rules/testing-standards.mdc)
91−4. **Task completion:** Follow [task-review.mdc](mdc:.cursor/rules/task-review.mdc) for mandatory code review workflow via Zen MCP tools
92−5. **Backwards Compatibility:** See [backwards-compatibility.mdc](mdc:.cursor/rules/backwards-compatibility.mdc) - NOT REQUIRED during development phase
118+**Functional Requirements:** Use clear, actionable language:
119+- "The system must allow users to..."
120+- "Users should be able to..."
121+- Number requirements for easy reference
93122
94−### Key Development Notes
123+**Delivery Considerations (high-level only):** Balance user needs with practical rollout:
124+- Consider MVP vs. full feature scope from a user value perspective
125+- Plan for incremental delivery of user value
126+- Identify which features deliver the most user/business value first
127+- Note: Detailed technical sequencing and dependencies belong in the Tech Spec
95128
96−- **Logging:** Use [core-libraries.mdc](mdc:.cursor/rules/core-libraries.mdc) for structured logging patterns
97−- **Core types:** Use `core.ID` for UUIDs, `core.Ref` for polymorphic references
98−- **Dependencies:** Mock external dependencies in tests when necessary (see [testing-standards.mdc](mdc:.cursor/rules/testing-standards.mdc))
129+**Separation of Concerns:**
130+- Keep the PRD centered on *what* the product should achieve, not *how* it will be built
131+- Capture only high-level technical constraints (e.g., required throughput, compliance mandates); defer architectural or code-level solutions to the Tech Spec
132+- If detailed design ideas arise, note them as TODOs for the Tech Spec author or move them to an appendix reference rather than the main PRD body
99133
100−## Task Management
134+**Document Size Guidelines:**
135+- Target a maximum length of ~3,000 words (≈7–8 pages)
136+- Prefer concise bullet points, tables, and links to external references over verbose narrative paragraphs
137+- Offload large data sets, research studies, or extended examples to appendices or separate reference documents to keep the core PRD lightweight
138+</content_guidelines>
101139
102−For task-based development workflows, see these rule files:
140+<output_specification>
141+- **Format:** Markdown (`.md`)
142+- **Location:** `./tasks/prd-[feature-slug]/`
143+- **Filename:** `_prd.md`
144+- **Template:** Use @_prd-template.md structure
145+</output_specification>
103146
104−- [prd-create.mdc](mdc:.cursor/rules/prd-create.mdc) - PRD Creation
105−- [prd-tech-spec.mdc](mdc:.cursor/rules/prd-tech-spec.mdc) - Technical Specifications
106−- [task-generate-list.mdc](mdc:.cursor/rules/task-generate-list.mdc) - Task List Generation
107−- [task-developing.mdc](mdc:.cursor/rules/task-developing.mdc) - Task Development
108−- [task-review.mdc](mdc:.cursor/rules/task-review.mdc) - Task Completion with Zen MCP code review
147+## Workflow Instructions
109148
110−## Rule Management
149+<workflow_instructions>
150+1. **ALWAYS** ask clarifying questions first to gather comprehensive information
151+2. **MUST THEN** use zen's planner tool to create comprehensive PRD development plan
152+3. **MUST VALIDATE** planning approach using zen's consensus tool with o3 and gemini 2.5 models
153+4. **DO NOT** proceed to PRD creation without completing both mandatory planning steps
154+5. **USE** the standardized template structure for consistency
155+6. **FOCUS** on comprehensive user and business requirements; defer implementation planning to the Tech Spec
156+7. **ENSURE** the PRD is actionable for both development and project management
157+8. **ITERATE** on the PRD based on user feedback and additional clarification
158+</workflow_instructions>
111159
112−The development rules are actively maintained and improved:
160+## Quality Checklist
113161
114−- **Rule Management**: [cursor_rules.mdc](mdc:.cursor/rules/cursor_rules.mdc) - Comprehensive guidelines for creating, maintaining, and improving rules
162+<quality_checklist>
163+Before finalizing the PRD, ensure:
115164
116−## Compozy Configuration Examples
165+**Planning Validation:**
166+- [ ] Used zen's planner tool to create comprehensive PRD development plan
167+- [ ] Validated planning approach with zen's consensus tool using o3 and gemini 2.5 models
168+- [ ] Incorporated consensus recommendations into final planning approach
169+- [ ] Received aligned approval from both expert models before proceeding
117170
118−For YAML configuration patterns and examples:
119−
120−- **Project Configuration**: [compozy-project-config.mdc](mdc:.cursor/rules/compozy-project-config.mdc) - Project setup patterns
121−- **Task Patterns**: [compozy-task-patterns.mdc](mdc:.cursor/rules/compozy-task-patterns.mdc) - Workflow task configurations
122−- **Agent Configuration**: [compozy-agent-config.mdc](mdc:.cursor/rules/compozy-agent-config.mdc) - AI agent setup patterns
123−- **Shared Patterns**: [compozy-shared-patterns.mdc](mdc:.cursor/rules/compozy-shared-patterns.mdc) - MCP, templates, and references
124−- **Configuration Index**: [compozy-examples.mdc](mdc:.cursor/rules/compozy-examples.mdc) - Overview and cross-references
125−
126−**All rule files are located in `.cursor/rules/` and use semantic XML tags for better context and AI understanding.**
127−
128−The project uses Go 1.24+ features and requires external dependencies to be mocked in tests when necessary.
171+**PRD Content Quality:**
172+- [ ] All template sections are completed with relevant information
173+- [ ] User stories cover primary flows and edge cases
174+- [ ] Functional requirements are numbered and specific
175+- [ ] High-level constraints (e.g., required integrations, compliance) are defined
176+- [ ] Phased rollout plan shows clear user-facing milestones and product-level dependencies
177+- [ ] Success metrics are measurable and relevant
178+- [ ] Risks are identified with mitigation strategies
179+- [ ] Open questions capture any remaining uncertainties
180+- [ ] Document is ≤ 3,000 words (core sections) – move overflow to Appendix
181+- [ ] No technical implementation details or architecture decisions included
182+</quality_checklist>
129183
