| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 20 | 6 | 0% |
| Commands | 0 | 12 | 0 | 0% |
| Section tags | 1 | 7 | 2 | 10% |
What each file covers
Sections
0 shared · 20 only in A · 6 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
- + Go Coding Standards
- + Project Structure and Organization
- + Code Style and Standards
- + Error Handling
- + Dependencies and Interfaces
- + Context and Concurrency
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 · 2 only in B- − setup
- − test
- − lint-format
- − testing-strategy
- − git-pr
- − database
- − agent-behaviour
- + code-style
- + dependencies
- architecture
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/go-coding-standards.mdc
@@ +1 @@
1---
2description:
3globs:
4alwaysApply: true
5---
6# Go Coding Standards
7
8<role>
9You are an expert in Go, microservices architecture, and clean backend development practices. Your role is to ensure code is idiomatic, modular, testable, and aligned with Compozy's established patterns and best practices.
10</role>
11
12## Project Structure and Organization
13
14- Group code by feature/domain when appropriate (agent, task, tool, workflow)
15- Keep package names simple and descriptive
16- Follow the established pattern of separating interfaces from implementations
17
18## Code Style and Standards
19
20<limits type="mandatory">
21- Adhere to Go's official style guide and the project's `.golangci.yml` configuration
22- Function length should not exceed 30 lines for business logic
23- Line length should not exceed 120 characters
24- Cyclomatic complexity should be kept below 10
25</limits>
26
27<documentation_policy>
28- **DON'T ADD** comments to explain code changes - explanation belongs in text responses
29- Only add code comments when user explicitly requests them or code is complex and requires context for future developers
30</documentation_policy>
31
32## Error Handling
33
34<unified_strategy type="mandatory">
35**UNIFIED ERROR HANDLING STRATEGY - SINGLE SOURCE OF TRUTH**
36
371. **Internal Error Propagation (within domains):**
38 - Use `fmt.Errorf()` for all internal error propagation within a domain
39 - Always wrap errors with context: `fmt.Errorf("failed to load user: %w", err)`
40 - This keeps internal code simple and avoids unnecessary abstraction
41
422. **Domain Boundaries (public service methods):**
43 - Use `core.NewError()` ONLY when returning errors from public service methods
44 - These are the methods exposed to other domains or external consumers
45 - Provides structured error information for cross-domain communication
46
473. **Always Required:**
48 - Check and handle errors explicitly - never ignore errors
49 - Return early on errors to avoid deep nesting
50 - Avoid naked returns in longer functions (as enforced by nakedret linter)
51</unified_strategy>
52
53<examples type="implementation">
54```go
55// ✅ INTERNAL: Use fmt.Errorf within domain
56func (s *userService) validateUser(ctx context.Context, user *User) error {
57 if user.Email == "" {
58 return fmt.Errorf("email is required")
59 }
60 if err := s.repo.CheckEmailExists(ctx, user.Email); err != nil {
61 return fmt.Errorf("failed to check email existence: %w", err)
62 }
63 return nil
64}
65
66// ✅ DOMAIN BOUNDARY: Use core.NewError for public methods
67func (s *userService) CreateUser(ctx context.Context, req CreateUserRequest) (*User, error) {
68 user := &User{Email: req.Email, Name: req.Name}
69 if err := s.validateUser(ctx, user); err != nil {
70 return nil, core.NewError(err, "USER_VALIDATION_FAILED", map[string]any{
71 "email": req.Email,
72 })
73 }
74 // ... rest of implementation using fmt.Errorf internally
75}
76```
77</examples>
78
79<pattern type="transaction">
80```go
81defer func() {
82 if err != nil { tx.Rollback(ctx) } else { tx.Commit(ctx) }
83}()
84```
85</pattern>
86
87## Dependencies and Interfaces
88
89- Prefer explicit dependency injection through constructor functions
90- Use interfaces to define behavior and enable testing
91
92<pattern type="interface_implementation">
93```go
94// Define interface
95type Service interface {
96 DoSomething(ctx context.Context, param string) error
97}
98
99// Implement interface
100type ServiceImpl struct {
101 dependency Dependency
102}
103
104// Constructor function
105func NewService(dependency Dependency) Service {
106 return &serviceImpl{
107 dependency: dependency,
108 }
109}
110```
111</pattern>
112
113## Context and Concurrency
114
115<requirements type="context">
116- Use `context.Context` for request-scoped values, deadlines, and cancellations
117- Pass context as the first parameter to functions that make external calls
118- Use the noctx linter to enforce context propagation
119- Ensure goroutines are properly managed and cleaned up
120</requirements>
121
@@ −1 +1 @@
1−# Development Guide
1+---
2+description:
3+globs:
4+alwaysApply: true
5+---
6+# Go Coding Standards
27
3−This file provides comprehensive guidance for working with the Compozy codebase, including development commands, standards, and workflow patterns.
8+<role>
9+You are an expert in Go, microservices architecture, and clean backend development practices. Your role is to ensure code is idiomatic, modular, testable, and aligned with Compozy's established patterns and best practices.
10+</role>
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+## Project Structure and Organization
2013
21−## Project Overview
14+- Group code by feature/domain when appropriate (agent, task, tool, workflow)
15+- Keep package names simple and descriptive
16+- Follow the established pattern of separating interfaces from implementations
2217
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.
18+## Code Style and Standards
2419
25−## Development Commands
20+<limits type="mandatory">
21+- Adhere to Go's official style guide and the project's `.golangci.yml` configuration
22+- Function length should not exceed 30 lines for business logic
23+- Line length should not exceed 120 characters
24+- Cyclomatic complexity should be kept below 10
25+</limits>
2626
27−### Essential Commands
27+<documentation_policy>
28+- **DON'T ADD** comments to explain code changes - explanation belongs in text responses
29+- Only add code comments when user explicitly requests them or code is complex and requires context for future developers
30+</documentation_policy>
2831
29−```bash
30−# Quick setup
31−make deps && make start-docker && make migrate-up
32+## Error Handling
3233
33−# Start development server with hot reload
34−make dev
34+<unified_strategy type="mandatory">
35+**UNIFIED ERROR HANDLING STRATEGY - SINGLE SOURCE OF TRUTH**
3536
36−# Run tests (excludes E2E/slow tests)
37−make test
37+1. **Internal Error Propagation (within domains):**
38+ - Use `fmt.Errorf()` for all internal error propagation within a domain
39+ - Always wrap errors with context: `fmt.Errorf("failed to load user: %w", err)`
40+ - This keeps internal code simple and avoids unnecessary abstraction
3841
39−# Run all tests including E2E
40−make test
42+2. **Domain Boundaries (public service methods):**
43+ - Use `core.NewError()` ONLY when returning errors from public service methods
44+ - These are the methods exposed to other domains or external consumers
45+ - Provides structured error information for cross-domain communication
4146
42−# Format and lint code (ALWAYS run before committing)
43−make fmt && make lint
47+3. **Always Required:**
48+ - Check and handle errors explicitly - never ignore errors
49+ - Return early on errors to avoid deep nesting
50+ - Avoid naked returns in longer functions (as enforced by nakedret linter)
51+</unified_strategy>
4452
45−# Run specific test
46−go test -v ./engine/task -run TestExecutor_Execute
53+<examples type="implementation">
54+```go
55+// ✅ INTERNAL: Use fmt.Errorf within domain
56+func (s *userService) validateUser(ctx context.Context, user *User) error {
57+ if user.Email == "" {
58+ return fmt.Errorf("email is required")
59+ }
60+ if err := s.repo.CheckEmailExists(ctx, user.Email); err != nil {
61+ return fmt.Errorf("failed to check email existence: %w", err)
62+ }
63+ return nil
64+}
65+
66+// ✅ DOMAIN BOUNDARY: Use core.NewError for public methods
67+func (s *userService) CreateUser(ctx context.Context, req CreateUserRequest) (*User, error) {
68+ user := &User{Email: req.Email, Name: req.Name}
69+ if err := s.validateUser(ctx, user); err != nil {
70+ return nil, core.NewError(err, "USER_VALIDATION_FAILED", map[string]any{
71+ "email": req.Email,
72+ })
73+ }
74+ // ... rest of implementation using fmt.Errorf internally
75+}
4776 ```
77+</examples>
4878
49−### Database Commands
50−
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
79+<pattern type="transaction">
80+```go
81+defer func() {
82+ if err != nil { tx.Rollback(ctx) } else { tx.Commit(ctx) }
83+}()
5684 ```
85+</pattern>
5786
58−## Architecture & Project Structure
87+## Dependencies and Interfaces
5988
60−**📁 Complete project structure, technology stack, and architectural patterns:** See [project-structure.mdc](mdc:.cursor/rules/project-structure.mdc)
89+- Prefer explicit dependency injection through constructor functions
90+- Use interfaces to define behavior and enable testing
6191
62−## 🚨 CRITICAL: Follow All Development Standards
92+<pattern type="interface_implementation">
93+```go
94+// Define interface
95+type Service interface {
96+ DoSomething(ctx context.Context, param string) error
97+}
6398
64−**📋 MANDATORY: Review and follow ALL established coding standards:**
99+// Implement interface
100+type ServiceImpl struct {
101+ dependency Dependency
102+}
65103
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
83−make fmt && make lint && make test
104+// Constructor function
105+func NewService(dependency Dependency) Service {
106+ return &serviceImpl{
107+ dependency: dependency,
108+ }
109+}
84110 ```
111+</pattern>
85112
86−### Development Process
113+## Context and Concurrency
87114
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
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−
102−For 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−
112−The 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−
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.
115+<requirements type="context">
116+- Use `context.Context` for request-scoped values, deadlines, and cancellations
117+- Pass context as the first parameter to functions that make external calls
118+- Use the noctx linter to enforce context propagation
119+- Ensure goroutines are properly managed and cleaned up
120+</requirements>
129121
