From a823caf3693954d53c45eae489df7684948685ca Mon Sep 17 00:00:00 2001 From: John Ogle Date: Wed, 8 Apr 2026 11:47:11 -0700 Subject: [PATCH] Remove beads/gastown/perles/dolt --- .gitattributes | 3 - .gitea/workflows/ci.yml | 3 - AGENTS.md | 4 - flake.lock | 98 +--- flake.nix | 47 -- .../commands/beads_batch_research_plan.md | 317 ------------ .../development/commands/beads_implement.md | 253 ---------- .../development/commands/beads_iterate.md | 214 -------- home/roles/development/commands/beads_plan.md | 306 ------------ .../development/commands/beads_research.md | 222 -------- .../development/commands/beads_workflow.md | 387 -------------- .../development/commands/gitea_pr_review.md | 472 ------------------ .../commands/import_gitea_issues.md | 130 ----- .../development/commands/parallel_beads.md | 409 --------------- .../development/commands/reconcile_beads.md | 129 ----- home/roles/development/default.nix | 131 +---- .../formulas/quick-fix.formula.toml | 115 ----- .../development/formulas/rpi.formula.toml | 124 ----- home/roles/development/skills/bd_workflow.md | 230 --------- .../skills/micro/artifact-format.md | 123 ----- .../development/skills/micro/planning.md | 121 ----- .../skills/micro/pr-description.md | 68 --- .../skills/micro/research-agents.md | 49 -- home/roles/emacs/doom/config.el | 14 - home/roles/emacs/doom/packages.el | 5 - packages/beads/default.nix | 26 - packages/gastown/default.nix | 31 -- packages/perles/default.nix | 25 - renovate.json | 26 - 29 files changed, 3 insertions(+), 4079 deletions(-) delete mode 100644 home/roles/development/commands/beads_batch_research_plan.md delete mode 100644 home/roles/development/commands/beads_implement.md delete mode 100644 home/roles/development/commands/beads_iterate.md delete mode 100644 home/roles/development/commands/beads_plan.md delete mode 100644 home/roles/development/commands/beads_research.md delete mode 100644 home/roles/development/commands/beads_workflow.md delete mode 100644 home/roles/development/commands/gitea_pr_review.md delete mode 100644 home/roles/development/commands/import_gitea_issues.md delete mode 100644 home/roles/development/commands/parallel_beads.md delete mode 100644 home/roles/development/commands/reconcile_beads.md delete mode 100644 home/roles/development/formulas/quick-fix.formula.toml delete mode 100644 home/roles/development/formulas/rpi.formula.toml delete mode 100644 home/roles/development/skills/bd_workflow.md delete mode 100644 home/roles/development/skills/micro/artifact-format.md delete mode 100644 home/roles/development/skills/micro/planning.md delete mode 100644 home/roles/development/skills/micro/pr-description.md delete mode 100644 home/roles/development/skills/micro/research-agents.md delete mode 100644 packages/beads/default.nix delete mode 100644 packages/gastown/default.nix delete mode 100644 packages/perles/default.nix diff --git a/.gitattributes b/.gitattributes index 807d598..e69de29 100644 --- a/.gitattributes +++ b/.gitattributes @@ -1,3 +0,0 @@ - -# Use bd merge for beads JSONL files -.beads/issues.jsonl merge=beads diff --git a/.gitea/workflows/ci.yml b/.gitea/workflows/ci.yml index 6e358d9..8a4bdc4 100644 --- a/.gitea/workflows/ci.yml +++ b/.gitea/workflows/ci.yml @@ -48,9 +48,6 @@ jobs: custom-mcrcon-rbw custom-tea-rbw custom-rclone-torbox-setup - custom-beads - custom-gastown - custom-perles custom-nextcloud-talk-desktop qt-pinned-jellyfin-media-player qt-pinned-stremio diff --git a/AGENTS.md b/AGENTS.md index 5b049e1..3301d99 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -6,10 +6,6 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co This is a NixOS configuration repository using flakes, managing multiple machines and home-manager configurations. The repository follows a modular architecture with reusable "roles" that can be composed for different machines. -## Issue Tracking - -This repository uses `beads` for issue tracking and management. Run `bd quickstart` to get an overview of the system at the start of every session. - ## Architecture ### Flake Structure diff --git a/flake.lock b/flake.lock index b9340b0..a7bab20 100644 --- a/flake.lock +++ b/flake.lock @@ -1,25 +1,5 @@ { "nodes": { - "beads": { - "inputs": { - "nixpkgs": [ - "nixpkgs-unstable" - ] - }, - "locked": { - "lastModified": 1774147838, - "narHash": "sha256-AqpdisbN6sFU2135/+B+FxJUUVknifzT7Gijc3dl2KQ=", - "owner": "steveyegge", - "repo": "beads", - "rev": "1402021b8bf36595fabad628317d3d27b4c88aa0", - "type": "github" - }, - "original": { - "owner": "steveyegge", - "repo": "beads", - "type": "github" - } - }, "doomemacs": { "flake": false, "locked": { @@ -59,48 +39,6 @@ "type": "github" } }, - "flake-utils": { - "inputs": { - "systems": "systems" - }, - "locked": { - "lastModified": 1731533236, - "narHash": "sha256-l0KFg5HjrsfsO/JpG+r7fRrqm12kzFHyUHqHCVpMMbI=", - "owner": "numtide", - "repo": "flake-utils", - "rev": "11707dc2f618dd54ca8739b309ec4fc024de578b", - "type": "github" - }, - "original": { - "owner": "numtide", - "repo": "flake-utils", - "type": "github" - } - }, - "gastown": { - "inputs": { - "beads": [ - "beads" - ], - "flake-utils": "flake-utils", - "nixpkgs": [ - "nixpkgs-unstable" - ] - }, - "locked": { - "lastModified": 1774219978, - "narHash": "sha256-nP0hblGmLrkEopkd2OuNfmAii06AhiWsfnBtT3qEqxI=", - "owner": "steveyegge", - "repo": "gastown", - "rev": "fc4feb81b72b284e70060112e7b92c9f04f86dd7", - "type": "github" - }, - "original": { - "owner": "steveyegge", - "repo": "gastown", - "type": "github" - } - }, "google-cookie-retrieval": { "inputs": { "nixpkgs": [ @@ -210,7 +148,7 @@ "doomemacs": "doomemacs", "emacs-overlay": "emacs-overlay", "nixpkgs": [], - "systems": "systems_2" + "systems": "systems" }, "locked": { "lastModified": 1774265710, @@ -296,22 +234,6 @@ "type": "github" } }, - "perles": { - "flake": false, - "locked": { - "lastModified": 1773694696, - "narHash": "sha256-8euoE/QViymgSEEzdMwF72Ui1/Bbikh3K0oC0cRo8tw=", - "owner": "zjrosen", - "repo": "perles", - "rev": "0871cb7626d7d7b67ad90d6ca1e3bb1cf257f988", - "type": "github" - }, - "original": { - "owner": "zjrosen", - "repo": "perles", - "type": "github" - } - }, "plasma-manager": { "inputs": { "home-manager": [ @@ -360,8 +282,6 @@ }, "root": { "inputs": { - "beads": "beads", - "gastown": "gastown", "google-cookie-retrieval": "google-cookie-retrieval", "home-manager": "home-manager", "home-manager-unstable": "home-manager-unstable", @@ -371,7 +291,6 @@ "nixpkgs": "nixpkgs", "nixpkgs-qt": "nixpkgs-qt", "nixpkgs-unstable": "nixpkgs-unstable", - "perles": "perles", "plasma-manager": "plasma-manager", "plasma-manager-unstable": "plasma-manager-unstable" } @@ -390,21 +309,6 @@ "repo": "default", "type": "github" } - }, - "systems_2": { - "locked": { - "lastModified": 1681028828, - "narHash": "sha256-Vy1rq5AaRuLzOxct8nz4T6wlgyUR7zLU309k9mBC768=", - "owner": "nix-systems", - "repo": "default", - "rev": "da67096a3b9bf56a91d16901293e51ba5b49a27e", - "type": "github" - }, - "original": { - "owner": "nix-systems", - "repo": "default", - "type": "github" - } } }, "root": "root", diff --git a/flake.nix b/flake.nix index 52dad29..e4e74c3 100644 --- a/flake.nix +++ b/flake.nix @@ -45,22 +45,6 @@ inputs.nixpkgs.follows = "nixpkgs-unstable"; }; - beads = { - url = "github:steveyegge/beads"; - inputs.nixpkgs.follows = "nixpkgs-unstable"; - }; - - gastown = { - url = "github:steveyegge/gastown"; - inputs.nixpkgs.follows = "nixpkgs-unstable"; - inputs.beads.follows = "beads"; - }; - - perles = { - url = "github:zjrosen/perles"; - flake = false; # No flake.nix upstream yet - }; - nix-doom-emacs-unstraightened = { url = "github:marienz/nix-doom-emacs-unstraightened"; # Don't follow nixpkgs to avoid rebuild issues with emacs-overlay @@ -127,19 +111,6 @@ (ufinal: uprev: { claude-code = uprev.callPackage ./packages/claude-code { }; }) - # Pin dolt to v1.82.4 (gastown requires >= 1.82.4) - (ufinal: uprev: { - dolt = uprev.dolt.overrideAttrs (old: rec { - version = "1.82.4"; - src = uprev.fetchFromGitHub { - owner = "dolthub"; - repo = "dolt"; - tag = "v${version}"; - hash = "sha256-mavL3y+Kv25hzFlDFXk7W/jeKVKlCBjlc67GkL3Jcwk="; - }; - vendorHash = "sha256-K1KzsqptZxO5OraWKIXeqKuVSzb6E/Mjy3c5PQ7Rs9k="; - }); - }) ]; nixosModules = [ @@ -292,9 +263,6 @@ permittedInsecurePackages = [ "qtwebengine-5.15.19" ]; }; }; - # Version strings for flake input packages - beadsRev = builtins.substring 0 8 (inputs.beads.rev or "unknown"); - gastownRev = builtins.substring 0 8 (inputs.gastown.rev or "unknown"); in { "custom-claude-code" = pkgs.custom.claude-code; @@ -306,21 +274,6 @@ "custom-opencode" = pkgs.custom.opencode; "qt-pinned-jellyfin-media-player" = pkgsQt.jellyfin-media-player; "qt-pinned-stremio" = pkgsQt.stremio; - # Flake input packages (beads, gastown) - these get version from input rev - "custom-beads" = pkgs.callPackage ./packages/beads { - inherit (pkgs.unstable) buildGoModule; - src = inputs.beads; - version = "0.52.0-${beadsRev}"; - }; - "custom-gastown" = pkgs.callPackage ./packages/gastown { - src = inputs.gastown; - version = "unstable-${gastownRev}"; - }; - "custom-perles" = pkgs.callPackage ./packages/perles { - inherit (pkgs.unstable) buildGoModule; - src = inputs.perles; - version = "unstable-${builtins.substring 0 8 (inputs.perles.rev or "unknown")}"; - }; } // ( if system == "x86_64-linux" then diff --git a/home/roles/development/commands/beads_batch_research_plan.md b/home/roles/development/commands/beads_batch_research_plan.md deleted file mode 100644 index 0c21d47..0000000 --- a/home/roles/development/commands/beads_batch_research_plan.md +++ /dev/null @@ -1,317 +0,0 @@ ---- -description: Batch research and planning for multiple beads with interactive question review -model: opus ---- - -# Beads Batch Research+Plan - -This skill automates the common workflow of: -1. Running /beads_research in parallel for multiple beads -2. Presenting open questions interactively for user input (bead-by-bead) -3. Running /beads_plan for all researched beads (plus any spawned from splits) - -## When to Use - -- You have multiple beads ready for work -- You want to research and plan them efficiently before implementation -- You prefer to batch your question-answering rather than context-switching between skills - -## Phase 1: Selection - -1. **Get ready beads**: Run `bd ready --limit=20` to list beads with no blockers - -2. **Filter already-researched beads**: - For each ready bead, check if it already has research: - ```bash - ls thoughts/beads-{bead-id}/research.md 2>/dev/null - ``` - - Categorize beads: - - **Needs research**: No `research.md` exists - - **Has research, needs plan**: `research.md` exists but no `plan.md` - - **Already planned**: Both `research.md` and `plan.md` exist - -3. **Present selection**: - ``` - Ready beads available for batch research+plan: - - NEEDS RESEARCH: - - {bead-id}: {title} (type: {type}) - - ... - - HAS RESEARCH (plan only): - - {bead-id}: {title} (type: {type}) - - ... - - ALREADY PLANNED (skip): - - {bead-id}: {title} - - Which beads would you like to process? - ``` - -4. **Use AskUserQuestion** with `multiSelect: true`: - - Include bead ID and title for each option - - Separate options by category - - Allow selection across categories - -## Phase 2: Parallel Research - -For each selected bead that NEEDS RESEARCH, launch a research subagent. - -### Subagent Instructions Template - -``` -Research bead [BEAD_ID]: [BEAD_TITLE] - -1. **Load bead context**: - ```bash - bd show [BEAD_ID] - ``` - -2. **Create artifact directory**: - ```bash - mkdir -p thoughts/beads-[BEAD_ID] - ``` - -3. **Conduct research** following beads_research.md patterns: - - Analyze and decompose the research question - - Spawn parallel sub-agent tasks (codebase-locator, codebase-analyzer, etc.) - - Synthesize findings - -4. **Write research document** to `thoughts/beads-[BEAD_ID]/research.md`: - - Include frontmatter with metadata - - Document findings with file:line references - - **CRITICAL**: Include "## Open Questions" section listing any unresolved items - -5. **Return summary**: - - Research status (complete/partial) - - Number of open questions - - Key findings summary (2-3 bullet points) - - List of open questions verbatim -``` - -### Launching Subagents - -Use `subagent_type: "opus"` for research subagents (matches beads_research model setting). - -Launch ALL research subagents in a single message for parallel execution: -``` - -``` - -### Collecting Results - -Wait for ALL research subagents to complete. Collect: -- Bead ID -- Research status -- Open questions list -- Any errors encountered - -## Phase 3: Interactive Question Review - -Present each bead's open questions sequentially for user input. - -### For Each Bead (in order): - -1. **Present research summary**: - ``` - ## Bead {N}/{total}: {bead-id} - {title} - - Research complete. Key findings: - - {finding 1} - - {finding 2} - - Open questions requiring your input: - 1. {question 1} - 2. {question 2} - - Additionally: - - Should this bead be split into multiple beads? (y/n) - - If split, describe the split: - ``` - -2. **Collect user responses**: - - Answers to open questions - - Split decision (yes/no) - - If split: new bead titles and how to divide the work - -3. **Handle splits**: - If user indicates a split: - ```bash - # Create new beads for split work - bd create --title="{split title 1}" --type={type} --priority={priority} \ - --description="{description based on user input}" - - # Update original bead if scope narrowed - bd update {original-bead-id} --description="{updated description}" - ``` - - Track new bead IDs for inclusion in planning phase. - -4. **Update research document**: - Append user answers to `thoughts/beads-{id}/research.md`: - ```markdown - ## User Clarifications [{timestamp}] - - Q: {question 1} - A: {user answer 1} - - Q: {question 2} - A: {user answer 2} - - ## Bead Splits - {If split: description of split and new bead IDs} - ``` - -### Progress Tracking - -After each bead's questions are answered, confirm before moving to next: -``` -Questions answered for {bead-id}. {N-1} beads remaining. -Continue to next bead? (y/n) -``` - -### Beads with No Questions - -If a bead's research had no open questions: -``` -## Bead {N}/{total}: {bead-id} - {title} - -Research complete with no open questions. - -Key findings: -- {finding 1} -- {finding 2} - -Should this bead be split? (y/n) -``` - -## Phase 4: Parallel Planning - -After all questions answered, launch planning subagents for all beads. - -### Beads to Plan - -Include: -- Original beads that were researched -- Beads that had existing research (from selection phase) -- New beads spawned from splits - -### Subagent Instructions Template - -``` -Create implementation plan for bead [BEAD_ID]: [BEAD_TITLE] - -1. **Load context**: - ```bash - bd show [BEAD_ID] - ``` - -2. **Read research** (it exists and has user clarifications): - Read `thoughts/beads-[BEAD_ID]/research.md` FULLY - -3. **Create plan** following beads_plan.md patterns: - - Context gathering via sub-agents - - Design approach based on research findings and user clarifications - - **Skip interactive questions** - they were already answered in research review - -4. **Write plan** to `thoughts/beads-[BEAD_ID]/plan.md`: - - Full plan structure with phases - - Success criteria (automated and manual) - - References to research document - -5. **Update bead**: - ```bash - bd update [BEAD_ID] --notes="Plan created: thoughts/beads-[BEAD_ID]/plan.md" - ``` - -6. **Return summary**: - - Plan status (complete/failed) - - Number of phases - - Estimated complexity (small/medium/large) - - Any issues encountered -``` - -### Launching Subagents - -Use `subagent_type: "opus"` for planning subagents (matches beads_plan model setting). - -Launch ALL planning subagents in a single message: -``` - -``` - -### Handling Beads Without Research - -For beads that had existing research but user didn't review questions: -- Planning subagent reads existing research -- If research has unresolved open questions, subagent should flag this in its return - -## Phase 5: Summary - -After all planning completes, present final summary. - -### Summary Format - -``` -## Batch Research+Plan Complete - -### Successfully Processed: -| Bead | Title | Research | Plan | Phases | Complexity | -|------|-------|----------|------|--------|------------| -| {id} | {title} | Complete | Complete | 3 | medium | -| {id} | {title} | Complete | Complete | 2 | small | - -### New Beads (from splits): -| Bead | Title | Parent | Status | -|------|-------|--------|--------| -| {new-id} | {title} | {parent-id} | Planned | - -### Failed: -| Bead | Title | Phase Failed | Error | -|------|-------|--------------|-------| -| {id} | {title} | Research | Timeout | - -### Next Steps: -1. Review plans at `thoughts/beads-{id}/plan.md` -2. Run `/parallel_beads` to implement all planned beads -3. Or run `/beads_implement {id}` for individual implementation - -### Artifacts Created: -- Research: thoughts/beads-{id}/research.md (x{N} files) -- Plans: thoughts/beads-{id}/plan.md (x{N} files) -``` - -## Error Handling - -### Research Subagent Failure -- Log the failure with bead ID and error -- Continue with other beads -- Exclude failed beads from question review and planning -- Report in final summary - -### Planning Subagent Failure -- Log the failure with bead ID and error -- Research still valid - can retry planning manually -- Report in final summary - -### User Cancellation During Question Review -- Save progress to bead notes -- Report which beads were completed -- User can resume with remaining beads in new session - -### Split Bead Creation Failure -- Report error but continue with original bead -- User can manually create split beads later - -## Resource Limits - -- Maximum concurrent research subagents: 5 -- Maximum concurrent planning subagents: 5 -- If more beads selected, process in batches - -## Notes - -- This skill is designed for the "research+plan before implementation" workflow -- Pairs well with `/parallel_beads` for subsequent implementation -- Run `/reconcile_beads` after implementation PRs merge diff --git a/home/roles/development/commands/beads_implement.md b/home/roles/development/commands/beads_implement.md deleted file mode 100644 index 7182571..0000000 --- a/home/roles/development/commands/beads_implement.md +++ /dev/null @@ -1,253 +0,0 @@ ---- -description: Implement a plan from thoughts/ for a bead issue ---- - -# Beads Implement - -You are tasked with implementing an approved plan for a bead issue. Plans are stored in `thoughts/beads-{id}/plan.md`. - -## Initial Setup - -When this command is invoked: - -1. **Parse the input for bead ID**: - - If a bead ID is provided, use it - - If no bead ID, check for beads with plans: - ```bash - bd list --status=in_progress - ``` - Then check which have plans in `thoughts/beads-{id}/plan.md` - -2. **Load bead context**: - ```bash - bd show {bead-id} - ``` - Note the bead **type** (bug, feature, task) from the output. - -3. **Check for plan and handle by type**: - - Check if plan exists: - ```bash - ls thoughts/beads-{bead-id}/plan.md 2>/dev/null - ``` - - **If plan exists**: Proceed normally (skip to step 4) - - **If no plan**: - - **type=bug**: Proceed without plan (simple bugs can implement directly) - - **type=feature or type=task**: Warn and ask: - ``` - No plan found for this {type}. - - Plans help ensure complex work is well-designed and verifiable. - Location expected: thoughts/beads-{bead-id}/plan.md - - Options: - 1. Create a plan first (recommended) - Run /beads_plan {bead-id} - 2. Proceed without a plan (for simple changes) - - How would you like to proceed? - ``` - Wait for user response before continuing. - -4. **Load plan and research context** (if plan exists): - - Read `thoughts/beads-{bead-id}/plan.md` FULLY - - Check for any existing checkmarks (- [x]) indicating partial progress - - Read any research at `thoughts/beads-{bead-id}/research.md` - - If plan's Success Criteria references contribution guidelines (e.g., "Per CONTRIBUTING.md:"), - verify the original CONTRIBUTING.md still exists and requirements are current - -5. **Mark bead in progress** (if not already): - ```bash - bd update {bead-id} --status=in_progress - ``` - -6. **Respond with**: - ``` - Implementing plan for bead {bead-id}: {bead-title} - - Plan location: thoughts/beads-{bead-id}/plan.md - {If partial progress: "Resuming from Phase X - previous phases completed."} - - I'll implement each phase and verify success criteria before proceeding. - ``` - -## Implementation Process - -### Step 1: Understand the Plan - -1. **Read the plan completely** -2. **Check for existing progress** (checkmarked items) -3. **Read all files mentioned in the plan** -4. **Create a TodoWrite list** tracking each phase - -### Step 2: Implement Each Phase - -For each phase in the plan: - -1. **Announce the phase**: - ``` - ## Starting Phase {N}: {Phase Name} - - This phase will: {overview from plan} - ``` - -2. **Make the changes**: - - Follow the plan's specific instructions - - Use Edit tool for modifications - - Create new files only when specified - -3. **Run automated verification**: - - Execute each command in "Automated Verification" - - Fix any issues before proceeding - -4. **Update plan checkboxes**: - - Use Edit tool to check off completed items in the plan - - This enables resume if session is interrupted - -5. **Update bead notes** with progress: - ```bash - bd update {bead-id} --notes="Phase {N} complete. Automated verification passed." - ``` - -### Step 3: Per-Plan Checkpoint - -**CRITICAL**: After completing ALL phases and ALL automated verification: - -``` -## Implementation Complete - Ready for Manual Verification - -All phases completed and automated verification passed: -- [ ] Phase 1: {name} - DONE -- [ ] Phase 2: {name} - DONE -- [ ] ... - -**Automated checks passed:** -- {List of automated checks that passed} - -**Please perform manual verification:** -- {List manual verification items from plan} - -Let me know when manual testing is complete so I can close the bead. - -**Contribution guidelines compliance:** -- {List any contribution guideline requirements that were part of Success Criteria} -- {Note if any requirements could not be automated and need manual review} -``` - -**STOP HERE and wait for user confirmation.** - -Do NOT: -- Close the bead automatically -- Proceed to "next steps" without confirmation -- Start additional work - -### Step 4: After Manual Verification - -When user confirms manual verification passed: - -1. **Update plan status**: - - Edit the plan's frontmatter: `status: complete` - -2. **Close the bead**: - ```bash - bd close {bead-id} --reason="Implementation complete. All verification passed." - ``` - -3. **Final summary**: - ``` - Bead {bead-id} closed. - - Summary: - - {What was implemented} - - {Key changes made} - - Artifacts: - - Plan: thoughts/beads-{bead-id}/plan.md - - {Any other artifacts created} - ``` - -## Handling Issues - -### When something doesn't match the plan: - -``` -Issue in Phase {N}: - -Expected: {what the plan says} -Found: {actual situation} -Why this matters: {explanation} - -Options: -1. Adapt the implementation to work with current state -2. Update the plan to reflect reality -3. Stop and investigate further - -How should I proceed? -``` - -### When tests fail: - -1. **Analyze the failure** -2. **Attempt to fix** if the fix is clear and within scope -3. **If fix is unclear**, report: - ``` - Test failure in Phase {N}: - - Failing test: {test name} - Error: {error message} - - I've attempted: {what you tried} - - This may require: {your assessment} - ``` - -### When blocked: - -``` -Blocked in Phase {N}: - -Blocker: {description} -Impact: {what can't proceed} - -Suggested resolution: {your recommendation} -``` - -## Resuming Work - -If the plan has existing checkmarks: - -1. **Trust completed work** - don't re-verify unless something seems off -2. **Pick up from first unchecked item** -3. **Verify previous work only if** current phase depends on it and seems broken - -## Important Guidelines - -1. **Follow the plan's intent** while adapting to reality -2. **Implement each phase fully** before moving to next -3. **Update checkboxes in real-time** as you complete items -4. **One checkpoint per plan** - not per phase -5. **Never close bead** without manual verification confirmation -6. **Keep bead notes updated** with progress - -## Session Close Protocol - -If you need to end the session before completion: - -1. **Update plan** with current progress (checkboxes) -2. **Update bead notes**: - ```bash - bd update {bead-id} --notes="In progress: Phase {N} partially complete. Next: {what's next}" - ``` -3. **Inform user** of status and how to resume - -## Example Invocation - -``` -User: /beads:implement nixos-configs-abc123 -Assistant: Implementing plan for bead nixos-configs-abc123... - -## Starting Phase 1: Database Schema - -This phase will add the new user_preferences table... -``` diff --git a/home/roles/development/commands/beads_iterate.md b/home/roles/development/commands/beads_iterate.md deleted file mode 100644 index 3120519..0000000 --- a/home/roles/development/commands/beads_iterate.md +++ /dev/null @@ -1,214 +0,0 @@ ---- -description: Iterate on existing implementation plans for a bead issue -model: opus ---- - -# Beads Iterate - -You are tasked with updating existing implementation plans based on feedback. Plans are stored in `thoughts/beads-{id}/plan.md`. - -## Initial Setup - -When this command is invoked: - -1. **Parse the input**: - - Bead ID (required or ask for it) - - Requested changes/feedback (can be provided with command or after) - -2. **Handle different scenarios**: - - **No bead ID provided**: - ``` - Which bead's plan would you like to iterate on? - - Recent beads with plans: - {list beads that have thoughts/beads-{id}/plan.md} - ``` - - **Bead ID but no feedback**: - ``` - I've found the plan at thoughts/beads-{bead-id}/plan.md - - What changes would you like to make? For example: - - "Add a phase for migration handling" - - "Update success criteria to include performance tests" - - "Adjust scope to exclude feature X" - - "Split Phase 2 into two separate phases" - ``` - - **Both bead ID and feedback provided**: - - Proceed immediately to Step 1 - -## Iteration Process - -### Step 1: Understand Current Plan - -1. **Read the existing plan COMPLETELY**: - ```bash - cat thoughts/beads-{bead-id}/plan.md - ``` - - Understand current structure, phases, scope - - Note success criteria and approach - -2. **Read the bead for context**: - ```bash - bd show {bead-id} - ``` - -3. **Understand requested changes**: - - Parse what user wants to add/modify/remove - - Identify if changes require codebase research - -### Step 2: Research If Needed - -**Only if changes require new technical understanding:** - -1. **Spawn parallel research tasks**: - - **codebase-locator**: Find relevant files - - **codebase-analyzer**: Understand implementation details - - **codebase-pattern-finder**: Find similar patterns - -2. **Be specific about directories** in prompts - -3. **Wait for ALL tasks** before proceeding - -### Step 3: Present Understanding - -Before making changes: - -``` -Based on your feedback, I understand you want to: -- {Change 1 with specific detail} -- {Change 2 with specific detail} - -{If research was needed:} -My research found: -- {Relevant discovery} -- {Important constraint} - -I plan to update the plan by: -1. {Specific modification} -2. {Another modification} - -Does this align with your intent? -``` - -Get user confirmation before proceeding. - -### Step 4: Update the Plan - -1. **Make focused, precise edits**: - - Use Edit tool for surgical changes - - Maintain existing structure unless explicitly changing it - - Keep file:line references accurate - -2. **Ensure consistency**: - - New phases follow existing pattern - - Update "What We're NOT Doing" if scope changes - - Maintain automated vs manual success criteria distinction - -3. **Update plan metadata**: - - Update frontmatter `date` to current timestamp - - Add `iteration: {N}` to frontmatter - - Add `iteration_reason: "{brief description}"` to frontmatter - -4. **Preserve completed work**: - - Don't uncheck items that were already completed - - If changing completed phases, discuss with user first - -### Step 5: Save Iteration History (Optional) - -For significant changes, save the previous version: - -```bash -cp thoughts/beads-{bead-id}/plan.md thoughts/beads-{bead-id}/plan-v{N}.md -``` - -Then update the main plan. - -### Step 6: Update Bead - -```bash -bd update {bead-id} --notes="Plan iterated: {brief description of changes}" -``` - -### Step 7: Present Changes - -``` -I've updated the plan at `thoughts/beads-{bead-id}/plan.md` - -Changes made: -- {Specific change 1} -- {Specific change 2} - -The updated plan now: -- {Key improvement} -- {Another improvement} - -Would you like any further adjustments? -``` - -## Important Guidelines - -1. **Be Skeptical**: - - Don't blindly accept changes that seem problematic - - Question vague feedback - ask for clarification - - Point out conflicts with existing phases - -2. **Be Surgical**: - - Make precise edits, not wholesale rewrites - - Preserve good content that doesn't need changing - - Only research what's necessary - -3. **Be Thorough**: - - Read entire plan before making changes - - Ensure updated sections maintain quality - - Verify success criteria are still measurable - -4. **Be Interactive**: - - Confirm understanding before making changes - - Allow course corrections - - Don't disappear into research without communicating - -5. **No Open Questions**: - - If changes raise questions, ASK - - Don't update plan with unresolved questions - -## Success Criteria Guidelines - -When updating success criteria, maintain two categories: - -**Automated Verification**: -- Commands: `make test`, `npm run lint` -- Prefer `make` commands when available -- File existence checks - -**Manual Verification**: -- UI/UX functionality -- Performance under real conditions -- Edge cases hard to automate - -## Handling Major Changes - -If feedback requires significant restructuring: - -1. **Discuss scope** before proceeding -2. **Consider if this should be a new plan** instead of iteration -3. **Preserve the original** in `plan-v{N}.md` -4. **Update bead description** if scope changed significantly - -## Example Invocations - -**With full context**: -``` -User: /beads:iterate nixos-configs-abc123 - add error handling phase -Assistant: Based on your feedback, I understand you want to add a new phase for error handling... -``` - -**Interactive**: -``` -User: /beads:iterate nixos-configs-abc123 -Assistant: I've found the plan. What changes would you like to make? -User: Split Phase 2 into backend and frontend phases -Assistant: I'll split Phase 2 into two separate phases... -``` diff --git a/home/roles/development/commands/beads_plan.md b/home/roles/development/commands/beads_plan.md deleted file mode 100644 index 871c6c5..0000000 --- a/home/roles/development/commands/beads_plan.md +++ /dev/null @@ -1,306 +0,0 @@ ---- -description: Create detailed implementation plans for a bead issue -model: opus ---- - -# Beads Plan - -You are tasked with creating detailed implementation plans for a bead issue. This skill integrates with the beads issue tracker and stores plans in the `thoughts/` directory. - -## Initial Setup - -When this command is invoked: - -1. **Parse the input for bead ID**: - - If a bead ID is provided, use it - - If no bead ID, run `bd ready` and ask which bead to plan for - -2. **Load bead context**: - ```bash - bd show {bead-id} - ``` - - Read the bead description for requirements - - Check for existing research: `thoughts/beads-{bead-id}/research.md` - - Note any dependencies or blockers - -3. **Create artifact directory**: - ```bash - mkdir -p thoughts/beads-{bead-id} - ``` - -4. **Check for existing research**: - - If `thoughts/beads-{bead-id}/research.md` exists, read it fully - - This research provides crucial context for planning - -5. **Respond with**: - ``` - Creating implementation plan for bead {bead-id}: {bead-title} - - {If research exists: "Found existing research at thoughts/beads-{bead-id}/research.md - incorporating findings."} - - Let me analyze the requirements and codebase to create a detailed plan. - ``` - -## Planning Process - -### Step 1: Context Gathering - -1. **Read all mentioned files FULLY**: - - Bead description references - - Existing research document - - Any linked tickets or docs - - Use Read tool WITHOUT limit/offset - -2. **Check for contribution guidelines**: - - ```bash - # Check standard locations for contribution guidelines - for f in CONTRIBUTING.md .github/CONTRIBUTING.md docs/CONTRIBUTING.md; do - if [ -f "$f" ]; then - echo "Found: $f" - break - fi - done - ``` - - If found: - - Read the file fully - - Extract actionable requirements (testing, code style, documentation, PR conventions) - - These requirements MUST be incorporated into the plan's Success Criteria - - If not found, note "No contribution guidelines found" and proceed. - -3. **Spawn initial research tasks**: - - **codebase-locator**: Find all files related to the task - - **codebase-analyzer**: Understand current implementation - - **codebase-pattern-finder**: Find similar features to model after - - **thoughts-locator**: Find any existing plans or decisions - -4. **Read all files identified by research**: - - Read them FULLY into main context - - Cross-reference with requirements - -### Step 2: Present Understanding - -Before writing the plan, confirm understanding: - -``` -Based on the bead and my research, I understand we need to [accurate summary]. - -I've found that: -- [Current implementation detail with file:line reference] -- [Relevant pattern or constraint discovered] -- [Potential complexity or edge case identified] - -Questions that my research couldn't answer: -- [Specific technical question requiring human judgment] -- [Business logic clarification] -``` - -Only ask questions you genuinely cannot answer through code investigation. - -### Step 3: Research & Discovery - -After getting clarifications: - -1. **If user corrects any misunderstanding**: - - Spawn new research tasks to verify - - Read specific files/directories mentioned - - Only proceed once verified - -2. **Present design options**: - ``` - Based on my research: - - **Current State:** - - [Key discovery about existing code] - - [Pattern or convention to follow] - - **Design Options:** - 1. [Option A] - [pros/cons] - 2. [Option B] - [pros/cons] - - Which approach aligns best? - ``` - -### Step 4: Plan Structure - -Once aligned on approach: - -``` -Here's my proposed plan structure: - -## Overview -[1-2 sentence summary] - -## Implementation Phases: -1. [Phase name] - [what it accomplishes] -2. [Phase name] - [what it accomplishes] - -Does this phasing make sense? -``` - -Get feedback on structure before writing details. - -### Step 5: Write the Plan - -Write to `thoughts/beads-{bead-id}/plan.md`: - -```markdown ---- -date: {ISO timestamp} -bead_id: {bead-id} -bead_title: "{bead title}" -author: claude -git_commit: {commit hash} -branch: {branch name} -repository: {repo name} -status: draft ---- - -# {Feature/Task Name} Implementation Plan - -## Overview - -{Brief description of what we're implementing and why} - -## Current State Analysis - -{What exists now, what's missing, key constraints} - -### Key Discoveries: -- {Finding with file:line reference} -- {Pattern to follow} - -## Desired End State - -{Specification of desired end state and how to verify it} - -## What We're NOT Doing - -{Explicitly list out-of-scope items} - -## Implementation Approach - -{High-level strategy and reasoning} - -## Phase 1: {Descriptive Name} - -### Overview -{What this phase accomplishes} - -### Changes Required: - -#### 1. {Component/File Group} -**File**: `path/to/file.ext` -**Changes**: {Summary} - -```{language} -// Specific code to add/modify -``` - -### Success Criteria: - -#### Automated Verification: -- [ ] Tests pass: `make test` -- [ ] Linting passes: `make lint` -- [ ] Type checking passes: `make typecheck` - -#### Manual Verification: -- [ ] Feature works as expected in UI -- [ ] Edge cases handled correctly - ---- - -## Phase 2: {Descriptive Name} -{Similar structure...} - ---- - -## Testing Strategy - -### Unit Tests: -- {What to test} -- {Key edge cases} - -### Integration Tests: -- {End-to-end scenarios} - -### Manual Testing Steps: -1. {Specific step} -2. {Another step} - -## References - -- Bead: {bead-id} -- Research: `thoughts/beads-{bead-id}/research.md` -- Similar implementation: {file:line} -``` - -### Step 6: Update the bead - -```bash -bd update {bead-id} --notes="Plan created: thoughts/beads-{bead-id}/plan.md" -``` - -### Step 7: Create implementation bead (if appropriate) - -If the planning bead is separate from implementation: - -```bash -bd create --title="Implement: {feature name}" --type=task --priority=1 \ - --description="Implement the plan at thoughts/beads-{original-bead-id}/plan.md - -See bead {original-bead-id} for planning context." - -# Link as dependency -bd dep add {new-bead-id} {original-bead-id} -``` - -### Step 8: Present for Review - -``` -I've created the implementation plan at: -`thoughts/beads-{bead-id}/plan.md` - -Please review it and let me know: -- Are the phases properly scoped? -- Are the success criteria specific enough? -- Any technical details that need adjustment? -- Missing edge cases or considerations? -``` - -## Important Guidelines - -1. **Be Skeptical**: Question vague requirements, identify potential issues early -2. **Be Interactive**: Don't write the full plan in one shot, get buy-in at each step -3. **Be Thorough**: Read all context files COMPLETELY, include specific file:line refs -4. **Be Practical**: Focus on incremental, testable changes -5. **No Open Questions**: If you have unresolved questions, STOP and ask - -## Success Criteria Guidelines - -Always separate into two categories: - -**Automated Verification** (run by agents): -- Commands: `make test`, `npm run lint`, etc. -- File existence checks -- Type checking - -**Manual Verification** (requires human): -- UI/UX functionality -- Performance under real conditions -- Edge cases hard to automate - -**From Contribution Guidelines** (if CONTRIBUTING.md exists): -- Include any testing requirements specified in guidelines -- Include any code style/linting requirements -- Include any documentation requirements -- Reference the guideline: "Per CONTRIBUTING.md: {requirement}" - -## Example Invocation - -``` -User: /beads:plan nixos-configs-abc123 -Assistant: Creating implementation plan for bead nixos-configs-abc123... -``` diff --git a/home/roles/development/commands/beads_research.md b/home/roles/development/commands/beads_research.md deleted file mode 100644 index ba05b6f..0000000 --- a/home/roles/development/commands/beads_research.md +++ /dev/null @@ -1,222 +0,0 @@ ---- -description: Research a bead topic comprehensively and store findings in thoughts/ -model: opus ---- - -# Beads Research - -You are tasked with conducting comprehensive research for a bead issue. This skill integrates with the beads issue tracker and stores findings in the `thoughts/` directory. - -## CRITICAL: YOUR ONLY JOB IS TO DOCUMENT AND EXPLAIN THE CODEBASE AS IT EXISTS TODAY -- DO NOT suggest improvements or changes unless the user explicitly asks for them -- DO NOT perform root cause analysis unless the user explicitly asks for them -- DO NOT propose future enhancements unless the user explicitly asks for them -- DO NOT critique the implementation or identify problems -- ONLY describe what exists, where it exists, how it works, and how components interact -- You are creating a technical map/documentation of the existing system - -## Initial Setup - -When this command is invoked: - -1. **Parse the input for bead ID**: - - If a bead ID is provided (e.g., `nixos-configs-abc123`), use it - - If no bead ID provided, run `bd ready --type=research` to find research beads, or ask which bead to research - -2. **Load bead context**: - ```bash - bd show {bead-id} - ``` - - Read the bead description to understand the research question - - Note any linked files or references in the bead - -3. **Create artifact directory**: - ```bash - mkdir -p thoughts/beads-{bead-id} - ``` - -4. **Respond with**: - ``` - Starting research for bead {bead-id}: {bead-title} - - Research question: {extracted from bead description} - - I'll analyze this thoroughly and store findings in thoughts/beads-{bead-id}/research.md - ``` - -## Research Process - -### Step 1: Read any directly mentioned files -- If the bead or user mentions specific files, read them FULLY first -- Use the Read tool WITHOUT limit/offset parameters -- Read these files yourself in the main context before spawning sub-tasks - -### Step 1.5: Check for contribution guidelines - -Before spawning sub-agents, check if the repository has contribution guidelines: - -```bash -for f in CONTRIBUTING.md .github/CONTRIBUTING.md docs/CONTRIBUTING.md; do - if [ -f "$f" ]; then echo "Found: $f"; break; fi -done -``` - -If found, read the file and note key requirements. These should be included in the research document under a "## Contribution Guidelines" section if relevant to the research question. - -### Step 2: Analyze and decompose the research question -- Break down the query into composable research areas -- Identify specific components, patterns, or concepts to investigate -- Create a research plan using TodoWrite -- Consider which directories, files, or patterns are relevant - -### Step 3: Spawn parallel sub-agent tasks - -Use specialized agents for research: - -**For codebase research:** -- **codebase-locator** - Find WHERE files and components live -- **codebase-analyzer** - Understand HOW specific code works -- **codebase-pattern-finder** - Find examples of existing patterns - -**For thoughts directory:** -- **thoughts-locator** - Discover what documents exist about the topic -- **thoughts-analyzer** - Extract key insights from specific documents - -**For web research (only if explicitly requested):** -- **web-search-researcher** - External documentation and resources - -Key principles: -- Run multiple agents in parallel when searching for different things -- Each agent knows its job - tell it what you're looking for, not HOW to search -- Remind agents they are documenting, not evaluating - -### Step 4: Synthesize findings - -Wait for ALL sub-agents to complete, then: -- Compile all results (codebase and thoughts findings) -- Prioritize live codebase findings as primary source of truth -- Connect findings across different components -- Include specific file paths and line numbers -- Highlight patterns, connections, and architectural decisions - -### Step 5: Gather metadata - -```bash -# Git metadata -git rev-parse HEAD # Current commit -git branch --show-current # Current branch -basename $(git rev-parse --show-toplevel) # Repo name -date -Iseconds # Current timestamp -``` - -### Step 6: Write research document - -Write to `thoughts/beads-{bead-id}/research.md`: - -```markdown ---- -date: {ISO timestamp with timezone} -bead_id: {bead-id} -bead_title: "{bead title}" -researcher: claude -git_commit: {commit hash} -branch: {branch name} -repository: {repo name} -status: complete ---- - -# Research: {bead title} - -**Bead**: {bead-id} -**Date**: {timestamp} -**Git Commit**: {commit hash} -**Branch**: {branch name} - -## Research Question -{Original question from bead description} - -## Summary -{High-level documentation answering the research question} - -## Detailed Findings - -### {Component/Area 1} -- Description of what exists (file.ext:line) -- How it connects to other components -- Current implementation details - -### {Component/Area 2} -... - -## Code References -- `path/to/file.py:123` - Description -- `another/file.ts:45-67` - Description - -## Architecture Documentation -{Current patterns, conventions found in codebase} - -## Contribution Guidelines -{If CONTRIBUTING.md exists, summarize key requirements relevant to the research topic} -{If no guidelines found, omit this section} - -## Historical Context (from thoughts/) -{Relevant insights from thoughts/ with references} - -## Open Questions -{Any areas needing further investigation} -``` - -### Step 7: Update the bead - -```bash -# Add artifact link to bead notes -bd update {bead-id} --notes="Research complete: thoughts/beads-{bead-id}/research.md" -``` - -### Step 8: Autonomy decision - -**For research beads (type=research):** -- If research is complete and comprehensive, close the bead: - ```bash - bd close {bead-id} --reason="Research complete. See thoughts/beads-{bead-id}/research.md" - ``` -- Present summary to user - -**For other bead types:** -- Do NOT close the bead -- Present findings and ask how to proceed - -### Step 9: Handle follow-up questions - -If the user has follow-up questions: -- Append to the same research document -- Add a new section: `## Follow-up Research [{timestamp}]` -- Update the bead notes with the new findings - -## Important Guidelines - -- Always use parallel Task agents to maximize efficiency -- Always run fresh codebase research - never rely solely on existing documents -- Focus on finding concrete file paths and line numbers -- Research documents should be self-contained -- Document cross-component connections -- Include temporal context (when research was conducted) -- Keep the main agent focused on synthesis, not deep file reading -- **CRITICAL**: You and all sub-agents are documentarians, not evaluators -- **REMEMBER**: Document what IS, not what SHOULD BE - -## Example Invocation - -``` -User: /beads:research nixos-configs-abc123 -Assistant: Starting research for bead nixos-configs-abc123: Investigate auth flow -... -``` - -Or without bead ID: -``` -User: /beads:research -Assistant: Let me check for research beads... -[runs bd ready] -Which bead would you like me to research? -``` diff --git a/home/roles/development/commands/beads_workflow.md b/home/roles/development/commands/beads_workflow.md deleted file mode 100644 index b24fbbe..0000000 --- a/home/roles/development/commands/beads_workflow.md +++ /dev/null @@ -1,387 +0,0 @@ ---- -description: Comprehensive guide for the beads + humanlayer integrated workflow ---- - -# Beads Workflow Guide - -This document describes the integrated workflow combining **beads** (issue tracking) with **humanlayer-style skills** (deep research, planning, implementation). - -## Philosophy - -### Two Systems, Complementary Purposes - -| System | Purpose | Storage | -|--------|---------|---------| -| **Beads** | Track WHAT work exists | `.beads/` (git-synced) | -| **Thoughts** | Store HOW to do the work | `thoughts/` (local or symlinked) | - -### Autonomy Model - -| Bead Type | Agent Autonomy | Checkpoint | -|-----------|----------------|------------| -| `research` | **Full** - agent closes when satisfied | None | -| `feature`, `task`, `bug` | **Checkpointed** - pause for validation | Per-plan | - -**Key insight**: Research produces artifacts. Implementation produces commits. Commits are the review boundary. - -## Directory Structure - -``` -project/ -├── .beads/ # Beads database (git-synced) -│ ├── beads.db -│ ├── config.yaml -│ └── issues.jsonl -├── thoughts/ # Artifacts (local or symlink) -│ ├── beads-{id}/ # Per-bead artifacts -│ │ ├── research.md -│ │ ├── plan.md -│ │ └── plan-v1.md # Iteration history -│ └── shared/ # Legacy/non-bead artifacts -│ ├── research/ -│ └── plans/ -└── home/roles/development/skills/ # Skill definitions - ├── beads_research.md - ├── beads_plan.md - ├── beads_implement.md - └── beads_iterate.md -``` - -## When to Use What - -### Use Beads When: -- Work spans multiple sessions -- Work has dependencies or blockers -- You need to track status across interruptions -- Multiple related tasks need coordination -- Context recovery after compaction matters - -### Use TodoWrite When: -- Single-session execution tracking -- Breaking down work within a session -- Tracking progress on a single bead - -### Use Both Together: -- Beads track the overall work items -- TodoWrite tracks progress within a session -- Example: Bead for "Implement auth", TodoWrite for each file being edited - -## Workflow Patterns - -### Pattern 1: Research-First Approach - -``` -1. Create research bead - bd create --title="Research auth patterns" --type=research --priority=1 - -2. Run research - /beads:research {bead-id} - → Agent researches, writes to thoughts/beads-{id}/research.md - → Agent closes bead when satisfied - -3. Create implementation bead - bd create --title="Implement auth" --type=feature --priority=1 - -4. Plan the implementation - /beads:plan {bead-id} - → Agent reads prior research, creates plan - → Plan saved to thoughts/beads-{id}/plan.md - -5. Implement - /beads:implement {bead-id} - → Agent follows plan, pauses for manual verification - → You validate, agent closes bead -``` - -### Pattern 2: Direct Implementation - -For well-understood tasks without research: - -``` -1. Create bead - bd create --title="Fix login bug" --type=bug --priority=0 - -2. Plan and implement - /beads:plan {bead-id} - → Quick planning based on bead description - - /beads:implement {bead-id} - → Follow plan, pause at checkpoint -``` - -### Pattern 3: Iterative Planning - -When requirements evolve: - -``` -1. Initial plan - /beads:plan {bead-id} - -2. Iterate based on feedback - /beads:iterate {bead-id} - add error handling phase - -3. Iterate again if needed - /beads:iterate {bead-id} - split phase 2 into backend/frontend - -4. Implement when plan is solid - /beads:implement {bead-id} -``` - -### Pattern 4: Parallel Work - -Using parallel_beads skill for multiple independent tasks: - -``` -1. Check what's ready - bd ready - -2. Select multiple beads - /parallel_beads - → Select beads to work on - → Each gets worktree, PR, review - -3. Reconcile after PRs merge - /reconcile_beads -``` - -## Skills Reference - -### /beads:research {bead-id} -- Conducts comprehensive codebase research -- Uses parallel sub-agents for efficiency -- Outputs to `thoughts/beads-{id}/research.md` -- **Autonomy**: Can close research beads automatically - -### /beads:plan {bead-id} -- Creates detailed implementation plans -- Interactive process with checkpoints -- Outputs to `thoughts/beads-{id}/plan.md` -- Can create dependent implementation beads - -### /beads:implement {bead-id} -- Follows plans from thoughts/ -- Updates plan checkboxes for resumability -- **Checkpoint**: Pauses after plan completion for manual verification -- Only closes bead after human confirms - -### /beads:iterate {bead-id} -- Updates existing plans based on feedback -- Preserves plan structure while making targeted changes -- Saves iteration history as `plan-v{N}.md` - -### /parallel_beads -- Orchestrates parallel bead processing -- Creates worktrees, PRs, reviews for multiple beads -- Good for batching independent work - -### /reconcile_beads -- Closes beads whose PRs have merged -- Run after merging PRs to keep beads in sync - -## Session Protocols - -### Starting a Session - -```bash -# Check what's available -bd ready - -# Pick work and start -bd update {bead-id} --status=in_progress -``` - -### Ending a Session - -```bash -# Always run this checklist: -[ ] git status # Check changes -[ ] git add # Stage code changes -[ ] bd sync # Sync beads -[ ] git commit -m "..." # Commit code -[ ] git push # Push to remote -``` - -### Resuming Work - -```bash -# Find in-progress work -bd list --status=in_progress - -# Check bead notes for context -bd show {bead-id} - -# Check for partial plan progress -cat thoughts/beads-{id}/plan.md | grep "\[x\]" -``` - -## Thoughts Directory Patterns - -### For Work Repos (via symlink) -``` -project/thoughts → ~/thoughts/repos/{repo-name}/ -``` -- Syncs via codelayer to work remote -- Shared across projects on same machine - -### For Personal Repos (local) -``` -project/thoughts/ # Regular directory, not symlink -``` -- Stays local to project -- Committed with project or gitignored - -### Determining Which Pattern -```bash -# Check if thoughts is a symlink -ls -la thoughts - -# If symlink, it points to ~/thoughts/repos/{repo}/ -# If directory, it's local to this project -``` - -## Best Practices - -### 1. Bead Descriptions Matter -Write clear descriptions - they're the input for research and planning: -```bash -bd create --title="Implement user preferences" --type=feature \ - --description="Add user preferences storage and UI. - -Requirements: -- Store preferences in SQLite -- Expose via REST API -- Add settings page in UI - -See related: thoughts/shared/research/preferences-patterns.md" -``` - -### 2. Link Artifacts in Beads -Always update bead notes with artifact locations: -```bash -bd update {id} --notes="Research: thoughts/beads-{id}/research.md -Plan: thoughts/beads-{id}/plan.md" -``` - -### 3. Use Dependencies -Structure work with dependencies: -```bash -# Research blocks planning -bd dep add {plan-bead} {research-bead} - -# Planning blocks implementation -bd dep add {impl-bead} {plan-bead} -``` - -### 4. Trust the Checkpoint Model -- Research beads: Let agent close them -- Implementation beads: Always validate before closing -- If in doubt, err on the side of checkpoints - -### 5. Keep Plans Updated -- Check off completed items as you go -- Update notes with progress -- This enables seamless resume across sessions - -## Troubleshooting - -### "What bead should I work on?" -```bash -bd ready # Shows unblocked work -``` - -### "Where did the research go?" -```bash -ls thoughts/beads-{id}/ -bd show {id} # Check notes for artifact links -``` - -### "Plan doesn't match reality" -```bash -/beads:iterate {id} # Update plan based on findings -``` - -### "Session ended mid-implementation" -```bash -bd show {id} # Check notes for progress -cat thoughts/beads-{id}/plan.md | grep "\[x\]" # See completed items -/beads:implement {id} # Resume - will pick up from last checkpoint -``` - -### "Bead is blocked" -```bash -bd show {id} # See what's blocking -bd blocked # See all blocked beads -``` - -## Migration Notes - -### From Pure Humanlayer to Beads+Humanlayer - -Old pattern: -``` -thoughts/shared/research/2025-01-01-topic.md -thoughts/shared/plans/2025-01-01-feature.md -``` - -New pattern: -``` -thoughts/beads-{id}/research.md -thoughts/beads-{id}/plan.md -``` - -The `shared/` structure still works for non-bead artifacts, but prefer per-bead directories for tracked work. - -### Existing Content -- Keep existing `thoughts/shared/` content -- New bead-tracked work uses `thoughts/beads-{id}/` -- Reference old research from bead descriptions when relevant - -## Design Decisions - -### Phase Tracking: Artifacts vs Statuses - -**Current approach**: Skills infer workflow phase from artifact presence: -- Has `research.md` → research done -- Has `plan.md` → planning done -- No artifacts → needs research/planning - -**Alternative considered**: Explicit phase statuses (`needs_research`, `needs_plan`, `implementing`, etc.) - -**Why artifacts win**: -1. **Single source of truth** - Status can't drift from reality -2. **Less state to maintain** - No need to update status when creating artifacts -3. **Works across repos** - No custom status config needed -4. **Skills already check artifacts** - Natural fit with existing behavior - -**When explicit statuses would help**: -- Pipeline visualization (e.g., `bd list --status=needs_plan`) -- Agent self-selection by phase -- Team coordination dashboards - -**Recommendation**: Keep artifact-inference as primary mechanism. If pipeline visibility becomes important, consider adding statuses that skills auto-set when creating artifacts (advisory, not enforced). - -### One Bead Per Feature (Default) - -**Current approach**: File one bead per logical feature. Skills handle phases internally. - -**Alternative considered**: Separate beads for research → planning → implementation, linked by dependencies. - -**Why single bead wins for most work**: -1. **Lower friction** - Quick idea dump without filing 3 tickets -2. **Simpler tracking** - One status to check -3. **Natural grouping** - Artifacts stay together in `thoughts/beads-{id}/` - -**When to split into multiple beads**: -- Research reveals the work should be multiple features -- Different phases need different assignees -- Explicit dependency tracking matters (e.g., "auth must ship before payments") - -**The discovered-work pattern**: Start with one bead. If research reveals split work, file additional beads with dependencies. Skills guide this naturally. - -### Plan Requirements by Type - -**Bug fixes** (`type=bug`): Can proceed without plans - usually well-scoped from bug report. - -**Features/tasks** (`type=feature`, `type=task`): Should have plans - helps ensure design is sound before implementation. - -This is advisory, not enforced. Skills warn but allow override for simple changes. diff --git a/home/roles/development/commands/gitea_pr_review.md b/home/roles/development/commands/gitea_pr_review.md deleted file mode 100644 index 92b5295..0000000 --- a/home/roles/development/commands/gitea_pr_review.md +++ /dev/null @@ -1,472 +0,0 @@ ---- -description: Address Gitea/Forgejo PR review comments with code changes ---- - -# Gitea PR Review - -You are tasked with **addressing** PR review comments by making code changes, then summarizing what was done. This skill drives PR progress, not just conversation. - -## Philosophy - -**Comments are work items, not conversation starters.** - -When a reviewer leaves a comment, they're identifying something that needs attention. This skill: -1. Categorizes comments by actionability -2. Makes code changes to address actionable comments -3. Commits and pushes those changes -4. Posts a single summary comment describing what was done - -## Prerequisites - -- `tea` CLI configured with a Gitea/Forgejo instance -- Access token from tea config: `~/.config/tea/config.yml` -- Repository must be a Gitea/Forgejo remote (not GitHub) -- **Nix users**: All tools available via nixpkgs (`nix run nixpkgs#tea`) - -## Initial Setup - -When this command is invoked: - -1. **Parse the input for PR number**: - - If a PR number is provided as argument, use it - - If no PR number, detect from current branch (see PR Detection section) - -2. **Verify required tools are available**: - ```bash - which tea - ``` - - If tea is missing: - ``` - Error: `tea` CLI not found. - - Please install: - - Nix: nix run nixpkgs#tea - - Other: https://gitea.com/gitea/tea - ``` - **STOP** if tea is missing. - -3. **Extract configuration from tea config**: - ```bash - # Read tea config (it's YAML but simple enough to grep) - TEA_CONFIG="$HOME/.config/tea/config.yml" - GITEA_URL=$(grep -A1 'logins:' "$TEA_CONFIG" | grep 'url:' | head -1 | sed 's/.*url: //') - TOKEN=$(grep -A5 'logins:' "$TEA_CONFIG" | grep 'token:' | head -1 | sed 's/.*token: //') - ``` - - If config is missing or invalid: - ``` - Error: Could not read tea config at ~/.config/tea/config.yml - - Please ensure `tea` is installed and configured: - 1. Install tea - 2. Log in: tea login add --url https://your-gitea-instance --token YOUR_TOKEN - ``` - **STOP** if config is invalid. - -4. **Detect repository info from git remote**: - ```bash - REMOTE_URL=$(git remote get-url origin) - # Parse owner and repo from URL (handles both SSH and HTTPS) - OWNER=$(echo "$REMOTE_URL" | sed -E 's#.*[:/]([^/]+)/[^/]+\.git$#\1#') - REPO=$(echo "$REMOTE_URL" | sed -E 's#.*/([^/]+)\.git$#\1#') - ``` - -5. **Ensure we're on the PR branch**: - ```bash - CURRENT_BRANCH=$(git branch --show-current) - # Verify this branch corresponds to the PR - ``` - -6. **Respond with**: - ``` - Addressing PR review comments for PR #{PR_NUMBER}... - - Repository: {OWNER}/{REPO} - Branch: {CURRENT_BRANCH} - Gitea URL: {GITEA_URL} - ``` - -## PR Detection - -If no PR number is provided, detect from the current branch: - -```bash -CURRENT_BRANCH=$(git branch --show-current) -tea pr list --fields index,head --output simple | grep "$CURRENT_BRANCH" -``` - -If no PR exists for the current branch, use `AskUserQuestion`: - -``` -No PR found for branch '{CURRENT_BRANCH}'. - -Would you like to: -1. Enter a PR number manually -2. Cancel -``` - -## Workflow - -### Step 1: Fetch and Parse Comments - -Fetch all reviews and their comments: - -```bash -# Fetch reviews (filter out dismissed reviews) -curl -s -H "Authorization: token $TOKEN" \ - "$GITEA_URL/api/v1/repos/$OWNER/$REPO/pulls/$PR_NUMBER/reviews" \ - | jq '[.[] | select(.dismissed != true)]' - -# For each review, fetch comments -curl -s -H "Authorization: token $TOKEN" \ - "$GITEA_URL/api/v1/repos/$OWNER/$REPO/pulls/$PR_NUMBER/reviews/$REVIEW_ID/comments" -``` - -**Filter resolved comments**: When processing comments, skip any that have been marked as resolved. Check the `resolver` field in the comment response - if it's not null, the comment has been resolved and should be skipped. - -```bash -# Example: Filter to only unresolved comments -jq '[.[] | select(.resolver == null)]' -``` - -If no reviews found or all comments are resolved: -``` -No unresolved reviews found for PR #{PR_NUMBER}. -Nothing to address. -``` -**STOP** here. - -### Step 2: Categorize Comments - -For each comment, categorize it as one of: - -| Category | Description | Action | -|----------|-------------|--------| -| **actionable** | Requests a code change, addition, or fix | Launch subagent to make change | -| **question** | Asks for clarification or explanation | Include answer in summary | -| **acknowledged** | FYI, self-resolved, or "no action needed" noted | Note in summary | -| **blocked** | Requires external input or is out of scope | Flag for user | - -**Categorization heuristics**: -- Contains "add", "change", "fix", "update", "consider adding", "should be" → **actionable** -- Contains "?" or "why", "how", "what" → **question** -- Contains "no need to update", "will be separate", "acknowledged" → **acknowledged** -- Contains "discuss", "later", "out of scope", "blocked by" → **blocked** - -Display the categorization: -``` -## Comment Analysis - -### Actionable (will make changes): -1. {file}:{line} - "{comment_summary}" → Will add nix note to prerequisites - -### Questions (will answer in summary): -2. {file}:{line} - "{comment_summary}" → Explain CI token approach - -### Acknowledged (no action needed): -3. {file}:{line} - "{comment_summary}" → Reviewer noted separate skill - -### Blocked (needs input): -(none) -``` - -### Step 3: User Confirmation - -Use `AskUserQuestion` to confirm the plan: - -``` -I've categorized {N} comments. My plan: - -**Will make changes for:** -- {file}:{line}: {planned_change} - -**Will explain in summary:** -- {file}:{line}: {planned_explanation} - -**No action needed:** -- {file}:{line}: {reason} - -Proceed with this plan? -``` - -Options: -1. **Proceed** - Execute the plan -2. **Modify** - Let user adjust categorization -3. **Cancel** - Exit without changes - -### Step 4: Address Actionable Comments (Parallel Subagents) - -For each actionable comment, launch a subagent using the Task tool: - -``` -Launch Task subagent with: -- subagent_type: "general-purpose" -- prompt: | - You are addressing a PR review comment. Make the requested change and nothing else. - - **File**: {file_path} - **Line**: {line_number} - **Comment**: {comment_body} - **Diff context**: - ``` - {diff_hunk} - ``` - - Instructions: - 1. Read the file to understand context - 2. Make the minimal change to address the comment - 3. Do NOT commit - just make the edit - 4. Report what you changed - - Be precise. Only change what's needed to address this specific comment. -``` - -**Important**: Launch actionable comment subagents in parallel when they touch different files. For comments on the same file, run sequentially to avoid conflicts. - -Wait for all subagents to complete and collect their results. - -### Step 5: Commit and Push - -After all subagents complete: - -1. **Stage changes**: - ```bash - git add -A - ``` - -2. **Create commit with summary**: - ```bash - git commit -m "Address PR review comments - - Changes made: - - {file1}: {change_summary} - - {file2}: {change_summary} - - Addresses comments from review by {reviewer}" - ``` - -3. **Push to remote**: - ```bash - git push - ``` - -### Step 6: Post Summary Comment - -Post a single comment summarizing all actions taken: - -```bash -tea comment $PR_NUMBER "$(cat <<'EOF' -## Review Comments Addressed - -cc @{reviewer1} @{reviewer2} - -**Changes made** (commit {SHORT_SHA}): -- `{file1}:{line}`: {what_was_changed} -- `{file2}:{line}`: {what_was_changed} - -**Responses to questions**: -- `{file3}:{line}`: {answer_to_question} - -**Acknowledged** (no action needed): -- `{file4}:{line}`: {reason_no_action} - ---- -*Automated response via /gitea_pr_review* -EOF -)" -``` - -### Step 7: Final Summary - -Display to user: - -``` -## PR Review Complete - -**Commit**: {SHA} -**Changes**: {N} files modified - -### Actions Taken: -- [x] {file1}:{line} - Added nix prerequisite note -- [x] {file2}:{line} - Explained CI approach in comment -- [ ] {file3}:{line} - Acknowledged (separate skill) - -**Reviewers tagged**: @{reviewer1}, @{reviewer2} -**Comment posted**: {comment_url} - -PR URL: {GITEA_URL}/{OWNER}/{REPO}/pulls/{PR_NUMBER} -``` - -**Note**: When posting the summary comment, tag all reviewers who left comments so they receive notifications about the changes. - -## Error Handling - -### Subagent failed to make change - -If a subagent fails: -``` -Warning: Could not address comment on {file}:{line} - -Reason: {error} - -Options: -1. Skip this comment and continue -2. Retry with manual guidance -3. Abort all changes -``` - -### Push failed - -``` -Error pushing changes: {error} - -Your changes are committed locally. You may need to: -1. Pull and resolve conflicts: git pull --rebase -2. Push again: git push -``` - -### No actionable comments - -If all comments are questions/acknowledged: -``` -No code changes needed. - -All comments are either questions or acknowledged items. -Posting summary comment with explanations... -``` - -## API Reference - -### Endpoints Used - -| Action | Method | Endpoint | -|--------|--------|----------| -| List reviews | GET | `/api/v1/repos/{owner}/{repo}/pulls/{index}/reviews` | -| Get review comments | GET | `/api/v1/repos/{owner}/{repo}/pulls/{index}/reviews/{id}/comments` | -| Create issue comment | POST | via `tea comment` | - -### Review States - -- `PENDING` - Draft review not yet submitted -- `COMMENT` - General comment without approval/rejection -- `APPROVE` - Approving the changes -- `REQUEST_CHANGES` - Requesting changes before merge - -## Shell Command Patterns - -Claude Code's bash execution has quirks. Use these patterns for reliability: - -### curl requests - -**DO** - Use single quotes for URL and header separately: -```bash -curl -s 'https://git.example.com/api/v1/repos/owner/repo/pulls/1/reviews' \ - -H 'Authorization: token YOUR_TOKEN_HERE' | jq . -``` - -**DON'T** - Variable expansion in `-H` flag often fails: -```bash -# This may fail with "blank argument" errors -curl -s -H "Authorization: token $TOKEN" "$URL" -``` - -### Iterating over reviews - -**DO** - Run separate commands for each review ID: -```bash -echo "=== Review 4 ===" && curl -s 'URL/reviews/4/comments' -H 'Authorization: token ...' | jq . -echo "=== Review 5 ===" && curl -s 'URL/reviews/5/comments' -H 'Authorization: token ...' | jq . -``` - -**DON'T** - For loops with multiline bodies often fail: -```bash -# This may cause syntax errors -for id in 4 5 6; do - curl -s "URL/reviews/$id/comments" -done -``` - -### tea comment - -**DO** - Use single-quoted string for comment body: -```bash -tea comment 26 '## Summary - -Changes made: -- Item 1 -- Item 2' -``` - -**DON'T** - Heredocs may hang or timeout: -```bash -# This may hang indefinitely -tea comment 26 "$(cat <<'EOF' -... -EOF -)" -``` - -## Limitations - -1. **Thread replies**: Gitea API doesn't support inline thread replies. We post a single summary comment instead. - -2. **Complex changes**: For comments requiring significant refactoring, the subagent may need guidance. The skill will flag these as "blocked" for user input. - -3. **Merge conflicts**: If the branch is behind, you may need to rebase before changes can be pushed. - -## Example Session - -``` -User: /gitea_pr_review 26 -Assistant: Addressing PR review comments for PR #26... - -Repository: johno/nixos-configs -Branch: bead/nixos-configs-vru -Gitea URL: https://git.johnogle.info - -## Comment Analysis - -### Actionable (will make changes): -1. gitea_pr_review.md:12 - "could we indicate nix+nixpkgs satisfies this?" - → Will add note that nix users can get tools via nixpkgs - -### Questions (will answer in summary): -(none) - -### Acknowledged (no action needed): -2. gitea_pr_review.md:50 - "we eventually want to run this in CI..." - → Reviewer noted this will be a separate skill - -Proceed with this plan? [Proceed] - -Launching subagent to address comment 1... -[Subagent completes edit] - -Committing changes... -[abc1234] Address PR review comments - -Pushing to remote... -Done. - -Posting summary comment... - -## PR Review Complete - -**Commit**: abc1234 -**Changes**: 1 file modified - -### Actions Taken: -- [x] gitea_pr_review.md:12 - Added nix prerequisite note -- [ ] gitea_pr_review.md:50 - Acknowledged (separate skill) - -**Comment posted**: https://git.johnogle.info/.../pulls/26#issuecomment-XXX - -PR URL: https://git.johnogle.info/johno/nixos-configs/pulls/26 -``` - -## See Also - -- `tea` CLI: https://gitea.com/gitea/tea -- Gitea API: https://docs.gitea.com/api/ -- `/beads_workflow` for full development workflow diff --git a/home/roles/development/commands/import_gitea_issues.md b/home/roles/development/commands/import_gitea_issues.md deleted file mode 100644 index d6214b6..0000000 --- a/home/roles/development/commands/import_gitea_issues.md +++ /dev/null @@ -1,130 +0,0 @@ ---- -description: Import open Gitea issues as beads, skipping already-imported ones ---- - -# Import Gitea Issues as Beads - -This skill imports open Gitea issues as beads, checking for duplicates to avoid re-importing already tracked issues. - -## Prerequisites - -- `tea` CLI must be installed and configured for the repository -- `bd` (beads) CLI must be installed -- Must be in a git repository with a Gitea/Forgejo remote - -## Workflow - -### Step 1: Get open Gitea issues - -List all open issues using `tea`: - -```bash -tea issues -``` - -This returns a table with columns: INDEX, TITLE, LABELS, MILESTONE - -### Step 2: Get existing beads - -List all current beads to check what's already imported: - -```bash -bd list -``` - -Also check bead notes for issue URLs to identify imports: - -```bash -bd list --json | jq -r '.[] | select(.notes != null) | .notes' | grep -oP 'issues/\K\d+' -``` - -### Step 3: Check for already-linked PRs - -Check if any open PRs reference beads (skip these issues as they're being worked on): - -```bash -tea pr list -``` - -Look for PRs with: -- Bead ID in title: `[nixos-configs-xxx]` -- Bead reference in body: `Implements bead:` or `Bead ID:` - -### Step 4: For each untracked issue, create a bead - -For each issue not already tracked: - -1. **Get full issue details**: - ```bash - tea issue [ISSUE_NUMBER] - ``` - -2. **Determine bead type** based on issue content: - - "bug" - if issue mentions bug, error, broken, fix, crash - - "feature" - if issue mentions feature, add, new, enhancement - - "task" - default for other issues - -3. **Create the bead**: - ```bash - bd add "[ISSUE_TITLE]" \ - --type=[TYPE] \ - --priority=P2 \ - --notes="Gitea issue: [ISSUE_URL] - - Original issue description: - [ISSUE_BODY]" - ``` - - Note: The `--notes` flag accepts multi-line content. - -### Step 5: Report results - -Present a summary: - -``` -## Gitea Issues Import Summary - -### Imported as Beads -| Issue | Title | Bead ID | Type | -|-------|-------|---------|------| -| #5 | Add dark mode | nixos-configs-abc | feature | -| #3 | Config broken on reboot | nixos-configs-def | bug | - -### Skipped (Already Tracked) -| Issue | Title | Reason | -|-------|-------|--------| -| #4 | Update flake | Existing bead: nixos-configs-xyz | -| #2 | Refactor roles | PR #7 references bead | - -### Skipped (Other) -| Issue | Title | Reason | -|-------|-------|--------| -| #1 | Discussion: future plans | No actionable work | -``` - -## Type Detection Heuristics - -Keywords to detect issue type: - -**Bug indicators** (case-insensitive): -- bug, error, broken, fix, crash, fail, issue, problem, wrong, not working - -**Feature indicators** (case-insensitive): -- feature, add, new, enhancement, implement, support, request, want, would be nice - -**Task** (default): -- Anything not matching bug or feature patterns - -## Error Handling - -- **tea not configured**: Report error and exit -- **bd not available**: Report error and exit -- **Issue already has bead**: Skip and report in summary -- **Issue is a PR**: Skip (tea shows PRs and issues separately) - -## Notes - -- Default priority is P2; adjust manually after import if needed -- Issue labels from Gitea are not automatically mapped to bead tags -- Run this periodically to catch new issues -- After import, use `bd ready` to see which beads can be worked on diff --git a/home/roles/development/commands/parallel_beads.md b/home/roles/development/commands/parallel_beads.md deleted file mode 100644 index dd6e54d..0000000 --- a/home/roles/development/commands/parallel_beads.md +++ /dev/null @@ -1,409 +0,0 @@ ---- -description: Orchestrate parallel bead processing with worktrees, PRs, and reviews ---- - -# Parallel Beads Workflow - -This skill orchestrates parallel bead processing using subagents. Each bead gets its own worktree, implementation, PR, and review. - -## Phase 1: Selection - -1. **Get ready beads**: Run `bd ready` to list all beads with no blockers - -2. **Filter by plan readiness**: - For each ready bead, check if it's ready for batch implementation: - - **Has plan** (`thoughts/beads-{id}/plan.md` exists): Include - - **type=bug** without plan: Include (simple bugs can implement directly) - - **type=feature/task** without plan: Exclude with warning - - ```bash - # Check for plan existence - ls thoughts/beads-{bead-id}/plan.md 2>/dev/null - ``` - -3. **Report skipped beads**: - If any beads were skipped, inform the user: - ``` - Skipped beads (no plan): - - {bead-id}: {title} (type: feature) - Run /beads_plan {bead-id} first - - {bead-id}: {title} (type: task) - Run /beads_plan {bead-id} first - ``` - -4. **Present selection**: Use `AskUserQuestion` with `multiSelect: true` to let the user choose which beads to work on - - Include bead ID and title for each option - - Only show beads that passed the plan check - - Allow selection of multiple beads - -Example: -``` -AskUserQuestion with: -- question: "Which beads do you want to work on in parallel?" -- multiSelect: true -- options from filtered bd ready output -``` - -## Phase 2: Worktree Setup - -Before launching implementation subagents, create worktrees for all selected beads: - -1. **Get repository name**: - ```bash - REPO_NAME=$(git remote get-url origin | sed 's|.*/||' | sed 's/\.git$//') - ``` - -2. **For each selected bead**, create its worktree: - ```bash - BEAD_ID="[bead-id]" - # Check if worktree already exists - if [ -d "$HOME/wt/${REPO_NAME}/${BEAD_ID}" ]; then - echo "Worktree already exists: ~/wt/${REPO_NAME}/${BEAD_ID}" - # Ask user: remove and recreate, or skip this bead? - else - git worktree add -b "bead/${BEAD_ID}" "$HOME/wt/${REPO_NAME}/${BEAD_ID}" - fi - ``` - -3. **Track created worktrees**: - Maintain a list of (bead_id, worktree_path) pairs for use in subagent instructions. - -4. **Report status**: - ``` - Created worktrees: - - nixos-configs-abc → ~/wt/nixos-configs/nixos-configs-abc (branch: bead/nixos-configs-abc) - - nixos-configs-xyz → ~/wt/nixos-configs/nixos-configs-xyz (branch: bead/nixos-configs-xyz) - - Skipped (existing worktree): - - nixos-configs-123 → Ask user for resolution - ``` - -**Note**: If a worktree or branch already exists, ask the user before proceeding: -- Remove existing worktree and branch, then recreate -- Skip this bead -- Use existing worktree as-is (risky - branch may have diverged) - -## Phase 3: Parallel Implementation - -For each selected bead, launch a subagent using the Task tool. All subagents should be launched in parallel (single message with multiple Task tool calls). - -### Subagent Instructions Template - -Each implementation subagent should receive these instructions: - -``` -Work on bead [BEAD_ID]: [BEAD_TITLE] - -Worktree path: [WORKTREE_PATH] - -## CRITICAL: Branch Verification (MUST DO FIRST) - -1. **Navigate to worktree**: - ```bash - cd [WORKTREE_PATH] - ``` - -2. **Verify branch** (MANDATORY before ANY modifications): - ```bash - CURRENT_BRANCH=$(git branch --show-current) - echo "Current branch: $CURRENT_BRANCH" - pwd - ``` - - **ABORT CONDITIONS** - If ANY of these are true, STOP IMMEDIATELY: - - Branch is `main` or `master` - - Branch does not match `bead/[BEAD_ID]` - - If you detect any abort condition: - ``` - ABORTING: Branch verification failed. - Expected branch: bead/[BEAD_ID] - Actual branch: [CURRENT_BRANCH] - Working directory: [pwd output] - - DO NOT PROCEED. Report this error to the orchestrator. - ``` - -## After Verification Passes - -3. **Review the bead requirements**: - - Run `bd show [BEAD_ID]` to understand the acceptance criteria - - Note any external issue references (GitHub issues, Linear tickets, etc.) - -4. **Extract validation criteria**: - - Check for a plan: `thoughts/beads-[BEAD_ID]/plan.md` - - If plan exists: - - Read the plan and find the "Automated Verification" section - - Extract each verification command (lines starting with `- [ ]` followed by a command) - - Example: `- [ ] Tests pass: \`make test\`` → extract `make test` - - Note any "Per CONTRIBUTING.md:" requirements for additional validation - - Also read the "Manual Verification" section from the plan if present - - Save manual verification items for inclusion in the PR description (they won't be executed) - - If no plan exists, use best-effort validation: - - Check if `Makefile` exists → try `make test` and `make lint` - - Check if `flake.nix` exists → try `nix flake check` - - Check if `package.json` exists → try `npm test` - - **Check for CONTRIBUTING.md** → read and extract testing/linting requirements - - Track which requirements can be automated vs need manual review - - Automated: commands that can be run (e.g., "run `make test`") - - Manual: qualitative checks (e.g., "ensure documentation is updated") - - If none found, note "No validation criteria found" - -5. **Implement the changes**: - - Work in the worktree directory - - Complete all acceptance criteria listed in the bead - - After implementation, run validation: - - Execute each validation command from step 4 - - Track results in this format: - ``` - VALIDATION_RESULTS: - - make test: PASS - - make lint: FAIL (exit code 1: src/foo.ts:23 - missing semicolon) - - nix flake check: SKIP (not applicable - no flake.nix) - - cargo test: ERROR (command not found) - ``` - - **Status definitions:** - - **PASS**: Check executed successfully with no issues - - **FAIL**: Check executed but found issues that need attention - - **SKIP**: Check not applicable to this project (e.g., no Makefile for `make test`) - - **ERROR**: Check could not execute (missing tool, permission error, command not found) - - - If any validation fails: - - Continue with PR creation (don't block) - - Document failures in bead notes: `bd update [BEAD_ID] --notes="Validation failures: [list]"` - -6. **Commit and push**: - - Stage all changes: `git add -A` - - Create a descriptive commit message - - Push the branch: `git push -u origin bead/[BEAD_ID]` - -7. **Create a PR**: - - Detect hosting provider from origin URL: `git remote get-url origin` - - If URL contains `github.com`, use `gh`; otherwise use `tea` (Gitea/Forgejo) - - PR title: "[BEAD_ID] [BEAD_TITLE]" - - PR body must include: - - Reference to bead ID: "Implements bead: [BEAD_ID]" - - Any external issue references from the bead (e.g., "Closes #123") - - Summary of changes - - For GitHub (`gh`): - ```bash - gh pr create --title "[BEAD_ID] [BEAD_TITLE]" --body "$(cat <<'EOF' - ## Summary - [Brief description of changes] - - ## Bead Reference - Implements bead: [BEAD_ID] - - ## External Issues - [Any linked issues from the bead] - - ## Changes - - [List of changes made] - - ## Validation Steps Completed - - ### Automated Checks - | Check | Status | Details | - |-------|--------|---------| - | make test | PASS | | - | make lint | FAIL | src/foo.ts:23 - missing semicolon | - | nix flake check | SKIP | not applicable - no flake.nix | - | cargo test | ERROR | command not found | - - ### Manual Verification Required - [If plan has Manual Verification items, list them as unchecked boxes:] - - [ ] Verify UI changes match design mockups - - [ ] Test on mobile viewport sizes - [If no manual verification items: "None specified in plan."] - - ### CONTRIBUTING.md Compliance - [If CONTRIBUTING.md requirements were extracted:] - - [x] Tests pass (verified via `make test`) - - [ ] Documentation updated (needs manual review) - [If no CONTRIBUTING.md: "No contribution guidelines found."] - EOF - )" - ``` - - For Gitea (`tea`): - ```bash - tea pr create --head bead/[BEAD_ID] --base main \ - --title "[BEAD_ID] [BEAD_TITLE]" \ - --description "## Summary - [Brief description of changes] - - ## Bead Reference - Implements bead: [BEAD_ID] - - ## External Issues - [Any linked issues from the bead] - - ## Changes - - [List of changes made] - - ## Validation Steps Completed - - ### Automated Checks - | Check | Status | Details | - |-------|--------|---------| - | make test | PASS | | - | make lint | FAIL | src/foo.ts:23 - missing semicolon | - | nix flake check | SKIP | not applicable - no flake.nix | - | cargo test | ERROR | command not found | - - ### Manual Verification Required - [If plan has Manual Verification items, list them as unchecked boxes:] - - [ ] Verify UI changes match design mockups - - [ ] Test on mobile viewport sizes - [If no manual verification items: None specified in plan.] - - ### CONTRIBUTING.md Compliance - [If CONTRIBUTING.md requirements were extracted:] - - [x] Tests pass (verified via make test) - - [ ] Documentation updated (needs manual review) - [If no CONTRIBUTING.md: No contribution guidelines found.]" - ``` - -8. **Update bead status**: - - Mark the bead as "in_review": `bd update [BEAD_ID] --status=in_review` - - Add the PR URL to the bead notes: `bd update [BEAD_ID] --notes="$(bd show [BEAD_ID] --json | jq -r '.notes') - -PR: [PR_URL]"` - -9. **Report results**: - - Return: - - PR URL - - Bead ID - - Implementation status (success/failure/blocked) - - Validation summary: `X passed, Y failed, Z skipped, W errors` - - List of any validation failures or errors with details - - If blocked or unable to complete, explain what's blocking progress - - If validation failed, include the specific failures so the main agent can summarize them for the user -``` - -### Launching Subagents - -For each bead, substitute into the template: -- `[BEAD_ID]` - the bead ID -- `[BEAD_TITLE]` - the bead title -- `[WORKTREE_PATH]` - the worktree path created in Phase 2 - -Use `subagent_type: "general-purpose"` for implementation subagents. Launch all selected beads' subagents in a single message for parallel execution: - -``` - -``` - -**Important**: The worktree paths were created in Phase 2. Use the exact paths that were created, e.g.: -- `~/wt/nixos-configs/nixos-configs-abc` -- `~/wt/nixos-configs/nixos-configs-xyz` - -Collect results from all subagents before proceeding. - -## Phase 4: Parallel Review - -After all implementation subagents complete, launch review subagents for each PR. - -### Review Subagent Instructions Template - -``` -Review PR for bead [BEAD_ID] - -1. **Detect hosting provider**: Run `git remote get-url origin` - if it contains `github.com` use `gh`, otherwise use `tea` - -2. **Read the PR**: - - For GitHub: `gh pr view [PR_NUMBER] --json title,body,additions,deletions,files` - - For Gitea: `tea pr view [PR_NUMBER]` - - View the diff: `git diff main...bead/[BEAD_ID]` - -3. **Review against acceptance criteria**: - - Run `bd show [BEAD_ID]` to get the acceptance criteria - - Verify each criterion is addressed - -4. **Leave review comments**: - - For GitHub: `gh pr review [PR_NUMBER] --comment --body "[COMMENTS]"` - - For Gitea: `tea pr review [PR_NUMBER] --comment "[COMMENTS]"` - - Include: - - Acceptance criteria checklist (which are met, which might be missing) - - Code quality observations - - Suggestions for improvement - -5. **Return summary**: - - Overall assessment (ready to merge / needs changes) - - Key findings -``` - -Launch all review subagents in parallel. - -## Phase 5: Cleanup and Summary - -After reviews complete: - -1. **Clean up worktrees**: - ```bash - git worktree remove ~/wt/[REPO_NAME]/[BEAD_ID] --force - ``` - Do this for each bead's worktree. - -2. **Provide final summary**: - Present a table or list with: - - Bead ID - - PR URL - - Status (success / failed / blocked) - - Validation summary (X/Y passed) - - Review summary - - Any failures or blockers encountered - - If any validation failures occurred, list them in a "Validation Failures" section so the user can address them. - -Example output: -``` -## Parallel Beads Summary - -| Bead | PR | Bead Status | Validation | Review | -|------|-----|-------------|------------|--------| -| beads-abc | #123 | in_review | 3/3 passed | Approved | -| beads-xyz | #124 | in_review | 2/3 passed | Needs changes | -| beads-123 | - | open (failed) | - | Blocked by missing dependency | - -### Validation Failures -- beads-xyz: `make lint` failed - src/foo.ts:23 missing semicolon - -### Failures/Blockers -- beads-123: Could not complete because [reason] - -### Next Steps -- Fix validation failures before merging -- Review PRs that need changes -- Address blockers for failed beads -- Run `/reconcile_beads` after PRs are merged to close beads -``` - -## Error Handling - -- **Worktree creation failures** (Phase 2): - - If `git worktree add` fails (branch exists, path exists), prompt user: - - Remove existing and retry - - Skip this bead - - Use existing (with warning about potential divergence) - - Do NOT proceed to subagent launch until worktree is confirmed - -- **Branch verification failures** (subagent reports): - - If subagent reports it's on `main` or `master`, do NOT retry - - Mark bead as failed with reason "Branch verification failed" - - Continue with other beads but flag this as a critical issue - - Investigation required: the worktree may have been corrupted or not created properly - -- **Subagent failures**: If a subagent fails or times out, note it in the summary but continue with other beads -- **PR creation failures**: Report the error but continue with reviews of successful PRs - -## Resource Limits - -- Consider limiting concurrent subagents to 3-5 to avoid overwhelming system resources -- If user selects more beads than the limit, process them in batches - -## Notes - -- This workflow integrates with the beads system (`bd` commands) -- Worktrees are created in `~/wt/[REPO_NAME]/` by convention -- Each bead gets its own isolated branch and worktree -- PRs automatically reference the bead ID for traceability diff --git a/home/roles/development/commands/reconcile_beads.md b/home/roles/development/commands/reconcile_beads.md deleted file mode 100644 index 186c3a6..0000000 --- a/home/roles/development/commands/reconcile_beads.md +++ /dev/null @@ -1,129 +0,0 @@ ---- -description: Reconcile beads with merged PRs and close completed beads ---- - -# Reconcile Beads Workflow - -This skill reconciles beads that are in `in_review` status with their corresponding PRs. If a PR has been merged, the bead is closed and any linked Gitea issue is also closed. - -## Prerequisites - -- Custom status `in_review` must be configured: `bd config set status.custom "in_review"` -- Beads in `in_review` status should have a PR URL in their notes -- `tea` CLI must be configured for closing Gitea issues - -## Workflow - -### Step 1: Find beads in review - -```bash -bd list --status=in_review -``` - -### Step 2: For each bead, check PR status - -1. **Get the PR URL from bead notes**: - ```bash - bd show [BEAD_ID] --json | jq -r '.[0].notes' - ``` - Note: `bd show --json` returns an array, so use `.[0]` to access the first element. - Extract the PR URL (look for lines starting with "PR:" or containing pull request URLs). - Extract the PR number: `echo "$NOTES" | grep -oP '/pulls/\K\d+'` - -2. **Detect hosting provider**: - - Run `git remote get-url origin` - - If URL contains `github.com`, use `gh`; otherwise use `tea` (Gitea/Forgejo) - -3. **Check PR status**: - - For GitHub: - ```bash - gh pr view [PR_NUMBER] --json state,merged - ``` - - For Gitea: - ```bash - tea pr list --state=closed - ``` - Look for the PR number in the INDEX column with STATE "merged". - Note: `tea pr view [PR_NUMBER]` lists all PRs, not a specific one. Use `tea pr list --state=closed` and look for your PR number in the results. - -### Step 3: Close merged beads - -If the PR is merged: -```bash -bd close [BEAD_ID] --reason="PR merged: [PR_URL]" -``` - -### Step 3.1: Close corresponding Gitea issue (if any) - -After closing a bead, check if it has a linked Gitea issue: - -1. **Check for Gitea issue URL in bead notes**: - Look for the pattern `Gitea issue: ` in the notes. Extract the URL. - -2. **Extract issue number from URL**: - ```bash - # Example: https://git.johnogle.info/johno/nixos-configs/issues/16 -> 16 - echo "$GITEA_URL" | grep -oP '/issues/\K\d+' - ``` - -3. **Close the Gitea issue**: - ```bash - tea issues close [ISSUE_NUMBER] - ``` - -4. **Handle errors gracefully**: - - If issue is already closed: Log warning, continue - - If issue not found: Log warning, continue - - If `tea` fails: Log error, continue with other beads - - Example warning output: - ``` - Warning: Could not close Gitea issue #16: issue already closed - ``` - -### Step 4: Report summary - -Present results: - -``` -## Beads Reconciliation Summary - -### Closed (PR Merged) -| Bead | PR | Gitea Issue | Title | -|------|-----|-------------|-------| -| beads-abc | #123 | #16 closed | Feature X | -| beads-xyz | #456 | (none) | Bug fix Y | - -### Gitea Issues Closed -| Issue | Bead | Status | -|-------|------|--------| -| #16 | beads-abc | Closed successfully | -| #17 | beads-def | Already closed (skipped) | -| #99 | beads-ghi | Error: issue not found | - -### Still in Review -| Bead | PR | Status | Title | -|------|-----|--------|-------| -| beads-def | #789 | Open | Feature Z | - -### Issues Found -- beads-ghi: No PR URL found in notes -- beads-jkl: PR #999 not found (may have been deleted) -``` - -## Error Handling - -- **Missing PR URL**: Skip the bead and report it -- **PR not found**: Report the error but continue with other beads -- **API errors**: Report and continue -- **Gitea issue already closed**: Log warning, continue (not an error) -- **Gitea issue not found**: Log warning, continue (issue may have been deleted) -- **No Gitea issue linked**: Normal case, no action needed -- **tea command fails**: Log error with output, continue with other beads - -## Notes - -- This skill complements `/parallel_beads` which sets beads to `in_review` status -- Run this skill periodically or after merging PRs to keep beads in sync -- Beads with closed (but not merged) PRs are not automatically closed - they may need rework -- Gitea issues are only closed for beads that have a `Gitea issue: ` in their notes diff --git a/home/roles/development/default.nix b/home/roles/development/default.nix index 1a37f17..0ae5371 100644 --- a/home/roles/development/default.nix +++ b/home/roles/development/default.nix @@ -5,27 +5,6 @@ with lib; let cfg = config.home.roles.development; - # Build beads and gastown from flake inputs using shared package definitions - beadsRev = builtins.substring 0 8 (globalInputs.beads.rev or "unknown"); - beadsPackage = pkgs.callPackage ../../../packages/beads { - src = globalInputs.beads; - version = "0.52.0-${beadsRev}"; - }; - - gastownRev = builtins.substring 0 8 (globalInputs.gastown.rev or "unknown"); - gastownPackage = pkgs.callPackage ../../../packages/gastown { - src = globalInputs.gastown; - version = "unstable-${gastownRev}"; - }; - - # Build perles from flake input using shared package definition - perlesRev = builtins.substring 0 8 (globalInputs.perles.rev or "unknown"); - perlesPackage = pkgs.callPackage ../../../packages/perles { - inherit (pkgs.unstable) buildGoModule; - src = globalInputs.perles; - version = "unstable-${perlesRev}"; - }; - # Fetch the claude-plugins repository (for humanlayer commands/agents) # Update the rev to get newer versions of the commands claudePluginsRepo = builtins.fetchGit { @@ -64,13 +43,8 @@ in config = mkIf cfg.enable { home.packages = [ - beadsPackage - gastownPackage - perlesPackage pkgs.unstable.claude-code - pkgs.unstable.claude-code-router pkgs.unstable.codex - pkgs.unstable.dolt pkgs.sqlite # Custom packages @@ -129,72 +103,11 @@ in fi done - # Copy local commands from this repo (with retry for race conditions with running Claude) - for file in ${./commands}/*.md; do - if [ -f "$file" ]; then - filename=$(basename "$file" .md) - dest="$HOME/.claude/commands/''${filename}.md" - # Remove existing file first, then copy with retry on failure - rm -f "$dest" 2>/dev/null || true - if ! cp "$file" "$dest" 2>/dev/null; then - sleep 0.5 - cp "$file" "$dest" || echo "Warning: Failed to copy $filename.md to commands" - fi - chmod u+w "$dest" 2>/dev/null || true - fi - done - - # Copy local skills (reference materials) to skills subdirectory - mkdir -p ~/.claude/commands/skills - for file in ${./skills}/*.md; do - if [ -f "$file" ]; then - filename=$(basename "$file" .md) - dest="$HOME/.claude/commands/skills/''${filename}.md" - rm -f "$dest" 2>/dev/null || true - if ! cp "$file" "$dest" 2>/dev/null; then - sleep 0.5 - cp "$file" "$dest" || echo "Warning: Failed to copy $filename.md to skills" - fi - chmod u+w "$dest" 2>/dev/null || true - fi - done - - # Copy micro-skills (compact reusable knowledge referenced by formulas) - for file in ${./skills/micro}/*.md; do - if [ -f "$file" ]; then - dest="$HOME/.claude/commands/skills/$(basename "$file")" - rm -f "$dest" 2>/dev/null || true - cp "$file" "$dest" - chmod u+w "$dest" 2>/dev/null || true - fi - done - - # Install beads formulas to user-level formula directory - mkdir -p ~/.beads/formulas - for file in ${./formulas}/*.formula.toml; do - if [ -f "$file" ]; then - dest="$HOME/.beads/formulas/$(basename "$file")" - rm -f "$dest" 2>/dev/null || true - cp "$file" "$dest" - chmod u+w "$dest" 2>/dev/null || true - fi - done - - $DRY_RUN_CMD echo "Claude Code plugins installed: humanlayer commands/agents + local commands + local skills + formulas" - ''; - - # Set up beads Claude Code integration (hooks for SessionStart/PreCompact) - # This uses the CLI + hooks approach which is recommended over MCP for Claude Code - home.activation.claudeCodeBeadsSetup = lib.hm.dag.entryAfter ["writeBoundary" "claudeCodeCommands"] '' - # Run bd setup claude to install hooks into ~/.claude/settings.json - # This is idempotent - safe to run multiple times - ${beadsPackage}/bin/bd setup claude 2>/dev/null || true - - $DRY_RUN_CMD echo "Claude Code beads integration configured (hooks installed)" + $DRY_RUN_CMD echo "Claude Code plugins installed: humanlayer commands/agents" ''; # Configure Claude Code statusline (merge into existing settings.json) - home.activation.claudeCodeStatusLine = lib.hm.dag.entryAfter ["writeBoundary" "claudeCodeBeadsSetup"] '' + home.activation.claudeCodeStatusLine = lib.hm.dag.entryAfter ["writeBoundary"] '' SETTINGS="$HOME/.claude/settings.json" mkdir -p "$HOME/.claude" if [ -f "$SETTINGS" ]; then @@ -205,46 +118,6 @@ in $DRY_RUN_CMD echo "Claude Code statusline configured" ''; - # Beads timer gate checker (Linux only - uses systemd) - # Runs every 5 minutes to auto-resolve expired timer gates across all beads projects - # This enables self-scheduling molecules (watchers, patrols, etc.) - systemd.user.services.beads-gate-check = lib.mkIf pkgs.stdenv.isLinux { - Unit = { - Description = "Check and resolve expired beads timer gates"; - }; - Service = { - Type = "oneshot"; - # Check gates in all workspaces that have running daemons - ExecStart = pkgs.writeShellScript "beads-gate-check-all" '' - # Get list of workspaces from daemon registry - workspaces=$(${beadsPackage}/bin/bd daemon list --json 2>/dev/null | ${pkgs.jq}/bin/jq -r '.[].workspace // empty' 2>/dev/null) - - if [ -z "$workspaces" ]; then - exit 0 # No beads workspaces, nothing to do - fi - - for ws in $workspaces; do - if [ -d "$ws" ]; then - cd "$ws" && ${beadsPackage}/bin/bd gate check --type=timer --quiet 2>/dev/null || true - fi - done - ''; - }; - }; - - systemd.user.timers.beads-gate-check = lib.mkIf pkgs.stdenv.isLinux { - Unit = { - Description = "Periodic beads timer gate check"; - }; - Timer = { - OnBootSec = "5min"; - OnUnitActiveSec = "5min"; - }; - Install = { - WantedBy = [ "timers.target" ]; - }; - }; - # Note: modules must be imported at top-level home config }; } diff --git a/home/roles/development/formulas/quick-fix.formula.toml b/home/roles/development/formulas/quick-fix.formula.toml deleted file mode 100644 index 8e9708e..0000000 --- a/home/roles/development/formulas/quick-fix.formula.toml +++ /dev/null @@ -1,115 +0,0 @@ -# Quick Fix Formula -# -# Streamlined workflow for well-understood bugs and small fixes. -# Skips the deep research and planning phases of RPI - get in, fix, get out. -# -# Use when: -# - Bug is well-understood (you know what's broken) -# - Fix is straightforward (no architectural decisions) -# - Change is small (< 100 lines) -# -# Use RPI instead when: -# - Root cause is unclear -# - Multiple approaches possible -# - Significant design decisions needed - -formula = "quick-fix" -description = """ -Streamlined workflow for bugs and small fixes. - -A faster alternative to RPI for well-understood issues: -1. Quick investigation to confirm understanding -2. Implement the fix -3. Verify with tests -4. Commit and close - -No human gates - designed for quick turnaround on obvious fixes. -""" -version = 1 -type = "workflow" - -# === Variables === - -[vars.title] -required = true -description = "Brief description of the bug/fix" - -[vars.bead_id] -description = "Existing bead ID (creates new if not provided)" - -[vars.test_cmd] -default = "make test" -description = "Command to verify the fix" - -# === Steps === - -[[steps]] -id = "investigate" -title = "Investigate: {{title}}" -description = """ -Quick investigation to confirm understanding of the bug. - -Goals: -- Locate the problematic code -- Confirm root cause matches expectations -- Identify files that need changes - -This is NOT deep research - spend 5-10 minutes max. -If the bug is more complex than expected, pivot to RPI workflow. - -Output: Mental model of what to fix (no artifact needed). -""" - -[[steps]] -id = "fix" -title = "Fix: {{title}}" -needs = ["investigate"] -description = """ -Implement the fix. - -Guidelines: -- Make minimal changes to fix the issue -- Follow existing code patterns -- Add/update tests if appropriate -- Keep changes focused (no drive-by refactors) - -If the fix grows beyond expectations, pause and consider: -- Should this be an RPI workflow instead? -- Should we split into multiple changes? -""" - -[[steps]] -id = "verify" -title = "Verify fix" -needs = ["fix"] -description = """ -Verify the fix works correctly. - -Run: {{test_cmd}} - -Also check: -- Bug is actually fixed (manual verification) -- No obvious regressions introduced -- Code compiles/builds cleanly - -If tests fail, iterate on the fix step. -""" - -[[steps]] -id = "commit" -title = "Commit and close" -needs = ["verify"] -description = """ -Commit the fix and close the bead. - -Actions: -1. Stage changes: git add -A -2. Commit with descriptive message: git commit -m "fix: {{title}}" -3. Push to remote: git push -4. Close the bead: bd close {{bead_id}} - -Commit message should explain: -- What was broken -- How it was fixed -- Any relevant context -""" diff --git a/home/roles/development/formulas/rpi.formula.toml b/home/roles/development/formulas/rpi.formula.toml deleted file mode 100644 index 00f5b7a..0000000 --- a/home/roles/development/formulas/rpi.formula.toml +++ /dev/null @@ -1,124 +0,0 @@ -# RPI Formula - Research -> Plan -> Implement -# -# Universal workflow for feature development with human gates. - -formula = "rpi" -description = """ -Research -> Plan -> Implement workflow. - -Usage: - bd pour rpi --var title="Add user preferences" - bd pour rpi --var title="Auth" --var bead_id="project-abc" --var test_cmd="nix flake check" -""" -version = 1 -type = "workflow" - -# ─── Variables ─── - -[vars.title] -required = true -description = "What are we building?" - -[vars.bead_id] -description = "Existing bead ID (creates new if not provided)" - -[vars.test_cmd] -default = "make test" -description = "Command to run tests" - -[vars.lint_cmd] -default = "make lint" -description = "Command to run linting" - -# ─── Research Phase ─── - -[[steps]] -id = "research" -title = "Research: {{title}}" -skill = "research-agents" -description = """ -Conduct comprehensive codebase research. - -Goals: -- Understand current implementation -- Identify patterns to follow -- Find relevant files and dependencies -- Document key discoveries - -Output: thoughts/beads-{{bead_id}}/research.md -""" - -# ─── Planning Phase ─── - -[[steps]] -id = "plan" -title = "Plan: {{title}}" -needs = ["research"] -type = "human" -skill = "planning" -description = """ -Create detailed implementation plan based on research. - -Goals: -- Present understanding and clarify requirements -- Propose design options with tradeoffs -- Define phases with success criteria -- Identify what we're NOT doing - -Output: thoughts/beads-{{bead_id}}/plan.md -""" - -[steps.gate] -type = "human" -reason = "Plan approval before implementation" - -# ─── Implementation Phase ─── - -[[steps]] -id = "implement" -title = "Implement: {{title}}" -needs = ["plan"] -description = """ -Execute the approved plan phase by phase. - -For each phase: -1. Make the changes -2. Run verification: {{test_cmd}}, {{lint_cmd}} -3. Update plan checkboxes for resumability - -Stop and ask if encountering unexpected issues. -""" - -# ─── Verification Phase ─── - -[[steps]] -id = "verify" -title = "Manual verification" -needs = ["implement"] -type = "human" -description = """ -Human confirms implementation works correctly. - -Check: feature works, edge cases handled, no regressions. -Tests: {{test_cmd}} | Lint: {{lint_cmd}} -""" - -[steps.gate] -type = "human" -reason = "Confirm implementation is correct" - -# ─── Completion ─── - -[[steps]] -id = "complete" -title = "Close bead" -needs = ["verify"] -skill = "artifact-format" -description = """ -Mark work as complete. - -Actions: -- bd update {{bead_id}} --notes="Implementation complete" -- bd close {{bead_id}} --reason="Completed: {{title}}" -- bd sync && git push -""" diff --git a/home/roles/development/skills/bd_workflow.md b/home/roles/development/skills/bd_workflow.md deleted file mode 100644 index b419e6d..0000000 --- a/home/roles/development/skills/bd_workflow.md +++ /dev/null @@ -1,230 +0,0 @@ ---- -description: How to use the bd (beads) CLI for issue tracking, dependencies, and workflow orchestration ---- - -# BD Workflow - -The `bd` CLI is a git-backed issue tracker with first-class dependency support. Use it for multi-session work, blocking relationships, and persistent memory across conversation compaction. - -## When to Use BD vs TodoWrite - -| Use BD | Use TodoWrite | -|--------|---------------| -| Work spans multiple sessions | Single-session tasks | -| Dependencies between tasks | Independent subtasks | -| Need audit trail in git | Ephemeral tracking | -| Cross-repo coordination | Local project only | -| Resuming after compaction | Simple task lists | - -## Core Commands - -### Creating Issues - -```bash -bd create "Issue title" # Basic task -bd create "Bug title" --type=bug --priority=1 # P1 bug -bd create "Feature" --type=feature -d "Details" # With description -bd q "Quick capture" # Output only ID -``` - -### Managing Issues - -```bash -bd show # View issue details -bd show --children # View children of epic -bd list # List open issues (default 50) -bd list --all # Include closed -bd list -s in_progress # Filter by status -bd list -t bug -p 0 # P0 bugs -bd list --pretty # Tree format -``` - -### Updating Issues - -```bash -bd update --status=in_progress # Start work -bd update --status=blocked # Mark blocked -bd update --claim # Claim atomically -bd update --add-label=urgent # Add label -bd update -d "New description" # Update description -``` - -### Closing Issues - -```bash -bd close # Close issue -bd close --continue # Auto-advance to next step -bd close --suggest-next # Show newly unblocked -``` - -## Finding Work - -```bash -bd ready # Ready issues (no blockers) -bd ready --mol # Ready steps in molecule -bd ready -n 5 # Limit to 5 -bd ready --assignee me # Assigned to me -bd blocked # Show blocked issues -bd blocked --parent # Blocked within epic -``` - -## Dependency Management - -### Creating Dependencies - -```bash -bd dep --blocks # A blocks B -bd dep add # Same as above -bd dep relate # Bidirectional link -``` - -### Viewing Dependencies - -```bash -bd dep list # Show dependencies -bd dep tree # Dependency tree -bd dep cycles # Detect cycles -``` - -### Removing Dependencies - -```bash -bd dep remove # Remove dependency -bd dep unrelate # Remove relation -``` - -## Sync Workflow - -BD syncs issues via git. The daemon handles this automatically, but manual sync is available: - -```bash -bd sync # Full sync (pull, merge, push) -bd sync --flush-only # Export to JSONL only -bd sync --import-only # Import from JSONL only -bd sync --status # Show sync branch diff -bd sync --squash # Accumulate without commit -``` - -## Formula and Molecule Workflow - -Formulas are reusable workflow templates. Molecules are instantiated workflows. - -### Formulas - -```bash -bd formula list # List available formulas -bd formula list --type=workflow # Filter by type -bd formula show # Show formula details -bd cook # Compile to proto (stdout) -bd cook --var name=auth # With variable substitution -bd cook --dry-run # Preview steps -bd cook --persist # Save to database -``` - -### Molecules: Pour vs Wisp - -| pour (persistent) | wisp (ephemeral) | -|-------------------|------------------| -| Feature implementations | Release workflows | -| Multi-session work | Patrol cycles | -| Audit trail needed | Health checks | -| Git-synced | Local only | - -```bash -# Persistent molecule (liquid phase) -bd mol pour --var name=auth - -# Ephemeral molecule (vapor phase) -bd mol wisp --var version=1.0 -bd mol wisp list # List wisps -bd mol wisp gc # Garbage collect -``` - -### Tracking Molecule Progress - -```bash -bd mol show # Show structure -bd mol show --parallel # Parallelizable steps -bd mol current # Where am I? -bd mol current # Status for molecule -bd mol progress # Progress summary + ETA -``` - -### Molecule Lifecycle - -```bash -bd mol squash # Condense to digest -bd mol burn # Delete wisp -bd mol distill # Extract formula from epic -``` - -## Gates and Human Checkpoints - -Gates are async wait conditions that block workflow steps: - -| Gate Type | Wait Condition | -|-----------|---------------| -| human | Manual `bd close` | -| timer | Timeout expires | -| gh:run | GitHub workflow completes | -| gh:pr | PR merges | -| bead | Cross-rig bead closes | - -```bash -bd gate list # Show open gates -bd gate list --all # Include closed -bd gate check # Evaluate all gates -bd gate check --type=bead # Check bead gates only -bd gate resolve # Close manually -``` - -## Common Patterns - -### Starting Work on a Bead - -```bash -bd update --status=in_progress -# ... do work ... -bd close -``` - -### Creating Related Issues - -```bash -bd create "Main task" --deps "blocks:" -bd dep add -``` - -### Working Through a Molecule - -```bash -bd mol pour my-workflow --var name=feature -bd ready --mol # Find next step -bd update --claim # Claim step -# ... do work ... -bd close --continue # Close and advance -``` - -### Quick Status Check - -```bash -bd ready -n 3 # Top 3 ready items -bd list -s in_progress # What's in flight? -bd blocked # What's stuck? -``` - -## Useful Flags - -| Flag | Effect | -|------|--------| -| `--json` | JSON output for scripting | -| `--quiet` | Suppress non-essential output | -| `--dry-run` | Preview without executing | -| `--pretty` | Tree format display | - -## Integration Notes - -- BD auto-syncs via daemon (check with `bd info`) -- Issues stored in `.beads/` directory -- JSONL files sync through git -- Use `bd doctor` if something seems wrong diff --git a/home/roles/development/skills/micro/artifact-format.md b/home/roles/development/skills/micro/artifact-format.md deleted file mode 100644 index d75bef9..0000000 --- a/home/roles/development/skills/micro/artifact-format.md +++ /dev/null @@ -1,123 +0,0 @@ ---- -description: How to structure research and plan artifacts in thoughts/ ---- - -# Artifact Format - -Standardized format for thoughts/ artifacts. All beads-related artifacts should follow these conventions for consistency and machine parseability. - -## Frontmatter (Required) - -Every artifact MUST include YAML frontmatter: - -```yaml ---- -date: 2026-01-15T10:00:00-08:00 # ISO 8601 with timezone -bead_id: project-abc # Bead identifier -bead_title: "Title of the bead" # Human-readable title -author: claude # Who created this -git_commit: abc123def # Commit hash at creation -branch: main # Branch name -repository: repo-name # Repository name -status: draft|complete # Artifact status ---- -``` - -### Gathering Metadata - -```bash -git rev-parse HEAD # Current commit -git branch --show-current # Current branch -basename $(git rev-parse --show-toplevel) # Repo name -date -Iseconds # ISO timestamp -``` - -## Research Artifact Structure - -Location: `thoughts/beads-{bead-id}/research.md` - -```markdown -# Research: {bead title} - -**Bead**: {bead-id} -**Date**: {timestamp} -**Git Commit**: {commit hash} - -## Research Question -{Original question from bead description} - -## Summary -{2-3 sentence overview answering the research question} - -## Key Discoveries -- {Finding with file:line reference} -- {Pattern or convention found} -- {Architectural decision documented} - -## Architecture -{Current patterns and conventions in the codebase} - -## Code References -- `path/to/file.py:123` - Description of relevance -- `another/file.ts:45-67` - Description of relevance - -## Open Questions -{Areas needing further investigation or human clarification} -``` - -## Plan Artifact Structure - -Location: `thoughts/beads-{bead-id}/plan.md` - -```markdown -# {Title} Implementation Plan - -## Overview -{What we're implementing and why - 1-2 sentences} - -## Current State -{What exists now, key constraints discovered} - -### Key Discoveries -- {Finding with file:line reference} -- {Pattern to follow} - -## Desired End State -{Specification of what success looks like} - -## What We're NOT Doing -{Explicitly list out-of-scope items} - -## Phase 1: {Descriptive Name} - -### Overview -{What this phase accomplishes} - -### Changes -- [ ] {Specific change with file path} -- [ ] {Another change} - -### Success Criteria - -#### Automated -- [ ] Tests pass: `{test command}` -- [ ] Lint passes: `{lint command}` - -#### Manual -- [ ] {Human verification step} - -## Phase 2: {Descriptive Name} -{Repeat structure...} - -## References -- Bead: {bead-id} -- Research: `thoughts/beads-{bead-id}/research.md` -``` - -## Key Principles - -1. **Always include file:line references** - Makes artifacts actionable -2. **Separate automated vs manual verification** - Enables agent autonomy -3. **Use checkboxes for phases** - Enables resumability after interruption -4. **Keep frontmatter machine-parseable** - Enables tooling integration -5. **Link related artifacts** - Research links to plan, plan links to bead diff --git a/home/roles/development/skills/micro/planning.md b/home/roles/development/skills/micro/planning.md deleted file mode 100644 index 210a596..0000000 --- a/home/roles/development/skills/micro/planning.md +++ /dev/null @@ -1,121 +0,0 @@ ---- -description: How to create effective implementation plans with phased delivery and clear success criteria ---- - -# Planning - -Create implementation plans that enable incremental, verifiable progress. - -## Core Principles - -1. **Incremental delivery**: Each phase should produce working, testable changes -2. **Clear checkpoints**: Success criteria that can be verified without ambiguity -3. **Buy-in before detail**: Confirm understanding and approach before writing specifics -4. **Explicit scope**: State what we're NOT doing to prevent scope creep - -## Plan Document Structure - -```markdown -# {Feature} Implementation Plan - -## Overview -{1-2 sentences: what we're building and why} - -## Current State Analysis -{What exists now, key constraints, file:line references} - -## Desired End State -{Specification of outcome and how to verify it} - -## What We're NOT Doing -{Explicit out-of-scope items} - -## Phase 1: {Descriptive Name} -### Overview -{What this phase accomplishes - should be independently valuable} - -### Changes Required -{Specific files and modifications with code snippets} - -### Success Criteria -#### Automated Verification -- [ ] Tests pass: `{test command}` -- [ ] Lint passes: `{lint command}` - -#### Manual Verification -- [ ] {Human-observable outcome} - -## Testing Strategy -{Unit tests, integration tests, manual testing steps} - -## References -{Links to research, related files, similar implementations} -``` - -## Phase Design - -Good phases are: -- **Self-contained**: Completable in one session -- **Testable**: Has clear pass/fail criteria -- **Reversible**: Can be rolled back if needed -- **Incremental**: Builds on previous phases without requiring all phases - -Bad phases are: -- "Refactor everything" (too broad) -- "Add helper function" (too granular) -- Phases that only work if ALL phases complete - -## Success Criteria Guidelines - -**Automated Verification** (agent-runnable): -- Test commands: `make test`, `npm test`, `nix flake check` -- Lint/format: `make lint`, `cargo fmt --check` -- Type checking: `make typecheck`, `tsc --noEmit` -- Build verification: `make build`, `nix build` - -**Manual Verification** (requires human): -- UI/UX functionality and appearance -- Performance under realistic conditions -- Edge cases hard to automate -- Integration with external systems - -**From Contribution Guidelines** (if CONTRIBUTING.md exists): -- Include any testing requirements specified -- Reference the guideline: "Per CONTRIBUTING.md: {requirement}" - -## Presenting Understanding - -Before writing the plan, confirm alignment: - -``` -Based on the requirements and my research, I understand we need to [summary]. - -I've found that: -- [Current implementation detail with file:line] -- [Relevant pattern or constraint] -- [Potential complexity identified] - -Questions my research couldn't answer: -- [Specific technical question requiring judgment] -``` - -Only ask questions you genuinely cannot answer through code investigation. - -## Design Options Pattern - -When multiple approaches exist: - -``` -**Design Options:** -1. [Option A] - [1-sentence description] - - Pro: [benefit] - - Con: [drawback] - -2. [Option B] - [1-sentence description] - - Pro: [benefit] - - Con: [drawback] - -Which approach aligns best with [relevant consideration]? -``` - -Get buy-in on approach before detailing phases. diff --git a/home/roles/development/skills/micro/pr-description.md b/home/roles/development/skills/micro/pr-description.md deleted file mode 100644 index c636a88..0000000 --- a/home/roles/development/skills/micro/pr-description.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -description: How to write comprehensive PR descriptions that help reviewers understand changes ---- - -# PR Description - -Write PR descriptions that help reviewers understand what changed and why. - -## Structure - -Use this standard structure for PR descriptions: - -```markdown -## Summary -<1-3 bullet points of what changed and why> - -## Context - - - -## Changes - -- Area 1: What changed and why -- Area 2: What changed and why - -## Testing - -- Automated: Tests added/updated, CI status -- Manual: Steps to verify functionality - -## Screenshots (if UI changes) - -``` - -## Guidelines - -### Lead with WHY, not WHAT -- The diff shows WHAT changed - your description explains WHY -- Start with the problem being solved -- Explain the approach chosen and alternatives considered - -### Link to context -- Reference related issues: `Fixes #123` or `Relates to #456` -- Link to design docs or discussions -- Mention dependent PRs if any - -### Call out review areas -- Highlight areas needing careful review -- Note any tricky or non-obvious code -- Point out architectural decisions - -### Note breaking changes prominently -- Use a dedicated "Breaking Changes" section if applicable -- Explain migration path for consumers -- List any deprecations - -### Be scannable -- Use bullet points over paragraphs -- Keep sections focused and concise -- Put the most important info first - -## Anti-patterns to Avoid - -- Empty descriptions or just "fixes bug" -- Repeating the commit messages verbatim -- Including irrelevant implementation details -- Missing context on why the change was made -- Forgetting to mention breaking changes diff --git a/home/roles/development/skills/micro/research-agents.md b/home/roles/development/skills/micro/research-agents.md deleted file mode 100644 index a57dd24..0000000 --- a/home/roles/development/skills/micro/research-agents.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -description: How to spawn and coordinate research sub-agents ---- - -# Research Agents - -Use parallel sub-agents for efficient codebase research. - -## Available Agents - -| Agent | Purpose | -|-------|---------| -| codebase-locator | Find WHERE files and components live | -| codebase-analyzer | Understand HOW specific code works | -| codebase-pattern-finder | Find examples of existing patterns | -| thoughts-locator | Discover relevant documents in thoughts/ | - -## Spawning Protocol - -1. **Decompose** - Break the research question into 3-5 specific questions -2. **Spawn parallel** - Use one Task call with multiple agents -3. **Be specific** - Include directories and file patterns in prompts -4. **Wait for all** - Do not synthesize until ALL agents complete -5. **Synthesize** - Combine findings into coherent summary with file:line references - -## Example - -``` -Task(codebase-locator, "Find all files related to authentication in src/") -Task(codebase-analyzer, "Explain how JWT tokens are validated in src/auth/") -Task(codebase-pattern-finder, "Find examples of middleware patterns in src/") -Task(thoughts-locator, "Find documents about auth design decisions in thoughts/") -``` - -## Key Principles - -- **Parallel when different** - Run agents in parallel when searching for different things -- **WHAT not HOW** - Each agent knows its job; tell it what you need, not how to search -- **Document, don't evaluate** - Agents should describe what exists, not critique it -- **Specific directories** - Always scope searches to relevant directories -- **File references** - Include specific file:line references in synthesis - -## Agent Prompts - -When spawning agents, include: -- The specific question or goal -- Relevant directories to search -- Reminder to document (not evaluate) what they find -- Request for file:line references in findings diff --git a/home/roles/emacs/doom/config.el b/home/roles/emacs/doom/config.el index e1cef06..3fb13ba 100644 --- a/home/roles/emacs/doom/config.el +++ b/home/roles/emacs/doom/config.el @@ -306,20 +306,6 @@ rbw is unavailable or the entry is not found." claude-code-ide-window-side 'right claude-code-ide-window-width 90)) -(use-package! beads - :commands (beads) - :init - (map! :leader - (:prefix ("o" . "open") - (:prefix ("B" . "beads") - :desc "List issues" "B" (cmd! (require 'beads) (beads-list)) - :desc "Project issues" "p" (cmd! (require 'beads) (beads-project-list)) - :desc "Activity feed" "a" (cmd! (require 'beads) (beads-activity)) - :desc "Stale issues" "s" (cmd! (require 'beads) (beads-stale)) - :desc "Orphaned issues" "o" (cmd! (require 'beads) (beads-orphans)) - :desc "Find duplicates" "d" (cmd! (require 'beads) (beads-duplicates)) - :desc "Lint issues" "l" (cmd! (require 'beads) (beads-lint)))))) - (after! gptel (require 'gptel-tool-library) (setq gptel-tool-library-use-maybe-safe t diff --git a/home/roles/emacs/doom/packages.el b/home/roles/emacs/doom/packages.el index 525bbc4..39821ea 100644 --- a/home/roles/emacs/doom/packages.el +++ b/home/roles/emacs/doom/packages.el @@ -68,11 +68,6 @@ :files ("*.el")) :pin "baffc3b0d74a2b7cbda0d5cd6dd7726d6ccaca83") -(package! beads - :recipe (:type git :repo "https://codeberg.org/ctietze/beads.el.git" - :files ("lisp/*.el")) - :pin "f40a6461d3c0fa0969311bbb6a1e30d1bba86c88") - (package! pi-coding-agent :recipe (:host github :repo "dnouri/pi-coding-agent" :files ("*.el")) diff --git a/packages/beads/default.nix b/packages/beads/default.nix deleted file mode 100644 index d92355b..0000000 --- a/packages/beads/default.nix +++ /dev/null @@ -1,26 +0,0 @@ -# Beads package - issue tracker for AI-supervised coding workflows -# Takes src as argument so it can be called from both overlay and flake packages -{ lib -, buildGoModule -, git -, pkg-config -, icu -, src -, version ? "unknown" -}: - -buildGoModule { - pname = "beads"; - inherit version src; - subPackages = [ "cmd/bd" ]; - doCheck = false; - vendorHash = "sha256-XAhe4yuLzP9vQ3IFhWAO5fN/3OOfokcRxfeGKaRYEws="; - nativeBuildInputs = [ git pkg-config ]; - buildInputs = [ icu ]; - meta = with lib; { - description = "beads (bd) - An issue tracker designed for AI-supervised coding workflows"; - homepage = "https://github.com/steveyegge/beads"; - license = licenses.mit; - mainProgram = "bd"; - }; -} diff --git a/packages/gastown/default.nix b/packages/gastown/default.nix deleted file mode 100644 index 76f571d..0000000 --- a/packages/gastown/default.nix +++ /dev/null @@ -1,31 +0,0 @@ -# Gastown package - multi-agent workspace manager -# Takes src as argument so it can be called from both overlay and flake packages -{ lib -, buildGoModule -, src -, version ? "unknown" -}: - -buildGoModule { - pname = "gastown"; - inherit version src; - vendorHash = "sha256-8SdvSASP+bJjMooqEQvkCzG+J6CbsK+HCQulrPnJZ1Y="; - subPackages = [ "cmd/gt" ]; - doCheck = false; - - # Must match ldflags from gastown Makefile - BuiltProperly=1 is required - # or gt will error with "This binary was built with 'go build' directly" - ldflags = [ - "-X github.com/steveyegge/gastown/internal/cmd.Version=${version}" - "-X github.com/steveyegge/gastown/internal/cmd.Commit=${version}" - "-X github.com/steveyegge/gastown/internal/cmd.BuildTime=nix-build" - "-X github.com/steveyegge/gastown/internal/cmd.BuiltProperly=1" - ]; - - meta = with lib; { - description = "Gas Town - multi-agent workspace manager by Steve Yegge"; - homepage = "https://github.com/steveyegge/gastown"; - license = licenses.mit; - mainProgram = "gt"; - }; -} diff --git a/packages/perles/default.nix b/packages/perles/default.nix deleted file mode 100644 index b4633ba..0000000 --- a/packages/perles/default.nix +++ /dev/null @@ -1,25 +0,0 @@ -# Perles - Terminal UI for beads issue tracking -# Takes src as argument so it can be called from both overlay and flake packages -{ lib -, buildGoModule -, src -, version ? "unknown" -}: - -buildGoModule { - pname = "perles"; - inherit version src; - doCheck = false; - vendorHash = "sha256-A5LE9Cor/DRcJtVpiScSoqDYhJIKyaq0cbK+OGmr4XU="; - - ldflags = [ - "-X main.version=${version}" - ]; - - meta = with lib; { - description = "Perles - Terminal UI for beads issue tracking"; - homepage = "https://github.com/zjrosen/perles"; - license = licenses.mit; - mainProgram = "perles"; - }; -} diff --git a/renovate.json b/renovate.json index 9a945d3..7ee432a 100644 --- a/renovate.json +++ b/renovate.json @@ -77,32 +77,6 @@ "matchPackageNames": [ "/google-cookie-retrieval/" ] - }, - { - "description": "Gastown is under active development - check for updates daily", - "matchManagers": [ - "nix" - ], - "matchPackageNames": [ - "/gastown/" - ], - "schedule": [ - "before 6am" - ], - "automerge": false - }, - { - "description": "Beads is under active development - check for updates daily", - "matchManagers": [ - "nix" - ], - "matchPackageNames": [ - "/beads/" - ], - "schedule": [ - "before 6am" - ], - "automerge": false } ] }