Planning saves debugging time. Planning thoroughly upfront typically prevents days of fixing architectural issues later.

Instruction Format Options

This methodology supports multiple instruction formats:

• Prose (Markdown/XML): Natural language with structural headings. Paste directly into web-based AI chat interfaces.
• PAG (Pattern Abstract Grammar): Structured instruction syntax using explicit keywords (READ, WRITE, SET, VALIDATE). Reduces interpretive ambiguity through code-like patterns. Effective for CLI-based AI agents or when explicit constraints matter.

The principles remain identical; choose the format that matches your AI interface.

The Four Stages

Stage 1: AI Behavioral Configuration

Deploy systematic behavioral consistency and constraint enforcement:

1. Configure AI Custom Instructions:

   Set up AI-PREFERENCES.XML as custom instructions. This establishes behavioral constraints and uncertainty flagging with ⚠️ indicators when the AI lacks certainty.

2. RECOMMENDED: Load Persona Framework:

   Upload CORE-PERSONA-FRAMEWORK.json and select domain-appropriate persona:

   • GUIDE-PERSONA.json - Methodology enforcement specialist (prevents vibe coding)
   • TECDOC-PERSONA.json - Technical documentation specialist
   • R&D-PERSONA.json - Research scientist with absolute code quality standards
   • MURMATE-PERSONA.json - Visual systems specialist
   • Create project-specific persona using CREATE-PERSONA-PLUGIN.json

3. RECOMMENDED: Activate Persona:

   Issue command: "Simulate Persona"

Stage 2: Collaborative Planning

Share METHODOLOGY.XML with the AI to structure your project plan. Work together to:

1. Define scope and completion criteria
2. Identify components and dependencies
3. Structure phases based on logical progression
4. Generate systematic tasks with measurable checkpoints

Output: A development plan following dependency chains with modular boundaries.

PAG Alternative: For explicit structure, express your plan using PAG phases with validation gates:

# PHASE 1: Core Implementation

## PURPOSE
Implement primary application logic.

## DEPENDENCIES
Phase 0 infrastructure complete.

## VALIDATION GATE
✅ All core functions implemented
✅ Unit tests passing
✅ Benchmarks integrated

Stage 3: Systematic Implementation

Work phase by phase, section by section. Each request follows: "Can you implement [specific component]?" with focused objectives.

File size stays ≤150 lines. This constraint provides:

• Smaller context windows for processing
• Focused implementation over multi-function attempts
• Easier sharing and debugging

Implementation flow:

Request (prose or PAG) → AI processes → Validate → Benchmark → Continue

Stage 4: Data-Driven Iteration

The benchmarking suite (built first) provides performance data throughout development. Feed this data back to the AI for optimization decisions based on measurements rather than guesswork.

Why This Approach Works

Decision Processing: AI handles "Can you do A?" more reliably than "Can you do A, B, C, D, E, F, G, H?"

Context Management: Small files and bounded problems prevent the AI from juggling multiple concerns simultaneously.

Behavioral Constraint Enforcement: Persona system prevents AI drift through systematic character validation, maintaining consistent collaboration patterns across extended sessions.

Empirical Validation: Performance data replaces subjective assessment. Decisions come from measurable outcomes.

Systematic Constraints: Architectural checkpoints, file size limits, and dependency gates force consistent behavior.

Structured Instruction Clarity: By reducing interpretive ambiguity. ALWAYS: Keep files under 150 lines is less ambiguous than "try to keep files small."

Example Projects

• Discord Bot Template - Production-ready bot foundation with plugin architecture, security, API management, and comprehensive testing. 46 files, all under 150 lines, with benchmarking suite and automated compliance checking. (View Project Structure)

• PhiCode Runtime - Programming language runtime engine with transpilation, caching, security validation, and Rust acceleration. Complex system maintaining architectural discipline across 70+ modules. (View Project Structure)

• PhiPipe - CI/CD regression detection system with statistical analysis, GitHub integration, and concurrent processing. Go-based service handling performance baselines and automated regression alerts. (View Project Structure)

You can compare the methodology principles to the codebase structure to see how the approach translates to working code.

Implementation Steps

Format Selection

Each format emphasizes different domains:

| Format | Best For | Characteristics | |--------|----------|-----------------| | Markdown (.md) | Documentation, web browser AI | Human-readable, AI continues structure naturally | | XML (.xml) | Machine parsing, structured prompts | Explicit tags, code-like structure | | JSON (.json) | Configuration, programmatic access | Strict syntax, data exchange | | PAG | CLI agents, explicit constraints | Validation gates, ALWAYS/NEVER rules |

XML and JSON provide code-like structure that tends to strengthen code generation while reducing unnecessary jargon. Markdown works well for documentation as AI recognizes and continues the structure naturally.

PAG is particularly effective when you need explicit validation gates and constraint enforcement. See PAG Documentation for full language reference.

View Prompt Formats

Setup

1. Configure AI with AI-PREFERENCES.XML as custom instructions
2. RECOMMENDED: Share CORE-PERSONA-FRAMEWORK.json + selected PERSONA.json (Could potentially be placed in custom instructions)
3. RECOMMENDED: Issue command: "Simulate Persona"
4. Share METHODOLOGY.XML for planning session
5. Collaborate on project structure and phases
6. Generate systematic development plan

Execution

1. Build Phase 0 benchmarking infrastructure first
2. Work through phases sequentially
3. Implement one component per interaction
4. Run benchmarks and share results with AI
5. Validate architectural compliance continuously

Quality Assurance

• Performance regression detection
• Architectural principle validation
• Code duplication auditing
• File size compliance checking
• Dependency boundary verification

Project State Extraction

Use the included project extraction tool systematically to generate structured snapshots of your codebase:

python scripts/pr