notque/vexjoy-agent / skills/process/workflow
workflow
VerifiedStructured work: multi-phase tasks, feature builds, planning, objective loops, hill climbing.
references/project-coordinator/communication-protocols.md
View on GitHub# Communication Protocols Reference
> **Scope**: Templates for STATUS.md, HANDOFF.md, PROGRESS.md, BLOCKERS.md in multi-agent coordination.
---
## STATUS.md — Live Project Heartbeat
Update after every agent task completion.
```markdown
# STATUS.md
UPDATED: 2026-04-09 15:42 UTC
PHASE: 3 of 5 — API Endpoint Implementation
OVERALL: IN PROGRESS
## Active Agents
| Agent | Task | Status | File Domain | Attempts |
|-------|------|--------|-------------|----------|
| api-worker (programming/nodejs-api.md) | /api/users endpoint | IN PROGRESS | src/routes/users.js | 1/3 |
## Completed Phases
- [x] Phase 1: Database schema — db-worker (data/database.md) — DONE
## Context Health
CONTEXT USAGE: ~45% (safe)
NEXT CHECKPOINT: At Phase 4 start
```
**Rules**: Update after every task (not just phase). File domains list specific files. Attempt count (X/3) must be accurate.
---
## HANDOFF.md — Task Assignment
One per agent dispatch.
```markdown
# HANDOFF — api-worker (programming/nodejs-api.md)
ATTEMPT: 1 of 3
## Task
Implement `/api/users` GET endpoint with pagination.
## File Domain (ONLY these files)
- `src/routes/users.js`, `src/routes/users.test.js`
DO NOT TOUCH: src/models/, src/middleware/, schema.sql
## Dependencies (Already Complete)
- schema.sql (Phase 1, DONE)
- src/models/user.js (Phase 2, DONE)
## Success Criteria (All Must Pass)
1. `npm test src/routes/users.test.js` exits 0
2. GET /api/users returns `{ data: [...], page: N, total: N }`
3. Missing page defaults to page=1, limit=20
4. Invalid page returns HTTP 400
5. `npm run build` exits 0
## Escalation
If blocked after attempting, write BLOCKERS.md and stop. Do NOT attempt a 4th time.
```
**Rules**: File domains must be explicit and mutually exclusive. Success criteria must be executable commands. Escalation instructions prevent exceeding 3-attempt limit.
---
## PROGRESS.md — Context Reload Summary
Write at 70% context AND at project completion.
```markdown
# PROGRESS.md
WRITTEN: 2026-04-09 16:15 UTC
REASON: Context approaching 70%
## Project Phases
| Phase | Status | Agent | Notes |
|-------|--------|-------|-------|
| 1 | DONE | db-worker (data/database.md) | 4 tables |
| 2 | DONE | python-worker (programming/python-general.md) | User, Preferences models |
| 3 | DONE | api-worker (programming/nodejs-api.md) | /users, /users/:id, /users/me |
| 4 | NOT STARTED | — | |
## Modified Files
### Created
- schema.sql, src/models/user.py, src/routes/users.js
### Modified
- package.json (added express-validator), src/app.js (registered router at line 34)
## Key Decisions Made
1. Pagination: page+limit (not cursor), defaults page=1 limit=20
2. Auth: JWT at router level
## Next Phase Instructions
Dispatch api-worker (programming/nodejs-api.md) AND python-worker (programming/python-general.md) in PARALLEL for Phase 4.
File domains do NOT overlap — safe for parallel execution.
```
**Rules**: Write at 70%, not 100% (too late). List every modified file. Decisions must be explicit. Next-phase instructions complete enough for a fresh coordinator.
---
## BLOCKERS.md — Escalation Log
Append-only. Unique IDs for cross-reference.
```markdown
## BLOCKER-001
AGENT: api-worker (programming/nodejs-api.md)
ATTEMPTS: 3/3 FAILED
STATUS: OPEN
### Failure Pattern
All 3: OperationalError: database connection refused (port 5432)
### Root Cause
Dev database not running. Not a code issue.
### Resolution Options
A) Start postgres: `sudo systemctl start postgresql`
B) Use SQLite for dev (requires model changes)
C) Skip tests, mock DB (reduces coverage)
USER ACTION REQUIRED: Choose A, B, or C
```
**Rules**: Root cause must distinguish infrastructure from code failures. Resolution options must be concrete actions. User action label triggers escalation.
---
## Error-Fix Mappings
| Symptom | Fix |
|---------|-----|
| Agent continues past 3 attempts | Add explicit "stop at 3, write BLOCKERS.md" to every HANDOFF |
| Fresh agent repeats completed work | Write PROGRESS.md at 70% context |
| Two agents conflict on same file | Audit all active HANDOFF.md file domains before parallel dispatch |
| Cannot determine current phase | Enforce STATUS.md update after every agent completion |
| Blocker stalls indefinitely | Each option must be executable, not directional |
---
## Detection Commands
```bash
ls -la STATUS.md 2>/dev/null || echo "MISSING STATUS.md"
grep -L "SUCCESS CRITERIA" HANDOFF*.md 2>/dev/null
grep -c "STATUS: OPEN" BLOCKERS.md 2>/dev/null
# Verify non-overlapping file domains
grep "File Domain\|FILE DOMAIN" HANDOFF*.md | grep -oP '(?<=\s)\S+\.(js|py|go|ts|sql)' | sort | uniq -d
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| planning-and-task-breakdownaddyosmani/agent-skillsBreaks work into ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable tasks. Use when a task feels too large to start, when you need to estimate scope, or when parallel work is possible. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| screenpipethedotmack/claude-memSearch screen and audio history recorded by Screenpipe and optionally save selected context into claude-mem. Use when the user asks to recall desktop activity, a meeting, or something seen in another app through Screenpipe. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| contact-widgetnexu-io/open-designSelf-contained floating chat widget with welcome screen, social links, meeting button, and message input. Single HTML file, zero dependencies. | Stars: 108k | Updated | Claude CodeCodex | Verified | Install |
| meeting-notesnexu-io/open-designMeeting notes page — title bar with attendees, agenda checklist, decisions block, action items table with owners + dates, and a "next meeting" footer. Use when the brief mentions "meeting notes", "minutes", "1:1 notes", "all-hands recap", or "会议纪要". | Stars: 108k | Updated | Claude CodeCodex | Verified | Install |