From 04ee7e450653a3f6f8721a128d3c372867adfcc8 Mon Sep 17 00:00:00 2001 From: Trevin Chow Date: Sun, 8 Feb 2026 15:08:59 -0800 Subject: [PATCH] fix(compound): prevent subagents from writing intermediary files (#150) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The /workflows:compound command was inconsistently creating intermediary files during research phase instead of having subagents return text data to the orchestrator. Changes: - Add 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 --- .../commands/workflows/compound.md | 91 +++++++++++++------ 1 file changed, 64 insertions(+), 27 deletions(-) diff --git a/plugins/compound-engineering/commands/workflows/compound.md b/plugins/compound-engineering/commands/workflows/compound.md index 4042685..7f647d2 100644 --- a/plugins/compound-engineering/commands/workflows/compound.md +++ b/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: + +**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. + + +### Phase 1: Parallel Research + + + +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) - - Assembles complete markdown file - - Validates YAML frontmatter - - Formats content for readability - - Creates the file in correct location + -### 7. **Optional: Specialized Agent Invocation** (Post-Documentation) - Based on problem type detected, automatically invoke applicable agents: - - **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` +### Phase 2: Assembly & Write + + + +**WAIT for all Phase 1 subagents to complete before proceeding.** + +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` + + + +### Phase 3: Optional Enhancement + +**WAIT for Phase 2 to complete before proceeding.** + + + +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` + + ## 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 - ✓ Related Docs Finder: Found 2 related issues - ✓ Prevention Strategist: Generated test cases - ✓ Category Classifier: docs/solutions/performance-issues/ - ✓ Documentation Writer: Created complete markdown + ✓ Solution Extractor: 3 code fixes + ✓ Related Docs Finder: 2 related issues + ✓ Prevention Strategist: Prevention strategies, test suggestions + ✓ Category Classifier: `performance-issues` Specialized Agent Reviews (Auto-Triggered): ✓ performance-oracle: Validated query optimization approach