[Workflow Handoffs] Phase 4: Agent Instruction Updates #119
Conversation
…fic handoff behavior
- Create agents/components/handoff-instructions.component.md with consolidated handoff logic
- Add {{HANDOFF_INSTRUCTIONS}} component include to all 14 PAW agents
- Update stage-specific handoff sections for each agent with mode-aware behavior
- Standard workflow agents (PAW-01A through PAW-05): handoff patterns for spec/research/planning/implementation/review/docs/pr stages
- Review workflow agents (PAW-R1A through PAW-R3B): handoff patterns for understanding/baseline/impact/gap/feedback/critic stages
- Document PAW-01A token limit issue in WorkflowContext.md (pre-existing, will be addressed separately)
- Mark Phase 4 complete in ImplementationPlan.md
Automated verification:
- All 87 unit tests pass
- TypeScript compilation succeeds
- Agent linter passes for all agents except PAW-01A (pre-existing token issue)
|
🐾 Implementation Reviewer 🤖: Review SummaryPhase 4 implementation reviewed and verified. All automated checks pass. What ChangedNew Component Created:
14 Agents Updated: Quality Assessment
Token Count AnalysisAgents with warnings (exceed 3500 threshold but under 6500 error limit):
PAW-01A exceeds error limit (6831 tokens) - pre-existing issue documented in WorkflowContext.md. Notes for Human Reviewer
Ready for human review. |
|
|
||
| ### Specification Handoff | ||
|
|
||
| **Next stage**: PAW-02A Code Researcher |
There was a problem hiding this comment.
This needs to be conditional - when having produced a spec research prompt, then the next stage is spec research. If the SpecResearch.md exists and the spec was generated, then code researcher. User should have the option in manual mode to skip spec research and go straight to code research even if that's the next stage. In semi-auto mode, in the case the next stage is spec research, then that is automatic. The pause is appropriate only before code research.
| ### Invoking Handoffs | ||
|
|
||
| When transitioning to another stage: | ||
| 1. Map user request to target agent (e.g., "research" → `PAW-01B Spec Researcher`) |
There was a problem hiding this comment.
The agent needs to know this mapping, so list them here concisely.
|
|
||
| ### Prerequisite Validation | ||
|
|
||
| Before handoff, validate required artifacts exist. If missing, provide actionable error with artifact path and which command to run first. |
There was a problem hiding this comment.
Don't validate before handoff. Let the next agent check for its prerequisites and suggest next steps if they aren't met.
Agents need to be given information about what agent to suggest if their prerequisites fail - currently only next stage is stated for success case.
| @@ -0,0 +1,30 @@ | |||
| ````markdown | |||
| ## Handoff Mode and Stage Navigation | |||
There was a problem hiding this comment.
This section should indicate that the user can ask the Status agent for help navigating the workflow - this is applicable to every stage. This should be states concisely as part of the handoff message.
lossyrob
force-pushed
the
feature/workflow-handoffs_phase4
branch
from
da96cb2 to
f6799c0
Compare
Updates handoff-instructions.component.md: - Add command-to-agent mapping table (#2569868767) - Add 'continue' command behavior for default next stage - Replace 'Prerequisite Validation' with 'Getting Help' section (#2569885927) - Add prompt file option mention in handoff messages (#2569886459) - Add Status Agent help guidance in handoff messages (#2569888255) Updates PAW-01A Specification handoff (#2569861784): - Make next stage conditional: spec research vs code research - In manual mode, allow skipping spec research to go directly to code research - Semi-Auto auto-chains to spec research, pauses before code research Updates other agent handoff sections (voice notes feedback): - PAW-02B: Clarify local vs prs strategy options - PAW-03A: Explicit 'handoff to reviewer' in semi-auto/auto - PAW-03B: Detailed prs vs local strategy handoff logic - PAW-04: Add review comment handling handoff - PAW-05: Clarify review command for Final PR - PAW-R1A: Conditional handoff for baseline research #119 (comment) #119 (comment) #119 (comment) #119 (comment) #119 (comment)
|
🐾 Implementation Reviewer 🤖: PR Review Comments VerificationAll PR review comments and voice notes have been successfully addressed. Changes verified and pushed. Detailed Comment TrackingComment #2569868767 - Command-to-Agent MappingRequest: List command-to-agent mapping concisely in handoff component Comment #2569885927 - Prerequisite ValidationRequest: Don't validate before handoff; let next agent check prerequisites and inform which agent to suggest if prerequisites fail Comment #2569886459 - Prompt File OptionRequest: Handoff message must indicate user has option to generate prompt files Comment #2569888255 - Status Agent GuidanceRequest: Section should indicate users can ask Status agent for help navigating workflow, applicable to every stage Comment #2569861784 - Conditional Specification HandoffRequest: Spec handoff needs to be conditional - when producing spec research prompt, next stage is spec research; if SpecResearch.md exists, next is code research; manual mode should allow skipping research
Voice Notes Feedback AddressedPAW-02B Impl PlannerIssue: Handoff should clarify local vs prs strategy options, avoid requiring "Phase 1" specification PAW-03A ImplementerIssue: Semi-auto/auto mode should explicitly say "immediate handoff to reviewer" PAW-03B Impl ReviewerIssue: "All modes pause" is not true for local strategy; handoff to "PAW 03B" should use full agent name PAW-04 DocumenterIssue: Should understand review process and be able to handoff to itself with review context PAW-05 PR AgentIssue: "Address review comments on PR number X" too verbose, should just be "review" PAW-R1A Understanding AgentIssue: Next stage conditional based on whether baseline research is done; must handoff with prompt path when research needed
Continue CommandIssue: User should be able to say "continue" to proceed with default next stage User-Friendly Command NamesIssue: Users shouldn't have to say "PAW-03B" or include numbers; should say "spec", "planner", "implementer", "reviewer" Overall SummaryChanges Made by Implementation Agent
Verification Results
Ready for Re-ReviewAll requested changes have been implemented. The handoff system now provides:
The phase is ready for final human review and approval. |
| Next: Invoke Evaluation Stage agents (PAW-R2A Impact Analysis, PAW-R2B Gap Analysis) with these understanding artifacts. | ||
| ``` | ||
|
|
||
| {{HANDOFF_INSTRUCTIONS}} |
There was a problem hiding this comment.
The handoff instructions, especially the table, are specific to the PAW implementation workflow, not the PAW Review workflow. There should be a separate handoff component for review workflows. Similarly, I noticed that the {{PAW_CONTEXT}} is also included in the review agents, but this is a PAW implementation workflow specific context. Please also remove that.
| @@ -0,0 +1,49 @@ | |||
| ````markdown | |||
There was a problem hiding this comment.
Does not need the markdown wrapper, remove.
| | `review`, `reviewer` | PAW-03B Impl Reviewer | | ||
| | `docs`, `documenter`, `documentation` | PAW-04 Documenter | | ||
| | `pr`, `final pr` | PAW-05 PR | | ||
| | `status`, `help` | PAW-X Status Update | |
There was a problem hiding this comment.
There needs to be a stronger command for addressing PR review comments. This is for the Implemntation Planner, Implementer (or Impl Reviewer who hands off to Impl), Docs, and PR. A phrase meaning, there are new comments go address them. This is for PR mode only. This should be a clear step in the handoff instructions.
| **prs strategy** (Phase PR opened): | ||
| - All Modes: Pause (wait for human PR review and merge) | ||
| - After PR merged, more phases remain: Present `implement`, `status` | ||
| - After PR merged, all phases complete: Present `docs`, `status` |
There was a problem hiding this comment.
Needs a conditional for before PR merged, PR has comments that need to be addressed. When asked to address PR comments it should hand off to the implementer agent.
agents/PAW-04 Documenter.agent.md
Outdated
| - [List of commits with brief descriptions] | ||
| **prs strategy** (Docs PR opened): | ||
| - All Modes: Pause after Docs PR (wait for human review) | ||
| - After PR review comments: Say `review` to address comments (handoff to self with review context) |
There was a problem hiding this comment.
'review' might not be the right word here. Perhaps "address comments". Or "check pr".
Addresses PR review comments from December 3, 2025:
1. Comment #2585581858: Remove markdown wrapper from handoff-instructions.component.md
- Removed ````markdown at start and ```` at end
2. Comment #2585473074: Separate review workflow handoff instructions
- Created review-handoff-instructions.component.md for PAW-R* agents
- Removed {{HANDOFF_INSTRUCTIONS}} and {{PAW_CONTEXT}} from all six PAW-R* agents
- These placeholders are implementation workflow specific, not review workflow specific
3. Comment #2585598107: Add 'address comments' command for PR review comments
- Added 'address comments' and 'check pr' commands to handoff-instructions.component.md
- Commands apply to Impl Planner, Implementer/Impl Reviewer, Docs, and PR agents
4. Comment #2585602054: Conditional handoff when PR has comments
- Updated PAW-03B Impl Reviewer handoff logic
- When PR has review comments and not merged, present 'address comments' or 'check pr'
5. Comment #2585604450: Clarify PR review comment terminology
- Changed PAW-04 Documenter to use 'address comments' or 'check pr' instead of 'review'
- Improves clarity when referring to addressing PR review comments
Links:
- #114 (comment)
- #114 (comment)
- #114 (comment)
- #114 (comment)
- #114 (comment)
|
🐾 Implementation Reviewer 🤖: Review Comments AddressedAll review comments from December 3, 2025 have been addressed. Here's the detailed tracking: Comment #2585581858 - Remove markdown wrapperWhat was done: Removed markdown code fence wrapper from Comment #2585473074 - Separate review workflow handoff instructionsWhat was done:
Comment #2585598107 - Add 'address comments' command for PR review commentsWhat was done:
Comment #2585602054 - Conditional handoff when PR has commentsWhat was done:
Comment #2585604450 - Clarify PR review comment terminologyWhat was done:
Additional Bug FixWhat was done: Fixed Overall SummaryThe Implementation Agent successfully addressed all five review comments from December 3, 2025 regarding:
Additionally, a bug was fixed in the handoff tool to ensure proper agent invocation in chat mode. Testing: All 87 tests pass ✅ Ready for re-review and approval. |
Summary
This phase updates all 14 PAW agent instruction files to include the new handoff component and stage-specific handoff behavior, enabling intelligent stage navigation and workflow transitions.
Changes
Handoff Component
agents/components/handoff-instructions.component.mdwith consolidated handoff logic covering:Agent Updates
All 14 agents updated to include
{{HANDOFF_INSTRUCTIONS}}component and stage-specific handoff sections:Standard Workflow Agents:
Review Workflow Agents:
Mode-Aware Behavior
Each agent now adapts handoff behavior based on mode:
Verification
Automated ✅
npm testnpm run compileManual (Outstanding)
continueArtifacts
.paw/work/workflow-handoffs/ImplementationPlan.mdagents/components/handoff-instructions.component.mdNotes
#69 (partial - Phase 4 of 6)
Related: #60
🐾 Generated with PAW