Poiesis Framework

From the Greek ποίησις (poiesis): the act of creation, making, and bringing into being.

A comprehensive methodology and automation system for building maintainable, well-documented software systems with AI assistance.

🧠 What is Poiesis Framework?

Poiesis Framework serves dual purposes:

1. Development Methodology

A comprehensive framework that emphasizes:

• 📦 Component-Based Architecture - Components = Expertise, Sub-Components = Function
• 📝 Documentation First - Understand WHY before HOW
• 🧪 Evidence-Based Testing - Real I/O proof, not just passing tests
• 🎯 Context-Driven Development - Clear package boundaries and consumer needs
• 🤖 AI-Assisted Development - Cursor AI rules that enforce methodology
• 🔄 Continuous Learning - Institutional memory through qa.md

2. Cursor Commands & Automation

Built-in commands for common Poiesis workflows:

• Tier Wiring - Config-driven setup for data, intelligence, and logging tiers
• Report Communication - Local file-based report sharing between packages
• Code Review - Automated review against Poiesis principles (coming soon)
• Component Management - Create, refactor, and verify components (coming soon)
• More coming soon - See .cursor/commands/help.sh for full list

🏗️ Architecture-Agnostic Framework

Poiesis is architecture-agnostic - it works with any technology stack.

Configure your infrastructure packages in poiesis.config.json:

• Data tier package (e.g., your MongoDB/PostgreSQL abstraction)
• Intelligence tier package (e.g., your AI/ML service layer)
• Logging system (e.g., your structured logging package)

Poiesis enforces methodology (boundaries, context, testing), not specific technologies.

See:

• /docs/packages-topology.md for complete tier landscape
• /docs/standard-locations.md for file placement guidelines
• /docs/config-discovery.md for configuration management
• /docs/location-index.md for quick location reference

🚀 Quick Start

Option 1: Use as Development Framework

# Clone the framework template
git clone https://github.com/your-org/poiesis-framework.git my-new-project
cd my-new-project

# Remove framework's git history and start fresh
rm -rf .git
git init

# Initialize for your project
./init-poiesis.sh "@mycompany/my-package-name"

# Copy the Poiesis framework to your project
cp -r poiesis-project/* /path/to/your/project/

# Navigate to your project
cd /path/to/your/project

# Run the initialization script
./poiesis-framework/init-poiesis.sh @your-org/your-package-name

# Open in Cursor - AI will automatically enforce methodology
cursor .

# Explore available commands
bash .cursor/commands/help.sh

# Wire your infrastructure tiers
bash .cursor/commands/tier-data.sh
bash .cursor/commands/tier-logging.sh

Option 2: Use CLI Tools

# Install globally (for policy-sync and other framework tools)
npm install -g poiesis-framework

# Build from source
npm run build

# Sync framework to multiple projects
bash .cursor/commands/policy-sync.sh

Option 3: Distribution Scripts (For Multiple Projects)

If you have multiple Poiesis projects to maintain:

# Setup distribution configuration (first time only)
.\setup-distribution.ps1

# Edit distribution-config.json with your paths
# Then distribute to all projects
.\distribute-framework.ps1

Distribution Features:

• Configurable paths: Edit distribution-config.json with your project locations
• Template included: distribution-config.template.json for easy setup
• Automatic initialization: Runs init scripts for each project
• Git-ignored config: Your local paths stay private
• Cursor commands: Run npm run cursor:COMMAND in any project (e.g., npm run cursor:poiesis)

📚 New to Poiesis? Start with:

• START-HERE.md - 60-second overview + quick start paths
• FRAMEWORK-SUMMARY.md - One document to understand everything
• docs/quick-start.md - 15-minute hands-on guide

📋 Core Commands (Nerve Center)

Project Management

poiesis add-project <id> <name> <path> <variation>  # Add project
poiesis list-projects                               # List all projects
poiesis deploy <project-id|all>                     # Deploy projects

Communication

poiesis send-message <from> <to> <type> <subject> <content>  # Send message
poiesis send-to-human <from> <type> <subject> <content>      # Send to human
poiesis get-messages [component]                             # Get messages

Monitoring & Reports

poiesis status         # Show nerve center status
poiesis health-check   # Check all project health
poiesis report         # Generate comprehensive report

🏗️ Architecture

Poiesis Variations

The framework supports three main variations:

• Xronox-Poiesis - Data tier focus (databases, logging, data operations)
• Athenix-Poiesis - Intelligence tier focus (AI/ML, analytics, intelligence)
• Poiesis - Full framework (complete feature set)

Communication System

Each project gets structured communication folders:

project/
├── communications/
│   ├── from-others/          # Messages from other components
│   ├── to-others/            # Messages sent to other components
│   ├── from-human/           # Messages from human
│   └── to-human/             # Messages sent to human

Message Types

• report: Status updates, results, findings
• request: Asking for something (data, action, information)
• fix: Reporting bugs or requesting fixes
• feedback: Providing feedback on received messages
• query: Asking questions or seeking clarification

🤖 Automation Capabilities

The nerve center includes 12+ automation features:

1. Auto-discovery - Find new Poiesis projects automatically
2. Dependency-aware deployment - Deploy in correct order
3. Cross-project communication - Orchestrate messaging
4. Health monitoring - Monitor all project health
5. Global testing - Run tests across all projects
6. Configuration sync - Synchronize configs across projects
7. Backup system - Automated project backups
8. Dependency management - Update dependencies
9. Log aggregation - Collect logs from all projects
10. Performance monitoring - Monitor project performance
11. Security scanning - Run security scans
12. Documentation generation - Generate docs for all projects

📊 Function-Based API

The framework provides a comprehensive function-based API for programmatic use:

import { 
  initNerveCenter,
  addProject, 
  deployProject,
  sendMessage,
  checkHealth,
  generateReport 
} from 'poiesis-framework';

// Initialize nerve center
await initNerveCenter();

// Add a project
addProject({
  projectId: 'user-service',
  name: 'User Service',
  path: '/path/to/user-service',
  variation: 'poiesis',
  dependencies: ['auth-service']
});

// Deploy project
await deployProject('user-service');

// Send message between components
await sendMessage({
  fromComponent: 'user-service',
  toComponent: 'auth-service',
  type: 'report',
  subject: 'Status Update',
  content: 'All systems operational'
});

// Check health
await checkHealth();

// Generate report
const report = await generateReport();

What's Included (Development Framework)

📋 Cursor AI Rules (.cursor/rules/)

Comprehensive MDC files that teach Cursor AI the Poiesis methodology:

Core Rules:

• 00-poiesis-core.mdc - Core doctrine, Ask-First/Validate-First/Minimal-Change, diagnostic problem-solving
• 01-poiesis-collaboration.mdc - Collaboration boundaries and communication protocols
• 45-poiesis-configuration.mdc - Environment management and configuration enforcement
• 90-poiesis-verification.mdc - Standard verification gates for all changes

Variant-Specific Rules:

• 01-athenix-collaboration.mdc - AI/Intelligence tier collaboration rules
• 01-xronox-collaboration.mdc - Data tier collaboration rules
• 45-athenix-configuration.mdc - AI tier configuration management
• 45-xronox-configuration.mdc - Data tier configuration management
• 90-athenix-verification.mdc - AI tier verification gates
• 90-xronox-verification.mdc - Data tier verification gates

📚 Documentation (/docs/)

Dual Documentation Strategy:

The framework provides two versions of key files:

• Template versions (*-template.md) - Generic, for any organization
• Implementation versions (no suffix) - NX Intelligence/Sagente specific

Core documentation files:

• context.md - WHY your package exists (boundaries, consumers, scope)
• packages-topology.md - Your architecture packages (configured in poiesis.config.json)
• packages-topology-template.md - Generic template version
• implementation-landscape.md - REAL tech stack (MongoDB, Redis, S3, OpenAI, etc.)
• implementation-landscape-template.md - Generic template version
• nx-intelligence-specifics.md - NX Intelligence/Sagente specific details
• config-patterns.md - Configuration file patterns ([tier]-config.json)
• poiesis.md - The complete methodology
• testing-principles.md - Testing rules and requirements
• developer-principles.md - Core development principles
• logging-guide.md - Complete logging methodology (xronolog)
• data-tier-guide.md - Complete data tier methodology
• intelligence-tier-guide.md - Complete AI tier methodology
• infrastructure-setup.md - Step-by-step infrastructure setup
• quick-start.md - 15-minute quick start guide
• poiesis-quick-ref.md - Quick reference card
• templates-guide.md - How to use all templates

📝 Templates (/templates/)

Ready-to-use templates:

Development Templates:

• cr-template-cursor.md - Change requests from Cursor AI
• cr-template-human.md - Change requests from humans
• bug-report-cursor.md - Bug reports from Cursor AI
• bug-report-human.md - Bug reports from humans
• test-plan-cursor.md - Test planning template
• demo-template-cursor.md - Individual test demos

Setup Templates:

• package.json - With all infrastructure packages pre-configured
• env-template.txt - All required environment variables (copy to .env)
• docker-compose.yml - Local MongoDB + Redis for development
• tier-configs/ - Configuration templates for all 5 tiers

Core Concepts

Infrastructure First: Logging, Data & AI Tiers

Poiesis enforces concrete infrastructure patterns using proven packages:

Logging: xronolog

import { logger } from './utils/logger';

// ALWAYS use structured logging (5 levels: ERROR, WARN, INFO, DEBUG, VERBOSE)
logger.info('User registered', {
  userId: user.id,
  email: user.email
});

// NEVER use console.log()
console.log('Something happened');  // ❌ Cursor will flag this

Data Tier Example:

// Import from YOUR configured data tier package (see poiesis.config.json)
import { getDataTier } from './data';

// ALWAYS use data tier abstraction
const dataTier = getDataTier();

await dataTier.create('users', data, metadata);  // ✅ Uses your configured package

// NEVER access database directly
await db.collection('users').insertOne(data);  // ❌ Cursor will flag this

AI Tier Example:

// Import from YOUR configured intelligence tier package (see poiesis.config.json)
import { getIntelligenceTier } from './ai';

// ALWAYS use intelligence tier for AI capabilities
const intelligenceTier = getIntelligenceTier();

const result = await intelligenceTier.execute({
  task: 'USER-QUERY',
  context: { /* ... */ },
  options: {
    /* Your AI tier options */
  }
});

// NEVER do direct AI calls
const openai = new OpenAI();  // ❌ Cursor will flag this
await openai.chat.completions.create();  // ❌

Why these matter:

• Logging: Structured, searchable, level-controlled
• Data Tier: Versioning, audit trails, multi-tenancy, time-travel
• AI Tier: Memory, learning, context, cost optimization

Cursor enforces all three patterns automatically.

Components = Expertise

// ✅ GOOD: Component has single domain expertise
class DataComponent {
  // Knows: data persistence, retrieval, caching
}

// ❌ BAD: Component mixing multiple expertises
class UserComponent {
  // Mixing: data, validation, email, analytics
}

Sub-Components = Function

// ✅ GOOD: Sub-component does one thing
class CacheInvalidator {
  invalidate(key: string): void { }
}

// ❌ BAD: Sub-component doing multiple things
class CacheManager {
  invalidate(key: string): void { }
  buildQuery(sql: string): Query { }  // Wrong! Query building is different function
}

Context-Driven Decisions

Every package starts with context.md:

## Why This Package Exists
[Business problem you're solving]

## Who This Package Serves  
[Your consumers and their needs]

## Package Boundaries
In Scope: ✅ [What you do]
Out of Scope: ❌ [What you don't do]

Result: Clear "yes/no" framework for feature requests.

Evidence-Based Testing

/demos/
└── cache-invalidator/
    └── basic-invalidation/
        ├── demo.md        # What this tests
        ├── demo.ts        # The test code
        └── /io/
            ├── input.json   # Actual input
            └── output.json  # REAL output (proof it ran)

No output.json = No evidence = Didn't really test

How It Works

1. Session Start (Cursor AI)

Every Cursor session automatically:

1. Read context.md     → Understand package purpose and boundaries
2. Read qa.md          → Learn from past decisions  
3. Read architecture.md → Understand structure
4. Read poiesis.md     → Remember methodology

2. During Development

Cursor AI will:

• ✅ Check changes against package boundaries (context.md)
• ✅ Enforce component/sub-component separation
• ✅ Require evidence for testing (input.json + output.json)
• ✅ Maintain qa.md with learnings
• ✅ Propose fixes following Poiesis principles

3. Before Completion

Cursor AI runs verification:

npm run typecheck  # Types must pass
npm test           # Tests must pass
npm run build      # Build must be clean

Plus documentation checks:

• [ ] Component README updated
• [ ] architecture.md updated
• [ ] qa.md updated with learnings
• [ ] Test plan exists with I/O evidence

🔧 Configuration (Nerve Center)

Environment Variables

The framework uses these environment variables:

• POIESIS_COMMUNICATION_ROOT - Communication directory (default: ./communications)
• POIESIS_LOGS_DIR - Logs directory (default: ./logs)
• POIESIS_BACKUP_DIR - Backup directory (default: ./backups)

📁 Project Structure

poiesis-framework/
├── src/                           # TypeScript source code
│   ├── cli.ts                     # Command-line interface
│   ├── poiesis-nerve-center.ts    # Core nerve center
│   ├── communication-manager.ts   # Communication system
│   ├── deployment-tool.ts         # Deployment automation
│   └── poiesis-cli-functions.ts  # Function-based API
├── dist/                          # Compiled JavaScript
├── .cursor/
│   └── rules/                    # Cursor AI rules (9 .mdc files)
│       ├── 00-poiesis-core.mdc
│       ├── 10-poiesis-boundaries.mdc
│       ├── 15-poiesis-testing.mdc
│       ├── 20-poiesis-migration.mdc
│       ├── 30-poiesis-logging.mdc          # Logging tier enforcement
│       ├── 40-poiesis-data-tier.mdc        # Data tier enforcement
│       ├── 50-poiesis-intelligence-tier.mdc # AI tier enforcement
│       ├── 90-poiesis-verification.mdc
│       └── 99-poiesis-safety.mdc
├── docs/                         # Framework documentation
│   ├── context.md               # Template for package context
│   ├── packages-topology.md     # Infrastructure package mapping
│   ├── poiesis.md               # Complete methodology
│   ├── testing-principles.md    # Testing rules
│   ├── developer-principles.md  # Core principles
│   ├── logging-guide.md         # Logging tier complete guide
│   ├── data-tier-guide.md       # Data tier complete guide
│   ├── intelligence-tier-guide.md  # AI tier complete guide (external)
│   ├── ai-tier-internal.md      # AI tier internal guide
│   ├── agentic-tier-internal.md # Agentic tier internal guide
│   ├── environment-requirements.md  # Empty template
│   ├── architecture.md          # Empty template
│   ├── qa.md                    # Empty template (Cursor maintains)
│   ├── infrastructure-setup.md  # Step-by-step infrastructure setup
│   ├── quick-start.md           # 15-minute quick start
│   ├── poiesis-quick-ref.md     # Quick reference
│   ├── poiesis-complete-summary.md
│   ├── poiesis-complete-index.md
│   └── templates-guide.md       # How to use templates
├── templates/                    # Standalone templates
│   ├── cr-template-cursor.md
│   ├── cr-template-human.md
│   ├── bug-report-cursor.md
│   ├── bug-report-human.md
│   ├── test-plan-cursor.md
│   ├── demo-template-cursor.md
│   ├── package.json             # With infrastructure packages
│   ├── env-template.txt         # Environment variables
│   └── docker-compose.yml       # Local dev environment
├── poiesis-framework/             # Framework variations
│   ├── Xronox-Poiesis/            # Data tier variation
│   ├── Athenix-Poiesis/           # Intelligence tier variation
│   ├── Poiesis/                   # Full variation
│   └── Poiesis-Methodology/       # Framework documentation
├── init-poiesis.sh              # Setup script for new projects
├── .gitignore                   # Ignores reports, node_modules, etc.
├── .cursorrules                 # Framework-specific Cursor rules
├── package.json                   # Package configuration
├── README.md                    # This file
├── SETUP.md                     # Detailed setup guide
├── INFRASTRUCTURE.md            # Infrastructure requirements
├── CONTRIBUTING.md              # Contribution guidelines
└── LICENSE                      # Framework license

🧪 Testing

The framework includes comprehensive testing capabilities:

# Run health checks
poiesis health-check

# Run global test suite
poiesis run-tests

# Generate test reports
poiesis report --type all

🔒 Security

• All communication is logged and auditable
• Environment variables for sensitive configuration
• No hardcoded secrets or credentials
• Safe error handling without exposing internals

📈 Monitoring & Reporting

Status Dashboard

poiesis status

Shows:

• Nerve center initialization status
• Total projects managed
• Active automation tasks
• Communication system status

Comprehensive Reports

poiesis report

Generates:

• Project Report: Health, variations, deployment status
• Communication Report: Message statistics, delivery rates
• Automation Report: Task execution, success rates

Philosophy

Documentation Before Code

Traditional:

Write code → Hope it works → Document later (maybe)

Poiesis:

context.md → Understand WHY → Design components → Implement → Prove with evidence

Quality Over Speed

We value:

• ✅ Proper decomposition over quick hacks
• ✅ Real testing over mock testing
• ✅ Clear boundaries over convenience
• ✅ Evidence over assumptions
• ✅ Learning over forgetting

AI as Partner

Cursor AI becomes your:

• Architectural reviewer - Checks component boundaries
• Context enforcer - Validates against package scope
• Documentation maintainer - Updates qa.md automatically
• Testing advocate - Requires I/O evidence
• Learning system - Remembers and applies past lessons

Benefits

For Individual Developers

• 🎯 Clear decisions (context.md provides framework)
• 📚 Less mental overhead (documentation is always current)
• 🤖 AI that understands your goals (via Cursor rules)
• 🧪 Confidence in changes (evidence-based testing)
• 🚫 No bad patterns (Cursor flags console.log(), direct MongoDB access)
• ✅ Infrastructure enforced (logging and data tier are automatic)

For Teams

• 🔄 Consistent patterns across projects
• 📖 Onboarding is reading context.md
• 🤝 Shared understanding via documentation
• 🚀 AI assistance that knows your conventions
• 📝 Institutional memory in qa.md

For Organizations

• 🏗️ Maintainable architecture (clear component boundaries)
• 📊 Traceable decisions (context.md + qa.md)
• ⚡ Faster development (AI does enforcement)
• 🔒 Reduced technical debt (prevented by rules)

🛠️ Development

Building from Source

git clone https://github.com/your-org/poiesis-framework.git
cd poiesis-framework
npm install
npm run build

Contributing

This framework is meant to be forked and customized for your organization's needs.

Customization Ideas

• Add organization-specific rules to .cursor/rules/
• Extend templates in /templates/
• Add language-specific conventions
• Include compliance requirements
• Add security scanning rules

Sharing Improvements

If you make improvements that would benefit others:

1. Fork this repo
2. Make your changes
3. Submit a pull request
4. Explain the improvement in PR description

Requirements

Development Tools

• Cursor AI - IDE with AI assistance (https://cursor.sh)
• Git - Version control
• Node.js 16+ - For TypeScript/JavaScript projects

Infrastructure Services

For projects using the infrastructure tiers, you need:

• MongoDB 5.0+ - Data tier storage
• Redis 6.0+ - Caching and working memory
• S3-Compatible Storage (optional) - Large content storage
• AI Provider Account (optional) - OpenAI, Anthropic, or Google AI

See: /docs/implementation-landscape.md for complete infrastructure details

Development: Use Docker Compose for local MongoDB and Redis (see setup guide)

FAQ

Q: Is this only for TypeScript projects?

A: No! While examples use TypeScript, Poiesis principles apply to any language. The .mdc rules are language-agnostic.

Q: Do I need Cursor AI?

A: The framework is designed for Cursor AI, but the documentation and principles work without it. You just lose the automatic enforcement.

Q: Can I use this with other AI tools?

A: The .mdc files are Cursor-specific, but you can adapt the principles to other AI pair programming tools.

Q: What if my project is already started?

A: Add Poiesis incrementally:

1. Copy .cursor/rules/ to your project
2. Install infrastructure: Install packages listed in your poiesis.config.json
3. Set up infrastructure (see INFRASTRUCTURE.md and docs/implementation-landscape.md)
4. Create context.md documenting current state
5. Start following patterns for new code
6. Refactor old code gradually (Cursor will help identify violations)

Q: Is this overkill for small projects?

A: Poiesis scales down. For small projects:

• Skip some templates
• Simplify context.md
• Keep the core: component boundaries + testing evidence

📚 Documentation

• Framework Overview
• Xronox-Poiesis Guide
• Athenix-Poiesis Guide
• Full Poiesis Guide

Documentation Map

Getting Started:

• START-HERE.md - Begin here if new to Poiesis
• FRAMEWORK-SUMMARY.md - Complete overview in one document
• docs/quick-start.md - 15-minute hands-on guide
• SETUP.md - Detailed setup instructions

Infrastructure:

• INFRASTRUCTURE.md - Infrastructure requirements overview
• docs/packages-topology.md - Package selection guide (REAL packages)
• docs/implementation-landscape.md - Actual tech stack (MongoDB, Redis, etc.)
• docs/infrastructure-setup.md - Step-by-step infrastructure setup

Methodology:

• docs/poiesis.md - Complete methodology
• docs/poiesis-quick-ref.md - Quick reference card
• docs/testing-principles.md - Testing requirements
• docs/developer-principles.md - Core principles

Infrastructure Guides:

• docs/logging-guide.md - Complete xronolog guide
• docs/data-tier-guide.md - Complete data tier guide
• docs/intelligence-tier-guide.md - Complete intelligence tier guide
• docs/ai-tier-internal.md - For building AI tier packages
• docs/agentic-tier-internal.md - For building agentic packages

Contributing:

• CONTRIBUTING.md - How to contribute to framework
• VERIFICATION.md - Framework completeness checklist

🤝 Support

• Issues: https://github.com/your-org/poiesis-framework/issues
• Discussions: https://github.com/your-org/poiesis-framework/discussions
• Documentation: See poiesis-framework/Poiesis-Methodology/
• Communication: Use the nerve center messaging system

📄 License

MIT License - see LICENSE file for details.

🎯 Roadmap

• [ ] Web dashboard for nerve center
• [ ] Real-time project monitoring
• [ ] Advanced automation workflows
• [ ] Integration with CI/CD systems
• [ ] Plugin system for custom automation

Credits

Created by the team at NX Intelligence.

Inspired by:

• Domain-Driven Design (Eric Evans)
• Clean Architecture (Robert C. Martin)
• Test-Driven Development (Kent Beck)
• Documentation-Driven Development

Made better with: Cursor AI pair programming.

The Poiesis Framework - Your comprehensive development methodology and nerve center for all Poiesis projects 🧠

Built with ❤️ for the Poiesis ecosystem

Remember: Build by expertise. Compose by function. Prove by evidence.