Agent System Architecture

GigiKit operates on a hierarchical orchestrator pattern: a top-level Claude Code session acts as the coordinator, spawning specialized sub-agents for discrete phases of work. No single agent does everything — responsibility is distributed.

The Orchestrator Role

When you open Claude Code in a GigiKit project, CLAUDE.md loads and establishes the orchestrator role:

“Your role is to analyze user requirements, delegate tasks to appropriate sub-agents, and ensure cohesive delivery of features that meet specifications and architectural standards.”

The orchestrator never implements code directly for complex tasks. It reads requirements, activates the right skills, delegates via the Task tool, and synthesizes results.

Agent Communication Flow

GigiKit Agent Hierarchy

graph TD
User[“User Request”] —> Orch[“Orchestrator\n(Claude Code + CLAUDE.md)”]
Orch —> Researcher[“researcher\nResearch & analysis”]
Orch —> Planner[“planner\nPlan creation”]
Orch —> Dev[“fullstack-developer\nCode implementation”]
Orch —> Tester[“tester\nTest execution”]
Orch —> Reviewer[“code-reviewer\nCode quality review”]
Orch —> PM[“project-manager\nPlan sync & docs”]
Orch —> Git[“git-manager\nCommit & push”]
Researcher —>|“report”| Planner
Planner —>|“plan.md”| Dev
Dev —>|“code”| Tester
Tester —>|“results”| Reviewer
Reviewer —>|“feedback”| Dev
Reviewer —>|“approval”| PM

Sub-Agent Types

GigiKit ships with these built-in sub-agent roles:

Agent	Responsibility	Invoked By
`researcher`	Gather technical context, docs, codebase patterns	planner, cook
`planner`	Create structured phase plans in `./plans/`	cook, orchestrator
`fullstack-developer`	Implement code per phase file spec	cook, planner
`tester`	Run tests, analyze coverage, report failures	cook, orchestrator
`code-reviewer`	Review code quality, score, flag issues	cook, orchestrator
`debugger`	Investigate failures, trace root causes	orchestrator, tester
`project-manager`	Sync plan files, update `./docs/`	cook finalization
`docs-manager`	Update documentation after implementation	project-manager
`git-manager`	Stage, commit, push changes	cook finalization
`ui-ux-designer`	Handle frontend design work	cook (UI tasks)

Sequential vs. Parallel Execution

Sequential Chaining

Use when each agent’s output feeds the next:

Planning → Implementation → Testing → Review → Finalize

Each agent completes fully before the next begins. The orchestration protocol requires passing context explicitly — plan file paths, SHA ranges, report locations — between handoffs.

Parallel Execution

Use when tasks are independent and have no file conflicts:

Backend Dev  ──┐
Frontend Dev ──┼──► Merge → Test → Review
Docs Writer  ──┘

Delegation Context

When the orchestrator spawns a sub-agent via the Task tool, it must always include three pieces of context:

Work context: /absolute/path/to/project
Reports: /absolute/path/to/project/plans/reports/
Plans: /absolute/path/to/project/plans/

This ensures sub-agents write reports and plans to the correct locations, not to their own working directories.

Agent Teams (Advanced)

For large features requiring multiple parallel implementation sessions, activate the /gk:team skill. Teams use git worktrees to give each developer-agent a fully isolated branch, eliminating file conflicts entirely.

See Agent Teams for setup and coordination protocols.

Next Steps

The Planner Agent — how plans are created and structured
The Developer Agent — implementation rules and file ownership
The Tester Agent — test execution and quality gates