SKILL: ARCHITECTURE & PLANNING

Goal: Define DSP architecture, complexity assessment, and implementation strategy Trigger: /plan [Name] Input: Reads $PluginPath/.ideas/creative-brief.md and parameter-spec.md Output Location: $PluginPath/.ideas/

🎯 PHASE 2: PLAN (Architecture & Strategy)

Prerequisites:

• $PluginPath/.ideas/creative-brief.md exists
• $PluginPath/.ideas/parameter-spec.md exists
• Phase 1 (DREAM) complete

Output Files:

• $PluginPath/.ideas/architecture.md - DSP component design
• $PluginPath/.ideas/plan.md - Implementation strategy and complexity assessment

📋 STEP 1: ARCHITECTURE DEFINITION

1.1 Read Input Contracts

Read these files in parallel:

• $PluginPath/.ideas/creative-brief.md - Plugin concept and behavior
• $PluginPath/.ideas/parameter-spec.md - Parameter definitions and ranges

1.2 Define DSP Architecture

Create $PluginPath/.ideas/architecture.md with this structure:

# DSP Architecture Specification

## Core Components
List the main DSP building blocks needed:

**Example for a compressor:**
- Input gain stage
- Sidechain detection (RMS/Peak)
- Gain computer (log/linear)
- Lookahead delay buffer
- Output gain stage

**Example for a delay:**
- Input buffer management
- Delay line (circular buffer)
- Feedback processing
- Mix control
- Output processing

## Processing Chain
Define the signal flow:

Input → [Component 1] → [Component 2] → ... → Output

**Example:**

Input → Input Gain → Sidechain → Detector → Gain Computer → Lookahead → Output Gain → Output

## Parameter Mapping
Map each parameter to DSP components:

| Parameter | Component | Function | Range |
|-----------|-----------|----------|-------|
| Threshold | Detector | Sets detection level | -60dB to 0dB |
| Ratio | Gain Computer | Sets compression ratio | 1:1 to 20:1 |
| Attack | Detector | Sets attack time | 0.1ms to 100ms |

## Complexity Assessment
Rate the plugin complexity (1-5):

**Level 1 (Simple):** Basic gain, simple filter, single parameter
**Level 2 (Moderate):** Multi-parameter, basic dynamics, simple modulation
**Level 3 (Advanced):** Multi-band processing, complex algorithms, state management
**Level 4 (Expert):** Synthesis engines, complex feedback, real-time analysis
**Level 5 (Research):** Machine learning, complex modeling, advanced DSP

**Score: [1-5]**
**Rationale: [Explain the complexity factors]**

📊 STEP 2: IMPLEMENTATION PLANNING

2.1 Create Implementation Plan

Create $PluginPath/.ideas/plan.md with this structure:

# Implementation Plan

## Complexity Score: [1-5]

## Implementation Strategy

### Single-Pass Implementation (Score ≤2)
Execute all DSP components in one implementation session:
- Core processing logic
- Parameter binding
- Basic optimization

**Example for simple gain plugin:**
- Implement gain calculation
- Connect to parameter
- Add smoothing

### Phased Implementation (Score ≥3)
Break implementation into logical phases:

**Phase 2.1.1: Core Processing**
- [ ] Basic signal path
- [ ] Core DSP algorithm
- [ ] Parameter integration

**Phase 2.1.2: Optimization**
- [ ] Real-time safety
- [ ] Memory management
- [ ] Performance tuning

**Phase 2.1.3: Polish**
- [ ] Edge case handling
- [ ] State management
- [ ] Testing integration

## Dependencies
List required JUCE modules and external dependencies:

**Required JUCE Modules:**
- juce_audio_basics
- juce_audio_processors
- juce_dsp

**Optional Modules:**
- juce_gui_basics (for custom UI)
- juce_audio_formats (for file I/O)

## Risk Assessment
Identify potential implementation challenges:

**High Risk:**
- [List complex algorithms or real-time constraints]

**Medium Risk:**
- [List parameter smoothing or state management issues]

**Low Risk:**
- [List straightforward components]

🎨 STEP 3: UI FRAMEWORK SELECTION

3.1 Framework Decision

Based on the architecture complexity and plugin requirements:

Visage Framework (Recommended for):

• Simple to moderate complexity (Score 1-3)
• Performance-critical plugins
• Minimal UI requirements
• Pure C++ development preference

WebView Framework (Recommended for):

• Complex UI requirements
• Rich visualizations
• Interactive controls
• Web-based design workflow

If user has not explicitly chosen a UI framework, ask this question before deciding: "Do you want WebView2 (HTML/JS UI) or Visage (native C++) for this plugin?"

Decision: [visage/webview] Rationale: [Explain the choice based on plugin requirements]

3.1b Format Decision: CLAP (opt-in)

CLAP output is opt-in per plugin (default: VST3 + Standalone only). If the user has not stated a preference, ask:

"Also build a CLAP version of this plugin? (Loads in Bitwig, REAPER, FL Studio, Studio One and more — no extra code needed, clap-juce-extensions wraps the same AudioProcessor. Pro Tools does not load CLAP.)"

If the plugin opts in, record it in status.json via Complete-Phase/Update-PluginState:

"formats": {
  "clap": true,
  "clap_id": "<clap.id_prefix>.<plugin-slug>",
  "clap_features": ["audio-effect"]
}

• clap_id: clap.id_prefix from apc.config.json (default com.noizefield)
  • . + plugin slug, lowercase (e.g. com.noizefield.cloudwash). Must be unique and stable across versions — hosts key presets/automation to it.
• clap_features: first entry is the category:
  • effect -> audio-effect
  • synth/instrument -> instrument synthesizer
  • note/MIDI effect -> note-effect
  • analyzer -> analyzer
• The impl phase emits the clap_juce_extensions_plugin(...) block in the plugin CMakeLists with <Name>_ENABLE_CLAP ON. Build target: <Name>_CLAP.

3.2 Update Project State

Use the state management system to update project state:

Import state management:

# Import state management module
. "$PSScriptRoot\..\scripts\state-management.ps1"
$PluginPath = Get-ApcPluginPath -PluginName $PluginName

Validate prerequisites:

# Check that ideation phase is complete
if (-not (Test-PluginState -PluginPath $PluginPath -RequiredPhase "ideation_complete" -RequiredFiles @(".ideas/creative-brief.md", ".ideas/parameter-spec.md"))) {
    Write-Error "Prerequisites not met. Complete ideation phase first."
    exit 1
}

Update state with framework selection:

# Use centralized framework selection
Set-PluginFramework -PluginPath $PluginPath -Framework "[visage/webview]" -Rationale "[Explain framework choice]"

# Update state with planning completion
Complete-Phase -PluginPath $PluginPath -Phase "plan" -Updates @{
  "complexity_score" = [1-5]
  "framework_selection.implementation_strategy" = "[single-pass/phased]"
  "validation.architecture_defined" = $true
  "validation.ui_framework_selected" = $true
}

State schema after planning:

{
  "plugin_name": "[Name]",
  "version": "v0.0.0",
  "current_phase": "plan_complete",
  "ui_framework": "[visage/webview]",
  "complexity_score": [1-5],
  "created_at": "2026-01-04T20:20:00Z",
  "last_modified": "2026-01-04T20:20:00Z",
  "phase_history": [
    {
      "phase": "ideation_complete",
      "completed_at": "2026-01-04T20:20:00Z",
      "framework_selected": null
    },
    {
      "phase": "plan_complete",
      "completed_at": "2026-01-04T20:20:00Z",
      "framework_selected": "[visage/webview]"
    }
  ],
  "validation": {
    "creative_brief_exists": true,
    "parameter_spec_exists": true,
    "architecture_defined": true,
    "ui_framework_selected": true,
    "design_complete": false,
    "code_complete": false,
    "tests_passed": false,
    "ship_ready": false
  },
  "framework_selection": {
    "decision": "[visage/webview]",
    "rationale": "[Framework choice explanation]",
    "implementation_strategy": "[single-pass/phased]"
  },
  "formats": {
    "clap": false,
    "clap_id": null,
    "clap_features": []
  },
  "error_recovery": {
    "last_backup": null,
    "rollback_available": false,
    "error_log": []
  }
}

🔄 STEP 4: VALIDATION & CONTINUATION

4.1 Validation Checklist

Verify all required files exist:

• $PluginPath/.ideas/architecture.md created
• $PluginPath/.ideas/plan.md created
• $PluginPath/status.json updated with framework selection
• Complexity score assigned and justified

4.2 Decision Menu

Present user with next steps:

✓ Architecture & Planning Complete

Plugin: [Name]
Complexity: [Score]/5
Framework: [visage/webview]

What's next?
1. Start DESIGN phase - Create UI mockups and specifications
2. Review architecture - Examine DSP design and implementation plan
3. Modify plan - Adjust complexity assessment or framework choice
4. Pause here

Choose (1-4): _

4.3 Routing Logic

• Option 1: Proceed to Phase 3 (DESIGN) - invoke /apc-design (design skill)
• Option 2: Read and display architecture.md, plan.md, parameter-spec.md
• Option 3: Allow user to modify plan.md and re-run validation
• Option 4: Save state and exit skill

📚 INTEGRATION

Invoked by:

• Natural language: "Plan architecture for [Name]", "Research DSP for [Name]"
• After Phase 1 (DREAM) complete
• Manual trigger via /plan [Name]

Creates:

• $PluginPath/.ideas/architecture.md - DSP component design
• $PluginPath/.ideas/plan.md - Implementation strategy
• Updates $PluginPath/status.json - Framework selection

Next phase:

• Phase 3: DESIGN (if user chooses to continue)

⚠️ CRITICAL RULES

1. Architecture First: Always define DSP components before implementation
2. Complexity Assessment: Be honest about complexity - affects implementation approach
3. Framework Selection: Choose based on plugin requirements, not preference
4. State Management: Always update status.json with framework selection
5. Validation: Verify all contracts exist before proceeding
6. User Choice: Present clear options for continuation

🛠️ TROUBLESHOOTING

Missing creative brief:

• Error: "Creative brief required. Run /dream [Name] first."
• Solution: Ensure Phase 1 is complete

Missing parameter spec:

• Error: "Parameter specification required."
• Solution: Create parameter-spec.md from creative brief

Architecture validation fails:

• Check all required sections exist
• Verify parameter mapping is complete
• Ensure complexity score is justified

Framework selection unclear:

• Re-evaluate plugin requirements
• Consider performance vs. UI complexity trade-offs
• Default to Visage for simpler plugins