Context Files

AgentWeave uses a layered context system to give agents the right information at the right time.

File Hierarchy

Project Root/
├── CLAUDE.md / GEMINI.md / AGENTS.md             # Agent-specific context (auto-read)
└── .agentweave/
    ├── ai_context.md        # Your project DNA source
    ├── context/             # Per-agent context profiles injected by runners
    │   ├── claude.md
    │   └── kimi.md
    ├── protocol.md          # Collaboration protocol
    ├── roles.json           # Agent role assignments (auto-generated)
    ├── roles/               # Per-role behavioral guides
    │   ├── tech_lead.md
    │   ├── backend_dev.md
    │   └── ...
    └── shared/
        └── context.md       # Current focus (changes daily)

Canonical Runtime Context

.agentweave/context/<agent>.md is the canonical model-facing context for a declared agent. It is generated by agentweave sync-context and refreshed by agentweave activate.

It includes:

• a generated project operating profile from agentweave.yml and session state
• the declared team, runners, models, roles, and principal
• active quality gates and definition-of-done rules
• project-wide instructions
• the agent's assigned role contracts
• project context from .agentweave/ai_context.md when it is not still the placeholder template
• guidance for live session context in .agentweave/shared/context.md

Runner launch paths inject or reference this file where supported: Claude uses --append-system-prompt-file, Codex uses model_instructions_file, OpenCode uses --file, Codex MCP passes it as developer instructions, and Kimi pilot mode points its generated agent YAML at the same context file.

Root Bootstrap Files

Each agent reads a specific file at the project root on session start:

Agent	File	Notes
claude	CLAUDE.md	Claude Code bootstrap
gemini	GEMINI.md	Gemini CLI bootstrap
claude_proxy runners	CLAUDE.md	Proxy agents run through Claude Code
All others	AGENTS.md	Generic bootstrap

These root files are intentionally lightweight. They tell the model how to find .agentweave/context/<agent>.md and provide fallback instructions if the generated context is missing.

.agentweave/ai_context.md — Project DNA

This is the long-lived project knowledge source. Edit this file to define:

• Tech stack and versions
• Architecture overview
• Coding standards
• Testing requirements
• Deployment process

Template Structure

# AI Context — [Project Name]

## Tech Stack

- Language: Python 3.11
- Framework: FastAPI
- Database: PostgreSQL 15
...

## Architecture

[High-level overview with diagrams if helpful]

## Coding Standards

[Style guide, linting rules, etc.]

## Testing

[What to test, how to run tests, coverage requirements]

## Deployment

[How the project is built and deployed]

After editing, regenerate agent files:

agentweave sync-context

Running agentweave activate also regenerates context files as its final step.

If this file still contains the default [Replace with: ...] placeholders, AgentWeave does not silently present it as project facts. Generated context will warn that project context is incomplete instead.

.agentweave/protocol.md

Generated on init. Describes:

• Your session mode (hierarchical/peer/review)
• Principal and delegate agents
• MCP vs manual relay workflows

.agentweave/roles.json

Auto-generated role configuration. Contains:

• agent_assignments — maps each agent to a single default role in freshly initialized projects
• agent_roles — optional multi-role map used by newer role-management flows
• roles — role definitions with labels and responsibilities

Example:

{
  "version": 1,
  "agent_assignments": {
    "claude": "tech_lead",
    "kimi": "backend_dev"
  },
  "agent_roles": {
    "claude": ["tech_lead", "backend_dev"]
  },
  "roles": {
    "tech_lead": {
      "label": "Tech Lead",
      "responsibilities_short": "Architecture decisions, code review, integration"
    },
    "backend_dev": {
      "label": "Backend Developer",
      "responsibilities_short": "APIs, database, business logic, server-side"
    },
    "code_reviewer": {
      "label": "Code Reviewer",
      "responsibilities_short": "Pull request reviews, style enforcement"
    }
  }
}

Multi-Role Support

Agents can have multiple roles simultaneously. This is useful when:

• An agent needs to both architect and implement (e.g., tech_lead + backend_dev)
• A small team where agents wear multiple hats
• Specialized tasks that cross traditional boundaries

Managing roles via CLI:

# List all agents and their roles
agentweave roles list

# Add a role to an agent
agentweave roles add claude backend_dev

# Remove a role from an agent
agentweave roles remove claude backend_dev

# Set multiple roles (replaces existing)
agentweave roles set claude tech_lead,backend_dev

# List available role types
agentweave roles available

.agentweave/roles/*.md

Per-role behavioral guides. Available roles include:

Role File	Description	Default For
tech_lead.md	Architecture, code review, integration	claude
backend_dev.md	APIs, database, business logic	kimi, codex, qwen
frontend_dev.md	UI components, client-side state	cursor, windsurf
fullstack_dev.md	Backend and frontend features	gemini, cline
devops_engineer.md	CI/CD, infrastructure	opendevin
qa_engineer.md	Tests, quality assurance	—
security_engineer.md	Security review, auth	—
technical_writer.md	Documentation, guides, READMEs	gpt
code_reviewer.md	Pull request reviews, style enforcement	aider, copilot
project_manager.md	Project planning, coordination	—
data_engineer.md	Data pipelines, ETL, warehousing	—
ml_engineer.md	ML models, training pipelines, inference	—

Role files are stable contracts. They define scope, responsibilities, non-responsibilities, handoff rules, quality behavior, definition of done, and escalation paths. They do not embed a full copy of agentweave.yml; generated agent context layers current project facts around the assigned role contracts.

.agentweave/shared/context.md

Dynamic file — update this daily or when state changes:

# Current Project State

## Current Sprint
[MVP development / Refactoring / Release prep]

## Active Work
### In Progress
- [Agent] is working on: [description]

### Next Up
- [Task] — assigned to [agent]

## Recent Decisions
1. [Date] [Decision] — [Rationale]

## Blockers
- [Issue needing attention]

What to Commit

Safe to commit: - CLAUDE.md / GEMINI.md / AGENTS.md - .agentweave/ai_context.md - .agentweave/context/*.md - .agentweave/protocol.md - .agentweave/roles.json - .agentweave/roles/*.md - .agentweave/shared/context.md

Never commit: - .agentweave/session.json - .agentweave/transport.json - .agentweave/tasks/* - .agentweave/messages/* - .agentweave/logs/*

Claude Code Skills

When you run agentweave init, Claude Code skills are auto-generated in .claude/skills/:

Collaboration Skills

Skill	Purpose
/aw-collab-start	Orient yourself at session start — check role, inbox, tasks
/aw-delegate	Delegate a task to another agent
/aw-status	Show full collaboration overview
/aw-done	Mark task complete and notify principal
/aw-review	Request a code review
/aw-relay	Generate relay prompt for manual handoff
/aw-sync	Sync context files from .agentweave/ai_context.md
/aw-revise	Accept a revision request and move task to in_progress

AW-Spec Workflow Skills

Skill	Purpose
/aw-spec-explore	Explore what to build — idea, problem, workflows, requirements
/aw-spec-technical-explore	Explore how to build it — architecture, tests, deployment, agents
/aw-spec-propose	Create a structured proposal with design and tasks
/aw-spec-apply	Implement tasks from a proposal
/aw-spec-archive	Archive a completed change

Utility Skills

Skill	Purpose
agentweave checkpoint	Save context checkpoint before handoffs (CLI command)
/aw-deploy	Release a new version of AgentWeave
/check-build	Check GitHub Actions CI build status

See Also

• Session Modes — how hierarchical/peer/review modes work
• Adding New Agents — adding support for new agents