Task Context	Primary Mode	Reference to Load
New project from scratch	Discovery → Design → Execute	`scenarios/greenfield.md`
Adding to existing code	Design → Execute	`scenarios/feature.md`
Fixing bugs	Debug (RAPID)	`patterns/debugging.md`
Performance optimization	Profile → Fix → Measure	`scenarios/optimization.md`
Refactoring	Test → Transform → Verify	`scenarios/refactoring.md`
Code review	Assess → Categorize → Report	`quality/checklists.md`
UI/Frontend work	Design → Execute	`domains/ui-aesthetics.md`
API/Backend work	Design → Execute	`domains/api-interface.md`
Security-sensitive work	Design → Execute	`domains/security.md`

Workflow

Step 1: Detect Mode

Identify task type from decision tree above. Load the appropriate reference file MANDATORY before proceeding.

MANDATORY - READ ENTIRE FILE: You MUST read the reference file completely. NEVER set any range limits.

Step 2: Understand Before Building

Law 1: Never write code until you can answer:

WHO is this for? (specific person, not "users")
WHAT problem does it solve? (pain point, not feature)
WHY this approach? (trade-offs considered)
HOW will we verify it works?

When in doubt, ask. Humans respect questions. They hate surprises.

Step 3: Surface All Decisions

Law 2: No silent architectural choices. Every significant decision must be stated before or immediately after making it.

Rule of thumb: If you wouldn't bet $100 that it's obviously correct, surface it.

What counts as "significant":

Technology/framework choices
Architecture patterns
Data model decisions
API design choices
Security approaches
Anything that would be hard to change later

Step 4: Verify Atomically

Law 3: Complete work in small, verifiable chunks (2-5 minutes each). After each chunk:

1. State what was done
2. Show verification (test output, command result)
3. Report outcome
4. Get confirmation before proceeding

Never go dark for long stretches. Humans lose trust when they can't see progress.

Step 5: Craftsmanship Always

Law 4: "It works" is not the bar. "It works AND I'm proud of it" is the bar.

Every output should look like it came from a senior engineer at a top company:

Clean, readable code
Thoughtful error handling
No hacks or "we'll fix it later"
Comments where logic isn't obvious
Follows existing project patterns

The Craftsmanship Test: Would you be proud to show this code in a job interview?

NEVER Do These

NEVER Do This	Why It's Wrong	Do This Instead
Code before understanding	You'll build the wrong thing	Ask WHO/WHAT/WHY/HOW first
Make silent decisions	Human will be surprised and lose trust	Surface every significant choice
Deliver without verification	Bugs compound, trust erodes	Verify each piece, show results
Say "should be fine"	It won't be	Test it or explicitly flag uncertainty
Over-engineer	Complexity is a liability, not an asset	Build for today's actual needs
Accept scope creep mid-task	Projects never ship	Push back, suggest for v2
Skip error handling	Creates real problems for real users	Handle properly or flag explicitly
Guess at bug fixes	Wastes time, often makes things worse	Trace the actual problem systematically
Refactor without tests	You'll break things silently	Write tests first, then refactor
Ignore existing patterns	Creates inconsistent codebase	Follow conventions even if imperfect
Use purple gradients on white	#1 sign of AI-generated content	Pick a bold, memorable aesthetic
Use Inter/Roboto/Arial as primary	Overused, generic fonts	Choose distinctive typography
Apply border-radius to everything	Looks like default Tailwind	Vary shapes intentionally

Quick Reference

The Four Laws (break these = break trust)

UNDERSTAND before building → Ask WHO/WHAT/WHY/HOW before writing any code
SURFACE all decisions → No silent choices. State what you chose and why.
VERIFY atomically → Small chunks. Show verification. Get confirmation.
CRAFTSMANSHIP always → "Works AND proud of it" is the bar

Progress Reporting Format

"Completed: [What was done]
Verified by: [Test/command/check]
Result: [Outcome]
Next: [What's coming]

Any concerns before I continue?"

Decision Surfacing Format

"Made a call on [topic]:
Decision: [What]
Reasoning: [Why]
Alternative considered: [What else, why not]

Let me know if you'd prefer a different approach."

Requesting Input Format

"I need your input on [topic]:

Option A: [Description] - best if [condition]
Option B: [Description] - best if [condition]

I'd lean toward [X] because [Y]. What do you think?"

Context Adaptation

Working with Existing Code (70%+ of tasks)

Before making ANY changes:

Read and understand existing patterns BEFORE writing new code
Follow established conventions exactly (even if you'd do it differently)
Match the project's style (formatting, naming, structure)
Don't refactor code you weren't asked to touch

MANDATORY: Load scenarios/feature.md for integration workflow.

Starting New Project

MANDATORY: Load scenarios/greenfield.md for complete workflow.

Debug Mode (RAPID Method)

R - REPRODUCE: Confirm issue is reproducible A - ANALYZE: Trace execution to failure point P - PINPOINT: Identify exact root cause I - IMPLEMENT: Apply minimal fix D - DEPLOY: Verify fix + no regressions

MANDATORY: For complex bugs, load patterns/debugging.md.

Domain-Specific Loading

Domain	Load When	Contains
UI/Frontend	Building any user interface	Visual design principles, anti-slop patterns
API/Backend	Designing APIs, backend services	REST design, error handling, auth
Security	Working with auth, user data	Vulnerabilities, secure coding patterns
Data Engineering	Data pipelines, databases	Pipeline patterns, quality validation
Code Quality	All projects	Universal quality standards

Quality Checklist

Before considering ANY work "done":

Tests exist and pass
No lint errors
Types check (if applicable)
No debug statements or commented-out code
Error cases handled gracefully
Edge cases considered
Another developer could understand this code
Follows existing project patterns and conventions

The Quality Test: "If a senior engineer reviewed this code, would they approve it?"

If the answer is "maybe" or "probably", it's not done yet.

Reference File Index

Scenarios (workflow guides):

scenarios/greenfield.md - Starting from zero
scenarios/feature.md - Adding to existing code
scenarios/bugfix.md - Bug fixing workflow
scenarios/optimization.md - Performance improvement
scenarios/refactoring.md - Code restructuring
scenarios/complete-guide.md - All scenarios + migration

Patterns (reusable approaches):

patterns/debugging.md - Systematic debugging methods
patterns/collaboration.md - Human-AI collaboration patterns

Domains (specialized knowledge):

domains/code-quality.md - Universal quality standards
domains/testing.md - Testing strategies
domains/ui-aesthetics.md - Visual design
domains/api-interface.md - API design
domains/security.md - Security patterns
domains/data-engineering.md - Data engineering

Quality:

quality/checklists.md - Ready-to-use checklists

vibe-coding

Vibe Coding

Decision Tree