feat: Add Claude Code agent files as automatic installation alongside skills

[juandagalo]

📋 Pre-flight Checks

• I have searched existing issues and this is not a duplicate
• I understand this issue needs status:approved before a PR can be opened

🔍 Problem Description

Claude Code supports native agent files (~/.claude/agents/*.md) that launch as independent sub-processes with their own context, tool restrictions, and model assignments. Currently, agent-teams-lite only installs skills for Claude Code (~/.claude/skills/*/SKILL.md), which are loaded as inline context — consuming tokens and providing no control over tool permissions or model selection.

Skills alone cannot:

• Restrict which tools a sub-agent can use (disallowedTools)
• Assign specific models per phase (e.g., opus for design, sonnet for tasks)
• Be invoked as native slash commands (/sdd-explore)
• Be used programmatically via Agent(subagent_type: "sdd-explore", ...)

💡 Proposed Solution

Install 10 thin agent wrapper files (~20 lines each, ~5KB total) to ~/.claude/agents/ automatically when setting up Claude Code — alongside the existing skill installation. No user choice needed; purely additive.

Each agent .md file contains:

• YAML frontmatter: name, tools, disallowedTools, model
• A startup protocol that reads the corresponding SKILL.md at runtime

Example agent file (sdd-explore.md):

---
name: sdd-explore
description: Investigates ideas and codebase before committing to a change
tools:
  - Read
  - Glob
  - Grep
  - Bash
disallowedTools:
  - Edit
  - Write
model: opus
---

# SDD Explore Agent

## Startup Protocol
Read your skill file FIRST: `~/.claude/skills/sdd-explore/SKILL.md`
Follow it completely.

## Constraints
- Read-only exploration — no code modifications
- Save findings to engram before returning

How it integrates with the existing setup flow:

The current install_skills() function in setup.sh copies skill directories to ~/.claude/skills/. The proposal adds a new install_agents() function that runs after install_skills() — only for claude-code:

install_agents() {
    local agent_name="$1"

    # Only Claude Code supports native agent files
    [ "$agent_name" = "claude-code" ] || return 0

    local agents_src="$REPO_ROOT/agents/claude-code"
    [ -d "$agents_src" ] || return 0

    local target_dir="$HOME/.claude/agents"
    mkdir -p "$target_dir"

    local count=0
    for agent_file in "$agents_src"/sdd-*.md; do
        [ -f "$agent_file" ] || continue
        cp "$agent_file" "$target_dir/"
        count=$((count + 1))
    done
    ok "$count agent files installed → $target_dir"
}

This gets called in the existing setup_agent() function right after skills are installed:

# Existing line (~line 422):
install_skills "$skills_path" "$agent"

# New line added after:
install_agents "$agent"

What changes in the repo:

1. New directory: agents/claude-code/ with 10 agent .md files
2. scripts/setup.sh: Add install_agents() function, call it after install_skills() for claude-code
3. scripts/setup.ps1: Parallel PowerShell changes
4. scripts/install_test.sh: New test cases verifying agent installation
5. Documentation: Update README.md, docs/installation.md, docs/architecture.md

Key points:

• Skills MUST still be installed (agents reference them at startup)
• Agents are strictly additive — no existing behavior changes
• 10 files: orchestrator + 9 SDD phases (init, explore, propose, spec, design, tasks, apply, verify, archive)
• This mirrors how OpenCode already installs commands + skills + plugins — install everything the tool can use

📦 Affected Area

Scripts (setup, installation)

🔄 Alternatives Considered

1. User choice at install time ("Install as skills or agents?"): Rejected because agents are additive, not a replacement. Adding a choice adds UX friction for no benefit — both should be installed.

2. Agents as a separate --agents flag: Considered for install.sh, but for setup.sh (the recommended path), automatic installation is cleaner. Could add the flag to install.sh as a convenience.

3. Replace skills with agents entirely: Not viable — agents are thin wrappers that READ skills at startup. Skills are the source of truth for behavior; agents add execution metadata.

📎 Additional Context

I've already built and tested all 10 agent files locally. They are confirmed working as:

• ✅ User-facing slash commands (/sdd-explore, /sdd-design, etc.)
• ✅ Programmatic sub-agent types (Agent(subagent_type: "sdd-explore", ...))
• ✅ With tool restrictions and model assignments functioning correctly

The agent files are essentially a capability layer on top of skills — adding what Claude Code natively supports but skills alone can't provide. The maintenance burden is minimal since agents are ~20-line wrappers that rarely change (all logic lives in SKILL.md files).