# Subagent Workflow

> Use when orchestrating subagents for implementation. Covers when to dispatch vs recall, how to scope tasks, session management, and handoff patterns. Load this before working with any subagent.

- Skill: `majiayu000/subagent-workflow` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add majiayu000/subagent-workflow`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/subagent-workflow/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/subagent-workflow

---


# Subagent Workflow

Orchestrate subagents effectively.

> **Announce:** "I'm using subagent-workflow to coordinate [subagent] for this task."

## Iron Law

```
TRACK SESSION IDs - RECALL FOR FOLLOW-UPS
```

When a subagent completes work and later issues are found, recall their session
instead of starting fresh. They have context.

## Available Subagents

### @supabase-expert

**Invoke for:**
- Database schema changes
- SQL function creation/modification
- RLS policy implementation
- PostGIS/pgvector operations

**What they know:**
- Source-based workflow (`supabase/db/` → `db:rebuild` → `test db`)
- This project's schema structure
- Game logic ownership (ALL business logic)

**What they DON'T know:**
- Frontend code or patterns
- Vue/TypeScript specifics

**Tools:** bash (db commands), edit, write, read, sequential-thinking

### @frontend-expert

**Invoke for:**
- Vue 3 component creation/modification
- shadcn-vue UI implementation
- Pinia store updates
- Composable creation

**What they know:**
- Vue 3 Composition API
- shadcn-vue components
- How to call `supabase.rpc()`

**What they DON'T know:**
- Database internals or SQL
- Game logic (will refuse to implement)

**Tools:** bash (lint/test), edit, write, read

### @code-reviewer

**Invoke for:**
- Post-implementation review
- Architecture compliance check
- Security audit

**What they do:**
- Review and report findings
- Do NOT make changes

**Tools:** read, glob, grep, list, sequential-thinking

### @researcher

**Invoke for:**
- Technical questions
- Comparing approaches
- Documentation exploration

**What they do:**
- Investigate and synthesize
- Advise on approaches
- Do NOT implement

**Tools:** read, glob, grep, webfetch, exa search, sequential-thinking

### @player

**Invoke for:**
- Manual gameplay testing
- UX verification

**Tools:** chrome-devtools only (no code access)

## Task Scoping

When dispatching a subagent, provide:

```
TASK: [One clear sentence]

CONTEXT:
- Relevant files: [list paths]
- Current state: [what exists]
- Expected outcome: [what should exist after]

CONSTRAINTS:
- [Any specific limitations]
- [Reference to spec if applicable]
```

**Good task:**
```
TASK: Add RLS policy for leaderboard_entries table that restricts 
reads to authenticated users.

CONTEXT:
- Table defined in: supabase/db/schema/leaderboard.sql
- Similar policy exists: supabase/db/schema/game_sessions.sql:45-52
- Expected: Only auth.uid() can read their own entries

CONSTRAINTS:
- Follow existing RLS patterns
- Add pgTAP test
```

**Bad task:**
```
TASK: Fix the leaderboard security
```

## Session Management

### Dispatching (Fresh Session)

Use for independent, new tasks:

```
Dispatching @supabase-expert for Task 2.1
[Provide scoped task]
→ Note session_id when they respond
```

### Recalling (Same Session)

Use when:
- Code review found issues in their work
- Follow-up question about their implementation
- Bug found in code they wrote

```
Recalling @supabase-expert session [session_id]:
Code review found RLS policy missing auth.uid() check in 
get_leaderboard function. Please fix.
```

The agent has full context of what they did - no re-reading needed.

### When to Recall vs Fresh

| Situation | Action |
|-----------|--------|
| Review found bugs in their work | RECALL |
| Follow-up question | RECALL |
| New independent task | FRESH |
| Different domain (DB issue, but need frontend fix) | FRESH with correct agent |

## Handoff Patterns

### Pattern 1: Sequential Implementation

```
1. Dispatch @supabase-expert for DB tasks → session_id: A
2. Dispatch @frontend-expert for UI tasks → session_id: B
3. Dispatch @code-reviewer for review
4. If DB issues found → Recall session A
5. If UI issues found → Recall session B
```

### Pattern 2: Blocked Subagent

If a subagent reports they're blocked:

```
@frontend-expert: "I need a new RPC function get_stats() but it 
doesn't exist. Pausing until backend is ready."

Main agent action:
1. Note frontend session_id: B
2. Dispatch @supabase-expert to create function → session_id: C
3. After completion, recall frontend session B:
   "The get_stats() function is now available. Please continue."
```

### Pattern 3: Cross-Domain Issue

If one agent finds issues in another's domain:

```
@frontend-expert: "The RPC call to get_leaderboard returns wrong 
data format. Expected {entries: []}, got []."

Main agent action:
1. Pause frontend (note session B)
2. Dispatch @supabase-expert to fix function
3. After fix, recall frontend session B to continue
```

## Post-Subagent Verification

After subagent returns:

1. **Review output:**
   - Did they complete the task?
   - Any issues reported?

2. **Consider review:**
   - For significant changes → dispatch @code-reviewer
   
3. **Report to user:**
   - Summarize what was done
   - Don't just pass through raw output

4. **Collect feedback (optional but valuable):**
   - If the task was complex or the agent struggled, recall and ask:
   ```
   STOP - Don't read any more files. Just reflect briefly:
   - What context was missing that would have helped?
   - What would have made this task easier?
   - Any suggestions for improving the task description?
   ```
   - Use this feedback to improve future task scoping and context
   - Consider updating skills or documentation based on patterns

## Red Flags - STOP

If you:
- Dispatch without clear task scope
- Forget to note session_id
- Start fresh when you should recall
- Trust output without verification

STOP. Follow the workflow.

## Common Mistakes

| Mistake | Why Bad | Do Instead |
|---------|---------|------------|
| Vague task scope | Subagent will guess wrong | Be explicit about files and outcomes |
| Forgetting session_id | Can't recall for follow-ups | Always note it |
| Fresh session for fix | Agent loses context | Recall original session |
| Trusting blindly | Subagents have blind spots | Verify with @code-reviewer |

## Anti-Pattern: Rewriting OpenSpec as Instructions

When an openspec change exists, do NOT rewrite its content as task instructions.

**WRONG:**
```
TASK: Update trigger to fire on INSERT OR UPDATE...
Change RAISE WARNING to RAISE EXCEPTION in these files...
[rewrites entire tasks.md content]
```

**RIGHT:**
```
Implement the approved openspec change: fix-learning-trigger-errors

Run `openspec show fix-learning-trigger-errors` to see the proposal and tasks.
Load skills_openspec_apply and follow the task list.
Report back when complete.
```

**Why this matters:**
- OpenSpec is the single source of truth
- Rewriting bypasses the agent's skill loading
- You're doing the agent's work, treating them as code-execution proxies
- Any discrepancy between your rewrite and openspec causes confusion

**When to provide detailed context:**
- Ad-hoc tasks with no openspec change
- Quick fixes that don't warrant a full proposal
- Exploratory investigation tasks

**When to just point to openspec:**
- Approved changes with tasks.md
- Any task that has formal specification