feat(skills): Add validation status to parallel_beads PR descriptions

Enhances the parallel_beads workflow to capture and report validation status:

- Add step 3 to extract validation criteria from plans or use best-effort
  fallbacks (make test, nix flake check, npm test)
- Update step 4 to run validation and track PASS/FAIL/SKIP results
- Add Validation section with table to PR body templates (gh and tea)
- Enhance result reporting to include validation summary
- Add Validation column and Validation Failures section to summary table

Implements bead: nixos-configs-39m

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

AGENTS.md

@@ -6,6 +6,10 @@ 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

home/home-server.nix

@@ -11,6 +11,7 @@
     base.enable = true;
     development.enable = true;
     emacs.enable = true;
+    kubectl.enable = true;
     starship.enable = true;
     tmux.enable = true;
   };

home/roles/base-linux/default.nix

@@ -3,6 +3,7 @@
   # Includes Linux-specific roles that require Linux-only home-manager modules
   imports = [
     ../plasma-manager
+    ../plasma-manager-kodi
     ../i3+sway
   ];
 }

home/roles/default.nix

@@ -15,7 +15,6 @@
     ./launchers
     ./media
     ./office
-    ./plasma-manager-kodi
     ./sync
     ./tmux
     ./emacs

home/roles/development/default.nix

@@ -44,7 +44,6 @@ in
 
       # Custom packages
       pkgs.custom.tea-rbw
-      pkgs.custom.perles
     ];
 
     # Install Claude Code humanlayer command and agent plugins

home/roles/development/skills/beads_implement.md

@@ -0,0 +1,218 @@
+---
+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 and plan context**:
+   ```bash
+   bd show {bead-id}
+   ```
+   - 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`
+
+3. **Mark bead in progress** (if not already):
+   ```bash
+   bd update {bead-id} --status=in_progress
+   ```
+
+4. **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.
+```
+
+**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...
+```

home/roles/development/skills/beads_iterate.md

@@ -0,0 +1,214 @@
+---
+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...
+```

home/roles/development/skills/beads_plan.md

@@ -0,0 +1,281 @@
+---
+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. **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
+
+3. **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
+
+## Example Invocation
+
+```
+User: /beads:plan nixos-configs-abc123
+Assistant: Creating implementation plan for bead nixos-configs-abc123...
+```

home/roles/development/skills/beads_research.md

@@ -0,0 +1,206 @@
+---
+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 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}
+
+## 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?
+```

home/roles/development/skills/beads_workflow.md

@@ -0,0 +1,337 @@
+---
+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 <files>               # 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

home/roles/development/skills/parallel_beads.md

@@ -41,17 +41,41 @@ Work on bead [BEAD_ID]: [BEAD_TITLE]
    - Run `bd show [BEAD_ID]` to understand the acceptance criteria
    - Note any external issue references (GitHub issues, Linear tickets, etc.)
 
-3. **Implement the changes**:
+3. **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`
+   - 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`
+     - If none found, note "No validation criteria found"
+
+4. **Implement the changes**:
    - Work in the worktree directory
    - Complete all acceptance criteria listed in the bead
-   - Run any relevant tests or checks
 
-4. **Commit and push**:
+   After implementation, run validation:
+   - Execute each validation command from step 3
+   - 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 (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]"`
+
+5. **Commit and push**:
    - Stage all changes: `git add -A`
    - Create a descriptive commit message
    - Push the branch: `git push -u origin bead/[BEAD_ID]`
 
-5. **Create a PR**:
+6. **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]"
@@ -73,6 +97,15 @@ Work on bead [BEAD_ID]: [BEAD_TITLE]
 
      ## Changes
      - [List of changes made]
+
+     ## Validation
+     [Include validation results from step 4]
+
+     | Check | Status | Details |
+     |-------|--------|---------|
+     | make test | PASS | |
+     | make lint | FAIL | src/foo.ts:23 - missing semicolon |
+     | nix flake check | SKIP | command not found |
      EOF
      )"
      ```
@@ -90,18 +123,33 @@ Work on bead [BEAD_ID]: [BEAD_TITLE]
      [Any linked issues from the bead]
 
      ## Changes
-     - [List of changes made]"
+     - [List of changes made]
+
+     ## Validation
+     [Include validation results from step 4]
+
+     | Check | Status | Details |
+     |-------|--------|---------|
+     | make test | PASS | |
+     | make lint | FAIL | src/foo.ts:23 - missing semicolon |
+     | nix flake check | SKIP | command not found |"
      ```
 
-6. **Update bead status**:
+7. **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]"`
 
-7. **Report results**:
+8. **Report results**:
-   - Return: PR URL, bead ID, success/failure status
+   - Return:
+     - PR URL
+     - Bead ID
+     - Implementation status (success/failure/blocked)
+     - Validation summary: `X passed, Y failed, Z skipped`
+     - List of any validation failures 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
@@ -164,23 +212,30 @@ After reviews complete:
    - 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 | Review |
+| Bead | PR | Bead Status | Validation | Review |
-|------|-----|-------------|--------|
+|------|-----|-------------|------------|--------|
-| beads-abc | #123 | in_review | Approved |
+| beads-abc | #123 | in_review | 3/3 passed | Approved |
-| beads-xyz | #124 | in_review | Needs changes |
+| beads-xyz | #124 | in_review | 2/3 passed | Needs changes |
-| beads-123 | - | open (failed) | Blocked by missing dependency |
+| 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

home/roles/emacs/doom/config.el

@@ -167,6 +167,20 @@
         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

machines/boxy/configuration.nix

@@ -26,6 +26,7 @@ with lib;
       enable = true;
       autologin = true;
       wayland = true;
+      appLauncherServer = true;
       jellyfinScaleFactor = 1.0;
     };
     nfs-mounts.enable = true;

machines/john-endesktop/configuration.nix

@@ -104,6 +104,23 @@ with lib;
   # User configuration
   roles.users.enable = true;
 
+  # k3s agent configuration
+  roles.k3s-node = {
+    enable = true;
+    role = "agent";
+    # serverAddr defaults to https://10.0.0.222:6443
+    # tokenFile defaults to /etc/k3s/token
+    extraFlags = [
+      # Node labels for workload scheduling
+      # fast-cpu: This node has a faster CPU than other cluster nodes
+      "--node-label=fast-cpu=true"
+      # fast-storage: This node is the NFS host with fast local storage access
+      "--node-label=fast-storage=true"
+      # k3s-upgrade=disabled: NixOS manages k3s upgrades via Nix, not system-upgrade-controller
+      "--node-label=k3s-upgrade=disabled"
+    ];
+  };
+
   # Time zone
   time.timeZone = "America/Los_Angeles"; # Adjust as needed
 

machines/nix-book/configuration.nix

@@ -41,14 +41,9 @@
   boot.initrd.luks.devices."luks-b614167b-9045-4234-a441-ac6f60a96d81".device = "/dev/disk/by-uuid/b614167b-9045-4234-a441-ac6f60a96d81";
 
   services.logind.settings.Login = {
-    HandleLidSwitch = "suspend-then-hibernate";
     HandlePowerKey = "hibernate";
     HandlePowerKeyLongPress = "poweroff";
   };
-  systemd.sleep.extraConfig = ''
-    HibernateDelaySec=30m
-    SuspendState=mem
-  '';
 
   networking.hostName = "nix-book"; # Define your hostname.
   # networking.wireless.enable = true;  # Enables wireless support via wpa_supplicant.

machines/zix790prors/configuration.nix

@@ -25,6 +25,7 @@ with lib;
       wayland = true;
       x11 = true;
     };
+    kodi.enable = true;
     nfs-mounts.enable = true;
     nvidia = {
       enable = true;

packages/default.nix

@@ -3,5 +3,4 @@
   tea-rbw = pkgs.callPackage ./tea-rbw {};
   app-launcher-server = pkgs.callPackage ./app-launcher-server {};
   claude-code = pkgs.callPackage ./claude-code {};
-  perles = pkgs.callPackage ./perles {};
 }

packages/perles/default.nix

@@ -1,26 +0,0 @@
-{ lib, buildGoModule, fetchFromGitHub }:
-
-buildGoModule rec {
-  pname = "perles";
-  version = "unstable-2025-01-09";
-
-  src = fetchFromGitHub {
-    owner = "zjrosen";
-    repo = "perles";
-    rev = "main";
-    hash = "sha256-JgRayb4+mJ1r0AtdnQfqAw2+QRte+licsfZOaRgYqcs=";
-  };
-
-  vendorHash = "sha256-R7UWTdBuPteneRqxrWK51nqLtZwDsqQoMAcohN4fyak=";
-
-  # Tests require a real git repository context
-  doCheck = false;
-
-  meta = with lib; {
-    description = "A TUI for the Beads issue tracking system with BQL query language";
-    homepage = "https://github.com/zjrosen/perles";
-    license = licenses.mit;
-    maintainers = [ ];
-    mainProgram = "perles";
-  };
-}

roles/default.nix

@@ -9,6 +9,7 @@ with lib;
     ./bluetooth
     ./btrfs
     ./desktop
+    ./k3s-node
     ./kodi
     ./nfs-mounts
     ./nvidia

roles/k3s-node/default.nix

@@ -0,0 +1,81 @@
+{ lib, config, pkgs, ... }:
+
+with lib;
+
+let
+  cfg = config.roles.k3s-node;
+in
+{
+  options.roles.k3s-node = {
+    enable = mkEnableOption "Enable k3s node";
+
+    role = mkOption {
+      type = types.enum [ "server" "agent" ];
+      default = "agent";
+      description = "k3s role: server (control plane) or agent (worker)";
+    };
+
+    serverAddr = mkOption {
+      type = types.str;
+      default = "https://10.0.0.222:6443";
+      description = "URL of k3s server to join (required for agents, used for HA servers)";
+    };
+
+    tokenFile = mkOption {
+      type = types.path;
+      default = "/etc/k3s/token";
+      description = "Path to file containing the cluster join token";
+    };
+
+    clusterInit = mkOption {
+      type = types.bool;
+      default = false;
+      description = "Initialize a new cluster (first server only)";
+    };
+
+    extraFlags = mkOption {
+      type = types.listOf types.str;
+      default = [];
+      description = "Additional flags to pass to k3s";
+    };
+
+    gracefulNodeShutdown = mkOption {
+      type = types.bool;
+      default = true;
+      description = "Enable graceful node shutdown";
+    };
+
+    openFirewall = mkOption {
+      type = types.bool;
+      default = true;
+      description = "Open firewall ports for k3s";
+    };
+  };
+
+  config = mkIf cfg.enable {
+    # k3s service configuration
+    services.k3s = {
+      enable = true;
+      role = cfg.role;
+      tokenFile = cfg.tokenFile;
+      extraFlags = cfg.extraFlags;
+      gracefulNodeShutdown.enable = cfg.gracefulNodeShutdown;
+      serverAddr = if (cfg.role == "agent" || !cfg.clusterInit) then cfg.serverAddr else "";
+      clusterInit = cfg.role == "server" && cfg.clusterInit;
+    };
+
+    # Firewall rules for k3s
+    networking.firewall = mkIf cfg.openFirewall {
+      allowedTCPPorts = [
+        6443  # k3s API server
+        10250 # kubelet metrics
+      ] ++ optionals (cfg.role == "server") [
+        2379  # etcd clients (HA)
+        2380  # etcd peers (HA)
+      ];
+      allowedUDPPorts = [
+        8472  # flannel VXLAN
+      ];
+    };
+  };
+}

roles/kodi/default.nix

@@ -22,7 +22,7 @@ in
     appLauncherServer = {
       enable = mkOption {
         type = types.bool;
-        default = true;
+        default = false;
         description = "Enable HTTP app launcher server for remote control";
       };
       port = mkOption {