| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 10 | 20 | 0% |
| Commands | 0 | 2 | 0 | 0% |
| Section tags | 2 | 2 | 2 | 33% |
What each file covers
Sections
0 shared · 10 only in A · 20 only in B- − Task Completion Workflow with Zen MCP
- − 1. Task Definition Validation
- − 2. Rules Analysis & Code Review with Zen MCP
- − 2.1 Rules Analysis
- − 2.2 Multi-Model Code Review
- − 2.3 Rules-Specific Review
- − 3. Fix Review Issues
- − 4. Pre-Commit Validation
- − 5. Mark Task Complete
- − Important Notes
- + 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 · 2 only in A · 0 only in B- − make lint
- − make test
Section tags
2 shared · 2 only in A · 2 only in B- − git-pr
- − agent-behaviour
- + code-style
- + dependencies
- testing-strategy
- do-not
Line diff
compozy/gograph · .cursor/rules/task-review.mdc
@@ −1 @@
1---
2description:
3globs:
4alwaysApply: true
5---
6# Task Completion Workflow with Zen MCP
7
8<critical_requirement>
9**MANDATORY:** Before marking any task as complete, you MUST follow this exact workflow to ensure code quality:
10</critical_requirement>
11
12<workflow_overview>
13**Enhanced Quality Assurance Steps:**
141. **Task Definition Validation** - Verify alignment with task, PRD, and tech spec
152. **Rules Analysis & Code Review** - Analyze applicable rules and perform comprehensive review
163. **Issue Resolution** - Address all identified problems
174. **Pre-Commit Validation** - Final validation before commit
185. **Task Completion** - Mark task as complete only after successful validation
19</workflow_overview>
20
21## 1. Task Definition Validation
22
23<mandatory_step>
24**FIRST:** Verify the implementation aligns with requirements:
25</mandatory_step>
26
27- **Task Definition:** Review the specific task file (e.g., `tasks/prd-[feature-slug]/[task_number]_task.md`)
28- **PRD Alignment:** Check against the Product Requirements Document (`tasks/prd-[feature-slug]/_prd.md`)
29- **Tech Spec Compliance:** Ensure implementation follows the Technical Specification (`tasks/prd-[feature-slug]/_techspec.md`)
30
31```
32Verify that task [task_number] implementation fully satisfies:
331. The specific requirements defined in the task file
342. The business objectives from the PRD
353. The technical specifications and architecture requirements
364. All acceptance criteria and success metrics
37```
38
39## 2. Rules Analysis & Code Review with Zen MCP
40
41<mandatory_step>
42**Analyze applicable rules first, then perform comprehensive code review:**
43</mandatory_step>
44
45### 2.1 Rules Analysis
46```
47Analyze all Cursor rules that apply to the changed files for task [task_number]:
48- Identify which .cursor/rules/*.mdc files are relevant to the implementation
49- List the specific coding standards, patterns, and requirements that apply
50- Check for any rule violations or areas needing attention
51```
52
53### 2.2 Multi-Model Code Review
54
55<mandatory_step>
56Use the criteria from [`review-checklist.mdc`](mdc:.cursor/rules/review-checklist.mdc) as the basis for all code reviews:
57</mandatory_step>
58
59<critical>
60**MANDATORY REQUIREMENTS:**
61- **ALWAYS** check dependent files APIs before write tests to avoid write wrong code
62- **ALWAYS** verify against PRD and tech specs - NEVER make assumptions
63- **NEVER** use workarounds, especially in tests - implement proper solutions
64- **MUST** follow all established project standards:
65 - Architecture patterns: `.cursor/rules/architecture.mdc`
66 - Go coding standards: `.cursor/rules/go-coding-standards.mdc`
67 - Testing requirements: `.cursor/rules/testing-standards.mdc`
68 - API standards: `.cursor/rules/api-standards.mdc`
69 - Security & quality: `.cursor/rules/quality-security.mdc`
70- **MUST** run `make lint` and `make test` before completing ANY subtask
71- **MUST** follow `.cursor/rules/task-review.mdc` workflow for parent tasks
72**Enforcement:** Violating these standards results in immediate task rejection.
73</critical>
74
75```
76Use zen for codereview with gemini-2.5-pro-preview-05-06 to analyze the implementation for task [task_number]: [task_title].
77Focus on the review checklist criteria: code quality, security, adherence to project standards, error handling, testing patterns, and maintainability.
78Apply the specific rules identified in step 2.1 during the review.
79```
80
81```
82Use zen with o3 to perform a logical review of the implementation for task [task_number]: [task_title].
83Analyze the logic, edge cases, and potential issues while considering the applicable coding standards and rules.
84```
85
86### 2.3 Rules-Specific Review
87```
88Use zen with gemini-2.5-pro-preview-05-06 to review task [task_number] implementation specifically against the identified Cursor rules:
89- Verify compliance with project-specific coding standards
90- Check adherence to architectural patterns and design principles
91- Validate implementation follows the established conventions
92- Ensure all rule-based requirements are met
93```
94
95## 3. Fix Review Issues
96
97<mandatory_fixes>
98Address ALL issues identified:
99- Fix critical and high-severity issues immediately
100- Address medium-severity issues unless explicitly justified
101- Document any decisions to skip low-severity issues
102</mandatory_fixes>
103
104## 4. Pre-Commit Validation
105
106<mandatory_step>
107**Execute codereview validation with proper parameters:**
108</mandatory_step>
109
110**Required Parameters:**
111- `path`: Current workspace directory (absolute path)
112- `model`: Use `gemini-2.5-pro-preview-05-06` for comprehensive analysis
113- `prompt`: Original task requirements and context
114
115**Example Implementation:**
116```
117Execute codereview validation for task [task_number]:
118- Path: /path/to/workspace
119- Model: gemini-2.5-pro-preview-05-06
120- Context: Implementation of [task_title] as defined in task requirements
121- Review: Comprehensive validation of all staged and unstaged changes
122```
123
124**Validation Focus:**
125- Verify implementation matches task requirements
126- Check for bugs, security issues, and incomplete implementations
127- Ensure changes follow project coding standards
128- Validate test coverage and error handling
129- Confirm no code duplication or logic redundancy
130
131## 5. Mark Task Complete
132
133**ONLY AFTER** successful validation, update the Markdown task file:
134
135```markdown
136- [x] 1.0 [task_title] ✅ COMPLETED
137 - [x] 1.1 Implementation completed
138 - [x] 1.2 Task definition, PRD, and tech spec validated
139 - [x] 1.3 Rules analysis and compliance verified
140 - [x] 1.4 Code review completed with Zen MCP
141 - [x] 1.5 Ready for deployment
142```
143
144## Important Notes
145
146- **Tool Usage:** Most Zen MCP tools use natural language requests, but **codereview requires structured parameters** (path, model, prompt)
147- **File Paths:** Use absolute paths when referencing files with Zen MCP
148- **Available Models:** `gemini-2.5-pro-preview-05-06` (deep analysis), `o3` (logical reasoning), `flash` (fast responses)
149- **Codereview Parameters:** Always provide absolute workspace path, model selection, and task context for codereview validation
150- **Exceptions:** Only allowed for hotfixes, documentation-only, or config-only changes (must be documented)
151
152<enforcement_policy>
153**MANDATORY:** This workflow must be followed for every task completion. No exceptions without explicit justification.
154</enforcement_policy>
155
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 @@
11 ---
2−description:
2+description: Comprehensive architectural standards and design principles following SOLID principles, Clean Architecture, and DRY practices for building maintainable, scalable software
33 globs:
44 alwaysApply: true
55 ---
6−# Task Completion Workflow with Zen MCP
6+# Architecture & Design Principles
7+# Architecture & Design Principles
78
8−<critical_requirement>
9−**MANDATORY:** Before marking any task as complete, you MUST follow this exact workflow to ensure code quality:
10−</critical_requirement>
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>
1112
12−<workflow_overview>
13−**Enhanced Quality Assurance Steps:**
14−1. **Task Definition Validation** - Verify alignment with task, PRD, and tech spec
15−2. **Rules Analysis & Code Review** - Analyze applicable rules and perform comprehensive review
16−3. **Issue Resolution** - Address all identified problems
17−4. **Pre-Commit Validation** - Final validation before commit
18−5. **Task Completion** - Mark task as complete only after successful validation
19−</workflow_overview>
13+## Core Architectural Principles
2014
21−## 1. Task Definition Validation
15+### SOLID Principles
2216
23−<mandatory_step>
24−**FIRST:** Verify the implementation aligns with requirements:
25−</mandatory_step>
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>
2624
27−- **Task Definition:** Review the specific task file (e.g., `tasks/prd-[feature-slug]/[task_number]_task.md`)
28−- **PRD Alignment:** Check against the Product Requirements Document (`tasks/prd-[feature-slug]/_prd.md`)
29−- **Tech Spec Compliance:** Ensure implementation follows the Technical Specification (`tasks/prd-[feature-slug]/_techspec.md`)
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>
3032
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
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+}
73+
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+}
3182 ```
32−Verify that task [task_number] implementation fully satisfies:
33−1. The specific requirements defined in the task file
34−2. The business objectives from the PRD
35−3. The technical specifications and architecture requirements
36−4. All acceptance criteria and success metrics
37−```
83+</dry_strategies>
3884
39−## 2. Rules Analysis & Code Review with Zen MCP
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>
4092
41−<mandatory_step>
42−**Analyze applicable rules first, then perform comprehensive code review:**
43−</mandatory_step>
93+### Clean Architecture
4494
45−### 2.1 Rules Analysis
95+<architecture_structure type="domain_driven">
96+**Domain-Driven Design Structure:**
4697 ```
47−Analyze all Cursor rules that apply to the changed files for task [task_number]:
48−- Identify which .cursor/rules/*.mdc files are relevant to the implementation
49−- List the specific coding standards, patterns, and requirements that apply
50−- Check for any rule violations or areas needing attention
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
51106 ```
107+</architecture_structure>
52108
53−### 2.2 Multi-Model Code Review
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
54115
55−<mandatory_step>
56−Use the criteria from [`review-checklist.mdc`](mdc:.cursor/rules/review-checklist.mdc) as the basis for all code reviews:
57−</mandatory_step>
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>
58121
59−<critical>
60−**MANDATORY REQUIREMENTS:**
61−- **ALWAYS** check dependent files APIs before write tests to avoid write wrong code
62−- **ALWAYS** verify against PRD and tech specs - NEVER make assumptions
63−- **NEVER** use workarounds, especially in tests - implement proper solutions
64−- **MUST** follow all established project standards:
65− - Architecture patterns: `.cursor/rules/architecture.mdc`
66− - Go coding standards: `.cursor/rules/go-coding-standards.mdc`
67− - Testing requirements: `.cursor/rules/testing-standards.mdc`
68− - API standards: `.cursor/rules/api-standards.mdc`
69− - Security & quality: `.cursor/rules/quality-security.mdc`
70−- **MUST** run `make lint` and `make test` before completing ANY subtask
71−- **MUST** follow `.cursor/rules/task-review.mdc` workflow for parent tasks
72−**Enforcement:** Violating these standards results in immediate task rejection.
73−</critical>
122+<dependency_flow>
123+```go
124+// ✅ Good: Dependencies flow inward
125+package task
74126
127+import (
128+ "context"
129+ "github.com/project/engine/core" // Domain entities
130+)
131+
132+type Service struct {
133+ repo Repository // Interface defined in domain
134+}
135+
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+}
140+
141+// Implementation in infrastructure layer
142+package infra
143+
144+import (
145+ "github.com/project/engine/task" // Application layer
146+)
147+
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+}
75155 ```
76−Use zen for codereview with gemini-2.5-pro-preview-05-06 to analyze the implementation for task [task_number]: [task_title].
77−Focus on the review checklist criteria: code quality, security, adherence to project standards, error handling, testing patterns, and maintainability.
78−Apply the specific rules identified in step 2.1 during the review.
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
168+type WorkflowExecutionResult struct {
169+ TaskResults []TaskResult `json:"task_results"`
170+ ExecutionTime time.Duration `json:"execution_time"`
171+ Status ExecutionStatus `json:"status"`
172+}
173+
174+func (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
183+type WfExecRes struct {
184+ TskRes []TskRes `json:"tr"`
185+ ExecT int64 `json:"et"`
186+ Stat int `json:"s"`
187+}
188+
189+func (w *WfSvc) ExecWf(ctx context.Context, id string, mr int) (*WfExecRes, error) {
190+ // Implementation
191+}
79192 ```
193+</example>
80194
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
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+}
214+
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+}
81224 ```
82−Use zen with o3 to perform a logical review of the implementation for task [task_number]: [task_title].
83−Analyze the logic, edge cases, and potential issues while considering the applicable coding standards and rules.
84−```
225+</example>
85226
86−### 2.3 Rules-Specific Review
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>
231+
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+ }
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+}
87250 ```
88−Use zen with gemini-2.5-pro-preview-05-06 to review task [task_number] implementation specifically against the identified Cursor rules:
89−- Verify compliance with project-specific coding standards
90−- Check adherence to architectural patterns and design principles
91−- Validate implementation follows the established conventions
92−- Ensure all rule-based requirements are met
93−```
251+</example>
94252
95−## 3. Fix Review Issues
253+## Project-Specific Patterns
96254
97−<mandatory_fixes>
98−Address ALL issues identified:
99−- Fix critical and high-severity issues immediately
100−- Address medium-severity issues unless explicitly justified
101−- Document any decisions to skip low-severity issues
102−</mandatory_fixes>
255+### Domain Organization
103256
104−## 4. Pre-Commit Validation
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>
105263
106−<mandatory_step>
107−**Execute codereview validation with proper parameters:**
108−</mandatory_step>
264+### Service Construction
109265
110−**Required Parameters:**
111−- `path`: Current workspace directory (absolute path)
112−- `model`: Use `gemini-2.5-pro-preview-05-06` for comprehensive analysis
113−- `prompt`: Original task requirements and context
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>
114272
115−**Example Implementation:**
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+}
116300 ```
117−Execute codereview validation for task [task_number]:
118−- Path: /path/to/workspace
119−- Model: gemini-2.5-pro-preview-05-06
120−- Context: Implementation of [task_title] as defined in task requirements
121−- Review: Comprehensive validation of all staged and unstaged changes
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+}
122308 ```
123309
124−**Validation Focus:**
125−- Verify implementation matches task requirements
126−- Check for bugs, security issues, and incomplete implementations
127−- Ensure changes follow project coding standards
128−- Validate test coverage and error handling
129−- Confirm no code duplication or logic redundancy
310+### Circular Dependencies
311+```go
312+// ❌ Avoid: Package A imports B, B imports A
313+```
130314
131−## 5. Mark Task Complete
315+### Magic Numbers/Strings
316+```go
317+// ❌ Avoid: Magic values
318+if status == 1 { /* what does 1 mean? */ }
132319
133−**ONLY AFTER** successful validation, update the Markdown task file:
134−
135−```markdown
136−- [x] 1.0 [task_title] ✅ COMPLETED
137− - [x] 1.1 Implementation completed
138− - [x] 1.2 Task definition, PRD, and tech spec validated
139− - [x] 1.3 Rules analysis and compliance verified
140− - [x] 1.4 Code review completed with Zen MCP
141− - [x] 1.5 Ready for deployment
320+// ✅ Use: Named constants
321+const StatusActive = 1
322+if status == StatusActive { /* clear meaning */ }
142323 ```
143324
144−## Important Notes
325+## Quality Metrics
145326
146−- **Tool Usage:** Most Zen MCP tools use natural language requests, but **codereview requires structured parameters** (path, model, prompt)
147−- **File Paths:** Use absolute paths when referencing files with Zen MCP
148−- **Available Models:** `gemini-2.5-pro-preview-05-06` (deep analysis), `o3` (logical reasoning), `flash` (fast responses)
149−- **Codereview Parameters:** Always provide absolute workspace path, model selection, and task context for codereview validation
150−- **Exceptions:** Only allowed for hotfixes, documentation-only, or config-only changes (must be documented)
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
151331
152−<enforcement_policy>
153−**MANDATORY:** This workflow must be followed for every task completion. No exceptions without explicit justification.
154−</enforcement_policy>
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
155348
