jmagly/devkit-create-agent

Create AIWG Agent

Create a new agent with AI assistance to define expertise, workflow, and capabilities.

Follows: Agent Design Bible - 10 Golden Rules for production-grade agents.

Research Foundation: REF-001 (Bandara et al.), REF-002 (Roig 2025) failure archetype prevention.

Usage

/devkit-create-agent <name> --to <target> [options]

Arguments

| Argument | Required | Description | |----------|----------|-------------| | name | Yes | Agent name (kebab-case recommended) |

Required Options

| Option | Description | |--------|-------------| | --to | Target addon or framework |

Optional Options

| Option | Description | |--------|-------------| | --template | Agent template: simple (default), complex, orchestrator | | --interactive | Enable interactive mode with guided questions |

Templates

Templates are in ~/.local/share/ai-writing-guide/templates/agent-scaffolding/.

simple (default)

Single-purpose, focused agent with minimal structure (Rule 1: Single Responsibility).

• Best for: Utility agents, single-task specialists
• Model: haiku (efficiency tier)
• Tools: Read, Write (Rule 2: Minimal Tools)

complex

Full reasoning agent with all safeguards including failure archetype prevention.

• Best for: Subject matter experts, reviewers, analysts
• Model: sonnet/opus (based on complexity)
• Tools: Read, Write, Grep (Rule 2: 0-3 tools)
• Includes: Grounding, uncertainty handling, recovery protocol

orchestrator

Multi-agent coordination with workflow patterns and agent assignment tables.

• Best for: Workflow coordinators, phase managers
• Model: opus (Rule 8: reasoning tier for coordination)
• Tools: Task only (Rule 2: single tool for delegation)

validator

Read-only validation agent that doesn't modify state.

• Best for: Quality gates, compliance checks, code review
• Model: haiku/sonnet
• Tools: Read, Grep (read-only)

Interactive Mode

When --interactive is specified, I will ask:

1. Role: What is this agent's primary role?
2. Expertise: What domains does it specialize in?
3. Responsibilities: What are its key responsibilities?
4. Tools: What tools does it need access to?
5. Workflow: How should it approach tasks?
6. Output: What format should its output take?

Examples

# Simple agent
/devkit-create-agent code-reviewer --to aiwg-utils

# Complex domain expert
/devkit-create-agent security-auditor --to sdlc-complete --template complex

# Orchestrator agent
/devkit-create-agent deployment-coordinator --to sdlc-complete --template orchestrator --interactive

Execution

1. Validate inputs: Check name and target
2. Verify target exists: Ensure addon/framework is installed
3. Select template: Use specified or default to simple
4. Gather expertise: In interactive mode, ask about domain knowledge
5. Generate agent file: Create with frontmatter and sections
6. Update manifest: Add agent to manifest.json
7. Report success: Show location and customization tips

Output Location

<target>/agents/<name>.md

Agent File Structure

---
name: agent-name
description: Agent description
model: claude-sonnet-4-6
tools: Read, Write, MultiEdit, Bash, WebFetch
---

# Agent Title

[Description]

## Expertise
[Domain knowledge]

## Responsibilities
[What the agent does]

## Workflow
[How it approaches tasks]

## Output Format
[Expected output structure]

CLI Equivalent

aiwg add-agent <name> --to <target> --template <type>

10 Golden Rules Validation

After creation, validate against the Agent Design Bible:

aiwg lint agents <target>/agents/<name>.md --verbose

| Rule | Check | |------|-------| | 1. Single Responsibility | One clear purpose, no "and" overload | | 2. Minimal Tools | 0-3 tools, justified | | 3. Explicit I/O | Inputs and outputs defined | | 4. Grounding | Verify before acting (Archetype 1) | | 5. Uncertainty | Escalate ambiguity (Archetype 2) | | 6. Context Scope | Filter distractors (Archetype 3) | | 7. Recovery | Handle errors (Archetype 4) | | 8. Model Tier | Match task complexity | | 9. Parallel Ready | Concurrent execution safe | | 10. Observable | Traceable output |

Related Commands

• /devkit-create-command - Create a slash command
• /devkit-create-skill - Create an auto-triggered skill
• /devkit-validate - Validate agent structure
• aiwg lint agents - Validate against 10 Golden Rules

References

• @$AIWG_ROOT/agentic/code/addons/aiwg-dev/README.md — aiwg-dev addon overview
• @$AIWG_ROOT/docs/extensions/extension-types.md — Extension types including agent type
• @$AIWG_ROOT/docs/cli-reference.md — CLI reference including add-agent command
• @$AIWG_ROOT/agentic/code/addons/aiwg-utils/rules/god-session.md — Single-responsibility rules for agents
• @$AIWG_ROOT/agentic/code/addons/aiwg-utils/rules/agent-deployment.md — Agent metadata structure and multi-provider deployment