AI Integration Files

When you run deciduous init, it generates files that teach Claude Code 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, Claude forgets:

The generated files solve this by:

  1. Teaching Claude about deciduous commands
  2. Enforcing real-time logging as work happens
  3. Enabling context recovery at session start

What Gets Created

Run deciduous init to generate:

File Purpose
.claude/commands/decision.md Slash command for managing the graph
.claude/commands/recover.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:

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
/decision show 42 deciduous show 42

/recover — The Memory Restorer

The /recover slash command recovers context at session start:

Using /recover at Session Start
/recover 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

The Workflow Loop

These files enforce a continuous loop:

SESSION START
    │
    ▼
Run /recover → 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.

Viewing Node Details

Use the show command to see full details for any node:

Viewing Node Details
deciduous show 51 Node #51 action ──────────────────────────────────────────────────────────── Title: Implemented Redis caching Status: active Created: 2024-01-15T10:30:00 Metadata Confidence: 90% Branch: feature/caching Commit: abc1234 Connections Incoming (1): #48 ─[chosen]→ here: Redis chosen for horizontal scaling

Deploying to GitHub Pages

The docs/ directory is ready for GitHub Pages:

  1. Run deciduous sync to export graph and git history
  2. Push to GitHub
  3. Go to Settings > Pages
  4. Set source to Deploy from branch
  5. 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:

$ deciduous update

This updates slash commands, skills, hooks, and the web viewer to the latest versions while preserving your custom additions to CLAUDE.md.

When to Update

Run deciduous update after upgrading deciduous (cargo install deciduous) or when release notes mention new skills or commands.

What Makes This Work

The Key Insight

Claude Code is excellent at following explicit instructions. By embedding the decision logging workflow directly into the files it reads at session start, we make the workflow automatic.

You don't have to remember to log decisions—Claude does it for you.

The combination of:

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