12 KiB

Raw Permalink Blame History

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):

Add note that friction tracking infrastructure is not yet implemented
Fix UX plugin reference path and clarify it shows planned (V2) architecture
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

12 KiB Raw Permalink Blame History