Case Study: cass-memory | ACFS Learning Hub

Goal

Learn the full flywheel workflow through a real project: 693 beads, 282 commits on day one, 85% complete in hours.

The Challenge: Building a Memory System

On December 7, 2025, a new project was conceived: cass-memory - a procedural memory system for coding agents. The goal? Go from zero to a fully functional CLI tool in a single day using the flywheel workflow.

Day 1 Results

693

Total Beads

282

Day 1 Commits

25+

Agents Involved

~5hrs

To 85% Complete

This lesson walks you through exactly how it was done, so you can replicate this workflow on your own projects.

Phase 1: Multi-Model Planning

The first step isn't to start coding. It's to gather diverse perspectives on the problem.

Collect Competing Proposals

Ask multiple frontier models to propose implementation plans

GPT 5.1 Pro

Scientific validation approach

Gemini 3 Ultra

Search pointers & tombstones

Grok 4.1

Cross-agent enrichment

Claude Opus 4.5

ACE pipeline design

Each model received the same prompt with minimal guidance - just 2-3 messages to clarify the goal. The key instruction: "Design a memory system that works for all coding agents, not just Claude."

Pro Tip

Save each conversation as markdown. The chat_shared_conversation_to_file tool makes this easy.

Phase 2: Plan Synthesis

Now comes the crucial step: have one model synthesize the best ideas from all proposals into a single master plan.

bash

1# Put all proposal files in the project folder
2competing_proposal_plans/
3  2025-12-07-gemini-*.md
4  2025-12-07-grok-*.md
5  gpt_pro_version.md
6  claude_version/
7
8# Ask Opus 4.5 to create the hybrid plan
9cc "Read all the files in competing_proposal_plans/.
10Create a hybrid plan that takes the best parts of each.
11Write it to PLAN_FOR_CASS_MEMORY_SYSTEM.md"

PLAN_FOR_CASS_MEMORY_SYSTEM.md

5,600+ lines

11 major sections

Best ideas from 4 models

Complete implementation roadmap

The resulting plan was 5,600+ lines - a comprehensive blueprint covering architecture, data models, CLI commands, the reflection pipeline, storage, and implementation roadmap.

Anatomy of a Great Plan

The plan is the bedrock of a successful agentic project. Let's dissect what makes the actual 5,600+ line plan so effective.

Document Structure: 11 Major Sections

Executive Summary

Problem statement, three-layer solution, key innovations table

Core Architecture

Cognitive model, ACE pipeline, 7 design principles

Data Models

TypeScript schemas, confidence decay algorithm, validation rules

CLI Commands

15+ commands with usage examples and JSON outputs

Reflection Pipeline

Generator, Reflector, Validator, Curator phases

Integration

Search wrapper, error handling, secret sanitization

LLM Integration

Provider abstraction, Zod schemas, prompt templates

Storage & Persistence

Directory structure, cascading config, embeddings

Agent Integration

AGENTS.md template, MCP server design

Implementation Roadmap

Phased delivery with ROI priorities

Comparison Matrix

Feature checklist against competing proposals

Patterns That Make Plans Effective

Theory-First Approach

Each major feature includes: schema definition → algorithm → usage examples → implementation notes. Never jumps to code before explaining the why.

Progressive Elaboration

Simple concepts expand into nested detail. 'Bullet maturity' starts as a concept, becomes a state machine, then includes transition rules and decay calculations.

Concrete Examples Throughout

Not just 'validate inputs' but actual TypeScript interfaces, JSON outputs, bash command examples, and ASCII diagrams showing data flow.

Edge Cases Anticipated

The plan addresses error handling for cass timeouts, toxic bullet blocking, stale rule detection, and secret sanitization before implementation begins.

Comparison Tables

Key decisions contextualized against alternatives. Shows trade-offs between approaches from different model proposals.

Distinctive Innovations in This Plan

Confidence Decay Half-Life

Rules lose credibility over time. Harmful events weighted 4× helpful ones. Full algorithm with decay factors specified.

Anti-Pattern Inversion

Harmful rules converted to 'DON'T do X' instead of deleted, preserving the learning while inverting the advice.

Evidence-Count Gate

Pre-LLM heuristic filter that saves API calls. Rules need minimum evidence before promotion.

Cascading Config

Global user playbooks + repo-level playbooks merged intelligently with conflict resolution.

Pro Tip

What Your Plans Should Include:

• Executive summary - Problem + solution in 1 page
• Data models - TypeScript/Zod schemas for all entities
• CLI/API surface - Every command with examples
• Architecture diagrams - ASCII boxes showing data flow
• Error handling - What can go wrong, how to recover
• Implementation roadmap - Prioritized phases with dependencies
• Comparison tables - Why this approach over alternatives

Note

The full plan is available at github.com/Dicklesworthstone/cass_memory_system. Study it as a template for your own project plans.

Phase 3: From Plan to Beads

A 5,600-line markdown file is great for humans, but agents need structured, trackable tasks. This is where beads comes in.

bash

1# Initialize beads in the project
2bd init
3
4# Have an agent transform the plan into beads
5cc "Read PLAN_FOR_CASS_MEMORY_SYSTEM.md carefully.
6
7Transform each section, feature, and implementation detail
8into individual beads using the bd CLI.
9
10Create epics for major phases, then break them into tasks.
11Set up dependencies so blockers are clear.
12Use priorities: P0 for foundation, P1-P2 for core features,
13P3-P4 for polish and future work.
14
15Create at least 300 beads covering the full implementation."

Beads Structure

Epics

350+

Tasks

13h

Avg Lead Time

Tasks linked with dependencies so blockers are visible and agents know what to work on next.

Note

This transformation took multiple passes to refine. The agents reviewed and improved the beads structure several times.

Phase 4: Swarm Execution

With 350+ beads ready, it's time to unleash the swarm. Multiple agents work in parallel, each picking up tasks based on what's ready.

The Agent Swarm

Claude Code

5-6 agents (Opus 4.5)

Codex CLI

3 agents (5.1 Max)

Gemini CLI

2 agents (review duty)

bash

1# Launch the swarm with NTM
2ntm spawn cass-memory --cc=6 --cod=3 --gmi=2
3
4# Each agent runs this workflow:
5# 1. Check what's ready
6bv --robot-triage
7
8# 2. Claim a task
9bd update <id> --status in_progress
10
11# 3. Implement
12# (agent does the work)
13
14# 4. Close when done
15bd close <id>
16
17# 5. Repeat

The agents coordinate using bv (beads viewer) to see what's ready, avoiding conflicts and ensuring the most important blockers get cleared first.

Agent Coordination with Agent Mail

When agents need to share context or coordinate on overlapping work, Agent Mail provides the communication layer.

File reservations: Agents claim files before editing to avoid conflicts
Status updates: Agents report progress so others know what's happening
Handoffs: When one agent finishes a blocker, dependent agents get notified
Review requests: Agents can ask each other to review their work

bash

1# Example Agent Mail coordination
2
3# Agent "BlueLake" reserves files before editing
4mcp.file_reservation_paths(
5  project_key="/data/projects/cass-memory",
6  agent_name="BlueLake",
7  paths=["src/playbook/*.ts"],
8  ttl_seconds=3600,
9  exclusive=true
10)
11
12# Agent "GreenCastle" messages about a blocker being cleared
13mcp.send_message(
14  project_key="/data/projects/cass-memory",
15  sender_name="GreenCastle",
16  to=["BlueLake", "RedFox"],
17  subject="Types foundation complete",
18  body_md="Zod schemas are done. You can now work on playbook and CLI."
19)

Pro Tip

The full Agent Mail archive from this project was published as a static site so you can see the actual agent-to-agent communication.

The Commit Cadence

With many agents working simultaneously, commits need careful orchestration. A dedicated commit agent runs continuously.

bash

1# The commit agent pattern (runs every 15-20 minutes)
2
3# Step 1: Understand the project
4cc "First read AGENTS.md, read the README, and explore
5the project to understand what we're doing. Use ultrathink."
6
7# Step 2: Commit in logical groupings
8cc "Based on your knowledge of the project, commit all
9changed files now in a series of logically connected
10groupings with super detailed commit messages for each
11and then push.
12
13Take your time to do it right. Don't edit the code at all.
14Don't commit ephemeral files. Use ultrathink."

Commit Statistics

282

Day 1 Commits

~12

Per Hour

Detailed

Messages

The commit agent ran every 15-20 minutes, grouping changes logically and writing detailed commit messages.

This pattern ensures atomic, well-documented commits even when 10+ agents are making changes simultaneously.

Results & Key Lessons

After one day of flywheel-powered development, the cass-memory project achieved:

11K+

Lines of Code

282

Day 1 Commits

151

Tests Passing

85-90%

Complete

Key Lessons

Planning is 80% of the work

A detailed plan makes agent execution predictable and fast

Multi-model synthesis beats single-model planning

Each model brought unique insights that improved the final design

Beads enable parallelism

Structured tasks with dependencies let many agents work without conflicts

Coordination tools are essential

Agent Mail and file reservations prevent agents from stepping on each other

Dedicated commit agent keeps history clean

Separating commit responsibility from coding ensures atomic commits

Try It Yourself

Ready to try this workflow on your own project? Here's the quickstart:

bash

1# 1. Gather proposals from multiple models
2# (Use GPT Pro, Gemini, Claude, Grok - whichever you have access to)
3# Save each as markdown in competing_proposal_plans/
4
5# 2. Synthesize into a master plan
6cc "Read all files in competing_proposal_plans/.
7Create a hybrid plan taking the best of each.
8Write to PLAN.md"
9
10# 3. Transform plan into beads
11bd init
12cc "Read PLAN.md. Transform into 100+ beads with
13dependencies and priorities. Use bd CLI."
14
15# 4. Launch the swarm
16ntm spawn myproject --cc=3 --cod=2 --gmi=1
17
18# 5. Monitor with bv
19bv --robot-triage  # See what's ready
20
21# 6. Watch the magic happen
22ntm attach myproject
23
24# 7. (Every 15-20 min) Run the commit agent
25cc "Commit all changes in logical groupings with
26detailed messages. Don't edit code. Push when done."

Note

Start smaller than the cass-memory example. Try this workflow with a project that would normally take you a day or two manually. Build your confidence before tackling larger projects.

1# Put all proposal files in the project folder

2competing_proposal_plans/

3 2025-12-07-gemini-*.md

4 2025-12-07-grok-*.md

5 gpt_pro_version.md

6 claude_version/

8# Ask Opus 4.5 to create the hybrid plan

9cc "Read all the files in competing_proposal_plans/.

10Create a hybrid plan that takes the best parts of each.

11Write it to PLAN_FOR_CASS_MEMORY_SYSTEM.md"

1# Initialize beads in the project

2bd init

4# Have an agent transform the plan into beads

5cc "Read PLAN_FOR_CASS_MEMORY_SYSTEM.md carefully.

7Transform each section, feature, and implementation detail

8into individual beads using the bd CLI.

10Create epics for major phases, then break them into tasks.

11Set up dependencies so blockers are clear.

12Use priorities: P0 for foundation, P1-P2 for core features,

13P3-P4 for polish and future work.

15Create at least 300 beads covering the full implementation."

1# Launch the swarm with NTM

2ntm spawn cass-memory --cc=6 --cod=3 --gmi=2

4# Each agent runs this workflow:

5# 1. Check what's ready

6bv --robot-triage

8# 2. Claim a task

9bd update <id> --status in_progress

11# 3. Implement

12# (agent does the work)

14# 4. Close when done

15bd close <id>

17# 5. Repeat

1# Example Agent Mail coordination

3# Agent "BlueLake" reserves files before editing

4mcp.file_reservation_paths(

5 project_key="/data/projects/cass-memory",

6 agent_name="BlueLake",

7 paths=["src/playbook/*.ts"],

8 ttl_seconds=3600,

9 exclusive=true

10)

12# Agent "GreenCastle" messages about a blocker being cleared

13mcp.send_message(

14 project_key="/data/projects/cass-memory",

15 sender_name="GreenCastle",

16 to=["BlueLake", "RedFox"],

17 subject="Types foundation complete",

18 body_md="Zod schemas are done. You can now work on playbook and CLI."

19)

1# The commit agent pattern (runs every 15-20 minutes)

3# Step 1: Understand the project

4cc "First read AGENTS.md, read the README, and explore

5the project to understand what we're doing. Use ultrathink."

7# Step 2: Commit in logical groupings

8cc "Based on your knowledge of the project, commit all

9changed files now in a series of logically connected

10groupings with super detailed commit messages for each

11and then push.

13Take your time to do it right. Don't edit the code at all.

14Don't commit ephemeral files. Use ultrathink."

1# 1. Gather proposals from multiple models

2# (Use GPT Pro, Gemini, Claude, Grok - whichever you have access to)

3# Save each as markdown in competing_proposal_plans/

5# 2. Synthesize into a master plan

6cc "Read all files in competing_proposal_plans/.

7Create a hybrid plan taking the best of each.

8Write to PLAN.md"

10# 3. Transform plan into beads

11bd init

12cc "Read PLAN.md. Transform into 100+ beads with

13dependencies and priorities. Use bd CLI."

15# 4. Launch the swarm

16ntm spawn myproject --cc=3 --cod=2 --gmi=1

18# 5. Monitor with bv

19bv --robot-triage # See what's ready

21# 6. Watch the magic happen

22ntm attach myproject

24# 7. (Every 15-20 min) Run the commit agent

25cc "Commit all changes in logical groupings with

26detailed messages. Don't edit code. Push when done."

New to ACFS?

The Challenge: Building a Memory System

Day 1 Results

Phase 1: Multi-Model Planning

Collect Competing Proposals

Phase 2: Plan Synthesis

PLAN_FOR_CASS_MEMORY_SYSTEM.md

Anatomy of a Great Plan

Document Structure: 11 Major Sections

Executive Summary

Core Architecture

Data Models

CLI Commands

Reflection Pipeline

Integration

LLM Integration

Storage & Persistence

Agent Integration

Implementation Roadmap

Comparison Matrix

Patterns That Make Plans Effective

Theory-First Approach

Progressive Elaboration

Concrete Examples Throughout

Edge Cases Anticipated

Comparison Tables

Distinctive Innovations in This Plan

Confidence Decay Half-Life

Anti-Pattern Inversion

Evidence-Count Gate

Cascading Config

Phase 3: From Plan to Beads

Beads Structure

Phase 4: Swarm Execution

The Agent Swarm

Agent Coordination with Agent Mail

The Commit Cadence

Commit Statistics

Results & Key Lessons

Key Lessons

Planning is 80% of the work

Multi-model synthesis beats single-model planning

Beads enable parallelism

Coordination tools are essential

Dedicated commit agent keeps history clean

Try It Yourself

Ready to level up?

New to ACFS?

The Challenge: Building a Memory System

Day 1 Results

Phase 1: Multi-Model Planning

Collect Competing Proposals

Phase 2: Plan Synthesis

PLAN_FOR_CASS_MEMORY_SYSTEM.md

Anatomy of a Great Plan

Document Structure: 11 Major Sections

Executive Summary

Core Architecture

Data Models

CLI Commands

Reflection Pipeline

Integration

LLM Integration

Storage & Persistence

Agent Integration

Implementation Roadmap

Comparison Matrix

Patterns That Make Plans Effective

Theory-First Approach

Progressive Elaboration

Concrete Examples Throughout

Edge Cases Anticipated

Comparison Tables

Distinctive Innovations in This Plan

Confidence Decay Half-Life

Anti-Pattern Inversion

Evidence-Count Gate

Cascading Config

Phase 3: From Plan to Beads

Beads Structure