gitwalter/cursor-agent-factory: A configurable factory for generating Cursor IDE development agent systems. Creates .cursorrules, agents, skills, workflows, and templates for any tech stack. Supports blueprints for SAP, Python, Cloud-Native, and more. Includes refactoring capabilities for existing projects

Build AI-powered development systems that truly understand your project.

Quick Start: New here? See docs/QUICKSTART.md or run python cli/factory_cli.py --quickstart to get running in 5 minutes.

Welcome! Whether you’re a solo developer exploring new possibilities or a team building something meaningful together, we’re here to help you create an AI development environment grounded in purpose, principles, and care.

Not sure where to begin? We’ve got you covered.

New to all this? Start with Getting Started to find your ideal path, or run the Quickstart to see the factory in action.

Need help? See Prerequisites for setup or Troubleshooting if you run into issues.

Every project we generate is built on a 5-layer architecture grounded in Love, Truth, and Beauty:

flowchart TB
    subgraph L0 [Layer 0: Foundation]
        A0[Love - Truth - Beauty]
    end
    
    subgraph L1 [Layer 1: Integrity]
        A1[Reasoning]
        A2[Curiosity]
        A3[Humility]
    end
    
    subgraph L2 [Layer 2: Purpose]
        Mission[Mission]
        Stakeholders[Stakeholders]
        Success[Success Criteria]
    end
    
    subgraph L3 [Layer 3: Principles]
        Ethics[Ethical Boundaries]
        Quality[Quality Standards]
    end
    
    subgraph L4 [Layer 4: Technical]
        Agents[AI Agents]
        Skills[Skills]
        Knowledge[Knowledge Files]
    end
    
    L0 --> L1
    L1 --> L2
    L2 --> L3
    L3 --> L4

This isn’t just about code – it’s about building systems that serve the flourishing of all beings.

See the factory in action with zero configuration:

python cli/factory_cli.py --quickstart

This creates a complete demo project showing what you’ll get. Perfect for exploration!

1. Open this project in Cursor IDE
2. Say: “Create a new agent system”
3. Follow the guided 5-phase questionnaire
4. Specify your output directory
5. Review your generated project

For teams of 2+ people, collaborative workshops help align your team:

Each workshop is grounded in Axiom 0: Love, Truth, and Beauty. See the Team Workshop Guide for details.

# List available blueprints
python cli/factory_cli.py --list-blueprints

# Generate from a blueprint
python cli/factory_cli.py --blueprint python-fastapi --output C:\Projects\my-api

# Interactive mode with full questionnaire
python cli/factory_cli.py --interactive --output C:\Projects\my-project

# Onboard an existing repository
python cli/factory_cli.py --onboard C:\Projects\existing-repo

The Cursor Agent Factory is a meta-system that generates complete AI agent development systems. It uses a 5-layer deductive-inductive architecture to create agent systems that are technically capable and grounded in clear values.

Generated projects include:

• Purpose documentation (PURPOSE.md) – Your mission and success criteria
• 5-layer .cursorrules – AI guidance with axioms, principles, and methodology
• AI agent definitions (.cursor/agents/) – Specialized assistants for your workflow
• Reusable skill definitions (.cursor/skills/) – Procedures your agents can follow
• Structured knowledge files (knowledge/) – Domain expertise in JSON format
• Code and document templates (templates/) – Consistent starting points
• 21 ready-to-use workflows (workflows/) – Automated development, testing, PM, and deployment
• Methodology configuration (workflows/methodology.yaml) – How your team works
• Integrity Guardian – Layer 0 protection for all operations
• Memory System – User-validated learning from interactions

Workflow Categories:

Every generated project includes an Integrity Guardian – an active Layer 0 protector that ensures AI agents align with core axioms.

Motto: SDG – Love – Truth – Beauty

The Guardian monitors for:

• Destructive commands (rm -rf /, DROP DATABASE)
• Exposed secrets (API keys, passwords, connection strings)
• Axiom violations (hidden logic, deception, instruction overrides)

Invoke manually: "Guardian, check this" or "check my alignment"

See GUARDIAN_COORDINATION.md for complete documentation.

The Factory includes a Memory System that learns from your interactions and stores user-validated knowledge for future sessions.

Key Features:

• All memories require user approval (Axiom A2: User Primacy)
• Layers 0-2 remain immutable – only knowledge files can be extended
• Works offline after initial setup (no API keys required)
• Chat-based interaction for memory management

Chat Commands:

"Show my memories"              → List stored memories
"What do you remember about X?" → Semantic search
"Delete the memory about X"     → Remove a memory
"Accept/Reject"                 → Respond to proposals

See MEMORY_SYSTEM.md for complete documentation.

The Factory includes mathematically proven guarantees that the core architecture satisfies its foundational axioms. Using Lean 4, we prove:

Trust Chain: Factory proofs → Project proofs → Team extensions → All verifiable

Quick Commands:

cd proofs && lake build       # Verify all proofs
scripts/generate_attestation.sh  # Create cryptographic attestation

See docs/VERIFICATION.md for complete documentation.

A complete dynamic multi-agent verification system (lib/society/) extending formal proofs to runtime behavior. Enables verified agent communication, contracts, and behavior in multi-agent societies.

Quick Usage:

from lib.society import HybridVerificationSystem
system = HybridVerificationSystem.create_default()
result = system.record_event(event)  # Verify against all axioms

See docs/design/AGENT_SOCIETY_VERIFICATION.md for architecture and docs/SOCIETY_USAGE.md for complete usage guide.

The Factory includes an automatic Knowledge Evolution System that keeps blueprints, patterns, and knowledge files current with the latest best practices from trusted sources.

"Check for knowledge updates"        # See what's available
"Apply pending updates"              # Apply with confirmation
"Configure knowledge evolution"      # Change settings

Configure in .cursor/config/settings.json or use the system-configuration skill.

See docs/KNOWLEDGE_EVOLUTION.md for complete documentation.

Generated projects can receive updates from the Factory:

"Check for Factory updates"    # In your generated project
"Sync with Factory"            # Apply available updates

This creates a connection between the Factory and generated projects, allowing teams to benefit from ongoing Factory improvements.

For visual documentation, see the diagrams/ folder:

cursor-agent-factory/
├── .cursor/
│   ├── agents/                  # Factory's own agents (12 agents)
│   │   └── *.md                 # debug-conductor, integrity-guardian, knowledge-evolution, etc.
│   └── skills/                  # Factory's own skills (40 skills)
│       ├── agent-generation/
│       ├── algo-trading/
│       ├── alignment-check/
│       ├── analyze-knowledge-gaps/
│       ├── axiom-selection/
│       ├── ci-monitor/
│       ├── commit-release/
│       └── ...                       # + more skills
├── patterns/                    # Reusable patterns (100+ files)
│   ├── axioms/                  # Layer 0 axiom definitions
│   ├── principles/              # Layer 2 principle patterns
│   ├── methodologies/           # Layer 3 methodology templates
│   ├── enforcement/             # Enforcement patterns
│   ├── practices/               # Practice patterns
│   ├── agents/                  # Agent pattern definitions
│   ├── skills/                  # Skill pattern definitions
│   ├── games/                   # Workshop game definitions
│   ├── workshops/               # Workshop pattern definitions
│   ├── team-formats/            # Team size adaptations
│   ├── stacks/                  # Stack blueprint patterns
│   ├── templates/               # Template patterns
│   └── workflows/               # Workflow patterns
├── blueprints/                  # Technology stack blueprints (27 blueprints)
│   ├── python-fastapi/
│   ├── python-streamlit/
│   ├── ai-agent-development/
│   ├── multi-agent-systems/
│   ├── typescript-react/
│   ├── nextjs-fullstack/
│   ├── java-spring/
│   ├── kotlin-spring/
│   ├── csharp-dotnet/
│   ├── n8n-automation/
│   ├── sap-abap/
│   ├── sap-rap/
│   ├── sap-cap/
│   └── sap-cpi-pi/
├── knowledge/                   # Reference data (75+ files)
│   └── *.json                   # Stack, workflow, MCP, security, AI patterns
├── templates/                   # Code and document templates (200+ files)
│   ├── factory/                 # Factory templates (cursorrules, PURPOSE.md, etc.)
│   ├── ai/                      # AI agent templates
│   ├── python/                  # Python templates (FastAPI, Streamlit)
│   ├── typescript/              # TypeScript templates (Next.js)
│   ├── java/                    # Java Spring templates
│   ├── csharp/                  # C# Clean Architecture templates
│   ├── abap/                    # SAP ABAP/RAP templates
│   ├── cap/                     # SAP CAP templates
│   ├── integration/             # SAP CPI/PI integration templates
│   ├── automation/              # n8n automation templates
│   ├── workflows/               # CI/CD workflow templates
│   ├── methodology/             # Methodology templates
│   └── docs/                    # Documentation templates
├── docs/                        # Documentation
│   ├── reference/               # Detailed reference docs
│   ├── research/                # Research paper series
│   ├── examples/                # Example walkthroughs
│   └── *.md                     # Guides and tutorials
├── diagrams/                    # Architecture diagrams (Mermaid)
├── scripts/                     # Utility scripts
├── cli/                         # CLI interface
│   └── factory_cli.py
├── tests/                       # Test suite
│   ├── unit/
│   ├── integration/
│   ├── validation/
│   └── fixtures/
├── .github/
│   └── workflows/               # CI/CD workflows
├── .cursorrules                 # Factory behavior rules
├── CHANGELOG.md                 # Version history
└── README.md                    # This file

The factory includes 27 blueprints organized by category. For detailed documentation including use cases, technology stacks, and configuration options, see Blueprints Reference.

The Team Workshop System is grounded in Axiom 0:

“All being and doing is grounded in Love, Truth, and Beauty.”

This foundational axiom precedes all technical axioms (A1-A5) and ensures that collaborative design emerges from:

• Love: Genuine care for humanity and those who depend on our work
• Truth: Honesty, transparency, and verifiability in all things
• Beauty: Harmony, elegance, and wholeness in what we create
• Trust emerges naturally when Love meets Truth over time

Creative Games (Vision & Ideation):

• Future Headlines: Write newspaper headlines from 5 years in the future
• Stakeholder Safari: Role-play as different stakeholders
• Dream Demo: Describe the ideal product demo without constraints

Strategic Games (Ethics & Decisions):

• Dilemma Duel: Debate ethical scenarios with no perfect answer
• Value Auction: Bid limited points on values to reveal priorities
• Trade-Off Tetris: Fit constraints into limited capacity

Collaborative Games (Design & Celebration):

• Agent Trading Cards: Create collectible cards for each agent
• Skill Bingo: Fill bingo cards with needed skills
• Architecture Pictionary: Draw and guess system components
• Demo Derby: Showcase all workshop artifacts
• Gratitude Circle: Express appreciation to team members

For complete facilitation instructions, see docs/TEAM_WORKSHOP_GUIDE.md.

The Factory includes 18 structured learning workshops covering modern technology stacks. Each workshop is a 2.5-hour hands-on session with a proven 5-phase methodology.

Export any workshop to a standalone learning project with full AI assistance:

# Export a workshop to a learning project
python scripts/workshops/export_workshop.py L1_ethereum_fundamentals c:/learning/ethereum
python scripts/workshops/export_workshop.py L7_langchain_fundamentals c:/learning/langchain

Generated artifacts include:

Each workshop follows a 5-phase structure:

Blockchain:   L1 Ethereum ──► L4 Solana ──► L2 Bitcoin
AI Engineer:  L7 LangChain ──► L3 LangGraph ──► L8 RAG ──► L5 CrewAI
Fullstack:    L9 React ──► L10 Next.js ──► L11 FastAPI ──► L13 Docker
ML Engineer:  L14 PyTorch ──► L6 HuggingFace ──► L15 Fine-Tuning

For complete workshop documentation, see docs/LEARNING_WORKSHOPS.md.

These agents can be included in generated projects:

These skills can be included in generated projects:

flowchart TB
    subgraph Agents["Agents (Orchestrators)"]
        A1["requirements-architect"]
        A2["stack-builder"]
        A3["template-generator"]
    end
    
    subgraph Skills["Skills (Procedures)"]
        S1["requirements-gathering"]
        S2["stack-configuration"]
        S3["agent-generation"]
        S4["skill-generation"]
    end
    
    subgraph Knowledge["Knowledge (Data)"]
        K1["patterns/*.json"]
        K2["blueprints/*.json"]
    end
    
    A1 --> S1
    A2 --> S2
    A3 --> S3
    A3 --> S4
    S1 --> K1
    S2 --> K2
    
    style Agents fill:#e3f2fd
    style Skills fill:#e8f5e9
    style Knowledge fill:#fff3e0

• Select core axioms (A1-A5 always included)
• Choose optional axioms (A6-A10)
• Configure derivation rules

• Mission statement (verifiable)
• Primary stakeholders (specific)
• Success criteria (measurable)

• Ethical boundaries and quality standards
• Methodology selection (Agile/Kanban/R&D/Enterprise)
• Team size and coordination patterns

• Quality, safety, integrity enforcement
• Daily, craft, alignment practices

• Project context and domain
• Technology stack and frameworks
• Workflow triggers and artifacts
• Knowledge domain and conventions
• Agent and skill capabilities

Generated projects include all 5-layer artifacts:

{PROJECT_NAME}/
├── .cursor/
│   ├── agents/               # AI agent definitions
│   └── skills/               # Reusable skill definitions
├── knowledge/                # Structured reference data (JSON)
├── templates/                # Code and document templates
├── workflows/
│   └── methodology.yaml      # Layer 3: Methodology config
├── src/                      # Source code
├── tests/                    # Test files
├── docs/                     # User documentation
├── .cursorrules              # 5-layer agent rules (L0-L4)
├── PURPOSE.md                # Layer 1: Mission & purpose
├── enforcement.yaml          # Enforcement patterns (Comprehensive)
├── practices.yaml            # Team practices (Comprehensive)
└── README.md                 # Project documentation

flowchart TB
    subgraph Project["Generated Project"]
        subgraph Cursor[".cursor/"]
            A["agents/*.md"]
            S["skills/*/SKILL.md"]
        end
        K["knowledge/*.json"]
        T["templates/*"]
        CR[".cursorrules"]
    end
    
    A -->|"uses"| S
    S -->|"queries"| K
    CR -->|"configures"| A
    
    style Cursor fill:#e3f2fd
    style K fill:#fff3e0

The factory includes 50+ MCP servers across 6 categories. See the full MCP Servers Guide for details.

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
    },
    "git": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-git", "--repository", "."]
    },
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    }
  }
}

For detailed setup instructions, see docs/MCP-SERVERS.md.

You can create projects from YAML or JSON configuration:

# project-config.yaml
project_name: my-api-project
project_description: REST API with FastAPI
domain: web-development
primary_language: python
frameworks:
  - fastapi
  - sqlalchemy
triggers:
  - jira
  - confluence
agents:
  - code-reviewer
  - test-generator
skills:
  - bugfix-workflow
  - feature-workflow
  - tdd
mcp_servers:
  - name: atlassian
    url: https://mcp.atlassian.com/v1/sse
    purpose: Jira/Confluence integration

1. Create directory: blueprints/{blueprint-id}/
2. Create blueprint.json with:
   • Metadata (name, description, tags)
   • Stack configuration
   • Agent and skill references
   • Template paths

1. Create pattern JSON in appropriate patterns/ directory
2. Follow the pattern schema in patterns/{type}/{type}-pattern.json
3. Reference pattern in blueprints

1. Create skill directory: .cursor/skills/{skill-name}/
2. Create SKILL.md with frontmatter and process documentation
3. Add to factory’s skill registry

• Python 3.10+
• Cursor IDE
• PyYAML (for YAML config support)

Tool Paths: Commands below use default Windows paths from .cursor/config/tools.json.
See Configuration Guide to customize for your environment.
See Path Configuration Guide for directory customization and environment variables.

# Install test dependencies
C:\App\Anaconda\Scripts\pip.exe install -r requirements-dev.txt

The project includes a comprehensive pytest-based test suite with unit tests, integration tests, and validation tests.

# Run all tests
C:\App\Anaconda\python.exe -m pytest tests/ -v

# Run with coverage report
C:\App\Anaconda\python.exe -m pytest tests/ --cov=scripts --cov=cli --cov-report=html

# Run specific test categories
C:\App\Anaconda\python.exe -m pytest tests/unit/ -v           # Unit tests
C:\App\Anaconda\python.exe -m pytest tests/integration/ -v    # Integration tests
C:\App\Anaconda\python.exe -m pytest tests/validation/ -v     # Schema validation tests

# Run specific test file
C:\App\Anaconda\python.exe -m pytest tests/unit/test_project_config.py -v

# Run tests matching a pattern
C:\App\Anaconda\python.exe -m pytest tests/ -k "blueprint" -v

For detailed testing documentation, see docs/TESTING.md.

tests/
├── conftest.py                 # Shared pytest fixtures
├── unit/                       # Unit tests (60 tests)
│   ├── test_project_config.py  # ProjectConfig dataclass tests
│   ├── test_project_generator.py # ProjectGenerator class tests
│   └── test_pattern_loading.py # Pattern/blueprint loading tests
├── integration/                # Integration tests (38 tests)
│   ├── test_cli.py             # CLI command tests
│   └── test_generation.py      # End-to-end generation tests
├── validation/                 # Schema validation tests (33 tests)
│   ├── test_blueprint_schema.py
│   ├── test_pattern_schema.py
│   └── test_knowledge_schema.py
└── fixtures/                   # Test fixture files
    ├── sample_config.yaml
    ├── sample_config.json
    └── minimal_blueprint.json

# Run the CLI help
C:\App\Anaconda\python.exe cli\factory_cli.py --help

# List blueprints
C:\App\Anaconda\python.exe cli\factory_cli.py --list-blueprints

# List patterns
C:\App\Anaconda\python.exe cli\factory_cli.py --list-patterns

# Generate test project from blueprint
C:\App\Anaconda\python.exe cli\factory_cli.py --blueprint python-fastapi --output C:\Temp\test-project

# Generate from config file
C:\App\Anaconda\python.exe cli\factory_cli.py --config tests\fixtures\sample_config.yaml --output C:\Temp\yaml-project

The project uses GitHub Actions for CI/CD. Tests run automatically on:

• Push to main or develop branches
• Pull requests to main or develop branches

The CI pipeline includes:

• Test Matrix: Python 3.10, 3.11, 3.12 on Ubuntu and Windows
• Code Quality: Ruff linter checks
• JSON Validation: Syntax validation for all JSON files
• Generation Test: End-to-end project generation verification

See .github/workflows/ci.yml for the full configuration.

Complete, step-by-step examples showing the factory in action with real technology stacks:

Each example includes a complete walkthrough, sample answers, and expected output files for verification.

Comprehensive academic documentation of the methodology (~150 pages, CC0 licensed):

1. Fork the repository
2. Create a feature branch
3. Add patterns, blueprints, or skills
4. Test generation
5. Submit pull request

cursor-ide ai-agents llm-automation code-generation agent-orchestration meta-programming project-scaffolding development-workflow mcp-servers ai-assisted-development cursor-rules agent-factory skill-composition knowledge-management prompt-engineering

Categories:

• AI Development Tools: Cursor IDE agent system generator, LLM behavior configuration
• Code Generation: Project scaffolding, template-based generation, multi-stack support
• Agent Architecture: Agent/skill composition patterns, knowledge-grounded workflows
• Enterprise Integration: SAP, Jira, Confluence, GitHub via MCP servers

This project incorporates ideas and patterns from several valuable sources:

For complete academic references, see docs/research/REFERENCES.md.

MIT License

Cursor Agent Factory v3.14.0
Meta-system for generating Cursor AI agent development systems
Now with 5-layer architecture: Integrity -> Purpose -> Principles -> Methodology -> Technical
50+ MCP servers across 6 categories with starter packs and role-based recommendations
Formally verified axiom compliance with Lean 4 mathematical proofs
Agent Society Verification implementation for dynamic multi-agent systems