.cursorrules

/_
Package architecture defines the core architectural guidelines and patterns
for AI assistance in this Go project. It emphasizes clean code, controlled
changes, and clear communication patterns.
_/
package architecture

// Guidelines defines the core architectural rules and patterns
// for AI assistance in this project
var Guidelines = struct {
// ChangeManagement defines rules for how code modifications should be handled
ChangeManagement struct {
// Principles defines core tenets for making changes
Principles []string
// UpdateStrategy defines how changes should be implemented
UpdateStrategy struct {
PreferredApproach string
Methodology []string
Scope map[string]string
}
// Validation defines requirements for validating changes
Validation struct {
Required []string
}
}

    // CodeStandards defines code quality requirements and patterns
    CodeStandards struct {
        // Structure defines code organization rules
        Structure struct {
            PackageOrganization string
            InterfaceDesign    string
            ErrorHandling      string
        }
        // Documentation defines documentation requirements
        Documentation struct {
            Required []string
            Style    string
        }
        // Patterns provides example patterns to follow
        Patterns struct {
            Interface string
            Error    string
            Handler  string
        }
    }

    // AIProtocols defines how AI should interact with the codebase
    AIProtocols struct {
        // BeforeModifying lists steps required before making changes
        BeforeModifying []string
        // DuringImplementation lists requirements while making changes
        DuringImplementation []string
        // Communication defines how AI should communicate about changes
        Communication struct {
            Required      []string
            Clarification struct {
                When []string
                How  string
            }
        }
    }

}{
ChangeManagement: struct {
Principles []string
UpdateStrategy struct {
PreferredApproach string
Methodology []string
Scope map[string]string
}
Validation struct {
Required []string
}
}{
Principles: []string{
"Make minimal, precise changes",
"Verify before modifying",
"Document all changes",
"Test thoroughly",
},
UpdateStrategy: struct {
PreferredApproach string
Methodology []string
Scope map[string]string
}{
PreferredApproach: "incremental",
Methodology: []string{
"Identify specific section to modify",
"Verify surrounding dependencies",
"Make targeted change",
"Validate change does not affect other components",
},
Scope: map[string]string{
"minimal": "Single function or method update",
"moderate": "Package-level modification",
"major": "Must be broken into smaller changes",
},
},
Validation: struct {
Required []string
}{
Required: []string{
"Interface compliance",
"Error handling",
"Documentation updates",
"Test coverage",
},
},
},

    CodeStandards: struct {
        Structure struct {
            PackageOrganization string
            InterfaceDesign    string
            ErrorHandling      string
        }
        Documentation struct {
            Required []string
            Style    string
        }
        Patterns struct {
            Interface string
            Error    string
            Handler  string
        }
    }{
        Structure: struct {
            PackageOrganization string
            InterfaceDesign    string
            ErrorHandling      string
        }{
            PackageOrganization: "Small, focused packages with clear responsibilities",
            InterfaceDesign:     "Small interfaces, composition over inheritance",
            ErrorHandling:       "Use error wrapping, provide context",
        },
        Documentation: struct {
            Required []string
            Style    string
        }{
            Required: []string{
                "Package purpose",
                "Interface contracts",
                "Error scenarios",
                "Usage examples",
            },
            Style: "Explain why, not what",
        },
        Patterns: struct {
            Interface string
            Error    string
            Handler  string
        }{
            Interface: `
                // Agent represents an autonomous agent in the system
                type Agent interface {
                    // Process handles incoming tasks and returns results
                    // It may return ErrInvalidTask if the task cannot be processed
                    Process(ctx context.Context, task Task) (Result, error)

                    // Status returns the current agent status
                    Status() AgentStatus
                }
            `,
            Error: `
                // Example error handling pattern
                if err != nil {
                    return fmt.Errorf("processing task %s: %w", task.ID, err)
                }
            `,
            Handler: `
                // Example handler pattern
                func (agent *Agent) HandleTask(ctx context.Context, task Task) (Result, error) {
                    // Pre-conditions
                    if err := task.Validate(); err != nil {
                        return Result{}, fmt.Errorf("invalid task: %w", err)
                    }

                    // Core logic
                    result, err := agent.process(ctx, task)
                    if err != nil {
                        return Result{}, fmt.Errorf("processing task: %w", err)
                    }

                    // Post-conditions
                    if err := result.Validate(); err != nil {
                        return Result{}, fmt.Errorf("invalid result: %w", err)
                    }

                    return result, nil
                }
            `,
        },
    },

    AIProtocols: struct {
        BeforeModifying []string
        DuringImplementation []string
        Communication struct {
            Required      []string
            Clarification struct {
                When []string
                How  string
            }
        }
    }{
        BeforeModifying: []string{
            "Understand full context",
            "Identify minimal change set",
            "Verify interface compliance",
            "Plan rollback strategy",
        },
        DuringImplementation: []string{
            "Follow Go idioms and patterns",
            "Maintain interface contracts",
            "Document changes inline",
            "Handle all error cases",
        },
        Communication: struct {
            Required      []string
            Clarification struct {
                When []string
                How  string
            }
        }{
            Required: []string{
                "Explicit assumptions",
                "Clear limitations",
                "Specific questions",
                "Validation needs",
            },
            Clarification: struct {
                When []string
                How  string
            }{
                When: []string{
                    "Ambiguous requirements",
                    "Missing context",
                    "Multiple approaches possible",
                    "High-risk changes",
                },
                How: "Ask specific, targeted questions about interfaces and behaviors",
            },
        },
    },

}

// Example validation function
func ValidateChange(change struct {
Type string
Files []string
Description string
}) error {
// Implementation would verify change against guidelines
return nil
}

// Example error creation function
func CreateError(code string, message string, context error) error {
if context != nil {
return fmt.Errorf("%s: %s: %w", code, message, context)
}
return fmt.Errorf("%s: %s", code, message)
}