# Plugin Architecture Philosophy - Review Report

## Summary

The document is well-structured and provides comprehensive guidance for building Claude Code plugins. It successfully establishes a coherent philosophy around skill orchestration, subagent delegation, and workflow composition. However, there are several gaps in implementation details (particularly around friction tracking infrastructure and phase transitions), some inconsistencies with referenced documents, and one reference to a non-existent directory structure.

## Document Reviewed

**Path:** `/home/jared/dev/cc-plugins/cc-architect/references/plugin-architecture-philosophy.md`

**Purpose:** Defines the architectural philosophy for Claude Code plugins, covering plugin hierarchy, lifecycle management, core components (skills, workflows, scripts, hooks), execution model, model selection, and anti-patterns.

**Recent additions reviewed:**
- Plugin Lifecycle section with friction tracking phases
- Command Consolidation decision tree
- Model Selection friction tracking
- Workflow Composition with UX plugin reference
- Known Issues table
- Under-scripting warnings

## Issues Found

### P0 - Blocking (must fix before using document)

**1. Friction directory does not exist**
- **Section:** Plugin Lifecycle > Friction Files (lines 43-48)
- **Problem:** The document specifies friction files live at `.claude/friction/{plugin-name}/{date}-{issue-slug}.md`, but this directory does not exist in the codebase. The friction tracking infrastructure is described but not implemented.
- **Why it matters:** Someone following this document during Active Development would try to write friction files to a location that doesn't exist, with no template or example to follow.
- **Suggested fix:** Either:
  1. Create the `.claude/friction/` directory with a README explaining the format and an example friction file, OR
  2. Add a note that friction tracking is planned but not yet implemented, with a TODO reference

**2. No definition of "reflection step" referenced**
- **Section:** Plugin Lifecycle > Active Development (line 27), Enabling/Disabling Friction Tracking (lines 61-66)
- **Problem:** The document says "Reflection step runs after every workflow execution" and "The reflection step itself is a workflow that can be attached to any skill's completion phase" but no such workflow exists, and there's no reference to where it would be defined.
- **Why it matters:** A reader cannot implement friction tracking without knowing what this reflection step looks like or how to attach it to a skill.
- **Suggested fix:** Either:
  1. Add a concrete example of what a reflection step contains and how it integrates with a skill (e.g. inline in the philosophy doc, alongside `references/self-improvement/friction-reflection.md`), OR
  2. Mark this as "planned but not implemented"

### P1 - High (fix soon)

**1. UX plugin reference path is incorrect**
- **Section:** Workflow Composition (line 98), Integration (line 235)
- **Problem:** The document references `../ux/` as the implementation reference. This is a relative path that only works from within the `references/` directory. The actual UX plugin is at `/home/jared/dev/cc-plugins/ux/`.
- **Why it matters:** Someone reading the philosophy document from a different context (e.g., main CLAUDE.md) cannot find the UX plugin.
- **Suggested fix:** Change to an absolute reference from the marketplace root: `ux/` (relative to marketplace root) with a note about where to find it.

**2. UX plugin example doesn't match actual implementation**
- **Section:** Workflow Composition (lines 92-97)
- **Problem:** The document describes three roles (UX Consultant, UX Strategist, UX Architect) with shared workflows. The actual UX plugin only implements UX Consultant in V1, with UX Strategist and UX Architect marked as "Planned for V2+".
- **Why it matters:** The example suggests a more complex multi-role implementation than exists. Readers looking at the actual plugin will be confused by the mismatch.
- **Suggested fix:** Update the example to accurately reflect V1 implementation, or add a note that the example shows the target architecture (V2+) not current state.

**3. Subagent pattern document uses different terminology**
- **Section:** Core Components > Workflows (line 86), Integration (line 232)
- **Problem:** The philosophy document references `subagent-pattern.md` and says findings go to "scratch workspace." But the actual `subagent-pattern.md` uses "scratch/" for findings, while the role-workflow pattern uses "task files." These are different mechanisms.
- **Why it matters:** Unclear whether to use scratch files or task files for subagent findings.
- **Suggested fix:** Clarify that:
  - Simple subagents can use scratch files
  - Role-Workflow pattern uses task files as shared state
  - Update `subagent-pattern.md` to mention task file pattern as an alternative or reference role-workflow pattern

**4. Missing link between "Task File Pattern" and where it's defined**
- **Section:** Plugin Checklist (line 244)
- **Problem:** Checklist item says "Task file template defined (if using task file pattern)" but doesn't link to where the task file pattern is documented.
- **Why it matters:** Reader doesn't know if they should use the task file pattern or what it entails.
- **Suggested fix:** Add a reference: "See `tool-patterns/role-workflow-pattern.md` for task file template structure"

**5. Phase transition criteria undefined**
- **Section:** Plugin Lifecycle > Phases (lines 25-38)
- **Problem:** The phases are described (Active Development, Tuned, Maintenance) but there's no guidance on when to transition between them. What makes a plugin "stable, producing reliable results"? How many sessions without friction before removing the reflection step?
- **Why it matters:** Without criteria, phase transitions become subjective and inconsistent.
- **Suggested fix:** Add concrete transition criteria:
  - Active Development → Tuned: "No P0-P1 friction for [N] executions" or "User explicitly marks as tuned"
  - Tuned → Maintenance: "No friction of any kind for [M] weeks"

### P2 - Medium (fix when convenient)

**1. Model Selection table differs from role-workflow pattern**
- **Section:** Model Selection (lines 189-205)
- **Problem:** Philosophy says "Workflow execution: Haiku." Role-workflow pattern says "Complex analysis workflows: Opus (when judgment required in workflow)." These aren't contradictory but could cause confusion about when to use Opus for subagent work.
- **Why it matters:** Developers may unnecessarily use Haiku for workflows requiring judgment, degrading results.
- **Suggested fix:** Add nuance to the Model Selection table: "Workflow execution | Haiku (mechanical), Opus (judgment-heavy)"

**2. Scripts section doesn't mention scripts directory convention**
- **Section:** Core Components > Scripts (lines 100-112)
- **Problem:** The section explains what scripts are and signs of under-scripting, but doesn't establish where scripts should live in a plugin structure.
- **Why it matters:** Without a convention, scripts end up in inconsistent locations.
- **Suggested fix:** Add: "Scripts live in `scripts/` directory at the plugin root."

**3. Hooks section missing example hooks.json**
- **Section:** Core Components > Hooks (lines 115-139)
- **Problem:** Mentions "Plugin-level: `hooks/hooks.json`" but provides no example of what this file looks like.
- **Why it matters:** Someone implementing hooks has to guess the JSON schema.
- **Suggested fix:** Either add a brief example or reference a document that shows the schema.

**4. Anti-patterns could link to positive patterns**
- **Section:** Anti-Patterns table (lines 207-218)
- **Problem:** Anti-patterns list fixes but don't link to the documents that explain the correct approach in detail.
- **Why it matters:** Readers know what not to do but may not find the detailed guidance on what to do instead.
- **Suggested fix:** Add references to each fix, e.g., "Use general subagent + workflow document (see `subagent-pattern.md`)"

**5. No example of 6-8 line dispatch**
- **Section:** Execution Model (line 213), referenced multiple times
- **Problem:** "6-8 line dispatch" is mentioned as the target, but no example is provided in this document.
- **Why it matters:** The role-workflow pattern has an example, but someone reading only the philosophy document doesn't see it.
- **Suggested fix:** Add a brief example or explicit reference: "See `tool-patterns/role-workflow-pattern.md` for dispatch template."

### P3 - Low (nice to have)

**1. "Community consensus (Jan 2026)" lacks citation**
- **Section:** General Subagents Over Custom Agents (line 168)
- **Problem:** Claims "Community consensus" but doesn't link to where this consensus was documented or discussed.
- **Why it matters:** Minor credibility issue; readers may wonder where this consensus came from.
- **Suggested fix:** Add a link to the discussion/decision record, or change to "Based on testing and team consensus"

**2. Plugin Hierarchy examples could include more context**
- **Section:** Plugin Hierarchy table (lines 5-9)
- **Problem:** Examples are single words (cc-architect, ux, commit) without brief descriptions of what they do.
- **Why it matters:** New readers don't know what these plugins are.
- **Suggested fix:** Add a brief description column or parenthetical: "cc-architect (meta-plugin for building plugins)"

**3. Known Issues table has only one entry**
- **Section:** Known Issues (lines 220-226)
- **Problem:** A single-entry table feels like placeholder content.
- **Why it matters:** Minor visual inconsistency; suggests more issues should be tracked.
- **Suggested fix:** Either populate with known issues or change format to a simple bullet point until more issues exist.

**4. Checklist could be a reusable template**
- **Section:** Plugin Checklist (lines 237-249)
- **Problem:** Checklist is embedded in the philosophy document. If it needs updates, this document must be modified.
- **Why it matters:** Checklists are operational artifacts that may need independent versioning.
- **Suggested fix:** Consider replacing the inline checklist with a pointer to `templates/audit-checklist-template.md`, which already covers plugin/skill/workflow-specific attributes and can be extended instead of duplicated.

## No Issues Found In

The following areas were reviewed and found to be clear, consistent, and well-documented:

- **Plugin Hierarchy concept** - Clear tiers with sensible dependency rules
- **Core Components > Skills (Orchestrators)** - Clear responsibilities
- **Core Components > Workflows** - Aligns well with knowledge-philosophy.md
- **Main Thread Delegates** - Clear "3 file" heuristic, good anti-bloat guidance
- **General Subagents Over Custom Agents** - Well-argued with clear migration path
- **Command Consolidation** - Comprehensive decision tree
- **knowledge-philosophy.md alignment** - Philosophy correctly defers framework knowledge to AI training
- **deterministic-scripting.md alignment** - Under-scripting warnings are consistent
- **tool-patterns/catalog.md alignment** - References are accurate and bidirectional

## Recommendations

**Immediate (before using document for new plugins):**
1. Add note that friction tracking infrastructure is not yet implemented
2. Fix UX plugin reference path and clarify it shows planned (V2) architecture
3. Add reference to role-workflow pattern for task file template

**Short-term (next documentation pass):**
4. Define phase transition criteria for Plugin Lifecycle
5. Add scripts directory convention
6. Clarify subagent findings location (scratch vs task file)
7. Add dispatch example or explicit cross-reference

**When convenient:**
8. Add example hooks.json schema
9. Link anti-patterns to positive pattern documents
10. Extract checklist to reusable template
