/analyzing-agent-systems

name: analyzing-agent-systems
description: Scans project structure and agent system components, runs 11-category weakness analysis, and produces actionable restructuring recommendations. Use when analyzing an existing agent system for weaknesses. Use when user says "analyze agent system", "check agent setup", "audit agent config". Use when called by migrating-agent-systems or refactoring-skills.

Analyzing Agent Systems

Overview

**Analyzing agent systems IS understanding the project context, detecting weaknesses, and producing actionable restructuring recommendations.**

Scan the project structure, inventory every agent component (CLAUDE.md, rules, hooks, skills, agents), check against 11 weakness categories, generate restructuring recommendations, and produce a severity-rated report.

**Core principle:** Analyze the project first, then the agent system. Recommendations without project context are guesses.

Routing

**Pattern:** Chain **Handoff:** user-confirmation **Next:** `planning-agent-systems` (if recommendations are clear) or `brainstorming-workflows` (if more exploration needed) **Chain:** main

Task Initialization (MANDATORY)

Follow [task initialization protocol](../../references/task-initialization.md).

**Tasks:** 1. Scan project structure 2. Scan agent components 3. Run weakness analysis 4. Produce restructuring recommendations 5. Produce analysis report 6. Present findings to user

Announce: "Created 6 tasks. Starting execution..."

Task 1: Scan Project Structure

**Goal:** Understand the project before analyzing its agent system.

**Important:** Read [references/project-scanning.md](references/project-scanning.md) for the full scanning guide.

**Scan areas:**

• Language and framework detection (package.json, Cargo.toml, go.mod, pyproject.toml, etc.)
• Project type inference (monorepo, library, application, CLI tool, etc.)
• Dev workflow detection (CI/CD configs, Makefile, scripts/, etc.)
• Team scale signals (CODEOWNERS, contributing guides, PR templates, branch protection)

**Record findings in Project Overview format:**

• Primary language(s) and framework(s)
• Project type and structure
• Build and test tooling
• Dev workflow and CI/CD
• Team size signals
• Notable conventions or constraints

**Verification:** Project overview complete with all aspects filled.

Task 2: Scan Agent Components

**Goal:** Find all agent system components in the project.

**Scan locations:**

• `CLAUDE.md` (project root and `.claude/`)
• `.claude/rules/**/*.md`
• `.claude/settings.json` (hooks section)
• `.claude/skills/` or plugin skill directories
• `.claude/agents/` or subagent definitions
• `~/.claude/rules/` (user-level rules)
• `~/.claude/CLAUDE.md` (user-level constitution)
• `~/.claude/skills/` (user-level skills)
• `.cursorrules`, `.github/copilot-instructions.md`, `.windsurfrules` (other AI tool configs)
• `.editorconfig`, linter configs (conventions that should be mirrored)

**For each component found, record:**

• Type (CLAUDE.md / rule / hook / skill / agent)
• Scope (user-root / project)
• Path
• Line count
• Brief purpose (from frontmatter or first heading)

**User-root gap analysis:** Compare `~/.claude/rules/` against `.claude/rules/`:

• Which user-root rules have no project-level specialization?
• Which languages/frameworks are used in the project but have no matching rules or hooks?
• Does the project have a `settings.local.json` for sensitive data?

**Verification:** Complete inventory of all components with paths, types, and scope. Gap analysis between user-root and project level documented.

Task 3: Run Weakness Analysis

**Goal:** Check every component against the 11-category weakness checklist.

**Important:** Read [references/weakness-checklist.md](references/weakness-checklist.md) for the full 11-category checklist.

**For each weakness found, record:**

• Category (1-11)
• Severity: **CRITICAL** / **WARNING** / **INFO**
• Component affected
• Specific finding (what's wrong)
• Suggested fix (one sentence)

**Severity guidelines:** | Severity | Criteria | |----------|----------| | CRITICAL | Blocks normal operation, causes errors, security risk | | WARNING | Degrades experience, causes confusion, maintenance burden | | INFO | Minor improvement, cosmetic, nice-to-have |

**Cross-component checks:**

• Compare all skill descriptions for overlap
• Check CLAUDE.md content against rules for duplication
• Check hook coverage against rule requirements
• Verify skill chain connections are complete

**Pipeline checks:**

• Scan all skill handoff definitions, build skill call graph
• Detect chain breaks: skill A hands off to B, but B doesn't exist or doesn't accept A's output
• Detect orphan nodes: skill with no inbound handoffs and not an entry point
• Detect dead ends: skill with no handoff and no explicit termination
• Check state persistence: does each pipeline have state files/directory for recoverability?
• Classify pipeline mode: owner-pipe vs chain-pipe, check for mode mismatch

**Verification:** Every checklist item evaluated. At least one pass through each category. Pipeline checks complete.

Task 4: Produce Restructuring Recommendations

**Goal:** Transform weakness findings and project overview into actionable recommendations.

**Important:** Read [references/restructuring-guide.md](references/restructuring-guide.md) for the full recommendation guide.

**Generate recommendations by type:**

**Merge recommendations:**

• Overlapping skills that should be consolidated
• Redundant rules covering the same concern
• Duplicate content across CLAUDE.md and rules

**Extract recommendations:**

• CLAUDE.md sections that should be extracted to rules (scoped or global)
• Monolithic rules that should be split by concern

**Pipeline recommendations:**

• Pipeline design based on project type (monorepo vs single-app vs library)
• Pipeline mode selection (owner-pipe vs chain-pipe) with rationale
• State persistence strategy for recoverability

**Traceabili