English | 中文

Agent TaskGraph

Build native Codex and Claude Code Agent Teams with a shared outcome, roles, task relationships, a collaboration protocol, and a lifecycle.

Version: v0.8.0-beta.19 | License: Apache-2.0

Agent TaskGraph makes the current session the Lead, selects Solo, Delegation, or Team mode, and uses the host's native Agents to form the team, delegate work, coordinate Handoffs, review changes, and integrate the result. It runs no external orchestration service.

Start in 60 seconds

1. Install

git clone https://github.com/wu736139669/agent-taskgraph-protocol.git
cd agent-taskgraph-protocol
./install.sh
./install.sh --status

The same Skill is linked into:

• ~/.codex/skills/agent-taskgraph
• ~/.claude/skills/agent-taskgraph

2. Form a development team

Use agent-taskgraph to form a development team for this request.
Understand the project, define the shared outcome, roles, task dependencies,
write boundaries, and definition of done, then execute, hand off, review,
and integrate the work with the current host's native Agents.

The Lead produces a preview such as:

Mode and topology: Team / hub-and-spoke
Team outcome: ...
Members: Lead/Integrator, Backend Builder, Frontend Builder, Reviewer
Task relationships: T1 → T2/T3 → T4 Review → T5 Integration
Definition of done: integration tests, build, and risk checks pass

Invoking the Skill authorizes reasonable internal team formation. Only product decisions, permission expansion, or external side effects require additional confirmation.

Three modes

Mode	Use when	Shape
Solo	Small fix, one module, or sequential work	Current session
Delegation	Independent branches only need to report to the Lead	Lead + native Members
Team	Shared outcome, role collaboration, dependencies, or cross-module integration	Team Charter + Task Graph + lifecycle

Do not form a Team for appearances

Use Solo or Delegation when:

• the work cannot produce two independent, testable outputs
• Members would edit the same files concurrently
• coordination costs more than the work itself
• the request is too unclear to define Task Acceptance

Five parts of a Team

1. Outcome: the shared result, Non-goals, and Definition of done.
2. Roles: Lead, Integrator, and the Builders, Specialists, or Reviewers required by current Tasks.
3. Task Graph: Owner, Needs, Produces, Consumer, Writes, and Acceptance.
4. Collaboration: READY / BLOCKED / HANDOFF / REVIEW.
5. Lifecycle:

forming → briefing → executing → reviewing → integrating → complete/stopped

A default Team has two to four active Members including the Lead. No real Task means no corresponding Member.

Complete development example

references/development-team-example.md follows an asynchronous report-export feature through the full Team lifecycle:

T1 API contract
 ├─ T2 Backend implementation
 └─ T3 Frontend implementation
       ↓
T4 Independent review
       ↓
T5 Integration and team acceptance

The example includes the Team Charter, Roster, Task Graph, assignment contract, blocker, Handoff, Review, and completion report.

Native runtimes

Codex

A Codex Team defaults to hub-and-spoke: the main thread is Lead and native subagents/Agent threads are Members. The Lead manages dependencies through Task contracts, artifacts, and Handoffs without assuming peer messaging.

Claude Code

• Subagents: Lead-centered Teams.
• Agent Teams: only when Members must message each other, claim shared tasks, or coordinate decisions.

A logical Team is not synonymous with Claude Agent Teams. If Agent Teams are unavailable, subagents can still implement a Lead-centered Team.

Writes, Git, and permissions

• Parallel writers use separate worktrees or disjoint paths.
• A file, generated artifact, or migration state has one Owner at a time.
• Members do not commit, merge, rebase, tag, push, or release by default.
• The Integrator owns the final diff, conflict resolution, and team-level verification.
• Multi-agent execution never expands current permissions or authorization for external effects.

Optional durable state

Short Teams use native tasks and messages. For cross-session work, important dependencies, or an audit trail, run:

./init.sh /path/to/project

.agent-taskgraph/
├── PROJECT.md       # stable project facts
├── TEAM.md          # Team Charter and Roster
├── PLAN.md          # Task Graph and integration path
├── STATUS.md        # lifecycle, progress, and blockers
├── DECISIONS.md     # decisions that changed the team contract
├── tasks/<id>.md    # one Task contract and Handoff
└── archive/         # ended Team batches

Templates use stable English field names; values can use the project's primary language. Durable files restore team facts, not presumed-live Agents.

Optional GEP-lite experience layer

plugins/agent-gep-lite adds a local, optional experience loop to the existing Team workflow. It does not replace Solo, Delegation, Team, Task Acceptance, review, or integration. It adds two small hooks:

• Before dispatch: recall matching Gene/Capsule lessons and inject only distilled warnings or strategy points (at most five entries, three lines each).
• After acceptance: record both successful and failed outcomes, including verification evidence and failure-avoidance advice, so the next similar task starts with context instead of repeating the same mistake.

The practical benefit is a feedback loop: queue still tracks the current work, while lessons/ preserves reusable "how to do it" and "what not to do" guidance. Everything stays in local Markdown/JSON files, uses no external service or new dependency, and travels with the repository through Git.

Quick start for a task contract:

L=plugins/agent-gep-lite/skills/agent-gep-lite/scripts
"$L/lesson-recall.sh" --append .agent-taskgraph/tasks/<id>.md "并行开发; 冲突面; 验收命令"
"$L/lesson-record.sh" .agent-taskgraph/tasks/<id>.md verify.out --kind success --gene gene-accept-run-command

Read plugins/agent-gep-lite/README.md for the plugin overview and references/gep-lite.md for the SOP, decision upgrades, and experience-to-protocol loop.

Related workflow: define the Goal first

Goal Instruction Writer is a companion skill for previewing a bounded work loop and defining the outcome, acceptance evidence, checkpoints, and stop conditions before a longer task. Use that contract as input when choosing Solo, Delegation, or Team mode here.

Start in two minutes · Three prompts to try · Real workflow cases

Documentation map

Document	Read when
SKILL.md	Skill routing and non-negotiable constraints
references/team-protocol.md	Entering Team mode
references/native-runtimes.md	Creating or controlling native Members
references/development-team-example.md	Learning the complete end-to-end flow
plugins/agent-gep-lite/README.md	Using the optional experience layer
references/gep-lite.md	GEP-lite SOP, boundaries, and integration guidance
templates/	Persisting Team state across sessions

Validate and update

./tests/smoke.sh
python3 ./scripts/check-docs.py
./install.sh --check-update