compound-workflows

Fork of Every's compound-engineering for Claude Code. Longer sessions without context exhaustion, session recovery when things go wrong, task tracking that survives compaction, multi-model red team (PAL + Claude), fewer plan iterations, and memory that persists across sessions.

• What is Compound Engineering?
• Why Fork?
• What's Different
• Install
• Update
• Commands
• Dependencies
• Key Concept: Disk-Persisted Agents
• Roadmap
• Attribution

What is Compound Engineering?

Compound engineering is a methodology where each unit of engineering work makes subsequent units easier. You document solutions, capture decisions with their rationale, and build institutional knowledge that compounds over time.

Compound workflows generalize this idea beyond software engineering to all knowledge work — an opinionated way to use Claude Code for research, planning, decision-making, and implementation. The cycle remains the same: brainstorm → plan → work → review → compound.

The plugin captures best-practice patterns and makes them shareable, while remaining configurable to individual user preferences.

Why Fork?

Ambitious tasks in Claude Code hit walls:

• Context exhaustion — Agent outputs fill up context and trigger compaction. → Agents write to disk and return summaries, so sessions last longer.
• State loss — Work progress disappears on compaction. → /compact-prep and /recover handle planned and unplanned session boundaries; beads tracking survives across compactions.
• Plan iteration overhead — Plans require many rounds to reach quality. → Readiness checks and consolidation catch issues earlier, preventing the fix-introduces-new-bug cycle.
• Single-model blind spots — One model can't catch its own assumptions. → Red team challenges from multiple providers (Gemini, OpenAI, Claude) surface what a single model misses.
• Knowledge loss — Context learned in one session is gone in the next. → Tiered memory management promotes frequently-used knowledge to where it's auto-loaded.

What's Different

Install

/plugin marketplace add adamfeldman/compound-workflows
/plugin install compound-workflows

Warning: Do not install alongside compound-engineering. This plugin bundles all agents and skills. Installing both will cause agent name conflicts. Run /do:setup to detect and resolve conflicts.

Then run setup to detect your environment:

/do:setup

Update

From your terminal:

claude plugin update compound-workflows@compound-workflows-marketplace

Or use the interactive /plugin menu inside Claude Code.

Commands

/compound:* aliases still work during the v3.0 transition period.

Workflow Cycle

brainstorm -> plan -> [deepen-plan] -> work -> review -> compound

Each step produces documents that feed the next. Solutions feed future brainstorms.

Session Recovery

Context exhaustion is inevitable in long sessions. Two paths:

• Proactive: /do:compact-prep before /compact — saves memory, checks for uncommitted work, queues a resume task. Say "resume" after compaction.
• Ending a session: /do:abandon — captures memory, compounds learnings, commits, and pushes without queuing a resume task.
• Reactive: /compound-workflows:recover when a session dies without compaction — parses the JSONL session log, cross-references git/beads/.workflows/plan state to reconstruct progress and extract what would otherwise be lost.

Dependencies

Without beads: TodoWrite fallback (loses state on compaction). Without PAL: Claude-only subagent fallback (single model).

Key Concept: Disk-Persisted Agents

Instead of agents returning full results into conversation context (which fills up and compacts), every agent writes findings to .workflows/ and returns only a 2-3 sentence summary.

• Context stays lean — run 15+ agents without exhaustion
• Research survives — files persist across sessions and compactions
• Traceability — see exactly what informed each decision
• Recovery — disk files + beads = full recovery after compaction

Stats & Analysis

The plugin automatically collects per-dispatch timing and token data across all workflows. All data stays local on your machine in .workflows/stats/ — nothing is sent externally. This enables:

• Estimation calibration — compare estimated vs actual time, segmented by type, priority, scope, and size. Discover which kinds of work consistently blow estimates and apply correction factors.
• Workflow-level timing — see how long each workflow step takes you, so you know where your time goes.
• Model routing — see which steps need the most capable model and which can run cheaper, so you spend quota where it matters.
• Velocity tracking — beads/hour trend over time, correlated with workflow maturity.
• Outcome correlation — because beads track tangible goals, time and token data connects back to actual deliverables, not just activity.
• Deep insights — mine Claude Code's session logs to understand compaction overhead, quota consumption patterns, and what's actually driving cost.

Run /compound-workflows:classify-stats to add complexity labels to collected data. /do:analyze-stats (coming soon) will run the full analysis and present findings interactively.

Roadmap

Attribution

Includes agents and skills forked from Every's compound engineering plugin (MIT). The brainstorm-plan-work-review-compound cycle, agent-based review architecture, and knowledge compounding philosophy originate from that project. See NOTICE and FORK-MANIFEST.yaml for provenance.

License

MIT