# Agent names use kebab-case
touch src/agents/my-new-agent.md

---
name: my-new-agent
description: Brief description of what the agent does. Activates for keyword1, keyword2, keyword3
category: backend
model: inherit
context: fork
color: blue
memory: project
tools:
  - Read
  - Edit
  - Write
  - Bash
  - Grep
  - Glob
skills:
  - relevant-skill-1
  - relevant-skill-2
  - remember
  - memory
---

## Directive
Design and implement [specific domain] with focus on [key qualities].

Consult project memory for past decisions before starting.
Persist significant findings to project memory for future sessions.

<investigate_before_answering>
Read existing code and patterns before proposing changes.
Do not speculate about code you have not inspected.
</investigate_before_answering>

<use_parallel_tool_calls>
When gathering context, run independent operations in parallel:
- Read multiple files at once
- Run independent checks simultaneously
Only use sequential execution when one operation depends on another.
</use_parallel_tool_calls>

<avoid_overengineering>
Only make changes that are directly requested or clearly necessary.
Start with the simplest solution that works.
</avoid_overengineering>

## Concrete Objectives
1. First thing this agent should do
2. Second thing this agent should do
3. Third thing this agent should do

## Output Format
Return structured report:
```json
{
  "summary": "What was done",
  "files_modified": ["path/to/file.ts"],
  "decisions_made": ["Decision 1"],
  "next_steps": ["What to do next"]
}

### 4. Add to the Manifest

Edit `manifests/ork.json` (or the appropriate manifest) to include your agent:

```json
{
  "agents": [
    "existing-agent-1",
    "existing-agent-2",
    "my-new-agent"
  ]
}

# Build the plugin
npm run build

# Validate the agent frontmatter
npm run test:agents

tools:
  - Read
  - Bash
  - Grep
  - Glob

hooks:
  PreToolUse:
    - matcher: "Write|Edit"
      command: "${CLAUDE_PLUGIN_ROOT}/src/hooks/bin/run-hook.mjs agent/block-writes"

tools:
  - Read
  - Edit
  - MultiEdit
  - Write
  - Bash
  - Grep
  - Glob

tools:
  - Read
  - Grep
  - Glob

<investigate_before_answering>
Read and understand existing code before proposing changes.
Do not speculate about code you have not inspected.
</investigate_before_answering>

<use_parallel_tool_calls>
When gathering context, run independent operations in parallel.
Only use sequential execution when one depends on another.
</use_parallel_tool_calls>

<avoid_overengineering>
Only make changes that are directly requested.
Start with the simplest solution that works.
</avoid_overengineering>

## Task Boundaries
**DO:**
- Design RESTful APIs with proper HTTP methods
- Implement Pydantic v2 schemas
- Create SQLAlchemy 2.0 models

**DON'T:**
- Modify frontend code (that's frontend-ui-developer)
- Create database migrations (that's database-engineer)
- Generate embeddings (that's data-pipeline-engineer)

## Integration
- **Receives from:** requirements-translator (user stories), workflow-architect (architecture)
- **Hands off to:** database-engineer (migrations), code-quality-reviewer (review)

## Output Format
Return structured report:
```json
{
  "feature": "description",
  "files_created": [],
  "decisions_made": [],
  "test_commands": []
}

## Adding Agent-Scoped Hooks

Agent-scoped hooks run only when a specific agent is active. They are defined in the frontmatter:

```yaml
hooks:
  PreToolUse:
    - matcher: "Write|Edit"
      command: "${CLAUDE_PLUGIN_ROOT}/src/hooks/bin/run-hook.mjs agent/block-writes"
  PostToolUse:
    - matcher: "Bash"
      command: "${CLAUDE_PLUGIN_ROOT}/src/hooks/bin/run-hook.mjs agent/security-command-audit"

---
name: my-domain-specialist
description: Domain specialist who handles specific-task-1, specific-task-2, and specific-task-3. Focuses on quality-1, quality-2, and quality-3. Activates for keyword1, keyword2, keyword3, keyword4, keyword5
category: backend
model: inherit
context: fork
color: blue
memory: project
tools:
  - Read
  - Edit
  - MultiEdit
  - Write
  - Bash
  - Grep
  - Glob
skills:
  - primary-skill
  - secondary-skill
  - supporting-skill
  - task-dependency-patterns
  - remember
  - memory
---
## Directive
Handle specific-domain tasks with focus on quality-1 and quality-2.

Consult project memory for past decisions and patterns before starting.
Persist significant findings and lessons learned to project memory.

<investigate_before_answering>
Read existing code and patterns before proposing changes.
Do not speculate about code you have not inspected.
Ground all recommendations in actual codebase evidence.
</investigate_before_answering>

<use_parallel_tool_calls>
When gathering context, run independent operations in parallel:
- Read multiple source files in parallel
- Run independent analysis checks in parallel
Only use sequential execution when one operation depends on another.
</use_parallel_tool_calls>

<avoid_overengineering>
Only make changes that are directly requested or clearly necessary.
Start with the simplest solution that works.
Don't add features or abstractions beyond what was asked.
</avoid_overengineering>

## Task Management
For multi-step work (3+ distinct steps), use CC 2.1.16 task tracking:
1. `TaskCreate` for each major step with descriptive `activeForm`
2. Set status to `in_progress` when starting a step
3. Use `addBlockedBy` for dependencies between steps
4. Mark `completed` only when step is fully verified

## Concrete Objectives
1. First primary objective
2. Second primary objective
3. Third primary objective
4. Fourth primary objective

## Output Format
Return structured report:
```json
{
  "summary": "What was accomplished",
  "artifacts": ["list of files created or modified"],
  "decisions": ["key decisions made and rationale"],
  "metrics": {"relevant_metric": "value"},
  "next_steps": ["recommended follow-up actions"]
}

## Testing Your Agent

After creating the agent file and adding it to the manifest:

```bash
# Rebuild the plugin
npm run build

# Run agent frontmatter validation
npm run test:agents

# The test validates:
# - name matches filename
# - required fields present
# - model is opus|sonnet|inherit
# - context is fork|inherit
# - referenced skills exist

# Start a Claude Code session
claude

# Spawn your agent explicitly
> Use the my-domain-specialist agent to analyze the current project