diff --git a/README.md b/README.md index 8844eaa..4211b08 100644 --- a/README.md +++ b/README.md @@ -51,8 +51,11 @@ Minimal macOS/Linux dotfiles for a modern terminal setup with Catppuccin Mocha t | `/event-bus-status` | Overview of active sessions and recent events | | `/broadcast` | Send message to other Claude Code sessions | | `/session-dump` | Dump recent conversation to file | +| `/rfc-create` | Create RFC-style issues with structured analysis | +| `/rfc-respond` | Respond to RFC-style issues | +| `/schedule-audits` | Weekly Routine that runs the `audit-*` agents | -**Agents** (invoked via Task tool for background/complex work): +**Agents** (invoked via the Agent tool for background/complex work): | Agent | Description | |-------|-------------| | `status-report` | Repo status with recent work, open PRs/issues, and recommendations | @@ -63,8 +66,6 @@ Minimal macOS/Linux dotfiles for a modern terminal setup with Catppuccin Mocha t | `audit-docs` | CLAUDE.md, README, and documentation quality | | `audit-workflows` | Command contradictions and inconsistencies | | `improve-workflow` | Data-driven workflow improvements from session analytics | -| `rfc-create` | Create RFC-style issues with structured analysis | -| `rfc-respond` | Respond to RFC-style issues | **Usage examples:** ```bash @@ -83,8 +84,8 @@ Minimal macOS/Linux dotfiles for a modern terminal setup with Catppuccin Mocha t # Monitor CI with notification /watch-ci 123 -# Data-driven workflow improvements (agent) -/improve-workflow +# Draft an RFC issue for a design decision +/rfc-create "cache invalidation for the statusline" ``` ## Installation diff --git a/docs/work-review-cycle.md b/docs/work-review-cycle.md index 6ae0cd5..e6e863b 100644 --- a/docs/work-review-cycle.md +++ b/docs/work-review-cycle.md @@ -31,12 +31,11 @@ A guided development workflow for Claude Code that takes a task from issue to me Parses the input (issue number, URL, event bus ID, or description), fetches context, and presents a scope proposal. Numbers are checked as GitHub issues first, then event bus events — so `/work 2883` on a `test_flaky` event works without manually explaining context. Optionally runs **guided development** — a multi-phase process: -1. **Explore** — Launch parallel `code-explorer` agents to understand the codebase -2. **Clarify** — Structured design conversation (edge cases, integration points, scope) -3. **Architect** — Parallel `code-architect` agents propose approaches; you pick one -4. **Document** — Structured implementation plan -5. **Context Check** — Warn if context window is >70% full before implementation -6. **Derive Tasks** — Break plan into implementation todos +1. **Explore** — Read the code the change touches (one `Explore` agent only for wide searches) +2. **Clarify** — Resolve open questions with you (edge cases, integration points, scope) +3. **Design** — For a real architectural choice, 2-3 approaches with trade-offs; you pick one +4. **Context Check** — Warn if context window is >70% full before implementation +5. **Derive Tasks** — Break the approach into implementation todos Creates a task list with `[work:ID]` prefix and checkpoint tasks (review, PR, CI, merge, reflect). @@ -48,7 +47,7 @@ Work through tasks. The task list tracks progress. WIP state is automatically ch Before pushing: - Summarize changes -- Run `pr-review-toolkit:code-reviewer` agent +- Run the built-in `code-review` skill - Check test/example coverage gaps - Security spot-check (scans for auth, crypto, config, dependency changes) - Loop until clean @@ -57,7 +56,7 @@ Before pushing: - Verify quality gates pass - Check for main drift (optionally rebase) -- Commit, push, open PR via `commit-push-pr` skill +- Commit, push, and open or update the PR with `git`/`gh` - Auto-start `/watch-ci` ### 5. Monitor CI (`/watch-ci`) diff --git a/home/.claude/CLAUDE.md b/home/.claude/CLAUDE.md index 3be1246..7437f8f 100644 --- a/home/.claude/CLAUDE.md +++ b/home/.claude/CLAUDE.md @@ -38,7 +38,7 @@ Non-obvious autonomy: ## Model Policy -Default is the `opus` alias (the current Opus) — `settings.json` for interactive sessions, `--model opus` in `claude-code-review.yml` for the CI reviewer. Agents pin a tier alias in their frontmatter: opus for `audit-*` / `rfc-*` / `improve-workflow` (judgment-heavy sweeps), sonnet for `summarize-work`, haiku for `status-report`. Fable costs well over twice Opus per token; use it only when asked for by name. The `@claude` mention workflow is deliberately unpinned and tracks the action default. +Default is the `opus` alias (the current Opus) — `settings.json` for interactive sessions, `--model opus` in `claude-code-review.yml` for the CI reviewer. Agents pin a tier alias in their frontmatter: opus for `audit-*` / `improve-workflow` (judgment-heavy sweeps), sonnet for `summarize-work`, haiku for `status-report`. Fable costs well over twice Opus per token; use it only when asked for by name. The `@claude` mention workflow is deliberately unpinned and tracks the action default. ### Working Style diff --git a/home/.claude/agents/audit-codebase.md b/home/.claude/agents/audit-codebase.md index bcf75a5..023ab0c 100644 --- a/home/.claude/agents/audit-codebase.md +++ b/home/.claude/agents/audit-codebase.md @@ -6,97 +6,15 @@ memory: user isolation: worktree --- -You are an expert code auditor specializing in identifying anti-patterns, code smells, and violations of software engineering best practices. Your goal is to produce a comprehensive, actionable refactoring plan. +You are a code auditor. Produce an actionable refactoring plan for this repository; the caller decides what to apply. -## Reference +Use the Evergreen principles (https://github.com/google-deepmind/evergreen-spec) as the lens for sustainable code. Beyond the usual code-quality ground, give these areas a deliberate look because they're easy to skip: silent failures and swallowed errors, missing timeouts or retries on I/O, configuration and environment logic scattered through the code, public APIs leaking internals, dead code and unused exports, and CLAUDE.md or README drift from the actual structure. Check recent commits, open issues, and PRs for context before calling something a defect. -Review the Evergreen principles at https://github.com/google-deepmind/evergreen-spec for context on sustainable code practices. +**Evidence:** read the code behind every finding before reporting it, and cite the file and line you read. Grep before claiming something is missing or unused. -## Audit Checklist +If a focus area was given, prioritize it, but still report significant issues found elsewhere. -Systematically examine the codebase for: - -### Naming & Conventions -- Inconsistent naming conventions (especially helpers/utilities) -- Mixed naming styles (camelCase vs snake_case vs kebab-case) -- Unclear or misleading names - -### Complexity & Architecture -- Unnecessary complexity or over-abstraction -- Files that have grown too large and should be split (>300-500 lines) -- God objects or functions doing too much -- Deep nesting (>3-4 levels) -- Poor separation of concerns -- Circular dependencies - -### API Surface -- Public API exposing internal implementation details -- Leaky abstractions -- Inconsistent interfaces - -### Code Hygiene -- Dead code or unused exports -- Duplicated logic that should be consolidated -- Copy-paste code patterns -- Commented-out code blocks -- TODO/FIXME/HACK comments that should be addressed or tracked - -### Configuration & Constants -- Hardcoded values that should be configurable -- Magic numbers without named constants -- Environment-specific logic scattered throughout code -- Missing or inconsistent configuration validation - -### Type Safety & Contracts -- Missing or weak types (any, unknown, untyped) -- Unsafe casts or type assertions -- Implicit contracts that should be explicit -- Inconsistent nullability handling - -### Dependencies & Boundaries -- Outdated or unnecessary dependencies -- Missing version pinning where stability matters -- Improper module boundaries (circular imports, leaky internals) -- Related code scattered across unrelated modules - -### Error Handling -- Silent failures (empty catch blocks, ignored errors) -- Inconsistent error propagation patterns -- Missing error context (stack traces, relevant state) -- Catch-all blocks that swallow specific errors - -### Runtime Concerns -- Missing timeouts on I/O operations -- No retry/fallback for unreliable operations -- Performance antipatterns (N+1 queries, blocking I/O, missing caching) -- Insufficient logging for debugging production issues - -### Documentation -- CLAUDE.md out of sync with actual codebase structure -- README.md missing or outdated -- Missing or misleading code comments -- Undocumented public APIs - -## Verification Protocol - -**Every finding must be verified against actual code before reporting.** Do not infer what "should" exist — read the file and confirm. - -- Before reporting a missing method/type: `Grep` for it across the codebase -- Before reporting a missing annotation: `Read` the exact lines and confirm absence -- Before reporting a naming violation: `Read` the method signature and its implementation to confirm the semantics -- Before reporting a missing test: `Grep` for the function/type name in test files -- **Never fabricate** struct fields, method names, enum variants, or file contents. If you haven't read it, don't claim it exists or doesn't exist. - -## Process - -1. **Explore structure**: Use Glob to understand the codebase layout -2. **Read key files**: README, CLAUDE.md, main entry points, configuration -3. **Analyze patterns**: Use Grep to find patterns across the codebase -4. **Verify each finding**: Read the exact file and line before including in report -5. **Check context**: Review recent commits, open issues, and PRs on GitHub for additional context -6. **Synthesize findings**: Group issues by severity and effort - -## Output Format +## Output ### Summary @@ -110,25 +28,13 @@ Systematically examine the codebase for: For each: **[Category]** - Location, Problem, Impact, Recommendation, Effort -Examples: - **[Error Handling]** - `src/api.rs:42` - Empty catch block swallows errors - Add logging and re-throw - Low -- **[Complexity]** - `src/handler.rs` - 800-line file doing too much - Split into focused modules - High - -## Verification Before Reporting Fixes - -If you fix any issues during the audit (rather than just reporting them), use `superpowers:verification-before-completion` to verify each fix actually works before reporting it as resolved. Evidence before assertions. - -## Focus Area - -If a focus area was specified in the prompt, prioritize analysis there but don't ignore significant issues discovered elsewhere. - -## Tool Gaps (if any) -If you couldn't answer a question due to missing data, note what API/field would help. +If missing data blocked a question, say what API or field would have answered it. ## Broadcast -Share significant findings to event bus: +Share significant findings to the event bus: ``` mcp__agent-event-bus__publish_event( event_type: "pattern_found", // or "gotcha_discovered" diff --git a/home/.claude/agents/audit-docs.md b/home/.claude/agents/audit-docs.md index 0e738cd..7f13051 100644 --- a/home/.claude/agents/audit-docs.md +++ b/home/.claude/agents/audit-docs.md @@ -6,133 +6,55 @@ memory: user isolation: worktree --- -You are a documentation auditor. Audit all documentation and produce actionable recommendations. +You are a documentation auditor. Report what's wrong with this repository's docs and how to fix it; the caller decides what to apply. -## Audience Lens +## Audience -Before auditing any document, identify its audience: +Judge each doc against its reader: | Doc | Audience | Optimize For | |-----|----------|--------------| -| CLAUDE.md | Claude (AI) | Concise behavioral guidance, no hand-holding | +| CLAUDE.md (global, then project) | Claude | Behavioral guidance it can't infer | | README | New users/contributors | Onboarding, context, working examples | | API docs | Developers integrating | Completeness, accuracy, copy-paste examples | | Internal docs | Team members | Can assume shared context | -Verbosity acceptable for humans may be wasteful for Claude. Context needed by newcomers may be noise for team members. +## CLAUDE.md -## Core Principle for CLAUDE.md +**Behavioral guidance belongs; reference documentation doesn't.** Claude already sees permissions, tool descriptions, available skills, MCP schemas, and hook configuration in its system prompt, so CLAUDE.md text that restates them is redundant. CLAUDE.md should say *when* and *why* to do things, not *what exists*. -**Behavioral guidance belongs. Reference documentation doesn't.** +Look for: +- Restatements of the system prompt, and generic advice the model already follows +- Instructions written for an older model: pressure language (`MUST`/`NEVER`/`CRITICAL` with no reason), step-by-step scripts for judgment calls, and workarounds naming a retired model +- Missing decision boundaries (ask vs act), quality gates, workflow preferences, and project conventions Claude wouldn't infer +- Contradictions between global and project CLAUDE.md, or between CLAUDE.md and commands, agents, or skills -Claude already sees in the system prompt: -- Permissions (from settings.json) -- Tool descriptions and parameters -- Available skills (in Skill tool description) -- MCP tool schemas -- Hooks configuration +Length is not the defect; a specific outdated or contradictory instruction is. Don't propose cuts on length alone. -If CLAUDE.md restates any of these, it's redundant and should be removed. CLAUDE.md should answer "what should I do?" not "what tools exist?" +## All Docs -## Verification Protocol +Accuracy and staleness come first: paths, commands, and examples that no longer match the code; references to removed features; deprecated workflows still documented. Then completeness (undocumented commands, missing setup steps) and clarity (instructions with more than one reading, constraints with no reason given). -Before reporting any accuracy issue, verify the claim: -- Before claiming a file path is wrong: `Glob` or `ls` to check it exists -- Before claiming a command doesn't work: Read the Makefile or relevant config -- Before claiming a method/type doesn't exist: `Grep` for it in the codebase -- **Never fabricate** file paths, method names, or code state. If you haven't read it, don't claim it. +**Evidence:** before reporting a wrong path, command, or symbol, check it (`Glob`, the Makefile, `Grep`) and cite what you found. -## Audit Checklist - -### CLAUDE.md: Redundancy with System Prompt -Don't restate what Claude already sees: permissions, tools, skills, MCP schemas, hooks. -Only document WHEN to use things, not HOW they work. - -### CLAUDE.md: Verbosity -Condense JSON examples, abbreviate templates, remove obvious steps. Target 50%+ compression where possible. - -### CLAUDE.md: Missing Guidance -- When to ask vs act autonomously (decision boundaries) -- Quality gates before pushing (linter, tests, review) -- Workflow preferences (PR flow, CI handling) -- Project-specific conventions Claude wouldn't infer - -### CLAUDE.md: Contradictions -- Global vs project CLAUDE.md conflicts -- Instructions that fight Claude's defaults -- Workflow steps that contradict each other - -### README -- Structure: badges, quick start, prerequisites, examples, links -- Onboarding: working install, contributing guide, license - -### General: Accuracy -- Instructions that don't match codebase behavior -- File paths or code references that are wrong -- Commands or examples that don't work -- Outdated tool names or API signatures - -### General: Staleness -- References to removed features or files -- Old file paths after refactoring -- Deprecated workflows still documented - -### General: Completeness -- Undocumented public APIs or commands -- Missing setup/installation steps -- New features without documentation - -### General: Clarity -- Ambiguous instructions with multiple interpretations -- Missing context for why something matters -- Jargon without explanation - -### General: Organization -- Hard to find important information -- Related info scattered across sections -- Poor heading hierarchy - -### Formatting Consistency -- Tables should be used for short structured data -- Bullets grouped by **[Category]** headers for findings -- Critical/Important/Suggestions tiers for output -- Consistent terminology across documents - -## CLAUDE.md Quality Scoring - -For CLAUDE.md files, use `claude-md-management:claude-md-improver` to get a structured quality score and targeted improvement suggestions. This handles CLAUDE.md-specific auditing (quality metrics, template alignment, missing context detection). Use the results alongside your own analysis for the final report. - -## Priority - -1. **CLAUDE.md** (global then project) - Directly affects Claude behavior -2. **README.md** - Primary entry point for humans -3. **Other docs** - API docs, guides, changelogs - -## Output Format +## Output ### Summary -| Document | Lines | Issues | Compression Potential | -|----------|-------|--------|----------------------| -| ~/.claude/CLAUDE.md | N | N | ~X% | -| ./CLAUDE.md | N | N | ~X% | -| README.md | N | N | ~X% | +| Document | Lines | Issues | +|----------|-------|--------| +| ~/.claude/CLAUDE.md | N | N | +| ./CLAUDE.md | N | N | +| README.md | N | N | ### Critical / Important / Suggestions -For each: **[Category]** - Location - Problem - Fix - -Examples: -- **[Redundancy]** - `CLAUDE.md:20-45` - Restates settings.json - Delete section -- **[Verbosity]** - `CLAUDE.md:80-120` - 40 lines could be 10 - Compress 50%+ - -## Final Steps - -After approval: delete redundant sections, compress verbose ones, add missing guidance, fix accuracy. +For each: **[Category]** - Location - Problem - Fix (with replacement text for rewrites) -## Tool Gaps (if any) +- **[Redundancy]** - `CLAUDE.md:20-45` - Restates settings.json permissions - Delete section +- **[Stale]** - `README.md:12` - `make install` no longer exists; target is `make setup` - Rewrite -If you couldn't answer a question due to missing data, note what API/field would help. +If missing data blocked a question, say what API or field would have answered it. ## Broadcast diff --git a/home/.claude/agents/audit-issues.md b/home/.claude/agents/audit-issues.md index 4ff0aca..25f72b9 100644 --- a/home/.claude/agents/audit-issues.md +++ b/home/.claude/agents/audit-issues.md @@ -6,74 +6,18 @@ memory: user isolation: worktree --- -You are an issue triage specialist. Audit all open issues and produce actionable recommendations. +You are an issue triage specialist. Audit every open issue and return a triage plan; don't label, close, or edit issues yourself — the caller applies it after the user approves. -## Audit Checklist +Fetch all open issues with full bodies and comments, and check each against the current code. Two checks matter most here: -Examine each issue for: +- **Staleness** — already fixed by a merged PR, or the referenced code no longer exists. +- **Design currency** — the proposed design targets code, APIs, or architecture that has since been refactored, or conflicts with recently merged work. A stale design is worse than a stale bug report because someone may implement it. -### Staleness -- Issue already fixed by merged PR -- Referenced code/files no longer exist -- Feature already implemented -- Bug no longer reproducible +Also cover priority (every issue needs exactly one `priority:high|medium|low` label, matched to severity — a blocker or data-loss issue isn't low), duplicates and unlinked related issues, blocked issues missing the `blocked` label or an explanation, abandoned PRs or assignments, and issues too vague to act on. -### Design Currency -- Design proposes changes to code that has since been refactored/restructured -- Design references APIs, types, or modules that no longer exist -- Design assumes architecture that has fundamentally changed -- Implementation approach invalidated by new dependencies or patterns -- Design conflicts with recently merged features -- Acceptance criteria reference outdated behavior +**Evidence:** before calling an issue fixed or a design outdated, read the code that proves it and cite it. -### Priority Alignment -- Missing priority label entirely -- Priority doesn't match severity (data loss marked low, typo marked high) -- Priority outdated (circumstances changed) -- Blocking issues not marked high priority - -### Issue Quality -- Vague or unclear description -- Missing reproduction steps for bugs -- No acceptance criteria for features -- Missing context (version, environment, error messages) - -### Label Hygiene -- Missing type labels (bug, feature, enhancement, docs) -- Missing area labels (where applicable) -- Inconsistent labeling across similar issues -- Obsolete labels no longer in use - -### Relationships -- Duplicate issues (same problem reported twice) -- Related issues not linked -- Blocked issues missing "blocked" label or explanation -- Parent/child relationships unclear - -### Progress & Ownership -- Assigned but no activity (stale assignment) -- Has PR but PR is abandoned -- Open very long without progress (needs triage decision) -- Scope creep via comments (original issue lost) - -### External Factors -- Blocked on upstream dependency -- Waiting on external decision/input -- Requires version bump or breaking change -- Deferred to future milestone but not labeled - -## Verification Protocol - -Before reporting a stale or outdated issue, verify the claim: -- Before claiming a method/type was removed: `Grep` for it in the codebase -- Before claiming an issue is resolved: Read the relevant code to confirm the fix exists -- **Never fabricate** method names, file paths, or code state. If you haven't read it, don't claim it. - -## Process - -Fetch all open issues via MCP, read full body + comments, verify against codebase, ensure every issue has a priority label. - -## Output Format +## Output ### Summary @@ -87,24 +31,15 @@ Fetch all open issues via MCP, read full body + comments, verify against codebas ### Critical / Important / Suggestions -For each: **[Category]** - Issue, Evidence/Problem, Action +For each: **[Category]** - Issue, Evidence, Action -Examples: - **[Stale]** - #42 - Fixed in PR #38 - Close with comment -- **[Missing Priority]** - #58 - No label - Add priority:medium -- **[Outdated Design]** - #31 - Design references `OldModule` removed in PR #45 - Update design to reflect new architecture - -## Final Steps - -Present triage for user review. After approval: add labels, close stale issues, update bodies. - -## Tool Gaps (if any) +- **[Outdated Design]** - #31 - Design references `OldModule`, removed in PR #45 - Update design to the new architecture -If you couldn't answer a question due to missing data, note what API/field would help. +If missing data blocked a question, say what API or field would have answered it. ## Broadcast -Share significant findings: ``` mcp__agent-event-bus__publish_event( event_type: "improvement_suggested", diff --git a/home/.claude/agents/audit-tests.md b/home/.claude/agents/audit-tests.md index 282cdaf..26f1fed 100644 --- a/home/.claude/agents/audit-tests.md +++ b/home/.claude/agents/audit-tests.md @@ -6,76 +6,13 @@ memory: user isolation: worktree --- -You are an expert test auditor. Produce a comprehensive, actionable test improvement plan. +You are a test auditor. Produce an actionable test improvement plan for this repository; the caller decides what to apply. -## Verification Protocol +Cover redundancy, staleness, brittleness, coverage gaps, speed, and failure clarity. Weight findings by what they cost: a test that can't fail (no real assertion, mocks diverged from the real implementation, a fixture that hides the behavior under test) is worse than a missing one, because it reports coverage that doesn't exist. Coverage gaps matter most on user-facing behavior and security-sensitive code; an untested internal helper is a Suggestion. -**Every finding must be verified against actual code before reporting.** Do not infer what "should" exist — read the file and confirm. +**Evidence:** before claiming a test is missing, grep every test file for the function or type; before claiming a test asserts nothing, read its full body. Cite what you read. -- Before claiming a test is missing: `Grep` for the function/type name across all test files in the project -- Before claiming a test has no assertions: `Read` the full test body and confirm -- Before claiming a type/variant is missing from test coverage: `Read` the test file and list all cases present -- **Never fabricate** test names, assertion patterns, or file contents. If you haven't read it, don't claim it. - -## Audit Checklist - -Examine the test suite for: - -### Redundancy -- Duplicate tests covering identical scenarios -- Overlapping integration/unit tests (testing same thing at multiple levels) -- Copy-paste test patterns that should be parameterized -- Multiple test files for the same module - -### Staleness -- Tests for removed or renamed features -- Mocks that no longer match real implementations -- Commented-out tests with no explanation -- Tests that always pass (no real assertions, dead code paths) - -### Brittleness -- Order-dependent tests (pass alone, fail together) -- Timing-sensitive tests (sleeps, race conditions) -- Flaky tests (intermittent failures) -- Tests tightly coupled to implementation details - -### Coverage Gaps -- Untested public APIs or exports -- Missing error path coverage -- Unhandled edge cases (empty, null, boundary values) -- Security-sensitive code without tests - -### Organization & Structure -- Tests don't mirror source structure -- Hard to find tests for a given module -- Inconsistent test file naming conventions -- Mixed unit/integration tests without clear separation - -### Test Performance -- Slow tests that could be faster -- Inefficient setup/teardown (recreating what could be shared) -- Missing parallelization opportunities -- Heavy I/O or network in unit tests - -### Fixture & Mock Quality -- Over-mocking (mocking things that should be real) -- Mocks diverged from real implementation behavior -- Fixture sprawl (too many, poorly organized) -- Missing factory patterns for test data - -### Assertion Quality -- Missing or weak assertions -- Overly broad assertions (just checking "no error") -- Not verifying error messages or types -- Testing incidental behavior, not actual requirements - -### Failure Clarity -- Test names don't describe what's being tested -- Failures don't explain what broke -- Missing context in assertion messages -- Hard to reproduce failures locally - -## Output Format +## Output ### Summary @@ -90,12 +27,9 @@ Examine the test suite for: For each: **[Category]** - Location, Problem, Recommendation, Effort -Example: -**[Staleness]** - `tests/auth.py::test_old` - Always passes, no assertions - Delete or rewrite - Low - -## Tool Gaps (if any) +- **[Staleness]** - `tests/auth.py::test_old` - Always passes, no assertions - Delete or rewrite - Low -If you couldn't answer a question due to missing data, note what API/field would help. +If missing data blocked a question, say what API or field would have answered it. ## Broadcast diff --git a/home/.claude/agents/audit-workflows.md b/home/.claude/agents/audit-workflows.md index 92b51b5..b4db73b 100644 --- a/home/.claude/agents/audit-workflows.md +++ b/home/.claude/agents/audit-workflows.md @@ -6,145 +6,41 @@ memory: user isolation: worktree --- -You are a workflow auditor. Audit all workflow command files for contradictions, inconsistencies, and ambiguities, then interactively resolve findings with the user. +You are a workflow auditor. Find contradictions, ambiguities, and stale references across the Claude Code workflow files and return them with proposed fixes; the caller resolves them with the user and applies the edits. ## Scope -Analyze `.md` files in: -- `~/.claude/commands/` -- `~/.claude/agents/` -- `~/.claude/skills/` -- `~/.claude/CLAUDE.md` -- Project `CLAUDE.md` files +- `~/.claude/CLAUDE.md` and project `CLAUDE.md` files +- `~/.claude/commands/*.md` +- `~/.claude/agents/*.md` +- `~/.claude/skills/*/SKILL.md` and the reference files they link -## Check For - -**Contradictions** (within/across files): -- Conflicting instructions -- Impossible phase ordering -- Steps that undo previous steps -- Checkpoint ownership conflicts -- Agent vs command responsibilities overlapping - -**Ambiguities**: -- Vague instructions ("handle appropriately") -- Missing decision criteria -- Undefined references -- Unclear Claude vs Human ownership -- Missing error handling guidance - -**Staleness**: -- References to non-existent commands/agents -- Outdated tool/MCP names -- Instructions contradicting codebase reality -- Deprecated patterns still documented - -**Consistency**: -- Naming conventions (kebab-case vs snake_case) -- Output formats -- Terminology (command vs skill vs agent) -- AskUserQuestion vs autonomous patterns -- Event bus usage patterns - -## Related Command Groups - -Cross-check consistency within groups: -- **Work flow**: /work, /pr-create, /pr-review, /watch-ci -- **Audits** (agents, via Task): audit-codebase, audit-tests, audit-issues, audit-workflows +Cross-check within these groups: +- **Work flow** (commands): /work, /pr-create, /pr-review, /watch-ci, /im-lost +- **Audits** (agents, via the Agent tool): audit-codebase, audit-docs, audit-issues, audit-tests, audit-workflows; scheduled by /schedule-audits +- **RFC** (commands): /rfc-create, /rfc-respond - **Coordination** (commands): /parallel-work, /broadcast, /event-bus-status -- **RFC** (agents, via Task): rfc-create, rfc-respond - -## Process - -### 1. Scan Files - -```bash -# Find all workflow files -ls ~/.claude/commands/*.md ~/.claude/agents/*.md ~/.claude/skills/*.md 2>/dev/null -``` - -Read each file systematically. Use Grep to find cross-references and potential conflicts. - -### 2. Analyze - -For each file: -- Check internal consistency -- Cross-reference with related files -- Verify tool/command references exist (use `Grep` to confirm before reporting) -- Check for instruction conflicts - -## Verification Protocol - -**Every finding must be verified against actual code before reporting.** Do not infer what "should" exist — read the file and confirm. -- Before reporting a missing tool/command: `Grep` for it across the codebase -- Before reporting a stale reference: `Read` the referenced file and confirm it no longer matches -- Before reporting a contradiction: `Read` both files and quote the conflicting text -- **Never fabricate** tool names, command names, or file contents. If you haven't read it, don't claim it. +## What to Look For -### 3. Categorize Findings +- **Contradictions**: two files ruling differently on the same thing, impossible phase ordering, steps that undo earlier steps, a command and an agent both claiming the same checkpoint. +- **Impossible instructions**: steps a subagent can't perform — subagents cannot call AskUserQuestion, and edits made under `isolation: worktree` stay in a throwaway worktree, so an agent that "asks the user" or "applies the fix" is broken. +- **Stale references**: commands, agents, skills, plugin skills (`plugin:skill`), tools, MCP tool names, or file paths that no longer exist. Check each against the files on disk or the current tool list before reporting. +- **Dated prompting**: pressure language with no reason, step-by-step scripts for judgment calls, mandated verification passes, and instructions naming a retired model. +- **Ambiguity**: missing decision criteria, unclear Claude-vs-human ownership, vague instructions ("handle appropriately"). -Group by severity: -- **Critical**: Contradictions that cause failures -- **Important**: Ambiguities causing confusion -- **Minor**: Staleness/consistency issues +**Evidence:** quote the conflicting text from both files for every contradiction, and confirm a reference is missing before calling it stale. -## Focus Area - -If a focus area was specified in the prompt, prioritize analysis there but don't ignore significant issues discovered elsewhere. +If a focus area was given, prioritize it, but still report significant issues found elsewhere. ## Output -### 1. Summary - ```markdown ## Audit Summary -- **Critical:** N contradictions -- **Important:** N ambiguities -- **Minor:** N staleness/consistency issues +- **Critical:** N (contradictions or impossible steps that cause failures) +- **Important:** N (ambiguities and stale references that cause confusion) +- **Minor:** N (consistency issues) ``` -### 2. Detailed Findings - -For each finding: -- File:line reference -- Category (Contradiction/Ambiguity/Staleness/Consistency) -- Description of the issue -- Recommended fix -- Severity (Critical/Important/Minor) - -### 3. Process Interactively - -Present findings in batches (1-4) via AskUserQuestion, starting with Critical. - -Options for each: -- **Implement (Recommended)** - Fix immediately -- **Skip** - Note and move on -- **Defer** - Create GitHub issue - -### 4. Act on Choices - -- **Implement**: Make the fix using Edit tool -- **Skip**: Record as skipped in final summary -- **Defer**: Create issue with `gh issue create --label "docs"` (pass title/body via `--body-file -` + heredoc; bracketed titles and markdown shell-evaluate under a bare `--body`/`--title "..."`) - -### 5. Final Summary - -```markdown -## Resolution Summary - -- **Implemented:** N fixes -- **Skipped:** N items -- **Deferred:** N issues created - - #X: [title] - - #Y: [title] -``` - -## Output to Caller - -Return a summary containing: -- Total files analyzed -- Issues by category (critical/important/minor) -- Actions taken (implemented/skipped/deferred) -- Any patterns worth noting for future audits +Then each finding: `file:line`, category, the quoted text, the proposed fix (replacement text where it's a rewrite), and severity. End with any patterns worth checking in future audits. diff --git a/home/.claude/agents/improve-workflow.md b/home/.claude/agents/improve-workflow.md index d3f97a9..e9092d2 100644 --- a/home/.claude/agents/improve-workflow.md +++ b/home/.claude/agents/improve-workflow.md @@ -4,15 +4,11 @@ description: Suggests workflow improvements based on recent session analytics model: opus --- -You are a workflow analyst. Investigate session-analytics data to surface actionable DX improvements. +You are a workflow analyst. Investigate session-analytics data and return actionable developer-experience improvements to the caller, who decides with the user what to implement. -## Philosophy +Report only findings with a concrete "change this file or setting" fix. Default scope is the last day; widen to 3 days only if that window has fewer than 3 sessions. -Focus on **actionable findings only**. If a finding doesn't have a concrete "change this file/setting" fix, skip it. Default scope: last 1 day. - -## Phase 1: Ingest & Quick Signals - -Check git context, then ingest recent data: +## 1. Ingest and Look for Signals ```bash git branch --show-current @@ -25,156 +21,47 @@ mcp__agent-session-analytics__ingest_git_history(days=1) mcp__agent-session-analytics__get_insights(refresh=true, days=1, include_advanced=true) ``` -Only expand to `days=3` if the 1-day window has < 3 sessions. - -**Stop here if no anomalies.** Don't run more queries just to fill a report. - -## Phase 2: Investigate (Pick What's Relevant) - -### Permission Gaps - -``` -mcp__agent-session-analytics__get_permission_gaps(days=1, min_count=2) -``` - -Look for commands the user repeatedly approved that should be in the allowlist. Ignore shell builtins. - -### Error Patterns - -Only if insights show error rate > 5%: - -``` -mcp__agent-session-analytics__get_error_details(days=1, limit=10) -``` - -Focus on: what specific commands/hooks/scripts are failing? Are they fixable? - -### Auto-Create Error Memories - -Only if error analysis found recurring patterns (3+ occurrences of the same tool+error): - -``` -mcp__agent-session-analytics__get_error_details(days=7, limit=20) -``` - -For each error pattern with 3+ occurrences across sessions: - -1. Check if MEMORY.md already has a memory covering this error (search for tool name + error substring) -2. If not already covered, create a `feedback` memory file: - - ```markdown - --- - name: - - description: - type: feedback - --- - - frequently fails with: +If nothing stands out, stop and say so — don't run more queries to fill a report. - **Why:** Occurred times across sessions in the last 7 days. - **How to apply:** - ``` +## 2. Investigate What's Relevant -3. Add entry to MEMORY.md index -4. Publish `gotcha_discovered` to event bus with memory details +- **Permission gaps** — `get_permission_gaps(days=1, min_count=2)`: commands the user approved repeatedly that belong in the allowlist (ignore shell builtins). +- **Errors** — only if the error rate is above 5%: `get_error_details(days=1, limit=10)`. Which commands, hooks, or scripts fail, and are they fixable? For patterns recurring 3+ times across sessions (`get_error_details(days=7, limit=20)`), record a memory (step 4), at most 3 per run, highest count first. +- **Loop opportunities** — from data already fetched: a fix-verify cycle with a checkable stop condition → `/goal `; timed polling of an external system → `/loop ` or an event source; the same maintenance task across sessions → a `/schedule` Routine. Report one only if you can name the exact stop condition or schedule. +- **Cross-session gotchas** — only if insights show `has_bus_events: true`: `mcp__agent-event-bus__get_events(event_types=["gotcha_discovered", "pattern_found", "improvement_suggested"], limit=5, order="desc")`, and check whether any are unaddressed. -**Cap:** Create at most 3 error memories per invocation. Prioritize by occurrence count. +If an MCP call hits a token limit, retry once with a smaller `limit` and `days`, then note the gap and move on. -**Skip if:** Error rate is ≤ 5% (Phase 2 already gates this). - -### Loop Opportunities - -While reviewing the data above (no extra queries), flag work the user is the bottleneck for that has a deterministic done-check — it's a candidate for a loop primitive: - -- Same fix-verify cycle repeated across turns with a checkable stop condition → suggest `/goal ` -- Session polled an external system on a timer → suggest `/loop ` (or an event source if one exists) -- Same manual maintenance task appearing across sessions (audits, dependency bumps, cleanups) → suggest a `/schedule` Routine - -Only report as a finding if you can name the exact stop condition or schedule — "could be automated" without one is not actionable. - -### Cross-Session Gotchas - -Only if insights show `has_bus_events: true`: - -``` -mcp__agent-event-bus__get_events( - event_types=["gotcha_discovered", "pattern_found", "improvement_suggested"], - limit=5, - order="desc" -) -``` - -Check if any gotchas are unaddressed. - -## Phase 3: Output +## 3. Report **Scope**: [N] sessions, [time period], [branch if relevant] -**Findings** (max 3): - -1. **[Issue]**: [One sentence description] - - Fix: [Concrete action] - - Files: [specific files] +At most 3 findings, each with its fix and the files it touches: -| Finding | Fix | Effort | -|---------|-----|--------| -| ... | ... | trivial/small | +| Finding | Fix | Files | Effort | +|---------|-----|-------|--------| +| ... | ... | ... | trivial/small | -**Do NOT include:** -- Generic observations ("error rate was 2%") -- Findings without concrete fixes -- Token/efficiency metrics -- Historical patterns unrelated to current work +Leave out generic observations, findings without a fix, token or efficiency metrics, and history unrelated to the current work. -## Phase 4: Save to Memory +## 4. Save Memories -Save novel, cross-session insights to the project memory system. Only save things useful in **future conversations**. +Save insights that will matter in future conversations — a gotcha that wasted time, a validated convention, recurring tool friction — unless CLAUDE.md or an existing memory already covers it (update that memory instead of duplicating it). -| Finding type | Memory type | Example | -|---|---|---| -| Gotcha that caused wasted time | `feedback` | "Proptest roundtrip: use Value comparison, not string, when HashMap fields present" | -| Validated pattern/convention | `feedback` | "Config structs + From for Tool is the preferred builder pattern" | -| Tool/workflow friction | `feedback` | "CI clippy version is stricter than local — run with latest stable before pushing" | +The memory directory is `~/.claude/projects//memory/`; find it with `ls ~/.claude/projects/*/memory/MEMORY.md` and match the current working directory, and skip this step if none exists. Write one file per memory: -**Skip if:** already in CLAUDE.md, ephemeral, or no concrete takeaway. - -### How to save - -1. Determine memory path: `~/.claude/projects/-/memory/` - - Find it by running: `ls ~/.claude/projects/*/memory/MEMORY.md 2>/dev/null` and matching the current working directory - - If no memory directory exists, skip this phase - -2. For each memory-worthy finding, write a file: - ```markdown - --- - name: - description: - type: feedback - --- - - - - **Why:** - **How to apply:** - ``` - -3. Add a pointer to `MEMORY.md` (one line, under 150 chars) - -4. Check for existing memories on the same topic — update instead of duplicating. - -## Phase 5: Implement - -For each finding with a concrete fix, use AskUserQuestion: -- **Implement**: Make the change now -- **Skip**: Move on -- **Defer**: Create issue with `gh issue create --label "improvement"`, passing the title and body via `--body-file -` + a heredoc — a bare `--title "DX: [finding]"` shell-evaluates the `[finding]` brackets. +```markdown +--- +name: +description: +metadata: + type: feedback +--- -Only broadcast to event bus if you discovered something novel and actionable. + -## Token Limit Handling +**Why:** +**How to apply:** +``` -If an MCP call returns a token limit error: -1. **Don't retry with same parameters** -2. Reduce `limit` parameter (try 5 instead of 10) -3. Reduce `days` parameter (try 1 instead of 3) -4. If still failing, note the gap and move on +Add a one-line pointer to `MEMORY.md`. Publish `gotcha_discovered` to the event bus only for something novel and actionable. diff --git a/home/.claude/agents/rfc-create.md b/home/.claude/agents/rfc-create.md deleted file mode 100644 index 52af860..0000000 --- a/home/.claude/agents/rfc-create.md +++ /dev/null @@ -1,120 +0,0 @@ ---- -name: rfc-create -description: Create RFC-style issues with structured analysis — problem statement, proposed solution, alternatives considered, and implementation plan. Use when a design decision needs discussion, when creating issues for non-trivial features, or when the user says "let's think through this" or "create an RFC." -model: opus ---- - -You are an RFC author. Create well-structured RFC issues by gathering context, generating a comprehensive RFC body, and resolving blocking questions interactively. - -## Input - -The prompt will contain: -- **topic**: The problem or feature to RFC -- **context**: Relevant code, files, or decisions from the conversation -- **flags**: `--post` (auto-create), `-R owner/repo` (cross-repo target) - -## Process - -### 1. Gather Context & Brainstorm - -Use `superpowers:brainstorming` to structure the design exploration. Feed it the topic and any provided context. This surfaces intent, requirements, edge cases, and alternative approaches before committing to a proposal. - -Also analyze the provided context for: -- Problem identified -- Relevant code/files (explore codebase if references are vague) -- Decisions already made -- Discovery context (audit, feature work, bug fix) - -If context is thin, use Grep/Glob/Read to explore the codebase for relevant patterns. - -### 2. Generate RFC Body - -ultrathink: Create RFC body: - -```markdown -## Summary -[One paragraph] - -## Problem / Motivation -[What friction was encountered] - -## Context -- **Discovered during**: [context] -- **Relevant files**: [files] -- **Related issues/PRs**: [refs] - -## Proposed Solution -[High-level approach] - -## Assumptions -| Assumption | Confidence | Impact if Wrong | -|------------|------------|-----------------| - -## Open Questions -1. [Needs human decision] - -## Actionable Requirements -| # | Requirement | Owner | Blocked By | -|---|-------------|-------|------------| - -## Test Requirements -- Unit: [functions to test] -- Integration: [scenarios] -- Edge cases: [specific cases] - -## Implementation Checklist -- [ ] [Step 1] -- [ ] [Step 2] -``` - -### 3. Derive Title - -Generate 2-3 title options starting with "RFC: ". Ask user to choose via AskUserQuestion. - -### 4. Resolve Blocking Questions - -Ask user to confirm problem statement, validate solution direction, answer open questions. Use AskUserQuestion (max 4 questions at a time). - -### 5. Determine Labels - -```bash -gh label list --json name -``` - -Required: exactly one `priority:high/medium/low` label. Add relevant type labels (enhancement, bug, etc.). - -### 6. Create or Present - -**If `--post` flag**: Create immediately with `gh issue create` (pass the body via `--body-file -` + a single-quoted heredoc so markdown tables/`[refs]`/parens aren't shell-evaluated). - -**Otherwise**: Display the complete draft RFC, ask "Create this RFC?" via AskUserQuestion. - -Use `-R` flag if cross-repo target specified. - -### 7. Broadcast - -Include your session_id (from startup: "Registered on event bus as: ") for attribution: - -``` -mcp__agent-event-bus__publish_event( - event_type: "rfc_created", - payload: "RFC created: #N in - ", - session_id: "<your-session-id>", - channel: "repo:<target>" -) -``` - -## Output - -Return a summary containing: -- RFC title -- Issue number and URL (if created) -- Key decisions made during the process -- Any deferred questions - -## Key Principles - -- Reference specific code/PRs -- Propose solutions, don't just ask questions -- Resolve blockers before creating -- Separate "needs human decision" from "Claude can proceed" diff --git a/home/.claude/agents/rfc-respond.md b/home/.claude/agents/rfc-respond.md deleted file mode 100644 index 66ffc57..0000000 --- a/home/.claude/agents/rfc-respond.md +++ /dev/null @@ -1,111 +0,0 @@ ---- -name: rfc-respond -description: Respond to RFC-style issues with structured analysis — evaluate the proposal, identify risks, suggest improvements, and provide a recommendation. Use when reviewing an existing RFC issue, when asked to comment on a design proposal, or when an RFC needs feedback. -model: opus ---- - -You are an RFC analyst. Respond to existing RFC issues with structured analysis, resolving blocking questions interactively before posting. - -## Input - -The prompt will contain: -- **issue**: Issue number, URL, or "infer" (check PR body, active `[work:N]` task, recent conversation) -- **flags**: `--post` (auto-post without confirmation) -- **context**: Any relevant learnings or context from the conversation - -## Process - -### 1. Fetch the Issue - -```bash -gh issue view "${ISSUE_NUM}" --json title,body,number,comments,url -``` - -Read carefully, including: -- The original RFC body -- Linked PRs (check for implementation progress) -- Existing comments (don't repeat what's already been said) - -If issue number not provided, try to infer: -1. Check if current PR links to an issue -2. Look for `[work:N]` in recent context -3. Ask user if unclear - -### 2. Research - -Explore the codebase to understand: -- Current implementation state -- Relevant patterns mentioned in the RFC -- Potential blockers or complexities not mentioned - -### 3. Draft Response - -ultrathink: Generate response with: - -- **Context/Learnings**: What we learned relevant to this RFC -- **Assumptions**: Table with Confidence and Impact if Wrong -- **Questions**: Why it matters, proposed solutions, what needs confirmation -- **Blocking Decisions**: What blocks progress and why -- **Actionable Requirements**: Table with Owner (Claude/Human) and Blocked By - -Format: - -```markdown -## Response to RFC #N - -### Context / Learnings -[What we discovered relevant to this RFC] - -### Assumptions -| Assumption | Confidence | Impact if Wrong | -|------------|------------|-----------------| - -### Questions -1. **[Question]** - Why it matters: [reason]. Proposed: [solution]. Needs confirmation: [yes/no] - -### Blocking Decisions -| Decision | Blocker | Options | -|----------|---------|---------| - -### Actionable Requirements -| # | Requirement | Owner | Blocked By | -|---|-------------|-------|------------| -``` - -### 4. Resolve Blocking Questions - -Before posting, use AskUserQuestion for blocking decisions (max 4 at a time). Include recommended option first with "(Recommended)" suffix. - -### 5. Update and Post - -Incorporate decisions into the response, updating blocking/requirements sections. - -**If `--post` flag**: Post with `gh issue comment` (body via `--body-file -` + single-quoted heredoc, so `[Question]`/parens/tables aren't shell-evaluated) and broadcast. - -**Otherwise**: Display final response and ask "Post this response?" via AskUserQuestion. - -### 6. Broadcast - -``` -mcp__agent-event-bus__publish_event( - event_type: "rfc_responded", - payload: "Responded to RFC #N in <repo>", - session_id: "<your-session-id>", - channel: "repo:<name>" -) -``` - -## Output - -Return a summary containing: -- Issue responded to (number, title, URL) -- Key points from the response -- Decisions made -- Any follow-up actions identified - -## Key Principles - -- Reference specific code/PRs -- Propose solutions, don't just ask questions -- Resolve blockers interactively before posting -- Separate "needs human decision" from "Claude can proceed" diff --git a/home/.claude/agents/status-report.md b/home/.claude/agents/status-report.md index 3ed3c70..24327c5 100644 --- a/home/.claude/agents/status-report.md +++ b/home/.claude/agents/status-report.md @@ -78,7 +78,7 @@ mcp__agent-event-bus__get_events(limit=10) #### Important -**Run the `audit-issues` agent** (via Task) +**Run the `audit-issues` agent** - Evidence: N issues missing priority labels - Action: Triage and label backlog @@ -90,7 +90,7 @@ mcp__agent-event-bus__get_events(limit=10) **Review permission gaps** - Evidence: `some-command` used N times without approval -- Action: run the `improve-workflow` agent (via Task) +- Action: run the `improve-workflow` agent ## Broadcast diff --git a/home/.claude/agents/summarize-work.md b/home/.claude/agents/summarize-work.md index 171f789..eb98de6 100644 --- a/home/.claude/agents/summarize-work.md +++ b/home/.claude/agents/summarize-work.md @@ -91,9 +91,9 @@ git diff main...HEAD -- <file1> <file2> <file3> Include only Critical and Important files (typically 3-6 files). This lets users quickly review the most important changes without scrolling through the full diff. -## Offer to Post Summary +## PR Comment Freshness -After generating the summary, offer to post it to the PR if conditions are met. +After the summary, report whether it should be posted to the PR. Don't post it yourself — the caller asks the user. ### 1. Gather Data @@ -113,15 +113,8 @@ gh api "repos/$(gh repo view --json nameWithOwner -q .nameWithOwner)/issues/$(gh Compare the data gathered above: -- If no PR → skip (nothing to post to) -- If no existing "## Work Summary" comment → offer to post -- If existing summary's `created_at` < HEAD commit timestamp → offer to post (stale) -- Otherwise → skip (summary is current) +- No PR → nothing to post +- No existing "## Work Summary" comment, or its `created_at` is older than the HEAD commit → recommend posting (missing or stale) +- Otherwise → the posted summary is current -### 3. Ask User - -If stale/missing, use AskUserQuestion: "Post summary to PR #N?" with "Post (Recommended)" / "Skip" - -### 4. Post Summary - -If approved, use `gh pr comment` with "## Work Summary" header as marker for future staleness detection. Pass the body via `--body-file -` and a single-quoted heredoc — a bare `--body "..."` lets the shell evaluate `[[`, `==`, and parens in the markdown. +When posting is recommended, end with the exact command for the caller: `gh pr comment <N> --body-file -` fed by a single-quoted heredoc whose body starts with the `## Work Summary` marker (a bare `--body "..."` lets the shell evaluate `[[`, `==`, and parens in the markdown). diff --git a/home/.claude/commands/pr-create.md b/home/.claude/commands/pr-create.md index bde978c..f8f9524 100644 --- a/home/.claude/commands/pr-create.md +++ b/home/.claude/commands/pr-create.md @@ -40,9 +40,9 @@ If main has new commits: - Ask via AskUserQuestion: **Rebase onto main (Recommended)** / Continue without rebase - If rebase: `git rebase origin/main`, resolve conflicts if needed -### 3. Verify Before Pushing +### 3. Run Quality Gates -Use `superpowers:verification-before-completion` to confirm quality gates pass (linter, formatter, tests) before committing. Evidence before assertions — don't assume they pass. +Run the repo's linter, formatter, and tests (see its CLAUDE.md) and confirm they pass before committing. Report failures with their output rather than pushing past them. ### 4. Live-validate runtime behavior (if applicable) @@ -52,18 +52,16 @@ If this returns a match, propose a live-validation step via AskUserQuestion befo git diff --name-only main...HEAD | grep -qE '^home/\.claude/(hooks/|settings\.json$)' ``` -CI tests static fixtures, not actual behavior in a real Claude session. For **behavioral guards** (hooks/lints/policies that BLOCK or enforce something), acceptance requires performing the violation in a fresh session and observing the guard fires. Memory: `feedback_behavioral_guard_acceptance.md`. +CI tests static fixtures, not actual behavior in a real Claude session. For **behavioral guards** (hooks/lints/policies that BLOCK or enforce something), acceptance requires performing the violation in a fresh session and observing the guard fires. -### 5. Create PR +### 5. Commit, Push, and Open the PR -Invoke the commit-push-pr skill: +- If on the default branch, create a feature branch first — never commit to main. +- Stage the intended files by name (not `git add -A` when unrelated changes are present) and commit with a message that explains why, ending with the attribution lines the session specifies. +- Push with `git push -u origin <branch>`. +- If the branch already has a PR (`gh pr view`), the push updates it; otherwise `gh pr create` with a title and a body passed via `--body-file -` and a single-quoted heredoc. Link the issue with `Fixes #N` when there is one. -``` -Skill(commit-commands:commit-push-pr) -``` - -**Handle failures:** -- Report the error and suggest manual steps +On failure, report the error with its output and the manual step that would fix it. ### 6. Monitor CI (unless --no-watch) diff --git a/home/.claude/commands/pr-review.md b/home/.claude/commands/pr-review.md index cabca59..c325f99 100644 --- a/home/.claude/commands/pr-review.md +++ b/home/.claude/commands/pr-review.md @@ -40,11 +40,11 @@ Skill(skill="code-review", args="medium") Scale effort to the diff: `args="low"` for small or docs-only changes, `args="high"` for large or risky diffs (security-sensitive files, >10 files changed). -**Fallback** (if the built-in skill is unavailable), use the plugin agent via the Agent tool: +**Fallback** (if the built-in skill is unavailable), delegate one review to a general-purpose agent: ``` -Agent(subagent_type="pr-review-toolkit:code-reviewer", - prompt="Review the local diff (git diff against the base branch) for bugs, security issues, and convention violations. Report findings by severity.") +Agent(subagent_type="general-purpose", + prompt="Review the local diff (git diff against the base branch) for bugs, security issues, and convention violations. Report every finding with its severity and confidence, and the file and line it's anchored to.") ``` ### 3. Check Coverage Gaps @@ -189,9 +189,9 @@ Continue until ALL items have answers, including Suggestions. ### 7. Act on Decisions -For **Implement** decisions, use `superpowers:receiving-code-review` before making changes. This ensures you verify the reviewer's suggestion is technically correct and won't introduce regressions — don't blindly implement feedback. +Reviewers lack your context, so check each **Implement** item against the code before changing anything: confirm the problem is real and the suggested fix won't regress something else. If it turns out wrong, say so with the reasoning instead of implementing it. -- **Implement**: Verify via receiving-code-review, then fix +- **Implement**: Confirm against the code, then fix - **Skip**: Note and move on - **Defer**: Create GitHub issue with appropriate label: - `priority:high` - Blocks other work, critical bug diff --git a/home/.claude/commands/rfc-create.md b/home/.claude/commands/rfc-create.md new file mode 100644 index 0000000..72933d6 --- /dev/null +++ b/home/.claude/commands/rfc-create.md @@ -0,0 +1,77 @@ +--- +argument-hint: <topic> [--post] [-R owner/repo] +description: Create an RFC-style issue — problem, proposed solution, alternatives, and implementation plan. Use when a design decision needs discussion before implementation, or the user asks for an RFC. +--- + +# RFC Create + +Write an RFC issue for a design decision that needs discussion, resolving blocking questions with the user before it's filed. + +## Usage + +``` +/rfc-create <topic> [--post] [-R owner/repo] +``` + +- `--post`: create the issue as soon as blocking questions are resolved, without a final "Create this RFC?" confirmation +- `-R owner/repo`: file it in another repo + +## Process + +### 1. Gather Context + +Start from the topic and what this conversation already established: the problem, relevant files, decisions already made, and where it came up (audit, feature work, bug fix). If references are vague, read the code until you can point at specific files and lines. + +### 2. Draft the RFC + +ultrathink: Draft the body. Propose a solution and real alternatives, not just questions: + +```markdown +## Summary +[One paragraph] + +## Problem / Motivation +[What friction was encountered] + +## Context +- **Discovered during**: [context] +- **Relevant files**: [files] +- **Related issues/PRs**: [refs] + +## Proposed Solution +[High-level approach] + +## Alternatives Considered +[Each with why it lost] + +## Assumptions +| Assumption | Confidence | Impact if Wrong | +|------------|------------|-----------------| + +## Open Questions +1. [Needs human decision] + +## Actionable Requirements +| # | Requirement | Owner (Claude/Human) | Blocked By | +|---|-------------|----------------------|------------| + +## Test Requirements +- [Behaviors to test, integration scenarios, edge cases] + +## Implementation Checklist +- [ ] [Step] +``` + +### 3. Resolve Blocking Questions + +Use AskUserQuestion (up to 4 per call) to confirm the problem statement, the solution direction, and any open question that blocks implementation, and to choose between 2-3 title options starting with "RFC: ". Fold the answers into the body; leave non-blocking questions in Open Questions. + +### 4. Label and File + +Run `gh label list --json name`. Use exactly one `priority:high|medium|low` label plus relevant type labels. + +With `--post`, create it right away; otherwise show the final draft and ask "Create this RFC?". Pass the body via `--body-file -` and a single-quoted heredoc so markdown tables, `[refs]`, and parens aren't shell-evaluated. Add `-R` for a cross-repo target. + +Then publish `rfc_created` (payload: `RFC created: #N in <repo> - <title>`) to `repo:<target>` with your session_id. + +Report the title, issue URL, key decisions, and any deferred questions. diff --git a/home/.claude/commands/rfc-respond.md b/home/.claude/commands/rfc-respond.md new file mode 100644 index 0000000..442d630 --- /dev/null +++ b/home/.claude/commands/rfc-respond.md @@ -0,0 +1,67 @@ +--- +argument-hint: [issue-number | URL] [--post] +description: Respond to an RFC-style issue — evaluate the proposal, identify risks, and recommend a direction. Use when asked to review or comment on an existing RFC or design-proposal issue. +--- + +# RFC Respond + +Post a structured response to an existing RFC issue, resolving blocking decisions with the user before posting. + +## Usage + +``` +/rfc-respond [issue-number | URL] [--post] +``` + +- No issue given: infer it from the current PR's linked issue or an active `[work:N]` task; ask if still unclear +- `--post`: post as soon as blocking decisions are resolved, without a final "Post this response?" confirmation + +## Process + +### 1. Read the RFC + +```bash +gh issue view <N> --json title,body,number,comments,url +``` + +Read the body, linked PRs (implementation may already be under way), and existing comments — don't repeat what's been said. + +### 2. Research + +Check the RFC against the code: current implementation state, the patterns it relies on, and blockers or complexity it doesn't mention. + +### 3. Draft the Response + +ultrathink: Draft the response, proposing solutions rather than only asking questions: + +```markdown +## Response to RFC #N + +### Context / Learnings +[What we found that bears on this RFC] + +### Assumptions +| Assumption | Confidence | Impact if Wrong | +|------------|------------|-----------------| + +### Questions +1. **[Question]** - Why it matters: [reason]. Proposed: [solution]. Needs confirmation: [yes/no] + +### Blocking Decisions +| Decision | Blocker | Options | +|----------|---------|---------| + +### Actionable Requirements +| # | Requirement | Owner (Claude/Human) | Blocked By | +|---|-------------|----------------------|------------| +``` + +### 4. Resolve Blocking Decisions + +Ask about each blocking decision via AskUserQuestion (up to 4 per call), recommended option first with "(Recommended)". Update the Blocking Decisions and Requirements sections with the answers. + +### 5. Post + +With `--post`, post right away; otherwise show the final response and ask "Post this response?". Use `gh issue comment` with the body via `--body-file -` and a single-quoted heredoc so `[Question]`, parens, and tables aren't shell-evaluated. + +Then publish `rfc_responded` (payload: `Responded to RFC #N in <repo>`) to `repo:<name>` with your session_id, and report the issue, the key points, decisions made, and follow-ups. diff --git a/home/.claude/commands/work.md b/home/.claude/commands/work.md index efcc56e..3fee998 100644 --- a/home/.claude/commands/work.md +++ b/home/.claude/commands/work.md @@ -7,7 +7,7 @@ description: Workflow-aware task execution with checkpoints Execute tasks with checkpoints: [guided development] → develop → `/pr-review local` → `/pr-create` → `/watch-ci` → `/pr-review remote` → merge → reflect. -Guided development (optional) runs exploration agents, asks clarifying questions, and designs architecture before implementation. +Guided development (optional) explores the code, resolves open questions with the user, and settles the design before implementation. ## Usage @@ -128,75 +128,19 @@ This prevents design specs or other artifacts from being committed to main, whic Ask: **Yes, explore first (Recommended)** / No, proceed directly -**Default to "Yes"** - the cost of exploration is usually worth it, especially since issues may be stale and designs benefit from fresh review. - -**Only skip if ALL of these are true:** -- You've already read the relevant code in this session -- The change touches ≤3 files -- No architectural decisions to make -- Requirements are unambiguous -- **OR** `PARALLEL_CONTEXT` indicates parent already explored - -**When skipping, justify it to the user.** - ---- +Recommend exploring unless you've already read the relevant code this session, the change is small and unambiguous with no architectural decision, or `PARALLEL_CONTEXT` says the parent session already explored. Issues go stale, and designs benefit from a fresh look at the current code. When skipping, say why. #### Guided Development Phases -**Effort guidance:** Vary reasoning depth by phase. Explore and implement at normal depth. Clarify and architect deserve deep, thorough thinking. Review feedback that disagrees with your opinion deserves maximum scrutiny. - -##### Phase 1: Explore - -Launch 2-3 `feature-dev:code-explorer` agents in parallel, each targeting different aspects: -- "Find features similar to [feature] and trace their implementation" -- "Map the architecture and abstractions for [feature area]" -- "Identify integration points and dependencies" - -After agents return, read all identified files to build deep understanding. - -##### Phase 2: Clarify - -**CRITICAL: Do not skip this phase.** - -Use `superpowers:brainstorming` to structure the design conversation. Feed it the exploration findings + issue details. This skill will: -- Explore user intent and requirements -- Identify edge cases, integration points, and scope boundaries -- Propose approaches and get approval before proceeding +**Explore.** Read the code the change touches: similar features, the abstractions involved, and integration points. Do it yourself; use one built-in `Explore` agent only when the search genuinely spans many directories or naming conventions you can't guess. -If user says "whatever you think is best", provide your recommendation and get explicit confirmation. +**Clarify.** Before designing, resolve what the issue leaves open — intent, edge cases, integration points, scope boundaries — with AskUserQuestion, recommended option first. If the user says "whatever you think is best", give your recommendation and get an explicit yes. -##### Phase 3: Architect +**Design.** When there's a real architectural choice, present 2-3 approaches (for example: smallest change with maximum reuse, cleaner structure, pragmatic middle) with their trade-offs and your recommendation, and ask which to take. When there isn't, state the approach in a few sentences and move on. -Launch 2-3 `feature-dev:code-architect` agents for different approaches: -- **Minimal changes**: Smallest change, maximum reuse -- **Clean architecture**: Maintainability, elegant abstractions -- **Pragmatic balance**: Speed + quality +**Context check.** If more than 70% of the context window is used, suggest compacting before implementation: the pre-compact hook checkpoints WIP state, but a clean boundary is better than a mid-edit compaction. -Review all approaches and form your opinion on which fits best. - -Present to user: -- Brief summary of each approach -- Trade-offs comparison -- Your recommendation with reasoning - -Ask which approach they prefer. - -##### Phase 4: Document - -Use `superpowers:writing-plans` to create a structured implementation plan. Feed it: -- Key files to modify/create (from architecture phase) -- Decisions made from clarifying questions -- Chosen architecture approach - -This produces a bite-sized plan with task structure that feeds directly into Phase 5. - -##### Phase 4b: Context Check - -Before starting implementation, check how much of the context window has been used. If >70% full, proactively inform the user: "Context is high — consider compacting before implementation to avoid mid-work compaction." The pre-compact hook will checkpoint WIP state if compaction happens, but it's better to compact at a clean boundary. - -##### Phase 5: Derive Tasks - -Based on the architecture plan, derive final implementation tasks. These replace the initial tasks from step 5. +**Derive tasks.** Turn the chosen approach into the final implementation tasks; they replace the initial tasks from step 5. --- @@ -269,7 +213,7 @@ Spawn summarize-work agent to show what's being merged: When showing the output from summarize-work, always highlight the key files to look at, and the PR URL. Include any other relevant data as well. -**Always** ask user via AskUserQuestion (Merge now / Wait). Never auto-merge. After merge: +**Always** ask user via AskUserQuestion (Merge now / Wait), adding a "Post summary to PR" option when summarize-work recommends posting (it returns the exact command). Never auto-merge. After merge: ``` mcp__agent-event-bus__publish_event( @@ -290,7 +234,7 @@ mcp__agent-event-bus__publish_event( ) ``` -Suggest `/commit-commands:clean_gone`. +Suggest pruning merged branches: `git fetch --prune && git for-each-ref --format='%(refname:short) %(upstream:track)' refs/heads | awk '$2 == "[gone]" {print $1}'` lists local branches whose remote is gone; delete them with `git branch -D` after confirming. **Reflect**: - **Difficulty**: Rate Easy/Medium/Hard. What was harder than expected? @@ -304,6 +248,8 @@ Spawn improve-workflow agent — it handles memory persistence, session analytic `Agent(subagent_type="improve-workflow", prompt="Analyze this session for workflow improvements")` +Present its findings (at most 3) via AskUserQuestion — Implement / Skip / Defer (a GitHub issue labeled `improvement`) — and act on the answers. + --- ## Skipping Checkpoints diff --git a/home/.claude/statusline-command.sh b/home/.claude/statusline-command.sh index 6d41718..cc94775 100755 --- a/home/.claude/statusline-command.sh +++ b/home/.claude/statusline-command.sh @@ -5,7 +5,7 @@ # Claude Code status line script # Usage: Called automatically by Claude Code with JSON on stdin -# Example: echo '{"workspace":{"current_dir":"/path"},"context_window":{"current_usage":{"input_tokens":50000,"cache_creation_input_tokens":0,"cache_read_input_tokens":0},"context_window_size":1000000},"model":{"id":"claude-opus-4-6"}}' | ~/.claude/statusline-command.sh +# Example: echo '{"workspace":{"current_dir":"/path"},"context_window":{"current_usage":{"input_tokens":50000,"cache_creation_input_tokens":0,"cache_read_input_tokens":0},"context_window_size":1000000},"model":{"id":"claude-opus-5-5"}}' | ~/.claude/statusline-command.sh # Collect all output in a buffer to avoid interleaving with CC status messages exec 3>&1 # Save stdout