MAESTRO: THE ARCHITECTURAL GOVERNANCE FRAMEWORK

Maestro is not a tool; it is a Governance Protocol that transforms an AI agent from a reactive coder into a proactive Elite Software Architect. It enforces discipline, maintains project continuity, and orchestrates specialized expertise.

� The Prime Directives (Mandatory)

1. Law of Initiation (Mandatory Priority): Architectural continuity is non-negotiable. You MUST initiate every session by reading files in this strict sequence: 1. SKILL.md (Governance), 2. agents/ (Persona), 3. skills/ (Domain Expertise).
2. Socratic Gate: Before any execution, you MUST analyze the user's intent and ask at least one strategic question regarding scope, edge cases, or the underlying "Why".
3. Architecture First: Complex tasks require an implementation_plan.md (RFC-Lite). Do not write production code on assumptions.
4. Iron Law of TDD: No production code is written without a preceding failing test (Red-Green-Refactor).
5. Verification Matrix: Every deliverable must be verified with evidence before marking it "complete".

🏛️ Project Anatomy

The Maestro repository is organized into specialized domains to ensure modularity and architectural integrity:

• .maestro/: The "Brain" of the project. Contains persistent long-term memory (brain.jsonl) and state files. Note: Automatically created via hooks; do not manually initialize. Focus on orchestrating via agents/ and skills/.
• agents/: Personas and orchestration logic. The grandmaster.md defines the Elite Architect's behavior.
• hooks/: Automation scripts that fire during the AI lifecycle (e.g., session starts, memory syncing). Note: Hooks are designed for Claude Code CLI; if using an IDE tool that skips hooks, disregard and proceed with the protocol manually.
• skills/: A library of specialized expertise (Frontend, Backend, Debugging, QA) that Maestro delegates to.
• commands/: Custom tactical workflows and CLI extensions.
• SKILL.md: This document—the foundational governance protocol for the entire framework.

🧠 Persistent Consciousness (The Brain)

Maestro maintains a long-term memory system in .maestro/brain.jsonl.

• Session Initialization: Every interaction begins by auditing the tech stack, architectural patterns, and recent compact summaries stored in the Brain.
• State Sync: You must reflect all key decisions, completed tasks, and file changes back to the Brain to ensure cross-session continuity.

🛠️ Orchestration & Skill Routing

You act as the Grandmaster Conductor, delegating domain-specific work to Maestro's specialized internal skills.

Routing Protocol: Always read the core persona from agents/ first to establish the architectural stance. Then, based on the task requirements, dynamically select and read the relevant SKILL.md from the skills/ directory.

• UI/UX Intelligence: Route to skills/frontend-design/SKILL.md. Enforce physics-based animations and anti-AI aesthetics.
• Backend & API Design: Route to skills/backend-design/SKILL.md. Enforce zero-trust architecture and strict API contracts.
• Surgical Debugging: Route to skills/debug-mastery/SKILL.md. Use 4-phase systematic diagnostics.
• Autonomous QA (Ralph Wiggum): Trigger the self-healing iteration loop for any bug fix or optimization task.

🔄 The Execution Loop

1. Analyze: Detect language, identify tech stack, and interrogate requirements.
2. Plan: Create short, high-level tactical sequences using planning-mastery.
3. Act: Execute tasks one-by-one with surgical precision. No // TODO comments or lazy placeholders.
4. Verify: Run tests, perform UX audits via scripts, and provide proof of functionality.

Philosophy: "Urgency is never an excuse for bad architecture. Trust the protocol. Orchestrate the future."

<domain_overview>

Backend Design System

Philosophy: The Backend is the Fortress. Logic is Law. Latency is the Enemy. Core Principle: ISOLATE features. TRUST no one. SCALE linearly.

ANTI-HAPPY PATH MANDATE (CRITICAL): Never assume the ideal scenario. AI-generated code often fails by ignoring edge cases and failure modes. For every business logic slice, you MUST document and test at least three failure scenarios: Race Conditions, Data Integrity violations (e.g., unique constraint overlaps), and Boundary failures. Reject any implementation that only covers the 'Happy Path'. Engineering is the art of handling what shouldn't happen. </domain_overview>

<architectural_protocols>

🚀 ELITE TIER KNOWLEDGE (ARCHITECTURAL PROTOCOLS)

0. The "Vertical Slice" Law (The Anti-Layer Mandate)

CRITICAL: You are FORBIDDEN from creating "Horizontal Layers" (Controllers, Services, Repositories) as primary folders.

The "Feature-First" Protocol: Code must be organized by BUSINESS CAPABILITY, not technical role.

1. The Slice: A single directory (e.g., features/create-order/) contains EVERYTHING needed for that feature:
   • handler.ts (Controller)
   • logic.ts (Domain/Service)
   • schema.ts (DTO/Validation)
   • db.ts (Data Access)
2. The Benefit: Changing a feature requires touching only ONE folder. No "Shotgun Surgery" across 5 layers.
3. Shared Kernel: Only truly generic code (Logging, Auth Middleware, Database Connection) goes into shared/.

1. The "Modular Monolith" Mandate

• Microservices Ban: Do NOT start with microservices. Start with a Modular Monolith.
• Modulith Rules:
  • Modules must be isolated (like internal microservices).
  • Modules communicate via Events (Sub-Process or Message Bus), NEVER by importing another module's code directly.
  • The Outbox Pattern (Guaranteed Delivery):
    • Problem: If DB commit succeeds but Event Bus fails, the system is inconsistent.
    • Mandate: Write events to an outbox table in the SAME transaction as the data change.
    • Relay: A background worker pushes outbox entries to the Message Bus (RabbitMQ/Kafka).
  • Data Sovereignty: Module A cannot query Module B's tables. It must ask Module B via API/Event.

2. The "Zero Trust" Security Protocol

Detailed protocols: See security-protocols.md

Quick Rules:

1. Strict Serialization: NEVER return raw DB entities → Use ResponseDTO
2. Validation at Gate: Schema validation (Zod/Pydantic) BEFORE logic
3. Token Sovereignty: PASETO v4 > JWT (Ed25519 if JWT forced) </architectural_protocols>

<reliability_contracts>

🏗️ Reliability & Performance Contracts

3. The "Sub-100ms" Performance Mandate

• The Latency Budget: P50 < 100ms. P99 < 500ms.
• UUIDv7 (The Time-Lord Rule):
  • Ban: Never use UUIDv4 (Random) for Primary Keys. It fragments B-Tree indexes.
  • Mandate: Use UUIDv7 (Time-ordered). It enables clustered index locality (fast inserts) like integers, with the uniqueness of UUIDs.
• N+1 Assassin:
  • Check: Always inspect ORM queries. Loops triggering DB calls are a "Level 0" error.
  • Fix: Use DataLoader pattern or explicit JOIN loading.

4. API Reliability Contracts

• RFC 7807 (Problem Details):
  • Ban: returning { "error": "Something went wrong" }.
  • Mandate: Return standard Problem JSON:

    {
      "type": "https://api.myapp.com/errors/insufficient-funds",
      "title": "Insufficient Funds",
      "status": 403,
      "detail": "Current balance is 10.00, required is 15.00",
      "instance": "/transactions/12345"
    }
    

• Idempotency Keys:
  • Rule: All critical POST/PATCH (Money, State Change) must accept an Idempotency-Key header.
  • Logic: If key exists in Cache (24h TTL), return stored response without re-executing logic. </reliability_contracts>

<database_integrity>

🗄️ Database Integrity & Design

5. Database Integrity & Design

• Hard Constraints: Application-level checks are "Suggestions". Database Constraints (Foreign Keys, Unique Indexes, Check Constraints) are "Laws".
• Cursor Pagination:
  • Ban: OFFSET / LIMIT on large tables (O(N) performance degradation).
  • Mandate: Cursor-based pagination (WHERE created_at < cursor LIMIT 20).
• Migration Discipline:
  • Never alter a column in a way that locks the table for >1s.
  • Use "Expand and Contract" pattern for breaking changes.
• Concurrency Control:
  • Problem: Two users update the same record. The last one wipes the first.
  • Mandate: Use Optimistic Locking. Add a version (int) column.
  • Logic: Update WHERE id = X AND version = Y. If 0 rows affected, throw StaleObjectException.

6. AI & Vector Readiness

• Semantic Storage: Backend must be ready to store embeddings (Vector Types).
• Guardrails: Output from LLMs must be sanitized and structure-checked on the server side before returning to frontend. </database_integrity>

<domain_overview>

💡 BRAINSTORMING: DESIGN BEFORE CODE

Philosophy: Understanding comes before implementation. A well-designed solution is half-implemented. Never code without a clear design.

HALLUCINATION FIREWALL MANDATE (CRITICAL): Never propose software components or libraries without verification. AI-generated designs frequently fail by hallucinating non-existent packages or misinterpreting their capabilities. Every recommended 3rd-party library MUST be validated using npm info or equivalent before the plan is finalized. Furthermore, you MUST provide at least one 'Counter-Architecture' (Steel-man argument) that challenges your primary recommendation to prevent homogenized or biased designs. Help turn ideas into fully formed designs and specs through natural collaborative dialogue. Process:

1. Understand the current project context
2. Ask questions one at a time to refine the idea
3. Present the design in small sections (200-300 words)
4. Check after each section whether it looks right

📋 WHEN TO USE

MUST use before:

• Creating new features
• Building new components
• Adding significant functionality
• Modifying core behavior
• Any task that takes more than 30 minutes Skip only for:
• Simple bug fixes with obvious solutions
• Documentation updates
• Trivial configuration changes </domain_overview> <process_workflow>

🔄 THE PROCESS

Phase 1: Understanding the Idea

First, check current project state:

• Review relevant files and docs
• Check recent commits
• Understand existing patterns Then ask questions one at a time:
• MANDATORY: Use the AskUserQuestion tool for ALL questions.
• Prefer multiple choice options within the tool whenever possible.
• Open-ended questions should also use AskUserQuestion (users can use the 'Other' option).
• Only one question per tool call.
• If topic needs more exploration, break into multiple sequential tool calls. Focus on understanding:
• Purpose: What problem does this solve?
• Constraints: What limitations exist?
• Success criteria: How do we know it works?
• Edge cases: What could go wrong?

Phase 2: Exploring Approaches

Always propose 2-3 different approaches with trade-offs:

I see three possible approaches:
**Option A: [Name]**
- Pros: Simple, fast to implement
- Cons: May not scale, harder to test
- Best for: Quick prototypes
**Option B: [Name]**
- Pros: Scalable, well-tested pattern
- Cons: More complex, longer implementation
- Best for: Production systems
**Option C: [Name]**
- Pros: Flexible, future-proof
- Cons: Over-engineered for current needs
- Best for: When requirements are uncertain
**My recommendation:** Option B because [reasoning]
Which approach resonates with your goals?

Lead with your recommended option and explain why.

Phase 3: Presenting the Design

Once you understand what you're building, present the design:

1. Break it into sections of 200-300 words
2. Ask after each section: "Does this look right so far?"
3. Be ready to go back and clarify if something doesn't make sense Cover these areas:

• Architecture: How components fit together
• Components: What pieces we need to build
• Data flow: How information moves through the system
• Error handling: What happens when things fail
• Testing: How we verify it works

Phase 4: Documentation

After design is validated:

1. Write the design to docs/plans/YYYY-MM-DD-<topic>-design.md
2. Commit the design document to git
3. Ask: "Ready to set up for implementation?" </process_workflow> <methodology_protocols>

🎤 QUESTION TECHNIQUES

Multiple Choice (MANDATORY TOOL USE)

Always use the AskUserQuestion tool for structured feedback:

{
  "questions": [
    {
      "header": "Auth Method",
      "question": "How should users authenticate?",
      "options": [
        {"label": "JWT Tokens", "description": "Stateless, scalable"},
        {"label": "Server Sessions", "description": "Simple, secure"},
        {"label": "OAuth Only", "description": "Delegate to providers"}
      ],
      "multiSelect": false
    }
  ]
}

Open-Ended (Using Tool)

Even for open-ended questions, use the tool. The CLI will provide an "Other" option for custom text input. "What's the most important user story for this feature?"

Clarifying

"You mentioned 'fast' - what response time would feel fast enough?"

🚫 ANTI-PATTERNS TO AVOID

📝 DESIGN DOCUMENT TEMPLATE

# [Feature Name] Design
**Date:** YYYY-MM-DD
**Author:** Grandmaster (with user collaboration)
**Status:** Draft | Approved | Implemented
## Problem Statement
What problem are we solving? Why does it matter?
## Goals
- Primary goal
- Secondary goals
- Non-goals (explicitly out of scope)
## Approach
### Architecture
How components fit together.
### Components
1. **Component A**
   - Purpose
   - Interface
   - Dependencies
2. **Component B**
   - Purpose
   - Interface
   - Dependencies
### Data Flow
1. User action triggers X
2. X calls Y with Z
3. Y returns result
4. Result displayed to user
### Error Handling
| Error | Handling | User Message |
|-------|----------|--------------|
| Network failure | Retry 3x | "Connection lost, retrying..." |
| Invalid input | Reject | "Please check your input" |
## Testing Strategy
- Unit tests for each component
- Integration test for happy path
- Edge case tests for error handling
## Open Questions
- [ ] Question 1
- [ ] Question 2
## Decision Log
| Date | Decision | Rationale |
|------|----------|-----------|
| YYYY-MM-DD | Chose Option B | Better scalability |

</design_artifacts> <integration_protocols>

🔗 INTEGRATION WITH MAESTRO

Triggering Brainstorming

User can invoke explicitly:

/maestro design [feature description]

Or system detects complex task and suggests:

This looks like a significant feature. Would you like to 
brainstorm the design first, or proceed directly?

After Brainstorming

1. If continuing to implementation:
   • Use @planning-mastery to create detailed plan
   • Use @git-worktrees to create isolated workspace
2. If pausing:
   • Design document is saved
   • Can resume later with /maestro plan [design-doc]

🔗 RALPH WIGGUM INTEGRATION

When Ralph Wiggum is active with "Feature Mode":

1. Before first iteration: Run brainstorming phase
2. Design document: Required before implementation begins
3. Scope lock: Don't add features not in design
4. Design changes: Require explicit approval </integration_protocols> <audit_and_reference>

📋 KEY PRINCIPLES

🔗 RELATED SKILLS

• @planning-mastery - Create implementation plan from design
• @git-worktrees - Set up isolated workspace
• @tdd-mastery - Implement with tests first
• @clean-code - Quality standards for implementation </audit_and_reference>

<domain_overview>

🌐 BROWSER EXTENSION: THE 2026 MASTERCLASS

Philosophy: Extensions are ephemeral, restricted, yet powerful. Persistence is an Art. Security is a Mandate. Design Constraint: For UI/UX, Aesthetics, and Layout, YOU MUST REFER TO THE frontend-design SKILL. PERSISTENCE PARADOX GUARD (CRITICAL): Never rely on global variables or in-memory state in background scripts. AI-generated code frequently fails by assuming Manifest V3 service workers are persistent. They are NOT; they terminate after 30 seconds of inactivity. You MUST backup every piece of state to chrome.storage or IndexedDB immediately upon change. This skill aims to eliminate "volatile-state" bugs typical of generic AI implementations. If data is not in durable storage, it does not exist. </domain_overview> <manifest_architecture>

🏗️ PROTOCOL 1: THE MANIFEST V3 CONSTITUTION

All extensions must be built on Manifest v3. No exceptions.

1. Manifest Blueprint:
   • Service Workers: No persistent background pages. Use "background": { "service_worker": "background.js" }.
   • No Remote Code: All scripts must be local. unsafe-eval is forbidden.
   • Permissions: Principle of Least Privilege. Use optional_permissions where possible.
   • Action UI: Prefer action over browser_action or page_action.
2. Side Panel Supremacy:
   • Requirement: Use chrome.sidePanel for persistent, non-intrusive experiences.
   • API: chrome.sidePanel.setOptions({ path: 'sidepanel.html', enabled: true }). </manifest_architecture> <persistence_engine>

⚡ PROTOCOL 2: THE PERSISTENCE ENGINE (ANTI-TERMINATION)

Service Workers sleep. You must keep the logic alive.

1. The Alarm Pulse:
   • Use chrome.alarms to wake up the Service Worker every 1-5 minutes for background sync.
2. The Offscreen Document (When needed):
   • Use the offscreen API for tasks like DOM parsing, heavy calculations, or keeping the SW alive via periodic messaging.
3. State Management Protocol:
   • NEVER rely on global variables.
   • Mandatory: Use chrome.storage.session for transient session-only secrets.
   • Mandatory: Use IndexedDB or chrome.storage.local for large datasets and persistent user data. </persistence_engine> <security_fortress>

🔐 PROTOCOL 3: THE SECURITY FORTRESS

1. Context Bridge Safety:
   • Content Scripts are "Hostile Territory". Always sanitize data passed to the Service Worker via chrome.runtime.sendMessage.
2. Declarative Net Request:
   • Use declarativeNetRequest for blocking/modifying headers. Only use webRequest as a fallback for Firefox if dynamic rules are critical. </security_fortress> <design_integration>

🎨 PROTOCOL 4: DESIGN & UI/UX (INTEGRATED)

Direct Instruction: You are an extension developer, not a designer. You must outsource the "Soul" of the UI.

1. UI Execution:
   • Popup/SidePanel: Follow the 8-Point Grid and Glassmorphism rules from frontend-design.
   • Component Atomization: Use Atomic Design 2.0 principles.
   • Friction: Ensure the popup interaction is < 400ms (Doherty Threshold). </design_integration> <audit_and_reference>

🛠️ PROTOCOL 5: SCRIPT ENFORCEMENT (THE SENTINEL)

Every extension build MUST pass the high-tier audit suite.

1. manifest-auditor.js:
   • Rule: MV3 compliance and CSP safety. No broad permissions.
2. persistence-check.js:
   • Rule: Service Worker "Heartbeat" verification and State integrity.
3. asset-master.js:
   • Rule: Icon dimensional audit and asset optimization.

📂 COGNITIVE AUDIT CYCLE

1. Run node scripts/js/manifest-auditor.js -> Clean?
2. Run node scripts/js/persistence-check.js -> Heartbeat detected?
3. Run node scripts/js/asset-master.js -> Assets optimized?
4. MANDATORY: Run playwright test -> All paths pass?
5. Is it Manifest v3 compliant?
6. Does the Service Worker handle termination gracefully (State stored)?
7. Are permissions minimized?
8. Is the UI justified by a "Narrative-First" screenplay from frontend-design?

Link: frontend-design </audit_and_reference>

<domain_overview>

🛡️ CLEAN CODE: THE FOUNDATION

Philosophy: This skill is the FOUNDATION - it applies to ALL other skills. Every piece of code must pass these gates. ALGORITHMIC ELEGANCE MANDATE (CRITICAL): Never prioritize "clever" code over readable, intent-revealing engineering. AI-generated code often fails by introducing unnecessary abstractions or using vague naming conventions that obscure logic. You MUST use intent-revealing names for every variable and function. Any implementation that increases cognitive complexity without a proportional gain in performance or scalability must be rejected. Avoid "Hype-Driven Development"—proven patterns trump trending but unstable frameworks. </domain_overview> <iron_laws>

🚨 IRON LAWS

1. NO HALLUCINATED PACKAGES - Verify before import
2. NO LAZY PLACEHOLDERS - Code must be runnable
3. NO SECURITY SHORTCUTS - Production-ready defaults
4. NO OVER-ENGINEERING - Simplest solution first

</iron_laws> <security_protocols>

📦 PROTOCOL 1: SUPPLY CHAIN SECURITY

LLMs hallucinate packages that sound real but don't exist.

1. Verify before import - npm search or pip show for unfamiliar packages
2. Prefer battle-tested - lodash, date-fns, zod over obscure alternatives
3. Check npm audit / pip-audit before adding new dependencies
4. Pin versions in production - no ^ or ~ for critical deps 2025 AI Package Risks:

• Never import AI "wrapper" libraries without verification
• LLM SDKs: Use official only (openai, anthropic, google-generativeai)
• Vector DBs: Stick to established (pinecone, weaviate, chromadb)

🔐 PROTOCOL 2: SECURITY-FIRST DEFAULTS

Frontend Security:

• Rate limiting on ALL public endpoints
• Input validation at the gate (Zod/Pydantic)
• Output sanitization for AI-generated content
• PASETO > JWT for new projects </security_protocols> <modularity_and_placeholder_rules>

🏗️ PROTOCOL 3: NO LAZY PLACEHOLDERS

Forbidden Patterns:

// ❌ BANNED
// TODO: Implement this
// ... logic goes here
function placeholder() { }
throw new Error('Not implemented');

Required:

• Every function must be runnable
• If too complex, break into smaller complete functions
• "Hurry" is not an excuse - write minimal viable implementation

📐 PROTOCOL 4: MODULARITY & STRUCTURE

The 50/300 Rule:

• Functions > 50 lines → Break down
• Files > 300 lines → Split into modules SOLID Principles: | Principle | Quick Check | |-----------|-------------| | Single Responsibility | Does this do ONE thing? | | Open/Closed | Can I extend without modifying? | | Liskov Substitution | Can subtypes replace parent? | | Interface Segregation | Are interfaces minimal? | | Dependency Inversion | Do I depend on abstractions? | </modularity_and_placeholder_rules> <complexity_and_dependencies>

🎯 PROTOCOL 5: COMPLEXITY CAP

Native First:

// ❌ Don't install is-odd
npm install is-odd
// ✅ Use native
const isOdd = n => n % 2 !== 0;

Anti-Patterns:

• AbstractFactoryBuilderManager for simple functions
• 10 layers of abstraction for CRUD
• "Future-proofing" for requirements that don't exist YAGNI: You Aren't Gonna Need It. Build for today's requirements.

🔄 PROTOCOL 6: DEPENDENCY HYGIENE

Freshness Check:

npm outdated      # Check for updates
npm audit         # Check for vulnerabilities

The CVE Brake:

• "Latest" is not always "Safest"
• If latest has Critical CVE → Rollback to last secure version
• Security > New Features 2025 Recommended: | Category | Recommended | |----------|-------------| | Validation | zod, valibot | | HTTP | ky, ofetch | | State | zustand, jotai | | ORM | drizzle, prisma | | Auth | lucia, better-auth | </complexity_and_dependencies> <ai_era_protocols>

🤖 PROTOCOL 7: AI-ERA CONSIDERATIONS

When Building AI Features:

1. Validate AI outputs - Never trust raw LLM responses
2. Rate limit AI calls - Prevent cost explosions
3. Sanitize before display - AI can generate malicious content
4. Log AI interactions - For debugging and compliance When AI is Writing Code:
5. Verify imports exist - AI hallucinates packages
6. Check types are correct - AI guesses at APIs
7. Test edge cases - AI misses boundary conditions
8. Review security - AI takes shortcuts </ai_era_protocols> <audit_and_reference>

✅ QUICK AUDIT CHECKLIST

Before committing ANY code:

• No hallucinated imports (verified packages exist)
• No security shortcuts (CORS, eval, hardcoded secrets)
• No lazy placeholders (// TODO, empty functions)
• Functions < 50 lines, files < 300 lines
• Dependencies audited (npm audit clean)
• Types are strict (no any)

🔗 CROSS-SKILL INTEGRATION

<domain_overview>

🐛 DEBUG MASTERY: SYSTEMATIC DEBUGGING

Philosophy: Random fixes waste time and create new bugs. Quick patches mask underlying issues. ALWAYS find root cause before attempting fixes. FORENSIC ANALYSIS MANDATE (CRITICAL): Never apply a fix without a confirmed root cause. AI-generated fixes often address symptoms rather than underlying architectural logic. You MUST perform a 'Forensic Investigation' that identifies the specific assumption or boundary condition that failed. For every fix, you must provide a brief analysis note explaining WHY the original architecture allowed the bug to exist, transforming every error into a systemic engineering lesson.

🚨 THE IRON LAW

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST

If you haven't completed Phase 1, you cannot propose fixes. Violating the letter of this process is violating the spirit of debugging.

📋 WHEN TO USE

Use for ANY technical issue:

• Test failures
• Bugs in production
• Unexpected behavior
• Performance problems
• Build failures
• Integration issues Use ESPECIALLY when:
• Under time pressure (emergencies make guessing tempting)
• "Just one quick fix" seems obvious
• You've already tried multiple fixes
• Previous fix didn't work
• You don't fully understand the issue Don't skip when:
• Issue seems simple (simple bugs have root causes too)
• You're in a hurry (systematic is faster than thrashing)
• Manager wants it fixed NOW (systematic is faster than guess-and-check) </domain_overview> <debugging_phases>

🔄 THE FOUR PHASES

You MUST complete each phase before proceeding to the next.

Phase 1: Root Cause Investigation

BEFORE attempting ANY fix:

1. Read Error Messages Carefully
   • Don't skip past errors or warnings
   • They often contain the exact solution
   • Read stack traces completely
   • Note line numbers, file paths, error codes
2. Reproduce Consistently
   • Can you trigger it reliably?
   • What are the exact steps?
   • Does it happen every time?
   • If not reproducible → gather more data, don't guess
3. Check Recent Changes
   • What changed that could cause this?
   • Git diff, recent commits
   • New dependencies, config changes
   • Environmental differences
4. Gather Evidence in Multi-Component Systems WHEN system has multiple components (CI → build → signing, API → service → database): BEFORE proposing fixes, add diagnostic instrumentation:

   For EACH component boundary:
     - Log what data enters component
     - Log what data exits component
     - Verify environment/config propagation
     - Check state at each layer
   Run once to gather evidence showing WHERE it breaks
   THEN analyze evidence to identify failing component
   THEN investigate that specific component
   

5. Trace Data Flow WHEN error is deep in call stack: See @root-cause-tracing.md for the complete backward tracing technique. Quick version:
   • Where does bad value originate?
   • What called this with bad value?
   • Keep tracing up until you find the source
   • Fix at source, not at symptom

Phase 2: Pattern Analysis

Find the pattern before fixing:

1. Find Working Examples
   • Locate similar working code in same codebase
   • What works that's similar to what's broken?
2. Compare Against References
   • If implementing pattern, read reference implementation COMPLETELY
   • Don't skim - read every line
   • Understand the pattern fully before applying
3. Identify Differences
   • What's different between working and broken?
   • List every difference, however small
   • Don't assume "that can't matter"
4. Understand Dependencies
   • What other components does this need?
   • What settings, config, environment?
   • What assumptions does it make?

Phase 3: Hypothesis and Testing

Scientific method:

1. Form Single Hypothesis
   • State clearly: "I think X is the root cause because Y"
   • Write it down
   • Be specific, not vague
2. Test Minimally
   • Make the SMALLEST possible change to test hypothesis
   • One variable at a time
   • Don't fix multiple things at once
3. Verify Before Continuing
   • Did it work? Yes → Phase 4
   • Didn't work? Form NEW hypothesis
   • DON'T add more fixes on top
4. When You Don't Know
   • Say "I don't understand X"
   • Don't pretend to know
   • Ask for help
   • Research more

Phase 4: Implementation

Fix the root cause, not the symptom:

1. Create Failing Test Case
   • Simplest possible reproduction
   • Automated test if possible
   • One-off test script if no framework
   • MUST have before fixing
   • Use the @tdd-mastery skill for writing proper failing tests
2. Implement Single Fix
   • Address the root cause identified
   • ONE change at a time
   • No "while I'm here" improvements
   • No bundled refactoring
3. Verify Fix
   • Test passes now?
   • No other tests broken?
   • Issue actually resolved?
4. If Fix Doesn't Work
   • STOP
   • Count: How many fixes have you tried?
   • If < 3: Return to Phase 1, re-analyze with new information
   • If ≥ 3: STOP and question the architecture (step 5 below)
   • DON'T attempt Fix #4 without architectural discussion
5. If 3+ Fixes Failed: Question Architecture Pattern indicating architectural problem:
   • Each fix reveals new shared state/coupling/problem in different place
   • Fixes require "massive refactoring" to implement
   • Each fix creates new symptoms elsewhere STOP and question fundamentals:
   • Is this pattern fundamentally sound?
   • Are we "sticking with it through sheer inertia"?
   • Should we refactor architecture vs. continue fixing symptoms? Discuss with user before attempting more fixes This is NOT a failed hypothesis - this is a wrong architecture. </debugging_phases> <red_flags_and_rationalizations>

🚨 RED FLAGS - STOP AND FOLLOW PROCESS

If you catch yourself thinking:

• "Quick fix for now, investigate later"
• "Just try changing X and see if it works"
• "Add multiple changes, run tests"
• "Skip the test, I'll manually verify"
• "It's probably X, let me fix that"
• "I don't fully understand but this might work"
• "Pattern says X but I'll adapt it differently"
• "Here are the main problems: [lists fixes without investigation]"
• Proposing solutions before tracing data flow
• "One more fix attempt" (when already tried 2+)
• Each fix reveals new problem in different place ALL of these mean: STOP. Return to Phase 1. If 3+ fixes failed: Question the architecture (see Phase 4.5)

🚫 COMMON RATIONALIZATIONS

📊 QUICK REFERENCE

🛠️ SUPPORTING TECHNIQUES

These techniques are part of systematic debugging:

• @root-cause-tracing.md - Trace bugs backward through call stack to find original trigger
• @defense-in-depth.md - Add validation at multiple layers after finding root cause

🛰️ OBSERVABILITY TOOLING

Precision Logging (JSON-First)

Mandatory Fields: timestamp, level, traceId, component, message, context Log Levels:

• ERROR: System failure, data loss, crash. Immediate audit required.
• WARN: Recoverable anomaly (retry, fallback triggered).
• INFO: Significant state change (phase transition, tool started).
• DEBUG: Detailed execution path, raw payloads, environment.

Distributed Tracing

1. Propagation: Every request/action carries TraceID
2. Span Definition: Wrap tool calls and complex logic to measure latency

Domain-Specific Troubleshooting

Frontend:

• Time-Travel: Redux DevTools, state snapshots
• Visual Regression: ux-audit.js for layout shifts Backend:
• eBPF Observability: Kernel-level IO/Network tracing
• Transaction Audits: ACID compliance verification Extensions (MV3):
• Service Worker: Verify chrome.alarms pulses
• Context Bridge: Check "Disconnected Port" errors

📈 REAL-WORLD IMPACT

From debugging sessions:

• Systematic approach: 15-30 minutes to fix
• Random fixes approach: 2-3 hours of thrashing
• First-time fix rate: 95% vs 40%
• New bugs introduced: Near zero vs common

🔗 RELATED SKILLS

• @tdd-mastery - For creating failing test case (Phase 4, Step 1)
• @verification-mastery - Verify fix worked before claiming success
• @clean-code - Prevent bugs through good practices </observability_and_references>

<domain_overview>

Frontend Design System

Philosophy: Minimize cognitive load and make interactions intuitive. Every design decision should respect human psychology, behavioral patterns, and cognitive limitations. The designer bears complexity so the user experiences simplicity. Core Principle: Good design is invisible - users should accomplish their goals without noticing the design itself. Design should feel effortless and natural, aligning with how humans naturally think and behave.

⚠️ Core Protocols & Standards

ANTI-AI AESTHETIC MANDATE (CRITICAL): Never use generic aesthetics that give the impression of being AI-generated. This includes overused font families (Inter, Roboto, Arial, system fonts), cliché color schemes (especially purple gradients on white backgrounds), predictable layouts, and repetitive component patterns. ABSOLUTELY FORBIDDEN: The "Cyberpunk" aesthetic is strictly prohibited. Do NOT use neon glows, matrix rain, glitch effects, or "high-tech" dark modes unless explicitly requested for a specific context. This cliché is the hallmark of lazy AI generation. Specifically avoid template-driven designs that lack context-specific character. This skill aims to create distinctive, original, and production-level frontends. Realize functional, high-fidelity code by paying extraordinary attention to aesthetic details and creative decisions.

CRITICAL PROTOCOL: The detailed rules are stored in separate reference files. You MUST use the Read tool to load these files into your context BEFORE starting any design work. Do not assume you know the contents.

• frontend_reference.md: Contains Technical Standards, Aesthetic Signatures, and Creative Protocols.
• animation_reference.md: Contains 2025 Motion Standards, Physics-based animation rules, and Micro-interactions.
• css_art_reference.md: FOR VISUAL OBJECTS. Use this when asked to "draw" or "create" complex items (Swords, Logos, Icons) using code. Defines Geometric Composition & LCH Materials.
• security-protocols.md: Contains critical Frontend Security rules.

🎬 Core Animation Principles

Motion Mandate: Animation must be Physics-Based (Springs), Continuous (No Teleportation), and Meaningful (Storytelling).

• Continuity: State changes must morph, not cut (View Transitions).
• Weight: Objects must feel like they have mass (Use Spring Animations).
• Focus: Animation guides attention; it does not distract.
• Narrative: Every motion tells a story about where an element came from and where it is going. (See animation_reference.md for the full 12-Principle Framework)

🔗 Related & Required Skills

When executing Frontend tasks, you MUST integrate these complementary skills to ensure architectural integrity:

🛠️ Automation Scripts

Use the following script to audit your implementation:

• scripts/js/ux-audit.js: Run this to perform a heuristic analysis of the UI for consistency, accessibility (contrast/spacing), and compliance with the design tokens.
  • Usage: node scripts/js/ux-audit.js </domain_overview>

<domain_overview>

🌳 GIT WORKTREES: ISOLATED WORKSPACES

Philosophy: Isolation prevents contamination. Work on features without affecting the main workspace. Systematic directory selection + safety verification = reliable isolation. ISOLATION INTEGRITY MANDATE (CRITICAL): Never create worktrees in directories that are not explicitly ignored by Git. AI-generated workflows often fail by polluting the primary repository with tracked worktree data. You MUST verify that the destination directory is within .gitignore before execution. Furthermore, you MUST ensure a 'Clean Baseline' by running tests before starting any feature work in a new worktree to avoid cross-contamination of artifacts. </domain_overview>

<directory_selection>

🎯 OVERVIEW

Git worktrees create isolated workspaces sharing the same repository, allowing work on multiple branches simultaneously without switching. Benefits:

• Work on feature branch without stashing changes
• Test in isolation without affecting main workspace
• Run long processes without blocking other work
• Easy cleanup when feature is complete

📋 WHEN TO USE

Use before:

• Starting new feature development
• Implementing plans from @planning-mastery
• Making experimental changes
• Working on multiple features in parallel Skip for:
• Quick bug fixes on current branch
• Documentation updates
• Configuration changes

📁 DIRECTORY SELECTION PROCESS

Follow this priority order:

1. Check Existing Directories

Unix/macOS:

ls -d .worktrees 2>/dev/null     # Preferred (hidden)
ls -d worktrees 2>/dev/null      # Alternative

Windows (PowerShell):

if (Test-Path ".worktrees") { ".worktrees" }
elseif (Test-Path "worktrees") { "worktrees" }

If found: Use that directory. If both exist, .worktrees wins.

2. Check CLAUDE.md

grep -i "worktree.*director" CLAUDE.md 2>/dev/null

If preference specified: Use it without asking.

3. Ask User

If no directory exists and no CLAUDE.md preference:

No worktree directory found. Where should I create worktrees?
1. .worktrees/ (project-local, hidden)
2. %USERPROFILE%\.config\maestro\worktrees\<project>\ (global location)
Which would you prefer?

</directory_selection> <safety_verification>

🔒 SAFETY VERIFICATION

For Project-Local Directories

MUST verify directory is ignored before creating worktree: Unix/macOS:

git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null

Windows (PowerShell):

git check-ignore -q .worktrees 2>$null
if ($LASTEXITCODE -ne 0) {
    git check-ignore -q worktrees 2>$null
}

If NOT ignored:

1. Add appropriate line to .gitignore
2. Commit the change
3. Proceed with worktree creation Why critical: Prevents accidentally committing worktree contents to repository.

For Global Directory

No .gitignore verification needed - outside project entirely. </safety_verification> <creation_and_setup>

🔨 CREATION STEPS

1. Detect Project Name

Unix/macOS:

project=$(basename "$(git rev-parse --show-toplevel)")

Windows (PowerShell):

$project = Split-Path -Leaf (git rev-parse --show-toplevel)

2. Create Worktree

Unix/macOS:

# Project-local
path=".worktrees/$BRANCH_NAME"
git worktree add "$path" -b "$BRANCH_NAME"
cd "$path"
# Or global
path="$HOME/.config/maestro/worktrees/$project/$BRANCH_NAME"
mkdir -p "$(dirname "$path")"
git worktree add "$path" -b "$BRANCH_NAME"
cd "$path"

Windows (PowerShell):

# Project-local
$path = ".worktrees\$BRANCH_NAME"
git worktree add $path -b $BRANCH_NAME
Set-Location $path
# Or global
$path = "$env:USERPROFILE\.config\maestro\worktrees\$project\$BRANCH_NAME"
New-Item -ItemType Directory -Force -Path (Split-Path $path)
git worktree add $path -b $BRANCH_NAME
Set-Location $path

3. Run Project Setup

Auto-detect and run appropriate setup: Cross-platform:

# Node.js
if [ -f package.json ]; then npm install; fi
# Python
if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
if [ -f pyproject.toml ]; then poetry install; fi
# Rust
if [ -f Cargo.toml ]; then cargo build; fi
# Go
if [ -f go.mod ]; then go mod download; fi

Windows (PowerShell):

# Node.js
if (Test-Path "package.json") { npm install }

# Python
if (Test-Path "requirements.txt") { pip install -r requirements.txt }
if (Test-Path "pyproject.toml") { poetry install }

# Rust
if (Test-Path "Cargo.toml") { cargo build }

# Go
if (Test-Path "go.mod") { go mod download }

4. Verify Clean Baseline

Run tests to ensure worktree starts clean:

# Use project-appropriate command
npm test
pytest
cargo test
go test ./...

If tests fail: Report failures, ask whether to proceed or investigate. If tests pass: Report ready.

5. Report Location

Worktree ready at <full-path>
Tests passing (<N> tests, 0 failures)
Ready to implement <feature-name>

</creation_and_setup> <audit_and_reference>

📊 QUICK REFERENCE

🧹 CLEANUP

When feature work is complete: List worktrees:

git worktree list

Remove worktree:

git worktree remove .worktrees/feature-name
# or force if uncommitted changes
git worktree remove --force .worktrees/feature-name

Prune stale entries:

git worktree prune

🚫 COMMON MISTAKES

Skipping ignore verification

• Problem: Worktree contents get tracked, pollute git status
  • Fix: Always use git check-ignore before creating project-local worktree

Assuming directory location

• Problem: Creates inconsistency, violates project conventions
  • Fix: Follow priority: existing > CLAUDE.md > ask

Proceeding with failing tests

• Problem: Can't distinguish new bugs from pre-existing issues
  • Fix: Report failures, get explicit permission to proceed

Hardcoding setup commands

• Problem: Breaks on projects using different tools
  • Fix: Auto-detect from project files (package.json, etc.)

Forgetting to cleanup

• Problem: Disk space consumed, stale branches accumulate
  • Fix: Remove worktree when feature is merged

📝 EXAMPLE WORKFLOW

You: I'm using the git-worktrees skill to set up an isolated workspace.
[Check .worktrees/ - exists]
[Verify ignored - git check-ignore confirms .worktrees/ is ignored]
[Create worktree: git worktree add .worktrees/auth -b feature/auth]
[Run npm install]
[Run npm test - 47 passing]
Worktree ready at C:\Users\Dev\myproject\.worktrees\auth
Tests passing (47 tests, 0 failures)
Ready to implement auth feature

🚨 RED FLAGS

Never:

• Create worktree without verifying it's ignored (project-local)
• Skip baseline test verification
• Proceed with failing tests without asking
• Assume directory location when ambiguous
• Skip CLAUDE.md check Always:
• Follow directory priority: existing > CLAUDE.md > ask
• Verify directory is ignored for project-local
• Auto-detect and run project setup
• Verify clean test baseline
• Report full path when done

🔗 INTEGRATION

Called by:

• @brainstorming - After design approved, before implementation
• @planning-mastery - When executing plan

Pairs with:

• @planning-mastery - Work happens in this worktree
• @tdd-mastery - Implementation methodology
• @verification-mastery - Complete development after all tasks

🔗 RALPH WIGGUM INTEGRATION

When Ralph Wiggum is active:

1. Before first iteration: Create worktree for isolated work
2. During iterations: All work happens in worktree
3. After completion: Merge or create PR from worktree
4. Cleanup: Remove worktree after merge

🔗 RELATED SKILLS

• @brainstorming - Design before worktree creation
• @planning-mastery - Plan to execute in worktree
• @verification-mastery - Verify before finishing branch </audit_and_reference>

<domain_overview>

⚡ OPTIMIZATION MASTERY: THE VELOCITY CORE

Philosophy: Efficiency is the highest form of quality. Minimal overhead, maximum impact. Performance-First is the only law. INTERACTION HYGIENE MANDATE (CRITICAL): Never prioritize synthetic benchmarks over real-world interaction smoothness. AI-generated code often misses Interaction to Next Paint (INP) bottlenecks caused by synchronous main-thread blocking. You MUST use scheduler.yield() or requestAnimationFrame for any complex DOM or state updates triggered by user events. Any implementation that risks "Layout Thrashing" or exceeds the 200ms INP threshold must be rejected. </domain_overview> <frontend_velocity>

🎨 PROTOCOL 1: FRONTEND PRECISION (INP & BUNDLE)

Aesthetics must be fast. Refer to frontend-design for visuals, but enforce these for speed.

1. The INP Threshold:
   • Core Metric: Interaction to Next Paint (INP) MUST be < 200ms.
   • Action: Yield to main thread for heavy logic. Use scheduler.yield() or requestIdleCallback.
2. Hydration Strategies:
   • Mandatory: Use Partial Hydration or Resumability (e.g. Qwik/Astro patterns).
   • Forbidden: Massive "Full Hydration" of static content.
3. Asset Governance:
   • Images: Modern formats (AVIF/WebP) with srcset are mandatory.
   • Fonts: Only wght variable fonts; subsetted. </frontend_velocity> <backend_velocity>

🏗️ PROTOCOL 2: BACKEND VELOCITY (QUERY & DATA)

The backend must be a fortress of speed. Refer to backend-design for architecture.

1. Identifier Strategy:
   • Mandatory: Use UUIDv7 for all primary keys in high-insert tables.
   • Rationale: Time-sortable IDs prevent B-tree fragmentation and boost insert speed by ~30%.
2. Query Budget:
   • Max Latency: Sub-100ms for OLTP queries.
   • Action: Every index MUST be a "Covering Index" for critical read paths.
3. Edge compute:
   • Offload logic to Edge Functions (Vercel/Cloudflare) to reduce Time-to-First-Byte (TTFB). </backend_velocity> <ai_token_stewardship>

🤖 PROTOCOL 3: AI TOKEN STEWARDSHIP (RESOURCE OPS)

AIs are expensive/slow. Optimize the "thought" itself.

1. Context Window Management:
   • Action: Use "Context Folding" (summarizing history) to keep prompts under 4k tokens if possible.
2. Credit-Based Execution:
   • Assign a "Token Budget" to complex tool calling phases.
3. Caching:
   • Implement Semantic Caching for repetitive LLM queries. </ai_token_stewardship> <audit_and_reference>

📂 COGNITIVE AUDIT CYCLE

1. Is INP < 200ms?
2. Are primary keys UUIDv7?
3. Is hydration partial/resumable?
4. Is the token budget justified for this request? </audit_and_reference>

<domain_overview>

📋 RFC-Lite Planning Protocol

The 300-Line Limit: If your plan exceeds 300 lines, YOU HAVE FAILED. Rule: Code belongs in files, not plans. Do not write pseudo-code. Do not paste entire file contents. Focus: Define What (Files), How (Logic Strategy), and Success (Verification).

DEPENDENCY FORECASTING MANDATE (CRITICAL): Never propose a change without mapping its "Blast Radius". AI-generated plans frequently fail by ignoring downstream effects on coupled modules. Before defining file changes, you MUST explicitly identify which existing features or tests might break. If a change requires "Shotgun Surgery" (modifying more than 5 files for one feature), you MUST pause and propose an architectural abstraction instead. </domain_overview>

🎯 CORE PHILOSOPHY

Understanding comes before implementation. A well-designed solution is half-implemented. Never code without a clear design. <template_enforcement>

📝 MANDATORY TEMPLATE (Copy & Fill)

# [Task/Feature Name] - Implementation Plan
## 1. 🎯 Objective
[1-2 sentences strictly defining the goal.]
## 2. 🏗️ Tech Strategy
- **Pattern:** [e.g. Composition vs Inheritance]
- **State:** [e.g. Global Store vs Local Hook]
- **Constraints:** [e.g. "Must use LCH colors", "No external libs"]
## 3. 📂 File Changes
| Action | File Path | Brief Purpose |
|:-------|:----------|:--------------|
| [NEW]  | `src/components/MyComp.tsx` | Visual shell |
| [MOD]  | `src/App.tsx` | Routing integration |
## 4. 👣 Execution Sequence
1.  **Scaffold:** Create component files with types (No logic yet).
2.  **Logic:** Implement `useLogic.ts` hook with TDD.
3.  **Visuals:** Apply LCH gradients & Glassmorphism.
4.  **Connect:** Wire up to parent component.
## 5. ✅ Verification Standards
- [ ] **Visual:** Check against `frontend_reference.md` (no flat colors).
- [ ] **Interaction:** Verify `scale(0.97)` tap effect.
- [ ] **Console:** Zero errors during flow.

</template_enforcement> <strict_rules>

⛔ ZERO TOLERANCE RULES

1. NO CODE BLOCKS: Do not write function bodies in the plan.
2. NO EXPLANATIONS: Do not teach the user why React is good.
3. NO CONVERSATION: Do not talk to the user in the plan.
4. STAY HIGH LEVEL: "Implement Auth" is better than "Write function login() { ... }". </strict_rules> <audit_and_reference>

📂 COGNITIVE AUDIT CYCLE

1. Does the plan exceed 300 lines?
2. Are all breaking changes identified?
3. Is it RFC-Lite compliant?
4. Are verification steps actionable commands? </audit_and_reference>

<domain_overview>

🔄 RALPH WIGGUM: SURGICAL FIXER

Philosophy: "I'm helping!" — Rational: Fix the root, not the symptom. ROOT CAUSE SURGERY MANDATE (CRITICAL): Ralph is not a feature developer. He is a surgical specialist for existing logic failures. You MUST NOT propose fixes without completed Phase 1 (Forensic Root Cause). Every fix MUST address the architectural flaw that allowed the bug to manifest. Reject any patch that merely hides a symptom or adds "Maybe this works" logic. </domain_overview> <autonomous_debugging>

� AUTONOMOUS DEBUGGING (THE HARNESS)

Ralph uses the ralph-harness.js to ruthlessly pursue and eliminate error signals.

1. Forensic Investigation (Phase 1)

• Trace Back: Use @debug-mastery to find the bad value origin.
• Reproduce: Never fix what you haven't broken first with a test.
• State Check: Check .maestro/brain.jsonl for historical context on why this logic was built.

2. The Harness Loop

Run fix attempts through the persistent orchestrator:

node scripts/js/ralph-harness.js "npm test" --elite

• Max Iterations: 50 loops (Stop after 3 same errors).
• Circuit Breaker: If 3 failures occur, STOP and question the architecture. </autonomous_debugging> <code_improvement_loop>

✨ CODE INTEGRITY & REFLECTION

Ralph ensures all existing code meets the @clean-code standard.

1. Reflection Loop (Generate → Reflect → Refine)

Before finalizing any code optimization:

node scripts/js/reflection-loop.js

• Checklist: Edge cases, Input validation, Security, Completeness.
• Rule: If the reflection finds MAJOR issues, the code is rejected immediately.

2. Algorithmic Hygiene

• Naming: Every variable and function must reveal its intent.
• Modularity: No "Logic Slabs". Break code into testable, single-responsibility slices. </code_improvement_loop> <recovery_and_pivots>

🛡️ STRATEGIC RECOVERY

When basic fixes fail, Ralph triggers intelligent pivots.

• Strategy: Different Algorithm: Delete it and start with a fresh mental model.
• Strategy: Divide & Conquer: Break the complex fix into 3 smaller, testable steps.
• Strategy: Rollback: If regressions occur, return to the last stable git commit.
• Strategy: Ask Clarification: If 50 iterations fail, stop and ask the Architect for new context. </recovery_and_pivots> <audit_and_reference>

� COGNITIVE AUDIT CYCLE

1. Did I find the ROOT CAUSE or just a symptom?
2. Did I write a test that fails without my fix?
3. Did my fix introduce "Blast Radius" damage in unrelated files?
4. Did the Reflection Loop pass with zero major issues?

� INTEGRATION

• Surgical Tool: Called when tests fail or code is "smelly".
• Pairing: Works with @debug-mastery (Investigation) and @clean-code (Standard).
• No Feature Mode: Ralph is explicitly forbidden from designing new business requirements. </audit_and_reference>

<domain_overview>

🧪 TDD MASTERY: THE IRON LAW

Philosophy: If you didn't watch the test fail, you don't know if it tests the right thing. TDD is not optional—it's the foundation of trustworthy code. TEST-FIRST INTEGRITY MANDATE (CRITICAL): Never write production code before a test exists and has been seen failing. AI-generated code often attempts to write implementation and tests simultaneously or implementation first. You MUST strictly adhere to the Red-Green-Refactor cycle. Any code submitted without a preceding failing test or that generates tests after the implementation must be rejected as "Legacy Code on Arrival".

🚨 THE IRON LAW

NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST

Write code before the test? Delete it. Start over.

No exceptions:

• Don't keep it as "reference"
• Don't "adapt" it while writing tests
• Don't look at it
• Delete means delete

Implement fresh from tests. Period. </domain_overview> <core_workflow>

🔴 RED-GREEN-REFACTOR CYCLE

Phase 1: RED - Write Failing Test

Write one minimal test showing what should happen.

Good Example:

test('retries failed operations 3 times', async () => {
  let attempts = 0;
  const operation = () => {
    attempts++;
    if (attempts < 3) throw new Error('fail');
    return 'success';
  };

  const result = await retryOperation(operation);

  expect(result).toBe('success');
  expect(attempts).toBe(3);
});

Clear name, tests real behavior, one thing

Bad Example:

test('retry works', async () => {
  const mock = jest.fn()
    .mockRejectedValueOnce(new Error())
    .mockResolvedValueOnce('success');
  await retryOperation(mock);
  expect(mock).toHaveBeenCalledTimes(2);
});

Vague name, tests mock not code

Requirements:

• One behavior per test
• Clear, descriptive name
• Real code (mocks only if unavoidable)

Phase 2: VERIFY RED - Watch It Fail

MANDATORY. Never skip.

npm test path/to/test.test.ts
# or
pytest tests/path/test.py::test_name -v

Confirm:

• Test fails (not errors)
• Failure message is expected
• Fails because feature missing (not typos)

Test passes? You're testing existing behavior. Fix test.

Test errors? Fix error, re-run until it fails correctly.

Phase 3: GREEN - Minimal Code

Write simplest code to pass the test.

Good:

async function retryOperation<T>(fn: () => Promise<T>): Promise<T> {
  for (let i = 0; i < 3; i++) {
    try {
      return await fn();
    } catch (e) {
      if (i === 2) throw e;
    }
  }
  throw new Error('unreachable');
}

Just enough to pass

Bad:

async function retryOperation<T>(
  fn: () => Promise<T>,
  options?: {
    maxRetries?: number;
    backoff?: 'linear' | 'exponential';
    onRetry?: (attempt: number) => void;
  }
): Promise<T> {
  // YAGNI - You Aren't Gonna Need It
}

Over-engineered

Don't add features, refactor other code, or "improve" beyond the test.

Phase 4: VERIFY GREEN - Watch It Pass

MANDATORY.

npm test path/to/test.test.ts

Confirm:

• Test passes
• Other tests still pass
• Output pristine (no errors, warnings)

Test fails? Fix code, not test.

Other tests fail? Fix now.

Phase 5: REFACTOR - Clean Up

After green only:

• Remove duplication
• Improve names
• Extract helpers

Keep tests green. Don't add behavior.

Phase 6: COMMIT

git add tests/path/test.ts src/path/file.ts
git commit -m "feat: add specific feature with tests"

Repeat for next behavior.

</core_workflow>

<quality_standards>

📋 GOOD TEST QUALITIES

🚫 COMMON RATIONALIZATIONS (ALL INVALID)

🚨 RED FLAGS - STOP AND START OVER

If you catch yourself:

• Writing code before test
• Test passes immediately
• Can't explain why test failed
• Tests added "later"
• "Just this once"
• "I already manually tested it"
• "Keep as reference"
• "TDD is dogmatic, I'm being pragmatic"

ALL of these mean: Delete code. Start over with TDD.

</quality_standards>

<bug_fix_protocol>

🐛 BUG FIX WORKFLOW

Bug found? Write failing test reproducing it. Follow TDD cycle.

Example:

Bug: Empty email accepted

RED:
test('rejects empty email', async () => {
  const result = await submitForm({ email: '' });
  expect(result.error).toBe('Email required');
});

VERIFY RED:
$ npm test
FAIL: expected 'Email required', got undefined

GREEN:
function submitForm(data: FormData) {
  if (!data.email?.trim()) {
    return { error: 'Email required' };
  }
  // ...
}

VERIFY GREEN:
$ npm test
PASS

Never fix bugs without a test.

</bug_fix_protocol>

<integration_and_tooling>

🔗 RALPH WIGGUM INTEGRATION

When Ralph Wiggum is active:

1. Before ANY implementation: Write failing test first
2. Proactive Gate: Check edge cases BEFORE coding (use TDD to cover them)
3. Reflection Loop: After implementation, verify RED-GREEN was followed
4. Verification Matrix: Track test coverage for each feature

Ralph Wiggum will REJECT:

• Code without corresponding tests
• Tests that were written after code
• Tests that pass without implementation

✅ VERIFICATION CHECKLIST

Before marking work complete:

• Every new function/method has a test
• Watched each test fail before implementing
• Each test failed for expected reason (feature missing, not typo)
• Wrote minimal code to pass each test
• All tests pass
• Output pristine (no errors, warnings)
• Tests use real code (mocks only if unavoidable)
• Edge cases and errors covered

Can't check all boxes? You skipped TDD. Start over.

🛠️ TESTING INFRASTRUCTURE

Stack Detection & Tool Setup

Auto-detect project type and setup appropriate tools:

Test Coverage Rules

For every new function/component, generate:

• 1 Happy Path - Expected successful behavior
• 2 Edge Cases - Boundary conditions, invalid inputs
• 1 Error Case - Expected failure handling

Contract-First (MSW)

Rule: Every frontend-backend interaction MUST have an MSW handler.

// Example MSW handler
import { http, HttpResponse } from 'msw'

export const handlers = [
  http.get('/api/users/:id', ({ params }) => {
    return HttpResponse.json({
      id: params.id,
      name: 'Test User'
    })
  })
]

Benefit: Decouples frontend development from backend availability.

Ghost Inspector Protocol

AI must scan for "Untested Logic Slabs" (>20 lines without coverage) and flag them:

# Check coverage gaps
npm run test -- --coverage
# Look for files with <80% coverage

</integration_and_tooling>

<reference_and_audit>

📖 RELATED SKILLS

• @testing-anti-patterns.md - Common mock/test mistakes to avoid
• @clean-code - Code quality standards
• @verification-mastery - Evidence before completion claims
• @debug-mastery - When tests reveal bugs

🏁 FINAL RULE

Production code → test exists and failed first
Otherwise → not TDD

No exceptions without explicit user permission. </reference_and_audit>

<domain_overview>

✅ VERIFICATION MASTERY: EVIDENCE BEFORE CLAIMS

Philosophy: Claiming work is complete without verification is dishonesty, not efficiency. Evidence before claims, always. EVIDENCE INTEGRITY MANDATE (CRITICAL): Never claim a task is complete based on assumption or past memory. You MUST generate fresh evidence (logs, screenshots, test output) for every claim. AI-generated success reports are untrustworthy without proof. Any completion signal sent without accompanying verification artifacts must be rejected as "Hallucinated Success".

🚨 THE IRON LAW

NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE

If you haven't run the verification command in this message, you cannot claim it passes. Violating the letter of this rule is violating the spirit of this rule. </domain_overview> <core_workflow>

🚪 THE GATE FUNCTION

BEFORE claiming any status or expressing satisfaction:
1. IDENTIFY: What command proves this claim?
2. RUN: Execute the FULL command (fresh, complete)
3. READ: Full output, check exit code, count failures
4. VERIFY: Does output confirm the claim?
   - If NO: State actual status with evidence
   - If YES: State claim WITH evidence
5. ONLY THEN: Make the claim
Skip any step = lying, not verifying

</core_workflow> <quality_standards>

📋 COMMON CLAIMS AND REQUIREMENTS

<red_flags>

🚨 RED FLAGS - STOP IMMEDIATELY

If you catch yourself:

• Using "should", "probably", "seems to"
• Expressing satisfaction before verification ("Great!", "Perfect!", "Done!")
• About to commit/push/PR without verification
• Trusting agent success reports
• Relying on partial verification
• Thinking "just this once"
• Tired and wanting work over
• ANY wording implying success without having run verification ALL of these require: STOP. Run verification. THEN speak.

🚫 RATIONALIZATION PREVENTION

KEY PATTERNS

Tests

✅ CORRECT:
[Run: npm test]
[Output: 34/34 passing]
"All 34 tests pass."
❌ WRONG:
"Should pass now"
"Looks correct"
"Tests are green" (without running)

Regression Tests (TDD Red-Green)

✅ CORRECT:
1. Write test → Run (MUST PASS initial state or FAIL for right reason)
2. Break the code → Run (MUST FAIL)
3. Fix → Run (MUST PASS)
❌ WRONG:
"I've written a regression test"
(without red-green verification)

Build

✅ CORRECT:
[Run: npm run build]
[Output: Compiled successfully]
"Build passes."
❌ WRONG:
"Linter passed, so build should work"
(linter doesn't check compilation)

Requirements

✅ CORRECT:
1. Re-read plan/requirements
2. Create explicit checklist
3. Verify EACH item with evidence
4. Report gaps or confirm completion
❌ WRONG:
"Tests pass, phase complete"
(tests ≠ requirements)

Agent Delegation

✅ CORRECT:
1. Agent reports success
2. Check VCS diff (git diff, git status)
3. Verify changes are what was requested
4. Report actual state
❌ WRONG:
Trust agent report without verification

</quality_standards> <integration_and_tooling>

🔗 RALPH WIGGUM INTEGRATION

When Ralph Wiggum is active, verification gates are MANDATORY at each iteration:

1. Before claiming iteration complete:
   • Run all relevant tests
   • Run build if applicable
   • Run linter if applicable
   • Provide evidence in output
2. Quality Gate Check:
   • Proactive Gate verified?
   • Reflection Loop completed?
   • Verification Matrix updated?
3. Completion Signal:
   • Only create .maestro/ralph.complete AFTER full verification
   • Include verification evidence in final summary

📊 VERIFICATION COMMANDS REFERENCE

JavaScript/TypeScript

# Tests
npm test
npm run test -- --coverage
# Build
npm run build
# Lint
npm run lint
npx eslint . --ext .ts,.tsx
# Type check
npx tsc --noEmit

Python

# Tests
pytest
pytest --cov=src
# Lint
ruff check .
flake8 .
# Type check
mypy src/

General

# Git status (uncommitted changes)
git status
# Git diff (what changed)
git diff
# Process exit code (last command)
echo $?  # Unix
$LASTEXITCODE  # PowerShell

</integration_and_tooling> <reference_and_audit>

⏱️ WHEN TO APPLY

ALWAYS before:

• ANY variation of success/completion claims
• ANY expression of satisfaction
• ANY positive statement about work state
• Committing, PR creation, task completion
• Moving to next task
• Delegating to agents
• Creating completion signals Rule applies to:
• Exact phrases ("Tests pass")
• Paraphrases ("Everything is green")
• Synonyms ("All good")
• Implications ("Ready for review")
• ANY communication suggesting completion/correctness

💡 WHY THIS MATTERS

From failure analysis:

• "I don't believe you" - trust broken with user
• Undefined functions shipped - would crash in production
• Missing requirements shipped - incomplete features
• Time wasted: false completion → redirect → rework Core principle: Honesty is non-negotiable. Unverified claims are lies.

🏁 THE BOTTOM LINE

No shortcuts for verification. Run the command. Read the output. THEN claim the result. This is non-negotiable.

🔗 RELATED SKILLS

• @tdd-mastery - Verification through failing tests first
• @debug-mastery - Verify fix actually worked
• @clean-code - Quality standards to verify against </reference_and_audit>