The New Archon (Beta) - The Operating System for AI Coding Assistants!

2025-12-24 02:39:17 -05:00 · 2025-08-13 07:58:24 -05:00
parent 13e1fc6a0e
commit 59084036f6
603 changed files with 131376 additions and 417 deletions
--- a/PRPs/templates/prp-base.md
+++ b/PRPs/templates/prp-base.md
@@ -0,0 +1,316 @@
+name: "Base PRP Template v3 - Implementation-Focused with Precision Standards"
+description: |
+
+---
+
+## Goal
+
+**Feature Goal**: [Specific, measurable end state of what needs to be built]
+
+**Deliverable**: [Concrete artifact - API endpoint, service class, integration, etc.]
+
+**Success Definition**: [How you'll know this is complete and working]
+
+## User Persona (if applicable)
+
+**Target User**: [Specific user type - developer, end user, admin, etc.]
+
+**Use Case**: [Primary scenario when this feature will be used]
+
+**User Journey**: [Step-by-step flow of how user interacts with this feature]
+
+**Pain Points Addressed**: [Specific user frustrations this feature solves]
+
+## Why
+
+- [Business value and user impact]
+- [Integration with existing features]
+- [Problems this solves and for whom]
+
+## What
+
+[User-visible behavior and technical requirements]
+
+### Success Criteria
+
+- [ ] [Specific measurable outcomes]
+
+## All Needed Context
+
+### Context Completeness Check
+
+_Before writing this PRP, validate: "If someone knew nothing about this codebase, would they have everything needed to implement this successfully?"_
+
+### Documentation & References
+
+```yaml
+# MUST READ - Include these in your context window
+- url: [Complete URL with section anchor]
+  why: [Specific methods/concepts needed for implementation]
+  critical: [Key insights that prevent common implementation errors]
+
+- file: [exact/path/to/pattern/file.py]
+  why: [Specific pattern to follow - class structure, error handling, etc.]
+  pattern: [Brief description of what pattern to extract]
+  gotcha: [Known constraints or limitations to avoid]
+
+- docfile: [PRPs/ai_docs/domain_specific.md]
+  why: [Custom documentation for complex library/integration patterns]
+  section: [Specific section if document is large]
+```
+
+### Current Codebase tree (run `tree` in the root of the project) to get an overview of the codebase
+
+```bash
+
+```
+
+### Desired Codebase tree with files to be added and responsibility of file
+
+```bash
+
+```
+
+### Known Gotchas of our codebase & Library Quirks
+
+```python
+# CRITICAL: [Library name] requires [specific setup]
+# Example: FastAPI requires async functions for endpoints
+# Example: This ORM doesn't support batch inserts over 1000 records
+```
+
+## Implementation Blueprint
+
+### Data models and structure
+
+Create the core data models, we ensure type safety and consistency.
+
+```python
+Examples:
+ - orm models
+ - pydantic models
+ - pydantic schemas
+ - pydantic validators
+
+```
+
+### Implementation Tasks (ordered by dependencies)
+
+```yaml
+Task 1: CREATE src/models/{domain}_models.py
+  - IMPLEMENT: {SpecificModel}Request, {SpecificModel}Response Pydantic models
+  - FOLLOW pattern: src/models/existing_model.py (field validation approach)
+  - NAMING: CamelCase for classes, snake_case for fields
+  - PLACEMENT: Domain-specific model file in src/models/
+
+Task 2: CREATE src/services/{domain}_service.py
+  - IMPLEMENT: {Domain}Service class with async methods
+  - FOLLOW pattern: src/services/database_service.py (service structure, error handling)
+  - NAMING: {Domain}Service class, async def create_*, get_*, update_*, delete_* methods
+  - DEPENDENCIES: Import models from Task 1
+  - PLACEMENT: Service layer in src/services/
+
+Task 3: CREATE src/tools/{action}_{resource}.py
+  - IMPLEMENT: MCP tool wrapper calling service methods
+  - FOLLOW pattern: src/tools/existing_tool.py (FastMCP tool structure)
+  - NAMING: snake_case file name, descriptive tool function name
+  - DEPENDENCIES: Import service from Task 2
+  - PLACEMENT: Tool layer in src/tools/
+
+Task 4: MODIFY src/main.py or src/server.py
+  - INTEGRATE: Register new tool with MCP server
+  - FIND pattern: existing tool registrations
+  - ADD: Import and register new tool following existing pattern
+  - PRESERVE: Existing tool registrations and server configuration
+
+Task 5: CREATE src/services/tests/test_{domain}_service.py
+  - IMPLEMENT: Unit tests for all service methods (happy path, edge cases, error handling)
+  - FOLLOW pattern: src/services/tests/test_existing_service.py (fixture usage, assertion patterns)
+  - NAMING: test_{method}_{scenario} function naming
+  - COVERAGE: All public methods with positive and negative test cases
+  - PLACEMENT: Tests alongside the code they test
+
+Task 6: CREATE src/tools/tests/test_{action}_{resource}.py
+  - IMPLEMENT: Unit tests for MCP tool functionality
+  - FOLLOW pattern: src/tools/tests/test_existing_tool.py (MCP tool testing approach)
+  - MOCK: External service dependencies
+  - COVERAGE: Tool input validation, success responses, error handling
+  - PLACEMENT: Tool tests in src/tools/tests/
+```
+
+### Implementation Patterns & Key Details
+
+```python
+# Show critical patterns and gotchas - keep concise, focus on non-obvious details
+
+# Example: Service method pattern
+async def {domain}_operation(self, request: {Domain}Request) -> {Domain}Response:
+    # PATTERN: Input validation first (follow src/services/existing_service.py)
+    validated = self.validate_request(request)
+
+    # GOTCHA: [Library-specific constraint or requirement]
+    # PATTERN: Error handling approach (reference existing service pattern)
+    # CRITICAL: [Non-obvious requirement or configuration detail]
+
+    return {Domain}Response(status="success", data=result)
+
+# Example: MCP tool pattern
+@app.tool()
+async def {tool_name}({parameters}) -> str:
+    # PATTERN: Tool validation and service delegation (see src/tools/existing_tool.py)
+    # RETURN: JSON string with standardized response format
+```
+
+### Integration Points
+
+```yaml
+DATABASE:
+  - migration: "Add column 'feature_enabled' to users table"
+  - index: "CREATE INDEX idx_feature_lookup ON users(feature_id)"
+
+CONFIG:
+  - add to: config/settings.py
+  - pattern: "FEATURE_TIMEOUT = int(os.getenv('FEATURE_TIMEOUT', '30'))"
+
+ROUTES:
+  - add to: src/api/routes.py
+  - pattern: "router.include_router(feature_router, prefix='/feature')"
+```
+
+## Validation Loop
+
+### Level 1: Syntax & Style (Immediate Feedback)
+
+```bash
+# Run after each file creation - fix before proceeding
+ruff check src/{new_files} --fix     # Auto-format and fix linting issues
+mypy src/{new_files}                 # Type checking with specific files
+ruff format src/{new_files}          # Ensure consistent formatting
+
+# Project-wide validation
+ruff check src/ --fix
+mypy src/
+ruff format src/
+
+# Expected: Zero errors. If errors exist, READ output and fix before proceeding.
+```
+
+### Level 2: Unit Tests (Component Validation)
+
+```bash
+# Test each component as it's created
+uv run pytest src/services/tests/test_{domain}_service.py -v
+uv run pytest src/tools/tests/test_{action}_{resource}.py -v
+
+# Full test suite for affected areas
+uv run pytest src/services/tests/ -v
+uv run pytest src/tools/tests/ -v
+
+# Coverage validation (if coverage tools available)
+uv run pytest src/ --cov=src --cov-report=term-missing
+
+# Expected: All tests pass. If failing, debug root cause and fix implementation.
+```
+
+### Level 3: Integration Testing (System Validation)
+
+```bash
+# Service startup validation
+uv run python main.py &
+sleep 3  # Allow startup time
+
+# Health check validation
+curl -f http://localhost:8000/health || echo "Service health check failed"
+
+# Feature-specific endpoint testing
+curl -X POST http://localhost:8000/{your_endpoint} \
+  -H "Content-Type: application/json" \
+  -d '{"test": "data"}' \
+  | jq .  # Pretty print JSON response
+
+# MCP server validation (if MCP-based)
+# Test MCP tool functionality
+echo '{"method": "tools/call", "params": {"name": "{tool_name}", "arguments": {}}}' | \
+  uv run python -m src.main
+
+# Database validation (if database integration)
+# Verify database schema, connections, migrations
+psql $DATABASE_URL -c "SELECT 1;" || echo "Database connection failed"
+
+# Expected: All integrations working, proper responses, no connection errors
+```
+
+### Level 4: Creative & Domain-Specific Validation
+
+```bash
+# MCP Server Validation Examples:
+
+# Playwright MCP (for web interfaces)
+playwright-mcp --url http://localhost:8000 --test-user-journey
+
+# Docker MCP (for containerized services)
+docker-mcp --build --test --cleanup
+
+# Database MCP (for data operations)
+database-mcp --validate-schema --test-queries --check-performance
+
+# Custom Business Logic Validation
+# [Add domain-specific validation commands here]
+
+# Performance Testing (if performance requirements)
+ab -n 100 -c 10 http://localhost:8000/{endpoint}
+
+# Security Scanning (if security requirements)
+bandit -r src/
+
+# Load Testing (if scalability requirements)
+# wrk -t12 -c400 -d30s http://localhost:8000/{endpoint}
+
+# API Documentation Validation (if API endpoints)
+# swagger-codegen validate -i openapi.json
+
+# Expected: All creative validations pass, performance meets requirements
+```
+
+## Final Validation Checklist
+
+### Technical Validation
+
+- [ ] All 4 validation levels completed successfully
+- [ ] All tests pass: `uv run pytest src/ -v`
+- [ ] No linting errors: `uv run ruff check src/`
+- [ ] No type errors: `uv run mypy src/`
+- [ ] No formatting issues: `uv run ruff format src/ --check`
+
+### Feature Validation
+
+- [ ] All success criteria from "What" section met
+- [ ] Manual testing successful: [specific commands from Level 3]
+- [ ] Error cases handled gracefully with proper error messages
+- [ ] Integration points work as specified
+- [ ] User persona requirements satisfied (if applicable)
+
+### Code Quality Validation
+
+- [ ] Follows existing codebase patterns and naming conventions
+- [ ] File placement matches desired codebase tree structure
+- [ ] Anti-patterns avoided (check against Anti-Patterns section)
+- [ ] Dependencies properly managed and imported
+- [ ] Configuration changes properly integrated
+
+### Documentation & Deployment
+
+- [ ] Code is self-documenting with clear variable/function names
+- [ ] Logs are informative but not verbose
+- [ ] Environment variables documented if new ones added
+
+---
+
+## Anti-Patterns to Avoid
+
+- ❌ Don't create new patterns when existing ones work
+- ❌ Don't skip validation because "it should work"
+- ❌ Don't ignore failing tests - fix them
+- ❌ Don't use sync functions in async context
+- ❌ Don't hardcode values that should be config
+- ❌ Don't catch all exceptions - be specific