agent-swarm-os: Instructions file for Claude Code

Agent Squad

Agent Squad runs domain-specific multi-agent missions with a manifest-driven workspace and dashboard.

Claude Agent Teams (Required)

This project expects Claude Agent Teams to be enabled for all runs.

Use: CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 claude --teammate-mode in-process

Reference: https://code.claude.com/docs/en/agent-teams.md

Workspace Conventions

All mission data is under workspaces/:

workspaces/{YYYY-MM-DD}-{slug}/
  workspace.json
  tasks.json
  source/mission.md
  agents/*.md
  artifacts/{module-id}/

Use workspace.json as the source of truth for:

• team metadata
• groups
• agents
• modules
• workflow lanes
• comms settings

Directory Safety

Before creating new directories or workspaces:

1. Confirm the correct working directory with the user
2. Default to operating within the current project structure
3. Never create workspaces outside workspaces/ without explicit confirmation
4. Use pwd to verify location before spawning agents

Ownership Rules

• Each agent owns its assigned tasks and module outputs.
• Do not rewrite another agent's deliverable unless task dependencies require it.
• Keep edits traceable and mission-focused.

Team Comms Feed

Post updates to the team feed JSONL:

~/.claude/teams/{teamName}/team-feed.jsonl

Using agent-squad:comms skill (recommended):

post_update(message="Research phase complete")
post_insight(message="Found pattern: 80% of leads lack decision-maker info", category="data-quality")
post_blocker(message="Cannot proceed - missing API credentials", blockedTask="task-003")

Manual JSONL format (if skills unavailable):

{"timestamp":"ISO8601","agent":"agent-id","type":"update|insight|blocker","message":"text","workspaceId":"workspace-id"}

CRITICAL: workspaceId is REQUIRED

When multiple workspaces share the same team name, messages WITHOUT a workspaceId field will NOT appear in the dashboard. The dashboard filters messages to show only those belonging to the current workspace.