cc-os/plugins/cc-architect/references/plugin-architecture-philosophy.md

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:

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