# Plugin Architecture Philosophy

## Plugin Hierarchy

| Level | Scope | Examples |
|-------|-------|----------|
| High | Teams/orchestration | cc-architect |
| Medium | Domain specialists | ux, rails-dev, n8n |
| Low | Tools/services | invoice-ninja, commit, push |

Higher-level plugins may depend on lower-level. No circular dependencies.

## Plugin Lifecycle

Plugins move through phases. Friction tracking intensity varies by phase.

```
New/Changed → Active Development → Tuned → Maintenance
     ↑              |                         |
     └──────────────┴─────── (changes) ───────┘
```

### Phases

**Active Development** - New plugins or plugins with recent changes.
- Reflection step runs after every workflow execution
- Friction logged to central friction directory
- Model uncertainty documented as friction
- Expect frequent iteration

Note: The friction tracking infrastructure described here is planned for V2+. Current V1 implementation tracks friction informally.

**Tuned** - Plugin is stable, producing reliable results.
- Reflection step removed (reduces overhead)
- Friction tracking disabled
- Changes trigger return to Active Development

**Maintenance** - Long-term stable, minimal changes.
- No active friction tracking
- Major changes restart the lifecycle

### Friction Files

Friction files live at user level, outside any project:

```
~/.claude/friction/
  {plugin-name}/
    {date}-{issue-slug}.md
```

Each friction file uses YAML frontmatter for discoverability:

```yaml
---
plugin: cc-architect
skill: skill-architect
priority: P1
date: 2026-01-25
slug: audit-missing-step
---
```

Body contains:
- What happened (symptoms)
- Suspected cause
- Recommended investigation path

This separation lets friction accumulate without polluting plugin directories. User chooses when to address—urgent issues (P0-P1) get handled fast; optimization opportunities (P2-P3) wait.

### Enabling/Disabling Friction Tracking

Like inserting a debugger breakpoint:
- Add reflection step when developing or debugging a plugin
- Remove when plugin is tuned
- Re-add when making changes

The reflection step itself is a workflow that can be attached to any skill's completion phase.

## Core Components

### Skills (Orchestrators)

- Know available workflows and when to use each
- Dispatch general-purpose subagents with workflow documents
- Define reporting standards and persistence conventions
- Handle user interaction in main thread
- Do NOT execute detail work themselves

### Workflows

- Live in `workflows/` as `.md` files
- Contain: rubrics, templates, process steps
- Do NOT contain: theory, framework explanations
- Can be static (files) or dynamic (runtime-selected)
- Multiple skills/roles can dispatch the same workflow

See `knowledge-philosophy.md` for what belongs in workflows.

#### Workflow Composition

Roles dispatch workflows. Multiple roles can share workflows.

Example from UX plugin:
- **UX Consultant** (audit-focused) dispatches: heuristic evaluation, accessibility audit
- **UX Strategist** (planning-focused) dispatches: journey orchestration, feature prioritization
- **UX Architect** (system-level) dispatches: navigation model design, state-machine mapping
- **Shared workflows**: All roles might dispatch a common "reporting" workflow for consistent output format

Note: This example shows planned V2+ architecture with multiple specialized roles. Current V1 uses simpler single-role approach.

See `ux/` (marketplace root) for implementation reference.

### Scripts

- Deterministic, repeatable tasks
- Binary correctness (valid/invalid, not good/better)
- Pre-analysis before AI judgment
- Verification of work completion

**Under-scripting is a common failure mode.** When AI runs multiple deterministic commands sequentially (e.g., `git status`, `git diff`, `git log`), a script should batch them and return a structured report. Signs of under-scripting:
- AI running 3+ tool calls for data gathering that could be one script
- Same commands executed repeatedly across sessions
- Structured output parsed differently each time

See `tool-patterns/deterministic-scripting.md` for when to script.

### Hooks

Event-driven automation that runs at specific lifecycle points.

**When to use hooks:**

| Use Case | Hook Type | Example |
|----------|-----------|---------|
| Validate before execution | PreToolUse | Block writes to .env files |
| Format/lint after changes | PostToolUse | Run prettier on edited files |
| Inject session context | SessionStart | Load project-specific settings |
| Custom notifications | Notification | Desktop alerts for permissions |
| Control agent stopping | Stop, SubagentStop | Evaluate task completion |

**When NOT to use hooks:**

- Workflow logic that requires AI judgment (use subagents)
- Complex multi-step processes (use workflows)
- User interaction (use skills)

**Configuration levels:**

1. Plugin-level: `hooks/hooks.json` - applies when plugin enabled
2. Component-level: skill/agent frontmatter - scoped to component execution

**Key principle:** Hooks handle mechanical guardrails and automation. Skills handle orchestration and judgment.

## Execution Model

### Main Thread Delegates

Main thread responsibilities:
- Understand request
- Select workflow
- Create task file (if using task file pattern)
- Dispatch subagent
- Synthesize returned findings
- Present to user

Main thread does NOT:
- Read more than 3 files for workflow selection
- Execute evaluations
- Accumulate context through exploration

When exploration is needed, dispatch a subagent.

### General Subagents Over Custom Agents

**Decision:** Custom agents are relics. Use general-purpose + workflow documents.

Why:
- Same 294-token base overhead (no efficiency difference)
- More flexible (workflow docs can be composed, selected dynamically)
- No "context gatekeeping" (custom agents hide information from main thread)
- Community consensus (Jan 2026)

Migration path:
1. Extract agent logic into workflow document
2. Update skill to dispatch `general-purpose` subagent with workflow path
3. Delete agent file

### Command Consolidation

**Decision:** Skills are directly invocable with `/skill-name`. Standalone commands are redundant.

**Decision tree for existing commands:**

1. **Plugin+skill already does this** → Delete command (confirm with user first)
2. **Useful functionality, fits existing plugin** → Add as skill to that plugin, delete command
3. **Multiple related commands exist** → Create a plugin to house them as skills
   - Example: `commit` command + `repo-init` command → `git` plugin with `commit` and `repo-init` skills
4. **Doesn't fit anywhere** → Case-by-case; may warrant new plugin or remain standalone

**Do not create new standalone commands.** New functionality goes into plugins as skills.

## Model Selection

| Task | Model |
|------|-------|
| Orchestration/synthesis | Opus |
| Workflow execution | Haiku |
| Script implementation | Haiku |
| Trade-off decisions | Opus |

**Default to Opus when uncertain.**

When model choice is uncertain during Active Development phase, log as friction:
- What task triggered uncertainty
- Why Haiku seemed potentially sufficient
- Outcome (did Opus quality justify cost?)

This creates data for future model selection refinement. User can later test Haiku for that task type to evaluate cost/quality tradeoff.

## Anti-Patterns

| Anti-Pattern | Fix |
|--------------|-----|
| Custom agent proliferation | Use general subagent + workflow document |
| Main thread execution | Dispatch subagent, synthesize returned findings |
| Inline workflow content in dispatch | 6-8 line dispatch pointing to workflow path |
| Over-scripting judgment | Script validates format; AI judges quality |
| Under-scripting deterministic work | Batch sequential commands into scripts returning structured reports |
| Command-skill duplication | Delete command or migrate to plugin skill |
| Hooks for complex logic | Move to workflow document |
| Theory in workflow docs | Move to skill description or delete |

## Known Issues

Issues identified but deferred for prioritization.

| Issue | Description | Priority |
|-------|-------------|----------|
| Architect under-scripting blind spot | skill-architect and plugin-architect do not flag sequential deterministic commands as scripting opportunities (e.g., commit skill runs git commands individually instead of via script) | P1 |

## Integration

Works with:
- `knowledge-philosophy.md` - What to document
- `subagent-pattern.md` - When/how to dispatch
- `tool-patterns/role-workflow-pattern.md` - Multi-workflow orchestration
- `tool-patterns/deterministic-scripting.md` - When to script
- `ux/` (marketplace root) - Reference implementation for role-workflow pattern

## Plugin Checklist

When creating or auditing a plugin:

- [ ] Skills dispatch general subagents (no custom agents)
- [ ] Workflows in `workflows/` as `.md` files
- [ ] Scripts handle mechanical tasks (watch for under-scripting)
- [ ] Task file template defined (if using `tool-patterns/role-workflow-pattern.md`)
- [ ] Reporting standards documented
- [ ] Model selection follows table
- [ ] Commands migrated to skills or deleted
- [ ] Hooks used only for guardrails/automation (not logic)
- [ ] Friction tracking enabled (if Active Development phase)