@every-env/compound-plugin 0.1.1 → 0.2.0

package/.claude/commands/triage-prs.md

@@ -0,0 +1,193 @@
+---
+name: triage-prs
+description: Triage all open PRs with parallel agents, label, group, and review one-by-one
+argument-hint: "[optional: repo owner/name or GitHub PRs URL]"
+disable-model-invocation: true
+allowed-tools: Bash(gh *), Bash(git log *)
+---
+
+# Triage Open Pull Requests
+
+Review, label, and act on all open PRs for a repository using parallel review agents. Produces a grouped triage report, applies labels, cross-references with issues, and walks through each PR for merge/comment decisions.
+
+## Step 0: Detect Repository
+
+Detect repo context:
+- Current repo: !`gh repo view --json nameWithOwner -q .nameWithOwner 2>/dev/null || echo "no repo detected"`
+- Current branch: !`git branch --show-current 2>/dev/null`
+
+If `$ARGUMENTS` contains a GitHub URL or `owner/repo`, use that instead. Confirm the repo with the user if ambiguous.
+
+## Step 1: Gather Context (Parallel)
+
+Run these in parallel:
+
+1. **List all open PRs:**
+   ```bash
+   gh pr list --repo OWNER/REPO --state open --limit 50
+   ```
+
+2. **List all open issues:**
+   ```bash
+   gh issue list --repo OWNER/REPO --state open --limit 50
+   ```
+
+3. **List existing labels:**
+   ```bash
+   gh label list --repo OWNER/REPO --limit 50
+   ```
+
+4. **Check recent merges** (to detect duplicate/superseded PRs):
+   ```bash
+   git log --oneline -20 main
+   ```
+
+## Step 2: Batch PRs by Theme
+
+Group PRs into review batches of 4-6 based on apparent type:
+
+- **Bug fixes** - titles with `fix`, `bug`, error descriptions
+- **Features** - titles with `feat`, `add`, new functionality
+- **Documentation** - titles with `docs`, `readme`, terminology
+- **Configuration/Setup** - titles with `config`, `setup`, `install`
+- **Stale/Old** - PRs older than 30 days
+
+## Step 3: Parallel Review (Team of Agents)
+
+Spawn one review agent per batch using the Task tool. Each agent should:
+
+For each PR in their batch:
+1. Run `gh pr view --repo OWNER/REPO <number> --json title,body,files,additions,deletions,author,createdAt`
+2. Run `gh pr diff --repo OWNER/REPO <number>` (pipe to `head -200` for large diffs)
+3. Determine:
+   - **Description:** 1-2 sentence summary of the change
+   - **Label:** Which existing repo label fits best
+   - **Action:** merge / request changes / close / needs discussion
+   - **Related PRs:** Any PRs in this or other batches that touch the same files or feature
+   - **Quality notes:** Code quality, test coverage, staleness concerns
+
+Instruct each agent to:
+- Flag PRs that touch the same files (potential merge conflicts)
+- Flag PRs that duplicate recently merged work
+- Flag PRs that are part of a group solving the same problem differently
+- Report findings as a markdown table
+- Send findings back via message when done
+
+## Step 4: Cross-Reference Issues
+
+After all agents report, match issues to PRs:
+
+- Check if any PR title/body mentions `Fixes #X` or `Closes #X`
+- Check if any issue title matches a PR's topic
+- Look for duplicate issues (same bug reported twice)
+
+Build a mapping table:
+```
+| Issue | PR | Relationship |
+|-------|-----|--------------|
+| #158  | #159 | PR fixes issue |
+```
+
+## Step 5: Identify Themes
+
+Group all issues into themes (3-6 themes):
+- Count issues per theme
+- Note which themes have PRs addressing them and which don't
+- Flag themes with competing/overlapping PRs
+
+## Step 6: Compile Triage Report
+
+Present a single report with:
+
+1. **Summary stats:** X open PRs, Y open issues, Z themes
+2. **PR groups** with recommended actions:
+   - Group name and related PRs
+   - Per-PR: #, title, author, description, label, action
+3. **Issue-to-PR mapping**
+4. **Themes across issues**
+5. **Suggested cleanup:** spam issues, duplicates, stale items
+
+## Step 7: Apply Labels
+
+After presenting the report, ask user:
+
+> "Apply these labels to all PRs on GitHub?"
+
+If yes, run `gh pr edit --repo OWNER/REPO <number> --add-label "<label>"` for each PR.
+
+## Step 8: One-by-One Review
+
+Use **AskUserQuestion** to ask:
+
+> "Ready to walk through PRs one-by-one for merge/comment decisions?"
+
+Then for each PR, ordered by priority (bug fixes first, then docs, then features, then stale):
+
+### Show the PR:
+
+```
+### PR #<number> - <title>
+Author: <author> | Files: <count> | +<additions>/-<deletions> | <age>
+Label: <label>
+
+<1-2 sentence description>
+
+Fixes: <linked issues if any>
+Related: <related PRs if any>
+```
+
+Show the diff (trimmed to key changes if large).
+
+### Ask for decision:
+
+Use **AskUserQuestion**:
+- **Merge** - Merge this PR now
+- **Comment & skip** - Leave a comment explaining why not merging, keep open
+- **Close** - Close with a comment
+- **Skip** - Move to next without action
+
+### Execute decision:
+
+- **Merge:** `gh pr merge --repo OWNER/REPO <number> --squash`
+  - If PR fixes an issue, close the issue too
+- **Comment & skip:** `gh pr comment --repo OWNER/REPO <number> --body "<comment>"`
+  - Ask user what to say, or generate a grateful + specific comment
+- **Close:** `gh pr close --repo OWNER/REPO <number> --comment "<reason>"`
+- **Skip:** Move on
+
+## Step 9: Post-Merge Cleanup
+
+After all PRs are reviewed:
+
+1. **Close resolved issues** that were fixed by merged PRs
+2. **Close spam/off-topic issues** (confirm with user first)
+3. **Summary of actions taken:**
+   ```
+   ## Triage Complete
+
+   Merged: X PRs
+   Commented: Y PRs
+   Closed: Z PRs
+   Skipped: W PRs
+
+   Issues closed: A
+   Labels applied: B
+   ```
+
+## Step 10: Post-Triage Options
+
+Use **AskUserQuestion**:
+
+1. **Run `/release-docs`** - Update documentation site if components changed
+2. **Run `/changelog`** - Generate changelog for merged PRs
+3. **Commit any local changes** - If version bumps needed
+4. **Done** - Wrap up
+
+## Important Notes
+
+- **DO NOT merge without user approval** for each PR
+- **DO NOT force push or destructive actions**
+- Comments on declined PRs should be grateful and constructive
+- When PRs conflict with each other, note this and suggest merge order
+- When multiple PRs solve the same problem differently, flag for user to pick one
+- Use Haiku model for review agents to save cost (they're doing read-only analysis)

package/.claude-plugin/marketplace.json

@@ -11,8 +11,8 @@
   "plugins": [
     {
       "name": "compound-engineering",
-      "description": "AI-powered development tools that get smarter with every use. Make each unit of engineering work easier than the last. Includes 28 specialized agents, 24 commands, and 15 skills.",
-      "version": "2.28.0",
+      "description": "AI-powered development tools that get smarter with every use. Make each unit of engineering work easier than the last. Includes 29 specialized agents, 25 commands, and 16 skills.",
+      "version": "2.30.0",
       "author": {
         "name": "Kieran Klaassen",
         "url": "https://github.com/kieranklaassen",

package/.github/workflows/ci.yml

@@ -0,0 +1,25 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Install dependencies
+        run: bun install
+
+      - name: Run tests
+        run: bun test

package/README.md

@@ -1,5 +1,8 @@
 # Compound Marketplace
 
+[![Build Status](https://github.com/EveryInc/compound-engineering-plugin/actions/workflows/ci.yml/badge.svg)](https://github.com/EveryInc/compound-engineering-plugin/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/@every-env/compound-plugin)](https://www.npmjs.com/package/@every-env/compound-plugin)
+
 A Claude Code plugin marketplace featuring the **Compound Engineering Plugin** — tools that make each unit of engineering work easier than the last.
 
 ## Claude Code Install
@@ -27,10 +30,28 @@ Local dev:
 bun run src/index.ts install ./plugins/compound-engineering --to opencode
 ```
 
-OpenCode output is written to `~/.opencode` by default, with `opencode.json` at the root and `agents/`, `skills/`, and `plugins/` alongside it.
+OpenCode output is written to `~/.config/opencode` by default, with `opencode.json` at the root and `agents/`, `skills/`, and `plugins/` alongside it.
 Both provider targets are experimental and may change as the formats evolve.
 Codex output is written to `~/.codex/prompts` and `~/.codex/skills`, with each Claude command converted into both a prompt and a skill (the prompt instructs Codex to load the corresponding skill). Generated Codex skill descriptions are truncated to 1024 characters (Codex limit).
 
+## Sync Personal Config
+
+Sync your personal Claude Code config (`~/.claude/`) to OpenCode or Codex:
+
+```bash
+# Sync skills and MCP servers to OpenCode
+bunx @every-env/compound-plugin sync --target opencode
+
+# Sync to Codex
+bunx @every-env/compound-plugin sync --target codex
+```
+
+This syncs:
+- Personal skills from `~/.claude/skills/` (as symlinks)
+- MCP servers from `~/.claude/settings.json`
+
+Skills are symlinked (not copied) so changes in Claude Code are reflected immediately.
+
 ## Workflow
 
 ```

package/docs/plans/2026-02-08-feat-pr-triage-and-merge-plan.md

@@ -0,0 +1,128 @@
+---
+title: PR Triage, Review & Merge
+type: feat
+date: 2026-02-08
+---
+
+# PR Triage, Review & Merge
+
+## Overview
+
+Review all 17 open PRs one-by-one. Merge the ones that look good, leave constructive comments on the ones we won't take (keeping them open for contributors to address). Close duplicates/spam.
+
+## Approach
+
+Show the diff for each PR, get a go/no-go, then either merge or comment. PRs are ordered by priority group.
+
+## Group 1: Bug Fixes (high confidence merges)
+
+### PR #159 - fix(git-worktree): detect worktrees where .git is a file
+- **Author:** dalley | **Files:** 1 | **+2/-2**
+- **What:** Changes `-d` to `-e` check in `worktree-manager.sh` so `list` and `cleanup` detect worktrees (`.git` is a file in worktrees, not a dir)
+- **Fixes:** Issue #158
+- **Action:** Review diff → merge
+
+### PR #144 - Remove confirmation prompt when creating git worktrees
+- **Author:** XSAM | **Files:** 1 | **+0/-8**
+- **What:** Removes interactive `read -r` confirmation that breaks Claude's ability to create worktrees
+- **Related:** Same file as #159 (merge #159 first)
+- **Action:** Review diff → merge
+
+### PR #150 - fix(compound): prevent subagents from writing intermediary files
+- **Author:** tmchow | **Files:** 1 | **+64/-27**
+- **What:** Restructures `/workflows:compound` into 2-phase orchestration to prevent subagents from writing temp files
+- **Action:** Review diff → merge
+
+### PR #148 - Fix: resolve_pr_parallel uses non-existent scripts
+- **Author:** ajrobertsonio | **Files:** 1 | **+20/-7**
+- **What:** Replaces references to non-existent `bin/get-pr-comments` with standard `gh` CLI commands
+- **Fixes:** Issues #147, #54
+- **Action:** Review diff → merge
+
+## Group 2: Documentation (clean, low-risk)
+
+### PR #133 - Fix terminology: third person → passive voice
+- **Author:** FauxReal9999 | **Files:** 13 | docs-only
+- **What:** Corrects "third person" to "passive voice" across docs (accurate fix)
+- **Action:** Review diff → merge
+
+### PR #108 - Note new repository URL
+- **Author:** akx | **Files:** 5 | docs-only
+- **What:** Updates URLs from `kieranklaassen/compound-engineering-plugin` to `EveryInc/compound-engineering-plugin`
+- **Action:** Review diff → merge
+
+### PR #113 - docs: add brainstorm command to workflow documentation
+- **Author:** tmchow | docs-only
+- **What:** Adds brainstorming skill and learnings-researcher agent to README, fixes component counts
+- **Action:** Review diff → merge
+
+### PR #80 - docs: Add LSP prioritization guidance
+- **Author:** kevinold | **Files:** 1 | docs-only
+- **What:** Adds docs showing users how to customize agent behavior via project CLAUDE.md to prioritize LSP
+- **Action:** Review diff → merge
+
+## Group 3: Enhancements (likely merge)
+
+### PR #119 - fix: backup existing config files before overwriting
+- **Author:** jzw | **Files:** 5 | **+90/-3** | has tests
+- **What:** Adds `backupFile()` utility to create timestamped backups before overwriting Codex/OpenCode configs
+- **Fixes:** Issue #125
+- **Action:** Review diff → merge
+
+### PR #112 - feat(skills): add document-review skill
+- **Author:** tmchow | enhancement
+- **What:** Adds document-review skill for brainstorm/plan refinement, renames `/plan_review` → `/technical_review`
+- **Note:** Breaking rename - needs review
+- **Action:** Review diff → decide
+
+## Group 4: Needs Discussion (comment and leave open)
+
+### PR #157 - Rewrite workflows:review with context-managed map-reduce
+- **Author:** Drewx-Design | large rewrite
+- **What:** Complete rewrite of review command with file-based map-reduce architecture
+- **Comment:** Acknowledge quality, note it's a big change that needs dedicated review session
+
+### PR #131 - feat: add vmark-mcp plugin
+- **Author:** xiaolai | new plugin
+- **What:** Adds entirely new VMark markdown editor plugin to marketplace
+- **Comment:** Ask for more context on fit with marketplace scope
+
+### PR #124 - feat(commands): add /compound-engineering-setup
+- **Author:** internal | config
+- **What:** Interactive setup command for configuring review agents per project
+- **Comment:** Note overlap with #103, needs unified config strategy
+
+### PR #123 - feat: Add sync command for Claude Code personal config
+- **Author:** terry-li-hm | config
+- **What:** Sync personal Claude config across machines/editors
+- **Comment:** Note overlap with #124 and #103, needs unified config strategy
+
+### PR #103 - Add /compound:configure with persistent user preferences
+- **Author:** aviflombaum | **+36,866** lines
+- **What:** Massive architectural change adding persistent config with build system
+- **Comment:** Too large, suggest breaking into smaller PRs
+
+## Group 5: Close
+
+### PR #122 - [EXPERIMENTAL] add /slfg and /swarm-status
+- **Label:** duplicate
+- **What:** Already merged in v2.30.0 (commit e4ff6a8)
+- **Action:** Comment explaining it's been superseded, close
+
+### PR #68 - Improve all 13 skills to 90%+ grades
+- **Label:** wontfix
+- **What:** Massive stale PR (Jan 6), based on 13 skills when we now have 16+
+- **Action:** Comment thanking contributor, suggest fresh PR against current main, close
+
+## Post-Merge Cleanup
+
+After merging:
+- [ ] Close issues fixed by merged PRs (#158, #147, #54, #125)
+- [ ] Close spam issues (#98, #56)
+- [ ] Run `/release-docs` to update documentation site with new component counts
+- [ ] Bump version in plugin.json if needed
+
+## References
+
+- PR list: https://github.com/EveryInc/compound-engineering-plugin/pulls
+- Issues: https://github.com/EveryInc/compound-engineering-plugin/issues

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@every-env/compound-plugin",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "type": "module",
   "private": false,
   "bin": {

package/plans/grow-your-own-garden-plugin-architecture.md

@@ -1,6 +1,6 @@
 # Grow Your Own Garden: Adaptive Agent Ecosystem
 
-> **Issue:** https://github.com/kieranklaassen/compound-engineering-plugin/issues/20
+> **Issue:** https://github.com/EveryInc/compound-engineering-plugin/issues/20
 
 ## The Idea
 

package/plugins/compound-engineering/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "compound-engineering",
-  "version": "2.28.0",
-  "description": "AI-powered development tools. 28 agents, 24 commands, 15 skills, 1 MCP server for code review, research, design, and workflow automation.",
+  "version": "2.30.0",
+  "description": "AI-powered development tools. 29 agents, 25 commands, 16 skills, 1 MCP server for code review, research, design, and workflow automation.",
   "author": {
     "name": "Kieran Klaassen",
     "email": "kieran@every.to",

package/plugins/compound-engineering/CHANGELOG.md

@@ -5,6 +5,38 @@ All notable changes to the compound-engineering plugin will be documented in thi
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.30.0] - 2026-02-05
+
+### Added
+
+- **`orchestrating-swarms` skill** - Comprehensive guide to multi-agent orchestration
+  - Covers primitives: Agent, Team, Teammate, Leader, Task, Inbox, Message, Backend
+  - Documents two spawning methods: subagents vs teammates
+  - Explains all 13 TeammateTool operations
+  - Includes orchestration patterns: Parallel Specialists, Pipeline, Self-Organizing Swarm
+  - Details spawn backends: in-process, tmux, iterm2
+  - Provides complete workflow examples
+- **`/slfg` command** - Swarm-enabled variant of `/lfg` that uses swarm mode for parallel execution
+
+### Changed
+
+- **`/workflows:work` command** - Added optional Swarm Mode section for parallel execution with coordinated agents
+
+---
+
+## [2.29.0] - 2026-02-04
+
+### Added
+
+- **`schema-drift-detector` agent** - Detects unrelated schema.rb changes in PRs
+  - Compares schema.rb diff against migrations in the PR
+  - Catches columns, indexes, and tables from other branches
+  - Prevents accidental inclusion of local database state
+  - Provides clear fix instructions (checkout + migrate)
+  - Essential pre-merge check for any PR with database changes
+
+---
+
 ## [2.28.0] - 2026-01-21
 
 ### Added

package/plugins/compound-engineering/CLAUDE.md

@@ -59,7 +59,7 @@ When adding or modifying skills, verify compliance with skill-creator spec:
 ### YAML Frontmatter (Required)
 
 - [ ] `name:` present and matches directory name (lowercase-with-hyphens)
-- [ ] `description:` present and uses **third person** ("This skill should be used when..." NOT "Use this skill when...")
+- [ ] `description:` present and describes **what it does and when to use it** (per official spec: "Explains code with diagrams. Use when exploring how code works.")
 
 ### Reference Links (Required if references/ exists)
 
@@ -80,9 +80,8 @@ When adding or modifying skills, verify compliance with skill-creator spec:
 grep -E '`(references|assets|scripts)/[^`]+`' skills/*/SKILL.md
 # Should return nothing if all refs are properly linked
 
-# Check description format
-grep -E '^description:' skills/*/SKILL.md | grep -v 'This skill'
-# Should return nothing if all use third person
+# Check description format - should describe what + when
+grep -E '^description:' skills/*/SKILL.md
 ```
 
 ## Documentation

package/plugins/compound-engineering/README.md

@@ -6,16 +6,16 @@ AI-powered development tools that get smarter with every use. Make each unit of
 
 | Component | Count |
 |-----------|-------|
-| Agents | 27 |
-| Commands | 20 |
-| Skills | 14 |
+| Agents | 29 |
+| Commands | 25 |
+| Skills | 16 |
 | MCP Servers | 1 |
 
 ## Agents
 
 Agents are organized into categories for easier discovery.
 
-### Review (14)
+### Review (15)
 
 | Agent | Description |
 |-------|-------------|
@@ -26,21 +26,23 @@ Agents are organized into categories for easier discovery.
 | `data-migration-expert` | Validate ID mappings match production, check for swapped values |
 | `deployment-verification-agent` | Create Go/No-Go deployment checklists for risky data changes |
 | `dhh-rails-reviewer` | Rails review from DHH's perspective |
+| `julik-frontend-races-reviewer` | Review JavaScript/Stimulus code for race conditions |
 | `kieran-rails-reviewer` | Rails code review with strict conventions |
 | `kieran-python-reviewer` | Python code review with strict conventions |
 | `kieran-typescript-reviewer` | TypeScript code review with strict conventions |
 | `pattern-recognition-specialist` | Analyze code for patterns and anti-patterns |
 | `performance-oracle` | Performance analysis and optimization |
+| `schema-drift-detector` | Detect unrelated schema.rb changes in PRs |
 | `security-sentinel` | Security audits and vulnerability assessments |
-| `julik-frontend-races-reviewer` | Review JavaScript/Stimulus code for race conditions |
 
-### Research (4)
+### Research (5)
 
 | Agent | Description |
 |-------|-------------|
 | `best-practices-researcher` | Gather external best practices and examples |
 | `framework-docs-researcher` | Research framework documentation and best practices |
 | `git-history-analyzer` | Analyze git history and code evolution |
+| `learnings-researcher` | Search institutional learnings for relevant past solutions |
 | `repo-research-analyst` | Research repository structure and conventions |
 
 ### Design (3)
@@ -85,12 +87,14 @@ Core workflow commands use `workflows:` prefix to avoid collisions with built-in
 
 | Command | Description |
 |---------|-------------|
+| `/lfg` | Full autonomous engineering workflow |
+| `/slfg` | Full autonomous workflow with swarm mode for parallel execution |
 | `/deepen-plan` | Enhance plans with parallel research agents for each section |
 | `/changelog` | Create engaging changelogs for recent merges |
 | `/create-agent-skill` | Create or edit Claude Code skills |
 | `/generate_command` | Generate new slash commands |
 | `/heal-skill` | Fix skill documentation issues |
-| `/plan_review` | Multi-agent plan review in parallel |
+| `/technical_review` | Multi-agent technical/architecture review in parallel |
 | `/report-bug` | Report a bug in the plugin |
 | `/reproduce-bug` | Reproduce bugs using logs and console |
 | `/resolve_parallel` | Resolve TODO comments in parallel |
@@ -125,10 +129,18 @@ Core workflow commands use `workflows:` prefix to avoid collisions with built-in
 
 | Skill | Description |
 |-------|-------------|
+| `brainstorming` | Explore requirements and approaches through collaborative dialogue |
+| `document-review` | Improve documents through structured self-review |
 | `every-style-editor` | Review copy for Every's style guide compliance |
 | `file-todos` | File-based todo tracking system |
 | `git-worktree` | Manage Git worktrees for parallel development |
 
+### Multi-Agent Orchestration
+
+| Skill | Description |
+|-------|-------------|
+| `orchestrating-swarms` | Comprehensive guide to multi-agent swarm orchestration |
+
 ### File Transfer
 
 | Skill | Description |

package/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.

package/plugins/compound-engineering/agents/research/learnings-researcher.md

@@ -66,7 +66,7 @@ Grep: pattern="email" path=docs/solutions/ output_mode=files_with_matches -i=tru
 **Regardless of Grep results**, always read the critical patterns file:
 
 ```bash
-Read: docs/solutions/patterns/cora-critical-patterns.md
+Read: docs/solutions/patterns/critical-patterns.md
 ```
 
 This file contains must-know patterns that apply across all work - high-severity issues promoted to required reading. Scan for patterns relevant to the current feature/task.
@@ -182,7 +182,7 @@ Structure your findings as:
 - **Relevant Matches**: [Y files]
 
 ### Critical Patterns (Always Check)
-[Any matching patterns from cora-critical-patterns.md]
+[Any matching patterns from critical-patterns.md]
 
 ### Relevant Learnings
 

package/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
+   - 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