# Agent Capabilities Reference

This document provides inter-agent awareness so each agent understands what others can do, what they will check, and what they expect.

---

## Executor Capabilities

### What Executor CAN Do
- Create and modify files (Write, Edit tools)
- Execute shell commands (Bash tool)
- Run npm/pip/cargo/go commands
- Make API calls (with rate limits - 2 req/sec)
- Run tests (npm test, pytest, cargo test, go test)
- Git operations (add, commit, log, status)
- Self-verification (existence, syntax, import checks)
- Apply deviation rules (auto-fix bugs, missing critical functionality, blocking issues)
- Write to scratchpad for inter-agent communication
- Handle checkpoints and continuation

### What Executor CANNOT Do
- UI interaction (no browser automation - needs Playwright/Puppeteer)
- Visual verification (cannot see rendered output - needs grid-visual-inspector)
- Persist knowledge across sessions (needs checkpoint files)
- Run interactive commands (no -i flags, no TTY)
- Access external services requiring auth (unless credentials provided)
- Force push to git remotes (safety restriction)
- Make architectural decisions (returns checkpoint for user decision)

### Executor Output Expectations
- Atomic commits per thread (one commit per task)
- SUMMARY.md with lessons_learned for warmth transfer
- Checkpoint files at `.grid/CHECKPOINT.md` for recovery
- State updates at `.grid/STATE.md` after each thread
- Self-assessment table for Recognizer confidence scoring

---

## Recognizer Verification Steps

### Four-Level Artifact Verification

| Level | Name | What It Checks | Commands |
|-------|------|----------------|----------|
| L1 | EXISTENCE | File physically exists | `stat <path>` |
| L2 | SUBSTANTIVE | Real code, not stubs | Line count, export check, stub pattern grep |
| L3 | WIRED | Imported and used elsewhere | Import chain grep, usage grep |
| L4 | TESTED | Automated tests pass | `npm test`, `pytest`, `cargo test`, `go test` |

### Stub Detection Patterns
Recognizer searches for these anti-patterns:
- `TODO|FIXME|XXX|HACK|PLACEHOLDER`
- `return null|return undefined|return {}|return []`
- `placeholder|coming soon|lorem ipsum`
- Empty handlers: `onClick={() => {}}`
- Console-only implementations

### Key Link Verification
Recognizer verifies these connections:
- Component → API (fetch/axios calls with response handling)
- API → Database (query with result returned)
- Form → Handler (onSubmit with real implementation)
- State → Render (state variable used in JSX)

### Confidence Scoring Factors
| Factor | Weight | What Earns Points |
|--------|--------|-------------------|
| all_tests_pass | +0.30 | Tests exist AND all pass |
| no_stubs_detected | +0.25 | Zero stub patterns found |
| all_links_wired | +0.20 | All key links verified |
| no_todo_comments | +0.10 | No TODO/FIXME in new code |
| minimal_complexity | +0.10 | No architectural warnings |
| tests_exist | +0.05 | Test framework detected |

### What Recognizer Reports
- Status: CLEAR | GAPS_FOUND | PARTIAL | CRITICAL_ANOMALY
- Score: N/M must-haves verified
- Confidence score (0.00-1.00)
- Recommendation: auto_approve | human_verify
- Structured gaps in YAML frontmatter (for Planner --gaps)

---

## Planner Constraints

### Block Sizing Rules
- **Max 3 threads per block** (prevents context degradation)
- Target ~50% context usage per block
- Split if multiple subsystems (DB + API + UI = separate blocks)
- Split if any thread modifies >5 files

### Task Complexity Guidelines
| Complexity | Threads/Block | Context/Thread |
|------------|---------------|----------------|
| Simple (CRUD, config) | 3 | ~10-15% |
| Complex (auth, payments) | 2 | ~20-30% |
| Very complex (migrations) | 1-2 | ~30-40% |

### Wave Assignment
- Wave computed from dependencies during planning
- No dependencies → wave 1
- Has dependencies → max(dep waves) + 1
- Same wave = can run in parallel

### Must-Haves Structure (Goal-Backward)
Planner derives must-haves using:
1. **Truths** - Observable outcomes ("User can see messages")
2. **Artifacts** - Required files with min_lines and exports
3. **Key Links** - Connections (from → to via pattern)

### What Planner Produces
- PLAN.md with YAML frontmatter
- Wave numbers for parallel execution
- Checkpoint types (human-verify, decision, human-action)
- Verification criteria for Recognizer
- Dependencies between blocks

---

## Inter-Agent Awareness Matrix

### Executor → Planner
**Executor expects from Planner:**
- Clear thread definitions with specific actions
- `<verify>` commands that actually test completion
- `<done>` criteria that are measurable
- Files list for each thread
- Checkpoint types clearly specified

**What breaks if missing:**
- Vague actions → Executor makes assumptions → wrong implementation
- Missing verify → Executor can't self-verify
- Missing files → Executor may create orphaned work

### Executor → Recognizer
**Executor should know Recognizer will check:**
- Every artifact exists (L1)
- Every artifact has real code, not stubs (L2)
- Every artifact is imported/used (L3)
- Tests pass if framework exists (L4)
- Key links are actually wired
- No TODO/FIXME/placeholder patterns

**To earn high confidence score, Executor should:**
- Create substantive implementations (no stubs)
- Wire all created files to the system
- Include tests where appropriate
- Remove placeholder comments before committing
- Report honest self-assessment

### Planner → Recognizer
**Planner provides to Recognizer:**
- Must-haves in PLAN.md frontmatter
- Truths to verify
- Artifacts with expected exports/min_lines
- Key links with patterns to grep

**Recognizer uses this to:**
- Know exactly what to verify
- Check specific patterns for wiring
- Score confidence accurately
- Generate structured gaps for --gaps replanning

### Planner → Executor
**Planner should specify:**
- Exact file paths (not "create a component")
- What to avoid and WHY (not just what to do)
- Dependencies between threads
- Verification commands

**What breaks if missing:**
- File paths missing → inconsistent locations
- No "why" on avoidances → Executor may repeat mistakes
- Dependencies unclear → race conditions

---

## Common Capability Mismatches

### 1. Visual Verification Requested
**Problem:** Planner creates checkpoint:human-verify for something Executor could verify
**Solution:** Planner should use `<verify>` for programmatic checks, checkpoint only for visual

### 2. Browser Interaction Expected
**Problem:** Thread expects clicking buttons, filling forms in browser
**Solution:** Planner should note this needs grid-visual-inspector or Playwright setup

### 3. External Service Auth
**Problem:** Thread needs API key or OAuth that Executor doesn't have
**Solution:** Planner should include checkpoint:human-action for auth setup

### 4. Database State Verification
**Problem:** Recognizer can't verify data persisted correctly via grep
**Solution:** Executor should include test that queries database

### 5. Stub Detection False Positives
**Problem:** `return []` is valid for empty initial state
**Solution:** Executor should document intentional empty returns in comments

---

## Agent Communication Paths

```
User → Planner: "Build chat feature"
Planner → Executor: PLAN.md with must-haves, threads
Executor → Scratchpad: Discoveries during execution
Executor → Recognizer: SUMMARY.md with self-assessment
Recognizer → Planner: VERIFICATION.md with gaps (if --gaps)
Scratchpad → All Agents: Live context during execution
Warmth → Next Session: lessons_learned from SUMMARY.md
```

---

## Quick Reference for Each Agent

### Executor Quick Checks
Before completing a thread:
- [ ] File exists? (`stat`)
- [ ] Has content? (`wc -l > 0`)
- [ ] Valid syntax? (language-specific check)
- [ ] Imports work? (`node -e "require(...)"`)
- [ ] Self-assessment accurate?

### Recognizer Quick Checks
For each artifact:
- [ ] L1: Exists
- [ ] L2: Lines >= min_lines, exports match, no stubs
- [ ] L3: Imported by another file, used (not just imported)
- [ ] L4: Tests pass (or NO_TESTS noted)

For each key link:
- [ ] Pattern found in source file
- [ ] Response/result is used (not ignored)

### Planner Quick Checks
For each thread:
- [ ] File paths explicit?
- [ ] Action specific enough for different Claude?
- [ ] Verify command provided?
- [ ] Done criteria measurable?

For must-haves:
- [ ] Truths are outcomes, not tasks?
- [ ] Artifacts have paths and min_lines?
- [ ] Key links have grep-able patterns?

---

*This document enables agents to work together effectively by understanding each other's capabilities and expectations.*