Promptonomicon

Transform how you build software with AI through structured, documentation-driven development.

What is Promptonomicon?

Promptonomicon is a framework that gives AI coding assistants a consistent, high-quality development process. It works with any AI tool (Cursor, Claude, Windsurf, etc.) by providing:

• Six-phase process that ensures thorough, well-documented development
• Customizable templates that encode your team's standards and practices
• Single entrypoint (PROMPTONOMICON.md) that any AI can follow
• MCP server integration for real-time package versions and documentation
• AI assistant auto-configuration for Cursor, VS Code, and more

The result: AI assistants that follow your standards, document their work, and deliver production-ready code.

The Process

Every feature follows these six phases:

1. Understand - Investigate requirements and context thoroughly
2. Design - Create comprehensive design documentation
3. Plan - Build detailed, actionable implementation plans
4. Develop - Execute with test-driven development
5. Document - Capture what was actually built
6. Update - Synchronize all reference documentation

Repository Structure

your-repo/
├── .promptonomicon/             # Your customized process templates
│   ├── 1_BUILD_DESIGN.md       # Design doc template
│   ├── 3_BUILD_PLAN.md         # Implementation plan template
│   ├── 4_DEVELOPMENT_PROCESS.md # Your coding standards
│   ├── 5_BUILD_IMPLEMENTATION.md # Reality documentation
│   ├── 6_DOCUMENTATION_UPDATE.md # Update checklist
│   ├── PROMPTONOMICON.md       # AI entrypoint - "start here"
│   └── ai-assistants/          # AI tool configurations (copied during init)
│       ├── cursor-rules.mdc    # Cursor integration (.mdc format)
│       ├── vscode-promptonomicon.md # VS Code integration
│       ├── windsurf-rules.md   # Windsurf integration
│       ├── CLAUDE.md           # Claude instructions (copied to project root)
│       └── claude-reference.md # Claude Desktop MCP setup guide
├── ai-docs/                     # Generated documentation (commit these!)
│   ├── ai-design/              # Design documents
│   ├── ai-plans/               # Implementation plans
│   ├── ai-implementation/      # What was built
│   └── features/               # User-facing docs
├── .scratch/                    # Temporary work (gitignored)
│   ├── README.md               # Usage guide (auto-created)
│   └── todo.md                 # Current feature progress
├── .cursor/                     # Cursor configuration (if detected)
│   ├── rules/promptonomicon.mdc # Auto-created rules (.mdc format)
│   └── mcp.json                # MCP server config
├── CLAUDE.md                    # Claude instructions (auto-created)
└── .mcp.json                    # Generic MCP config (if configured)

Quick Start

Installation

NPM (Recommended)

# Install globally
npm install -g promptonomicon

# Or add to your project
npm install --save-dev promptonomicon

# If installed locally, use npx
npx promptonomicon init

Yarn

# Install globally
yarn global add promptonomicon

# Or add to your project
yarn add --dev promptonomicon

# If installed locally
yarn promptonomicon init

Using Promptonomicon in Your Project

Quick Setup

# Initialize in your project directory
promptonomicon init

# Check your setup
promptonomicon doctor

# Reset templates to latest version (destructive)
promptonomicon reset --yes

Commands

• promptonomicon init - Initialize Promptonomicon in the current directory

  • Creates all required directories
  • Fetches latest templates from GitHub
  • Sets up .scratch directory for temporary work
  • Use --with-mcp-servers to configure MCP servers
  • Use --force to overwrite existing setup

• promptonomicon doctor - Check if your setup is healthy

  • Verifies all directories exist
  • Checks all template files are present
  • Warns if templates haven't been customized
  • Validates MCP server configuration
  • Checks for MCP mentions in templates

• promptonomicon reset - Reset templates to latest version

  • ⚠️ Warning: This overwrites all customizations
  • Fetches fresh templates from GitHub
  • Use --with-mcp-servers to reconfigure MCP
  • Use --yes to skip confirmation

MCP Server Integration

Promptonomicon can configure two Model Context Protocol (MCP) servers:

versionator

• Checks latest versions of packages across all ecosystems
• Works automatically without configuration
• Example: get_package_version("npm", "react") returns latest React version

context7

• Fetches up-to-date documentation for libraries
• Requires CONTEXT7_API_KEY environment variable
• Get your API key at context7.com
• Example: get-library-docs("/react/react") returns current React docs

To configure MCP servers:

# Interactive selection
promptonomicon init --with-mcp-servers

# Specific servers
promptonomicon init --with-mcp-servers=versionator,context7

# Non-interactive with defaults
promptonomicon init -y --with-mcp-servers

AI Assistant Integration

Promptonomicon automatically configures your AI coding assistants:

• Cursor: Creates .cursor/rules/promptonomicon.mdc and .cursor/mcp.json
• VS Code: Creates .vscode/promptonomicon.md
• Windsurf: Creates .windsurf/rules.md
• Claude: Creates CLAUDE.md in project root (works with Claude Desktop/API)
• MCP Setup: See .promptonomicon/ai-assistants/claude-reference.md for Claude Desktop MCP configuration

The configuration files instruct AI assistants to follow the Promptonomicon process automatically.

Manual Setup (Alternative)

1. Copy the framework to your repository:

   • .promptonomicon/ directory (including all templates and PROMPTONOMICON.md)

2. Customize the templates in .promptonomicon/ with your:

   • Design principles and architecture patterns
   • Coding standards and testing approach
   • Documentation style and requirements

3. Use with any AI assistant:

   >  "Follow the Promptonomicon process in
      .promptonomicon/PROMPTONOMICON.md to
      implement [feature]"
   

See INTEGRATION.md for detailed setup instructions, or EXAMPLE_REPO_CONVERSION.md for step-by-step examples of converting an existing repository.

This Repository

This repository serves as both the npm package source and a living example:

• NPM package: Published to npmjs.com/package/promptonomicon
• Framework templates: .promptonomicon/ directory containing all templates
• AI assistant configs: .promptonomicon/ai-assistants/ for tool integration
• MCP server config: .promptonomicon/.mcp.json template
• Example output: ai-docs-sample/ shows what gets generated
• Integration guide: INTEGRATION.md for detailed setup

Development

To contribute or modify Promptonomicon:

# Clone the repository
git clone https://github.com/trianglegrrl/promptonomicon.git
cd promptonomicon

# Install dependencies
npm install

# Test locally
npm link
promptonomicon doctor

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Run tests in watch mode
npm run test:watch

Testing

Promptonomicon includes comprehensive test coverage:

• Unit tests for all CLI commands
• Integration tests for real-world usage scenarios
• Coverage reporting for quality assurance
• CI/CD pipeline that runs tests on multiple Node.js versions

Run the test suite:

npm test              # Run all tests
npm run test:coverage # Generate coverage report
npm run test:watch    # Watch mode for development

Publishing

The package is automatically published to npm when you create a new release on GitHub:

1. Set up npm authentication:

   • Generate an npm access token at npmjs.com/settings
   • Add it as NPMJS_ACCESS_TOKEN in your GitHub repository secrets
   • Go to Settings → Secrets and variables → Actions → New repository secret

2. Create a release:

   # Tag your release
   git tag -a v1.3.1 -m "Release version 1.3.1"
   git push origin v1.3.1
   
   # Then create a release on GitHub
   # The CI/CD pipeline will automatically publish to npm

Key Principles

• Documentation-Driven: Every feature begins and ends with documentation
• Fail-Hard Policy: No silent failures, exceptions propagate naturally
• Process Discipline: Six phases, no shortcuts
• Clean Code: SOLID, DRY, KISS, YAGNI throughout

File Naming Convention

All generated documents follow a consistent pattern:

• Design: ai-docs/ai-design/YYYYMMDD_design_feature_name.md
• Plan: ai-docs/ai-plans/YYYYMMDD_plan_feature_name.md
• Implementation: ai-docs/ai-implementation/YYYYMMDD_implementation_feature_name.md
• Features: ai-docs/features/feature-name.md

Use date +%Y%m%d to generate datestamps.

The .scratch Directory

The .scratch/ directory is your temporary workspace:

• Purpose: Temporary scripts, work-in-progress docs, experiments
• Key file: .scratch/todo.md tracks your progress through the 6 phases
• Git ignored: Nothing here gets committed (except the README)
• Auto-created: The install script sets this up with usage instructions

License

MIT License - see LICENSE for details.

Acknowledgments

Built to standardize AI-assisted software development across teams and tools.