Repository navigation
refactor(claude): fix impossible subagent steps and drop over-prescribed workflows - #353
Conversation
…bed workflows Subagents can't call AskUserQuestion (Claude Code removes it from every subagent), so several agents had steps that could never run: - rfc-create / rfc-respond were built around interactive questions; move them to commands so they run in the main session. - audit-workflows, improve-workflow, summarize-work, audit-issues and audit-docs asked the user or "applied after approval"; they now return findings and leave decisions to the caller. audit-workflows also globbed skills/*.md (skills are directories) and now checks for impossible subagent steps. Trim instructions written for older models: - /work no longer launches 2-3 explorer plus 2-3 architect agents by default (contradicting CLAUDE.md's delegation rule) or chains the brainstorming / writing-plans skills; it explores, clarifies with the user, and presents design options directly. - Remove mandated verification-skill passes (pr-create, audit-codebase) and CRITICAL pressure language. - Replace generic code-smell / test / triage checklists the model already knows with the project-specific checks worth a deliberate look. - audit-docs: drop the "50%+ compression" target; length isn't the defect. - improve-workflow: one memory format, matching the current frontmatter. Drop plugin dependencies (superpowers, feature-dev, commit-commands, pr-review-toolkit, claude-md-management) from commands and agents, replacing them with built-ins or explicit git/gh steps. Fix a stale memory-file citation in pr-create, "via Task" references, and the README's nonexistent /improve-workflow example. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LBftoc1JCMLow9LDFZMADs
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
| ### 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). |
There was a problem hiding this comment.
[Suggestion] The agent now returns a recommendation plus the exact gh pr comment command, but the caller in commands/work.md (Confirm merge, ~L211-216) only says to highlight key files and the PR URL. Nothing tells it to ask about posting when posting is recommended. Consider adding a line there, e.g. "If summarize-work recommends posting, offer Post summary alongside Merge now / Wait." Without it, the ## Work Summary freshness check runs but its result is quietly dropped.
| --- | ||
|
|
||
| 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. |
There was a problem hiding this comment.
[Suggestion] Same handoff gap: commands/work.md:247-249 spawns this agent but does not say to present its (up to 3) findings to the user via AskUserQuestion (Implement / Skip / Defer). That was the old Phase 5, which could never run inside the subagent. A one-line caller instruction would finish the move.
There was a problem hiding this comment.
Code Review — Round 1
Summary
This PR moves the interactive RFC flows from agents to commands, removes subagent steps that could never run (AskUserQuestion, edits that stay in a worktree), drops dependencies on the plugins, and cuts generic checklists. I found no stale references to the removed rfc-* agents or plugin skills in commands, agents, skills, or hooks. The .claude/agents directory is symlinked as a whole, so deleting the two agent files leaves no dangling per-file links. The for-each-ref / awk [gone] one-liner correctly lists branches whose upstream is gone. The PR changes no hooks or guards, so it needs no live validation.
Suggestions (non-blocking)
- The
summarize-workandimprove-workflowagents now hand the decision back to the caller, but/workdoes not yet tell the caller to act on what they return. See the inline comments. This is not a regression: the old in-agent prompts could never fire. docs/work-review-cycle.md:158still lists the plugins (superpowers, feature-dev, etc.) in the config table. This is fine until the follow-up PR disables them.
Verdict
APPROVE - No blocking findings.
Automated review by Claude Code
Both agents now hand decisions back to the caller; tell /work to offer posting the summary and to present improve-workflow's findings. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LBftoc1JCMLow9LDFZMADs
Feedback AddressedImplemented
Deferred
|
| 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: |
There was a problem hiding this comment.
[Suggestion] "Post summary to PR" is added as a third option next to Merge now / Wait. In a single-select AskUserQuestion, choosing it means not choosing Merge in that same answer, and nothing says to ask the merge question again after posting. Consider posting first and then asking Merge / Wait again, or making it a separate question in the same AskUserQuestion call (it accepts up to 4) so the user can choose both.
|
|
||
| `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. |
There was a problem hiding this comment.
[Suggestion] The old improve-workflow Defer step warned that a bare --title "DX: [finding]" gets shell-evaluated and said to pass the body via --body-file - plus a heredoc. That warning was removed when the step moved here. The other new instructions in this PR (rfc-create, rfc-respond, summarize-work) keep the heredoc note, so it may be worth keeping it for this gh issue create too.
There was a problem hiding this comment.
Code Review — Round 2
Summary
The follow-up commit adds the two handoffs from round 1: /work now offers to post summarize-work output and presents improve-workflow findings for a decision. I re-checked the tree. No stale references to the removed rfc-* agents or to the dropped plugin skills remain in commands, agents, skills, hooks, the Makefile, or CI. The only remaining plugin mentions are the settings.json enablement and the docs table, both deferred to the next PR as agreed. The PR changes no hooks or guards. I left two small non-blocking suggestions inline on the new /work lines.
Previously Addressed (Filtered)
summarize-workhandoff (Implemented)improve-workflowhandoff (Implemented)docs/work-review-cycle.mdplugin table (Deferred to follow-up PR)
Verdict
APPROVE - No blocking findings.
Automated review by Claude Code
1 participant
This is the second PR updating the setup for the Opus 5.5 generation. It covers agents and commands.
Steps that could never run
Claude Code removes
AskUserQuestionfrom every subagent (per the sub-agents docs), so these agent steps were dead:rfc-create,rfc-respond/rfc-create,/rfc-respond) so they run in the main sessionaudit-workflowsimprove-workflow,summarize-workaudit-issues,audit-docsaudit-workflowsalso globbedskills/*.md, which can't match because skills are directories. It still called the Agent tool "Task". It now also checks other files for impossible subagent steps.Instructions written for older models
/workguided development launched 2–3code-explorerand then 2–3code-architectagents by default. That contradicts CLAUDE.md's delegation rule. It also chained the superpowers brainstorming and writing-plans skills and used "CRITICAL" pressure language. It now explores directly (oneExploreagent only for wide searches), clarifies with the user, and presents 2–3 design options when there's a real choice.superpowers:verification-before-completioncalls inpr-createandaudit-codebase) are removed. The global CLAUDE.md already says these cause over-verification.audit-docs: removed the "Target 50%+ compression" goal. A specific outdated or contradictory instruction is the defect, not length.improve-workflow: the two duplicated memory-writing blocks are merged into one, using the currentmetadata:frontmatter.Plugin dependencies
Commands and agents no longer require
superpowers,feature-dev,commit-commands,pr-review-toolkit, orclaude-md-management:commit-commands:commit-push-prgit/ghstepsclean_gonefor-each-refone-linerpr-review-toolkitfallback reviewerreceiving-code-reviewThe next PR disables the plugins themselves.
Docs and stale references
/rfc-create,/rfc-respond, and/schedule-audits(it was missing). Replaces the nonexistent/improve-workflowexample.docs/work-review-cycle.md: matches the new/workflow.pr-create: removed the citation of a memory file that no longer exists.statusline-command.sh: updated the header example model ID (suggestion from chore: update model references for Claude Opus 5.5 #351's review).make checkpasses. The rewritten agents keep their frontmatter (model,memory: user,isolation: worktree), their output contracts, and their event-bus broadcasts.🤖 Generated with Claude Code
https://claude.ai/code/session_01LBftoc1JCMLow9LDFZMADs