mary.my.id / danaus
work-in-progress atproto PDS
typescript atproto pds atcute
4
fork

Configure Feed

Select the types of activity you want to include in your feed.

chore: update CLAUDE.md

Mary 0a5a8488 9c43c3f1

+17 -213
+17 -213
CLAUDE.md
··· 19 19 20 20 - new files should be in kebab-case 21 21 - use tabs for indentation, spaces allowed for diagrams in comments 22 - - use single quotes and add trailing commas 22 + - use single quotes for strings; use template literals for localization strings (user-facing 23 + strings, error messages) 24 + - add trailing commas 23 25 - prefer arrow functions, but use regular methods in classes unless arrow functions are necessary 24 26 (e.g., when passing the method as a callback that needs `this` binding) 25 27 - use braces for control statements, even single-line bodies 26 28 - use bare blocks `{ }` to group related code and limit variable scope 27 - - use template literals for user-facing strings and error messages 28 29 - avoid barrel exports (index files that re-export from other modules); import directly from source 29 30 - use `// #region <name>` and `// #endregion` to denote regions when a file needs to contain a lot 30 31 of code 31 - - prefer required parameters over optional ones; optional parameters are acceptable when: 32 - - the default is obvious and used by the vast majority of callers (e.g., `encoding = 'utf-8'`) 33 - - it's a configuration value with a sensible default (e.g., `timeout = 5000`) 32 + - a parameter should be optional only when callers genuinely split between passing a value and 33 + relying on the default; if every caller passes a value, make it required; if no caller would ever 34 + change it, it should not be a parameter at all 34 35 - avoid optional parameters that change behavioral modes or make the function do different things 35 - based on presence/absence; prefer separate functions instead 36 - - when adding optional parameters for backwards compatibility, consider whether a new function with 37 - a clearer name would be better 36 + based on presence/absence; prefer a separate function with a clearer name instead 37 + - avoid type assertions (`as Type`, `as const`) unless TypeScript actually errors without them; when 38 + it does error, prefer finding a solution that satisfies the type system naturally before resorting 39 + to an assertion 38 40 39 41 ### documentation 40 42 ··· 61 63 pause and ask for clarification when you're still unsure after looking into it 62 64 - in plan mode, present the plan for review before exiting to allow for feedback or follow-up 63 65 questions 64 - - when debugging problems, isolate the root cause first before attempting fixes: add logging, 65 - reproduce the issue, narrow down the scope, and confirm the exact source of the problem 66 + - when debugging problems, isolate the root cause first before attempting fixes; suggest adding 67 + logging and let the user reproduce and share the output, unless you can verify directly (e.g., by 68 + running tests or reading existing error output) 66 69 67 70 ### Claude Code-specific 68 71 69 - - Explore tool (subagents for exploration, planning, etc.) may not always be accurate; verify 70 - subagent findings when needed 71 - 72 - ### cgr 73 - 74 - use `@oomfware/cgr` to ask questions about external repositories. 75 - 76 - ``` 77 - npx @oomfware/cgr ask [options] <repo>[#branch] <question> 78 - 79 - options: 80 - -m, --model <model> model to use: opus, sonnet, haiku (default: haiku) 81 - -d, --deep clone full history (enables git log/blame/show) 82 - -w, --with <repo> additional repository to include, supports #branch (repeatable) 83 - ``` 84 - 85 - useful repositories: 86 - 87 - - `github.com/bluesky-social/atproto` for AT Protocol reference implementation, lexicons, XRPC 88 - - `github.com/ascorbic/cirrus` for TypeScript PDS on Cloudflare Workers, @atcute usage patterns 89 - - `github.com/haileyok/cocoon` for Go PDS implementation 90 - - `github.com/davidbuchanan314/millipds` for Python PDS implementation 91 - - `github.com/davidbuchanan314/atmst` for MST internals (Python) 92 - - `tangled.org/futur.blue/pegasus` for OCaml PDS + atproto libraries 93 - - `tangled.org/tranquil.farm/tranquil-pds` for Rust PDS implementation 94 - 95 - broad questions work for getting oriented; detailed questions get precise answers. include 96 - file/folder paths when you know them, and reference details from previous answers in follow-ups. 97 - 98 - run `npx @oomfware/cgr --help` for more options. 99 - 100 - ## Decision Graph Workflow 101 - 102 - **THIS IS MANDATORY. Log decisions IN REAL-TIME, not retroactively.** 103 - 104 - ### The Core Rule 105 - 106 - ``` 107 - BEFORE you do something -> Log what you're ABOUT to do 108 - AFTER it succeeds/fails -> Log the outcome 109 - CONNECT immediately -> Link every node to its parent 110 - AUDIT regularly -> Check for missing connections 111 - ``` 112 - 113 - ### Behavioral Triggers - MUST LOG WHEN: 114 - 115 - | Trigger | Log Type | Example | 116 - | ---------------------------- | ------------------ | ------------------------------ | 117 - | User asks for a new feature | `goal` **with -p** | "Add dark mode" | 118 - | Choosing between approaches | `decision` | "Choose state management" | 119 - | About to write/edit code | `action` | "Implementing Redux store" | 120 - | Something worked or failed | `outcome` | "Redux integration successful" | 121 - | Notice something interesting | `observation` | "Existing code uses hooks" | 122 - 123 - ### CRITICAL: Capture VERBATIM User Prompts 124 - 125 - **Prompts must be the EXACT user message, not a summary.** When a user request triggers new work, 126 - capture their full message word-for-word. 127 - 128 - **BAD - summaries are useless for context recovery:** 129 - 130 - ```bash 131 - # DON'T DO THIS - this is a summary, not a prompt 132 - deciduous add goal "Add auth" -p "User asked: add login to the app" 133 - ``` 134 - 135 - **GOOD - verbatim prompts enable full context recovery:** 136 - 137 - ```bash 138 - # Use --prompt-stdin for multi-line prompts 139 - deciduous add goal "Add auth" -c 90 --prompt-stdin << 'EOF' 140 - I need to add user authentication to the app. Users should be able to sign up 141 - with email/password, and we need OAuth support for Google and GitHub. The auth 142 - should use JWT tokens with refresh token rotation. 143 - EOF 144 - 145 - # Or use the prompt command to update existing nodes 146 - deciduous prompt 42 << 'EOF' 147 - The full verbatim user message goes here... 148 - EOF 149 - ``` 150 - 151 - **When to capture prompts:** 152 - 153 - - Root `goal` nodes: YES - the FULL original request 154 - - Major direction changes: YES - when user redirects the work 155 - - Routine downstream nodes: NO - they inherit context via edges 156 - 157 - **Updating prompts on existing nodes:** 158 - 159 - ```bash 160 - deciduous prompt <node_id> "full verbatim prompt here" 161 - cat prompt.txt | deciduous prompt <node_id> # Multi-line from stdin 162 - ``` 163 - 164 - Prompts are viewable in the TUI detail panel (`deciduous tui`) and web viewer. 165 - 166 - ### ⚠️ CRITICAL: Maintain Connections 167 - 168 - **The graph's value is in its CONNECTIONS, not just nodes.** 169 - 170 - | When you create... | IMMEDIATELY link to... | 171 - | ------------------ | --------------------------------- | 172 - | `outcome` | The action/goal it resolves | 173 - | `action` | The goal/decision that spawned it | 174 - | `option` | Its parent decision | 175 - | `observation` | Related goal/action | 176 - 177 - **Root `goal` nodes are the ONLY valid orphans.** 178 - 179 - ### Quick Commands 180 - 181 - ```bash 182 - deciduous add goal "Title" -c 90 -p "User's original request" 183 - deciduous add action "Title" -c 85 184 - deciduous link FROM TO -r "reason" # DO THIS IMMEDIATELY! 185 - deciduous serve # View live (auto-refreshes every 30s) 186 - deciduous sync # Export for static hosting 187 - 188 - # Metadata flags 189 - # -c, --confidence 0-100 Confidence level 190 - # -p, --prompt "..." Store the user prompt (use when semantically meaningful) 191 - # -f, --files "a.rs,b.rs" Associate files 192 - # -b, --branch <name> Git branch (auto-detected) 193 - # --commit <hash|HEAD> Link to git commit (use HEAD for current commit) 194 - 195 - # Branch filtering 196 - deciduous nodes --branch main 197 - deciduous nodes -b feature-auth 198 - ``` 199 - 200 - ### ⚠️ CRITICAL: Link Commits to Actions/Outcomes 201 - 202 - **After every git commit, link it to the decision graph!** 203 - 204 - ```bash 205 - git commit -m "feat: add auth" 206 - deciduous add action "Implemented auth" -c 90 --commit HEAD 207 - deciduous link <goal_id> <action_id> -r "Implementation" 208 - ``` 209 - 210 - The `--commit HEAD` flag captures the commit hash and links it to the node. The web viewer will show 211 - commit messages, authors, and dates. 212 - 213 - ### Git History & Deployment 214 - 215 - ```bash 216 - # Export graph AND git history for web viewer 217 - deciduous sync 218 - 219 - # This creates: 220 - # - docs/graph-data.json (decision graph) 221 - # - docs/git-history.json (commit info for linked nodes) 222 - ``` 223 - 224 - To deploy to GitHub Pages: 225 - 226 - 1. `deciduous sync` to export 227 - 2. Push to GitHub 228 - 3. Settings > Pages > Deploy from branch > /docs folder 229 - 230 - Your graph will be live at `https://<user>.github.io/<repo>/` 231 - 232 - ### Branch-Based Grouping 233 - 234 - Nodes are auto-tagged with the current git branch. Configure in `.deciduous/config.toml`: 235 - 236 - ```toml 237 - [branch] 238 - main_branches = ["main", "master"] 239 - auto_detect = true 240 - ``` 241 - 242 - ### Audit Checklist (Before Every Sync) 243 - 244 - 1. Does every **outcome** link back to what caused it? 245 - 2. Does every **action** link to why you did it? 246 - 3. Any **dangling outcomes** without parents? 247 - 248 - ### Session Start Checklist 249 - 250 - ```bash 251 - deciduous nodes # What decisions exist? 252 - deciduous edges # How are they connected? Any gaps? 253 - git status # Current state 254 - ``` 255 - 256 - ### Multi-User Sync 257 - 258 - Share decisions across teammates: 259 - 260 - ```bash 261 - # Export your branch's decisions 262 - deciduous diff export --branch feature-x -o .deciduous/patches/my-feature.json 263 - 264 - # Apply patches from teammates (idempotent) 265 - deciduous diff apply .deciduous/patches/*.json 266 - 267 - # Preview before applying 268 - deciduous diff apply --dry-run .deciduous/patches/teammate.json 269 - ``` 270 - 271 - PR workflow: Export patch → commit patch file → PR → teammates apply. 72 + - Explore subagent may not be accurate; verify findings as needed 73 + - only spawn subagents when there is genuine independent work to parallelize (e.g. searching across 74 + many files, answering a question requiring broad exploration.) never use them as file I/O proxies 75 + — read files directly in the main context, and prefer direct tool calls when they suffice.