Skip to content

Latest commit

 

History

History
102 lines (79 loc) · 2.68 KB

quick-reference.md

File metadata and controls

102 lines (79 loc) · 2.68 KB

Project Workflow Protocol — Quick Reference

One-page summary of the entire protocol. Print this, pin it, or drop it in your AI's context.


The Loop

PLAN  → Investigate → Write Plan → Get Approval → Start Branch
BUILD → Code → Commit (with refs) → Update Plan Status → Repeat
CHECK → tsc → build → tests → visual verify → merge --no-ff → post-merge build
DOCS  → Update VISION, plans, CHANGELOG after each milestone
SHIP  → User confirms → merge to main → deploy → verify → monitor

Branch Strategy

main                    ← production-ready at all times
├── feature/{name}      ← new features
├── fix/{name}          ← bug fixes
├── refactor/{name}     ← structural improvements
└── docs/{name}         ← documentation only

Commit Convention

{type}({scope}): {concise description}

Types:  feat | fix | refactor | style | docs | perf | test | chore
Scope:  component name | PLAN-{NNN}/{item} | feature ID

Pre-Merge Checklist

- [ ] tsc --noEmit passes
- [ ] npm run build exits 0
- [ ] npm test passes
- [ ] Visual check at desktop + mobile
- [ ] Commit history is clean and atomic

Plan Template (5-Line Solo)

Feature: What am I building?
Why:     What problem does this solve?
Files:   Which files will I touch?
Verify:  How will I know it works?
Risk:    What might break?

AI Agent Rules

1. Assistant, not authority — you propose, human decides
2. Plans before code — always
3. Smallest effective change — don't touch what isn't broken
4. Flag uncertainty — better to ask than hallucinate
5. Verify everything — list how the user can confirm your work

Severity Levels

P0 Critical  → Service down, all users affected     → Immediate
P1 Major     → Core feature degraded, workaround     → Within 1 hour
P2 Minor     → Non-core broken, most unaffected      → Within 24 hours
P3 Low       → Cosmetic, minor inconvenience          → Next sprint

Trust Levels (AI)

L0 Untested   → Plan-only, approval per change
L1 Verified   → Execute approved plans, show diffs
L2 Trusted    → Execute + commit within scope
L3 Autonomous → Plan + execute + verify within patterns

File Naming

camelCase     → functions, variables
PascalCase    → components, types, classes
SCREAMING_SNAKE → constants
kebab-case    → file names (non-component)

Recovery Protocol

1. DETECT   → Alert or report
2. ASSESS   → Severity (P0/P1/P2/P3)
3. MITIGATE → Restore service FIRST
4. DIAGNOSE → Root cause AFTER service is up
5. FIX      → Proper fix with verification
6. DOCUMENT → Postmortem within 48 hours