From 4584c83836d1b98ba73f020df43f6694b87b6449 Mon Sep 17 00:00:00 2001 From: Axl Ottle Date: Mon, 2 Feb 2026 14:03:00 -0600 Subject: [PATCH 1/2] fix: protect plan and solution files from review/resolve deletion The review/resolve pipeline could flag docs/plans/*.md and docs/solutions/*.md files for deletion, contradicting /workflows:work which treats them as living documents. Adds protection at three layers: - review.md: Protected Artifacts section + synthesis filter - code-simplicity-reviewer.md: YAGNI exception for pipeline artifacts - resolve_todo_parallel.md: Safety check to skip/wont_fix such todos Fixes #140 --- .../agents/review/code-simplicity-reviewer.md | 1 + .../commands/resolve_todo_parallel.md | 2 ++ .../commands/workflows/review.md | 12 ++++++++++++ 3 files changed, 15 insertions(+) diff --git a/plugins/compound-engineering/agents/review/code-simplicity-reviewer.md b/plugins/compound-engineering/agents/review/code-simplicity-reviewer.md index 9e207706..6719139a 100644 --- a/plugins/compound-engineering/agents/review/code-simplicity-reviewer.md +++ b/plugins/compound-engineering/agents/review/code-simplicity-reviewer.md @@ -33,6 +33,7 @@ When reviewing code, you will: - Eliminate extensibility points without clear use cases - Question generic solutions for specific problems - Remove "just in case" code + - **Exception: Never flag `docs/plans/*.md` or `docs/solutions/*.md` for removal.** These are compound-engineering pipeline artifacts (created by `/workflows:plan` and used as living documents by `/workflows:work`). They are intentional and permanent. 6. **Optimize for Readability**: - Prefer self-documenting code over comments diff --git a/plugins/compound-engineering/commands/resolve_todo_parallel.md b/plugins/compound-engineering/commands/resolve_todo_parallel.md index a98b5f96..680fab29 100644 --- a/plugins/compound-engineering/commands/resolve_todo_parallel.md +++ b/plugins/compound-engineering/commands/resolve_todo_parallel.md @@ -12,6 +12,8 @@ Resolve all TODO comments using parallel processing. Get all unresolved TODOs from the /todos/\*.md directory +**Protected Artifacts Check:** Before proceeding, scan each todo's proposed solution. If any todo recommends deleting, removing, or gitignoring files in `docs/plans/` or `docs/solutions/`, **skip that todo entirely** and mark it as `wont_fix`. These directories contain compound-engineering pipeline artifacts that are intentional and permanent. + ### 2. Plan Create a TodoWrite list of all unresolved items grouped by type.Make sure to look at dependencies that might occur and prioritize the ones needed by others. For example, if you need to change a name, you must wait to do the others. Output a mermaid flow diagram showing how we can do this. Can we do everything in parallel? Do we need to do one first that leads to others in parallel? I'll put the to-dos in the mermaid diagram flow‑wise so the agent knows how to proceed in order. diff --git a/plugins/compound-engineering/commands/workflows/review.md b/plugins/compound-engineering/commands/workflows/review.md index 282c9f0a..f7a478a6 100644 --- a/plugins/compound-engineering/commands/workflows/review.md +++ b/plugins/compound-engineering/commands/workflows/review.md @@ -48,6 +48,17 @@ Ensure that the code is ready for analysis (either in worktree or on current bra +#### Protected Artifacts + + +The following paths are **compound-engineering pipeline artifacts** and must NEVER be flagged for deletion, removal, or gitignore by any review agent: + +- `docs/plans/*.md` β€” Plan files created by `/workflows:plan`. These are living documents that track implementation progress (checkboxes are checked off by `/workflows:work`). They are intentional, permanent project artifacts. +- `docs/solutions/*.md` β€” Solution documents created during the pipeline. These are intentional, permanent project artifacts. + +If a review agent flags any file in these directories for cleanup/removal, **discard that finding** during synthesis. Do not create a todo for it. + + #### Parallel Agents to review the PR: @@ -207,6 +218,7 @@ Remove duplicates, prioritize by severity and impact. - [ ] Collect findings from all parallel agents +- [ ] **Discard any findings that recommend deleting or gitignoring files in `docs/plans/` or `docs/solutions/`** β€” these are protected pipeline artifacts (see Protected Artifacts section above) - [ ] Categorize by type: security, performance, architecture, quality, etc. - [ ] Assign severity levels: πŸ”΄ CRITICAL (P1), 🟑 IMPORTANT (P2), πŸ”΅ NICE-TO-HAVE (P3) - [ ] Remove duplicate or overlapping findings From 0cf7b6412e5c3983655c3ccb1882c54b62d1246c Mon Sep 17 00:00:00 2001 From: Axl Ottle Date: Mon, 2 Feb 2026 14:12:10 -0600 Subject: [PATCH 2/2] fix: protect plan and solution files from review/resolve deletion The review/resolve pipeline could flag docs/plans/*.md and docs/solutions/*.md files for deletion, contradicting /workflows:work which treats them as living documents. Adds protection at four layers: - review.md: Protected Artifacts section and synthesis filter - code-simplicity-reviewer.md: YAGNI exception for pipeline artifacts - resolve_todo_parallel.md: Skip and wont_fix todos targeting these paths - git-history-analyzer.md: Note not to characterize them as unnecessary Fixes #140 --- .../agents/research/git-history-analyzer.md | 2 ++ .../agents/review/code-simplicity-reviewer.md | 2 +- .../commands/resolve_todo_parallel.md | 2 +- .../compound-engineering/commands/workflows/review.md | 10 +++++----- 4 files changed, 9 insertions(+), 7 deletions(-) diff --git a/plugins/compound-engineering/agents/research/git-history-analyzer.md b/plugins/compound-engineering/agents/research/git-history-analyzer.md index 7a90c4dd..45da2837 100644 --- a/plugins/compound-engineering/agents/research/git-history-analyzer.md +++ b/plugins/compound-engineering/agents/research/git-history-analyzer.md @@ -40,3 +40,5 @@ When analyzing, consider: - The evolution of coding patterns and practices over time Your insights should help developers understand not just what the code does, but why it evolved to its current state, informing better decisions for future changes. + +Note that files in `docs/plans/` and `docs/solutions/` are compound-engineering pipeline artifacts created by `/workflows:plan`. They are intentional, permanent living documents β€” do not recommend their removal or characterize them as unnecessary. diff --git a/plugins/compound-engineering/agents/review/code-simplicity-reviewer.md b/plugins/compound-engineering/agents/review/code-simplicity-reviewer.md index 6719139a..63bbbb01 100644 --- a/plugins/compound-engineering/agents/review/code-simplicity-reviewer.md +++ b/plugins/compound-engineering/agents/review/code-simplicity-reviewer.md @@ -33,7 +33,7 @@ When reviewing code, you will: - Eliminate extensibility points without clear use cases - Question generic solutions for specific problems - Remove "just in case" code - - **Exception: Never flag `docs/plans/*.md` or `docs/solutions/*.md` for removal.** These are compound-engineering pipeline artifacts (created by `/workflows:plan` and used as living documents by `/workflows:work`). They are intentional and permanent. + - Never flag `docs/plans/*.md` or `docs/solutions/*.md` for removal β€” these are compound-engineering pipeline artifacts created by `/workflows:plan` and used as living documents by `/workflows:work` 6. **Optimize for Readability**: - Prefer self-documenting code over comments diff --git a/plugins/compound-engineering/commands/resolve_todo_parallel.md b/plugins/compound-engineering/commands/resolve_todo_parallel.md index 680fab29..afd653d7 100644 --- a/plugins/compound-engineering/commands/resolve_todo_parallel.md +++ b/plugins/compound-engineering/commands/resolve_todo_parallel.md @@ -12,7 +12,7 @@ Resolve all TODO comments using parallel processing. Get all unresolved TODOs from the /todos/\*.md directory -**Protected Artifacts Check:** Before proceeding, scan each todo's proposed solution. If any todo recommends deleting, removing, or gitignoring files in `docs/plans/` or `docs/solutions/`, **skip that todo entirely** and mark it as `wont_fix`. These directories contain compound-engineering pipeline artifacts that are intentional and permanent. +If any todo recommends deleting, removing, or gitignoring files in `docs/plans/` or `docs/solutions/`, skip it and mark it as `wont_fix`. These are compound-engineering pipeline artifacts that are intentional and permanent. ### 2. Plan diff --git a/plugins/compound-engineering/commands/workflows/review.md b/plugins/compound-engineering/commands/workflows/review.md index f7a478a6..e6593034 100644 --- a/plugins/compound-engineering/commands/workflows/review.md +++ b/plugins/compound-engineering/commands/workflows/review.md @@ -51,12 +51,12 @@ Ensure that the code is ready for analysis (either in worktree or on current bra #### Protected Artifacts -The following paths are **compound-engineering pipeline artifacts** and must NEVER be flagged for deletion, removal, or gitignore by any review agent: +The following paths are compound-engineering pipeline artifacts and must never be flagged for deletion, removal, or gitignore by any review agent: -- `docs/plans/*.md` β€” Plan files created by `/workflows:plan`. These are living documents that track implementation progress (checkboxes are checked off by `/workflows:work`). They are intentional, permanent project artifacts. -- `docs/solutions/*.md` β€” Solution documents created during the pipeline. These are intentional, permanent project artifacts. +- `docs/plans/*.md` β€” Plan files created by `/workflows:plan`. These are living documents that track implementation progress (checkboxes are checked off by `/workflows:work`). +- `docs/solutions/*.md` β€” Solution documents created during the pipeline. -If a review agent flags any file in these directories for cleanup/removal, **discard that finding** during synthesis. Do not create a todo for it. +If a review agent flags any file in these directories for cleanup or removal, discard that finding during synthesis. Do not create a todo for it. #### Parallel Agents to review the PR: @@ -218,7 +218,7 @@ Remove duplicates, prioritize by severity and impact. - [ ] Collect findings from all parallel agents -- [ ] **Discard any findings that recommend deleting or gitignoring files in `docs/plans/` or `docs/solutions/`** β€” these are protected pipeline artifacts (see Protected Artifacts section above) +- [ ] Discard any findings that recommend deleting or gitignoring files in `docs/plans/` or `docs/solutions/` (see Protected Artifacts above) - [ ] Categorize by type: security, performance, architecture, quality, etc. - [ ] Assign severity levels: πŸ”΄ CRITICAL (P1), 🟑 IMPORTANT (P2), πŸ”΅ NICE-TO-HAVE (P3) - [ ] Remove duplicate or overlapping findings