Cupcake 🧁

Your Personal Workspace Scaffolding Package

Cupcake transforms a blank workspace into a fully-equipped development environment with automated learning consolidation, knowledge management, and intelligent agent support.

---

What is Cupcake?

Cupcake is a workspace scaffolding system that provides:

• 📁 Organized Folder Structure - Projects, skills, learnings, and development work
• 🧠 Agent Memory System - Automated learning consolidation across chat sessions
• 📋 Atomic Rules - Consistent agent behavior (archive-don't-delete, checkbox discipline, economy)
• 📝 Template System - Quick project creation with built-in structure
• 🔧 Skills - Extensible capabilities following agentskills.io spec

Core Philosophy

1. Zero-Context Ready - Any stateless AI agent can pick up where others left off
2. Economy First - Combat context bloat through aggressive consolidation
3. Knowledge Persistence - Important insights don't get lost between sessions
4. Lightweight Process - Simple, repeatable, common-sense approach

---

Installation

Step 1: Copy Cupcake to Your Workspace

# Copy the entire FAKEROOT contents to your workspace root
cp -r FAKEROOT/* /path/to/your/workspace/
cd /path/to/your/workspace

Step 2: Configure

Edit USERS.md to add your basic info:

**Name:** Your Name
**Role:** Your Role (Developer, Designer, etc.)

Optional: Edit agent/counter-register.md to adjust consolidation cadence if desired.

Step 3: Set Up Hooks (IDE-Specific)

For Cursor IDE

Create hooks in .cursor/hooks/ (if your IDE supports it):

on-agent-start.sh:

#!/bin/bash
python agent/scripts/counter-increment.py

on-agent-end.sh:

#!/bin/bash
python agent/scripts/counter-check.py

Make executable:

chmod +x .cursor/hooks/*.sh

Manual Mode (No Hooks)

If your IDE doesn't support hooks, you can run consolidation manually:

# Check current counter and trigger actions
python agent/scripts/counter-check.py

# If actions are triggered, activate the agent-memory skill
# and tell it to run the specified action

Step 4: Start Working!

Create your first project:

# Copy the template
cp -r my-projects/template/YYYYMMDD-\[topic-name\] my-projects/20260418-my-first-project

# Edit the files
cd my-projects/20260418-my-first-project
# Update readme.md, use scratchpad.md for work, record learnings in learnings.md

---

Folder Structure

my-projects/              # All project work
  template/               # Template for new projects (copy this)
  YYYYMMDD-[topic]/       # Your dated project folders
    readme.md             # Project overview
    scratchpad.md         # Temporary working doc
    learnings.md          # Permanent project learnings
    gleanings.md          # Temporary gleanings (auto-created/deleted)
    z_archive/            # Archived files

my-skills/                # Skill definitions (agentskills.io spec)
  agent-memory/           # Learning consolidation skill
  skill-creator/          # Skill creation helper

my-dev/                   # Development workspace (optional)

my-learnings/             # Workspace-level learning consolidation
  learnings-primary.md    # Top 30 + bottom register
  learning-categories/    # Categorized overflow

agent/                    # Agent infrastructure
  rules/                  # Atomic rules (archive, checkbox, economy)
  scripts/                # Counter scripts
  hooks/                  # Hook definitions
  counter-register.md     # Counter state + consolidation programs

AGENTS.md                 # Critical info for AI agents
USERS.md                  # Critical info about you
LEARNINGS.md              # Workspace learnings overview

---

How the Agent-Memory System Works

The Counter

Every chat turn increments a counter. When certain milestones are hit, consolidation actions trigger:

Counter	Action	What Happens
5, 10, 15...	Glean	Extract learnings from recent conversation → gleanings.md
15, 30, 45...	Consolidate	Merge gleanings into learnings files, delete gleanings
50, 100, 150...	Review Critical	Identify patterns for USERS.md / AGENTS.md
100, 200, 300...	Deep Consolidation	Aggressive pruning, reorganization, optimization

The 30-Item Cap

my-learnings/learnings-primary.md has a top register limited to 30 items.

Why? Economy. Context is finite. The top 30 should be your most valuable learnings.

When it exceeds 30:

• Items are scored on value, criticality, complexity, breadth
• Lowest-scoring items move to bottom register
• Bottom register can overflow to category files

The Flow

Work → Chat → Chat → Chat → Chat → Chat
            ↓
       [Counter=5: Glean]
       Create gleanings.md
            ↓
Work → Chat → Chat → Chat → Chat → Chat
            ↓
       [Counter=10: Glean]
       Append to gleanings.md
            ↓
Work → Chat → Chat → Chat → Chat → Chat
            ↓
       [Counter=15: Consolidate]
       Merge gleanings → learnings
       Delete gleanings.md
            ↓
       Repeat...

---

Core Rules

1. Archive, Don't Delete

Never delete files. Always move to z_archive/ instead.

Good:

mv old-file.md z_archive/old-file.md

Bad:

rm old-file.md

2. Checkboxes Are Inviolate

• ✅ Checked = finished (reference only, don't modify)
• ☐ Unchecked = must resolve before moving on

Always resolve unchecked items before starting new work.

3. Economy First

Prioritize brevity. Eliminate redundancy. Maintain focus.

Good:

Use SQLite over Postgres (simpler setup, sufficient scale)

Bad:

After discussing the trade-offs, we decided that SQLite would be 
better than Postgres because it's simpler to set up and should be 
sufficient for our current scale...

---

Creating New Projects

Quick Method

DATE=$(date +%Y%m%d)
PROJECT_NAME="my-new-project"
cp -r my-projects/template/YYYYMMDD-\[topic-name\] my-projects/${DATE}-${PROJECT_NAME}

What to Do Next

1. Update readme.md - Explain the project
2. Use scratchpad.md - Task lists, analysis, working notes
3. Record in learnings.md - Decisions, findings, patterns
4. Let agent-memory do the rest - Gleanings and consolidation happen automatically

---

Skills

Cupcake ships with two skills (following agentskills.io spec):

agent-memory

Handles all learning consolidation:

• Gleaning conversations for insights
• Consolidating gleanings into learnings
• Reviewing for critical information
• Deep consolidation and pruning

Activate when counter triggers an action.

skill-creator

Helps create new skills following Anthropic's specification.

Use when you want to add new capabilities to your workspace.

---

Customization

Adjust Consolidation Cadence

Edit agent/counter-register.md to change when actions trigger:

| Modulo | Period | Action | Description |
|--------|--------|--------|-------------|
| 10 | Every 10 chats | glean-chat | Change from 5 to 10 |

Add Custom Rules

Create new rule files in agent/rules/:

touch agent/rules/my-custom-rule.md

Follow the format of existing rules (clear, atomic, actionable).

Create Custom Skills

Use the skill-creator skill or follow agentskills.io spec:

my-skills/my-new-skill/
  SKILL.md
  references/
  scripts/

---

Troubleshooting

Counter not incrementing

Check that hooks are set up correctly and scripts are executable:

ls -l agent/scripts/*.py  # Should show -rwxr-xr-x

Gleanings not consolidating

Check the counter value:

python agent/scripts/counter-check.py

Should show triggered actions when counter % 15 == 0.

Too many learnings

Run deep consolidation manually:

# Activate agent-memory skill with action: deep-consolidation

Categories feel messy

During deep consolidation, merge related categories. Use common sense.

---

Philosophy

Cupcake is designed around these principles:

Atomic Structure - Every piece (rules, skills, learnings) is self-contained

Adaptability - System adjusts to different project types and workflows

Economy - Aggressive about preventing context bloat

Usefulness - Only keep what's actionable or critical

Robustness - System survives interruptions, works with zero context

---

Requirements

• Python 3.6+ (for counter scripts)
• IDE with hook support (optional, for automation)
• AI agent with skill support (for agent-memory)

---

License

[Specify your license here]

---

Credits

• Agent Skills spec: https://agentskills.io/
• Inspired by effective knowledge management and context economy principles

---

Get Started

1. Install Cupcake in your workspace
2. Configure USERS.md with your info
3. Create your first project from template
4. Start working - let agent-memory handle the rest

Happy building! 🧁