feat: Add missing permissions and workflow documentation

[evansenter]

Summary

• Add git pull, git merge permissions to settings.json for branch management
• Add gh run view/list/rerun/watch permissions for CI monitoring workflows
• Add "When to use MCP vs gh CLI" guidance to clarify usage patterns
• Add step 9 (merge & cleanup) to Development Flow referencing clean_gone
• Document /commit-commands:clean_gone in Custom Commands section

Closes #26

Test plan

• Run ./bootstrap.sh -f after merge to apply new permissions
• Verify git pull and git merge work without prompts
• Verify gh run commands work without prompts

🤖 Generated with Claude Code

[claude]

Code Review

This PR makes targeted improvements to autonomous workflow permissions and documentation. Overall excellent work - the changes are focused, well-motivated, and aligned with the dotfiles architecture. A few observations below:

✅ Strengths

1. Well-scoped changes: Each addition directly addresses real workflow friction identified in issue Add missing permissions and /clean-branches command #26
2. Consistent with architecture: Permissions follow existing patterns in settings.json
3. Documentation sync: CLAUDE.md accurately reflects the new settings.json permissions
4. Practical guidance: The "When to use MCP vs gh CLI" section adds valuable decision-making criteria

📝 Observations & Suggestions

1. Command naming discrepancy (Minor)

• PR body references /commit-commands:clean_gone
• Issue Add missing permissions and /clean-branches command #26 originally proposed /clean-branches
• The commit-commands plugin approach is better (reuses existing infrastructure), but the naming divergence from the issue should be noted
• Suggestion: Update issue Add missing permissions and /clean-branches command #26 with a comment explaining the implementation choice before closing

2. git pull + git merge permissions (Worth discussing)

The new permissions enable both git pull and git merge:

"Bash(git pull:*)",
"Bash(git merge:*)"

Consideration: git pull is essentially git fetch + git merge, so both permissions together enable autonomous local branch merging. This is powerful but deviates from the documented preference in CLAUDE.md which states "Merging PRs" requires discussion (home/.claude/CLAUDE.md:27).

• If this is intentional (local merges != PR merges), that is fine
• If not, consider whether git pull alone is sufficient for the "updating local after PR merge" use case from issue Add missing permissions and /clean-branches command #26

3. MCP vs CLI guidance placement (Organizational)

The new section (home/.claude/CLAUDE.md:53-55) is well-written but interrupts the flow between "Allowed Permissions" and "Quality Gates". Consider:

• Moving it to a new "## Tool Selection" section after "Quality Gates"
• Or creating a "### Usage Notes" subsection under "Allowed Permissions"

This would improve scanability when users are looking for permission lists vs. usage guidance.

4. Test plan completeness

The test plan focuses on permission verification but does not explicitly test the documented workflow:

• Step 9 in Development Flow references clean_gone but no test validates this workflow step
• Suggestion: Add test item: "After merging a test PR, verify /commit-commands:clean_gone successfully cleans the feature branch"

🔒 Security & Safety

✅ No security concerns - all permissions are scoped to git/gh CLI with wildcards on arguments (not commands), which is appropriate for the use case.

🧪 Test Coverage

The PR modifies configuration files (JSON + Markdown docs) which do not have traditional unit tests. The test plan approach is appropriate:

• ✅ Bootstrap verification ensures symlinks work
• ✅ Permission validation ensures no approval prompts
• ⚠️ Missing: workflow validation for the clean_gone integration

📊 Performance

✅ No performance impact - configuration changes only

Summary

This is a well-executed PR that directly addresses documented pain points. The only substantive consideration is whether git merge permission aligns with the "Merging PRs" discussion requirement (likely they are orthogonal, but worth confirming).

Recommendation: Approve with optional consideration of the merge permission scope.

[claude]

PR Review: feat: Add missing permissions and workflow documentation

Summary

This PR adds practical permissions and workflow improvements based on real usage patterns from PR #25. The changes are well-scoped and address concrete friction points.

---

✅ Strengths

1. Well-grounded changes

• All additions stem from actual workflow pain points (referenced in Add missing permissions and /clean-branches command #26)
• Permissions align with documented autonomous operations in CLAUDE.md

2. Good documentation hygiene

• Clarifies MCP vs gh CLI usage patterns (lines 53-55)
• Disambiguates gh pr merge vs local git merge (line 27)
• Documents the new /commit-commands:clean_gone command (line 127)

3. Workflow completeness

• Step 9 in Development Flow addresses post-merge cleanup (line 74)
• CI permissions (gh run) enable the auto-rerun behavior documented at line 104

---

🔍 Code Quality

settings.json changes (lines 21-22, 35-38)

• ✅ Follows existing permission pattern: Bash(command:*)
• ✅ Alphabetically ordered within git/gh groups
• ✅ Consistent with CLAUDE.md documentation

CLAUDE.md changes

• ✅ Clarifications enhance precision without bloat
• ✅ New guidance section ("When to use MCP vs gh CLI") prevents confusion
• ✅ Development Flow step 9 references the correct command name

---

💡 Suggestions

1. Minor: Permission scope consideration

The git pull and git merge permissions grant broad autonomy. While aligned with the workflow, consider:

• Risk: git merge could theoretically merge any branch without user awareness
• Mitigation: The CLAUDE.md already states "Merging PRs (GitHub PR merges via gh pr merge, not local git merge)" requires discussion (line 27), which provides guidance but not enforcement
• Recommendation: Consider if you want to add a comment in settings.json clarifying intended use

2. Minor: MCP guidance could be more specific

Line 54-55 says "Prefer MCP for standard operations (faster, structured data)" but doesn't explain why it's faster. Consider adding more detail about the performance characteristics.

3. Observation: Test plan relies on manual verification

The test plan in the PR body requires manual testing after merge. This is appropriate for configuration changes, but you could enhance it by adding a verification date comment in settings.json.

---

🐛 Potential Issues

None identified. The changes are low-risk configuration and documentation updates.

---

🔒 Security Considerations

Low risk, but worth noting:

1. Expanded git autonomy: git pull and git merge permissions allow Claude to modify local branches autonomously. This is acceptable given:

   • Changes are local only (not pushed without user intent)
   • Workflow context is primarily feature branches
   • Git's reflog provides recovery mechanisms

2. CI rerun permissions: gh run rerun could theoretically spam CI, but:

   • CLAUDE.md limits it to "once per failure" (line 104)
   • GitHub's rate limits provide backstop
   • Workflow context makes abuse unlikely

Recommendation: ✅ Acceptable as-is given the workflow guardrails.

---

📊 Test Coverage

Not applicable - Configuration and documentation changes don't require automated tests. The test plan in the PR body appropriately covers manual verification.

---

🎯 Final Assessment

Verdict: LGTM with minor suggestions

This is a clean, focused PR that reduces workflow friction. The changes are:

• ✅ Well-motivated by real usage
• ✅ Properly documented
• ✅ Consistent with existing patterns
• ✅ Low-risk

Action items before merge:

1. ✅ None blocking
2. 💭 Optional: Consider the permission scope comment suggestion
3. 💭 Optional: Enhance MCP guidance clarity

After merge:

• Run ./bootstrap.sh -f to apply the new settings (as noted in test plan)
• Verify the permissions work as expected during next workflow

---

📝 Diff Review

home/.claude/CLAUDE.md:

• Line 27: ✅ Good clarification on merge types
• Line 41: ✅ Logical permission additions
• Line 46: ✅ New CI permissions align with line 104 auto-rerun workflow
• Line 53-55: ✅ Helpful MCP vs CLI guidance
• Line 74: ✅ Completes the workflow loop
• Line 127: ✅ Documents the new command

home/.claude/settings.json:

• Lines 21-22: ✅ git pull/merge permissions
• Lines 35-38: ✅ gh run permissions

All changes are internally consistent and align with the stated goals in #26.

---

Great work! This PR demonstrates good workflow introspection and continuous improvement. 🚀