From d016e69485e974759a7e9700f162a98aa43e1e4b Mon Sep 17 00:00:00 2001 From: Eric Gullickson <16152721+ericgullickson@users.noreply.github.com> Date: Sat, 3 Jan 2026 13:33:28 -0600 Subject: [PATCH] chore: update README with development workflow --- README.md | 221 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 220 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 13c2208..6d92c86 100644 --- a/README.md +++ b/README.md @@ -33,4 +33,223 @@ make migrate # run DB migrations - Switch traffic between environments on production: `sudo ./scripts/ci/switch-traffic.sh blue instant` - View which container images are running: `docker ps --format 'table {{.Names}}\t{{.Image}}'` - Flush all redis cache: `docker compose exec -T mvp-redis sh -lc "redis-cli FLUSHALL"` -- Flush all backup data on staging before restoring: `docker compose exec mvp-postgres psql -U postgres -d motovaultpro -c "TRUNCATE TABLE backup_history, backup_schedules, backup_settings RESTART IDENTITY CASCADE;"` \ No newline at end of file +- Flush all backup data on staging before restoring: `docker compose exec mvp-postgres psql -U postgres -d motovaultpro -c "TRUNCATE TABLE backup_history, backup_schedules, backup_settings RESTART IDENTITY CASCADE;"` + +## Development Workflow + +``` + MotoVaultPro Development Workflow +============================================================================ + + SPRINT ISSUE SELECTION + ---------------------- + + +--------------------+ +---------------------+ + | Gitea Issue Board | | status/backlog | + | (Source of Truth) |------->| | + +--------------------+ +----------+----------+ + | + v + +---------------------+ + | status/ready | + | (Current Sprint) | + +----------+----------+ + | + Select smallest + highest priority + | + v + +---------------------+ + | status/in-progress | + +----------+----------+ + | +============================================================================ + + PRE-PLANNING SKILLS (Optional) + ------------------------------ + + | + +-----------------------------------+-----------------------------------+ + | | | + v v v ++------------------+ +------------------+ +------------------+ +| CODEBASE | | PROBLEM | | DECISION | +| ANALYSIS SKILL | | ANALYSIS SKILL | | CRITIC SKILL | ++------------------+ +------------------+ +------------------+ +| When: Unfamiliar | | When: Complex | | When: Uncertain | +| area | | problem | | approach | ++------------------+ +------------------+ +------------------+ + +============================================================================ + + PLANNER SKILL: PLANNING WORKFLOW + --------------------------------- + + +---------------------+ + | PLANNING | + | (Context, Scope, | + | Decision, Refine) | + +----------+----------+ + | + v + +---------------------------------------+ + | PLAN REVIEW CYCLE | + | (All results posted to Issue) | + +---------------------------------------+ + | + v + +---------------------+ + +------>| QR: plan-complete- | + | | ness | + | +----------+----------+ + | | + [FAIL] | [PASS] | + | v + | +---------------------+ + | | QR: plan-code | + | | (RULE 0/1/2) | + | +----------+----------+ + | | + [FAIL]-----+ [PASS] | + v + +---------------------+ + +------>| TW: plan-scrub | + | +----------+----------+ + | | + | v + | +---------------------+ + | | QR: plan-docs | + | +----------+----------+ + | | + [FAIL]-----+ [PASS] | + v + +---------------------+ + | PLAN APPROVED | + +----------+----------+ + | + ============================================================================ + + EXECUTION + --------- + + | + v + +---------------------+ + | Create Branch | + | issue-{N}-{slug} | + +----------+----------+ + | + v + +---------------------------------------+ + | MILESTONE EXECUTION | + | (Parallel Developer Agents) | + +---------------------------------------+ + | + +---------------------------------------------------------+ + | +---------------+ +---------------+ +---------------+ + | | FEATURE AGENT | | FRONTEND | | PLATFORM | + | | (Backend) | | AGENT (React) | | AGENT | + | +-------+-------+ +-------+-------+ +-------+-------+ + | | | | + | +------------------+------------------+ + | | + | Delegate to DEVELOPER role-agent + | | + +---------------------------------------------------------+ + | + v + +---------------------+ + +------>| QR: post- | + | | implementation | + | +----------+----------+ + | | + | [FAIL] | [PASS] + | | | + +------+ v + +---------------------+ + | TW: Documentation | + +----------+----------+ + | + ============================================================================ + + PR AND REVIEW + ------------- + + | + v + +---------------------+ + | Open PR | + | Fixes #{N} | + +----------+----------+ + | + v + +---------------------+ + | status/review | + +----------+----------+ + | + v + +---------------------------------------+ + | QUALITY AGENT | + | (Final Gatekeeper - ALL GREEN) | + +---------------------------------------+ + | + +-----------------------+-----------------------+ + v v v + +------------------+ +------------------+ +------------------+ + | npm run lint | | npm run type- | | npm test | + | | | check | | | + +------------------+ +------------------+ +------------------+ + | | | + v v v + +------------------+ +------------------+ +------------------+ + | Mobile Viewport | | Desktop Viewport | | RULE 0/1/2 | + | (320px, 768px) | | (1920px) | | Review | + +------------------+ +------------------+ +------------------+ + | | | + +-----------------------+-----------------------+ + | + [FAIL] | [PASS] + | | | + v | v + +---------------+ | +---------------------+ + | Fix & Iterate |<--------+ | PR APPROVED | + +---------------+ +----------+----------+ + | + ============================================================================ + + COMPLETION + ---------- + + +---------------------+ + | Merge PR to main | + +----------+----------+ + | + v + +---------------------+ + | status/done | + +----------+----------+ + | + v + +---------------------+ + | DOC-SYNC SKILL | + +---------------------+ + + ============================================================================ + + LEGEND + ------ + Skills: codebase-analysis, problem-analysis, decision-critic, planner, doc-sync + Role-Agents: Developer, Technical Writer (TW), Quality Reviewer (QR), Debugger + Domain Agents: Feature Agent, Frontend Agent, Platform Agent, Quality Agent + + Labels: status/backlog -> status/ready -> status/in-progress -> status/review -> status/done + Commits: {type}: {summary} (refs #{N}) | Types: feat, fix, chore, docs, refactor, test + Branches: issue-{N}-{slug} | Example: issue-42-add-fuel-report + + QUALITY RULES + ------------- + RULE 0 (CRITICAL): Production reliability - unhandled errors, security, resource exhaustion + RULE 1 (HIGH): Project conformance - mobile+desktop, naming conventions, CI/CD pass + RULE 2 (SHOULD_FIX): Structural quality - god objects, duplicate logic, dead code + ``` + + See `.ai/workflow-contract.json` for the complete workflow specification. \ No newline at end of file