Agent Teams for td-watch
Roles
| Role |
Agent file |
Writes code |
Key tools |
| Lead |
(main session, delegate mode) |
Never |
Task management, SendMessage |
| Implementer |
.claude/agents/implementer.md |
Yes |
Read, Write, Edit, Glob, Grep, Bash |
| Reviewer |
.claude/agents/reviewer.md |
No |
Read, Glob, Grep, Bash |
| Researcher |
.claude/agents/researcher.md |
No |
Read, Glob, Grep, Bash, WebFetch, WebSearch |
| Tester |
.claude/agents/tester.md |
Test files only |
Read, Write, Edit, Glob, Grep, Bash |
The lead never writes code. Use delegate mode (Shift+Tab). Lead's job: break down work, assign tasks, triage friction, run quality gates, synthesize results.
Hard Rules
- No two teammates edit the same file. Split by file ownership. If two tasks touch the same file, make one depend on the other.
- Tasks are the coordination layer. Task list is source of truth.
- Start small. Lead + 2 teammates handles most work. Spawn more only when clearly beneficial.
- Never silently work around friction. Fix small friction now. Report large friction to lead.
- Codify discoveries as skills. If you searched for it, future agents will too.
Common Configurations
Lead + 2 Implementers (most common)
Split by file ownership. Example: one owns server routes, one owns page components.
Lead + Researcher + Implementer
Researcher investigates first, implementer builds after findings arrive.
Lead + 3 Implementers
For building multiple independent components/pages in parallel.
Lead + Implementer + Reviewer
For security-sensitive or contract-critical code. Review loop after implementation.
Task Guidelines
- Each task maps to clear file ownership boundaries
- 3-6 tasks per teammate per session
- Include acceptance criteria: "Build DataTable with sortable columns, pagination, loading/empty states, using design tokens" not just "Build DataTable"
- Use
blockedBy when a task genuinely depends on another (page depends on server route). Don't use it for sequencing preference.
Quality Gates
Run after implementation completes, before marking work done:
npx svelte-check # type errors
npm run test:unit # component tests
npm run test:server # server route tests
npm run test:e2e # integration tests
Lead can run these directly or assign to a tester teammate.
Friction Protocol
Friction = any point where an agent can only proceed by guessing, bypassing, or working around.
- Surface immediately. Never hide a workaround.
- Fix easy friction now (< 10 min) — even before your main task.
- Task hard friction explicitly. Create a real task, not a "later" note.
- Stop when blocked. If progress requires human access/decisions, report and pause.
Cross-Repository Work
~/code/td/ — td-sync server (Go)
~/code/td-watch/ — td-watch (SvelteKit)
~/code/sidecar/ — sidecar TUI (Go), reference only
Label which repo each task targets. Prefer separate tasks per repo. Researcher can explore ~/code/td/ while implementer works in ~/code/td-watch/.
Context Management
When the lead senses context pressure (many exchanges, approaching limits), write a summary task containing:
- Team state — who's spawned, what each is working on
- Task status — complete, in progress, blocked, why
- Friction log — resolved and open
- Key decisions made
- Reference pointers to relevant docs
- Next actions
Agentic Coding Runtimes
For programmatic agent dispatch with full coding capability and streaming output, see:
references/agentic-coding-patterns.md — Detailed reference covering:
- Codex App-Server Protocol (OpenAI) — JSON-RPC over stdio, thread/turn lifecycle, streaming events, multi-turn continuation. Best for Go integration.
- Claude Agent SDK (Anthropic) —
query() async generator, subagent orchestration with explicit role definitions, session persistence/resumption. TypeScript + Python.
- Comparison table, Go integration patterns, and when to use each.
Both support full agentic coding with subagent spawning. The integration shape from Go is identical: launch subprocess, read structured events from stdout.
Key References
references/agentic-coding-patterns.md — Codex app-server + Claude Agent SDK patterns
docs/agent-teams.md — full team workflow documentation
docs/sync-admin-web-spec.md — system spec, API contracts
docs/design-system.md — design tokens, component specs
docs/agent-dev-guide.md — dev environment, testing, logging
Starting a Team Session
Tell Claude what to build and how to structure the team:
I'm working on [feature]. Create an agent team with delegate mode.
Spawn:
- [role] for [scope with file ownership]
- [role] for [scope with file ownership]
Break the work into tasks based on the spec. Assign clear file ownership.
1---2name: agent-teams3description: Coordinate Claude Code agent teams for td-watch development. Use when creating teams, assigning tasks, running team sessions, or when any agent needs to understand team coordination rules. Covers roles, file ownership, friction protocol, quality gates, and common team configurations.4metadata:5 source: https://skillmd.com/skills/marcus/agent-teams6---78# Agent Teams for td-watch910## Roles1112| Role | Agent file | Writes code | Key tools |13|------|-----------|-------------|-----------|14| Lead | (main session, delegate mode) | Never | Task management, SendMessage |15| Implementer | `.claude/agents/implementer.md` | Yes | Read, Write, Edit, Glob, Grep, Bash |16| Reviewer | `.claude/agents/reviewer.md` | No | Read, Glob, Grep, Bash |17| Researcher | `.claude/agents/researcher.md` | No | Read, Glob, Grep, Bash, WebFetch, WebSearch |18| Tester | `.claude/agents/tester.md` | Test files only | Read, Write, Edit, Glob, Grep, Bash |1920**The lead never writes code.** Use delegate mode (Shift+Tab). Lead's job: break down work, assign tasks, triage friction, run quality gates, synthesize results.2122## Hard Rules23241. **No two teammates edit the same file.** Split by file ownership. If two tasks touch the same file, make one depend on the other.252. **Tasks are the coordination layer.** Task list is source of truth.263. **Start small.** Lead + 2 teammates handles most work. Spawn more only when clearly beneficial.274. **Never silently work around friction.** Fix small friction now. Report large friction to lead.285. **Codify discoveries as skills.** If you searched for it, future agents will too.2930## Common Configurations3132### Lead + 2 Implementers (most common)33Split by file ownership. Example: one owns server routes, one owns page components.3435### Lead + Researcher + Implementer36Researcher investigates first, implementer builds after findings arrive.3738### Lead + 3 Implementers39For building multiple independent components/pages in parallel.4041### Lead + Implementer + Reviewer42For security-sensitive or contract-critical code. Review loop after implementation.4344## Task Guidelines4546- Each task maps to clear file ownership boundaries47- 3-6 tasks per teammate per session48- Include acceptance criteria: "Build DataTable with sortable columns, pagination, loading/empty states, using design tokens" not just "Build DataTable"49- Use `blockedBy` when a task genuinely depends on another (page depends on server route). Don't use it for sequencing preference.5051## Quality Gates5253Run after implementation completes, before marking work done:5455```bash56npx svelte-check # type errors57npm run test:unit # component tests58npm run test:server # server route tests59npm run test:e2e # integration tests60```6162Lead can run these directly or assign to a tester teammate.6364## Friction Protocol6566Friction = any point where an agent can only proceed by guessing, bypassing, or working around.67681. **Surface immediately.** Never hide a workaround.692. **Fix easy friction now** (< 10 min) — even before your main task.703. **Task hard friction explicitly.** Create a real task, not a "later" note.714. **Stop when blocked.** If progress requires human access/decisions, report and pause.7273## Cross-Repository Work7475- `~/code/td/` — td-sync server (Go)76- `~/code/td-watch/` — td-watch (SvelteKit)77- `~/code/sidecar/` — sidecar TUI (Go), reference only7879Label which repo each task targets. Prefer separate tasks per repo. Researcher can explore `~/code/td/` while implementer works in `~/code/td-watch/`.8081## Context Management8283When the lead senses context pressure (many exchanges, approaching limits), write a summary task containing:841. Team state — who's spawned, what each is working on852. Task status — complete, in progress, blocked, why863. Friction log — resolved and open874. Key decisions made885. Reference pointers to relevant docs896. Next actions9091## Agentic Coding Runtimes9293For programmatic agent dispatch with full coding capability and streaming output, see:9495**`references/agentic-coding-patterns.md`** — Detailed reference covering:96- **Codex App-Server Protocol** (OpenAI) — JSON-RPC over stdio, thread/turn lifecycle, streaming events, multi-turn continuation. Best for Go integration.97- **Claude Agent SDK** (Anthropic) — `query()` async generator, subagent orchestration with explicit role definitions, session persistence/resumption. TypeScript + Python.98- Comparison table, Go integration patterns, and when to use each.99100Both support full agentic coding with subagent spawning. The integration shape from Go is identical: launch subprocess, read structured events from stdout.101102## Key References103104- `references/agentic-coding-patterns.md` — Codex app-server + Claude Agent SDK patterns105- `docs/agent-teams.md` — full team workflow documentation106- `docs/sync-admin-web-spec.md` — system spec, API contracts107- `docs/design-system.md` — design tokens, component specs108- `docs/agent-dev-guide.md` — dev environment, testing, logging109110## Starting a Team Session111112Tell Claude what to build and how to structure the team:113114```115I'm working on [feature]. Create an agent team with delegate mode.116Spawn:117- [role] for [scope with file ownership]118- [role] for [scope with file ownership]119Break the work into tasks based on the spec. Assign clear file ownership.120```