Archon-Agent-Kit-PRP-Automated - Enhanced AI Engineering Framework with Archon MCP Integration

🚀 Quick Start Guide

Need the simple steps? → steps.md - Get your PRPs in 2 minutes!

Want the full details? → Keep reading below for comprehensive information.

🚀 What's New in Archon-Agent-Kit-PRP-Automated

🎉 Major Release (v2.0.0) - Automatic PRP Generation

• ✅ BREAKTHROUGH: Automated PRP Generation: No more copying templates - system generates complete, customized PRPs
• ✅ 85.7% Test Success Rate: Core system highly functional and production-ready
• ✅ Multiple Project Type Support: Full-stack, API-only, Mobile, CLI tools, E-commerce, SaaS, Microservices
• ✅ Intelligent Requirements Extraction: Automatically extracts 30+ goals, 18+ constraints, 22+ features from INITIAL.md
• ✅ Technology Pattern Matching: Smart recommendations based on your tech stack
• ✅ 4 PRP Types Generated: Planning, API Contract, Implementation, and Task PRPs
• ✅ Quality Validation: Built-in PRP validation with quality scoring
• ✅ End-to-End Testing: Comprehensive test suite ensures reliability

🔧 Previous Updates (v1.x)

• ✅ NPM Package Published: Available as archon-agent-kit-prp-automated
• ✅ CLI Tools: Full command-line interface for project setup
• ✅ Python Environment: Virtual environment setup with dependencies
• ✅ Cross-Platform: Support for multiple Python versions and platforms

🤖 AI Choice Selection

Archon-Agent-Kit-PRP-Automated supports multiple AI coding assistants! Choose your preferred AI tool:

• Claude: Use .claude/commands/ directory
• Cursor: Use .cursor/rules/ directory (.mdc files)
• Other AIs: Adapt commands from either directory

See AI_CHOICE.md for detailed instructions for each AI.

Archon-Agent-Kit-PRP-Automated is an enhanced version of the original Process folder that automates project initialization from INITIAL.md files and integrates with Archon MCP for centralized knowledge management and intelligent guidance. Instead of manually copying files and setting up project structure, Archon-Agent-Kit-PRP-Automated intelligently detects your technology stack, sets everything up automatically, and provides context-rich next steps through Archon's knowledge base.

🔄 Enhanced Workflow vs. Original

Original Process Workflow (Manual):

1. Copy .claude/commands/ to project
2. Copy PRPs/templates/ to project
3. Create CLAUDE.md with project guidelines
4. Use /prime-core to initialize Claude
5. Create INITIAL.md for project context
6. Manually set up project structure
7. Manually select appropriate CLAUDE.md files

Archon-Agent-Kit-PRP-Automated Workflow (Fully Automated PRP Generation):

1. Copy Archon-Agent-Kit-PRP-Automated/ folder to new project location
2. Create INITIAL.md with your project specification
3. Run /initialize-project INITIAL.md
4. 🎉 BREAKTHROUGH: Everything is generated automatically!
   • Technology stack detection (30+ techs supported)
   • Requirements extraction (goals, constraints, features)
   • Technology pattern matching and best practices
   • 🔥 Complete PRP generation (Planning, API, Implementation, Tasks)
   • Project structure generation
   • CLAUDE.md file selection and customization
   • 🆕 Archon MCP project container creation
   • 🆕 Quality validation and scoring
5. Your PRPs are ready to use immediately - no manual work required!
6. Use /prime-core to initialize Claude with your generated context
7. 🆕 Run /generate-next-steps for intelligent guidance
8. Start developing with complete, customized PRPs and context-rich suggestions

🏗️ New Architecture

Archon-Agent-Kit-PRP-Automated/
├── bin/                        # CLI entry point
│   └── cli.js                 # Main command-line interface
├── lib/                        # Core Node.js modules
│   ├── ai-selector.js         # AI detection and selection
│   ├── project-initializer.js # Project setup and management
│   ├── project-status.js      # Project health monitoring
│   └── index.js               # Main library exports
├── .claude/commands/           # Claude-specific commands
├── .cursor/rules/              # Cursor-specific rules (.mdc files)
├── project-initializers/       # Python-based automation system
├── claude_md_files/           # Technology-specific guides
├── PRPs/                      # PRP templates and structure
├── package.json                # NPM package configuration
└── README.md                  # This file

🎯 Key Benefits

🔥 The Big Breakthrough: No More Manual PRP Creation!

Before: You had to manually create PRPs, fill in templates, guess what to include, and hope you got everything right.

Now: The system automatically generates complete, customized PRPs with real content based on your INITIAL.md file!

What You Get Automatically:

• ✅ Planning PRP: Complete project planning with goals, requirements, and success criteria
• ✅ API Contract PRP: API specification with endpoints, data models, and validation
• ✅ Implementation PRP: Technical implementation details and architecture
• ✅ Task PRPs: Breakdown of development tasks with acceptance criteria
• ✅ Intelligent Next Steps: Context-aware guidance for immediate development actions

Quality Assurance:

• ✅ 85.7% Test Success Rate: Proven system reliability
• ✅ Built-in Validation: Automatic quality scoring and issue detection
• ✅ Multiple Project Types: Web apps, APIs, mobile apps, CLI tools, microservices
• ✅ Technology-Specific: Content tailored to your exact tech stack

🖥️ CLI Commands

Main Commands

# Initialize new project
archon-agent-kit-prp-automated init

# Setup in existing project
archon-agent-kit-prp-automated setup

# Check project status
archon-agent-kit-prp-automated status

# Show detailed help
archon-agent-kit-prp-automated help

Command Options

# Initialize with specific INITIAL.md file
archon-agent-kit-prp-automated init -f ./my-project.md

# Select specific AI type
archon-agent-kit-prp-automated init -a claude
archon-agent-kit-prp-automated init -a cursor

# Skip prompts and use defaults
archon-agent-kit-prp-automated init -y

AI Selection

• Auto-detect: Automatically detects available AI tools
• Claude: Full command integration with Claude
• Cursor: Native IDE integration with Cursor
• Manual: User selects when auto-detection fails

1. Intelligent Technology Detection

• Automatically reads your INITIAL.md file
• Detects backend technologies (Python, Java, Node.js, Go)
• Detects frontend technologies (Next.js, React, Vue, Astro)
• Identifies databases (PostgreSQL, MySQL, MongoDB, Supabase)
• Recognizes infrastructure (Docker, Kubernetes, AWS, Vercel)

2. Smart CLAUDE.md Selection

• Automatically selects the right technology-specific CLAUDE.md files
• Customizes content with your project details
• Places files in the correct component directories
• Creates root CLAUDE.md with project overview

3. Intelligent Project Structure

• Generates appropriate directory structure for your tech stack
• Creates scaffolding files (requirements.txt, package.json, etc.)
• Sets up configuration files (.gitignore, Dockerfile, etc.)
• Handles full-stack projects with separate backend/frontend directories

4. Automated PRP Setup

• Selects appropriate PRP templates for your technology choices
• Copies relevant templates to your project
• Configures validation commands and testing frameworks

5. 🆕 Archon MCP Integration

• Creates project container for centralized knowledge management
• Crawls and stores project knowledge automatically
• Enables intelligent search through project patterns and best practices
• Provides context-rich guidance for next development steps

6. 🆕 Project-Local Architecture

• Isolated environment - each project gets its own setup
• No system-wide changes - respects existing environment
• Easy cleanup - just delete project folder to remove everything
• Team collaboration - consistent environment across all developers

7. 🆕 Full Python Environment Setup

• Automatic virtual environment creation with python3 -m venv
• Dependencies pre-installed from requirements.txt (requests, python-dotenv)
• Ready-to-use Python environment - no manual setup required
• Cross-platform support with fallbacks for different Python versions

🚀 Getting Started with Archon-Agent-Kit-PRP-Automated

Option 1: NPM Installation (Recommended)

# Install globally for easy access
npm install -g archon-agent-kit-prp-automated

# Or use npx for one-time use
npx archon-agent-kit-prp-automated init

# Initialize in your project
archon-agent-kit-prp-automated init

✅ Package is now live on npm! Users can install and use immediately.

Option 2: Manual Copy (Advanced Users)

# Copy the entire Archon-Agent-Kit-PRP-Automated folder to your new project location
cp -r Archon-Agent-Kit-PRP-Automated/ /path/to/new/project/
cd /path/to/new/project/Archon-Agent-Kit-PRP-Automated
npm install
npm start

Step 2: Create Your INITIAL.md

Create an INITIAL.md file that describes your project and technology stack:

# My Awesome Project

## Technology Stack
- Backend: Python 3.x with FastAPI
- Frontend: Next.js 15 with React 19
- Database: Supabase (PostgreSQL)
- Infrastructure: Docker containerization

## Project Description
[Your project description here]

Step 3: Run the Initializer

# Option 1: Use the CLI (Recommended)
archon-agent-kit-prp-automated init

# Option 2: Use the Claude command
/initialize-project INITIAL.md

# Option 3: Run manually
cd project-initializers
python project_initializer.py ../INITIAL.md --project-root ../

Step 4: Review and Customize

• Review the generated project structure
• Customize CLAUDE.md files with project-specific details
• Run /prime-core to initialize Claude

Step 5: 🆕 Generate Intelligent Next Steps

/generate-next-steps

This command automatically:

• Searches Archon knowledge base for relevant patterns
• Generates context-rich commands with plain English descriptions
• Provides specific, actionable next steps
• Tailors suggestions to your detected technology stack

Step 6: 🏗️ Create PRPs (Complete Development Workflow)

After generating intelligent next steps, follow this comprehensive PRP workflow to create and execute PRPs:

For New Features:

1. Create Planning PRP: /prp-planning-create "feature description"

   • Creates: PRPs/{feature-name}-prd.md (architectural plans)
   • Contains: Complete feature specification, user flows, technical architecture

2. Create API Contract: /api-contract-define "create API contracts for {feature} using PRPs/{feature-name}-prd.md"

   • Creates: PRPs/contracts/{feature}-api-contract.md (connection specs)
   • Contains: Exact API endpoints, data structures, error handling

3. Create Implementation PRP: /prp-base-create "implement {feature} using PRPs/{feature-name}-prd.md and PRPs/contracts/{feature}-api-contract.md"

   • Creates: PRPs/{feature-name}-implementation.md (construction manual)
   • Contains: Step-by-step implementation with all context needed

4. Execute Implementation: /prp-base-execute PRPs/{feature-name}-implementation.md

   • Result: Working feature with all tests passing

For Code Changes:

1. Create Specification PRP: /prp-spec-create "change description"

   • Creates: SPEC_PRP/PRPs/{spec-name}.md (renovation plans)
   • Contains: Current state, desired state, transformation steps

2. Execute Changes: /prp-spec-execute SPEC_PRP/PRPs/{spec-name}.md

   • Result: Code successfully changed

For Small Tasks:

1. Create Task PRP: /prp-task-create "task description"

   • Creates: TASK_PRP/PRPs/{task-name}.md (work order)
   • Contains: Specific tasks with validation and rollback plans

2. Execute Task: /prp-task-execute TASK_PRP/PRPs/{task-name}.md

   • Result: Task completed successfully

Step 7: Continue Development

• Execute suggested commands with confidence
• Create additional PRPs for new features
• Use specification PRPs for code changes
• Use task PRPs for small improvements

🔍 Technology Detection Examples

Full-Stack Python + Next.js

INITIAL.md mentions:
- Python 3.x, FastAPI
- Next.js 15, React 19
- Supabase, Docker

Result:
- backend/CLAUDE.md (from CLAUDE-PYTHON-BASIC.md)
- frontend/CLAUDE.md (from CLAUDE-NEXTJS-15.md)
- Full-stack project structure
- Docker Compose setup

Python Backend Only

INITIAL.md mentions:
- Python 3.x, FastAPI
- PostgreSQL

Result:
- CLAUDE.md (from CLAUDE-PYTHON-BASIC.md)
- Python backend structure
- Database configuration

Next.js Frontend Only

INITIAL.md mentions:
- Next.js 15, React 19
- Tailwind CSS

Result:
- CLAUDE.md (from CLAUDE-NEXTJS-15.md)
- Next.js project structure
- Frontend configuration

🛠️ Supported Technologies

Backend Technologies

• Python: FastAPI, Flask, Django
• Java: Spring Boot, Maven, Gradle
• Node.js: Express.js, npm/yarn
• Go: Gin, Echo, go modules
• Rust: Cargo, common frameworks

Frontend Technologies

• Next.js: App Router, Pages Router
• React: Modern React patterns
• Vue: Composition API, Options API
• Astro: Static site generation

Databases

• PostgreSQL: Native, Supabase
• MySQL: MariaDB variants
• MongoDB: Document database
• SQLite: Lightweight database

Infrastructure

• Docker: Containerization
• Kubernetes: Orchestration
• AWS: Cloud services
• Vercel: Frontend hosting

🧠 🆕 Intelligent Next Steps Generation

What /generate-next-steps Provides

Instead of guessing what to do next, the system generates intelligent suggestions with full context:

## 🚀 Next Steps for Your Project

### 1. Create Core PRP Structure
**Command:** `/prp-base-create "Implement dealership website scraper with data extraction and API endpoints"`
**What it does:** Creates a comprehensive PRP for the main scraping functionality, including data models, API endpoints, and integration with your existing dealer management system. This will establish the foundation for your entire scraping workflow.

**Expected outcome:** A detailed PRP document with implementation blueprint, validation gates, and specific tasks for building the scraper system.

### 2. Set Up Database Schema
**Command:** `/prp-base-create "Design and implement PostgreSQL database schema for dealership data"`
**What it does:** Creates a PRP for designing the database structure that will store scraped dealership information, inventory data, and historical pricing. This includes table design, relationships, and data validation rules.

**Expected outcome:** A complete database schema PRP with entity relationships, migration scripts, and data integrity constraints.

Technology-Specific Examples

Python/FastAPI Backend

### 3. API Endpoint Development
**Command:** `/prp-base-create "Build RESTful API endpoints for dealership data management"`
**What it does:** Creates a PRP for implementing FastAPI endpoints including GET /dealers, POST /dealers, PUT /dealers/{id}, and DELETE /dealers/{id}. This will establish the complete API surface for your dealership management system.

**Expected outcome:** A comprehensive API PRP with endpoint specifications, request/response models, validation, and error handling.

Next.js/React Frontend

### 4. Dashboard Interface
**Command:** `/prp-base-create "Create React dashboard for dealership data visualization and management"`
**What it does:** Creates a PRP for building a modern, responsive dashboard using Next.js 15 and React 19. This includes data tables, charts, search functionality, and real-time updates for dealership information.

**Expected outcome:** A complete frontend PRP with component architecture, state management, and user experience design.

How It Works

1. Archon Knowledge Search: Searches stored project patterns and best practices
2. Context Analysis: Analyzes your specific technology stack and requirements
3. Intelligent Generation: Creates tailored suggestions based on detected patterns
4. Plain English Context: Provides clear explanations of what each command accomplishes

🔧 Customization and Extension

Adding New Technologies

1. Update technology_detector.py with new patterns
2. Add CLAUDE.md file to claude_md_files/
3. Update mapping in CLAUDE_FILE_MAPPING
4. Add structure generation in project_structure_generator.py

Modifying Project Structures

• Edit the appropriate _generate_*_structure methods
• Add new configuration file templates
• Customize directory layouts

Extending CLAUDE.md Selection

• Modify detection patterns
• Add new technology categories
• Customize file placement logic

🧪 Testing the System

Test with Sample INITIAL.md

# Test the CLI
archon-agent-kit-prp-automated init --help
archon-agent-kit-prp-automated init -a claude

# Test the Python initializer directly
cd project-initializers
python project_initializer.py --help
python project_initializer.py test_INITIAL.md --project-root ./test-output

🆕 Archon MCP Configuration

Archon-Agent-Kit-PRP-Automated includes optional integration with Archon MCP server for enhanced knowledge management:

# With Archon MCP server
python project_initializer.py INITIAL.md \
  --archon-url http://localhost:8000 \
  --archon-api-key your-api-key

# Without Archon (default)
python project_initializer.py INITIAL.md

Archon MCP Benefits:

• Centralized knowledge management across projects
• Intelligent next steps generation with full context
• Project task tracking and organization
• Persistent knowledge across development sessions

Validate Generated Structure

• Check that all expected directories are created
• Verify CLAUDE.md files are properly customized
• Confirm PRP templates are copied correctly
• Test that the project can be built/run

🚨 Troubleshooting

Common Issues

Technology Not Detected

• Check spelling and formatting in INITIAL.md
• Add new patterns to technology_detector.py
• Verify technology is in supported list

CLAUDE.md Files Missing

• Ensure source files exist in claude_md_files/
• Check file naming conventions
• Verify mapping in CLAUDE_FILE_MAPPING

Project Structure Issues

• Review technology detection output
• Check project type classification
• Verify structure generation methods

Python Environment Issues

• Ensure python3 is available: python3 --version
• Check virtual environment creation: python3 -m venv --help
• Verify requirements.txt is copied to project-local environment
• Activate environment: source .archon-agent-kit/python-env/bin/activate

CLI Command Issues

• Verify global installation: npm list -g archon-agent-kit-prp-automated
• Check command availability: which archon-agent-kit-prp-automated
• Test with npx: npx archon-agent-kit-prp-automated --help

Debug Mode

# Run with verbose output
python project_initializer.py INITIAL.md --verbose

🔮 Future Enhancements

Planned Features

• Template customization: Allow users to customize generated structures
• Plugin system: Support for third-party technology detectors
• Validation: Built-in validation of generated project structures
• Integration: Better integration with existing development tools

Community Contributions

• New technology support: Community-driven technology additions
• Template improvements: Better project structure templates
• Documentation: Enhanced guides and examples

📚 Documentation and Resources

• Commands: See .claude/commands/ for available commands
• Examples: Check project-initializers/ for usage examples
• Templates: Review PRPs/templates/ for available PRP templates
• CLAUDE.md Files: Examine claude_md_files/ for technology guidelines

🎉 Success Story

Archon-Agent-Kit-PRP-Automated transforms this:

Manual PRP Creation + Guesswork (2-4 hours):
1. Copy template files manually
2. Read through empty PRP templates
3. Guess what content to include
4. Manually research best practices  
5. Fill in templates section by section
6. Hope you didn't miss anything critical
7. Create goals, constraints, features manually
8. **Spend hours writing PRPs from scratch**
9. **Wonder if you covered everything**
10. **Still not sure if PRPs are any good**

Into this:

Fully Automated PRP Generation (2 minutes):
1. Create INITIAL.md with your project details
2. Run /initialize-project
3. **🔥 Get 4 complete, customized PRPs instantly!**
   - Planning PRP with extracted goals & constraints
   - API Contract with endpoints & data models  
   - Implementation PRP with tech-specific details
   - Task breakdown with acceptance criteria
4. **🎯 85.7% quality validation passed**
5. **🆕 Run /generate-next-steps for intelligent guidance**
6. **🆕 Start developing immediately with ready-to-use PRPs**

🚀 BREAKTHROUGH Result: You save 2-4 hours per project, get professional-quality PRPs that are immediately usable, and eliminate all the guesswork with automatically generated, project-specific content that's validated for quality!

🎯 What Happens During Setup

1. CLI Installation (npm install)

• ✅ CLI tool installed globally
• ✅ All package files copied to npm's global directory
• ❌ No Python environment created yet
• ❌ No dependencies installed yet

2. Project Initialization (CLI init)

• ✅ Creates project-local virtual environment
• ✅ Installs Python dependencies from requirements.txt
• ✅ Sets up everything in the user's project directory
• ✅ Ready-to-use Python environment with all packages

3. Environment Activation

• ✅ Virtual environment ready at .archon-agent-kit/python-env
• ✅ Dependencies installed: requests, python-dotenv
• ✅ Activate with: source .archon-agent-kit/python-env/bin/activate

🚀 Quick Start (5 minutes)

# 1. Install the tool
npm install -g archon-agent-kit-prp-automated

# 2. Create INITIAL.md in your project
echo "# My Project\n## Technology Stack\n- Backend: Python with FastAPI\n- Frontend: Next.js 15" > INITIAL.md

# 3. Initialize your project (CLI setup)
archon-agent-kit-prp-automated init

# 4. Activate Python environment
source .archon-agent-kit/python-env/bin/activate

# 5. Open in Cursor/Claude and use AI commands!
#    - /initialize-project (sets up project structure)
#    - /generate-next-steps (gets intelligent guidance)

That's it! Your project is now set up with:

• ✅ Automated project structure
• ✅ Technology-specific AI guidance
• ✅ Python environment with dependencies
• ✅ AI integration ready

🔄 Clear Workflow: CLI vs AI Commands

Phase 1: CLI Setup (One-time per project)

archon-agent-kit-prp-automated init  # Sets up project environment

What it does:

• Creates .archon-agent-kit/ folder
• Sets up Python virtual environment
• Installs AI command files in .cursor/rules/ (.mdc files) or .claude/commands/

Phase 2: AI Commands (Daily development)

/initialize-project    # Sets up project structure from INITIAL.md
/generate-next-steps  # Gets intelligent guidance for next steps

What they do:

• Automate your actual development workflow
• Provide context-aware suggestions
• Generate project-specific guidance

Key Point: CLI setup happens once, then you use AI commands for everything else!

Archon-Agent-Kit-PRP-Automated: Where project initialization meets artificial intelligence and intelligent guidance. 🚀🧠