feat(skills): Add contribution guidelines check to beads skills

home/roles/development/skills/beads_implement.md

@@ -54,6 +54,8 @@ When this command is invoked:
    - 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
@@ -127,6 +129,10 @@ All phases completed and automated verification passed:
 - {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.**

home/roles/development/skills/beads_plan.md

@@ -51,13 +51,32 @@ When this command is invoked:
    - Any linked tickets or docs
    - Use Read tool WITHOUT limit/offset
 
-2. **Spawn initial research tasks**:
+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
 
-3. **Read all files identified by research**:
+4. **Read all files identified by research**:
    - Read them FULLY into main context
    - Cross-reference with requirements
 
@@ -273,6 +292,12 @@ Always separate into two categories:
 - 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
 
 ```

home/roles/development/skills/beads_research.md

@@ -51,6 +51,18 @@ When this command is invoked:
 - 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
@@ -143,6 +155,10 @@ status: complete
 ## 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}
 

home/roles/development/skills/parallel_beads.md

@@ -42,46 +42,7 @@ AskUserQuestion with:
 - options from filtered bd ready output
 ```
 
-## Phase 2: Worktree Setup
+## Phase 2: Parallel Implementation
-
-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).
 
@@ -92,60 +53,35 @@ Each implementation subagent should receive these instructions:
 ```
 Work on bead [BEAD_ID]: [BEAD_TITLE]
 
-Worktree path: [WORKTREE_PATH]
+1. **Create worktree**:
+   - Branch name: `bead/[BEAD_ID]`
+   - Worktree path: `~/wt/[REPO_NAME]/[BEAD_ID]`
+   - Command: `git worktree add -b bead/[BEAD_ID] ~/wt/[REPO_NAME]/[BEAD_ID]`
 
-## CRITICAL: Branch Verification (MUST DO FIRST)
+2. **Review the bead requirements**:
-
-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**:
+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`
+     - Note any "Per CONTRIBUTING.md:" requirements for additional validation
    - 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
      - If none found, note "No validation criteria found"
 
-5. **Implement the changes**:
+4. **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
+   - Execute each validation command from step 3
    - Track results in this format:
      ```
      VALIDATION_RESULTS:
@@ -157,12 +93,12 @@ Worktree path: [WORKTREE_PATH]
      - Continue with PR creation (don't block)
      - Document failures in bead notes: `bd update [BEAD_ID] --notes="Validation failures: [list]"`
 
-6. **Commit and push**:
+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]`
 
-7. **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]"
@@ -222,13 +158,13 @@ Worktree path: [WORKTREE_PATH]
      | nix flake check | SKIP | command not found |"
      ```
 
-8. **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]"`
 
-9. **Report results**:
+8. **Report results**:
    - Return:
      - PR URL
      - Bead ID
@@ -241,24 +177,15 @@ PR: [PR_URL]"`
 
 ### 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:
 
 ```
 <Task calls for each selected bead - all in one message>
 ```
 
-**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
+## Phase 3: Parallel Review
 
 After all implementation subagents complete, launch review subagents for each PR.
 
@@ -293,7 +220,7 @@ Review PR for bead [BEAD_ID]
 
 Launch all review subagents in parallel.
 
-## Phase 5: Cleanup and Summary
+## Phase 4: Cleanup and Summary
 
 After reviews complete:
 
@@ -339,21 +266,9 @@ Example output:
 
 ## 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
+- **Worktree conflicts**: If a worktree already exists, ask the user if they want to remove it or skip that bead
 
 ## Resource Limits