| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 20 | 20 | 0% |
| Commands | 0 | 12 | 0 | 0% |
| Section tags | 1 | 7 | 3 | 9% |
What each file covers
Sections
0 shared · 20 only in A · 20 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
- + Architecture & Design Principles
- + Core Architectural Principles
- + SOLID Principles
- + DRY Principle (Don't Repeat Yourself)
- + Clean Architecture
- + Clean Code Practices
- + Project-Specific Patterns
- + Domain Organization
- + Service Construction
- + Context Propagation
- + Resource Management
- + Anti-Patterns to Avoid
- + God Objects
- + Tight Coupling
- + Circular Dependencies
- + Magic Numbers/Strings
- + Quality Metrics
- + Code Quality Indicators
- + Architecture Health
- + Final Guidelines
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
1 shared · 7 only in A · 3 only in B- − setup
- − test
- − lint-format
- − architecture
- − git-pr
- − database
- − agent-behaviour
- + code-style
- + dependencies
- + do-not
- testing-strategy
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/architecture.mdc
@@ +1 @@
1---
2description: Comprehensive architectural standards and design principles following SOLID principles, Clean Architecture, and DRY practices for building maintainable, scalable software
3globs:
4alwaysApply: true
5---
6# Architecture & Design Principles
7# Architecture & Design Principles
8
9<goal>
10Establish comprehensive architectural standards and design principles for building maintainable, scalable, and robust software following industry best practices adapted to the project's domain-driven structure.
11</goal>
12
13## Core Architectural Principles
14
15### SOLID Principles
16
17<principle type="solid_srp">
18**Single Responsibility Principle (SRP):**
19- Each module, class, or function should have only one reason to change
20- Separate business logic, data access, and presentation concerns
21- Use domain-specific packages: `engine/{agent,task,tool,workflow,runtime,infra}/`
22- *Implementation examples: see [go-patterns.mdc](mdc:.cursor/rules/go-patterns.mdc)*
23</principle>
24
25<principle type="solid_ocp">
26**Open/Closed Principle (OCP):**
27- Open for extension, closed for modification
28- Use interfaces and composition over inheritance
29- Leverage factory patterns for extensible behavior
30- *Factory pattern implementation: see [go-patterns.mdc](mdc:.cursor/rules/go-patterns.mdc)*
31</principle>
32
33<principle type="solid_lsp">
34**Liskov Substitution Principle (LSP):**
35- Subtypes must be substitutable for their base types
36- Interface implementations must honor contracts
37- Ensure interface methods behave consistently
38- *Interface design patterns: see [go-patterns.mdc](mdc:.cursor/rules/go-patterns.mdc)*
39</principle>
40
41<principle type="solid_isp">
42**Interface Segregation Principle (ISP):**
43- Clients should not depend on interfaces they don't use
44- Create small, focused interfaces
45- Use interface composition for complex behavior
46- *Interface composition examples: see [go-patterns.mdc](mdc:.cursor/rules/go-patterns.mdc)*
47</principle>
48
49<principle type="solid_dip">
50**Dependency Inversion Principle (DIP):**
51- Depend on abstractions, not concretions
52- Use dependency injection through constructors
53- High-level modules should not depend on low-level modules
54- *Constructor patterns: see [go-patterns.mdc](mdc:.cursor/rules/go-patterns.mdc)*
55</principle>
56
57### DRY Principle (Don't Repeat Yourself)
58
59<dry_strategies type="code_reuse">
60**Code Reuse Strategies:**
61- Extract common functionality into shared packages
62- Use generic functions for similar operations
63- Create utility packages for cross-cutting concerns
64
65```go
66// ✅ Good: Reusable validation utility
67func ValidateRequired(value string, fieldName string) error {
68 if strings.TrimSpace(value) == "" {
69 return fmt.Errorf("%s is required", fieldName)
70 }
71 return nil
72}
73
74// Usage across multiple validators
75func (v *UserValidator) ValidateName(name string) error {
76 return ValidateRequired(name, "name")
77}
78
79func (v *TaskValidator) ValidateTitle(title string) error {
80 return ValidateRequired(title, "title")
81}
82```
83</dry_strategies>
84
85<dry_strategies type="configuration_patterns">
86**Configuration Patterns:**
87- Centralize configuration with defaults
88- Use template engine for dynamic configurations
89- Avoid duplicating configuration logic
90- *Configuration implementation: see [go-patterns.mdc](mdc:.cursor/rules/go-patterns.mdc)*
91</dry_strategies>
92
93### Clean Architecture
94
95<architecture_structure type="domain_driven">
96**Domain-Driven Design Structure:**
97```
98engine/
99├── agent/ # Agent domain logic
100├── task/ # Task execution domain
101├── tool/ # Tool management domain
102├── workflow/ # Workflow orchestration domain
103├── runtime/ # Runtime execution environment
104├── infra/ # Infrastructure concerns
105└── core/ # Shared domain primitives
106```
107</architecture_structure>
108
109<layer_separation>
110**Layer Separation:**
111- **Domain Layer** (`engine/core/`): Shared business entities, value objects, and cross-domain primitives
112- **Application Layer** (`engine/{agent,task,tool,workflow}/`): Domain-specific business logic, use cases, and port interfaces (repositories, external services)
113- **Infrastructure Layer** (`engine/infra/`): External concerns (DB, HTTP, etc.) and adapter implementations
114- **Runtime Layer** (`engine/runtime/`): Execution environment and system orchestration
115
116**Interface Ownership Clarification:**
117- **Port Interfaces** (e.g., Repository, ExternalService): Defined in Application Layer packages where they're used
118- **Domain Entities**: Defined in Domain Layer (`engine/core/`) for cross-domain sharing
119- **Adapter Implementations**: Defined in Infrastructure Layer, implementing Application Layer interfaces
120</layer_separation>
121
122<dependency_flow>
123```go
124// ✅ Good: Dependencies flow inward
125package task
126
127import (
128 "context"
129 "github.com/project/engine/core" // Domain entities
130)
131
132type Service struct {
133 repo Repository // Interface defined in domain
134}
135
136type Repository interface { // Domain-defined interface
137 Save(ctx context.Context, task *core.Task) error
138 Find(ctx context.Context, id core.ID) (*core.Task, error)
139}
140
141// Implementation in infrastructure layer
142package infra
143
144import (
145 "github.com/project/engine/task" // Application layer
146)
147
148type PostgreSQLTaskRepository struct {
149 db *sql.DB
150}
151
152func (r *PostgreSQLTaskRepository) Save(ctx context.Context, task *core.Task) error {
153 // Implementation details
154}
155```
156</dependency_flow>
157
158### Clean Code Practices
159
160**Naming Conventions:**
161- Use intention-revealing names
162- Avoid mental mapping and abbreviations
163- Use searchable names for important concepts
164
165<example type="naming_conventions">
166```go
167// ✅ Good: Clear, intention-revealing names
168type WorkflowExecutionResult struct {
169 TaskResults []TaskResult `json:"task_results"`
170 ExecutionTime time.Duration `json:"execution_time"`
171 Status ExecutionStatus `json:"status"`
172}
173
174func (w *WorkflowService) ExecuteWorkflowWithRetry(
175 ctx context.Context,
176 workflowID core.ID,
177 maxRetries int,
178) (*WorkflowExecutionResult, error) {
179 // Implementation
180}
181
182// ❌ Bad: Unclear, abbreviated names
183type WfExecRes struct {
184 TskRes []TskRes `json:"tr"`
185 ExecT int64 `json:"et"`
186 Stat int `json:"s"`
187}
188
189func (w *WfSvc) ExecWf(ctx context.Context, id string, mr int) (*WfExecRes, error) {
190 // Implementation
191}
192```
193</example>
194
195<function_design>
196**Function Design:**
197- Follow function length limits defined in go-coding-standards.mdc
198- Single level of abstraction per function
199- Minimize function parameters (max 3-4)
200</function_design>
201
202<example type="function_design">
203```go
204// ✅ Good: Small, focused function
205func (s *TaskService) ValidateTaskInput(task *core.Task) error {
206 if err := s.validateRequiredFields(task); err != nil {
207 return fmt.Errorf("validation failed: %w", err)
208 }
209 if err := s.validateBusinessRules(task); err != nil {
210 return fmt.Errorf("business rule validation failed: %w", err)
211 }
212 return nil
213}
214
215func (s *TaskService) validateRequiredFields(task *core.Task) error {
216 if task.Title == "" {
217 return errors.New("title is required")
218 }
219 if task.Type == "" {
220 return errors.New("type is required")
221 }
222 return nil
223}
224```
225</example>
226
227<error_handling_architecture>
228**Error Handling Architecture:**
229Follow unified error handling strategy from [go-coding-standards.mdc](mdc:.cursor/rules/go-coding-standards.mdc)
230</error_handling_architecture>
231
232<example type="error_handling">
233```go
234// ✅ Good: Structured error handling
235func (s *WorkflowService) ExecuteWorkflow(ctx context.Context, id core.ID) error {
236 workflow, err := s.repo.FindWorkflow(ctx, id)
237 if err != nil {
238 return fmt.Errorf("failed to load workflow %s: %w", id, err)
239 }
240
241 if err := s.validateWorkflow(workflow); err != nil {
242 return core.NewError(err, "WORKFLOW_VALIDATION_FAILED", map[string]any{
243 "workflow_id": id,
244 "workflow_type": workflow.Type,
245 })
246 }
247
248 return s.executeWorkflowTasks(ctx, workflow)
249}
250```
251</example>
252
253## Project-Specific Patterns
254
255### Domain Organization
256
257<package_structure>
258**Package Structure:**
259- Each domain in `engine/` has clear boundaries
260- Shared types in `engine/core/`
261- Infrastructure concerns in `engine/infra/`
262</package_structure>
263
264### Service Construction
265
266<constructor_pattern type="mandatory">
267**MANDATORY constructor pattern for all services**
268- Use dependency injection through constructors
269- Always provide nil-safe configuration handling
270- *Implementation examples: see [go-patterns.mdc](mdc:.cursor/rules/go-patterns.mdc)*
271</constructor_pattern>
272
273### Context Propagation
274
275<context_requirements type="mandatory">
276**Context as first parameter in all functions**
277- Always handle context cancellation
278- Propagate context through call chains
279- *Context handling patterns: see [go-patterns.mdc](mdc:.cursor/rules/go-patterns.mdc)*
280</context_requirements>
281
282### Resource Management
283
284<cleanup_patterns>
285**Resource cleanup requirements:**
286- Use defer for cleanup operations
287- Handle cleanup errors appropriately
288- Implement timeout handling for long-running operations
289- *Resource management patterns: see [go-patterns.mdc](mdc:.cursor/rules/go-patterns.mdc)*
290</cleanup_patterns>
291
292## Anti-Patterns to Avoid
293
294### God Objects
295```go
296// ❌ Avoid: Too many responsibilities
297type MegaService struct {
298 // Too many dependencies and responsibilities
299}
300```
301
302### Tight Coupling
303```go
304// ❌ Avoid: Direct dependency on concrete types
305type Service struct {
306 db *sql.DB // Should be an interface
307}
308```
309
310### Circular Dependencies
311```go
312// ❌ Avoid: Package A imports B, B imports A
313```
314
315### Magic Numbers/Strings
316```go
317// ❌ Avoid: Magic values
318if status == 1 { /* what does 1 mean? */ }
319
320// ✅ Use: Named constants
321const StatusActive = 1
322if status == StatusActive { /* clear meaning */ }
323```
324
325## Quality Metrics
326
327### Code Quality Indicators
328- **Function complexity and length:** Follow limits defined in go-coding-standards.mdc
329- **Package Coupling:** Minimize cross-package dependencies
330- **Test Coverage:** Aim for 80%+ on business logic
331
332### Architecture Health
333- **Dependency Direction:** Always inward toward domain
334- **Interface Usage:** High ratio of interfaces to concrete types
335- **Package Cohesion:** Related functionality grouped together
336- **Separation of Concerns:** Clear boundaries between layers
337
338## Final Guidelines
339
3401. **Design for Change:** Assume requirements will evolve
3412. **Favor Composition:** Over inheritance and complex hierarchies
3423. **Explicit Dependencies:** Make all dependencies visible
3434. **Fail Fast:** Validate inputs early and fail explicitly
3445. **Document Decisions:** Capture architectural decisions and trade-offs
3456. **Measure and Monitor:** Track architecture health metrics
3467. **Refactor Continuously:** Improve design as understanding grows
3478. **Test Architecture:** Verify architectural constraints in tests
348
@@ −1 +1 @@
1−# Development Guide
1+---
2+description: Comprehensive architectural standards and design principles following SOLID principles, Clean Architecture, and DRY practices for building maintainable, scalable software
3+globs:
4+alwaysApply: true
5+---
6+# Architecture & Design Principles
7+# Architecture & Design Principles
28
3−This file provides comprehensive guidance for working with the Compozy codebase, including development commands, standards, and workflow patterns.
9+<goal>
10+Establish comprehensive architectural standards and design principles for building maintainable, scalable, and robust software following industry best practices adapted to the project's domain-driven structure.
11+</goal>
412
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>
13+## Core Architectural Principles
2014
21−## Project Overview
15+### SOLID Principles
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+<principle type="solid_srp">
18+**Single Responsibility Principle (SRP):**
19+- Each module, class, or function should have only one reason to change
20+- Separate business logic, data access, and presentation concerns
21+- Use domain-specific packages: `engine/{agent,task,tool,workflow,runtime,infra}/`
22+- *Implementation examples: see [go-patterns.mdc](mdc:.cursor/rules/go-patterns.mdc)*
23+</principle>
2424
25−## Development Commands
25+<principle type="solid_ocp">
26+**Open/Closed Principle (OCP):**
27+- Open for extension, closed for modification
28+- Use interfaces and composition over inheritance
29+- Leverage factory patterns for extensible behavior
30+- *Factory pattern implementation: see [go-patterns.mdc](mdc:.cursor/rules/go-patterns.mdc)*
31+</principle>
2632
27−### Essential Commands
33+<principle type="solid_lsp">
34+**Liskov Substitution Principle (LSP):**
35+- Subtypes must be substitutable for their base types
36+- Interface implementations must honor contracts
37+- Ensure interface methods behave consistently
38+- *Interface design patterns: see [go-patterns.mdc](mdc:.cursor/rules/go-patterns.mdc)*
39+</principle>
2840
29−```bash
30−# Quick setup
31−make deps && make start-docker && make migrate-up
41+<principle type="solid_isp">
42+**Interface Segregation Principle (ISP):**
43+- Clients should not depend on interfaces they don't use
44+- Create small, focused interfaces
45+- Use interface composition for complex behavior
46+- *Interface composition examples: see [go-patterns.mdc](mdc:.cursor/rules/go-patterns.mdc)*
47+</principle>
3248
33−# Start development server with hot reload
34−make dev
49+<principle type="solid_dip">
50+**Dependency Inversion Principle (DIP):**
51+- Depend on abstractions, not concretions
52+- Use dependency injection through constructors
53+- High-level modules should not depend on low-level modules
54+- *Constructor patterns: see [go-patterns.mdc](mdc:.cursor/rules/go-patterns.mdc)*
55+</principle>
3556
36−# Run tests (excludes E2E/slow tests)
37−make test
57+### DRY Principle (Don't Repeat Yourself)
3858
39−# Run all tests including E2E
40−make test
59+<dry_strategies type="code_reuse">
60+**Code Reuse Strategies:**
61+- Extract common functionality into shared packages
62+- Use generic functions for similar operations
63+- Create utility packages for cross-cutting concerns
4164
42−# Format and lint code (ALWAYS run before committing)
43−make fmt && make lint
65+```go
66+// ✅ Good: Reusable validation utility
67+func ValidateRequired(value string, fieldName string) error {
68+ if strings.TrimSpace(value) == "" {
69+ return fmt.Errorf("%s is required", fieldName)
70+ }
71+ return nil
72+}
4473
45−# Run specific test
46−go test -v ./engine/task -run TestExecutor_Execute
74+// Usage across multiple validators
75+func (v *UserValidator) ValidateName(name string) error {
76+ return ValidateRequired(name, "name")
77+}
78+
79+func (v *TaskValidator) ValidateTitle(title string) error {
80+ return ValidateRequired(title, "title")
81+}
4782 ```
83+</dry_strategies>
4884
49−### Database Commands
85+<dry_strategies type="configuration_patterns">
86+**Configuration Patterns:**
87+- Centralize configuration with defaults
88+- Use template engine for dynamic configurations
89+- Avoid duplicating configuration logic
90+- *Configuration implementation: see [go-patterns.mdc](mdc:.cursor/rules/go-patterns.mdc)*
91+</dry_strategies>
5092
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
93+### Clean Architecture
94+
95+<architecture_structure type="domain_driven">
96+**Domain-Driven Design Structure:**
5697 ```
98+engine/
99+├── agent/ # Agent domain logic
100+├── task/ # Task execution domain
101+├── tool/ # Tool management domain
102+├── workflow/ # Workflow orchestration domain
103+├── runtime/ # Runtime execution environment
104+├── infra/ # Infrastructure concerns
105+└── core/ # Shared domain primitives
106+```
107+</architecture_structure>
57108
58−## Architecture & Project Structure
109+<layer_separation>
110+**Layer Separation:**
111+- **Domain Layer** (`engine/core/`): Shared business entities, value objects, and cross-domain primitives
112+- **Application Layer** (`engine/{agent,task,tool,workflow}/`): Domain-specific business logic, use cases, and port interfaces (repositories, external services)
113+- **Infrastructure Layer** (`engine/infra/`): External concerns (DB, HTTP, etc.) and adapter implementations
114+- **Runtime Layer** (`engine/runtime/`): Execution environment and system orchestration
59115
60−**📁 Complete project structure, technology stack, and architectural patterns:** See [project-structure.mdc](mdc:.cursor/rules/project-structure.mdc)
116+**Interface Ownership Clarification:**
117+- **Port Interfaces** (e.g., Repository, ExternalService): Defined in Application Layer packages where they're used
118+- **Domain Entities**: Defined in Domain Layer (`engine/core/`) for cross-domain sharing
119+- **Adapter Implementations**: Defined in Infrastructure Layer, implementing Application Layer interfaces
120+</layer_separation>
61121
62−## 🚨 CRITICAL: Follow All Development Standards
122+<dependency_flow>
123+```go
124+// ✅ Good: Dependencies flow inward
125+package task
63126
64−**📋 MANDATORY: Review and follow ALL established coding standards:**
127+import (
128+ "context"
129+ "github.com/project/engine/core" // Domain entities
130+)
65131
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
132+type Service struct {
133+ repo Repository // Interface defined in domain
134+}
75135
76−## Development Workflow
136+type Repository interface { // Domain-defined interface
137+ Save(ctx context.Context, task *core.Task) error
138+ Find(ctx context.Context, id core.ID) (*core.Task, error)
139+}
77140
78−### Pre-Commit Requirements
141+// Implementation in infrastructure layer
142+package infra
79143
80−**ALWAYS run before committing:**
144+import (
145+ "github.com/project/engine/task" // Application layer
146+)
81147
82−```bash
83−make fmt && make lint && make test
148+type PostgreSQLTaskRepository struct {
149+ db *sql.DB
150+}
151+
152+func (r *PostgreSQLTaskRepository) Save(ctx context.Context, task *core.Task) error {
153+ // Implementation details
154+}
84155 ```
156+</dependency_flow>
85157
86−### Development Process
158+### Clean Code Practices
87159
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
160+**Naming Conventions:**
161+- Use intention-revealing names
162+- Avoid mental mapping and abbreviations
163+- Use searchable names for important concepts
93164
94−### Key Development Notes
165+<example type="naming_conventions">
166+```go
167+// ✅ Good: Clear, intention-revealing names
168+type WorkflowExecutionResult struct {
169+ TaskResults []TaskResult `json:"task_results"`
170+ ExecutionTime time.Duration `json:"execution_time"`
171+ Status ExecutionStatus `json:"status"`
172+}
95173
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))
174+func (w *WorkflowService) ExecuteWorkflowWithRetry(
175+ ctx context.Context,
176+ workflowID core.ID,
177+ maxRetries int,
178+) (*WorkflowExecutionResult, error) {
179+ // Implementation
180+}
99181
100−## Task Management
182+// ❌ Bad: Unclear, abbreviated names
183+type WfExecRes struct {
184+ TskRes []TskRes `json:"tr"`
185+ ExecT int64 `json:"et"`
186+ Stat int `json:"s"`
187+}
101188
102−For task-based development workflows, see these rule files:
189+func (w *WfSvc) ExecWf(ctx context.Context, id string, mr int) (*WfExecRes, error) {
190+ // Implementation
191+}
192+```
193+</example>
103194
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
195+<function_design>
196+**Function Design:**
197+- Follow function length limits defined in go-coding-standards.mdc
198+- Single level of abstraction per function
199+- Minimize function parameters (max 3-4)
200+</function_design>
109201
110−## Rule Management
202+<example type="function_design">
203+```go
204+// ✅ Good: Small, focused function
205+func (s *TaskService) ValidateTaskInput(task *core.Task) error {
206+ if err := s.validateRequiredFields(task); err != nil {
207+ return fmt.Errorf("validation failed: %w", err)
208+ }
209+ if err := s.validateBusinessRules(task); err != nil {
210+ return fmt.Errorf("business rule validation failed: %w", err)
211+ }
212+ return nil
213+}
111214
112−The development rules are actively maintained and improved:
215+func (s *TaskService) validateRequiredFields(task *core.Task) error {
216+ if task.Title == "" {
217+ return errors.New("title is required")
218+ }
219+ if task.Type == "" {
220+ return errors.New("type is required")
221+ }
222+ return nil
223+}
224+```
225+</example>
113226
114−- **Rule Management**: [cursor_rules.mdc](mdc:.cursor/rules/cursor_rules.mdc) - Comprehensive guidelines for creating, maintaining, and improving rules
227+<error_handling_architecture>
228+**Error Handling Architecture:**
229+Follow unified error handling strategy from [go-coding-standards.mdc](mdc:.cursor/rules/go-coding-standards.mdc)
230+</error_handling_architecture>
115231
116−## Compozy Configuration Examples
232+<example type="error_handling">
233+```go
234+// ✅ Good: Structured error handling
235+func (s *WorkflowService) ExecuteWorkflow(ctx context.Context, id core.ID) error {
236+ workflow, err := s.repo.FindWorkflow(ctx, id)
237+ if err != nil {
238+ return fmt.Errorf("failed to load workflow %s: %w", id, err)
239+ }
117240
118−For YAML configuration patterns and examples:
241+ if err := s.validateWorkflow(workflow); err != nil {
242+ return core.NewError(err, "WORKFLOW_VALIDATION_FAILED", map[string]any{
243+ "workflow_id": id,
244+ "workflow_type": workflow.Type,
245+ })
246+ }
119247
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
248+ return s.executeWorkflowTasks(ctx, workflow)
249+}
250+```
251+</example>
125252
126−**All rule files are located in `.cursor/rules/` and use semantic XML tags for better context and AI understanding.**
253+## Project-Specific Patterns
127254
128−The project uses Go 1.24+ features and requires external dependencies to be mocked in tests when necessary.
255+### Domain Organization
256+
257+<package_structure>
258+**Package Structure:**
259+- Each domain in `engine/` has clear boundaries
260+- Shared types in `engine/core/`
261+- Infrastructure concerns in `engine/infra/`
262+</package_structure>
263+
264+### Service Construction
265+
266+<constructor_pattern type="mandatory">
267+**MANDATORY constructor pattern for all services**
268+- Use dependency injection through constructors
269+- Always provide nil-safe configuration handling
270+- *Implementation examples: see [go-patterns.mdc](mdc:.cursor/rules/go-patterns.mdc)*
271+</constructor_pattern>
272+
273+### Context Propagation
274+
275+<context_requirements type="mandatory">
276+**Context as first parameter in all functions**
277+- Always handle context cancellation
278+- Propagate context through call chains
279+- *Context handling patterns: see [go-patterns.mdc](mdc:.cursor/rules/go-patterns.mdc)*
280+</context_requirements>
281+
282+### Resource Management
283+
284+<cleanup_patterns>
285+**Resource cleanup requirements:**
286+- Use defer for cleanup operations
287+- Handle cleanup errors appropriately
288+- Implement timeout handling for long-running operations
289+- *Resource management patterns: see [go-patterns.mdc](mdc:.cursor/rules/go-patterns.mdc)*
290+</cleanup_patterns>
291+
292+## Anti-Patterns to Avoid
293+
294+### God Objects
295+```go
296+// ❌ Avoid: Too many responsibilities
297+type MegaService struct {
298+ // Too many dependencies and responsibilities
299+}
300+```
301+
302+### Tight Coupling
303+```go
304+// ❌ Avoid: Direct dependency on concrete types
305+type Service struct {
306+ db *sql.DB // Should be an interface
307+}
308+```
309+
310+### Circular Dependencies
311+```go
312+// ❌ Avoid: Package A imports B, B imports A
313+```
314+
315+### Magic Numbers/Strings
316+```go
317+// ❌ Avoid: Magic values
318+if status == 1 { /* what does 1 mean? */ }
319+
320+// ✅ Use: Named constants
321+const StatusActive = 1
322+if status == StatusActive { /* clear meaning */ }
323+```
324+
325+## Quality Metrics
326+
327+### Code Quality Indicators
328+- **Function complexity and length:** Follow limits defined in go-coding-standards.mdc
329+- **Package Coupling:** Minimize cross-package dependencies
330+- **Test Coverage:** Aim for 80%+ on business logic
331+
332+### Architecture Health
333+- **Dependency Direction:** Always inward toward domain
334+- **Interface Usage:** High ratio of interfaces to concrete types
335+- **Package Cohesion:** Related functionality grouped together
336+- **Separation of Concerns:** Clear boundaries between layers
337+
338+## Final Guidelines
339+
340+1. **Design for Change:** Assume requirements will evolve
341+2. **Favor Composition:** Over inheritance and complex hierarchies
342+3. **Explicit Dependencies:** Make all dependencies visible
343+4. **Fail Fast:** Validate inputs early and fail explicitly
344+5. **Document Decisions:** Capture architectural decisions and trade-offs
345+6. **Measure and Monitor:** Track architecture health metrics
346+7. **Refactor Continuously:** Improve design as understanding grows
347+8. **Test Architecture:** Verify architectural constraints in tests
129348
