fix(compound): prevent subagents from writing intermediary files (#150)

The /workflows:compound command was inconsistently creating intermediary
files during research phase instead of having subagents return text data
to the orchestrator.

Changes:
- Add <critical_requirement> block explicitly forbidding subagent file writes
- Restructure into clear two-phase orchestration (research → assembly)
- Remove Documentation Writer as parallel subagent (was incorrectly parallel)
- Add Phase 3 for optional enhancement agents with proper sequencing
- Add Common Mistakes table for quick reference
- Update success output to reflect new structure

Co-authored-by: Kieran Klaassen <kieranklaassen@users.noreply.github.com>

plugins/compound-engineering/commands/workflows/compound.md

@@ -21,53 +21,83 @@ Captures problem solutions while context is fresh, creating structured documenta
 /workflows:compound [brief context]    # Provide additional context hint
 ```
 
-## Execution Strategy: Parallel Subagents
+## Execution Strategy: Two-Phase Orchestration
 
-This command launches multiple specialized subagents IN PARALLEL to maximize efficiency:
+<critical_requirement>
+**Only ONE file gets written - the final documentation.**
 
-### 1. **Context Analyzer** (Parallel)
+Phase 1 subagents return TEXT DATA to the orchestrator. They must NOT use Write, Edit, or create any files. Only the orchestrator (Phase 2) writes the final documentation file.
+</critical_requirement>
+
+### Phase 1: Parallel Research
+
+<parallel_tasks>
+
+Launch these subagents IN PARALLEL. Each returns text data to the orchestrator.
+
+#### 1. **Context Analyzer**
    - Extracts conversation history
    - Identifies problem type, component, symptoms
-   - Validates against solution schema
+   - Validates against schema
    - Returns: YAML frontmatter skeleton
 
-### 2. **Solution Extractor** (Parallel)
+#### 2. **Solution Extractor**
    - Analyzes all investigation steps
    - Identifies root cause
    - Extracts working solution with code examples
    - Returns: Solution content block
 
-### 3. **Related Docs Finder** (Parallel)
+#### 3. **Related Docs Finder**
    - Searches `docs/solutions/` for related documentation
    - Identifies cross-references and links
    - Finds related GitHub issues
    - Returns: Links and relationships
 
-### 4. **Prevention Strategist** (Parallel)
+#### 4. **Prevention Strategist**
    - Develops prevention strategies
    - Creates best practices guidance
    - Generates test cases if applicable
    - Returns: Prevention/testing content
 
-### 5. **Category Classifier** (Parallel)
+#### 5. **Category Classifier**
    - Determines optimal `docs/solutions/` category
    - Validates category against schema
    - Suggests filename based on slug
    - Returns: Final path and filename
 
-### 6. **Documentation Writer** (Parallel)
+</parallel_tasks>
-   - Assembles complete markdown file
-   - Validates YAML frontmatter
-   - Formats content for readability
-   - Creates the file in correct location
 
-### 7. **Optional: Specialized Agent Invocation** (Post-Documentation)
+### Phase 2: Assembly & Write
-   Based on problem type detected, automatically invoke applicable agents:
+
-   - **performance_issue** → `performance-oracle`
+<sequential_tasks>
-   - **security_issue** → `security-sentinel`
+
-   - **database_issue** → `data-integrity-guardian`
+**WAIT for all Phase 1 subagents to complete before proceeding.**
-   - **test_failure** → `cora-test-reviewer`
+
-   - Any code-heavy issue → `kieran-rails-reviewer` + `code-simplicity-reviewer`
+The orchestrating agent (main conversation) performs these steps:
+
+1. Collect all text results from Phase 1 subagents
+2. Assemble complete markdown file from the collected pieces
+3. Validate YAML frontmatter against schema
+4. Create directory if needed: `mkdir -p docs/solutions/[category]/`
+5. Write the SINGLE final file: `docs/solutions/[category]/[filename].md`
+
+</sequential_tasks>
+
+### Phase 3: Optional Enhancement
+
+**WAIT for Phase 2 to complete before proceeding.**
+
+<parallel_tasks>
+
+Based on problem type, optionally invoke specialized agents to review the documentation:
+
+- **performance_issue** → `performance-oracle`
+- **security_issue** → `security-sentinel`
+- **database_issue** → `data-integrity-guardian`
+- **test_failure** → `cora-test-reviewer`
+- Any code-heavy issue → `kieran-rails-reviewer` + `code-simplicity-reviewer`
+
+</parallel_tasks>
 
 ## What It Captures
 
@@ -110,18 +140,25 @@ This command launches multiple specialized subagents IN PARALLEL to maximize eff
 - integration-issues/
 - logic-errors/
 
+## Common Mistakes to Avoid
+
+| ❌ Wrong | ✅ Correct |
+|----------|-----------|
+| Subagents write files like `context-analysis.md`, `solution-draft.md` | Subagents return text data; orchestrator writes one final file |
+| Research and assembly run in parallel | Research completes → then assembly runs |
+| Multiple files created during workflow | Single file: `docs/solutions/[category]/[filename].md` |
+
 ## Success Output
 
 ```
-✓ Parallel documentation generation complete
+✓ Documentation complete
 
-Primary Subagent Results:
+Subagent Results:
   ✓ Context Analyzer: Identified performance_issue in brief_system
-  ✓ Solution Extractor: Extracted 3 code fixes
+  ✓ Solution Extractor: 3 code fixes
-  ✓ Related Docs Finder: Found 2 related issues
+  ✓ Related Docs Finder: 2 related issues
-  ✓ Prevention Strategist: Generated test cases
+  ✓ Prevention Strategist: Prevention strategies, test suggestions
-  ✓ Category Classifier: docs/solutions/performance-issues/
+  ✓ Category Classifier: `performance-issues`
-  ✓ Documentation Writer: Created complete markdown
 
 Specialized Agent Reviews (Auto-Triggered):
   ✓ performance-oracle: Validated query optimization approach