Agent Workflow Rules

📋 Task Management Protocol (READ FIRST)

CRITICAL: All agents MUST follow the task coordination protocol:

• 📜 Master Protocol: ~/Projects/TASK_COORDINATION.md
• 🤖 AI Agent Guide: ~/Projects/.agents/AI_AGENT_TASK_PROTOCOL.md
• ✅ Project TODO: ~/Projects/DevBot/TODO.md

Task Lifecycle: [ ] → [⏳] → [✅] → [🔒] → Archive

Quick Rules:

• Creating task: Include acceptance criteria, estimate, dependencies
• Starting task: Mark [⏳], add owner & timestamp
• Completing task: Mark [✅], provide proof (commit SHA, tests passing)
• Blocked: Mark [🚧], create unblocking task, notify human
• Never abandon: Every [ ] task must reach [🔒] or [❌]

Core Principle: Parallel Build + Redevelopment Queue

Never block the main thread on errors. Always keep building forward.

The Pattern

Main Thread                    Background Agents
┌──────────────┐               ┌──────────────────┐
│ Build Task A │ ────done────► │ Verify Task A     │
│ Build Task B │               │ (type check, test │
│ Build Task C │               │  lint, review)    │
│    ...       │               └────────┬─────────┘
└──────────────┘                        │
                                        ▼
                               ┌──────────────────┐
                               │ Pass? ─► Done     │
                               │ Fail? ─► Requeue  │
                               │   with error ctx  │
                               └──────────────────┘

Rules

1. Launch background verification agents on completed subtasks while continuing to build the next ones
2. Never wait for a build/test/lint to finish before starting the next feature
3. When a background agent finishes, check its output:
   • If it found errors: fix immediately via another background agent or inline
   • If clean: mark verified and move on
4. Completed tasks go into a redevelopment queue for a second verification pass
5. Failed verifications get retried with the error chain injected into the prompt (up to 3 attempts)
6. At the end of a batch, run a final sweep: tsc --noEmit && vitest run

When to Apply

Subagent Usage

Use Task tool (subagents) for:

• Background error fixing: launch on build/lint failures while continuing main work
• Parallel file exploration: search multiple areas of codebase simultaneously
• Verification passes: type-check, test, lint completed work
• Independent feature building: when features have no dependencies

Provide subagents with:

• Clear, specific objective
• Relevant file paths and context
• Success criteria (what "done" looks like)
• Error context from previous attempts (if retrying)

Avoid subagents for:

• Simple single-file reads (use Read tool directly)
• Sequential dependent operations (do inline)
• Trivial changes that don't need verification

Planning

For any task that touches more than 3 files or involves architectural decisions:

1. Enter plan mode first
2. Present implementation plan
3. Wait for explicit "proceed" or "go ahead"
4. Execute step by step, using redevelopment queue for verification

Quality Gates

After ANY code edit, before marking complete:

1. Run typecheck: npx tsc --noEmit (background agent)
2. Run tests: npx vitest run (background agent)
3. If errors found, fix and re-run (redevelopment queue handles this)

Context Management

• Always read files before editing
• Use subagents to prevent context bloat
• Compact at task boundaries, not mid-work
• Summarize complex explorations

Self-Correction Loop

When a mistake is caught (by user, tests, or verification agent):

1. Acknowledge the correction
2. Fix the issue
3. Add to LEARNED.md
4. Re-verify the fix

Agent Registry Extension

BettorsACE Platform Agent (TypeScript)

• File: src/ai/bettorsace-agent.ts
• Goal: Provide platform-specific diagnostics, feature blueprints, and strategic recommendations for BettorsACE.
• Capabilities:
  • diagnosePlatformIssue(issue, focus, context)
  • createFeatureBlueprint(featureRequest, context)
  • generatePlatformStrategy(objective, context)
• Focus areas: auth, wallet, odds, analytics, performance, security, growth
• Notes: Uses existing Claude orchestration primitives from src/ai/claude.ts.