Skill: brianrwagner/agent-coordination (version 1.0.0)

--- name: agent-coordination description: This skill should be used when the user asks about "coordinate coding agents", "orchestrate agent team", "manage multiple agents", "vibekanban workflow", "task delegation to agents", "agent swarm coordination", "parallel agent execution", "chief of staff mode", "cos mode", "you're my cos", "your my cos", "act as cos", "be my cos", "you are my chief of staff", "create tasks for agents", "dispatch agents", or needs guidance on coordinating autonomous coding agents, task breakdown strategies, or multi-agent workflow patterns. --- # Agent Coordination Coordinate teams of autonomous coding agents using VibeKanban task management. **Note:** "cos" = "chief of staff". When user says "you're my cos", operate as Chief of Staff. ## CoS Mode Activation **STATE CHANGE**: When user declares you as CoS, this mode **persists for the entire conversation**. ### Immediate Actions 1. Acknowledge the CoS role 2. Verify VibeKanban MCP tools available 3. ALL subsequent requests become task delegations 4. Never revert to execution mode unless explicitly told ### The Golden Rule **"I want to X" → Create a task, do NOT do X yourself.** Even direct commands after CoS declaration get delegated: ```text User: "you're my cos. remove all lovable mentions" WRONG: "Let me search for lovable mentions..." [executes directly] RIGHT: "I'll create a task for this. Which project should I use?" ``` ## Role Definition | Role | Does | Does NOT | | --------------------- | ------------------------------ | --------------------- | | **Coordinator (You)** | Plan, delegate, track, monitor | Write code, implement | | **Executor (Agent)** | Implement assigned tasks | Plan or delegate | ### What You CAN Do - Check status via `git status`, inspect logs - Monitor task progress and agent outputs - Verify completion and outcomes - Read code for context (not to implement) ### What You Do NOT Do - Investigate codebases (delegate it) - Implement features or fixes (delegate it) - Write or Edit code files **Exception**: Full autonomy in [REDACTED_SECRET]. ## Two-Tier Delegation Pattern Use model tiers for cost-effective execution: | Tier | Model | Purpose | | -------------- | ------------ | --------------------------------------- | | Investigation | Opus/Sonnet | Explore, quantify, create detailed plan | | Implementation | Haiku/Sonnet | Follow the plan, execute, report | **Flow:** 1. Create investigation task → expensive model explores, estimates, plans 2. Once plan ready → create implementation task for cheaper model 3. Implementation follows the detailed plan See `references/delegation-patterns.md` for detailed examples. ## Task Creation ### Title Format ```text Bug: | Feature: | Chore: | Investigate: + brief description ``` ### Required Description Elements 1. **Problem/Goal** - What needs to be done 2. **Context** - 2-3 sentences for a fresh agent 3. **Acceptance Criteria** - How to verify completion 4. **Scope Boundaries** - What is NOT included ### Quick Template ```markdown ## Problem [Clear description] ## Context [Essential background for fresh agent] ## Acceptance Criteria - [ ] Criterion 1 - [ ] Criterion 2 ## Out of Scope - [What NOT to do] ``` See `examples/task-templates.md` for full templates. ## VibeKanban Workflow ### Starting Work ```text 1. mcp__vibe_kanban__list_projects() # Find project 2. mcp__vibe_kanban__list_repos(project_id) # Get repo info 3. mcp__vibe_kanban__create_task(...) # Create task 4. mcp__vibe_kanban__start_workspace_session( # Launch agent task_id, executor="CLAUDE_CODE", repos=[{repo_id, base_branch}]) ``` ### Task Status Flow ```text todo → inprogress → inreview → done ↘ cancelled ``` ### Status Reporting ```markdown | Task | Status | Notes | | ------------------ | ---------- | ------------------- | | Bug: Login | inprogress | Agent investigating | | Feature: Dark mode | todo | Ready | **Active**: 2 | **Done**: 5 ``` ## Monitoring ### CI Status Monitoring ```bash # Quick check scripts/monitor-pr-ci.py 123 -R owner/repo # Wait for completion scripts/monitor-pr-ci.py 123 --wait --timeout 600 ``` ### Escalation Triggers - Agent blocked >30 minutes - Decision outside agent scope - Security or breaking change concerns ## Anti-Patterns ### Coordinator Anti-Patterns - Writing code instead of delegating - Creating tasks without acceptance criteria - Assigning blocked tasks ### Task Anti-Patterns - Vague: "Fix the bug" - No context: Missing links/background - Scope creep: Adding requirements mid-task - Too large: Should be broken down ## Additional Resources ### Reference Files - **`references/vibekanban-api.md`** - Complete MCP tool reference - **`references/cos-workflow.md`** - Detailed workflow procedures - **`references/delegation-patterns.md`** - Two-tier pattern examples ### Scripts - **`scripts/monitor-pr-ci.py`** - Token-efficient CI monitoring ### Examples - **`examples/task-templates.md`** - Full task description templates

path: examples/task-templates.md
content: # Task Templates for Agent Coordination

Use these templates when creating tasks for autonomous coding agents.

---

## Bug Fix Task

```markdown
# Bug: [Brief description]

## Problem

[Clear description of what is broken]

- Expected behavior: [What should happen]
- Actual behavior: [What currently happens]
- Impact: [Users affected, frequency]

## Context

- First reported: [Date/source]
- Related issues: #123, #456
- Affected files: `src/components/Login.tsx`

## Reproduction Steps

1. [Step 1]
2. [Step 2]
3. [Step 3]

## Investigation Guidance

1. Check [specific file/function]
2. Look for [specific pattern/error]
3. Verify [specific condition]

## Acceptance Criteria

- [ ] Bug no longer reproducible with repro steps
- [ ] Root cause identified and fixed
- [ ] Regression test added
- [ ] No new warnings/errors introduced
- [ ] CI passes

## Out of Scope

- Refactoring unrelated code
- Performance optimizations
- UI polish beyond the fix
```

---

## Feature Task

```markdown
# Feature: [Brief description]

## Overview

[What this feature does and why it's needed]

## User Story

As a [role], I want [capability] so that [benefit].

## Requirements

### Must Have

- [ ] Requirement 1
- [ ] Requirement 2

### Nice to Have

- [ ] Optional enhancement

## Technical Approach

1. [Implementation step 1]
2. [Implementation step 2]
3. [Implementation step 3]

## Files to Modify

- `src/components/NewFeature.tsx` - New component
- `src/api/endpoints.ts` - Add endpoint
- `src/types/index.ts` - Add types

## Dependencies

- Requires: [Any prerequisites]
- API endpoint: [If applicable]

## Acceptance Criteria

- [ ] Feature works as described
- [ ] Unit tests cover main paths
- [ ] Documentation updated
- [ ] No performance regression
- [ ] CI passes

## Out of Scope

- [Explicitly list what NOT to do]
```

---

## Chore/Refactor Task

```markdown
# Chore: [Brief description]

## Motivation

[Why this maintenance work is needed]

- Technical debt addressed: [Specific debt]
- Benefit: [Improvement gained]

## Scope

### Include

- [File/module 1]
- [File/module 2]

### Exclude

- [What not to touch]

## Approach

1. [Step 1]
2. [Step 2]
3. [Step 3]

## Verification

- [ ] Existing tests pass
- [ ] No behavior changes
- [ ] Code review approved
- [ ] CI passes

## Risks

- [Potential risk and mitigation]
```

---

## Investigation Task

```markdown
# Investigate: [Brief description]

## Question

[What needs to be understood/discovered]

## Context

- Triggered by: [Issue/observation]
- Deadline: [If time-sensitive]

## Investigation Areas

1. [Area to investigate]
2. [Area to investigate]
3. [Area to investigate]

## Expected Deliverables

- [ ] Summary of findings
- [ ] Root cause identified (if applicable)
- [ ] Recommended next steps
- [ ] Follow-up tasks created (if needed)

## Resources

- Relevant logs: [Location]
- Related code: [Files]
- Documentation: [Links]
```

---

## Migration Task

```markdown
# Migration: [Brief description]

## Overview

[What is being migrated and why]

## Current State

- Version/system: [Current]
- Issues: [Problems with current]

## Target State

- Version/system: [Target]
- Benefits: [Improvements]

## Migration Steps

1. [ ] [Step 1]
2. [ ] [Step 2]
3. [ ] [Step 3]

## Rollback Plan

1. [How to revert if needed]

## Verification

- [ ] All functionality works post-migration
- [ ] Performance acceptable
- [ ] No data loss
- [ ] Rollback tested

## Timeline

- Start: [Date]
- Expected completion: [Date]
- Rollback window: [Duration]
```

---

## Quick Reference: Task Title Prefixes

| Prefix         | Use When                             |
| -------------- | ------------------------------------ |
| `Bug:`         | Something is broken                  |
| `Feature:`     | New capability                       |
| `Chore:`       | Maintenance, deps, config            |
| `Refactor:`    | Code improvement, no behavior change |
| `Docs:`        | Documentation only                   |
| `Test:`        | Test coverage improvement            |
| `Investigate:` | Research, discovery                  |
| `Migration:`   | Version/system upgrade               |

---

## Tips for Writing Agent-Friendly Tasks

### Be Specific

```text
Bad:  "Fix the login bug"
Good: "Bug: Login button unresponsive on Safari iOS - check touch event handlers in LoginButton.tsx"
```

### Include File Paths

```text
Bad:  "Update the API"
Good: "Feature: Add /api/users/export endpoint in src/routes/users.ts"
```

### Define Done Clearly

```text
Bad:  "Make it work"
Good: "Acceptance Criteria:
       - [ ] Endpoint returns CSV
       - [ ] Auth required
       - [ ] Rate limited to 10/min
       - [ ] Test coverage >80%"
```

### Set Boundaries

```text
Bad:  "Improve the codebase"
Good: "Chore: Extract validation logic from UserForm.tsx into useValidation hook
       Out of scope: Other forms, UI changes, new validations"
```


path: references/cos-workflow.md
content: # Chief of Staff Workflow

Procedure for acting as Chief of Staff to coordinate agent teams via VibeKanban.

## Role Definition

The Chief of Staff is a **coordinator**, not an executor:

### Responsibilities

1. Clarify requirements with the user
2. Plan and break down work into actionable tasks
3. Create tickets on VibeKanban for agents
4. Track progress and report status
5. Coordinate the agent team

### Non-Responsibilities

- Do NOT write code
- Do NOT fix bugs directly
- Do NOT execute tasks—agents do that
- Thread is for communication, clarification, and planning only

## Startup Sequence

### 1. List Projects

```python
mcp__vibe_kanban__list_projects()
```

### 2. Select Project

- Match by project name if provided
- Infer from working directory
- Ask user if ambiguous

### 3. Show Current Backlog

```python
mcp__vibe_kanban__list_tasks(project_id=<project_id>)
```

### 4. Report Ready

Confirm setup complete and ready for instructions.

## Task Creation

When user describes a bug, feature, or chore:

### 1. Create Task

```python
mcp__vibe_kanban__create_task(
    project_id=<project_id>,
    title="Bug: Login button broken on mobile",
    description="""
## Problem
Login button unresponsive on mobile Safari.

## Context
- Reported by users
- Works on Chrome mobile

## Investigation Steps
1. Check touch event handlers
2. Verify CSS pointer events
3. Test on Safari dev tools

## Acceptance Criteria
- [ ] Works on Safari iOS 17+
- [ ] No regression on other browsers
"""
)
```

Title prefixes:

- `Bug:` - Something broken
- `Feature:` - New functionality
- `Chore:` - Maintenance task

### 2. Assign Agent

```python
# Get repo info
repos = mcp__vibe_kanban__list_repos(project_id=<project_id>)

# Start agent
mcp__vibe_kanban__start_workspace_session(
    task_id=<task_id>,
    executor="CLAUDE_CODE",
    repos=[{"repo_id": repos[0]["id"], "base_branch": "main"}]
)
```

If repo config missing, inform user about blocker.

### 3. Always Try to Assign

Don't just create tasks—dispatch agents to work on them.

## Backlog Display

**Always fetch fresh data before displaying:**

```python
tasks = mcp__vibe_kanban__list_tasks(project_id=<project_id>)
```

Display as table:

| Task               | Status     | Agent   | Notes         |
| ------------------ | ---------- | ------- | ------------- |
| Bug: Login mobile  | inprogress | Agent-1 | Investigating |
| Feature: Dark mode | todo       | -       | Ready         |

## Task Statuses

| Status       | Meaning             |
| ------------ | ------------------- |
| `todo`       | Not started         |
| `inprogress` | Agent working on it |
| `inreview`   | Ready for review    |
| `done`       | Completed           |
| `cancelled`  | Dropped             |

## Communication Style

- Be concise and status-focused
- Use tables for backlog display
- Summarize after each action
- Proactively report blockers
- Ask clarifying questions when ambiguous

## Example Flow

```text
User: "the login button is broken on mobile"

CoS Response:
1. Ask clarifying questions (what's broken? error? browser?)
2. Create task: "Bug: Login button broken on mobile"
3. Add detailed description with investigation steps
4. Attempt to assign agent via start_workspace_session
5. Report task created and assignment status
```

## Escalation

Escalate when:

- Agent blocked >30 minutes
- Requires decision outside agent scope
- Conflicting requirements discovered
- Security or breaking change concerns

Format:

```markdown
## Escalation: [Brief title]

**Task**: #123 - Feature X
**Agent**: Agent-1
**Blocker**: [Description]
**Options**:

1. Option A - [pros/cons]
2. Option B - [pros/cons]
   **Recommendation**: Option A because [reason]
```


path: references/delegation-patterns.md
content: # Delegation Patterns

Detailed patterns for delegating work to coding agents using a two-tier model approach.

## Two-Tier Delegation Model

### Why Two Tiers?

Different tasks require different capabilities:

| Task Type      | Model Needed | Cost   | Example                             |
| -------------- | ------------ | ------ | ----------------------------------- |
| Investigation  | Opus/Sonnet  | Higher | "Find all usages of deprecated API" |
| Implementation | Haiku/Sonnet | Lower  | "Replace X with Y in these 5 files" |

**Key insight**: Expensive models do thinking; cheap models do execution with clear instructions.

### Tier 1: Investigation Tasks

**Purpose**: Explore, quantify, plan

**Characteristics**:

- Requires understanding complex codebases
- Needs judgment and decision-making
- Produces a detailed plan for execution
- Uses Opus or Sonnet model

**Task Template**:

```markdown
## Investigate: [Brief description]

### Question

[What needs to be understood/discovered]

### Context

[Background information]

### Investigation Areas

1. [Area to explore]
2. [Area to explore]

### Expected Deliverables

- [ ] Summary of findings with file paths
- [ ] Quantified scope (e.g., "12 files, ~200 lines to change")
- [ ] Poker planning estimate (S/M/L/XL)
- [ ] Detailed implementation plan for executor
- [ ] Follow-up task descriptions ready to create

### Output Format

Provide implementation plan as markdown that can be directly used as a task description for the implementation tier.
```

### Tier 2: Implementation Tasks

**Purpose**: Execute a clear, pre-defined plan

**Characteristics**:

- Clear instructions from investigation phase
- Minimal decision-making required
- Follows step-by-step plan
- Uses Haiku or Sonnet model

**Task Template**:

```markdown
## Implement: [Brief description]

### Plan

[Paste the detailed plan from investigation]

### Steps

1. [ ] Step 1 with specific file/function
2. [ ] Step 2 with specific changes
3. [ ] Step 3...

### Verification

- [ ] Tests pass
- [ ] No new warnings
- [ ] CI green

### Report

When done, summarize:

- What worked as planned
- What required adjustment
- Any follow-up needed
```

## Complete Two-Tier Example

### User Request

"Remove all references to the old 'lovable' branding"

### Tier 1: Investigation Task

````markdown
## Investigate: Scope of lovable branding removal

### Question

Quantify all "lovable" references that need removal or replacement.

### Context

We're rebranding. Need to find all mentions of "lovable" in code, docs, and config.

### Investigation Areas

1. Source code (strings, comments, variable names)
2. Documentation files
3. Configuration and environment files
4. Test fixtures and mocks
5. CI/CD configurations

### Expected Deliverables

- [ ] Complete list of files with "lovable" references
- [ ] Count of changes per file
- [ ] Classification (code vs docs vs config)
- [ ] Risk assessment (breaking changes?)
- [ ] Implementation plan for executor

### Tools to Use

```bash
grep -r "lovable" --include="*.{ts,js,tsx,jsx,md,json,yaml,yml}"
```

**Investigation Output** (what the agent produces):

```markdown
## Findings: Lovable Branding Removal

### Summary

- **Total files**: 23
- **Total occurrences**: 67
- **Estimate**: Medium (2-4 hours)

### Breakdown

| Category   | Files | Occurrences | Risk   |
| ---------- | ----- | ----------- | ------ |
| UI strings | 8     | 24          | Low    |
| Comments   | 6     | 18          | None   |
| Docs       | 5     | 15          | Low    |
| Config     | 4     | 10          | Medium |

### High-Risk Items

- `config/branding.ts` - exports BRAND_NAME constant used in 12 places
- `.env.example` - LOVABLE_API_KEY needs renaming

### Implementation Plan

**Phase 1: Config (do first)**

1. Update `config/branding.ts`: change BRAND_NAME export
2. Rename env var in `.env.example` and `.env.local`

**Phase 2: UI Strings**
Files: [list of 8 files with line numbers]

**Phase 3: Documentation**
Files: [list of 5 files]

**Phase 4: Comments** (optional, low priority)
Files: [list of 6 files]
```

### Tier 2: Implementation Task

```markdown
## Implement: Remove lovable branding - Phase 1 & 2

### Plan

From investigation task #123.

### Phase 1: Config

1. `config/branding.ts:5` - Change `BRAND_NAME = "lovable"` to `BRAND_NAME = "newbrand"`
2. `.env.example:12` - Rename `LOVABLE_API_KEY` to `NEWBRAND_API_KEY`
3. `.env.local` - Same rename

### Phase 2: UI Strings

1. `src/components/Header.tsx:23` - Update welcome message
2. `src/components/Footer.tsx:8` - Update copyright
   [... specific file:line for each change ...]

### Verification

- [ ] `npm run build` succeeds
- [ ] `npm test` passes
- [ ] `grep -r "lovable"` returns only Phase 3/4 items

### Out of Scope

- Documentation (Phase 3 - separate task)
- Comments (Phase 4 - optional)
```

## Parallel vs Sequential Delegation

### Safe to Parallelize

Tasks can run simultaneously when:

- Different directories
- No shared dependencies
- Independent features

```text
Task A: Update /src/auth/*
Task B: Update /src/billing/*
→ Safe to run in parallel
```

### Must Be Sequential

Tasks must wait when:

- Same files
- One depends on other's output
- Shared state/config

```text
Task A: Refactor config system
Task B: Update features using config
→ B waits for A to complete
```

## Handling Task Results

### On Success

1. Update task status to `done`
2. Check for follow-up tasks
3. Verify no regression

### On Partial Success

1. Keep task `inprogress`
2. Create follow-up task for remaining work
3. Document what completed

### On Failure

1. Keep task `inprogress`
2. Analyze failure reason
3. Either:
   - Adjust plan and retry
   - Escalate to user
   - Create investigation task to understand issue

## Cost Optimization Tips

1. **Batch similar changes**: One task for "update all imports" vs individual tasks
2. **Front-load investigation**: Thorough Tier 1 prevents Tier 2 rework
3. **Limit scope**: Smaller tasks = lower risk of expensive failures
4. **Use Haiku for**: Formatting, simple replacements, test running
5. **Use Opus for**: Architecture decisions, complex refactoring, debugging
````


path: references/vibekanban-api.md
content: # VibeKanban MCP API Reference

VibeKanban provides task and project management through MCP tools.

## Core Tools

### list_projects

List all available projects.

**Parameters**: None

**Response**:

```json
[
  {
    "id": "uuid",
    "name": "project-name",
    "description": "Project description",
    "created_at": "2025-01-01T00:00:00Z"
  }
]
```

**Usage**:

```text
mcp__vibe_kanban__list_projects()
```

---

### list_tasks

List tasks in a project with optional filtering.

**Parameters**:

| Parameter  | Type   | Required | Description                                         |
| ---------- | ------ | -------- | --------------------------------------------------- |
| project_id | UUID   | Yes      | Project to list tasks from                          |
| status     | string | No       | Filter: todo, inprogress, inreview, done, cancelled |
| limit      | int    | No       | Max tasks to return (default: 50)                   |

**Response**:

```json
[
  {
    "id": "uuid",
    "title": "Task title",
    "description": "Task description",
    "status": "todo",
    "created_at": "2025-01-01T00:00:00Z",
    "updated_at": "2025-01-01T00:00:00Z"
  }
]
```

**Usage**:

```text
mcp__vibe_kanban__list_tasks(project_id="<uuid>")
mcp__vibe_kanban__list_tasks(project_id="<uuid>", status="inprogress")
```

---

### get_task

Get detailed information about a specific task.

**Parameters**:

| Parameter | Type | Required | Description      |
| --------- | ---- | -------- | ---------------- |
| task_id   | UUID | Yes      | Task to retrieve |

**Response**:

```json
{
  "id": "uuid",
  "title": "Task title",
  "description": "Full task description with details",
  "status": "inprogress",
  "created_at": "2025-01-01T00:00:00Z",
  "updated_at": "2025-01-01T00:00:00Z",
  "attempts": [
    {
      "id": "uuid",
      "executor": "CLAUDE_CODE",
      "status": "running",
      "started_at": "2025-01-01T00:00:00Z"
    }
  ]
}
```

**Usage**:

```text
mcp__vibe_kanban__get_task(task_id="<uuid>")
```

---

### create_task

Create a new task in a project.

**Parameters**:

| Parameter   | Type   | Required | Description               |
| ----------- | ------ | -------- | ------------------------- |
| project_id  | UUID   | Yes      | Project to create task in |
| title       | string | Yes      | Task title                |
| description | string | No       | Task description          |

**Response**:

```json
{
  "id": "uuid",
  "title": "Task title",
  "description": "Task description",
  "status": "todo",
  "created_at": "2025-01-01T00:00:00Z"
}
```

**Usage**:

```text
mcp__vibe_kanban__create_task(
  project_id="<uuid>",
  title="Bug: Fix login on mobile",
  description="## Problem\nLogin button unresponsive...\n\n## Acceptance Criteria\n- [ ] Works on Safari"
)
```

---

### update_task

Update an existing task's title, description, or status.

**Parameters**:

| Parameter   | Type   | Required | Description                                             |
| ----------- | ------ | -------- | ------------------------------------------------------- |
| task_id     | UUID   | Yes      | Task to update                                          |
| title       | string | No       | New title                                               |
| description | string | No       | New description                                         |
| status      | string | No       | New status: todo, inprogress, inreview, done, cancelled |

**Response**:

```json
{
  "id": "uuid",
  "title": "Updated title",
  "status": "inprogress",
  "updated_at": "2025-01-01T00:00:00Z"
}
```

**Usage**:

```text
mcp__vibe_kanban__update_task(task_id="<uuid>", status="done")
mcp__vibe_kanban__update_task(task_id="<uuid>", title="New title", description="Updated desc")
```

---

### delete_task

Delete a task from a project.

**Parameters**:

| Parameter | Type | Required | Description    |
| --------- | ---- | -------- | -------------- |
| task_id   | UUID | Yes      | Task to delete |

**Response**:

```json
{
  "success": true
}
```

**Usage**:

```text
mcp__vibe_kanban__delete_task(task_id="<uuid>")
```

---

### list_repos

List repositories associated with a project.

**Parameters**:

| Parameter  | Type | Required | Description                |
| ---------- | ---- | -------- | -------------------------- |
| project_id | UUID | Yes      | Project to list repos from |

**Response**:

```json
[
  {
    "id": "uuid",
    "name": "repo-name",
    "url": "https://github.com/org/repo",
    "default_branch": "main"
  }
]
```

**Usage**:

```text
mcp__vibe_kanban__list_repos(project_id="<uuid>")
```

---

### start_workspace_session

Start working on a task by creating and launching a new workspace session.

**Parameters**:

| Parameter | Type   | Required | Description                                                    |
| --------- | ------ | -------- | -------------------------------------------------------------- |
| task_id   | UUID   | Yes      | Task to work on                                                |
| executor  | string | Yes      | Agent type: CLAUDE_CODE, CODEX, GEMINI, CURSOR_AGENT, OPENCODE |
| repos     | array  | Yes      | Repo configurations: [{repo_id, base_branch}]                  |
| variant   | string | No       | Executor variant if needed                                     |

**Response**:

```json
{
  "id": "uuid",
  "task_id": "uuid",
  "executor": "CLAUDE_CODE",
  "status": "running",
  "started_at": "2025-01-01T00:00:00Z"
}
```

**Usage**:

```text
mcp__vibe_kanban__start_workspace_session(
  task_id="<task-uuid>",
  executor="CLAUDE_CODE",
  repos=[{"repo_id": "<repo-uuid>", "base_branch": "main"}]
)
```

## Common Workflows

### Initialize Coordination Session

```python
# 1. List projects
projects = mcp__vibe_kanban__list_projects()

# 2. Select project (by name or let user choose)
project_id = projects[0]["id"]

# 3. Get repos for the project
repos = mcp__vibe_kanban__list_repos(project_id=project_id)

# 4. List current backlog
tasks = mcp__vibe_kanban__list_tasks(project_id=project_id)
```

### Create and Assign Task

```python
# 1. Create task
task = mcp__vibe_kanban__create_task(
    project_id=project_id,
    title="Bug: Fix mobile login",
    description="..."
)

# 2. Get repo info
repos = mcp__vibe_kanban__list_repos(project_id=project_id)

# 3. Start agent
attempt = mcp__vibe_kanban__start_workspace_session(
    task_id=task["id"],
    executor="CLAUDE_CODE",
    repos=[{"repo_id": repos[0]["id"], "base_branch": "main"}]
)
```

### Monitor Progress

```python
# Get in-progress tasks
active = mcp__vibe_kanban__list_tasks(
    project_id=project_id,
    status="inprogress"
)

# Check specific task
for task in active:
    details = mcp__vibe_kanban__get_task(task_id=task["id"])
    print(f"{details['title']}: {details['status']}")
    if details.get('attempts'):
        print(f"  Agent: {details['attempts'][-1]['executor']}")
```

### Complete Task

```python
# Mark task as done
mcp__vibe_kanban__update_task(
    task_id=task_id,
    status="done"
)
```

## Task Status Flow

```text
                    ┌─────────────┐
                    │    todo     │
                    └──────┬──────┘
                           │ start_workspace_session
                           ▼
                    ┌─────────────┐
           ┌────────│ inprogress  │────────┐
           │        └──────┬──────┘        │
           │               │               │
           │ blocked       │ PR created    │ cancelled
           │               ▼               │
           │        ┌─────────────┐        │
           │        │  inreview   │        │
           │        └──────┬──────┘        │
           │               │               │
           │               │ merged        │
           │               ▼               ▼
           │        ┌─────────────┐  ┌───────────┐
           └───────▶│    done     │  │ cancelled │
                    └─────────────┘  └───────────┘
```

## Error Handling

### Common Errors

| Error               | Cause                  | Resolution                         |
| ------------------- | ---------------------- | ---------------------------------- |
| Project not found   | Invalid project_id     | Use list_projects to get valid IDs |
| Task not found      | Invalid task_id        | Use list_tasks to get valid IDs    |
| Repo not configured | Missing repo setup     | Contact project admin              |
| Agent unavailable   | Executor not available | Try different executor             |

### Retry Pattern

```python
import time

def start_with_retry(task_id, executor, repos, max_attempts=3):
    for attempt in range(max_attempts):
        try:
            return mcp__vibe_kanban__start_workspace_session(
                task_id=task_id,
                executor=executor,
                repos=repos
            )
        except Exception as e:
            if attempt < max_attempts - 1:
                time.sleep(2 ** attempt)  # Exponential backoff
            else:
                raise
```


path: scripts/monitor-pr-ci.py
content: #!/usr/bin/env -S uv run --script
# /// script
# requires-python = ">=3.11"
# dependencies = []
# ///
"""
PR CI Monitor - Efficiently track CI status for a pull request.

Usage:
    monitor-pr-ci.py <pr> [--repo OWNER/REPO] [--wait] [--timeout SECONDS] [--quiet]

Examples:
    monitor-pr-ci.py 123                          # Check PR #123 in current repo
    monitor-pr-ci.py 123 --wait                   # Wait for CI to complete
    monitor-pr-ci.py 123 --wait --timeout 600    # Wait up to 10 minutes
    monitor-pr-ci.py https://github.com/org/repo/pull/123 --wait

Output is minimal unless CI fails - then shows error details.
"""
from __future__ import annotations

import argparse
import json
import re
import subprocess
import sys
import time
from dataclasses import dataclass
from enum import Enum


class Status(Enum):
    PENDING = "pending"
    SUCCESS = "success"
    FAILURE = "failure"
    CANCELLED = "cancelled"
    UNKNOWN = "unknown"


@dataclass
class CheckRun:
    name: str
    status: str  # queued, in_progress, completed
    conclusion: str | None  # success, failure, cancelled, skipped, etc.
    url: str

    @property
    def state(self) -> Status:
        if self.status != "completed":
            return Status.PENDING
        if self.conclusion == "success" or self.conclusion == "skipped":
            return Status.SUCCESS
        if self.conclusion == "failure":
            return Status.FAILURE
        if self.conclusion == "cancelled":
            return Status.CANCELLED
        return Status.UNKNOWN


def run_gh(args: list[str]) -> tuple[int, str, str]:
    """Run a gh CLI command."""
    try:
        result = subprocess.run(
            ["gh"] + args,
            capture_output=True,
            text=True,
            timeout=30,
        )
        return result.returncode, result.stdout, result.stderr
    except FileNotFoundError:
        return 1, "", "gh CLI not found. Install from https://cli.github.com/"
    except subprocess.TimeoutExpired:
        return 1, "", "Command timed out"


def parse_pr_arg(pr_arg: str) -> tuple[str | None, int]:
    """Parse PR argument - can be number or full URL."""
    # Full URL: https://github.com/owner/repo/pull/123
    url_match = re.match(r"https://github\.com/([^/]+/[^/]+)/pull/(\d+)", pr_arg)
    if url_match:
        return url_match.group(1), int(url_match.group(2))

    # Just a number
    if pr_arg.isdigit():
        return None, int(pr_arg)

    raise ValueError(f"Invalid PR argument: {pr_arg}. Use PR number or full URL.")


def get_check_runs(repo: str | None, pr_number: int) -> list[CheckRun]:
    """Get all check runs for a PR using gh pr checks."""
    repo_arg = ["-R", repo] if repo else []

    # Use gh pr checks - most reliable method
    code, stdout, stderr = run_gh(
        ["pr", "checks", str(pr_number), "--json", "name,state,link,workflow"]
        + repo_arg
    )
    if code != 0:
        # Check if it's just "no checks" which is not an error
        if "no checks" in stderr.lower():
            return []
        print(f"Error getting checks: {stderr}", file=sys.stderr)
        sys.exit(1)

    checks_data = json.loads(stdout) if stdout.strip() else []

    # Map gh state values to our status/conclusion model
    # gh states: SUCCESS, FAILURE, PENDING, SKIPPED, CANCELLED, etc.
    def parse_state(state: str) -> tuple[str, str | None]:
        state = state.upper()
        if state == "PENDING":
            return "in_progress", None
        elif state == "SUCCESS":
            return "completed", "success"
        elif state == "FAILURE":
            return "completed", "failure"
        elif state == "SKIPPED":
            return "completed", "skipped"
        elif state == "CANCELLED":
            return "completed", "cancelled"
        else:
            return "completed", state.lower()

    return [
        CheckRun(
            name=c.get("name", "unknown"),
            status=parse_state(c.get("state", ""))[0],
            conclusion=parse_state(c.get("state", ""))[1],
            url=c.get("link", ""),
        )
        for c in checks_data
    ]


def get_failed_job_logs(repo: str | None, check: CheckRun) -> str | None:
    """Get logs for a failed check run - just the error portion."""
    # Extract run ID from URL if possible
    # URL format: https://github.com/owner/repo/actions/runs/12345/job/67890
    run_match = re.search(r"/actions/runs/(\d+)", check.url)
    if not run_match:
        return None

    run_id = run_match.group(1)

    # Get failed job logs - gh run view shows summary with errors
    code, stdout, stderr = run_gh(
        ["run", "view", run_id, "--log-failed"] + (["-R", repo] if repo else [])
    )

    if code != 0 or not stdout.strip():
        # Try getting just the run summary
        code, stdout, stderr = run_gh(
            ["run", "view", run_id, "--json", "conclusion,jobs"]
            + (["-R", repo] if repo else [])
        )
        if code == 0:
            data = json.loads(stdout)
            failed_jobs = [
                j for j in data.get("jobs", []) if j.get("conclusion") == "failure"
            ]
            if failed_jobs:
                return f"Failed jobs: {', '.join(j.get('name', 'unknown') for j in failed_jobs)}"
        return None

    # Truncate logs if too long - keep last 100 lines (usually has the error)
    lines = stdout.strip().split("\n")
    if len(lines) > 100:
        return f"[... truncated {len(lines) - 100} lines ...]\n" + "\n".join(
            lines[-100:]
        )
    return stdout.strip()


def aggregate_status(checks: list[CheckRun]) -> Status:
    """Get overall CI status from all checks."""
    if not checks:
        return Status.UNKNOWN

    states = [c.state for c in checks]

    if Status.FAILURE in states:
        return Status.FAILURE
    if Status.CANCELLED in states:
        return Status.CANCELLED
    if Status.PENDING in states:
        return Status.PENDING
    if all(s == Status.SUCCESS for s in states):
        return Status.SUCCESS
    return Status.UNKNOWN


def print_status(checks: list[CheckRun], repo: str | None, verbose: bool = False):
    """Print CI status - minimal unless there are failures."""
    status = aggregate_status(checks)

    # Status emoji
    status_icons = {
        Status.PENDING: "⏳",
        Status.SUCCESS: "✅",
        Status.FAILURE: "❌",
        Status.CANCELLED: "🚫",
        Status.UNKNOWN: "❓",
    }

    # Count by status
    pending = sum(1 for c in checks if c.state == Status.PENDING)
    success = sum(1 for c in checks if c.state == Status.SUCCESS)
    failed = sum(1 for c in checks if c.state == Status.FAILURE)

    # One-line summary
    icon = status_icons.get(status, "❓")
    summary_parts = []
    if success:
        summary_parts.append(f"{success} passed")
    if pending:
        summary_parts.append(f"{pending} pending")
    if failed:
        summary_parts.append(f"{failed} failed")

    print(f"{icon} CI Status: {', '.join(summary_parts) or 'no checks'}")

    # If failed, show which checks failed and get logs
    if status == Status.FAILURE:
        print("\nFailed checks:")
        for check in checks:
            if check.state == Status.FAILURE:
                print(f"  ❌ {check.name}")
                if check.url:
                    print(f"     {check.url}")

                # Get error logs
                logs = get_failed_job_logs(repo, check)
                if logs:
                    print(f"\n  Error output for {check.name}:")
                    print("  " + "-" * 60)
                    for line in logs.split("\n"):
                        print(f"  {line}")
                    print("  " + "-" * 60)

    elif verbose and status == Status.PENDING:
        print("\nPending checks:")
        for check in checks:
            if check.state == Status.PENDING:
                print(f"  ⏳ {check.name}")


def main():
    parser = argparse.ArgumentParser(
        description="Monitor CI status for a GitHub PR",
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog=__doc__,
    )
    parser.add_argument("pr", help="PR number or full GitHub PR URL")
    parser.add_argument(
        "-R", "--repo", help="Repository (owner/repo), defaults to current"
    )
    parser.add_argument(
        "-w", "--wait", action="store_true", help="Wait for CI to complete"
    )
    parser.add_argument(
        "-t",
        "--timeout",
        type=int,
        default=1800,
        help="Max wait time in seconds (default: 1800)",
    )
    parser.add_argument(
        "-i",
        "--interval",
        type=int,
        default=30,
        help="Poll interval in seconds (default: 30)",
    )
    parser.add_argument(
        "-q", "--quiet", action="store_true", help="Minimal output while waiting"
    )

    args = parser.parse_args()

    try:
        repo_from_url, pr_number = parse_pr_arg(args.pr)
        repo = args.repo or repo_from_url
    except ValueError as e:
        print(f"Error: {e}", file=sys.stderr)
        sys.exit(1)

    start_time = time.time()
    last_status = None

    while True:
        checks = get_check_runs(repo, pr_number)
        status = aggregate_status(checks)

        if args.wait and status == Status.PENDING:
            elapsed = time.time() - start_time
            if elapsed >= args.timeout:
                print(f"⏰ Timeout after {args.timeout}s - CI still pending")
                print_status(checks, repo, verbose=True)
                sys.exit(2)

            # Only print if status changed or first iteration
            if not args.quiet or last_status != status:
                pending_count = sum(1 for c in checks if c.state == Status.PENDING)
                print(
                    f"⏳ Waiting... {pending_count} checks pending ({int(elapsed)}s elapsed)"
                )

            last_status = status
            time.sleep(args.interval)
            continue

        # Final status
        print_status(checks, repo)

        # Exit code based on status
        if status == Status.SUCCESS:
            sys.exit(0)
        elif status == Status.FAILURE:
            sys.exit(1)
        elif status == Status.PENDING:
            sys.exit(2)
        else:
            sys.exit(3)


if __name__ == "__main__":
    main()


path: skill-report.json
content: {
  "schema_version": "2.0",
  "meta": {
    "generated_at": "2026-01-10T12:15:23.255Z",
    "slug": "clementwalter-agent-coordination",
    "source_url": "https://github.com/ClementWalter/rookie-marketplace/tree/main/chief-of-staff/skills/agent-coordination",
    "source_ref": "main",
    "model": "claude",
    "analysis_version": "2.0.0",
    "source_type": "community",
    "content_hash": "8008377e1c81a587b4d0ac81e9b0979db27773c41b4531133d6b050835228e53",
    "tree_hash": "0469856ba51e71e357d444406e3ddf47dd4270d7a4c4fda804c56920f3dcc8bd"
  },
  "skill": {
    "name": "Agent Coordination",
    "description": "This skill should be used when the user asks about \"coordinate coding agents\", \"orchestrate agent team\", \"manage multiple agents\", \"vibekanban workflow\", \"task delegation to agents\", \"agent swarm coordination\", \"parallel agent execution\", \"chief of staff mode\", \"cos mode\", \"you're my cos\", \"your my cos\", \"act as cos\", \"be my cos\", \"you are my chief of staff\", \"create tasks for agents\", \"dispatch agents\", or needs guidance on coordinating autonomous coding agents, task breakdown strategies, or multi-agent workflow patterns.",
    "summary": "This skill should be used when the user asks about \"coordinate coding agents\", \"orchestrate agent te...",
    "icon": "🎯",
    "version": "1.0.0",
    "author": "ClementWalter",
    "license": "MIT",
    "category": "coding",
    "tags": [
      "multi-agent",
      "task-management",
      "coordination",
      "workflow"
    ],
    "supported_tools": [
      "claude",
      "claude-code"
    ],
    "risk_factors": [
      "scripts",
      "external_commands"
    ]
  },
  "security_audit": {
    "risk_level": "low",
    "is_blocked": false,
    "safe_to_publish": true,
    "summary": "Pure documentation skill with one utility script. The monitor-pr-ci.py script uses subprocess to run gh CLI commands for GitHub CI monitoring. All network operations go through the official GitHub CLI. No credential access, no file system enumeration, no suspicious endpoints.",
    "risk_factor_evidence": [
      {
        "factor": "scripts",
        "evidence": [
          {
            "file": "scripts/monitor-pr-ci.py",
            "line_start": 1,
            "line_end": 329
          }
        ]
      },
      {
        "factor": "external_commands",
        "evidence": [
          {
            "file": "scripts/monitor-pr-ci.py",
            "line_start": 60,
            "line_end": 73
          }
        ]
      }
    ],
    "critical_findings": [],
    "high_findings": [],
    "medium_findings": [],
    "low_findings": [],
    "dangerous_patterns": [],
    "files_scanned": 6,
    "total_lines": 1646,
    "audit_model": "claude",
    "audited_at": "2026-01-10T12:15:23.255Z"
  },
  "content": {
    "user_title": "Coordinate Agent Teams",
    "value_statement": "Managing multiple coding agents requires clear task definitions and coordination patterns. This skill provides Chief of Staff workflows, two-tier delegation patterns, and VibeKanban integration to orchestrate autonomous agent teams efficiently.",
    "seo_keywords": [
      "agent coordination",
      "multi-agent",
      "chief of staff",
      "cos mode",
      "vibekanban",
      "task delegation",
      "agent swarm",
      "parallel execution",
      "claude code",
      "autonomous agents"
    ],
    "actual_capabilities": [
      "Activate Chief of Staff mode for persistent agent coordination",
      "Create well-scoped tasks with acceptance criteria for agents",
      "Use two-tier delegation: investigation tasks for planning, implementation tasks for execution",
      "Track task status and agent progress through VibeKanban MCP tools",
      "Monitor CI status for pull requests using gh CLI",
      "Apply anti-patterns to avoid coordination failures"
    ],
    "limitations": [
      "Requires VibeKanban MCP server for full functionality",
      "Does not directly execute code or write files in user projects",
      "GitHub CI monitoring requires gh CLI installation",
      "Agent execution depends on configured executors and repositories"
    ],
    "use_cases": [
      {
        "target_user": "Engineering Leads",
        "title": "Orchestrate Agent Teams",
        "description": "Delegate complex features to specialized agents while maintaining visibility and quality control"
      },
      {
        "target_user": "DevOps Engineers",
        "title": "Monitor CI at Scale",
        "description": "Track CI status across multiple PRs with automated waiting and failure detection"
      },
      {
        "target_user": "Product Managers",
        "title": "Break Down Features",
        "description": "Transform feature requests into actionable tasks with clear scope and acceptance criteria"
      }
    ],
    "prompt_templates": [
      {
        "title": "Activate CoS Mode",
        "scenario": "Start coordination",
        "prompt": "Act as my Chief of Staff. I want you to coordinate coding agents for my project."
      },
      {
        "title": "Create Investigation Task",
        "scenario": "Scope complex work",
        "prompt": "Create an investigation task to understand the scope of refactoring our authentication system."
      },
      {
        "title": "Delegate Implementation",
        "scenario": "Assign implementation",
        "prompt": "Based on the investigation, create implementation tasks for the refactor. Use Haiku for simple changes and Sonnet for complex ones."
      },
      {
        "title": "Monitor Multiple PRs",
        "scenario": "Track CI status",
        "prompt": "Check the CI status for PR #456 and PR #458. Wait for both to complete and report results."
      }
    ],
    "output_examples": [
      {
        "input": "Act as my Chief of Staff. I need to add dark mode support to the app.",
        "output": [
          "✓ Chief of Staff mode activated. Ready for task delegation.",
          "Creating investigation task: 'Investigate: Dark mode implementation scope'",
          "Task #142 created with investigation tier. Agent exploring codebase...",
          "Once investigation completes, I'll create implementation tasks using the detailed plan."
        ]
      }
    ],
    "best_practices": [
      "Use the two-tier model: expensive models for investigation, cheap models for implementation",
      "Always include acceptance criteria and scope boundaries in task descriptions",
      "Verify VibeKanban MCP tools are available before starting coordination",
      "Track blocked agents and escalate decisions that exceed their scope"
    ],
    "anti_patterns": [
      "Writing code instead of delegating after CoS mode activation",
      "Creating vague tasks without context or acceptance criteria",
      "Assigning tasks that are too large or lack clear scope boundaries",
      "Ignoring agent blockers for more than 30 minutes"
    ],
    "faq": [
      {
        "question": "Which AI tools are supported?",
        "answer": "Claude and Claude Code are supported. The skill works with VibeKanban MCP tools for task management."
      },
      {
        "question": "What is the two-tier delegation model?",
        "answer": "Use Opus/Sonnet for investigation tasks that require planning, then Haiku/Sonnet for implementation tasks that follow the plan."
      },
      {
        "question": "How does CoS mode persist?",
        "answer": "Once activated, CoS mode persists for the entire conversation. All requests become task delegations until explicitly reverted."
      },
      {
        "question": "Is my data safe?",
        "answer": "Yes. The skill only accesses VibeKanban MCP tools and runs read-only gh CLI commands for CI monitoring."
      },
      {
        "question": "Why is gh CLI required?",
        "answer": "The monitor-pr-ci.py script uses gh CLI for efficient GitHub API access. No direct network calls are made."
      },
      {
        "question": "How is this different from regular Claude Code?",
        "answer": "As Chief of Staff, you delegate rather than execute. Create tasks instead of writing code directly."
      }
    ]
  },
  "file_structure": [
    {
      "name": "examples",
      "type": "dir",
      "path": "examples",
      "children": [
        {
          "name": "task-templates.md",
          "type": "file",
          "path": "examples/task-templates.md"
        }
      ]
    },
    {
      "name": "references",
      "type": "dir",
      "path": "references",
      "children": [
        {
          "name": "cos-workflow.md",
          "type": "file",
          "path": "references/cos-workflow.md"
        },
        {
          "name": "delegation-patterns.md",
          "type": "file",
          "path": "references/delegation-patterns.md"
        },
        {
          "name": "vibekanban-api.md",
          "type": "file",
          "path": "references/vibekanban-api.md"
        }
      ]
    },
    {
      "name": "scripts",
      "type": "dir",
      "path": "scripts",
      "children": [
        {
          "name": "monitor-pr-ci.py",
          "type": "file",
          "path": "scripts/monitor-pr-ci.py"
        }
      ]
    },
    {
      "name": "SKILL.md",
      "type": "file",
      "path": "SKILL.md"
    }
  ]
}


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)