-65

.opencode/agents/deciduous.md

Reviewed

··· 1 1 - --- 2 2 - description: Deciduous decision graph specialist - manages nodes, edges, and graph operations 3 3 - mode: subagent 4 4 - --- 5 5 - 6 6 - # Deciduous Agent 7 7 - 8 8 - You are a specialized agent for managing the deciduous decision graph. Use the `deciduous` CLI to manage nodes, edges, and graph operations. 9 9 - 10 10 - ## Core Commands 11 11 - 12 12 - ```bash 13 13 - # Add nodes 14 14 - deciduous add goal "Title" -c 90 -p "User request" 15 15 - deciduous add option "Approach" -c 70 16 16 - deciduous add decision "Choice" -c 85 17 17 - deciduous add action "Implementation" -c 85 -f "file1.rs,file2.rs" 18 18 - deciduous add outcome "Result" -c 95 --commit HEAD 19 19 - deciduous add observation "Finding" -c 80 20 20 - deciduous add revisit "Reconsidering" -c 75 21 21 - 22 22 - # Connect nodes (ALWAYS do this immediately) 23 23 - deciduous link <from> <to> -r "reason" 24 24 - 25 25 - # Query 26 26 - deciduous nodes 27 27 - deciduous edges 28 28 - deciduous graph 29 29 - deciduous pulse 30 30 - 31 31 - # Sync and export 32 32 - deciduous sync 33 33 - deciduous dot --png 34 34 - ``` 35 35 - 36 36 - ## Node Flow Rule 37 37 - 38 38 - ``` 39 39 - goal -> options -> decision -> actions -> outcomes 40 40 - ``` 41 41 - 42 42 - - Goals lead to options (possible approaches) 43 43 - - Options lead to decisions (choosing which option) 44 44 - - Decisions lead to actions (implementation) 45 45 - - Actions lead to outcomes (results) 46 46 - - Observations attach anywhere relevant 47 47 - - Root goals are the ONLY valid orphans 48 48 - 49 49 - ## Connection Rules 50 50 - 51 51 - | When you create... | IMMEDIATELY link to... | 52 52 - | ------------------ | ------------------------------- | 53 53 - | `option` | Its parent goal | 54 54 - | `decision` | The option(s) it chose between | 55 55 - | `action` | The decision that spawned it | 56 56 - | `outcome` | The action that produced it | 57 57 - | `observation` | Related goal/action | 58 58 - | `revisit` | The decision being reconsidered | 59 59 - 60 60 - ## After Git Commits 61 61 - 62 62 - ```bash 63 63 - deciduous add outcome "What was accomplished" -c 95 --commit HEAD 64 64 - deciduous link <action_id> <outcome_id> -r "Implementation complete" 65 65 - ```

+423

.opencode/commands/decision.md

View file Reviewed

··· 346 346 ``` 347 347 348 348 **Live graph**: https://notactuallytreyanastasio.github.io/deciduous/ 349 349 + 350 350 + ## Workflow: /work 351 351 + 352 352 + **USE THIS BEFORE STARTING ANY IMPLEMENTATION.** 353 353 + 354 354 + This skill creates the required deciduous nodes BEFORE you write any code. The `require-action-node` plugin will nag to `.deciduous/plugin.log` if you don't have a recent node — it does not block edits. The post-commit-reminder plugin will nag again to link the commit. Treat the nags as guardrails, not gates. 355 355 + 356 356 + ### Step 1: Create the Goal Node 357 357 + 358 358 + Based on $GOAL (or the user's most recent request), create a goal node: 359 359 + 360 360 + ```bash 361 361 + # Create goal with the user's request captured verbatim 362 362 + deciduous add goal "$GOAL" -c 90 --prompt-stdin << 'EOF' 363 363 + [INSERT THE EXACT USER REQUEST HERE - VERBATIM, NOT SUMMARIZED] 364 364 + EOF 365 365 + ``` 366 366 + 367 367 + **IMPORTANT**: The prompt must be the user's EXACT words, not your summary. 368 368 + 369 369 + ### Step 2: Announce the Goal ID 370 370 + 371 371 + After creating the goal, tell the user: 372 372 + 373 373 + - The goal ID that was created 374 374 + - What you're about to implement 375 375 + - That you'll create action nodes as you work 376 376 + 377 377 + ### Step 3: Before Each Major Edit 378 378 + 379 379 + Before editing files, create an action node: 380 380 + 381 381 + ```bash 382 382 + deciduous add action "What you're about to implement" -c 85 -f "file1.rs,file2.rs" 383 383 + deciduous link <goal_id> <action_id> -r "Implementation step" 384 384 + ``` 385 385 + 386 386 + ### Step 4: After Completion 387 387 + 388 388 + When the work is done: 389 389 + 390 390 + ```bash 391 391 + # After committing 392 392 + deciduous add outcome "What was accomplished" -c 95 --commit HEAD 393 393 + deciduous link <action_id> <outcome_id> -r "Implementation complete" 394 394 + 395 395 + # Sync the graph 396 396 + deciduous sync 397 397 + ``` 398 398 + 399 399 + ### Step 5: Attach Supporting Documents (Optional) 400 400 + 401 401 + If the work produced or referenced important files (diagrams, specs, screenshots): 402 402 + 403 403 + ```bash 404 404 + deciduous doc attach <goal_id> path/to/diagram.png -d "Architecture diagram" 405 405 + deciduous doc attach <action_id> path/to/spec.pdf --ai-describe 406 406 + ``` 407 407 + 408 408 + If the user shares images or drops in files not in the project, attach them to the most relevant active node. 409 409 + 410 410 + ### The Transaction Model 411 411 + 412 412 + ``` 413 413 + /work "Add feature X" 414 414 + | 415 415 + Goal node created (ID: N) 416 416 + | 417 417 + Action node before each edit (links to goal) 418 418 + | 419 419 + Implementation happens (Edit/Write now allowed) 420 420 + | 421 421 + git commit 422 422 + | 423 423 + Outcome node with --commit HEAD (links to action) 424 424 + | 425 425 + Attach supporting documents (optional) 426 426 + | 427 427 + deciduous sync 428 428 + ``` 429 429 + 430 430 + ### Why This Matters 431 431 + 432 432 + - **The plugins nag, they don't block.** If no recent action/goal exists, `.deciduous/plugin.log` records the reminder; the edit still goes through. Same for post-commit. 433 433 + - **Commits will remind you** to link them to the graph 434 434 + - **The graph captures your reasoning** for future sessions 435 435 + - **Context recovery works** because the graph has everything 436 436 + 437 437 + ### Quick Reference 438 438 + 439 439 + ```bash 440 440 + # Start work 441 441 + deciduous add goal "Feature title" -c 90 -p "User request" 442 442 + 443 443 + # Before editing (required!) 444 444 + deciduous add action "What I'm implementing" -c 85 445 445 + deciduous link <goal> <action> -r "Implementation" 446 446 + 447 447 + # After committing 448 448 + deciduous add outcome "Result" -c 95 --commit HEAD 449 449 + deciduous link <action> <outcome> -r "Complete" 450 450 + 451 451 + # Attach documents (optional) 452 452 + deciduous doc attach <goal> diagram.png -d "Description" 453 453 + 454 454 + # Always sync 455 455 + deciduous sync 456 456 + ``` 457 457 + 458 458 + ## Workflow: /document 459 459 + 460 460 + **Comprehensive documentation that shakes the tree to understand everything.** 461 461 + 462 462 + This skill generates in-depth documentation for a file or directory, focusing on: 463 463 + 464 464 + - Human readability while covering ALL surface area 465 465 + - Linking to tests as working examples 466 466 + - Refining tests to look more real-world if needed 467 467 + - Integration with the deciduous decision graph 468 468 + 469 469 + --- 470 470 + 471 471 + ### Step 1: Create Documentation Goal Node 472 472 + 473 473 + Before documenting, log what you're about to do: 474 474 + 475 475 + ```bash 476 476 + deciduous add goal "Document $TARGET" -c 90 --prompt-stdin << 'EOF' 477 477 + [User's verbatim documentation request] 478 478 + EOF 479 479 + ``` 480 480 + 481 481 + Store the goal ID for linking later. 482 482 + 483 483 + --- 484 484 + 485 485 + ### Step 2: Understand the Target 486 486 + 487 487 + #### For a File 488 488 + 489 489 + 1. **Read the file completely** 490 490 + - Understand every function, class, type, and export 491 491 + - Note all imports and dependencies 492 492 + - Identify the file's role in the larger system 493 493 + 494 494 + 2. **Find tests for this file** 495 495 + - Look for test files with similar names 496 496 + - Search for imports/references in test directories 497 497 + - These will become working examples in the docs 498 498 + 499 499 + 3. **Trace callers/callees** 500 500 + - Who calls this file? 501 501 + - What does this file call? 502 502 + - Map the dependency graph 503 503 + 504 504 + #### For a Directory 505 505 + 506 506 + 1. **Map the structure** 507 507 + - List all files and their purposes 508 508 + - Identify the public API (index/mod files) 509 509 + - Find the entry point 510 510 + 511 511 + 2. **Understand relationships** 512 512 + - How do files in this directory interact? 513 513 + - What's the data flow? 514 514 + 515 515 + 3. **Find related tests** 516 516 + - Test directories that cover this code 517 517 + - Integration tests that exercise the whole module 518 518 + 519 519 + --- 520 520 + 521 521 + ### Step 3: Document Each Component 522 522 + 523 523 + For each file/component, document: 524 524 + 525 525 + #### 3.1 Purpose 526 526 + 527 527 + - One sentence: what does this do? 528 528 + - Why does it exist? (The "why" is more important than the "what") 529 529 + 530 530 + #### 3.2 API Surface 531 531 + 532 532 + For every public function/method/class: 533 533 + 534 534 + ````markdown 535 535 + ### `function_name(param1: Type, param2: Type) -> ReturnType` 536 536 + 537 537 + **Purpose:** What this does and why you'd call it. 538 538 + 539 539 + **Parameters:** 540 540 + 541 541 + - `param1` - Description and valid values 542 542 + - `param2` - Description and valid values 543 543 + 544 544 + **Returns:** What the return value means 545 545 + 546 546 + **Throws/Errors:** What can go wrong 547 547 + 548 548 + **Example:** 549 549 + 550 550 + ```code 551 551 + // From: tests/example_test.rs:42 552 552 + let result = function_name("input", 42); 553 553 + assert_eq!(result, expected); 554 554 + ``` 555 555 + ```` 556 556 + 557 557 + **Related:** Links to related functions 558 558 + 559 559 + #### 3.3 Internal Architecture 560 560 + 561 561 + - How does it work internally? 562 562 + - What are the key data structures? 563 563 + - What are the invariants? 564 564 + 565 565 + #### 3.4 Dependencies 566 566 + 567 567 + - What does this depend on? 568 568 + - What depends on this? 569 569 + 570 570 + #### 3.5 Tests as Examples 571 571 + 572 572 + For each relevant test: 573 573 + 574 574 + - Show the test as a working example 575 575 + - Explain what the test demonstrates 576 576 + - **If test is too synthetic/artificial, REFINE IT:** 577 577 + - Make variable names descriptive 578 578 + - Add comments explaining the scenario 579 579 + - Use realistic values instead of "foo", "bar", 123 580 580 + - Create a deciduous observation node noting the refinement 581 581 + 582 582 + --- 583 583 + 584 584 + ### Step 4: Create Documentation File 585 585 + 586 586 + **Output location:** 587 587 + 588 588 + - For file `src/auth/jwt.rs` -> `docs/src/auth/jwt.rs.md` 589 589 + - For directory `src/auth/` -> `docs/src/auth/README.md` 590 590 + 591 591 + **Document structure:** 592 592 + 593 593 + ````markdown 594 594 + # <Component Name> 595 595 + 596 596 + > One-sentence description 597 597 + 598 598 + ## Overview 599 599 + 600 600 + High-level explanation of what this does and why it exists. 601 601 + 602 602 + ## Quick Start 603 603 + 604 604 + ```code 605 605 + // Most common usage pattern - from real tests 606 606 + ``` 607 607 + ```` 608 608 + 609 609 + ## API Reference 610 610 + 611 611 + [For each public function/type/constant] 612 612 + 613 613 + ### `function_name(...)` 614 614 + 615 615 + [Generated from Step 3.2] 616 616 + 617 617 + ## Architecture 618 618 + 619 619 + [Internal design, data flow, key invariants - from Step 3.3] 620 620 + 621 621 + ## Examples 622 622 + 623 623 + [Tests converted to examples - from Step 3.5] 624 624 + 625 625 + ## Dependencies 626 626 + 627 627 + [What this depends on, what depends on this - from Step 3.4] 628 628 + 629 629 + ## Related Documentation 630 630 + 631 631 + - Links to other relevant docs 632 632 + - Links to test files 633 633 + 634 634 + ```` 635 635 + 636 636 + --- 637 637 + 638 638 + ### Step 5: Refine Tests If Needed 639 639 + 640 640 + If tests are too synthetic (meaningless variable names, unrealistic values): 641 641 + 642 642 + 1. Read the test file 643 643 + 2. Improve it with: 644 644 + - Descriptive variable names (user_email, order_total, not x, y) 645 645 + - Realistic values (not "foo", "bar", 123) 646 646 + - Comments explaining the scenario 647 647 + 3. Edit the test file with improvements 648 648 + 4. Create observation node: 649 649 + 650 650 + ```bash 651 651 + deciduous add observation "Refined tests for <component> - made more real-world" -c 85 652 652 + deciduous link <action_id> <observation_id> -r "Test improvements during documentation" 653 653 + ```` 654 654 + 655 655 + --- 656 656 + 657 657 + ### Step 6: Link to Decision Graph 658 658 + 659 659 + After documentation is complete: 660 660 + 661 661 + ```bash 662 662 + # Create documentation action (if not already created) 663 663 + deciduous add action "Documented <target>" -c 95 -f "<files-created>" 664 664 + 665 665 + # Link to goal 666 666 + deciduous link <goal_id> <action_id> -r "Documentation complete" 667 667 + 668 668 + # Create outcome 669 669 + deciduous add outcome "Documentation complete for <target>" -c 95 670 670 + deciduous link <action_id> <outcome_id> -r "Successfully documented" 671 671 + 672 672 + # Sync 673 673 + deciduous sync 674 674 + ``` 675 675 + 676 676 + --- 677 677 + 678 678 + ### Step 7: Verify Coverage 679 679 + 680 680 + **Checklist before completing:** 681 681 + 682 682 + - [ ] Every public function documented 683 683 + - [ ] Every parameter explained 684 684 + - [ ] Every return value explained 685 685 + - [ ] Every error case documented 686 686 + - [ ] At least one example per function (from tests) 687 687 + - [ ] Architecture overview included 688 688 + - [ ] Dependencies mapped 689 689 + - [ ] Links to tests included 690 690 + - [ ] Tests refined if they were synthetic 691 691 + 692 692 + If anything is missing, go back and fill it in. **Do not miss any surface area.** 693 693 + 694 694 + --- 695 695 + 696 696 + ### Decision Criteria 697 697 + 698 698 + **What to document:** 699 699 + 700 700 + - Public APIs (always) 701 701 + - Complex internal logic (when it's not obvious) 702 702 + - Design decisions (why, not just what) 703 703 + - Edge cases and error handling 704 704 + - Integration points 705 705 + 706 706 + **What NOT to document:** 707 707 + 708 708 + - Trivial getters/setters 709 709 + - Auto-generated code 710 710 + - Implementation details obvious from code 711 711 + 712 712 + **How deep to go:** 713 713 + 714 714 + - Deep enough that someone new could understand and use the code 715 715 + - Deep enough that someone could modify it without breaking things 716 716 + - Capture the "why" behind design decisions 717 717 + 718 718 + --- 719 719 + 720 720 + ### Example Usage 721 721 + 722 722 + ```bash 723 723 + # Document a single file 724 724 + /document src/auth/jwt.rs 725 725 + 726 726 + # Document a directory 727 727 + /document src/auth/ 728 728 + 729 729 + # Document the whole project 730 730 + /document . 731 731 + ``` 732 732 + 733 733 + **What happens:** 734 734 + 735 735 + 1. Goal node created 736 736 + 2. Code analyzed thoroughly 737 737 + 3. Tests found and used as examples 738 738 + 4. Tests refined if synthetic 739 739 + 5. Documentation written to docs/ 740 740 + 6. Action/outcome nodes created 741 741 + 7. Graph synced 742 742 + 743 743 + --- 744 744 + 745 745 + ### Integration with Documentation Enforcement 746 746 + 747 747 + When documentation is created, the `require-documentation.sh` hook will recognize it exists. This creates a virtuous cycle: 748 748 + 749 749 + 1. Can't edit code without documentation (hook blocks) 750 750 + 2. Run `/document` to create documentation 751 751 + 3. Now code edits are allowed 752 752 + 4. When code changes significantly, re-run `/document` 753 753 + 754 754 + --- 755 755 + 756 756 + ### Quick Reference 757 757 + 758 758 + ```bash 759 759 + # Document and generate docs 760 760 + /document <path> 761 761 + 762 762 + # After documenting, you can edit the file 763 763 + # The require-documentation.sh hook will allow it 764 764 + ``` 765 765 + 766 766 + **Always creates:** 767 767 + 768 768 + - Goal node (before starting) 769 769 + - Action node (for the documentation work) 770 770 + - Outcome node (on completion) 771 771 + - Observation nodes (for test refinements)

-321

.opencode/commands/document.md

Reviewed

··· 1 1 - --- 2 2 - description: Document a file or directory comprehensively - shaking the tree to truly understand it 3 3 - arguments: 4 4 - - name: TARGET 5 5 - description: File or directory path to document 6 6 - required: true 7 7 - --- 8 8 - 9 9 - # Document 10 10 - 11 11 - **Comprehensive documentation that shakes the tree to understand everything.** 12 12 - 13 13 - This skill generates in-depth documentation for a file or directory, focusing on: 14 14 - 15 15 - - Human readability while covering ALL surface area 16 16 - - Linking to tests as working examples 17 17 - - Refining tests to look more real-world if needed 18 18 - - Integration with the deciduous decision graph 19 19 - 20 20 - --- 21 21 - 22 22 - ## Step 1: Create Documentation Goal Node 23 23 - 24 24 - Before documenting, log what you're about to do: 25 25 - 26 26 - ```bash 27 27 - deciduous add goal "Document $TARGET" -c 90 --prompt-stdin << 'EOF' 28 28 - [User's verbatim documentation request] 29 29 - EOF 30 30 - ``` 31 31 - 32 32 - Store the goal ID for linking later. 33 33 - 34 34 - --- 35 35 - 36 36 - ## Step 2: Understand the Target 37 37 - 38 38 - ### For a File 39 39 - 40 40 - 1. **Read the file completely** 41 41 - - Understand every function, class, type, and export 42 42 - - Note all imports and dependencies 43 43 - - Identify the file's role in the larger system 44 44 - 45 45 - 2. **Find tests for this file** 46 46 - - Look for test files with similar names 47 47 - - Search for imports/references in test directories 48 48 - - These will become working examples in the docs 49 49 - 50 50 - 3. **Trace callers/callees** 51 51 - - Who calls this file? 52 52 - - What does this file call? 53 53 - - Map the dependency graph 54 54 - 55 55 - ### For a Directory 56 56 - 57 57 - 1. **Map the structure** 58 58 - - List all files and their purposes 59 59 - - Identify the public API (index/mod files) 60 60 - - Find the entry point 61 61 - 62 62 - 2. **Understand relationships** 63 63 - - How do files in this directory interact? 64 64 - - What's the data flow? 65 65 - 66 66 - 3. **Find related tests** 67 67 - - Test directories that cover this code 68 68 - - Integration tests that exercise the whole module 69 69 - 70 70 - --- 71 71 - 72 72 - ## Step 3: Document Each Component 73 73 - 74 74 - For each file/component, document: 75 75 - 76 76 - ### 3.1 Purpose 77 77 - 78 78 - - One sentence: what does this do? 79 79 - - Why does it exist? (The "why" is more important than the "what") 80 80 - 81 81 - ### 3.2 API Surface 82 82 - 83 83 - For every public function/method/class: 84 84 - 85 85 - ````markdown 86 86 - ### `function_name(param1: Type, param2: Type) -> ReturnType` 87 87 - 88 88 - **Purpose:** What this does and why you'd call it. 89 89 - 90 90 - **Parameters:** 91 91 - 92 92 - - `param1` - Description and valid values 93 93 - - `param2` - Description and valid values 94 94 - 95 95 - **Returns:** What the return value means 96 96 - 97 97 - **Throws/Errors:** What can go wrong 98 98 - 99 99 - **Example:** 100 100 - 101 101 - ```code 102 102 - // From: tests/example_test.rs:42 103 103 - let result = function_name("input", 42); 104 104 - assert_eq!(result, expected); 105 105 - ``` 106 106 - ```` 107 107 - 108 108 - **Related:** Links to related functions 109 109 - 110 110 - ```` 111 111 - 112 112 - ### 3.3 Internal Architecture 113 113 - - How does it work internally? 114 114 - - What are the key data structures? 115 115 - - What are the invariants? 116 116 - 117 117 - ### 3.4 Dependencies 118 118 - - What does this depend on? 119 119 - - What depends on this? 120 120 - 121 121 - ### 3.5 Tests as Examples 122 122 - 123 123 - For each relevant test: 124 124 - - Show the test as a working example 125 125 - - Explain what the test demonstrates 126 126 - - **If test is too synthetic/artificial, REFINE IT:** 127 127 - - Make variable names descriptive 128 128 - - Add comments explaining the scenario 129 129 - - Use realistic values instead of "foo", "bar", 123 130 130 - - Create a deciduous observation node noting the refinement 131 131 - 132 132 - --- 133 133 - 134 134 - ## Step 4: Create Documentation File 135 135 - 136 136 - **Output location:** 137 137 - - For file `src/auth/jwt.rs` -> `docs/src/auth/jwt.rs.md` 138 138 - - For directory `src/auth/` -> `docs/src/auth/README.md` 139 139 - 140 140 - **Document structure:** 141 141 - 142 142 - ```markdown 143 143 - # <Component Name> 144 144 - 145 145 - > One-sentence description 146 146 - 147 147 - ## Overview 148 148 - 149 149 - High-level explanation of what this does and why it exists. 150 150 - 151 151 - ## Quick Start 152 152 - 153 153 - ```code 154 154 - // Most common usage pattern - from real tests 155 155 - ```` 156 156 - 157 157 - ## API Reference 158 158 - 159 159 - [For each public function/type/constant] 160 160 - 161 161 - ### `function_name(...)` 162 162 - 163 163 - [Generated from Step 3.2] 164 164 - 165 165 - ## Architecture 166 166 - 167 167 - [Internal design, data flow, key invariants - from Step 3.3] 168 168 - 169 169 - ## Examples 170 170 - 171 171 - [Tests converted to examples - from Step 3.5] 172 172 - 173 173 - ## Dependencies 174 174 - 175 175 - [What this depends on, what depends on this - from Step 3.4] 176 176 - 177 177 - ## Related Documentation 178 178 - 179 179 - - Links to other relevant docs 180 180 - - Links to test files 181 181 - 182 182 - ```` 183 183 - 184 184 - --- 185 185 - 186 186 - ## Step 5: Refine Tests If Needed 187 187 - 188 188 - If tests are too synthetic (meaningless variable names, unrealistic values): 189 189 - 190 190 - 1. Read the test file 191 191 - 2. Improve it with: 192 192 - - Descriptive variable names (user_email, order_total, not x, y) 193 193 - - Realistic values (not "foo", "bar", 123) 194 194 - - Comments explaining the scenario 195 195 - 3. Edit the test file with improvements 196 196 - 4. Create observation node: 197 197 - 198 198 - ```bash 199 199 - deciduous add observation "Refined tests for <component> - made more real-world" -c 85 200 200 - deciduous link <action_id> <observation_id> -r "Test improvements during documentation" 201 201 - ```` 202 202 - 203 203 - --- 204 204 - 205 205 - ## Step 6: Link to Decision Graph 206 206 - 207 207 - After documentation is complete: 208 208 - 209 209 - ```bash 210 210 - # Create documentation action (if not already created) 211 211 - deciduous add action "Documented <target>" -c 95 -f "<files-created>" 212 212 - 213 213 - # Link to goal 214 214 - deciduous link <goal_id> <action_id> -r "Documentation complete" 215 215 - 216 216 - # Create outcome 217 217 - deciduous add outcome "Documentation complete for <target>" -c 95 218 218 - deciduous link <action_id> <outcome_id> -r "Successfully documented" 219 219 - 220 220 - # Sync 221 221 - deciduous sync 222 222 - ``` 223 223 - 224 224 - --- 225 225 - 226 226 - ## Step 7: Verify Coverage 227 227 - 228 228 - **Checklist before completing:** 229 229 - 230 230 - - [ ] Every public function documented 231 231 - - [ ] Every parameter explained 232 232 - - [ ] Every return value explained 233 233 - - [ ] Every error case documented 234 234 - - [ ] At least one example per function (from tests) 235 235 - - [ ] Architecture overview included 236 236 - - [ ] Dependencies mapped 237 237 - - [ ] Links to tests included 238 238 - - [ ] Tests refined if they were synthetic 239 239 - 240 240 - If anything is missing, go back and fill it in. **Do not miss any surface area.** 241 241 - 242 242 - --- 243 243 - 244 244 - ## Decision Criteria 245 245 - 246 246 - **What to document:** 247 247 - 248 248 - - Public APIs (always) 249 249 - - Complex internal logic (when it's not obvious) 250 250 - - Design decisions (why, not just what) 251 251 - - Edge cases and error handling 252 252 - - Integration points 253 253 - 254 254 - **What NOT to document:** 255 255 - 256 256 - - Trivial getters/setters 257 257 - - Auto-generated code 258 258 - - Implementation details obvious from code 259 259 - 260 260 - **How deep to go:** 261 261 - 262 262 - - Deep enough that someone new could understand and use the code 263 263 - - Deep enough that someone could modify it without breaking things 264 264 - - Capture the "why" behind design decisions 265 265 - 266 266 - --- 267 267 - 268 268 - ## Example Usage 269 269 - 270 270 - ```bash 271 271 - # Document a single file 272 272 - /document src/auth/jwt.rs 273 273 - 274 274 - # Document a directory 275 275 - /document src/auth/ 276 276 - 277 277 - # Document the whole project 278 278 - /document . 279 279 - ``` 280 280 - 281 281 - **What happens:** 282 282 - 283 283 - 1. Goal node created 284 284 - 2. Code analyzed thoroughly 285 285 - 3. Tests found and used as examples 286 286 - 4. Tests refined if synthetic 287 287 - 5. Documentation written to docs/ 288 288 - 6. Action/outcome nodes created 289 289 - 7. Graph synced 290 290 - 291 291 - --- 292 292 - 293 293 - ## Integration with Documentation Enforcement 294 294 - 295 295 - When documentation is created, the `require-documentation.sh` hook will recognize it exists. This creates a virtuous cycle: 296 296 - 297 297 - 1. Can't edit code without documentation (hook blocks) 298 298 - 2. Run `/document` to create documentation 299 299 - 3. Now code edits are allowed 300 300 - 4. When code changes significantly, re-run `/document` 301 301 - 302 302 - --- 303 303 - 304 304 - ## Quick Reference 305 305 - 306 306 - ```bash 307 307 - # Document and generate docs 308 308 - /document <path> 309 309 - 310 310 - # After documenting, you can edit the file 311 311 - # The require-documentation.sh hook will allow it 312 312 - ``` 313 313 - 314 314 - **Always creates:** 315 315 - 316 316 - - Goal node (before starting) 317 317 - - Action node (for the documentation work) 318 318 - - Outcome node (on completion) 319 319 - - Observation nodes (for test refinements) 320 320 - 321 321 - **Now document: $TARGET**

-16

.opencode/commands/sync-graph.md

Reviewed

··· 1 1 - --- 2 2 - description: Sync the decision graph to GitHub Pages 3 3 - arguments: [] 4 4 - --- 5 5 - 6 6 - # Sync Decision Graph to GitHub Pages 7 7 - 8 8 - Export the current decision graph to docs/graph-data.json so it's deployed to GitHub Pages. 9 9 - 10 10 - ## Steps 11 11 - 12 12 - 1. Run `deciduous sync` to export the graph 13 13 - 2. Show the user how many nodes/edges were exported 14 14 - 3. If there are changes, stage them: `git add docs/graph-data.json` 15 15 - 16 16 - This should be run before any push to main to ensure the live site has the latest decisions.

-117

.opencode/commands/work.md

Reviewed

··· 1 1 - --- 2 2 - description: Start a work transaction - creates goal node BEFORE any implementation 3 3 - arguments: 4 4 - - name: GOAL 5 5 - description: The goal you're working towards 6 6 - required: true 7 7 - --- 8 8 - 9 9 - # Work Transaction 10 10 - 11 11 - **USE THIS BEFORE STARTING ANY IMPLEMENTATION.** 12 12 - 13 13 - This skill creates the required deciduous nodes BEFORE you write any code. The `require-action-node` plugin will nag to `.deciduous/plugin.log` if you don't have a recent node — it does not block edits. The post-commit-reminder plugin will nag again to link the commit. Treat the nags as guardrails, not gates. 14 14 - 15 15 - ## Step 1: Create the Goal Node 16 16 - 17 17 - Based on $GOAL (or the user's most recent request), create a goal node: 18 18 - 19 19 - ```bash 20 20 - # Create goal with the user's request captured verbatim 21 21 - deciduous add goal "$GOAL" -c 90 --prompt-stdin << 'EOF' 22 22 - [INSERT THE EXACT USER REQUEST HERE - VERBATIM, NOT SUMMARIZED] 23 23 - EOF 24 24 - ``` 25 25 - 26 26 - **IMPORTANT**: The prompt must be the user's EXACT words, not your summary. 27 27 - 28 28 - ## Step 2: Announce the Goal ID 29 29 - 30 30 - After creating the goal, tell the user: 31 31 - 32 32 - - The goal ID that was created 33 33 - - What you're about to implement 34 34 - - That you'll create action nodes as you work 35 35 - 36 36 - ## Step 3: Before Each Major Edit 37 37 - 38 38 - Before editing files, create an action node: 39 39 - 40 40 - ```bash 41 41 - deciduous add action "What you're about to implement" -c 85 -f "file1.rs,file2.rs" 42 42 - deciduous link <goal_id> <action_id> -r "Implementation step" 43 43 - ``` 44 44 - 45 45 - ## Step 4: After Completion 46 46 - 47 47 - When the work is done: 48 48 - 49 49 - ```bash 50 50 - # After committing 51 51 - deciduous add outcome "What was accomplished" -c 95 --commit HEAD 52 52 - deciduous link <action_id> <outcome_id> -r "Implementation complete" 53 53 - 54 54 - # Sync the graph 55 55 - deciduous sync 56 56 - ``` 57 57 - 58 58 - ## Step 5: Attach Supporting Documents (Optional) 59 59 - 60 60 - If the work produced or referenced important files (diagrams, specs, screenshots): 61 61 - 62 62 - ```bash 63 63 - deciduous doc attach <goal_id> path/to/diagram.png -d "Architecture diagram" 64 64 - deciduous doc attach <action_id> path/to/spec.pdf --ai-describe 65 65 - ``` 66 66 - 67 67 - If the user shares images or drops in files not in the project, attach them to the most relevant active node. 68 68 - 69 69 - ## The Transaction Model 70 70 - 71 71 - ``` 72 72 - /work "Add feature X" 73 73 - | 74 74 - Goal node created (ID: N) 75 75 - | 76 76 - Action node before each edit (links to goal) 77 77 - | 78 78 - Implementation happens (Edit/Write now allowed) 79 79 - | 80 80 - git commit 81 81 - | 82 82 - Outcome node with --commit HEAD (links to action) 83 83 - | 84 84 - Attach supporting documents (optional) 85 85 - | 86 86 - deciduous sync 87 87 - ``` 88 88 - 89 89 - ## Why This Matters 90 90 - 91 91 - - **The plugins nag, they don't block.** If no recent action/goal exists, `.deciduous/plugin.log` records the reminder; the edit still goes through. Same for post-commit. 92 92 - - **Commits will remind you** to link them to the graph 93 93 - - **The graph captures your reasoning** for future sessions 94 94 - - **Context recovery works** because the graph has everything 95 95 - 96 96 - ## Quick Reference 97 97 - 98 98 - ```bash 99 99 - # Start work 100 100 - deciduous add goal "Feature title" -c 90 -p "User request" 101 101 - 102 102 - # Before editing (required!) 103 103 - deciduous add action "What I'm implementing" -c 85 104 104 - deciduous link <goal> <action> -r "Implementation" 105 105 - 106 106 - # After committing 107 107 - deciduous add outcome "Result" -c 95 --commit HEAD 108 108 - deciduous link <action> <outcome> -r "Complete" 109 109 - 110 110 - # Attach documents (optional) 111 111 - deciduous doc attach <goal> diagram.png -d "Description" 112 112 - 113 113 - # Always sync 114 114 - deciduous sync 115 115 - ``` 116 116 - 117 117 - **Now create the goal node for: $GOAL**

-44

.opencode/plugins/version-check.ts

Reviewed

··· 1 1 - // OpenCode Plugin: Version Check (no-op) 2 2 - // 3 3 - // Suede does not run `deciduous update` (see AGENTS.md "Do not run 4 4 - // `deciduous update`" note). The upstream `deciduous` tool's 5 5 - // `update` subcommand regenerates `.opencode/`, `.claude/`, and 6 6 - // `AGENTS.md` from its own defaults, which would silently overwrite 7 7 - // the hand-edited integration files in this repo. We treat version 8 8 - // upgrades as opt-in: install a new `deciduous` binary if you want 9 9 - // new features, then *manually* reconcile any new files you want to 10 10 - // pull in — never via `deciduous update`. 11 11 - // 12 12 - // This plugin used to phone crates.io once per 24h and prompt the 13 13 - // user to upgrade + run `deciduous update`. It was rewritten as a 14 14 - // no-op for the reason above. The first time it runs, it appends a 15 15 - // single line to `.deciduous/plugin.log` so the no-op is observable 16 16 - // to anyone reading the log. 17 17 - 18 18 - import type { Plugin } from '@opencode-ai/plugin'; 19 19 - 20 20 - export const VersionCheck: Plugin = async () => { 21 21 - return { 22 22 - 'tool.execute.before': async () => { 23 23 - try { 24 24 - const fs = await import('fs'); 25 25 - const path = await import('path'); 26 26 - if (!fs.existsSync('.deciduous')) return; 27 27 - const marker = path.join('.deciduous', '.version_check_disabled'); 28 28 - if (fs.existsSync(marker)) return; 29 29 - fs.writeFileSync( 30 30 - marker, 31 31 - `version-check plugin disabled at ${new Date().toISOString()}\n` + 32 32 - `See AGENTS.md: do not run \`deciduous update\`.\n` 33 33 - ); 34 34 - const logFile = path.join('.deciduous', 'plugin.log'); 35 35 - fs.appendFileSync( 36 36 - logFile, 37 37 - `[${new Date().toISOString()}] version-check plugin: no-op. Do not run \`deciduous update\` (see AGENTS.md).\n` 38 38 - ); 39 39 - } catch { 40 40 - // Never let the plugin break edits. 41 41 - } 42 42 - } 43 43 - }; 44 44 - };

-26

.opencode/skills/task-lifecycle/SKILL.md

Reviewed

··· 1 1 - # Task lifecycle 2 2 - 3 3 - Run at the start of a task (branch setup) and at the end (note + verification). 4 4 - 5 5 - ## Before starting 6 6 - 7 7 - 1. Pull latest `main`: `git pull origin main` (or `git fetch` + rebase if `main` has moved). 8 8 - 2. Create a new branch from `main`: `git checkout -b <branch-type>/<slug>`. 9 9 - 3. Do the work. Apply other skills (TDD, debugging, code review) as relevant. 10 10 - 11 11 - ## Steps at task end 12 12 - 13 13 - 1. **Do not write a plan file to `agent-notes/plans/`.** That directory is gitignored. The plan is a per-task scratchpad; the compiled form (graph nodes, the task note's Decisions section) is what persists. If you need to resume work on a different machine, use `~/.agents/skills/handoff` — it captures the chat context, which is a superset of the plan file. 14 14 - 2. Copy `agent-notes/0000-00-00-00-task-template.md` to `agent-notes/YYYY-MM-DD-NN-<slug>.md`. **Always.** No skip-step. 15 15 - 3. Fill all sections from the work just done. Size scales with task; trivial tasks get short notes. 16 16 - 4. Run verification per AGENTS.md, fill `## Verification` with results. 17 17 - 5. Commit the work. Add a `Co-authored-by: opencode <noreply@opencode.ai>` trailer to the commit message. The human is the author; the trailer credits agent assistance. 18 18 - 6. Hand back with a one-line summary and a pointer to the note file. 19 19 - 20 20 - ## Rules 21 21 - 22 22 - - Task notes are records, not scratchpads. Fill at end, not during. 23 23 - - **Plan files in `agent-notes/plans/` are gitignored scratchpads, not artifacts.** Do not commit them. Do not read them at the start of a task — they're transient. Use `~/.agents/skills/handoff` to resume work across machines; the handoff doc supersedes any plan file. 24 24 - - AGENTS.md is always in context. Do not re-read it. 25 25 - - All work happens on a feature branch, not `main`. PR + merge per AGENTS.md. 26 26 - - The agent hands back at task end; it does not merge to `main`. The human reviews the PR and merges.

-39

.opencode/tools/deciduous.ts

Reviewed

··· 1 1 - // OpenCode Custom Tool: Deciduous Decision Graph 2 2 - // Wraps the deciduous CLI for direct graph operations from OpenCode 3 3 - // 4 4 - // This tool allows agents to interact with the decision graph without 5 5 - // needing to use the bash tool directly. 6 6 - 7 7 - import { tool } from '@opencode-ai/plugin'; 8 8 - 9 9 - export default tool({ 10 10 - description: 11 11 - 'Manage the deciduous decision graph - add nodes, create edges, query the graph, and sync', 12 12 - args: { 13 13 - command: tool.schema 14 14 - .string() 15 15 - .describe( 16 16 - 'The deciduous subcommand and arguments to run. Examples: ' + 17 17 - '\'add goal "Title" -c 90\', ' + 18 18 - '\'link 1 2 -r "reason"\', ' + 19 19 - "'nodes', 'edges', 'graph', 'pulse', 'sync'" 20 20 - ) 21 21 - }, 22 22 - async execute(args, context) { 23 23 - const proc = Bun.spawn(['sh', '-c', `deciduous ${args.command}`], { 24 24 - cwd: context.directory, 25 25 - stdout: 'pipe', 26 26 - stderr: 'pipe' 27 27 - }); 28 28 - 29 29 - const stdout = await new Response(proc.stdout).text(); 30 30 - const stderr = await new Response(proc.stderr).text(); 31 31 - const exitCode = await proc.exited; 32 32 - 33 33 - if (exitCode !== 0) { 34 34 - return `Error (exit ${exitCode}):\n${stderr}\n${stdout}`; 35 35 - } 36 36 - 37 37 - return stdout || '(no output)'; 38 38 - } 39 39 - });

+3 -5

AGENTS.md

View file Reviewed

··· 137 137 138 138 ## Task flow 139 139 140 140 - Every release branch follows this flow from task start to task done. The 141 141 - procedural reference lives at `.opencode/skills/task-lifecycle/SKILL.md`; 142 142 - this section is the in-context summary that consolidates the rules 143 143 - scattered above (Authoring boundaries, Working style, Releases, Decision 144 144 - Graph) into one sequence. 140 140 + Every release branch follows this flow from task start to task done. This 141 141 + section consolidates the rules scattered above (Authoring boundaries, 142 142 + Working style, Releases, Decision Graph) into one sequence. 145 143 146 144 ### Start 147 145