GigiKit Guides

Multi-Agent Team Orchestration

GigiKit teams are groups of specialized agents working in parallel under a lead coordinator. The lead assigns tasks, resolves conflicts, and synthesizes outputs. Each teammate owns a distinct slice of the codebase and communicates via structured message passing.

Multi-Agent Team Architecture 
flowchart TD
Lead([Lead Agent]) —> T1[Implementer\nsrc/api/]
Lead —> T2[Implementer\nsrc/ui/]
Lead —> T3[Tester\ntests/]
Lead —> T4[Docs Manager\ndocs/]
T1 — TaskUpdate completed —> Lead
T2 — TaskUpdate completed —> Lead
T3 — TaskUpdate completed —> Lead
T4 — TaskUpdate completed —> Lead
T1 — SendMessage message —> T2
T2 — SendMessage message —> T1
style Lead fill:#4f46e5,color:#fff
style T1 fill:#0891b2,color:#fff
style T2 fill:#059669,color:#fff
style T3 fill:#d97706,color:#fff
style T4 fill:#7c3aed,color:#fff

Activating a Team

Teams are an optional layer on top of standard orchestration. Activate them by invoking the /gk:team skill. The skill reads team configuration from ~/.claude/teams/{team-name}/config.json to discover teammates and their roles.

Lead Agent Responsibilities

The lead:

  1. Breaks work into tasks with explicit file ownership globs
  2. Assigns tasks to teammates via TaskUpdate(owner: "alice")
  3. Monitors TaskList for completion and newly unblocked tasks
  4. Resolves file ownership conflicts by restructuring tasks or absorbing shared files
  5. Synthesizes teammate reports into a final completion message
  6. Issues shutdown requests when all tasks are complete

The lead never edits files directly unless a conflict forces it to absorb a contested file.

Teammate Responsibilities

Each teammate follows this loop:

  1. Run TaskList — claim the lowest-ID unblocked task
  2. Set task in_progress via TaskUpdate before touching any file
  3. Read the full task description via TaskGet to confirm file ownership bounds
  4. Implement, respecting ownership strictly
  5. Run TaskUpdate(status: "completed")
  6. Send an implementation report to the lead via SendMessage
  7. Return to step 1

SendMessage Protocol

ScenarioMessage typeRecipient
Routine update to leadmessagelead’s name
Coordination with a peermessagepeer’s name
Critical blocker for whole teambroadcast(all)
Shutdown acknowledgementshutdown_responselead’s name

Always use teammate names, not agent IDs. Names come from the team config and are used as the recipient field in SendMessage and the owner field in TaskUpdate.

Completed task-03: implemented JWT middleware in src/api/auth-middleware.ts.
Added token validation, refresh logic, and error responses for 401/403.
Tests pass. Docs impact: minor (updated API contract in docs/api-reference.md).
Ready for review.

Report Conventions

Every teammate saves a report to the shared reports path injected by the subagent-start hook:

  • Path: {CK_REPORTS_PATH} (falls back to plans/reports/)
  • Naming: {role}-{date}-{slug}.md — e.g. implementer-260305-auth-middleware.md
  • Content: files modified, tasks completed, docs impact verdict (none | minor | major)

Idle State

Agents go idle after sending a message. This is normal — idle means waiting, not disconnected. A new message from the lead or a peer wakes the agent. Do not interpret idle notifications as completion signals.