| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 20 | 0 | 0% |
| Commands | 0 | 12 | 0 | 0% |
| Section tags | 0 | 8 | 0 | 0% |
What each file covers
Sections
0 shared · 20 only in A · 0 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
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
0 shared · 8 only in A · 0 only in B- − setup
- − test
- − lint-format
- − architecture
- − testing-strategy
- − git-pr
- − database
- − agent-behaviour
Line diff
compozy/gograph · GEMINI.md
@@ −1 @@
1# Development Guide
2
3This file provides comprehensive guidance for working with the Compozy codebase, including development commands, standards, and workflow patterns.
4
5<critical>
6**MANDATORY REQUIREMENTS:**
7- **ALWAYS** check dependent files APIs before write tests to avoid write wrong code
8- **ALWAYS** verify against PRD and tech specs - NEVER make assumptions
9- **NEVER** use workarounds, especially in tests - implement proper solutions
10- **MUST** follow all established project standards:
11 - Architecture patterns: `.cursor/rules/architecture.mdc`
12 - Go coding standards: `.cursor/rules/go-coding-standards.mdc`
13 - Testing requirements: `.cursor/rules/testing-standards.mdc`
14 - API standards: `.cursor/rules/api-standards.mdc`
15 - Security & quality: `.cursor/rules/quality-security.mdc`
16- **MUST** run `make lint` and `make test` before completing ANY subtask
17- **MUST** follow `.cursor/rules/task-review.mdc` workflow for parent tasks
18**Enforcement:** Violating these standards results in immediate task rejection.
19</critical>
20
21## Project Overview
22
23Compozy is a **workflow orchestration engine for AI agents** that enables building AI-powered applications through declarative YAML configuration and a robust Go backend. It integrates with various LLM providers and supports the Model Context Protocol (MCP) for extending AI capabilities.
24
25## Development Commands
26
27### Essential Commands
28
29```bash
30# Quick setup
31make deps && make start-docker && make migrate-up
32
33# Start development server with hot reload
34make dev
35
36# Run tests (excludes E2E/slow tests)
37make test
38
39# Run all tests including E2E
40make test
41
42# Format and lint code (ALWAYS run before committing)
43make fmt && make lint
44
45# Run specific test
46go test -v ./engine/task -run TestExecutor_Execute
47```
48
49### Database Commands
50
51```bash
52make migrate-up # Apply migrations
53make migrate-down # Rollback last migration
54make migrate-status # Check migration status
55make reset-db # Reset database completely
56```
57
58## Architecture & Project Structure
59
60**📁 Complete project structure, technology stack, and architectural patterns:** See [project-structure.mdc](mdc:.cursor/rules/project-structure.mdc)
61
62## 🚨 CRITICAL: Follow All Development Standards
63
64**📋 MANDATORY: Review and follow ALL established coding standards:**
65
66- **Code Formatting & Line Spacing**: [no_linebreaks.mdc](mdc:.cursor/rules/no_linebreaks.mdc) - NEVER add blank lines inside function bodies
67- **Go Coding Standards**: [go-coding-standards.mdc](mdc:.cursor/rules/go-coding-standards.mdc) - Function limits, error handling, documentation policy
68- **Testing Standards**: [testing-standards.mdc](mdc:.cursor/rules/testing-standards.mdc) - MANDATORY `t.Run("Should...")` pattern, testify usage
69- **Go Implementation Patterns**: [go-patterns.mdc](mdc:.cursor/rules/go-patterns.mdc) - Canonical implementations of architecture principles
70- **Architecture Principles**: [architecture.mdc](mdc:.cursor/rules/architecture.mdc) - SOLID principles, Clean Architecture, DRY
71- **Code Quality & Security**: [quality-security.mdc](mdc:.cursor/rules/quality-security.mdc) - Linting rules, security requirements
72- **Required Libraries**: [core-libraries.mdc](mdc:.cursor/rules/core-libraries.mdc) - Mandatory library choices and usage patterns
73- **API Development**: [api-standards.mdc](mdc:.cursor/rules/api-standards.mdc) - RESTful design, versioning, documentation
74- **Code Review Process**: [review-checklist.mdc](mdc:.cursor/rules/review-checklist.mdc) - Pre-review requirements and checklist
75
76## Development Workflow
77
78### Pre-Commit Requirements
79
80**ALWAYS run before committing:**
81
82```bash
83make fmt && make lint && make test
84```
85
86### Development Process
87
881. **API changes:** Update Swagger annotations (`swag` comments)
892. **Schema changes:** Create migrations with `make migrate-create name=<name>`
903. **New features:** Include comprehensive tests following [testing-standards.mdc](mdc:.cursor/rules/testing-standards.mdc)
914. **Task completion:** Follow [task-review.mdc](mdc:.cursor/rules/task-review.mdc) for mandatory code review workflow via Zen MCP tools
925. **Backwards Compatibility:** See [backwards-compatibility.mdc](mdc:.cursor/rules/backwards-compatibility.mdc) - NOT REQUIRED during development phase
93
94### Key Development Notes
95
96- **Logging:** Use [core-libraries.mdc](mdc:.cursor/rules/core-libraries.mdc) for structured logging patterns
97- **Core types:** Use `core.ID` for UUIDs, `core.Ref` for polymorphic references
98- **Dependencies:** Mock external dependencies in tests when necessary (see [testing-standards.mdc](mdc:.cursor/rules/testing-standards.mdc))
99
100## Task Management
101
102For task-based development workflows, see these rule files:
103
104- [prd-create.mdc](mdc:.cursor/rules/prd-create.mdc) - PRD Creation
105- [prd-tech-spec.mdc](mdc:.cursor/rules/prd-tech-spec.mdc) - Technical Specifications
106- [task-generate-list.mdc](mdc:.cursor/rules/task-generate-list.mdc) - Task List Generation
107- [task-developing.mdc](mdc:.cursor/rules/task-developing.mdc) - Task Development
108- [task-review.mdc](mdc:.cursor/rules/task-review.mdc) - Task Completion with Zen MCP code review
109
110## Rule Management
111
112The development rules are actively maintained and improved:
113
114- **Rule Management**: [cursor_rules.mdc](mdc:.cursor/rules/cursor_rules.mdc) - Comprehensive guidelines for creating, maintaining, and improving rules
115
116## Compozy Configuration Examples
117
118For YAML configuration patterns and examples:
119
120- **Project Configuration**: [compozy-project-config.mdc](mdc:.cursor/rules/compozy-project-config.mdc) - Project setup patterns
121- **Task Patterns**: [compozy-task-patterns.mdc](mdc:.cursor/rules/compozy-task-patterns.mdc) - Workflow task configurations
122- **Agent Configuration**: [compozy-agent-config.mdc](mdc:.cursor/rules/compozy-agent-config.mdc) - AI agent setup patterns
123- **Shared Patterns**: [compozy-shared-patterns.mdc](mdc:.cursor/rules/compozy-shared-patterns.mdc) - MCP, templates, and references
124- **Configuration Index**: [compozy-examples.mdc](mdc:.cursor/rules/compozy-examples.mdc) - Overview and cross-references
125
126**All rule files are located in `.cursor/rules/` and use semantic XML tags for better context and AI understanding.**
127
128The project uses Go 1.24+ features and requires external dependencies to be mocked in tests when necessary.
129
compozy/gograph · .cursor/rules/cursor_rules.mdc
@@ +1 @@
1---
2description: Guidelines for creating and maintaining Cursor rules to ensure consistency and effectiveness.
3globs: .cursor/rules/*.mdc
4alwaysApply: true
5---
6
7<rule_structure_requirements>
8
9- **Required Rule Structure:**
10
11 ```markdown
12 ---
13 description: Clear, one-line description of what the rule enforces
14 globs: path/to/files/*.ext, other/path/**/*
15 alwaysApply: boolean
16 ---
17
18 - **Main Points in Bold**
19 - Sub-points with details
20 - Examples and explanations
21 ```
22
23 </rule_structure_requirements>
24
25<file_reference_guidelines>
26
27- **File References:**
28 - Use `[filename](mdc:path/to/file)` ([filename](mdc:filename)) to reference files
29 - Example: [prisma.mdc](mdc:.cursor/rules/prisma.mdc) for rule references
30 - Example: [schema.prisma](mdc:prisma/schema.prisma) for code references
31 </file_reference_guidelines>
32
33<code_example_guidelines>
34
35- **Code Examples:**
36
37 - Use language-specific code blocks
38
39 ```typescript
40 // ✅ DO: Show good examples
41 const goodExample = true;
42
43 // ❌ DON'T: Show anti-patterns
44 const badExample = false;
45 ```
46
47 </code_example_guidelines>
48
49<content_guidelines>
50
51- **Rule Content Guidelines:**
52 - Start with high-level overview
53 - Include specific, actionable requirements
54 - Show examples of correct implementation
55 - Reference existing code when possible
56 - Keep rules DRY by referencing other rules
57 </content_guidelines>
58
59<rule_update_criteria>
60
61- **Rule Updates:**
62
63 - **Add New Rules When:**
64
65 - A new technology/pattern is used in 3+ files
66 - Common bugs could be prevented by a rule
67 - Code reviews repeatedly mention the same feedback
68 - New security or performance patterns emerge
69
70 - **Modify Existing Rules When:**
71
72 - Better examples exist in the codebase
73 - Additional edge cases are discovered
74 - Related rules have been updated
75 - Implementation details have changed
76
77 - **Rule Deprecation:**
78 - Mark outdated patterns as deprecated
79 - Remove rules that no longer apply
80 - Update references to deprecated rules
81 - Document migration paths for old patterns
82</rule_update_criteria>
83
84<quality_checks>
85
86- **Rule Quality Checks:**
87 - Rules should be actionable and specific
88 - Examples should come from actual code
89 - References should be up to date
90 - Patterns should be consistently enforced
91 - Use bullet points for clarity
92 - Keep descriptions concise
93 - Include both DO and DON'T examples
94 - Reference actual code over theoretical examples
95 - Use consistent formatting across rules
96 </quality_checks>
97
98<continuous_improvement>
99
100- **Continuous Improvement:**
101
102 - **Improvement Triggers:**
103
104 - New code patterns not covered by existing rules
105 - Repeated similar implementations across files
106 - Common error patterns that could be prevented
107 - New libraries or tools being used consistently
108 - Emerging best practices in the codebase
109
110 - **Analysis Process:**
111
112 - Compare new code with existing rules
113 - Identify patterns that should be standardized
114 - Look for references to external documentation
115 - Check for consistent error handling patterns
116 - Monitor test patterns and coverage
117
118 - **Documentation Updates:**
119 - Keep examples synchronized with code
120 - Update references to external docs
121 - Maintain links between related rules
122 - Document breaking changes
123 - Monitor code review comments
124 - Track common development questions
125 - Update rules after major refactors
126 - Add links to relevant documentation
127 - Cross-reference related rules
128</continuous_improvement>
129
@@ −1 +1 @@
1−# Development Guide
1+---
2+description: Guidelines for creating and maintaining Cursor rules to ensure consistency and effectiveness.
3+globs: .cursor/rules/*.mdc
4+alwaysApply: true
5+---
26
3−This file provides comprehensive guidance for working with the Compozy codebase, including development commands, standards, and workflow patterns.
7+<rule_structure_requirements>
48
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>
9+- **Required Rule Structure:**
2010
21−## Project Overview
11+ ```markdown
12+ ---
13+ description: Clear, one-line description of what the rule enforces
14+ globs: path/to/files/*.ext, other/path/**/*
15+ alwaysApply: boolean
16+ ---
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+ - **Main Points in Bold**
19+ - Sub-points with details
20+ - Examples and explanations
21+ ```
2422
25−## Development Commands
23+ </rule_structure_requirements>
2624
27−### Essential Commands
25+<file_reference_guidelines>
2826
29−```bash
30−# Quick setup
31−make deps && make start-docker && make migrate-up
27+- **File References:**
28+ - Use `[filename](mdc:path/to/file)` ([filename](mdc:filename)) to reference files
29+ - Example: [prisma.mdc](mdc:.cursor/rules/prisma.mdc) for rule references
30+ - Example: [schema.prisma](mdc:prisma/schema.prisma) for code references
31+ </file_reference_guidelines>
3232
33−# Start development server with hot reload
34−make dev
33+<code_example_guidelines>
3534
36−# Run tests (excludes E2E/slow tests)
37−make test
35+- **Code Examples:**
3836
39−# Run all tests including E2E
40−make test
37+ - Use language-specific code blocks
4138
42−# Format and lint code (ALWAYS run before committing)
43−make fmt && make lint
39+ ```typescript
40+ // ✅ DO: Show good examples
41+ const goodExample = true;
4442
45−# Run specific test
46−go test -v ./engine/task -run TestExecutor_Execute
47−```
43+ // ❌ DON'T: Show anti-patterns
44+ const badExample = false;
45+ ```
4846
49−### Database Commands
47+ </code_example_guidelines>
5048
51−```bash
52−make migrate-up # Apply migrations
53−make migrate-down # Rollback last migration
54−make migrate-status # Check migration status
55−make reset-db # Reset database completely
56−```
49+<content_guidelines>
5750
58−## Architecture & Project Structure
51+- **Rule Content Guidelines:**
52+ - Start with high-level overview
53+ - Include specific, actionable requirements
54+ - Show examples of correct implementation
55+ - Reference existing code when possible
56+ - Keep rules DRY by referencing other rules
57+ </content_guidelines>
5958
60−**📁 Complete project structure, technology stack, and architectural patterns:** See [project-structure.mdc](mdc:.cursor/rules/project-structure.mdc)
59+<rule_update_criteria>
6160
62−## 🚨 CRITICAL: Follow All Development Standards
61+- **Rule Updates:**
6362
64−**📋 MANDATORY: Review and follow ALL established coding standards:**
63+ - **Add New Rules When:**
6564
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
65+ - A new technology/pattern is used in 3+ files
66+ - Common bugs could be prevented by a rule
67+ - Code reviews repeatedly mention the same feedback
68+ - New security or performance patterns emerge
7569
76−## Development Workflow
70+ - **Modify Existing Rules When:**
7771
78−### Pre-Commit Requirements
72+ - Better examples exist in the codebase
73+ - Additional edge cases are discovered
74+ - Related rules have been updated
75+ - Implementation details have changed
7976
80−**ALWAYS run before committing:**
77+ - **Rule Deprecation:**
78+ - Mark outdated patterns as deprecated
79+ - Remove rules that no longer apply
80+ - Update references to deprecated rules
81+ - Document migration paths for old patterns
82+</rule_update_criteria>
8183
82−```bash
83−make fmt && make lint && make test
84−```
84+<quality_checks>
8585
86−### Development Process
86+- **Rule Quality Checks:**
87+ - Rules should be actionable and specific
88+ - Examples should come from actual code
89+ - References should be up to date
90+ - Patterns should be consistently enforced
91+ - Use bullet points for clarity
92+ - Keep descriptions concise
93+ - Include both DO and DON'T examples
94+ - Reference actual code over theoretical examples
95+ - Use consistent formatting across rules
96+ </quality_checks>
8797
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
98+<continuous_improvement>
9399
94−### Key Development Notes
100+- **Continuous Improvement:**
95101
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))
102+ - **Improvement Triggers:**
99103
100−## Task Management
104+ - New code patterns not covered by existing rules
105+ - Repeated similar implementations across files
106+ - Common error patterns that could be prevented
107+ - New libraries or tools being used consistently
108+ - Emerging best practices in the codebase
101109
102−For task-based development workflows, see these rule files:
110+ - **Analysis Process:**
103111
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
112+ - Compare new code with existing rules
113+ - Identify patterns that should be standardized
114+ - Look for references to external documentation
115+ - Check for consistent error handling patterns
116+ - Monitor test patterns and coverage
109117
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.
118+ - **Documentation Updates:**
119+ - Keep examples synchronized with code
120+ - Update references to external docs
121+ - Maintain links between related rules
122+ - Document breaking changes
123+ - Monitor code review comments
124+ - Track common development questions
125+ - Update rules after major refactors
126+ - Add links to relevant documentation
127+ - Cross-reference related rules
128+</continuous_improvement>
129129
