/agent

Onboard new agents with profiles, system prompts (contracts), and scope boundaries for effective team collaboration.

Quick Start

Copy/agileflow:agent AGENT_ID=AG-UI ROLE="Frontend Developer" TOOLS="Read,Write,Bash" SCOPE="src/components/,frontend"

Parameters

Examples

Onboard Frontend Developer

Copy/agileflow:agent AGENT_ID=AG-UI ROLE="Frontend Developer" TOOLS="Read,Write,Edit,Bash,Glob" SCOPE="src/components/,src/pages/,frontend,ui"

Creates agent profile with:

• Role and responsibilities
• Available tools (Read, Write, Edit, Bash)
• Scope boundaries (only src/components/ and src/pages/)
• System prompt (contract) with strict rules

Onboard API Developer

Copy/agileflow:agent AGENT_ID=AG-API ROLE="Backend API Developer" TOOLS="Read,Write,Edit,Bash,Grep" SCOPE="src/api/,src/services/,backend,api"

Onboard CI/CD Specialist

Copy/agileflow:agent AGENT_ID=AG-CI ROLE="CI/CD Automation Engineer" TOOLS="Read,Write,Bash,Grep" SCOPE=".github/,scripts/,ci,devops"

Output

1. Agent Profile

Creates agent profile markdown at docs/02-practices/prompts/agents/agent-<AGENT_ID>.md

Example content:

Copy---
agent_id: AG-UI
role: Frontend Developer
tools: [Read, Write, Edit, Bash, Glob]
scope:
  directories: [src/components/, src/pages/]
  story_tags: [frontend, ui, ux]
---
 
# AG-UI: Frontend Developer Agent
 
## Responsibilities
Build and maintain user interface components with React and Tailwind CSS.
 
## Available Tools
- Read - Read files and directories
- Write - Create new files
- Edit - Modify existing files
- Bash - Run commands (npm, git)
- Glob - Search for files by pattern
 
## Scope Boundaries
 
### Allowed Directories
- `src/components/` - UI components
- `src/pages/` - Page layouts
- `public/` - Static assets
 
### Restricted Directories
- `src/api/` - Backend code
- `.github/` - CI/CD workflows
 
### Story Tags
- `frontend` - UI features
- `ui` - Component work
- `ux` - User experience
- `design` - Design implementation
 
## System Prompt (Contract)
 
### Scope Restrictions
You can ONLY modify files in:
- `src/components/**`
- `src/pages/**`
 
You CANNOT modify:
- Backend code in `src/api/`
- CI/CD workflows in `.github/`
 
### Testing Requirements
Before committing, run:
- `npm test -- src/components/` - Run component tests
- `npm run lint:css` - Check Tailwind usage
 
### Commit Message Format
Use conventional commits with `ui:` prefix:
- `feat(ui): add new button component`
- `fix(ui): correct responsive breakpoint`
- `style(ui): update component spacing`
 
### Status Updates
After completing a story:
1. Update `docs/09-agents/status.json` with new status
2. Log to `docs/09-agents/bus/log.jsonl`
3. Include completion time and any blockers
 
### Code Standards
- TypeScript required (no .js files)
- JSDoc comments on exported components
- Storybook stories for all components
- 80%+ test coverage for components
- Accessibility checks (axe-core)

2. Agent Roster

Updates or creates docs/09-agents/roster.yaml:

Copyagents:
  AG-UI:
    id: AG-UI
    role: Frontend Developer
    tools: [Read, Write, Edit, Bash, Glob]
    scope:
      directories: [src/components/, src/pages/]
      story_tags: [frontend, ui, ux]
  AG-API:
    id: AG-API
    role: Backend API Developer
    tools: [Read, Write, Edit, Bash, Grep]
    scope:
      directories: [src/api/, src/services/]
      story_tags: [backend, api, database]

3. System Prompt

Outputs a condensed system prompt to copy/paste as terminal system prompt:

CopyYou are AG-UI, a Frontend Developer Agent.
 
ROLE: Build and maintain user interface components.
 
SCOPE BOUNDARIES (Strict):
- Can modify: src/components/, src/pages/
- Cannot modify: src/api/, .github/
- Story tags: frontend, ui, ux
 
TESTING:
- Run npm test before committing
- Maintain 80%+ coverage
- Check accessibility with axe-core
 
COMMITS:
- Format: "feat(ui):" or "fix(ui):"
- Conventional commits required
 
STATUS:
- Update docs/09-agents/status.json after completing stories
- Log events to docs/09-agents/bus/log.jsonl

Agent Profile Components

Responsibilities

Clear description of what agent does:

• Specific domain (UI, API, CI/CD)
• Technologies used
• Key deliverables
• Team role

Available Tools

What the agent can use:

• Read - Read files and analyze code
• Write - Create new files
• Edit - Modify existing files
• Bash - Run shell commands (git, npm, docker)
• Glob - Find files by pattern
• Grep - Search file contents

Scope Boundaries

Where the agent can work:

• Allowed directories - Files agent can modify
• Restricted directories - Files agent CANNOT touch
• Story tags - What work gets assigned to this agent

System Prompt (Contract)

Rules agent must follow:

• Scope restrictions - Exact file paths
• Testing requirements - When/how to test
• Commit conventions - Branch and message format
• Status updates - How to track progress
• Code standards - Quality requirements

Best Practices

Naming Agents

Use descriptive IDs that clearly indicate role:

• ✅ Good: AG-UI, AG-API, AG-CI, AG-DEVOPS, AG-SECURITY
• ❌ Bad: AG-001, AG-A, AG-DEV1

Defining Scope

Make boundaries crystal clear:

Good - Specific paths:

• src/components/
• src/api/routes/
• .github/workflows/

Bad - Vague boundaries:

• "frontend stuff"
• "backend things"

Testing Requirements

Include specific test commands:

Good - Clear commands:

• Run npm test -- src/components/
• Check coverage with npm run coverage
• Lint with npm run lint:tsx

Bad - Vague instructions:

• "Write tests"
• "Make sure it works"

Story Tag Mapping

Assign stories based on tags:

Workflow

1. Gather agent details:

   • Unique ID (AG-DOMAIN)
   • Role/title
   • Available tools
   • Scope boundaries
   • Story tags

2. Create agent profile from template

   • Responsibilities section
   • Tools list
   • Scope boundaries (clear and specific)
   • System prompt (contract with rules)

3. Update agent roster

   • Add entry to docs/09-agents/roster.yaml
   • Map ID → role, tools, scope

4. Generate system prompt

   • Output condensed prompt
   • Ready to paste as terminal system prompt

5. Validate agent

   • Review scope boundaries (no conflicts)
   • Confirm testing requirements
   • Check story tag assignments

Integration

Agent profiles integrate with:

• Status tracking - Roster shows active agents
• Story assignment - Use agent ID and tags
• Capacity planning - See who's available
• Handoffs - Reference agent profiles in comms
• Scope validation - Prevent out-of-scope changes

Use When

• Onboarding new team members - Create profile and contract
• Adding specialized roles - Security, performance, accessibility agents
• Restructuring team - Update scope boundaries
• Training agents - Use system prompt as reference
• Resolving conflicts - Clear scope prevents overlap

Related Commands

• /handoff - Document work transitions between agents
• /status - View all active agents and assignments
• /babysit - Monitor agent progress
• /metrics - Agent performance metrics