AI Integration Files

When you run deciduous init, it generates files that teach your AI assistant how to use the decision graph. These files are the secret sauce that makes the workflow loop automatic.

The Problem They Solve

AI assistants don't have persistent memory across sessions. When a session ends or context compacts, they forget:

What decisions were made and why
What options were considered but rejected
The reasoning behind architectural choices
What was tried before and failed

The generated files solve this by:

Teaching the AI about deciduous commands
Enforcing real-time logging as work happens
Enabling context recovery at session start

For Claude Code Users

Run deciduous init (or deciduous init --claude) to generate:

File	Purpose
`.claude/commands/decision.md`	Slash command for managing the graph
`.claude/commands/context.md`	Slash command for context recovery
`CLAUDE.md`	Project instructions with workflow rules

CLAUDE.md — The Behavioral Contract

CLAUDE.md is read by Claude Code at session start. It contains the Decision Graph Workflow section that defines when and how to log:

## Decision Graph Workflow

**THIS IS MANDATORY. Log decisions IN REAL-TIME, not retroactively.**

### The Core Rule

```
BEFORE you do something -> Log what you're ABOUT to do
AFTER it succeeds/fails -> Log the outcome
CONNECT immediately -> Link every node to its parent
AUDIT regularly -> Check for missing connections
```

This section also includes:

Behavioral triggers — when to log goals, decisions, actions, outcomes
Connection rules — what must link to what
Session start checklist — what to do at the beginning of each session
Audit checklist — how to verify graph integrity

Customize It

You can edit CLAUDE.md to add project-specific rules. The Decision Graph Workflow section will be preserved when you run deciduous update.

/decision — The Graph Manager

The /decision slash command provides a quick interface for graph operations:

Using /decision

/decision add goal "Implement caching" -p "User asked for better performance" Created node #47: goal "Implement caching" /decision add decision "Choose caching strategy" Created node #48: decision "Choose caching strategy" /decision link 47 48 -r "Need to decide approach" Created edge: #47 -> #48 (leads_to) /decision nodes ID Type Title Status Confidence ─────────────────────────────────────────────────────────────── 47 goal Implement caching active 90 48 decision Choose caching strategy active 75

The command maps to deciduous CLI operations:

Slash Command	Runs
`/decision nodes`	`deciduous nodes`
`/decision add goal "X"`	`deciduous add goal "X" -c 90`
`/decision link 1 2 "reason"`	`deciduous link 1 2 -r "reason"`
`/decision sync`	`deciduous sync`

/context — The Memory Restorer

The /context slash command recovers context at session start:

Using /context at Session Start

/context I'll query the decision graph to recover context... deciduous nodes ID Type Title Status Confidence ───────────────────────────────────────────────────────────────────── 47 goal Implement caching active 90 48 decision Choose caching strategy active 75 49 option Redis caching active 80 50 option In-memory LRU active 70 deciduous edges From To Type Rationale ──────────────────────────────────────────────── 47 48 leads_to Need to decide approach 48 49 leads_to Scales across instances 48 50 leads_to Simpler, single-node only git status On branch feature/caching Changes not staged for commit: modified: src/cache.rs Context Recovered: - Working on caching feature (branch: feature/caching) - Goal: Implement caching (#47) - Active decision: Choose caching strategy (#48) - Two options being considered: Redis vs in-memory LRU - Uncommitted changes to src/cache.rs Suggested next steps: 1. Review the options and make a decision 2. Log the chosen approach with --edge-type chosen 3. Continue implementation

For Windsurf Users

Run deciduous init --windsurf to generate:

File	Purpose
`.windsurf/rules/deciduous.md`	Always On rule for decision logging
`.windsurf/rules/context.md`	Model-triggered rule for context recovery
`.windsurf/memories.md`	Auto-retrieved project memories
`AGENTS.md`	Project instructions with workflow rules

Rules vs Memories

Windsurf uses two types of AI guidance:

Rules (.windsurf/rules/) — Instructions that Cascade follows. Can be "Always On" or "Model-triggered".
Memories (.windsurf/memories.md) — Facts about the project that Cascade auto-retrieves when relevant.

The deciduous.md rule is marked "Always On" so Cascade will always follow the decision logging workflow.

Important: Verify Rule Activation

After running deciduous init --windsurf, open Windsurf's Customizations panel and verify that deciduous.md is set to "Always On".

AGENTS.md

AGENTS.md is the Windsurf equivalent of CLAUDE.md. It contains the same Decision Graph Workflow section, formatted for Cascade.

The Workflow Loop

These files enforce a continuous loop:

SESSION START
    │
    ▼
Run /context → See past decisions
    │
    ▼
AUDIT → Fix any orphan nodes first!
    │
    ▼
DO WORK → Log BEFORE each action
    │
    ▼
CONNECT → Link new nodes immediately
    │
    ▼
AFTER CHANGES → Log outcomes, observations
    │
    ▼
AUDIT AGAIN → Any new orphans?
    │
    ▼
BEFORE PUSH → deciduous sync
    │
    ▼
PUSH → Live graph updates
    │
    ▼
SESSION END → Final audit
    │
    ▼
(repeat)

Git History Integration

The Timeline and DAG views can show git commits alongside decision nodes. This creates traceability between decisions and code.

Linking Commits to Nodes

After every git commit, link it to the decision graph:

Linking Commits

git commit -m "feat: add Redis caching" [feature/caching abc123] feat: add Redis caching 3 files changed, 87 insertions(+) deciduous add action "Implemented Redis caching" -c 90 --commit HEAD Created node #51: action "Implemented Redis caching" [commit: abc123] deciduous link 48 51 --edge-type chosen -r "Redis chosen for horizontal scaling" Created edge: #48 -> #51 (chosen)

The --commit HEAD flag automatically captures the current commit hash and links it to the node.

Exporting Git History

When you run deciduous sync, it also exports git history for commits linked to nodes:

$ deciduous sync
Exported graph to docs/graph-data.json
Exported git history to docs/git-history.json

The web viewer reads this file to show commit messages, authors, dates, and file counts alongside your decision nodes.

Deploying to GitHub Pages

The docs/ directory is ready for GitHub Pages:

Run deciduous sync to export graph and git history
Push to GitHub
Go to Settings > Pages
Set source to Deploy from branch
Select your branch and /docs folder

Your graph will be live at https://<username>.github.io/<repo>/

GitHub Action Included

deciduous init also creates .github/workflows/deploy-pages.yml which automatically deploys to GitHub Pages when you push to main.

Keeping Files Updated

As deciduous evolves, the generated files may get new features. Update them with:

# For Claude Code
$ deciduous update

# For Windsurf
$ deciduous update --windsurf

This overwrites the slash commands/rules with the latest versions while preserving your custom additions to CLAUDE.md or AGENTS.md.

What Makes This Work

The Key Insight

AI assistants are excellent at following explicit instructions. By embedding the decision logging workflow directly into the files they read at session start, we make the workflow automatic.

You don't have to remember to log decisions—your AI assistant does it for you.

The combination of:

CLAUDE.md / AGENTS.md — behavioral rules
Slash commands / Rules — quick access to operations
/context — memory restoration at session start

Creates a system where decisions are logged in real-time, survive context loss, and are automatically recovered in new sessions.

Previous Initializing Next Your First Nodes