📦 deps(thirdparty): update snapshots

2026-05-29 08:33:53 +00:00
parent fdb52f1e96
commit 06e0d13d57
1615 changed files with 232858 additions and 0 deletions
@@ -0,0 +1,86 @@
+# Stack Plugin Skill Consolidation
+
+**Date:** 2026-01-27
+**Scope:** `plugins/stack/`
+
+## Summary
+
+Consolidated 6 reference skills into 1 `outfitter-stack` skill with 8 references. Updated all workflow skills and agents to reference the new structure.
+
+**Before:** 13 skills
+**After:** 8 skills
+
+## Rationale
+
+The stack plugin had grown to include many granular reference skills for individual packages (`outfitter-cli`, `outfitter-mcp`, `outfitter-logging`, `outfitter-testing`, `outfitter-daemon`) plus the core `stack-patterns` skill. This made the skill table unwieldy and scattered related content across multiple entry points.
+
+Consolidating into a single `outfitter-stack` skill with references provides:
+- Single entry point for all Stack pattern documentation
+- Progressive disclosure via references (core patterns first, deep dives on demand)
+- Cleaner skill table in README
+- Unified trigger keywords for discovery
+
+## Changes
+
+### Created
+
+```
+plugins/stack/skills/outfitter-stack/
+├── SKILL.md                    # Core patterns (from stack-patterns)
+└── references/
+    ├── handler.md              # Handler contract details
+    ├── errors.md               # Error taxonomy details
+    ├── results.md              # Result utilities
+    ├── cli.md                  # @outfitter/cli deep dive
+    ├── mcp.md                  # @outfitter/mcp deep dive
+    ├── logging.md              # @outfitter/logging deep dive
+    ├── testing.md              # @outfitter/testing deep dive
+    └── daemon.md               # @outfitter/daemon deep dive
+```
+
+### Deleted
+
+- `plugins/stack/skills/stack-patterns/`
+- `plugins/stack/skills/outfitter-cli/`
+- `plugins/stack/skills/outfitter-mcp/`
+- `plugins/stack/skills/outfitter-logging/`
+- `plugins/stack/skills/outfitter-testing/`
+- `plugins/stack/skills/outfitter-daemon/`
+
+### Updated
+
+| File | Changes |
+|------|---------|
+| `stack-implement/SKILL.md` | Related Skills: `stack:stack-patterns` → `stack:outfitter-stack` |
+| `stack-architecture/SKILL.md` | Related Skills: `stack:stack-patterns` → `stack:outfitter-stack` |
+| `stack-review/SKILL.md` | Related Skills: `stack:stack-patterns` → `stack:outfitter-stack` |
+| `stack-debug/SKILL.md` | Related Skills: `stack:stack-patterns` → `stack:outfitter-stack` |
+| `stack-adoption/SKILL.md` | Phase refs + Related Skills updated |
+| `README.md` | Skills table rewritten, agent renamed |
+| `agents/stacker.md` | Skill routing table updated, skills list cleaned |
+
+### Agent Rename
+
+The agent was renamed from `outfitter` to `stacker`:
+- `agents/outfitter.md` → `agents/stacker.md`
+- Frontmatter `agent:` field updated in all workflow skills
+
+## Final Structure
+
+```
+plugins/stack/skills/
+├── outfitter-stack/          # Reference skill (consolidated)
+├── stack-adoption/           # Workflow: migrate to stack
+├── stack-architecture/       # Workflow: design handlers
+├── stack-debug/              # Workflow: troubleshoot issues
+├── stack-feedback/           # Workflow: report issues
+├── stack-implement/          # Workflow: TDD implementation
+├── stack-review/             # Workflow: compliance audit
+└── stack-scaffold/           # Workflow: component templates
+```
+
+## Verification
+
+- `rg "stack:outfitter-cli|stack:outfitter-mcp|stack:outfitter-logging|stack:outfitter-testing|stack:outfitter-daemon|stack:stack-patterns"` returns no matches
+- `outfitter-stack/` contains SKILL.md + 8 reference files
+- All workflow skills updated with correct `agent: stacker` frontmatter
@@ -0,0 +1,160 @@
+# Consolidation from Agentish to Outfitter
+
+**Date:** 2025-11-28
+**Context:** Migration and consolidation of Claude Code plugin development ecosystem
+
+## Background
+
+The `agentish` repo (`galligan/agentish`) was originally being built as a Claude Code marketplace for agent-driven development. During planning, we discovered:
+
+1. **Anthropic's official `plugin-dev`** plugin (from `claude-code-plugins` marketplace) already provides comprehensive creation capabilities:
+   - 7 skills for creating plugins, skills, commands, hooks, agents
+   - 3 specialized agents
+   - Well-documented and maintained
+
+2. **Existing `outfitter-dev/agents`** repo already had a `claude-dev` plugin with 13 skills covering both creation and validation
+
+3. **No plugin dependency system** exists in Claude Code - plugins are independent
+
+## Decision: Consolidate into Outfitter
+
+Rather than duplicate Anthropic's work or maintain two repos, we consolidated everything into `outfitter-dev/agents` with clear separation of concerns:
+
+### Ecosystem Architecture
+
+```
+Creating plugins/skills/etc:  Anthropic's plugin-dev (claude-code-plugins)
+Validating components:        claude-dev@outfitter
+General utilities:            outfitter@outfitter
+```
+
+## Changes Made
+
+### 1. Created `outfitter` Plugin
+
+New plugin for general-purpose development utilities:
+
+```
+outfitter/
+├── .claude-plugin/plugin.json
+├── commands/
+│   └── jam.md                    # /outfitter:jam command
+└── skills/
+    └── jam/
+        ├── SKILL.md              # Full skill (migrated from brainstorm)
+        ├── references/
+        │   ├── confidence.md     # Confidence interval deep-dive
+        │   └── questions.md      # Question crafting guidance
+        └── examples/
+            └── auth-system.md    # Example session
+```
+
+**Jam** is an adaptive Q&A workflow with confidence tracking:
+- Asks one question at a time with 2-4 options
+- Tracks confidence using emoji intervals (🚫🔴🟡🟢)
+- Delivers solution at 🟢 High confidence (≥86%)
+- Includes structured reflection after each answer
+
+### 2. Trimmed `claude-dev` Plugin
+
+Removed creation-focused skills (Anthropic's plugin-dev covers these):
+- `create-claude-command`
+- `create-claude-hook`
+- `create-claude-plugin`
+- `create-claude-skill`
+- `create-claude-subagent`
+- `distribute-claude-plugin`
+
+Kept validation and config management:
+- `validate-claude-plugin`
+- `validate-claude-command`
+- `validate-claude-hook`
+- `validate-claude-skill`
+- `validate-claude-subagent`
+- `setup-plugin-marketplace`
+- `manage-claude-config`
+
+Updated README to:
+- Focus on validation and config management
+- Recommend Anthropic's plugin-dev for creation
+- Document the complementary relationship
+
+### 3. Updated Marketplace
+
+`marketplace.json` now includes:
+- `outfitter` - General utilities (jam, etc.)
+- `claude-dev` - Validation and config management
+- `blz` - Documentation search (external source)
+
+### 4. Deprecated Agentish
+
+Updated `agentish` repo README and `CLAUDE.md`:
+- Clear deprecation notice
+- Redirect to `outfitter-dev/agents`
+- Installation instructions for new location
+
+## Installation Instructions
+
+```bash
+# Add Outfitter marketplace
+/plugin marketplace add outfitter-dev/agents
+
+# Install plugins
+/plugin install outfitter@outfitter
+/plugin install claude-dev@outfitter
+
+# For creating plugins (Anthropic's official)
+/plugin marketplace add anthropics/claude-code-plugins
+/plugin install plugin-dev@claude-code-plugins
+```
+
+## Key Concepts
+
+### Jam Skill
+
+Confidence intervals:
+- 🚫 **Unknown** (0-59): Major gaps, foundational questions needed
+- 🔴 **Low** (60-75): Significant uncertainty, key decisions pending
+- 🟡 **Medium** (76-85): Reasonable clarity, minor gaps remain
+- 🟢 **High** (86-100): Ready to deliver
+
+Workflow:
+1. Ask exactly one question with 2-4 options
+2. User responds (number, modification, or clarification)
+3. Restate understanding + update confidence
+4. Repeat until 🟢 or user requests delivery
+
+### Plugin Naming
+
+When installed, commands get namespace prefixes:
+- `/outfitter:jam` - Jam session command
+- `/claude-dev:validate:skill` - Skill validation (if nested)
+
+## Files Modified/Created
+
+**Created:**
+- `/outfitter/.claude-plugin/plugin.json`
+- `/outfitter/commands/jam.md`
+- `/outfitter/skills/jam/SKILL.md`
+- `/outfitter/skills/jam/references/confidence.md`
+- `/outfitter/skills/jam/references/questions.md`
+- `/outfitter/skills/jam/examples/auth-system.md`
+
+**Modified:**
+- `/.claude-plugin/marketplace.json`
+- `/claude-dev/README.md`
+
+**Deleted (from claude-dev/skills/):**
+- `create-claude-command/`
+- `create-claude-hook/`
+- `create-claude-plugin/`
+- `create-claude-skill/`
+- `create-claude-subagent/`
+- `distribute-claude-plugin/`
+
+## Future Considerations
+
+- The `jam` skill could be enhanced with more examples
+- Consider adding more general utilities to the `outfitter` plugin
+- May want to add CI/validation scripts to the repo
+- Could explore whether blz should be brought in-tree or kept as external reference
@@ -0,0 +1,153 @@
+# ~/.config/claude/ Inventory for Migration
+
+**Date:** 2025-11-28
+**Context:** Evaluating personal Claude Code customizations for migration to outfitter-dev/agents
+
+## Summary
+
+| Type | Count | Notable |
+|------|-------|---------|
+| Skills | 23 | Meta-tools, workflows, GitButler, Linear integration |
+| Agents | 21 | Specialist experts (security, TDD, architecture, etc.) |
+| Commands | 27 | Organized by workflow (review, sitrep, issues) |
+
+---
+
+## Skills Inventory
+
+### Agent & Skill Authoring (5 skills)
+
+- **subagent-authoring** (291 lines) - Creates/updates agents with YAML frontmatter
+- **agent-skill-authoring** (292 lines) - Creates/updates skills with progressive disclosure
+- **agent-skill-validation** (375 lines) - Validates against best practices, YAML schema
+- **agent-skill-review** (505 lines) - Reviews for discoverability, clarity, conciseness
+- **agent-validation** (305 lines) - Validates agents against best practices
+
+### Development & Workflow (6 skills)
+
+- **brainstorming** (146 lines) - Adaptive Q&A with confidence tracking → **REPLACED BY JAM**
+- **scenario-testing** (305 lines) - E2E testing instead of unit tests
+- **find-skills** (285 lines) - Skill discovery across sources → **MIGRATE AS discover-skills**
+- **agent-skill-list-flags** - Lists skill flags with grouping
+- **find-waymarks** - Code annotation search (:::) → **MIGRATE AS waymark PLUGIN**
+- **config-coderabbit** (257 lines) - CodeRabbit YAML config
+
+### Version Control & Git (5 skills) → **MIGRATE AS gitbutler PLUGIN**
+
+- **gitbutler-version-control** (483 lines) - Virtual branches for parallel work
+- **gitbutler-stack-workflows** (509 lines) - Stack creation and reorganization
+- **gitbutler-complete-branch** (620 lines) - Branch completion with safety checks
+- **gitbutler-multi-agent** (420 lines) - Multi-agent collaboration via virtual branches
+
+### Pairing & Collaboration (3 skills)
+
+- **codex-pairing** - OpenAI Codex CLI pair programming
+- **oracle-pairing** - Oracle CLI collaboration
+- **repoprompt-pairing** - RepoPrompt MCP orchestration
+
+### Project Integration (3 skills)
+
+- **implement-linear-issue** (488 lines) - End-to-end Linear issue workflow
+- **implement-pr-feedback** (529 lines) - PR feedback across Graphite stacks
+- **sitrep** - Multi-source 'check-status' reports (Graphite, GitHub, Linear)
+
+---
+
+## Agents Inventory
+
+### Tier 1: Universal, High Value (11 agents)
+
+| Agent | Purpose | Dependencies |
+|-------|---------|--------------|
+| **code-reviewer** | Tiered feedback (critical→minor) | Superpowers plugin |
+| **systematic-debugger** | Evidence-based root cause analysis | Superpowers plugin |
+| **test-driven-developer** | TDD red-green-refactor | Bun/Cargo test tools |
+| **type-safety-enforcer** | Strict TS, eliminate `any`, Ultracite | TypeScript 5.7+ |
+| **security-auditor** | Threat modeling, OWASP/CWE | Security expertise |
+| **performance-optimizer** | Profiling, benchmarking, bottlenecks | Profiling tools |
+| **senior-engineer** | Production code, features, refactoring | Language knowledge |
+| **systems-architect** | Design, tech selection, scaling | firecrawl |
+| **research-engineer** | Evidence-based recommendations | firecrawl, context7 |
+| **docs-librarian** | Documentation discovery, 70-85% compression | context7, firecrawl |
+| **safe-commit-specialist** | Atomic commits, quality gates | Git, local tools |
+
+### Tier 2: Niche but Valuable (6 agents)
+
+| Agent | Purpose | Dependencies |
+|-------|---------|--------------|
+| **complexity-challenger** | Anti-overengineering | Superpowers |
+| **bun-expert** | Bun migrations, monorepos, perf | context7 |
+| **cicd-optimization-expert** | GitHub Actions optimization | GitHub Actions |
+| **pr-review-implementer** | PR feedback across Graphite stacks | Graphite, gh |
+| **vercel-ai-sdk-expert** | AI SDK v5 streaming, agents | context7, firecrawl |
+| **status-scout** | Read-only repo SITREP | gh, Graphite |
+
+### Tier 3: Specialized (2 agents)
+
+| Agent | Purpose | Dependencies |
+|-------|---------|--------------|
+| **claude-code-expert** | Claude Code CLI/SDK/ecosystem | Research tools |
+| **gitbutler-ops** | GitButler virtual branches | GitButler CLI |
+
+### Not Ready
+
+- **test** - empty placeholder (delete)
+
+---
+
+## Migration Decisions
+
+### Confirmed for Migration
+
+1. **discover-skills** → `outfitter` plugin
+   - Rename from find-skills
+   - Skill discovery across user, project, plugin sources
+
+2. **gitbutler** → New plugin
+   - gitbutler-version-control
+   - gitbutler-stack-workflows
+   - gitbutler-complete-branch
+   - gitbutler-multi-agent
+   - gitbutler-ops agent
+
+3. **waymark** → New plugin
+   - find-waymarks skill
+
+### Under Consideration
+
+- **Agents** - Most are portable but have dependencies (Superpowers, MCP servers)
+- **Linear integration** - Could be own plugin or fold into outfitter
+- **Authoring/validation skills** - Could enhance claude-dev
+
+---
+
+## Commands Structure (for reference)
+
+```
+~/.config/claude/commands/
+├── review/           # 9 commands (code, perf, sec, deps, pr-single, etc.)
+├── sitrep/           # 4 commands (scout, stack, pr, issues)
+├── issues/           # work-on-issue
+├── recap/            # create, review
+├── init/             # use-core, use-repoprompt
+├── subagent/         # orchestrate, pair-program
+└── (root)            # skills, docs/get, ask, create-gist, test
+```
+
+---
+
+## Dependencies to Note
+
+- **Superpowers plugin** - code-reviewer, systematic-debugger, complexity-challenger delegate to superpowers:* skills
+- **MCP servers** - docs-librarian, research-engineer, bun-expert rely on context7/firecrawl
+- **Graphite** - pr-review-implementer, status-scout, sitrep use Graphite stacks
+- **GitButler** - gitbutler-* skills and gitbutler-ops agent
+
+---
+
+## Next Steps
+
+1. Create `gitbutler` plugin with 4 skills + agent
+2. Create `waymark` plugin with find-waymarks skill
+3. Add `discover-skills` to outfitter plugin
+4. Evaluate agent migration after skills are stable
@@ -0,0 +1,55 @@
+# Skill Naming Standardization
+
+**Date**: 2025-12-22
+**Scope**: All skills in `baselayer/skills/`
+
+## Summary
+
+Standardized all 18 skill names to use kebab-case consistently. Both directory names and YAML frontmatter `name:` fields now follow the same convention.
+
+## Naming Patterns Applied
+
+| Pattern | Examples |
+|---------|----------|
+| `*-dev` | bun-dev, hono-dev, react-dev, typescript-dev |
+| `*-engineering` | software-engineering, performance-engineering, security-engineering |
+| `*-authoring` / `*-check` | skills-authoring, skills-check, subagent-authoring, subagent-check |
+| Descriptive | test-driven-development, debugging-and-diagnosis, research-and-report |
+
+## Complete Rename List
+
+| Old Name | New Name |
+|----------|----------|
+| senior-developer | software-engineering |
+| architect | software-architecture |
+| expertise-performance | performance-engineering |
+| expertise-security | security-engineering |
+| typescript-development | typescript-dev |
+| dev-bun | bun-dev |
+| dev-hono | hono-dev |
+| dev-react | react-dev |
+| tdd | test-driven-development |
+| analysis | investigation |
+| fresh-eyes-review | code-review |
+| debugging | debugging-and-diagnosis |
+| challenge-complexity | complexity-analysis |
+| skill-authoring | skills-authoring |
+| skill-check | skills-check |
+| agent-authoring | subagent-authoring |
+| agent-check | subagent-check |
+| research | research-and-report |
+
+## Cross-References Updated
+
+Each rename included updates to all files referencing the old name:
+- `baselayer/README.md` — skills table
+- `baselayer/agents/*.md` — agent skill loading references
+- `.claude/rules/*.md` — SUBAGENTS.md, COMMANDS.md, FORMATTING.md
+- Other `SKILL.md` files with cross-skill references
+- `.agents/plans/` documentation
+
+## Notes
+
+- **test-driven-development** keeps "tdd" in description for discoverability
+- `subagent-*` naming aligns with Claude Code terminology (subagents vs agents)
+- `skills-*` plural form distinguishes from singular skill references
@@ -0,0 +1,428 @@
+# Agent Authoring Skill Gap Analysis
+
+**Date**: 2025-12-31
+**Sources Reviewed**:
+- <https://code.claude.com/docs/en/sub-agents> (primary subagent documentation)
+- <https://code.claude.com/docs/en/plugins-reference> (plugin components reference)
+
+**Current Skill**: `agent-kit/skills/claude-agent-authoring/`
+
+---
+
+## Executive Summary
+
+Comparison of our `claude-agent-authoring` skill against official Claude Code documentation reveals several gaps in configuration fields, recommended workflows, and advanced features. The official docs have evolved to include new capabilities (resumable agents, permission modes, skill auto-loading) that our skill doesn't cover.
+
+---
+
+## Critical Gaps
+
+### 1. Missing `permissionMode` Field
+
+**Source**: <https://code.claude.com/docs/en/sub-agents#configuration-fields>
+
+The official docs document a `permissionMode` field that controls how subagents handle permission requests:
+
+```yaml
+---
+name: agent-name
+permissionMode: default  # Optional - permission mode for the subagent
+---
+```
+
+**Valid values**:
+- `default` - Standard permission handling
+- `acceptEdits` - Auto-accept edit operations
+- `bypassPermissions` - Skip permission prompts entirely
+- `plan` - Planning mode permissions
+- `ignore` - Ignore permission requests
+
+**Impact**: Users creating automation-focused agents don't know they can configure permission behavior. This is particularly important for CI/CD agents or batch processing agents.
+
+**Our skill**: No mention of this field in SKILL.md or references/frontmatter.md.
+
+---
+
+### 2. Missing `skills` Field
+
+**Source**: <https://code.claude.com/docs/en/sub-agents#configuration-fields>
+
+> `skills` | No | Comma-separated list of skill names to auto-load when the subagent starts. Subagents do not inherit Skills from the parent conversation. If omitted, no Skills are preloaded.
+
+This is a significant gap because:
+1. **Subagents do NOT inherit skills** from the parent conversation
+2. Skills must be explicitly loaded via this field
+3. This is critical for skill-agent integration patterns
+
+**Example from docs**:
+
+```yaml
+---
+name: your-sub-agent-name
+skills: skill1, skill2  # Optional - skills to auto-load
+---
+```
+
+**Our skill**: No mention of this field. We discuss agents loading skills but don't explain that it must be configured via frontmatter, not inherited.
+
+---
+
+### 3. Missing `/agents` Command Reference
+
+**Source**: <https://code.claude.com/docs/en/sub-agents#using-the-agents-command-recommended>
+
+The official docs mark `/agents` as the **recommended** approach for agent management:
+
+> The `/agents` command provides a comprehensive interface for subagent management
+
+Features:
+- View all available subagents (built-in, user, and project)
+- Create new subagents with **guided setup**
+- Edit existing custom subagents, including their tool access
+- Delete custom subagents
+- See which subagents are active when duplicates exist
+- **Manage tool permissions** with a complete list of available tools
+
+**Key recommendation from docs**:
+> **Recommended**: generate with Claude first, then customize to make it yours
+
+**Our skill**: Focuses entirely on manual file creation. We don't mention `/agents` command at all, missing the officially recommended workflow.
+
+---
+
+### 4. Missing Resumable Subagents Feature
+
+**Source**: <https://code.claude.com/docs/en/sub-agents#resumable-subagents>
+
+This is a significant feature for long-running or multi-session work:
+
+> Subagents can be resumed to continue previous conversations, which is particularly useful for long-running research or analysis tasks that need to be continued across multiple invocations.
+
+**How it works**:
+- Each subagent execution is assigned a unique `agentId`
+- Agent conversation stored in separate transcript: `agent-{agentId}.jsonl`
+- Resume via `resume` parameter with the `agentId`
+- Agent continues with full context from previous conversation
+
+**Example workflow**:
+
+```
+> Use the code-analyzer agent to start reviewing the authentication module
+[Agent completes initial analysis and returns agentId: "abc123"]
+
+> Resume agent abc123 and now analyze the authorization logic as well
+[Agent continues with full context from previous conversation]
+```
+
+**Programmatic usage**:
+
+```json
+{
+  "description": "Continue analysis",
+  "prompt": "Now examine the error handling patterns",
+  "subagent_type": "code-analyzer",
+  "resume": "abc123"
+}
+```
+
+**Use cases**:
+- Long-running research broken into multiple sessions
+- Iterative refinement without losing context
+- Multi-step workflows with sequential context
+
+**Our skill**: No mention of resumable agents or the `resume` parameter.
+
+---
+
+### 5. Missing CLI `--agents` Flag
+
+**Source**: <https://code.claude.com/docs/en/sub-agents#cli-based-configuration>
+
+Dynamic subagent definition via CLI:
+
+```bash
+claude --agents '{
+  "code-reviewer": {
+    "description": "Expert code reviewer. Use proactively after code changes.",
+    "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
+    "tools": ["Read", "Grep", "Glob", "Bash"],
+    "model": "sonnet"
+  }
+}'
+```
+
+**Priority**: CLI-defined subagents have lower priority than project-level but higher than user-level.
+
+**Use cases**:
+- Quick testing of subagent configurations
+- Session-specific subagents that don't need to be saved
+- Automation scripts that need custom subagents
+- Sharing subagent definitions in documentation or scripts
+
+**Our skill**: No mention of CLI-based configuration.
+
+---
+
+### 6. Missing Built-in Subagents Reference
+
+**Source**: <https://code.claude.com/docs/en/sub-agents#built-in-subagents>
+
+The official docs describe three built-in subagents that users should understand:
+
+#### General-purpose Subagent
+
+- **Model**: Sonnet
+- **Tools**: All tools
+- **Mode**: Read and write, execute commands
+- **Purpose**: Complex research, multi-step operations, code modifications
+- **When used**: Tasks requiring both exploration AND modification, complex reasoning, multiple strategies needed
+
+#### Plan Subagent
+
+- **Model**: Sonnet
+- **Tools**: Read, Glob, Grep, Bash (exploration only)
+- **Purpose**: Research during plan mode
+- **When used**: Automatically in plan mode when Claude needs to research codebase
+- **Note**: Only used in plan mode, prevents infinite nesting
+
+#### Explore Subagent
+
+- **Model**: Haiku (fast, low-latency)
+- **Mode**: Strictly read-only
+- **Tools**: Glob, Grep, Read, Bash (read-only commands only)
+- **Purpose**: Fast file discovery and code exploration
+- **Thoroughness levels**: Quick, Medium, Very thorough
+
+**Why this matters**: Users should know when built-in agents suffice vs when to create custom agents.
+
+**Our skill**: No mention of built-in subagents.
+
+---
+
+## Inaccuracies
+
+### 1. File Priority Order (INCORRECT)
+
+**Source**: <https://code.claude.com/docs/en/sub-agents#file-locations>
+
+Official docs state:
+> When subagent names conflict, **project-level subagents take precedence** over user-level subagents.
+
+| Type | Location | Priority |
+|------|----------|----------|
+| Project subagents | `.claude/agents/` | **Highest** |
+| User subagents | `~/.claude/agents/` | Lower |
+
+**Our skill** (references/frontmatter.md lines 110-116):
+
+```markdown
+| Scope | Path | Priority |
+|-------|------|----------|
+| Personal | `~/.claude/agents/` | Highest |
+| Project | `<project>/agents/` | Medium |
+| Plugin | `<plugin>/agents/` | Lowest |
+```
+
+**This is backwards.** Project takes precedence over Personal/User.
+
+---
+
+### 2. Model Default Behavior (UNCLEAR)
+
+**Source**: <https://code.claude.com/docs/en/sub-agents#model-selection>
+
+Official docs clarify:
+> **Omitted**: If not specified, uses the **default model configured for subagents** (`sonnet`)
+
+The default is NOT inheritance - it's the configured subagent model (sonnet by default). `inherit` must be explicitly specified to use parent's model.
+
+**Our skill**: Implies inheritance is the default behavior, which is incorrect.
+
+---
+
+### 3. Task Tool Parameter Names (INCONSISTENT)
+
+**Source**: <https://code.claude.com/docs/en/sub-agents#resumable-subagents>
+
+Official docs show Task tool uses:
+
+```json
+{
+  "description": "Continue analysis",
+  "prompt": "Now examine the error handling patterns",
+  "subagent_type": "code-analyzer",
+  "resume": "abc123"
+}
+```
+
+**Our skill** (SKILL.md lines 449-458, references/task-tool.md) uses:
+
+```json
+{
+  "task": "Review authentication code for security vulnerabilities",
+  "subagent_type": "security-reviewer",
+  "context": [...]
+}
+```
+
+The actual parameters appear to be `prompt` and `description`, not `task` and `context`. Need to verify against actual implementation, but our docs may be using incorrect parameter names.
+
+---
+
+## Missing Best Practices
+
+### 1. "Generate with Claude First"
+
+**Source**: <https://code.claude.com/docs/en/sub-agents#best-practices>
+
+> **Start with Claude-generated agents**: We highly recommend generating your initial subagent with Claude and then iterating on it to make it personally yours. This approach gives you the best results - a solid foundation that you can customize to your specific needs.
+
+**Our skill**: Doesn't mention this approach. Focuses on manual authoring.
+
+---
+
+### 2. Proactive Invocation Hints
+
+**Source**: <https://code.claude.com/docs/en/sub-agents#automatic-delegation>
+
+> To encourage more proactive subagent use, include phrases like "use PROACTIVELY" or "MUST BE USED" in your `description` field.
+
+**Our skill**: Doesn't mention this technique for improving automatic delegation.
+
+---
+
+### 3. Agent Chaining Syntax
+
+**Source**: <https://code.claude.com/docs/en/sub-agents#chaining-subagents>
+
+Official docs show explicit chaining:
+
+```
+> First use the code-analyzer subagent to find performance issues, then use the optimizer subagent to fix them
+```
+
+**Our skill**: Has multi-agent workflow examples but doesn't show explicit user-facing chaining syntax.
+
+---
+
+## Plugin Agent Reference
+
+**Source**: <https://code.claude.com/docs/en/plugins-reference#agents>
+
+The plugins-reference shows a slightly different agent structure for plugin agents:
+
+```markdown
+---
+description: What this agent specializes in
+capabilities: ["task1", "task2", "task3"]
+---
+
+# Agent Name
+
+Detailed description of the agent's role, expertise, and when Claude should invoke it.
+
+## Capabilities
+- Specific task the agent excels at
+- Another specialized capability
+- When to use this agent vs others
+
+## Context and examples
+Provide examples of when this agent should be used and what kinds of problems it solves.
+```
+
+**Note**: Shows `capabilities` array field (possibly just example metadata, not schema).
+
+**Integration points**:
+- Agents appear in the `/agents` interface
+- Claude can invoke agents automatically based on task context
+- Agents can be invoked manually by users
+- Plugin agents work alongside built-in Claude agents
+
+---
+
+## What Our Skill Does Well
+
+1. **Agent vs Skill distinction table** - Clear differentiation (SKILL.md lines 13-24)
+2. **Description format with examples** - Good coverage of example patterns
+3. **Tool configuration philosophy** - "Don't over-restrict" guidance is solid
+4. **Validation guidance** - References claude-agent-validation skill
+5. **Troubleshooting section** - Common issues covered
+6. **Multi-agent workflow examples** - EXAMPLES.md has good orchestration patterns
+7. **Agent type patterns** - Analysis, Implementation, Review, Testing archetypes
+
+---
+
+## Recommended Improvements
+
+### High Priority
+
+1. **Add `permissionMode` field** to frontmatter documentation
+   - Document all valid values
+   - Explain use cases for each mode
+
+2. **Add `skills` field** to frontmatter documentation
+   - Emphasize that subagents DON'T inherit skills
+   - Show how to preload skills
+
+3. **Add `/agents` command section**
+   - Position as recommended approach
+   - Explain guided setup workflow
+   - "Generate with Claude first" guidance
+
+4. **Fix file priority order** in frontmatter.md
+   - Project > User (not User > Project)
+
+5. **Add resumable agents section**
+   - Explain `resume` parameter
+   - Show `agentId` usage
+   - Use cases for multi-session work
+
+### Medium Priority
+
+6. **Add built-in agents reference**
+   - Explore, Plan, General-purpose
+   - When to use vs custom agents
+
+7. **Verify Task tool parameters**
+   - Check if `prompt`/`description` vs `task`/`context`
+   - Update examples accordingly
+
+8. **Add CLI configuration section**
+   - `--agents` flag usage
+   - Testing and automation patterns
+
+9. **Clarify model default behavior**
+   - Default is sonnet, not inherited
+   - `inherit` must be explicit
+
+### Low Priority
+
+10. **Add proactive invocation hints**
+    - "PROACTIVELY" and "MUST BE USED" patterns
+
+11. **Add explicit chaining syntax examples**
+    - User-facing chaining commands
+
+---
+
+## Source Documentation Structure
+
+For reference, the official docs are structured as:
+
+**<https://code.claude.com/docs/en/sub-agents>**:
+- What are subagents?
+- Key benefits
+- Quick start
+- Subagent configuration (file locations, plugin agents, CLI config, file format, configuration fields, model selection, available tools)
+- Managing subagents (/agents command, direct file management)
+- Using subagents effectively (automatic delegation, explicit invocation)
+- Built-in subagents (general-purpose, plan, explore)
+- Example subagents (code reviewer, debugger, data scientist)
+- Best practices
+- Advanced usage (chaining, dynamic selection, resumable)
+- Performance considerations
+
+**<https://code.claude.com/docs/en/plugins-reference#agents>**:
+- Agents section under plugin components
+- File format and structure
+- Integration points
@@ -0,0 +1,140 @@
+# Superpowers Subagent Patterns
+
+Analysis of `obra/superpowers` orchestration skills for potential improvements to `baselayer/skills/subagent-coordination`.
+
+**Source**: `~/.claude/plugins/cache/superpowers-marketplace/superpowers/4.0.1/skills/`
+
+## Key Skills Reviewed
+
+### subagent-driven-development
+
+Execution workflow for implementing plans with subagents.
+
+**Core pattern**: Fresh subagent per task + two-stage review (spec then quality)
+
+**Process**:
+1. Controller reads plan, extracts all tasks with full text upfront
+2. Per task:
+   - Dispatch implementer subagent (with full task text, not file reference)
+   - Implementer asks questions if needed, then implements + tests + commits + self-reviews
+   - Dispatch spec reviewer → verify code matches spec (nothing more, nothing less)
+   - Dispatch code quality reviewer → verify implementation is well-built
+   - Both reviews loop until approved
+3. After all tasks: final code review of entire implementation
+
+**Key insight**: Controller provides context, subagents execute. Don't make subagents read plan files.
+
+### dispatching-parallel-agents
+
+When and how to parallelize subagent work.
+
+**Use when**:
+- 3+ independent failures/tasks
+- Different root causes or problem domains
+- No shared state between investigations
+- Each problem understood without context from others
+
+**Don't use when**:
+- Failures are related (fix one might fix others)
+- Need full system state understanding
+- Agents would interfere (editing same files)
+
+**Good prompts are**:
+- Focused: One clear problem domain
+- Self-contained: All context needed
+- Specific about output: What should agent return?
+
+## Comparison: Our Skill vs Superpowers
+
+| Pattern | subagent-coordination | superpowers | Gap |
+|---------|----------------------|-------------|-----|
+| Routing decisions | ✓ Primary focus | Assumes known | None |
+| Prompt templates | ✗ | ✓ Three templates | Could add |
+| Two-stage review | ✗ | ✓ Spec → Quality | Could add |
+| Parallel dispatch | Brief mention | ✓ Full skill | Could expand |
+| Controller role | Implicit | ✓ Explicit | Could clarify |
+| Process diagrams | Text-based | ✓ Dot graphs | Could add |
+| Red flags | Anti-patterns | ✓ "Never" list | Could enhance |
+
+## Patterns Worth Adopting
+
+### 1. Two-Stage Review
+
+Separate concerns:
+- **Spec compliance**: Did we build what was asked? Nothing missing, nothing extra.
+- **Code quality**: Is it well-built? Clean, tested, maintainable.
+
+Different mindsets, different reviewers. Spec first, quality second.
+
+### 2. Controller Provides Full Context
+
+Don't make subagents read plan files. Controller:
+- Extracts all tasks upfront
+- Provides full task text to each subagent
+- Includes scene-setting context (where task fits, dependencies)
+- Answers questions before subagent starts work
+
+### 3. Fresh Subagent Per Task
+
+Each task gets clean subagent. Prevents:
+- Context pollution from previous tasks
+- Confusion about what's already done
+- State leaking between tasks
+
+### 4. Prompt Templates
+
+Superpowers provides templates for:
+
+**implementer-prompt.md**:
+- Task description (full text)
+- Context (where it fits)
+- "Ask questions before starting"
+- Self-review checklist before reporting
+
+**spec-reviewer-prompt.md**:
+- What was requested (requirements)
+- What implementer claims (report)
+- "Do NOT trust the report" — verify by reading code
+- Check: missing requirements, extra work, misunderstandings
+
+**code-quality-reviewer-prompt.md**:
+- Uses code-review skill template
+- Only dispatched after spec compliance passes
+- Returns: strengths, issues (critical/important/minor), assessment
+
+### 5. Parallel Dispatch Criteria
+
+**Safe to parallelize**:
+- Independent problem domains
+- No shared files being edited
+- Each agent has complete context
+- Results can be integrated without conflicts
+
+**Not safe**:
+- Related failures (fix one might fix others)
+- Sequential dependencies
+- Shared state or resources
+
+## Potential Enhancements
+
+If we want to incorporate these patterns:
+
+1. **references/prompts.md** — Templates for implementer, spec-reviewer, code-quality-reviewer
+
+2. **references/parallel-dispatch.md** — Expand on when/how to parallelize, criteria for independence
+
+3. **Update SKILL.md**:
+   - Add two-stage review to workflow patterns
+   - Make controller role explicit
+   - Add dot diagrams for complex flows
+   - Enhance anti-patterns with specific "never" items
+
+4. **Consider**: Should we have a separate `plan-execution` skill (like superpowers' subagent-driven-development) vs our routing-focused **subagent-coordination**? Different purposes.
+
+## Notes
+
+- Superpowers is very process-oriented (how to execute)
+- Our skill is more routing-oriented (who handles what)
+- Both are valuable, potentially complementary
+- Superpowers uses dot/graphviz diagrams for flow visualization
+- "Do NOT trust the report" is a strong pattern for spec review