Arckit Agent Design

---
name: arckit-agent-design
description: "Design AI agent architecture — patterns, tool contracts, memory, orchestration, guardrails"
---

You are helping an enterprise architect design an AI agent architecture specification following a structured, traceable framework.

## User Input

```text
$ARGUMENTS
```

## Instructions

> **Note**: Before generating, scan `projects/` for existing project directories. For each project, list all `ARC-*.md` artifacts, check `external/` for reference documents, and check `000-global/` for cross-project policies. If no external docs exist but they would improve output, ask the user.

### 1. Read existing artifacts from the project context

**MANDATORY** (warn if missing):

- **AAGI** (Agent Inventory, recommended) — Extract: agent catalogue, current capabilities, lifecycle status, and operational context
  - If missing: warn user to run `$arckit-agent-inventory` first
- **REQ** (Requirements, recommended) — Extract: FR/NFR for agent capabilities, tool requirements, memory requirements, guardrail requirements
  - If missing: warn user to run `$arckit-requirements` first

**RECOMMENDED** (read if available, note if missing):

- **PRIN** (Architecture Principles, in 000-global) — Extract: AI/agent principles, technology constraints, compliance requirements
- **STKE** (Stakeholder Analysis) — Extract: Agent user personas, operator roles, governance stakeholders
- **RISK** (Risk Register) — Extract: AI-specific risks, tool security risks, data handling risks
- **AIPB** (AI Playbook) — Extract: AI ethics principles, model governance, bias considerations

**OPTIONAL** (read if available, skip silently if missing):

- **HLDR** (High-Level Design Review) — Extract: existing system architecture the agent will integrate with
- **SECD** (Secure by Design) — Extract: security controls applicable to agent systems
- **AAGI** (Agent Inventory) — Extract: existing agents, capability baseline, ownership, and operational status

### 2. Identify the target project

- Use the **ArcKit Project Context** (above) to find the project matching the user's input (by name or number)
- If no match, create a new project:
  1. Use Glob to list `projects/*/` directories and find the highest `NNN-*` number (or start at `001` if none exist)
  2. Calculate the next number (zero-padded to 3 digits, e.g., `002`)
  3. Slugify the project name (lowercase, replace non-alphanumeric with hyphens, trim)
  4. Use the Write tool to create `projects/{NNN}-{slug}/README.md` with the project name, ID, and date — the Write tool will create all parent directories automatically
  5. Also create `projects/{NNN}-{slug}/external/README.md` with a note to place external reference documents here
  6. Set `PROJECT_ID` = the 3-digit number, `PROJECT_PATH` = the new directory path

### 3. Interactive Configuration

Before generating the agent design, ask the user for key parameters. **Skip any question where the user has already provided a clear answer in their arguments.**

**Gathering rules** (apply to all questions in this section):

- Ask the most important question first; fill in secondary details from context or reasonable defaults.
- **Maximum 2 rounds of questions.** After that, pick the best option from available context.
- If still ambiguous after 2 rounds, choose the (Recommended) option and note: *"I went with [X] — easy to adjust if you prefer [Y]."*

**Question 1** — header: `Pattern`, multiSelect: false
> "What agent architecture pattern best describes this agent?"

- **Single Agent (Recommended)**: Single LLM core with tools — best for focused tasks, simple domains
- **Chain**: Sequential pipeline of specialized agents — best for multi-step reasoning, complex workflows
- **Multi-Agent**: Parallel workers with a coordinator — best for complex domains, parallelization
- **Hierarchical**: Supervisor + worker agents — best for coordinated multi-agent systems, dynamic task allocation

**Question 2** — header: `Scope`, multiSelect: false
> "What is the primary scope of this agent?"

- **Task Automation**: Automating repetitive workflows (data processing, report generation, routine decisions)
- **Knowledge Work**: Research, analysis, synthesis (document analysis, market research, decision support)
- **Creative**: Generation and ideation (content creation, design, brainstorming)
- **Decision Support**: Recommendation and evaluation (risk assessment, prioritization, planning)

### 4. Read the template

**Read the template** (with user override support):

- **First**, check if `.arckit/templates-custom/agent-design-template.md` exists in the project root
- **If found**: Read the user's customized template (user override takes precedence)
- **If not found**: Read `.arckit/templates/agent-design-template.md` (default)
- **Then**, read `.arckit/templates/_partials/RENDERING.md` and resolve the template's `<!-- DOC-CONTROL-HEADER -->` marker to the Document Control partial it selects, applying the `${organisation_name}` and `${default_classification}` substitutions. Remove the marker and its comment from the output — a rendered artefact must never contain either.

> **Tip**: Users can customize templates with `$arckit-customize agent-design`

### 5. Gather agent design information

**Agent identity and purpose**:

- **Agent name**: Short, descriptive name (e.g., "Research Analyst Agent")
- **Agent ID**: Unique identifier (e.g., "AGT-001")
- **Purpose**: One-sentence description of what the agent does
- **Domain**: Domain of expertise (e.g., "financial analysis", "code review")

**Architecture decisions** (from Questions or context):

- **Architecture pattern**: Single / Chain / Multi-Agent / Hierarchical (from Question 1)
- **Scope**: Task Automation / Knowledge Work / Creative / Decision Support (from Question 2)
- **LLM model**: Primary model (e.g., "Claude Sonnet 5 (session default)")
- **Hosting**: Local / Cloud / Hybrid

**Tool inventory** (minimum 3 tools):

Extract from REQ artifacts or define new:

- **Tool ID**: Unique identifier (e.g., "T-001")
- **Tool name**: Descriptive name
- **Tool type**: MCP / REST / Function / Database
- **Permissions**: Read / Write / Execute
- **Input schema**: Key parameters
- **Output schema**: Return format

**Memory design**:

- **Session memory**: In-memory context, session-scoped
- **Durable memory**: Persistent storage, cross-session
- **Vector memory**: Semantic search, embedding-based retrieval

**Guardrail requirements** (minimum 2 guardrails):

- **Output validation**: Regex / LLM-based / Heuristic checks
- **Input sanitization**: Prompt injection prevention
- **Rate limiting**: Usage controls
- **Content filtering**: Safety boundaries

**Testing approach**:

- **Unit tests**: Tool contract validation
- **Integration tests**: End-to-end agent flow
- **Security tests**: Prompt injection, jailbreak resistance

### 6. Auto-Populate from Existing Artifacts

**CRITICAL**: To create a high-quality, integrated agent design, extract data from existing ArcKit artifacts:

#### 6.1 Extract Requirements → Tool Contracts

If `projects/{project_id}/ARC-*-REQ-*.md` exists:

**Read the file** and extract:

- **FR (Functional Requirements)** → Map to **Tool Capabilities**
  - Example: "FR-010: Query knowledge base" → Tool T-001 (Knowledge Base MCP)
- **NFR (Non-Functional Requirements)** → Map to **Guardrails and Memory**
  - Example: "NFR-S-001: Respond within 5 seconds" → Guardrail: timeout
  - Example: "NFR-P-002: Remember user preferences" → Memory: Durable layer

#### 6.2 Extract Risks → Guardrail Configuration

If `projects/{project_id}/ARC-*-RISK-*.md` exists:

**Read the risk register** and extract:

- **Security risks** → Guardrails (prompt injection, data exfiltration)
- **Reliability risks** → Redundancy patterns, fallback mechanisms
- **Compliance risks** → Audit logging, data retention policies

#### 6.3 Extract Stakeholders → Agent Persona

If `projects/{project_id}/ARC-*-STKE-*.md` exists:

**Read stakeholder analysis** and extract:

- **End users** → Agent interaction patterns, tone, complexity level
- **Operators** → Monitoring requirements, admin capabilities
- **Governance** → Approval workflows, audit requirements

### 7. Detect Version

Before generating the document ID, check if a previous version exists:

1. Look for existing `ARC-{PROJECT_ID}-AAGR-v*.md` files in the project directory
2. **If no existing file**: Use VERSION="1.0"
3. **If existing file found**:
   - Read the existing document to understand its scope
   - Compare against current inputs and agent requirements
   - **Minor increment** (e.g., 1.0 → 1.1): Same pattern — updated tools, refined guardrails, corrected details
   - **Major increment** (e.g., 1.0 → 2.0): Pattern changed (single → multi-agent), fundamentally different tools, new memory architecture
4. Use the determined version for document ID, filename, Document Control, and Revision History
5. For v1.1+/v2.0+: Add a Revision History entry describing what changed from the previous version

### 8. Construct Document Control Metadata

- **Document ID**: `ARC-{PROJECT_ID}-AAGR-v{VERSION}` (e.g., `ARC-001-AAGR-v1.0`)

**Populate document control fields**:

- `document_id`: Constructed from format above
- `project_id`: From Step 2
- `project_name`: From Step 2
- `version`: Determined version from Step 7
- `author`: "ArcKit Agent Design Command"
- `date_created`: Current date (YYYY-MM-DD)
- `date_updated`: Current date (YYYY-MM-DD)
- `generation_date`: Current date and time
- `ai_model`: Your model name

### 9. Generate Agent Architecture Specification

**CRITICAL INSTRUCTIONS FOR QUALITY**:

1. **This is a LARGE document** (architecture diagram + tool matrix + orchestration design, 600-1200+ lines). You MUST use the **Write tool** to create the file. DO NOT output the full document to the user (you will exceed token limits).

2. **Follow the template structure** with all 7 sections:

   **Section 1: Agent Architecture Overview**
   - Architecture pattern selection with justification
   - Architecture pattern comparison table (Single / Chain / Multi-Agent / Hierarchical)
   - Component diagram (Mermaid C4) showing: LLM Core, Tool Layer, Memory, Guardrails
   - Agent capabilities summary table

   **Section 2: Tool Contracts** (minimum 3 tools)
   - Tool contract matrix with: Tool ID, Name, Type, Permissions, Input Schema, Output Schema
   - MCP server configurations
   - Tool dependency graph (Mermaid)

   **Section 3: Memory Architecture**
   - Memory layer table: Session / Durable / Vector
   - Storage technology, retention policy, access patterns
   - Memory flow diagram (Mermaid)

   **Section 4: Orchestration Design**
   - Orchestration table: Component, Framework, Role, Handoff
   - Flow diagram (Mermaid flowchart) showing node transitions
   - Error handling and retry strategies
   - State management approach

   **Section 5: Guardrail Configuration** (minimum 2 guardrails)
   - Guardrail table: Name, Type, Threshold, Action
   - Prompt injection prevention strategy
   - Output validation pipeline
   - Rate limiting and quota management

   **Section 6: Testing Strategy**
   - Test matrix: Unit / Integration / Security / Performance
   - Coverage targets and tooling
   - Evaluation framework (benchmarks, golden datasets)

   **Section 7: Traceability**
   - AAGI → AAGR → REQ traceability links
   - Cross-references to related artifacts

3. **Auto-populate from artifacts** (from Step 6):
   - Tool contracts from ARC-*-REQ-*.md
   - Guardrails from ARC-*-RISK-*.md
   - Agent personas from ARC-*-STKE-*.md

4. **Mermaid diagram requirements**:
   - C4Component diagram for architecture overview
   - Flowchart for orchestration design
   - All diagrams must use consistent styling
   - Include element descriptions in `Person()`, `Component()`, etc.

### 10. Quality Checks

Before writing the file, read `.arckit/references/quality-checklist.md` and verify all **Common Checks** plus the **AAGR** per-type checks pass. Fix any failures before proceeding.

**AAGR-specific quality checks**:

- **Architecture pattern defined**: One of Single, Chain, Multi-Agent, or Hierarchical — not left as placeholder
- **Component diagram present**: Valid Mermaid C4Component diagram with LLM Core, Tool Layer, Memory, Guardrails
- **Tool contracts**: At least 3 tools defined with complete schema (ID, name, type, permissions, input, output)
- **Memory architecture**: All 3 layers (Session, Durable, Vector) documented with storage and retention
- **Orchestration diagram**: Valid Mermaid flowchart with at least 3 nodes
- **Guardrails**: At least 2 guardrails defined with type, threshold, and action
- **Testing strategy**: At least 3 test types covered (Unit, Integration, Security)
- **No placeholder text**: No remaining `[Name]`, `[Model]`, `[MCP servers]`, or `[Schema]` tokens

### 11. Use Write tool to create the agent design file

- **CRITICAL**: Because agent designs are large documents (600-1200+ lines), you MUST use the Write tool to create the file
- Do NOT output the full content in your response (this will exceed token limits)
- Use Write tool with the full agent design content
- Path: `projects/{PROJECT_ID}-{project-name}/ARC-{PROJECT_ID}-AAGR-v{VERSION}.md`

**CRITICAL - Auto-Populate Document Control Fields**:

Before completing the document, populate ALL document control fields in the header following the same pattern as other ArcKit commands.

### Step 0: Detect Version

ADRs and agent designs follow the same version detection logic:

**Creating a new document** (default): Use `VERSION="1.0"`

**Updating an existing document** (user explicitly references an existing document):

1. Look for existing `ARC-{PROJECT_ID}-AAGR-v*.md` files in `projects/{project-dir}/`
2. **If no existing file**: Use VERSION="1.0"
3. **If existing file found**:
   - Read the existing document
   - **Minor increment** (e.g., 1.0 → 1.1): Same pattern — updated tools, refined guardrails
   - **Major increment** (e.g., 1.0 → 2.0): Pattern changed, fundamentally different architecture
4. Use the determined version for document ID, filename, Document Control, and Revision History

### Step 1: Populate Revision History

```markdown
| 1.0 | {DATE} | ArcKit AI | Initial creation from `$arckit-agent-design` command | [PENDING] | [PENDING] |
```

### Step 2: Populate Generation Metadata Footer

The footer should be populated with:

```markdown
**Generated by**: ArcKit `$arckit-agent-design` command
**Generated on**: {DATE} {TIME} GMT
**ArcKit Version**: {ARCKIT_VERSION}
**Project**: {PROJECT_NAME} (Project {PROJECT_ID})
**AI Model**: [Use actual model name]
**Generation Context**: [Brief note about source documents used]
```

### 12. Show summary to user (NOT full document)

```markdown
## Agent Architecture Specification Created

**Agent**: {agent_name}
**Document**: projects/{PROJECT_ID}-{project-name}/ARC-{PROJECT_ID}-AAGR-v1.0.md
**Document ID**: ARC-{PROJECT_ID}-AAGR-v1.0

### Architecture Pattern

**Pattern**: {Single Agent / Chain / Multi-Agent / Hierarchical}
**Justification**: {One-sentence rationale}

### Components

- **LLM Core**: {model} — {primary model}
- **Tool Layer**: {N} tools — {tool names}
- **Memory**: Session + Durable + Vector
- **Guardrails**: {N} guardrails — {guardrail names}

### Tool Contracts

| Tool ID | Name | Type |
|---------|------|------|
| T-001 | {name} | {type} |
| T-002 | {name} | {type} |
| T-003 | {name} | {type} |

### Memory Architecture

| Layer | Storage | Retention |
|-------|---------|-----------|
| Session | In-memory | Session only |
| Durable | {DB} | Indefinite |
| Vector | {Vector DB} | Configurable |

### Orchestration

- **Framework**: {LangGraph/CrewAI/etc}
- **Nodes**: {N} nodes in pipeline
- **Error handling**: {Strategy}

### Guardrails

| Guardrail | Type | Action |
|-----------|------|--------|
| {name} | {type} | {action} |
| {name} | {type} | {action} |

### Testing Strategy

| Test Type | Coverage | Tool |
|-----------|----------|------|
| Unit | Tool contracts | pytest |
| Integration | Agent flow | {framework} |
| Security | Prompt injection | {tool} |

### Traceability

- **AAGI**: {N} references
- **REQ**: {N} requirements traced
- **RISK**: {N} risks addressed

### Next Steps

- [ ] Review and validate architecture with stakeholders
- [ ] Create detailed designs for each component
- [ ] Set up tool contracts and MCP servers
- [ ] Implement guardrails and safety layer
- [ ] Develop testing framework
- [ ] Run `$arckit-agent-integration` for multi-agent coordination
- [ ] Run `$arckit-agent-security` for security review

### Files Created

📄 `projects/{PROJECT_ID}-{project-name}/ARC-{PROJECT_ID}-AAGR-v1.0.md` ({line_count} lines)
```

## Important Notes

- **Token Limit**: Agent designs are large documents. Always use Write tool to create the file, never output full content
- **Minimum requirements**: At least 3 tool contracts, 2 guardrails, all memory layers documented
- **Mermaid diagrams**: Must use valid syntax — C4Component for architecture, flowchart for orchestration
- **Markdown escaping**: When writing less-than or greater-than comparisons, always include a space after `<` or `>` (e.g., `< 3 seconds`, `> 99.9% uptime`) to prevent markdown renderers from interpreting them as HTML tags or emoji
- **Template customization**: Users can override the template by placing their own `agent-design-template.md` in `.arckit/templates-custom/`
- **Versioning**: Always check for existing versions before creating a new file — increment appropriately

## Suggested Next Steps

After completing this command, consider running:

- `$arckit-agent-integration` -- Design integration contracts for multi-agent systems
- `$arckit-agent-security` -- Design security architecture for agents