mary.my.id
work-in-progress atproto PDS
typescript
atproto
pds
atcute
chore: set up deciduous
+71
.claude/agents.toml
+71
.claude/agents.toml
···
1
+
# Project Subagents Configuration
2
+
# Domain-specific agents for working on different parts of the codebase.
3
+
#
4
+
# When working on a specific domain, spawn a Task with subagent_type="Explore" or
5
+
# "general-purpose" and include the relevant agent's context in the prompt.
6
+
#
7
+
# Customize this file for YOUR project's structure. The domains below are examples.
8
+
9
+
# Example: Backend/Core agent
10
+
# [agents.backend]
11
+
# name = "Backend Agent"
12
+
# description = "API routes, database models, business logic"
13
+
# file_patterns = [
14
+
# "src/**/*.rs",
15
+
# "src/**/*.py",
16
+
# "app/**/*.py"
17
+
# ]
18
+
# focus_areas = [
19
+
# "Database operations",
20
+
# "API endpoints",
21
+
# "Business logic"
22
+
# ]
23
+
# instructions = """
24
+
# When working on backend:
25
+
# - Run tests before and after changes
26
+
# - Follow existing patterns for new endpoints
27
+
# - Maintain backwards compatibility
28
+
# """
29
+
30
+
# Example: Frontend agent
31
+
# [agents.frontend]
32
+
# name = "Frontend Agent"
33
+
# description = "UI components, state management, styling"
34
+
# file_patterns = [
35
+
# "web/src/**/*.ts",
36
+
# "web/src/**/*.tsx",
37
+
# "src/components/**"
38
+
# ]
39
+
# focus_areas = [
40
+
# "React components",
41
+
# "State management",
42
+
# "Styling and layout"
43
+
# ]
44
+
# instructions = """
45
+
# When working on frontend:
46
+
# - Test in browser after changes
47
+
# - Follow component patterns
48
+
# - Keep accessibility in mind
49
+
# """
50
+
51
+
# Example: Infrastructure agent
52
+
# [agents.infra]
53
+
# name = "Infrastructure Agent"
54
+
# description = "CI/CD, deployment, configuration"
55
+
# file_patterns = [
56
+
# ".github/workflows/**",
57
+
# "Dockerfile",
58
+
# "docker-compose.yml",
59
+
# "scripts/**"
60
+
# ]
61
+
# focus_areas = [
62
+
# "GitHub Actions",
63
+
# "Docker configuration",
64
+
# "Deployment scripts"
65
+
# ]
66
+
# instructions = """
67
+
# When working on infrastructure:
68
+
# - Test workflows locally when possible
69
+
# - Keep builds fast with caching
70
+
# - Document any manual steps
71
+
# """
+195
.claude/commands/context.md
+195
.claude/commands/context.md
···
1
+
---
2
+
description: Recover context from decision graph and recent activity - USE THIS ON SESSION START
3
+
allowed-tools: Bash(deciduous:*, git:*, cat:*, tail:*)
4
+
argument-hint: [focus-area]
5
+
---
6
+
7
+
# Context Recovery
8
+
9
+
**RUN THIS AT SESSION START.** The decision graph is your persistent memory.
10
+
11
+
## Step 1: Query the Graph
12
+
13
+
```bash
14
+
# See all decisions (look for recent ones and pending status)
15
+
deciduous nodes
16
+
17
+
# Filter by current branch (useful for feature work)
18
+
deciduous nodes --branch $(git rev-parse --abbrev-ref HEAD)
19
+
20
+
# See how decisions connect
21
+
deciduous edges
22
+
23
+
# What commands were recently run?
24
+
deciduous commands
25
+
```
26
+
27
+
**Branch-scoped context**: If working on a feature branch, filter nodes to see only decisions relevant to this branch. Main branch nodes are tagged with `[branch: main]`.
28
+
29
+
## Step 1.5: Audit Graph Integrity
30
+
31
+
**CRITICAL: Check that all nodes are logically connected.**
32
+
33
+
```bash
34
+
# Find nodes with no incoming edges (potential missing connections)
35
+
deciduous edges | cut -d'>' -f2 | cut -d' ' -f2 | sort -u > /tmp/has_parent.txt
36
+
deciduous nodes | tail -n+3 | awk '{print $1}' | while read id; do
37
+
grep -q "^$id$" /tmp/has_parent.txt || echo "CHECK: $id"
38
+
done
39
+
```
40
+
41
+
**Review each flagged node:**
42
+
43
+
- Root `goal` nodes are VALID without parents
44
+
- `outcome` nodes MUST link back to their action/goal
45
+
- `action` nodes MUST link to their parent goal/decision
46
+
- `option` nodes MUST link to their parent decision
47
+
48
+
**Fix missing connections:**
49
+
50
+
```bash
51
+
deciduous link <parent_id> <child_id> -r "Retroactive connection - <reason>"
52
+
```
53
+
54
+
## Step 2: Check Git State
55
+
56
+
```bash
57
+
git status
58
+
git log --oneline -10
59
+
git diff --stat
60
+
```
61
+
62
+
## Step 3: Check Session Log
63
+
64
+
```bash
65
+
cat git.log | tail -30
66
+
```
67
+
68
+
## After Gathering Context, Report:
69
+
70
+
1. **Current branch** and pending changes
71
+
2. **Branch-specific decisions** (filter by branch if on feature branch)
72
+
3. **Recent decisions** (especially pending/active ones)
73
+
4. **Last actions** from git log and command log
74
+
5. **Open questions** or unresolved observations
75
+
6. **Suggested next steps**
76
+
77
+
### Branch Configuration
78
+
79
+
Check `.deciduous/config.toml` for branch settings:
80
+
81
+
```toml
82
+
[branch]
83
+
main_branches = ["main", "master"] # Which branches are "main"
84
+
auto_detect = true # Auto-detect branch on node creation
85
+
```
86
+
87
+
---
88
+
89
+
## REMEMBER: Real-Time Logging Required
90
+
91
+
After recovering context, you MUST follow the logging workflow:
92
+
93
+
```
94
+
EVERY USER REQUEST → Log goal/decision first
95
+
BEFORE CODE CHANGES → Log action
96
+
AFTER CHANGES → Log outcome, link nodes
97
+
BEFORE GIT PUSH → deciduous sync
98
+
```
99
+
100
+
**The user is watching the graph live.** Log as you go, not after.
101
+
102
+
### Quick Logging Commands
103
+
104
+
```bash
105
+
# Root goal with user prompt (capture what the user asked for)
106
+
deciduous add goal "What we're trying to do" -c 90 -p "User asked: <their request>"
107
+
108
+
deciduous add action "What I'm about to implement" -c 85
109
+
deciduous add outcome "What happened" -c 95
110
+
deciduous link FROM TO -r "Connection reason"
111
+
112
+
# Capture prompt when user redirects mid-stream
113
+
deciduous add action "Switching approach" -c 85 -p "User said: use X instead"
114
+
115
+
deciduous sync # Do this frequently!
116
+
```
117
+
118
+
**When to use `--prompt`:** On root goals (always) and when user gives new direction mid-stream. Downstream nodes inherit context via edges.
119
+
120
+
---
121
+
122
+
## Focus Areas
123
+
124
+
If $ARGUMENTS specifies a focus, prioritize context for:
125
+
126
+
- **auth**: Authentication-related decisions
127
+
- **ui** / **graph**: UI and graph viewer state
128
+
- **cli**: Command-line interface changes
129
+
- **api**: API endpoints and data structures
130
+
131
+
---
132
+
133
+
## The Memory Loop
134
+
135
+
```
136
+
SESSION START
137
+
↓
138
+
Run /recover → See past decisions
139
+
↓
140
+
AUDIT → Fix any orphan nodes first!
141
+
↓
142
+
DO WORK → Log BEFORE each action
143
+
↓
144
+
CONNECT → Link new nodes immediately
145
+
↓
146
+
AFTER CHANGES → Log outcomes, observations
147
+
↓
148
+
AUDIT AGAIN → Any new orphans?
149
+
↓
150
+
BEFORE PUSH → deciduous sync
151
+
↓
152
+
PUSH → Live graph updates
153
+
↓
154
+
SESSION END → Final audit
155
+
↓
156
+
(repeat)
157
+
```
158
+
159
+
**Live graph**: https://notactuallytreyanastasio.github.io/deciduous/
160
+
161
+
---
162
+
163
+
## Multi-User Sync
164
+
165
+
If working in a team, check for and apply patches from teammates:
166
+
167
+
```bash
168
+
# Check for unapplied patches
169
+
deciduous diff status
170
+
171
+
# Apply all patches (idempotent - safe to run multiple times)
172
+
deciduous diff apply .deciduous/patches/*.json
173
+
174
+
# Preview before applying
175
+
deciduous diff apply --dry-run .deciduous/patches/teammate-feature.json
176
+
```
177
+
178
+
Before pushing your branch, export your decisions for teammates:
179
+
180
+
```bash
181
+
# Export your branch's decisions as a patch
182
+
deciduous diff export --branch $(git rev-parse --abbrev-ref HEAD) \
183
+
-o .deciduous/patches/$(whoami)-$(git rev-parse --abbrev-ref HEAD).json
184
+
185
+
# Commit the patch file
186
+
git add .deciduous/patches/
187
+
```
188
+
189
+
## Why This Matters
190
+
191
+
- Context loss during compaction loses your reasoning
192
+
- The graph survives - query it early, query it often
193
+
- Retroactive logging misses details - log in the moment
194
+
- The user sees the graph live - show your work
195
+
- Patches share reasoning with teammates
+302
.claude/commands/decision.md
+302
.claude/commands/decision.md
···
1
+
---
2
+
description: Manage decision graph - track algorithm choices and reasoning
3
+
allowed-tools: Bash(deciduous:*)
4
+
argument-hint: <action> [args...]
5
+
---
6
+
7
+
# Decision Graph Management
8
+
9
+
**Log decisions IN REAL-TIME as you work, not retroactively.**
10
+
11
+
## When to Use This
12
+
13
+
| You're doing this... | Log this type | Command |
14
+
| --------------------------- | ------------------ | ------------------------------------------------------ |
15
+
| Starting a new feature | `goal` **with -p** | `/decision add goal "Add user auth" -p "user request"` |
16
+
| Choosing between approaches | `decision` | `/decision add decision "Choose auth method"` |
17
+
| Considering an option | `option` | `/decision add option "JWT tokens"` |
18
+
| About to write code | `action` | `/decision add action "Implementing JWT"` |
19
+
| Noticing something | `observation` | `/decision add obs "Found existing auth code"` |
20
+
| Finished something | `outcome` | `/decision add outcome "JWT working"` |
21
+
22
+
## Quick Commands
23
+
24
+
Based on $ARGUMENTS:
25
+
26
+
### View Commands
27
+
28
+
- `nodes` or `list` -> `deciduous nodes`
29
+
- `edges` -> `deciduous edges`
30
+
- `graph` -> `deciduous graph`
31
+
- `commands` -> `deciduous commands`
32
+
33
+
### Create Nodes (with optional metadata)
34
+
35
+
- `add goal <title>` -> `deciduous add goal "<title>" -c 90`
36
+
- `add decision <title>` -> `deciduous add decision "<title>" -c 75`
37
+
- `add option <title>` -> `deciduous add option "<title>" -c 70`
38
+
- `add action <title>` -> `deciduous add action "<title>" -c 85`
39
+
- `add obs <title>` -> `deciduous add observation "<title>" -c 80`
40
+
- `add outcome <title>` -> `deciduous add outcome "<title>" -c 90`
41
+
42
+
### Optional Flags for Nodes
43
+
44
+
- `-c, --confidence <0-100>` - Confidence level
45
+
- `-p, --prompt "..."` - Store the user prompt that triggered this node
46
+
- `-f, --files "file1.rs,file2.rs"` - Associate files with this node
47
+
- `-b, --branch <name>` - Git branch (auto-detected by default)
48
+
- `--no-branch` - Skip branch auto-detection
49
+
- `--commit <hash|HEAD>` - Link to a git commit (use HEAD for current commit)
50
+
51
+
### ⚠️ CRITICAL: Link Commits to Actions/Outcomes
52
+
53
+
**After every git commit, link it to the decision graph!**
54
+
55
+
```bash
56
+
git commit -m "feat: add auth"
57
+
deciduous add action "Implemented auth" -c 90 --commit HEAD
58
+
deciduous link <goal_id> <action_id> -r "Implementation"
59
+
```
60
+
61
+
## CRITICAL: Capture VERBATIM User Prompts
62
+
63
+
**Prompts must be the EXACT user message, not a summary.** When a user request triggers new work, capture their full message word-for-word.
64
+
65
+
**BAD - summaries are useless for context recovery:**
66
+
67
+
```bash
68
+
# DON'T DO THIS - this is a summary, not a prompt
69
+
deciduous add goal "Add auth" -p "User asked: add login to the app"
70
+
```
71
+
72
+
**GOOD - verbatim prompts enable full context recovery:**
73
+
74
+
```bash
75
+
# Use --prompt-stdin for multi-line prompts
76
+
deciduous add goal "Add auth" -c 90 --prompt-stdin << 'EOF'
77
+
I need to add user authentication to the app. Users should be able to sign up
78
+
with email/password, and we need OAuth support for Google and GitHub. The auth
79
+
should use JWT tokens with refresh token rotation.
80
+
EOF
81
+
82
+
# Or use the prompt command to update existing nodes
83
+
deciduous prompt 42 << 'EOF'
84
+
The full verbatim user message goes here...
85
+
EOF
86
+
```
87
+
88
+
**When to capture prompts:**
89
+
90
+
- Root `goal` nodes: YES - the FULL original request
91
+
- Major direction changes: YES - when user redirects the work
92
+
- Routine downstream nodes: NO - they inherit context via edges
93
+
94
+
**Updating prompts on existing nodes:**
95
+
96
+
```bash
97
+
deciduous prompt <node_id> "full verbatim prompt here"
98
+
cat prompt.txt | deciduous prompt <node_id> # Multi-line from stdin
99
+
```
100
+
101
+
Prompts are viewable in the TUI detail panel (`deciduous tui`) and web viewer.
102
+
103
+
## Branch-Based Grouping
104
+
105
+
**Nodes are automatically tagged with the current git branch.** This enables filtering by feature/PR.
106
+
107
+
### How It Works
108
+
109
+
- When you create a node, the current git branch is stored in `metadata_json`
110
+
- Configure which branches are "main" in `.deciduous/config.toml`:
111
+
```toml
112
+
[branch]
113
+
main_branches = ["main", "master"] # Branches not treated as "feature branches"
114
+
auto_detect = true # Auto-detect branch on node creation
115
+
```
116
+
- Nodes on feature branches (anything not in `main_branches`) can be grouped/filtered
117
+
118
+
### CLI Filtering
119
+
120
+
```bash
121
+
# Show only nodes from specific branch
122
+
deciduous nodes --branch main
123
+
deciduous nodes --branch feature-auth
124
+
deciduous nodes -b my-feature
125
+
126
+
# Override auto-detection when creating nodes
127
+
deciduous add goal "Feature work" -b feature-x # Force specific branch
128
+
deciduous add goal "Universal note" --no-branch # No branch tag
129
+
```
130
+
131
+
### Web UI Branch Filter
132
+
133
+
The graph viewer shows a branch dropdown in the stats bar:
134
+
135
+
- "All branches" shows everything
136
+
- Select a specific branch to filter all views (Chains, Timeline, Graph, DAG)
137
+
138
+
### When to Use Branch Grouping
139
+
140
+
- **Feature work**: Nodes created on `feature-auth` branch auto-grouped
141
+
- **PR context**: Filter to see only decisions for a specific PR
142
+
- **Cross-cutting concerns**: Use `--no-branch` for universal notes
143
+
- **Retrospectives**: Filter by branch to see decision history per feature
144
+
145
+
### Create Edges
146
+
147
+
- `link <from> <to> [reason]` -> `deciduous link <from> <to> -r "<reason>"`
148
+
149
+
### Sync Graph
150
+
151
+
- `sync` -> `deciduous sync`
152
+
153
+
### Multi-User Sync (Diff/Patch)
154
+
155
+
- `diff export -o <file>` -> `deciduous diff export -o <file>` (export nodes as patch)
156
+
- `diff export --nodes 1-10 -o <file>` -> export specific nodes
157
+
- `diff export --branch feature-x -o <file>` -> export nodes from branch
158
+
- `diff apply <file>` -> `deciduous diff apply <file>` (apply patch, idempotent)
159
+
- `diff apply --dry-run <file>` -> preview without applying
160
+
- `diff status` -> `deciduous diff status` (list patches in .deciduous/patches/)
161
+
- `migrate` -> `deciduous migrate` (add change_id columns for sync)
162
+
163
+
### Export & Visualization
164
+
165
+
- `dot` -> `deciduous dot` (output DOT to stdout)
166
+
- `dot --png` -> `deciduous dot --png -o graph.dot` (generate PNG)
167
+
- `dot --nodes 1-11` -> `deciduous dot --nodes 1-11` (filter nodes)
168
+
- `writeup` -> `deciduous writeup` (generate PR writeup)
169
+
- `writeup -t "Title" --nodes 1-11` -> filtered writeup
170
+
171
+
## Node Types
172
+
173
+
| Type | Purpose | Example |
174
+
| ------------- | ------------------------- | ----------------------------- |
175
+
| `goal` | High-level objective | "Add user authentication" |
176
+
| `decision` | Choice point with options | "Choose auth method" |
177
+
| `option` | Possible approach | "Use JWT tokens" |
178
+
| `action` | Something implemented | "Added JWT middleware" |
179
+
| `outcome` | Result of action | "JWT auth working" |
180
+
| `observation` | Finding or data point | "Existing code uses sessions" |
181
+
182
+
## Edge Types
183
+
184
+
| Type | Meaning |
185
+
| ---------- | ------------------------------ |
186
+
| `leads_to` | Natural progression |
187
+
| `chosen` | Selected option |
188
+
| `rejected` | Not selected (include reason!) |
189
+
| `requires` | Dependency |
190
+
| `blocks` | Preventing progress |
191
+
| `enables` | Makes something possible |
192
+
193
+
## Graph Integrity - CRITICAL
194
+
195
+
**Every node MUST be logically connected.** Floating nodes break the graph's value.
196
+
197
+
### Connection Rules
198
+
199
+
| Node Type | MUST connect to | Example |
200
+
| ------------- | --------------------------------- | ---------------------------------------------- |
201
+
| `outcome` | The action/goal it resolves | "JWT working" → links FROM "Implementing JWT" |
202
+
| `action` | The decision/goal that spawned it | "Implementing JWT" → links FROM "Add auth" |
203
+
| `option` | Its parent decision | "Use JWT" → links FROM "Choose auth method" |
204
+
| `observation` | Related goal/action/decision | "Found existing code" → links TO relevant node |
205
+
| `decision` | Parent goal (if any) | "Choose auth" → links FROM "Add auth feature" |
206
+
| `goal` | Can be a root (no parent needed) | Root goals are valid orphans |
207
+
208
+
### Audit Checklist
209
+
210
+
Ask yourself after creating nodes:
211
+
212
+
1. Does every **outcome** link back to what caused it?
213
+
2. Does every **action** link to why you did it?
214
+
3. Does every **option** link to its decision?
215
+
4. Are there **dangling outcomes** with no parent action/goal?
216
+
217
+
### Find Disconnected Nodes
218
+
219
+
```bash
220
+
# List nodes with no incoming edges (potential orphans)
221
+
deciduous edges | cut -d'>' -f2 | cut -d' ' -f2 | sort -u > /tmp/has_parent.txt
222
+
deciduous nodes | tail -n+3 | awk '{print $1}' | while read id; do
223
+
grep -q "^$id$" /tmp/has_parent.txt || echo "CHECK: $id"
224
+
done
225
+
```
226
+
227
+
Note: Root goals are VALID orphans. Outcomes/actions/options usually are NOT.
228
+
229
+
### Fix Missing Connections
230
+
231
+
```bash
232
+
deciduous link <parent_id> <child_id> -r "Retroactive connection - <why>"
233
+
```
234
+
235
+
### When to Audit
236
+
237
+
- Before every `deciduous sync`
238
+
- After creating multiple nodes quickly
239
+
- At session end
240
+
- When the web UI graph looks disconnected
241
+
242
+
## Multi-User Sync
243
+
244
+
**Problem**: Multiple users work on the same codebase, each with a local `.deciduous/deciduous.db` (gitignored). How to share decisions?
245
+
246
+
**Solution**: jj-inspired dual-ID model. Each node has:
247
+
248
+
- `id` (integer): Local database primary key, different per machine
249
+
- `change_id` (UUID): Globally unique, stable across all databases
250
+
251
+
### Export Workflow
252
+
253
+
```bash
254
+
# Export nodes from your branch as a patch file
255
+
deciduous diff export --branch feature-x -o .deciduous/patches/alice-feature.json
256
+
257
+
# Or export specific node IDs
258
+
deciduous diff export --nodes 172-188 -o .deciduous/patches/alice-feature.json --author alice
259
+
```
260
+
261
+
### Apply Workflow
262
+
263
+
```bash
264
+
# Apply patches from teammates (idempotent - safe to re-apply)
265
+
deciduous diff apply .deciduous/patches/*.json
266
+
267
+
# Preview what would change
268
+
deciduous diff apply --dry-run .deciduous/patches/bob-refactor.json
269
+
```
270
+
271
+
### PR Workflow
272
+
273
+
1. Create nodes locally while working
274
+
2. Export: `deciduous diff export --branch my-feature -o .deciduous/patches/my-feature.json`
275
+
3. Commit the patch file (NOT the database)
276
+
4. Open PR with patch file included
277
+
5. Teammates pull and apply: `deciduous diff apply .deciduous/patches/my-feature.json`
278
+
6. **Idempotent**: Same patch applied twice = no duplicates
279
+
280
+
### Patch Format (JSON)
281
+
282
+
```json
283
+
{
284
+
"version": "1.0",
285
+
"author": "alice",
286
+
"branch": "feature/auth",
287
+
"nodes": [{ "change_id": "uuid...", "title": "...", ... }],
288
+
"edges": [{ "from_change_id": "uuid1", "to_change_id": "uuid2", ... }]
289
+
}
290
+
```
291
+
292
+
## The Rule
293
+
294
+
```
295
+
LOG BEFORE YOU CODE, NOT AFTER.
296
+
CONNECT EVERY NODE TO ITS PARENT.
297
+
AUDIT FOR ORPHANS REGULARLY.
298
+
SYNC BEFORE YOU PUSH.
299
+
EXPORT PATCHES FOR YOUR TEAMMATES.
300
+
```
301
+
302
+
**Live graph**: https://notactuallytreyanastasio.github.io/deciduous/
+3
.gitignore
+3
.gitignore
+173
CLAUDE.md
+173
CLAUDE.md
···
58
58
be sure
59
59
- Task tool (subagents for exploration, planning, etc.) may not always be accurate; verify subagent
60
60
findings when needed
61
+
62
+
## Decision Graph Workflow
63
+
64
+
**THIS IS MANDATORY. Log decisions IN REAL-TIME, not retroactively.**
65
+
66
+
### The Core Rule
67
+
68
+
```
69
+
BEFORE you do something -> Log what you're ABOUT to do
70
+
AFTER it succeeds/fails -> Log the outcome
71
+
CONNECT immediately -> Link every node to its parent
72
+
AUDIT regularly -> Check for missing connections
73
+
```
74
+
75
+
### Behavioral Triggers - MUST LOG WHEN:
76
+
77
+
| Trigger | Log Type | Example |
78
+
| ---------------------------- | ------------------ | ------------------------------ |
79
+
| User asks for a new feature | `goal` **with -p** | "Add dark mode" |
80
+
| Choosing between approaches | `decision` | "Choose state management" |
81
+
| About to write/edit code | `action` | "Implementing Redux store" |
82
+
| Something worked or failed | `outcome` | "Redux integration successful" |
83
+
| Notice something interesting | `observation` | "Existing code uses hooks" |
84
+
85
+
### CRITICAL: Capture VERBATIM User Prompts
86
+
87
+
**Prompts must be the EXACT user message, not a summary.** When a user request triggers new work,
88
+
capture their full message word-for-word.
89
+
90
+
**BAD - summaries are useless for context recovery:**
91
+
92
+
```bash
93
+
# DON'T DO THIS - this is a summary, not a prompt
94
+
deciduous add goal "Add auth" -p "User asked: add login to the app"
95
+
```
96
+
97
+
**GOOD - verbatim prompts enable full context recovery:**
98
+
99
+
```bash
100
+
# Use --prompt-stdin for multi-line prompts
101
+
deciduous add goal "Add auth" -c 90 --prompt-stdin << 'EOF'
102
+
I need to add user authentication to the app. Users should be able to sign up
103
+
with email/password, and we need OAuth support for Google and GitHub. The auth
104
+
should use JWT tokens with refresh token rotation.
105
+
EOF
106
+
107
+
# Or use the prompt command to update existing nodes
108
+
deciduous prompt 42 << 'EOF'
109
+
The full verbatim user message goes here...
110
+
EOF
111
+
```
112
+
113
+
**When to capture prompts:**
114
+
115
+
- Root `goal` nodes: YES - the FULL original request
116
+
- Major direction changes: YES - when user redirects the work
117
+
- Routine downstream nodes: NO - they inherit context via edges
118
+
119
+
**Updating prompts on existing nodes:**
120
+
121
+
```bash
122
+
deciduous prompt <node_id> "full verbatim prompt here"
123
+
cat prompt.txt | deciduous prompt <node_id> # Multi-line from stdin
124
+
```
125
+
126
+
Prompts are viewable in the TUI detail panel (`deciduous tui`) and web viewer.
127
+
128
+
### ⚠️ CRITICAL: Maintain Connections
129
+
130
+
**The graph's value is in its CONNECTIONS, not just nodes.**
131
+
132
+
| When you create... | IMMEDIATELY link to... |
133
+
| ------------------ | --------------------------------- |
134
+
| `outcome` | The action/goal it resolves |
135
+
| `action` | The goal/decision that spawned it |
136
+
| `option` | Its parent decision |
137
+
| `observation` | Related goal/action |
138
+
139
+
**Root `goal` nodes are the ONLY valid orphans.**
140
+
141
+
### Quick Commands
142
+
143
+
```bash
144
+
deciduous add goal "Title" -c 90 -p "User's original request"
145
+
deciduous add action "Title" -c 85
146
+
deciduous link FROM TO -r "reason" # DO THIS IMMEDIATELY!
147
+
deciduous serve # View live (auto-refreshes every 30s)
148
+
deciduous sync # Export for static hosting
149
+
150
+
# Metadata flags
151
+
# -c, --confidence 0-100 Confidence level
152
+
# -p, --prompt "..." Store the user prompt (use when semantically meaningful)
153
+
# -f, --files "a.rs,b.rs" Associate files
154
+
# -b, --branch <name> Git branch (auto-detected)
155
+
# --commit <hash|HEAD> Link to git commit (use HEAD for current commit)
156
+
157
+
# Branch filtering
158
+
deciduous nodes --branch main
159
+
deciduous nodes -b feature-auth
160
+
```
161
+
162
+
### ⚠️ CRITICAL: Link Commits to Actions/Outcomes
163
+
164
+
**After every git commit, link it to the decision graph!**
165
+
166
+
```bash
167
+
git commit -m "feat: add auth"
168
+
deciduous add action "Implemented auth" -c 90 --commit HEAD
169
+
deciduous link <goal_id> <action_id> -r "Implementation"
170
+
```
171
+
172
+
The `--commit HEAD` flag captures the commit hash and links it to the node. The web viewer will show
173
+
commit messages, authors, and dates.
174
+
175
+
### Git History & Deployment
176
+
177
+
```bash
178
+
# Export graph AND git history for web viewer
179
+
deciduous sync
180
+
181
+
# This creates:
182
+
# - docs/graph-data.json (decision graph)
183
+
# - docs/git-history.json (commit info for linked nodes)
184
+
```
185
+
186
+
To deploy to GitHub Pages:
187
+
188
+
1. `deciduous sync` to export
189
+
2. Push to GitHub
190
+
3. Settings > Pages > Deploy from branch > /docs folder
191
+
192
+
Your graph will be live at `https://<user>.github.io/<repo>/`
193
+
194
+
### Branch-Based Grouping
195
+
196
+
Nodes are auto-tagged with the current git branch. Configure in `.deciduous/config.toml`:
197
+
198
+
```toml
199
+
[branch]
200
+
main_branches = ["main", "master"]
201
+
auto_detect = true
202
+
```
203
+
204
+
### Audit Checklist (Before Every Sync)
205
+
206
+
1. Does every **outcome** link back to what caused it?
207
+
2. Does every **action** link to why you did it?
208
+
3. Any **dangling outcomes** without parents?
209
+
210
+
### Session Start Checklist
211
+
212
+
```bash
213
+
deciduous nodes # What decisions exist?
214
+
deciduous edges # How are they connected? Any gaps?
215
+
git status # Current state
216
+
```
217
+
218
+
### Multi-User Sync
219
+
220
+
Share decisions across teammates:
221
+
222
+
```bash
223
+
# Export your branch's decisions
224
+
deciduous diff export --branch feature-x -o .deciduous/patches/my-feature.json
225
+
226
+
# Apply patches from teammates (idempotent)
227
+
deciduous diff apply .deciduous/patches/*.json
228
+
229
+
# Preview before applying
230
+
deciduous diff apply --dry-run .deciduous/patches/teammate.json
231
+
```
232
+
233
+
PR workflow: Export patch → commit patch file → PR → teammates apply.