---
name: step-00-init
description: Parse subcommand, agent name, scope, category, and resolve target directory
next_step: steps/step-01-design.md
---

# Step 0: Initialization

## MANDATORY EXECUTION RULES:
- ALWAYS parse subcommand first (create or update)
- ALWAYS validate agent name uniqueness
- ALWAYS resolve target file path before proceeding
- For UPDATE: verify agent exists before continuing

## YOUR TASK:
Parse input arguments, validate the agent name, and resolve the target file path.

---

## EXECUTION SEQUENCE:

### 1. Parse Input

```
Arguments from $ARGUMENTS:
  First word   → {subcommand} ("create" or "update")
  Second word  → {agent_name} (unique identifier)
  --scope X    → {scope} (default: "project")
  --category X → {category} (optional, for subdirectory)

Valid subcommands: create, update
Valid scopes: project, global, templates
```

If {subcommand} is missing or invalid:

```yaml
AskUserQuestion:
  header: "Action"
  question: "What do you want to do?"
  options:
    - label: "Create"
      description: "Create a new agent from scratch"
    - label: "Update"
      description: "Update an existing agent"
```

### 2. Validate Agent Name

If {agent_name} missing:

```yaml
AskUserQuestion:
  header: "Name"
  question: "What is the agent name? (unique identifier, kebab-case)"
```

Validation rules:
- Kebab-case recommended (hyphens, no spaces)
- Must be unique within scope
- Must not conflict with built-in agents (Explore, Plan, general-purpose, Bash)

### 3. Resolve Target Path

```
Based on {scope} and {category}:

  "project" →
    No category:  {target_path} = "{cwd}/.claude/agents/{agent_name}.md"
    With category: {target_path} = "{cwd}/.claude/agents/{category}/{agent_name}.md"

  "global" →
    No category:  {target_path} = "~/.claude/agents/{agent_name}.md"
    With category: {target_path} = "~/.claude/agents/{category}/{agent_name}.md"

  "templates" →
    No category:  {target_path} = "{cwd}/templates/agents/{agent_name}.md"
    With category: {target_path} = "{cwd}/templates/agents/{category}/{agent_name}.md"
```

### 4. Check Existing

**For CREATE:**
- Verify {target_path} does NOT already exist
- If exists: warn and ask to overwrite or switch to update

**For UPDATE:**
- Verify {target_path} exists
- If missing: search for agent in other locations, suggest correct path
- If found: read file and extract current frontmatter

### 5. List Existing Agents (for context)

Scan the target scope for existing agents:
```
Glob: "{target_dir}/*.md"
Glob: "{target_dir}/**/*.md"
```

Display:
```
Existing agents in {scope}:
| Name | Category | Model |
|------|----------|-------|
| {name} | {cat} | {model} |
```

### 6. Show Summary

```
Agent Configuration:

| Setting | Value |
|---------|-------|
| Action | {subcommand} |
| Name | {agent_name} |
| Scope | {scope} |
| Category | {category} |
| Target | {target_path} |

→ Designing agent...
```

---

## SUCCESS METRICS:
- Subcommand correctly identified
- Agent name validated (unique, not built-in)
- Target path resolved and checked
- Existing agents listed for context
- Summary displayed

## NEXT STEP:
After showing summary, proceed directly to `./step-01-design.md`
