Imported from chankov/agent-fleet (AGENTS.md). Install upstream with npx skills add chankov/agent-fleet. Copyright stays with the author.

AGENTS.md

This file provides guidance to AI coding agents working with code in this repository. pi is the coding agent Agent Fleet installs for; Claude Code takes part only as a coms peer (see docs/claude-code-coms-bridge.md).

Terminal File Links

• In terminal responses, link local files using descriptive Markdown link text and an absolute file:/// URL, e.g. [Agent guide](file:///absolute/path/to/AGENTS.md). Do not use relative Markdown link targets or show bare paths instead of named links. This avoids Zed/macOS opening errors.

Repository Overview

Agent Fleet — a Pi-centered multi-agent orchestration system (agent-hub dispatcher, herdr fleet control plane, coms peer messaging, Hermes remote control) plus a library of lifecycle skills and agent personas for pi. Skills live in two roots: fleet-native skills/ and the vendored upstream import vendor/agent-skills-upstream/skills/ (native wins on name collisions — see docs/UPSTREAM-SKILLS.md).

Skill-Driven Execution

Agent Fleet runs on a skill-driven execution model powered by this repository's /skills directory.

Core Rules

• If a task matches a skill, you MUST invoke it
• Skills are located in skills/<skill-name>/SKILL.md
• Never implement directly if a skill applies
• Always follow the skill instructions exactly (do not partially apply them)

Intent → Skill Mapping

The agent should automatically map user intent to skills:

• Feature / new functionality → spec-driven-development, then incremental-implementation, test-driven-development
• Planning / breakdown → planning-and-task-breakdown
• Bug / failure / unexpected behavior → debugging-and-error-recovery
• Code review → code-review-and-quality
• Refactoring / simplification → code-simplification
• API or interface design → api-and-interface-design
• UI work → frontend-ui-engineering

Lifecycle Mapping

The agent should internally follow this lifecycle and invoke the matching skill at each phase:

• DEFINE → spec-driven-development
• PLAN → planning-and-task-breakdown
• BUILD → incremental-implementation + test-driven-development
• VERIFY → debugging-and-error-recovery
• REVIEW → code-review-and-quality
• SHIP → shipping-and-launch

This lifecycle is normally implicit — the agent maps user intent to the right skill without being asked.

The repo also ships slash commands as explicit lifecycle entry points, af--prefixed in .pi/prompts/:

• /af-spec → spec-driven-development
• /af-plan → planning-and-task-breakdown
• /af-build → incremental-implementation + test-driven-development
• /af-test → test-driven-development
• /af-review → code-review-and-quality
• /af-code-simplify → code-simplification
• /af-ship → shipping-and-launch

Workspace installation is outside the prompt/skill layer: use the deterministic agent-fleet setup, agent-fleet doctor, and agent-fleet uninstall CLI commands.

Whether triggered implicitly or via a command, the agent MUST invoke the underlying skill — never inline the steps.

Execution Model

For every request:

1. Determine if any skill applies (even 1% chance)
2. Invoke the appropriate skill
3. Follow the skill workflow strictly
4. Only proceed to implementation after required steps (spec, plan, etc.) are complete

Anti-Rationalization

The following thoughts are incorrect and must be ignored:

• "This is too small for a skill"
• "I can just quickly implement this"
• "I’ll gather context first"

Correct behavior:

• Always check for and use skills first

This keeps workflow enforcement identical across every supported runtime.

Orchestration: Personas, Skills, and Commands

This repo has three composable layers. They have different jobs and should not be confused:

• Skills (skills/<name>/SKILL.md) — workflows with steps and exit criteria. The how. Mandatory hops when an intent matches.
• Personas (agents/<role>.md) — roles with a perspective and an output format. The who.
• Slash commands (.pi/prompts/af-*.md) — user-facing entry points. The when. The orchestration layer.

Composition rule: the user (or a slash command) is the orchestrator. Personas do not invoke other personas. A persona may invoke skills.

The multi-persona pattern this repo endorses in a plain session is parallel fan-out with a merge step — used by /af-ship to run code-reviewer, security-auditor, and test-engineer concurrently and synthesize their reports. Do not build a "router" persona that decides which other persona to call; that's the job of slash commands and intent mapping. The agent-hub harness is the sanctioned exception: the generated dispatcher prompt dispatches specialists under a Verification Contract, with that orchestration living in the harness rather than a peer persona calling another.

See docs/agents.md for the decision matrix and references/orchestration-patterns.md for the full pattern catalog.

Claude Code interop: a Claude Code pane joins a fleet as a coms peer, not as a persona host. It carries no persona file — runner: claude-code in .pi/agents/peers.yaml spawns the CLI plus .pi/agent-fleet/scripts/coms-claude-bridge.ts, and the peer's name is what other agents address. .pi/agents/dispatch-policy.yaml can then route an agent-hub team member's dispatch_agent call to that live peer. See docs/claude-code-coms-bridge.md.

Creating a New Skill

Directory Structure

skills/
  {skill-name}/           # kebab-case directory name
    SKILL.md              # Required: skill definition
    scripts/              # Required: executable scripts
      {script-name}.sh    # Bash scripts (preferred)
  {skill-name}.zip        # Required: packaged for distribution

Naming Conventions

• Skill directory: kebab-case (e.g. web-quality)
• SKILL.md: Always uppercase, always this exact filename
• Scripts: kebab-case.sh (e.g., deploy.sh, fetch-logs.sh)
• Zip file: Must match directory name exactly: {skill-name}.zip

SKILL.md Format

---
name: {skill-name}
description: {One sentence describing what the skill does, followed by one or more "Use when" trigger conditions. Include trigger phrases like "Deploy my app" or "Check logs" when helpful.}
---

# {Skill Title}

{Brief overview of what the skill does and why it matters.}

## How It Works

{Numbered list explaining the skill's workflow}

Equivalent headings like `Workflow`, `Core Process`, or `When to Use` are fine when they communicate the same structure clearly.

## Usage (Optional)

Include this section only if the skill ships runnable helpers under `scripts/`. Markdown-only skills can omit both the section and the directory entirely.

```bash
bash /mnt/skills/user/{skill-name}/scripts/{script}.sh [args]

Arguments:

• arg1 - Description (defaults to X)

Examples: {Show 2-3 common usage patterns}

Output

{Show example output users will see}

Present Results to User

{Template for how Claude should format results when presenting to users}

Troubleshooting

{Common issues and solutions, especially network/permissions errors}

### Best Practices for Context Efficiency

Skills are loaded on-demand — only the skill name and description are loaded at startup. The full `SKILL.md` loads into context only when the agent decides the skill is relevant. To minimize context usage:

- **Keep SKILL.md under 500 lines** — put detailed reference material in separate files
- **Write specific descriptions** — helps the agent know exactly when to activate the skill
- **Use progressive disclosure** — reference supporting files that get read only when needed
- **Prefer scripts over inline code** — script execution doesn't consume context (only output does)
- **File references work one level deep** — link directly from SKILL.md to supporting files

### Script Requirements

- Use `#!/bin/bash` shebang
- Use `set -e` for fail-fast behavior
- Write status messages to stderr: `echo "Message" >&2`
- Write machine-readable output (JSON) to stdout
- Include a cleanup trap for temp files
- Reference the script path as `/mnt/skills/user/{skill-name}/scripts/{script}.sh`

### Creating the Zip Package

After creating or updating a skill:

```bash
cd skills
zip -r {skill-name}.zip {skill-name}/

End-User Installation

Document these installation methods for users:

Deterministic workspace lifecycle:

npx @chankov/agent-fleet@latest setup

Use Default/Full and named features rather than raw item selectors; see docs/npm-install.md.

pi (manual):

cp -r skills/{skill-name} .pi/skills/