# Agency Agents — Administrator & Developer Guide

## 1. Architecture Overview

`agency-agents` is a **content repository**, not a software application. It contains no compiled code, no runtime services, no databases, and no network listeners. The repository distributes a curated library of markdown files — each describing a specialized AI agent persona with YAML frontmatter — plus a thin shell-script layer that copies those files into the agent directories of 13 supported AI coding tools.

The repository's value lives in four architectural layers:

1. **Agent roster** — 200+ opinionated role definitions across 15 business divisions, each with a consistent frontmatter contract and a persona body designed for direct LLM consumption
2. **NEXUS orchestration framework** (`strategy/`) — playbooks, runbooks, coordination templates, and activation prompts that chain multiple agents into structured multi-phase workflows
3. **Integration layer** (`integrations/<tool>/`) — per-tool installation guides, activation syntax, and format adapters for 13 AI coding tools
4. **Utility scripts** (`scripts/`) — `install.sh`, `convert.sh`, `lint-agents.sh`, and the i18n PowerShell localization pipeline

### Repository Structure

```text
agency-agents/
├── academic/                    # 5 agents — anthropology, geography, history, narratology, psychology
├── design/                      # 8 agents — UI/UX, brand, visual storytelling, inclusive visuals
├── engineering/                  # 29 agents — full SDLC coverage
├── examples/                    # 5 workflow examples + README
├── finance/                     # 5 agents — bookkeeping, FP&A, investment, tax
├── game-development/            # 5 cross-engine agents
│   ├── blender/                 # 1 agent — addon engineering
│   ├── godot/                   # 3 agents — gameplay, multiplayer, shaders
│   ├── roblox-studio/           # 3 agents — avatar, experience, systems
│   ├── unity/                   # 4 agents — architecture, shaders, multiplayer, editor tools
│   └── unreal-engine/           # 4 agents — multiplayer, systems, tech art, world building
├── integrations/                # README + 13 tool-specific integration dirs
│   ├── aider/
│   ├── antigravity/
│   ├── claude-code/
│   ├── cursor/
│   ├── gemini-cli/
│   ├── github-copilot/
│   ├── kimi/
│   ├── mcp-memory/              # README + setup.sh + backend-architect-with-memory.md
│   ├── openclaw/
│   ├── opencode/
│   ├── qwen/
│   └── windsurf/
├── marketing/                   # 30 agents — global + China-market specialists
├── paid-media/                  # 7 agents — PPC, programmatic, tracking, creative
├── product/                     # 5 agents — PM, sprint, nudge, feedback, trends
├── project-management/          # 6 agents — studio producer, shepherd, ops, Jira
├── sales/                       # 8 agents — outbound, discovery, deals, proposals, pipeline
├── scripts/
│   ├── convert.sh               # Format conversion between tool conventions
│   ├── install.sh               # Auto-detect tools and copy agents
│   ├── lint-agents.sh           # Validate formatting and consistency
│   └── i18n/
│       ├── README.md
│       ├── agent-names-zh.json  # 150+ English→Chinese name/description mappings
│       └── localize-agents-zh.ps1  # PowerShell localization script
├── spatial-computing/           # 6 agents — visionOS, WebXR, Metal, XR interaction
├── specialized/                 # 41 agents — industry-specific and cross-functional
├── strategy/
│   ├── EXECUTIVE-BRIEF.md       # Ecosystem overview and agent pairings
│   ├── QUICKSTART.md            # Guided first steps
│   ├── nexus-strategy.md        # Strategic coordination model
│   ├── coordination/
│   │   ├── agent-activation-prompts.md   # Ready-made activation prompts
│   │   └── handoff-templates.md          # Agent-to-agent handoff patterns
│   ├── playbooks/               # 7-phase lifecycle (phase-0 through phase-6)
│   └── runbooks/                # 4 scenario runbooks (MVP, incident, marketing, enterprise)
├── support/                     # 6 agents — response, analytics, finance, infra, legal, exec
├── testing/                     # 8 agents — API, performance, accessibility, evidence, workflow
├── CONTRIBUTING.md              # Contribution guidelines
├── CONTRIBUTING_zh-CN.md        # Chinese translation of contributing guidelines
├── LICENSE
├── README.md
└── SECURITY.md
```

> [!NOTE]
> This is a content repository — the "source code" is markdown. The AST code extractor finds 0 functions, 0 classes, 0 CLI commands, 0 API endpoints, and 0 config keys because the meaningful content is prose agent instructions, not executable code.

### Technology Stack

| Layer | Technology |
|---|---|
| Agent definitions | Markdown with YAML frontmatter |
| Installation script | Bash (`scripts/install.sh`) |
| Format converter | Bash (`scripts/convert.sh`) |
| Linting | Bash (`scripts/lint-agents.sh`) |
| Localization | PowerShell (`scripts/i18n/localize-agents-zh.ps1`) |
| Localization data | JSON (`scripts/i18n/agent-names-zh.json`) |
| MCP memory setup | Bash (`integrations/mcp-memory/setup.sh`) |
| Version control | Git |
| Hosting | GitHub |

### Data Flow

```text
Agent .md files (canonical source)
         │
         ├──→ install.sh ──→ Copy to tool-specific agent directories
         │                    (~/.github/agents/, ~/.cursor/, .claude/, etc.)
         │
         ├──→ convert.sh ──→ Format adaptation for different tool conventions
         │
         ├──→ lint-agents.sh ──→ Validation and consistency checks
         │
         └──→ localize-agents-zh.ps1 ──→ In-place Chinese localization
              (reads agent-names-zh.json)
```

---

## 2. System Requirements

| Requirement | Details |
|---|---|
| Git | Required for cloning |
| Bash | Required for `install.sh`, `convert.sh`, `lint-agents.sh`, and `setup.sh` |
| PowerShell | Required only for Chinese localization (`localize-agents-zh.ps1`) |
| Disk space | < 5 MB |
| Network | Only needed for initial clone |

> [!NOTE]
> There are no runtime dependencies, no package managers, no build tools, and no compiled artifacts. The repository is entirely self-contained markdown and shell scripts.

---

## 3. Configuration Reference

### Agent Frontmatter Specification

Every agent `.md` file uses YAML frontmatter delimited by `---` markers:

| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| `name` | string | Yes | — | Display name of the agent persona |
| `description` | string | Yes | — | 1–2 sentence expertise summary |
| `color` | string | No | — | Brand color — named (`green`, `blue`) or hex (`"#6B7280"`, `"#D97706"`) |
| `emoji` | string | No | — | Single emoji character as visual identifier |
| `vibe` | string | No | — | One-line personality statement; usually quoted |
| `tools` | string | No | — | Comma-separated tool capabilities (e.g., `WebFetch, WebSearch, Read, Write, Edit`) |

**Example — full frontmatter:**

```yaml
---
name: Chief of Staff
description: Master coordinator for founders and executives — filters noise, owns processes, enforces consistency.
color: "#6B7280"
emoji: 🧭
vibe: "I don't own any function. I own the space between all of them."
---
```

**Example — minimal frontmatter:**

```yaml
---
name: Growth Hacker
description: Expert growth strategist specializing in rapid user acquisition through data-driven experimentation.
---
```

> [!IMPORTANT]
> The `color` field accepts both named colors and hex codes. Hex codes must be quoted in YAML to avoid parsing errors (e.g., `color: "#6B7280"`, not `color: #6B7280`).

### Agent Body Structure

The body following the frontmatter closing `---` follows a consistent pattern across all 200+ agents:

1. **H1 Title** — agent name with optional emoji prefix (e.g., `# 🧭 Chief of Staff`)
2. **Identity & Memory** — role definition, personality traits, memory management, experience background
3. **Core Mission / Philosophy** — primary objectives organized as H3/H4 subsections with emoji-prefixed headers and capability bullets
4. **Critical Rules** — hard behavioral constraints, numbered or emoji-prefixed, each with explanation and "This means:" implementation details
5. **Deliverables / Templates** — concrete output specifications, code examples in fenced blocks, template structures with placeholders
6. **Domain Context** — decision frameworks, success metrics, communication style, architecture templates (varies by agent type)

### Agent Naming Convention

Files follow the pattern: `{category}/{category}-{role-name}.md`

| Pattern | Example |
|---|---|
| Standard | `engineering/engineering-senior-developer.md` |
| Sub-category | `game-development/unity/unity-architect.md` |
| Strategy docs | `strategy/EXECUTIVE-BRIEF.md` (uppercase for master documents) |
| Playbooks | `strategy/playbooks/phase-0-discovery.md` |
| Runbooks | `strategy/runbooks/scenario-startup-mvp.md` |
| Coordination | `strategy/coordination/handoff-templates.md` |
| Examples | `examples/workflow-startup-mvp.md` |
| Integration | `integrations/mcp-memory/backend-architect-with-memory.md` |

### Chinese Localization Mapping

`scripts/i18n/agent-names-zh.json` maps English agent names to Chinese equivalents:

```json
{
  "Frontend Developer": {
    "name": "前端开发工程师",
    "description": "专注现代 Web 技术、React/Vue/Angular 框架、UI 实现与性能优化的前端专家"
  },
  "Backend Architect": {
    "name": "后端架构师",
    "description": "负责 API 设计、数据库架构与可扩展性的后端系统专家"
  }
}
```

The mapping covers 150+ agents. JSON keys match the `name` field in agent frontmatter exactly (case-sensitive). Agents whose `name` has no mapping entry are skipped by the localization script.

### Localization Script Configuration

`scripts/i18n/localize-agents-zh.ps1` accepts a `-TargetDirs` parameter:

| Parameter | Type | Default | Description |
|---|---|---|---|
| `-TargetDirs` | `string[]` | `@("$env:USERPROFILE\.github\agents", "$env:USERPROFILE\.copilot\agents")` | Directories containing agent `.md` files to localize |

The script processes each `.md` file in the target directories:
1. Reads the file as UTF-8
2. Parses the YAML frontmatter (between `---` markers)
3. Extracts the `name` field
4. Looks up the name in `agent-names-zh.json`
5. If found, replaces `name` and `description` fields with Chinese translations
6. Writes the modified file back as UTF-8

> [!WARNING]
> The script modifies files in-place with no backup. It also does not touch the body of the agent file — only `name` and `description` frontmatter fields are replaced.

---

## 4. Deployment & Scaling

### Distribution Model

This is a Git-based distribution. Users clone the repository and run the installer or manually copy agent files. There is no package registry, no container image, and no server deployment.

**Distribution channels:**

| Channel | Mechanism |
|---|---|
| GitHub | `git clone https://github.com/msitarzewski/agency-agents.git` |
| ZIP download | GitHub web UI → Code → Download ZIP |
| Manual copy | Copy individual `.md` files directly |

### Installation Pipeline

`scripts/install.sh` handles automated deployment to local AI tool directories:

1. Detects which supported AI tools are installed by checking for their config directories
2. Copies agent `.md` files to each detected tool's agent directory
3. Reports results per tool

### Format Conversion Pipeline

`scripts/convert.sh` converts agent files between format conventions required by different AI tools.

### Adding a New Integration

To add support for a new AI tool:

1. Create `integrations/<tool-name>/README.md` with:
   - Tool-specific agent directory path
   - How to load/activate agents in that tool
   - Any format differences from the canonical markdown
2. Update `scripts/install.sh` to detect the new tool and copy agents to its directory
3. Update `scripts/convert.sh` if the tool requires format changes
4. Test with a representative set of agents

---

## 5. Operations

### Linting and Quality Assurance

Run the lint script to validate all agent files:

```bash
./scripts/lint-agents.sh
```

> [!TIP]
> Run linting after adding new agents, modifying frontmatter, or accepting pull requests to catch formatting inconsistencies.

### Updating Agents

Agent updates are straightforward Git operations:

```bash
cd agency-agents
git pull origin main
./scripts/install.sh  # Re-deploy updated agents to tools
```

### Agent Inventory Audit

To count agents by category:

```bash
for dir in academic design engineering finance game-development marketing \
           paid-media product project-management sales spatial-computing \
           specialized strategy support testing; do
  count=$(find "$dir" -name "*.md" -not -name "README.md" | wc -l)
  echo "$dir: $count agents"
done
```

> [!NOTE]
> Some directories contain README files that are not agent definitions. Exclude `README.md` files when counting agents. Strategy files (playbooks, runbooks, coordination) are workflow documents, not agent personas.

### Localization Operations

To verify localization coverage:

```bash
# Count agents in the zh mapping
python3 -c "import json; d=json.load(open('scripts/i18n/agent-names-zh.json')); print(f'{len(d)} agents mapped')"
```

To add a new agent to the Chinese localization:

1. Add an entry to `scripts/i18n/agent-names-zh.json` with the exact English `name` as key
2. Provide `name` (Chinese name) and `description` (Chinese description) values
3. Re-run the localization script on your target directories

---

## 6. Performance

### Repository Size

| Metric | Value |
|---|---|
| Total files | 234 |
| Total source characters | 9,359 (metadata-counted; actual content is larger as markdown body isn't fully counted) |
| Agent definitions | ~200+ |
| Categories | 15 |
| Shell scripts | 4 (install.sh, convert.sh, lint-agents.sh, setup.sh) |
| PowerShell scripts | 1 (localize-agents-zh.ps1) |
| JSON data files | 1 (agent-names-zh.json) |

> [!TIP]
> The repository is lightweight by design. Clone and install operations complete in seconds. Agent files average 2–5 KB each.

---

## 7. Security

### Security Policy

The repository includes a `SECURITY.md` file for responsible disclosure.

### Known Security Issues

Two security issues are tracked in GitHub Issues:

#### Hidden Unicode Soft Hyphens (Issue #478)

**Severity:** Medium — prompt injection vector

**Description:** Unicode soft hyphens (U+00AD) were found in 2 agent files. These invisible characters could alter LLM behavior when agent files are loaded as system prompts.

**Detection:**

```bash
grep -rP '\xC2\xAD' *.md */*.md
```

**Mitigation:**
- Remove all U+00AD characters from affected files
- Add Unicode validation to `scripts/lint-agents.sh`
- Review all agent files for unexpected invisible characters

> [!CAUTION]
> Agent files are consumed directly by LLMs as system prompts. Hidden Unicode characters can cause prompt injection, behavior manipulation, or instruction bypass. Always audit agent files from external contributors.

#### Hardcoded Credentials (Issue #477)

**Severity:** Medium — credential exposure

**Description:** `testing/testing-api-tester.md` and `testing/testing-performance-benchmarker.md` contained example credentials that could be mistaken for real ones or accidentally used.

**Mitigation:**
- Replace all credential-like strings with obvious placeholders
- Add credential pattern detection to `scripts/lint-agents.sh`
- Document in `CONTRIBUTING.md` that example credentials must use placeholder format

> [!WARNING]
> Never commit real API keys, passwords, tokens, or secrets in agent definition files. These files are designed to be shared publicly and loaded into AI tools — any credentials in them will be exposed.

### Security Considerations for Agent Files

| Risk | Description | Mitigation |
|---|---|---|
| Prompt injection | Malicious instructions hidden in agent files | Lint validation, Unicode checks, code review |
| Credential exposure | Real secrets in example code blocks | Placeholder-only policy, lint enforcement |
| Supply chain | Compromised agent files in upstream repo | Pin to known-good commits, review diffs |
| Scope escalation | Agent requesting broader tool access than needed | Review `tools` frontmatter field, restrict per-tool permissions |

---

## 8. Developer Internals

### Category Taxonomy

The 15 categories follow a consistent organizational principle: each maps to a business function or professional domain.

| Category | Agent Count | Sub-categories | Design Intent |
|---|---|---|---|
| `academic` | 5 | — | Research and analytical disciplines |
| `design` | 8 | — | Visual, UX, and brand design |
| `engineering` | 29 | — | Full SDLC from architecture to firmware |
| `examples` | 5 | — | Workflow demonstration files (not agents) |
| `finance` | 5 | — | Financial operations and analysis |
| `game-development` | 20 | blender, godot, roblox-studio, unity, unreal-engine | Engine-specific + cross-engine disciplines |
| `integrations` | 13 dirs | Per-tool directories | AI tool compatibility layer |
| `marketing` | 30 | — | Global + China-market digital marketing |
| `paid-media` | 7 | — | Advertising and media buying |
| `product` | 5 | — | Product management and research |
| `project-management` | 6 | — | Project execution and studio ops |
| `sales` | 8 | — | Sales cycle from outbound to account mgmt |
| `spatial-computing` | 6 | — | XR, visionOS, Metal, spatial interfaces |
| `specialized` | 41 | — | Industry-specific and cross-functional |
| `strategy` | 16 | coordination, playbooks, runbooks | NEXUS orchestration framework |
| `support` | 6 | — | Operational support functions |
| `testing` | 8 | — | Quality assurance and validation |

### NEXUS Strategy Framework Architecture

The strategy layer provides three workflow modes:

| Mode | Phases | Use Case |
|---|---|---|
| **Full** | Phases 0–6 (discovery → operate) | Complete product lifecycle |
| **Sprint** | 3 selected phases | Focused delivery sprint |
| **Micro** | Single agent | Ad-hoc specialist task |

**Phase lifecycle:**

```text
Phase 0: Discovery → Phase 1: Strategy → Phase 2: Foundation →
Phase 3: Build → Phase 4: Hardening → Phase 5: Launch → Phase 6: Operate
```

**Coordination mechanisms:**

- `coordination/handoff-templates.md` — structured context transfer between agents
- `coordination/agent-activation-prompts.md` — ready-made prompts to activate any agent in the roster

**Scenario runbooks:**

| Runbook | File | Agents Involved |
|---|---|---|
| Startup MVP | `scenario-startup-mvp.md` | Product Manager, Backend Architect, Frontend Developer, DevOps |
| Incident Response | `scenario-incident-response.md` | Incident Response Commander, SRE, Security Engineer |
| Marketing Campaign | `scenario-marketing-campaign.md` | Content Creator, channel-specific agents, Growth Hacker |
| Enterprise Feature | `scenario-enterprise-feature.md` | Product Manager, Software Architect, Senior Developer, Code Reviewer |

### MCP Memory Integration Architecture

The MCP memory integration (`integrations/mcp-memory/`) is a pattern, not a runtime. It provides:

1. **`setup.sh`** — a diagnostic script that:
   - Checks for MCP client configs at three known paths (`~/.config/claude/mcp.json`, `~/.cursor/mcp.json`, `.mcp.json`)
   - Prints guidance for installing an MCP-compatible memory server
   - Outputs the expected MCP config JSON structure
   - Does NOT install any server or modify any config files automatically

2. **`backend-architect-with-memory.md`** — a reference implementation showing how to weave memory tool usage (`remember`, `recall`, `rollback`, `search`) into an agent's prompt body

3. **`README.md`** — documentation of the memory integration pattern

The design is deliberately server-agnostic: any MCP-compatible memory server works. The integration only specifies the tool interface contract:

| MCP Tool | Parameters | Purpose |
|---|---|---|
| `remember` | content, context | Store decisions, deliverables, context |
| `recall` | query | Search by keyword or semantic similarity |
| `rollback` | state_id | Revert to a previous memory state |
| `search` | query | Find specific memories across sessions |

> [!NOTE]
> The `setup.sh` script is read-only — it detects and reports but does not modify any files. All configuration changes must be done manually by the user.

### Localization Pipeline Internals

The Chinese localization system has two components:

**`agent-names-zh.json`** (15,888 chars) — a flat JSON object mapping English agent names to Chinese translations. Each entry provides:

```json
{
  "Agent English Name": {
    "name": "中文名称",
    "description": "中文描述"
  }
}
```

Coverage: 150+ agents mapped. The mapping includes alternate name forms for some agents (e.g., both `"Academic Anthropologist"` and `"Anthropologist"` map to `"学术人类学家"`).

**`localize-agents-zh.ps1`** — PowerShell script that performs in-place frontmatter rewriting:

1. Iterates `.md` files in target directories
2. Detects YAML frontmatter by checking for leading `---`
3. Extracts `name:` field via regex `(?m)^name:\s*(.+)$`
4. Looks up the name in the JSON mapping
5. Replaces `name:` and `description:` lines via regex substitution
6. Writes back as UTF-8
7. Reports count of files updated per directory

**Key implementation details:**

- Uses `[System.IO.File]::ReadAllText/WriteAllText` for proper UTF-8 handling
- Only modifies frontmatter — body content is untouched
- Silently skips files without frontmatter or without a mapping entry
- Default target directories: `$env:USERPROFILE\.github\agents` and `$env:USERPROFILE\.copilot\agents`

### Utility Scripts

| Script | Path | Language | Purpose |
|---|---|---|---|
| `install.sh` | `scripts/install.sh` | Bash | Auto-detect AI tools and copy agent files to their directories |
| `convert.sh` | `scripts/convert.sh` | Bash | Convert agent files between format conventions |
| `lint-agents.sh` | `scripts/lint-agents.sh` | Bash | Validate agent file formatting and consistency |
| `setup.sh` | `integrations/mcp-memory/setup.sh` | Bash | MCP memory integration setup and diagnostics |
| `localize-agents-zh.ps1` | `scripts/i18n/localize-agents-zh.ps1` | PowerShell | Chinese localization of agent frontmatter |

> [!TIP]
> The `scripts/` directory is classified as LOW priority in the file triage because its contents are support tooling, not agent definitions. The `testing/` directory is similarly LOW priority — those are testing-methodology agents, not test suites.

### Agent Design Patterns

Across the 200+ agent definitions, several recurring patterns emerge:

**Pattern: Persona-first instruction**
Every agent opens with identity establishment (role, personality, experience) before listing capabilities. This primes the LLM to adopt the persona before processing task-specific instructions.

**Pattern: Critical rules as guardrails**
Agents include numbered "Critical Rules" or "Rules You Must Follow" sections with hard constraints. Each rule typically includes a "This means:" clause explaining implementation. This pattern prevents the LLM from drifting outside the agent's intended scope.

**Pattern: Deliverable templates**
Agents include concrete output templates with placeholder sections, showing the exact structure of expected deliverables. This reduces format variation across sessions.

**Pattern: Domain-specific code examples**
Technical agents embed real code examples (PHP, SQL, JavaScript, CSS, etc.) demonstrating the quality and style of output they should produce. These are not pseudo-code — they are functional snippets.

**Pattern: Anti-patterns as negative constraints**
Many agents explicitly list what NOT to do (e.g., "No culture salad", "function before aesthetics"). Negative constraints are as important as positive instructions for LLM behavior shaping.

**Pattern: Emoji-prefixed section headers**
H3 and H4 headers frequently use emoji prefixes for visual scanning (e.g., `### 🎯 Core Mission`, `### ⚡ Critical Rules`). This is a stylistic choice, not a functional requirement.

### File Inventory Summary

| File Type | Count | Location |
|---|---|---|
| Agent definitions (`.md`) | ~200 | Category directories |
| Integration READMEs | 13 | `integrations/*/README.md` |
| Strategy documents | 16 | `strategy/` and subdirectories |
| Workflow examples | 5 | `examples/` |
| Shell scripts | 4 | `scripts/`, `integrations/mcp-memory/` |
| PowerShell scripts | 1 | `scripts/i18n/` |
| JSON data | 1 | `scripts/i18n/agent-names-zh.json` |
| Project docs | 5 | Root (README, CONTRIBUTING, CONTRIBUTING_zh-CN, LICENSE, SECURITY) |
| Git config | 2 | Root (.gitattributes, .gitignore) |

### Code Patterns and Conventions

**Frontmatter consistency:** All agents use the same YAML frontmatter field set. `name` and `description` are universal; `color`, `emoji`, `vibe`, and `tools` are optional.

**Naming convention:** Files use `{category}-{role-name}.md` with lowercase kebab-case. Category prefix matches the directory name.

**Sub-categorization:** `game-development/` uses engine-specific subdirectories. `strategy/` uses function-specific subdirectories (playbooks, runbooks, coordination). Other categories are flat.

**Language:** Agent body content is English. Chinese localization is applied only to frontmatter fields, not body text.

**Line endings and encoding:** Files are UTF-8. The `.gitattributes` file manages line ending normalization.

### Known Issues and Improvement Opportunities

1. **Unicode sanitization** — No automated check for hidden Unicode characters (Issue #478). The lint script should detect non-ASCII invisible characters in agent files.

2. **Credential patterns** — No automated detection of credential-like strings in agent examples (Issue #477). A lint rule should flag patterns like `sk_test_`, `Bearer`, API key formats.

3. **Localization coverage gaps** — The zh-CN mapping covers ~150 of 200+ agents. New agents added without corresponding JSON entries will be skipped during localization.

4. **Feature request: Interior Designer agent** — Issue #491 requests an interior design specialist agent. Would belong in `design/` or `specialized/`.

5. **Monetization proposal** — Issue #486 proposes a native monetization layer via Merxex. This is an architectural discussion about potentially adding commercial infrastructure to a content repository.

### Contributing

The repository maintains contribution guidelines in two languages:

- `CONTRIBUTING.md` — English
- `CONTRIBUTING_zh-CN.md` — Chinese (zh-CN)

**To add a new agent:**

1. Choose the appropriate category directory
2. Create `{category}/{category}-{role-name}.md`
3. Include required frontmatter (`name`, `description`) and optional fields
4. Follow the body structure pattern: identity → mission → rules → deliverables
5. Run `scripts/lint-agents.sh` to validate
6. Add a zh-CN mapping entry to `scripts/i18n/agent-names-zh.json` if localization is desired
7. Submit a pull request

**To add a new integration:**

1. Create `integrations/<tool-name>/README.md`
2. Document the tool's agent directory path, activation method, and any format requirements
3. Update `scripts/install.sh` and `scripts/convert.sh` to support the new tool
4. Test with representative agents

**To add a new strategy component:**

1. Playbooks go in `strategy/playbooks/phase-{N}-{name}.md`
2. Runbooks go in `strategy/runbooks/scenario-{name}.md`
3. Coordination templates go in `strategy/coordination/`
4. Update cross-references in `strategy/EXECUTIVE-BRIEF.md`

### Testing

The `testing/` directory contains 8 testing-methodology agents (not test suites):

| Agent | File | Purpose |
|---|---|---|
| API Tester | `testing-api-tester.md` | API validation and integration testing |
| Performance Benchmarker | `testing-performance-benchmarker.md` | Performance testing and optimization |
| Accessibility Auditor | `testing-accessibility-auditor.md` | WCAG audit and inclusive design |
| Evidence Collector | `testing-evidence-collector.md` | Screenshot QA and visual verification |
| Reality Checker | `testing-reality-checker.md` | Production readiness validation |
| Test Results Analyzer | `testing-test-results-analyzer.md` | Test evaluation and coverage reporting |
| Tool Evaluator | `testing-tool-evaluator.md` | Technical evaluation and tool selection |
| Workflow Optimizer | `testing-workflow-optimizer.md` | Process analysis and automation |

There are no automated test suites, unit tests, or CI pipelines in this repository. Quality assurance is manual: lint validation via `scripts/lint-agents.sh` and human review of agent effectiveness.

---

## 9. Integration Points

### Supported AI Tools

| Tool | Integration Path | Distribution Method |
|---|---|---|
| Claude Code | `integrations/claude-code/` | Copy to `.claude/` project directory |
| Cursor | `integrations/cursor/` | Copy to Cursor rules |
| GitHub Copilot | `integrations/github-copilot/` | Copy to `~/.github/agents/` |
| Aider | `integrations/aider/` | Aider-specific conventions |
| Windsurf | `integrations/windsurf/` | Windsurf config directory |
| OpenCode | `integrations/opencode/` | OpenCode agent path |
| Gemini CLI | `integrations/gemini-cli/` | Gemini CLI config |
| Antigravity | `integrations/antigravity/` | Antigravity platform config |
| OpenClaw | `integrations/openclaw/` | OpenClaw setup |
| Kimi | `integrations/kimi/` | Kimi AI config |
| Qwen | `integrations/qwen/` | Qwen model config |

### MCP (Model Context Protocol)

The `integrations/mcp-memory/` directory provides a generic MCP memory integration pattern. Any MCP-compatible memory server can be used. See the Architecture section above for implementation details.

### External Dependencies

This repository has **zero external dependencies**. No package managers, no installed libraries, no network services. The only requirement is a shell (Bash for scripts, PowerShell for localization) and Git for version control.

---

_Generated May 2026 from msitarzewski/agency-agents at 783f6a7. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._