[Workflow Handoffs] Phase 4: Agent Instruction Updates

.paw/work/workflow-handoffs/ImplementationPlan.md

@@ -85,6 +85,7 @@ The approach proceeds in logical phases: first establish handoff infrastructure
 4. **Phase 4: Agent Instruction Updates** - Update all agents to present next-step options and invoke handoff tool based on mode
 5. **Phase 5: Testing and Validation** - Comprehensive unit tests, integration tests, manual workflow testing
 6. **Phase 6: On-Demand Prompt Generation** - Remove auto-creation of all prompt files during workflow initialization; prompts created only when requested
+7. **Phase 7: Status Command and Agent Rename** - Add `PAW: Get Work Status` command with work ID picker, rename Status Agent from `PAW-X Status Update` to `PAW-X Status`
 
 ---
 
@@ -563,9 +564,9 @@ When user wants customization before executing:
 ### Success Criteria:
 
 #### Automated Verification:
-- [ ] Agent linter passes for all updated agent files: `./scripts/lint-agent.sh agents/*.agent.md`
-- [ ] No markdown syntax errors in updated agents
-- [ ] Handoff component included in all agents that have stage transitions
+- [x] Agent linter passes for all updated agent files: `./scripts/lint-agent.sh agents/*.agent.md` (except PAW-01A which has pre-existing token count issue)
+- [x] No markdown syntax errors in updated agents
+- [x] Handoff component included in all agents that have stage transitions
 
 #### Manual Verification:
 - [ ] Spec Agent presents next-step options after completion in Manual mode
@@ -577,6 +578,73 @@ When user wants customization before executing:
 - [ ] Review workflow agents follow same handoff patterns (Understanding → Baseline auto-chain in Semi-Auto)
 - [ ] Final PR Agent does not present handoff options (terminal stage)
 
+### Phase 4 Complete
+
+**Implementation Summary:**
+Successfully updated all PAW agent instruction files to include the new handoff component (`{{HANDOFF_INSTRUCTIONS}}`) and stage-specific handoff behavior. Created `agents/components/handoff-instructions.component.md` as a shared component with consolidated handoff logic covering:
+- Reading Handoff Mode from WorkflowContext.md (manual/semi-auto/auto)
+- Mode-specific behavior patterns
+- Handoff tool invocation with intelligent agent name mapping
+- Prompt generation tool invocation for customization
+- Prerequisite validation before handoffs
+
+**All automated verification passed:**
+- All 87 unit tests pass: `npm test`
+- TypeScript compilation succeeds: `npm run compile`
+- Agent linter passes for all agents except PAW-01A (pre-existing token count issue documented in WorkflowContext.md)
+- Handoff component included in all 14 agents with stage transitions
+
+**Files Created/Modified:**
+- Created: `agents/components/handoff-instructions.component.md`
+- Modified: All 14 agent files to include `{{HANDOFF_INSTRUCTIONS}}` component and stage-specific handoff sections:
+  - Standard workflow: PAW-01A, PAW-01B, PAW-02A, PAW-02B, PAW-03A, PAW-03B, PAW-04, PAW-05
+  - Review workflow: PAW-R1A, PAW-R1B, PAW-R2A, PAW-R2B, PAW-R3A, PAW-R3B
+- Modified: `WorkflowContext.md` to document PAW-01A token limit issue
+
+**Notes for Next Phase:**
+Phase 5 (Testing and Validation) should verify the handoff behavior end-to-end. Manual verification of the handoff flows across all three modes (manual, semi-auto, auto) is critical to confirm the agent instruction updates work correctly.
+
+**Review Considerations:**
+- Verify handoff component is rendered correctly by the agent template system
+- Check that stage-specific handoff sections match the Semi-Auto behavior table in the component
+- Confirm PAW-R agents have appropriate pause points for review workflow
+
+### Addressed PR Review Comments:
+
+**Date**: 2025-12-02
+
+**PR Review Comments Addressed:**
+1. **#2569868767** - Add command-to-agent mapping table to handoff component
+2. **#2569885927** - Remove prerequisite validation from handoff component, let next agent check its own prerequisites
+3. **#2569886459** - Mention prompt file generation option in handoff messages
+4. **#2569888255** - Add Status Agent help guidance in handoff messages
+5. **#2569861784** - Make PAW-01A Specification handoff conditional (spec research vs code research)
+
+**Voice Notes Feedback Addressed:**
+- Command mapping table with friendly short names (`spec`, `review`, `implement`, etc.)
+- "Continue" command behavior - proceed to default next stage
+- Don't specify PR numbers in handoff - just say `review`
+- Conditional handoff logic based on workflow state (spec research generated vs complete)
+- Review strategy-specific behavior in Implementation Review Agent
+- Documenter agent review comment handling
+
+**Changes Made:**
+- `agents/components/handoff-instructions.component.md`: Complete rewrite with command mapping table, continue command, help guidance, prompt file option mention
+- `agents/PAW-01A Specification.agent.md`: Conditional next stage logic
+- `agents/PAW-02B Impl Planner.agent.md`: Local vs prs strategy options
+- `agents/PAW-03A Implementer.agent.md`: Explicit reviewer handoff
+- `agents/PAW-03B Impl Reviewer.agent.md`: Detailed prs vs local strategy handoff
+- `agents/PAW-04 Documenter.agent.md`: Review comment handling handoff
+- `agents/PAW-05 PR.agent.md`: Clarified review command
+- `agents/PAW-R1A Understanding.agent.md`: Conditional baseline research handoff
+
+**Verification:**
+- ✅ TypeScript compilation succeeds: `npm run compile`
+- ✅ All 87 unit tests pass: `npm test`
+- ✅ Agent linter passes for all agents except PAW-01A (7215 tokens) and PAW-02B (6519 tokens) - token limits to be addressed in follow-up work per user request
+
+**Commit:** ce191e2 "Address PR review comments and voice notes for Phase 4"
+
 ---
 
 ## Phase 5: Testing and Validation
@@ -723,6 +791,128 @@ Remove the automatic creation of all prompt template files during workflow initi
 
 ---
 
+## Phase 7: Status Command and Agent Rename
+
+### Overview
+Add a new VS Code command `PAW: Get Work Status` that allows users to quickly invoke the Status Agent at any time. The command presents a QuickPick of active work items (sorted by most recently edited), defaulting to blank so the agent can determine the active work from context. Also rename the Status Agent from `PAW-X Status Update` to `PAW-X Status` for brevity.
+
+### Changes Required:
+
+#### 1. New Status Command
+**File**: `src/commands/getWorkStatus.ts` (new)
+**Changes**:
+- Create new command handler for `paw.getWorkStatus`
+- Scan `.paw/work/` directory to find all work items with `WorkflowContext.md`
+- Sort work items by most recent modification time (check `WorkflowContext.md` mtime or most recent artifact mtime)
+- Present QuickPick with:
+  - First option: "(Auto-detect from context)" with value `""`
+  - Subsequent options: Work IDs sorted by recency, showing last modified time
+- After selection, invoke the Status Agent via `workbench.action.chat.open` with `agent: 'PAW-X Status'` and query containing Work ID (if selected)
+
+**Brief Example**:
+```typescript
+interface WorkItem {
+  slug: string;
+  lastModified: Date;
+  title?: string; // from WorkflowContext.md "Work Title" field
+}
+
+async function getWorkStatus(): Promise<void> {
+  const workItems = await scanWorkItems();
+  const selection = await vscode.window.showQuickPick([
+    { label: '$(search) Auto-detect from context', value: '' },
+    ...workItems.map(w => ({
+      label: w.slug,
+      description: w.title,
+      detail: `Last modified: ${formatRelativeTime(w.lastModified)}`,
+      value: w.slug
+    }))
+  ], { placeHolder: 'Select work item or auto-detect' });
+
+  if (selection) {
+    const query = selection.value ? `Work ID: ${selection.value}` : '';
+    await vscode.commands.executeCommand('workbench.action.chat.open', {
+      query,
+      agent: 'PAW-X Status'
+    });
+  }
+}
+```
+
+#### 2. Command Registration
+**File**: `src/extension.ts`
+**Changes**:
+- Import `registerGetWorkStatusCommand` from `./commands/getWorkStatus`
+- Add command registration in `activate()`: `registerGetWorkStatusCommand(context)`
+
+**File**: `package.json`
+**Changes**:
+- Add command definition to `contributes.commands` array:
+  - `command`: `paw.getWorkStatus`
+  - `title`: `Get Work Status`
+  - `category`: `PAW`
+
+#### 3. Rename Status Agent
+**File**: `agents/PAW-X Status Update.agent.md` → `agents/PAW-X Status.agent.md`
+**Changes**:
+- Rename file from `PAW-X Status Update.agent.md` to `PAW-X Status.agent.md`
+- Update agent name in file header/description if present
+
+**File**: `src/tools/handoffTool.ts`
+**Changes**:
+- Update `TargetAgent` type: change `'PAW-X Status Update'` to `'PAW-X Status'`
+
+**File**: `package.json`
+**Changes**:
+- Update `paw_call_agent` tool's `target_agent` enum: change `'PAW-X Status Update'` to `'PAW-X Status'`
+
+**File**: `src/tools/createPromptTemplates.ts`
+**Changes**:
+- Update status template `mode` field: change `'PAW-X Status Update'` to `'PAW-X Status'`
+
+**File**: `scripts/lint-agent.sh`
+**Changes**:
+- Update filename check: change `"PAW-X Status Update.agent.md"` to `"PAW-X Status.agent.md"`
+
+**File**: `agents/components/handoff-instructions.component.md`
+**Changes**:
+- Update any references to `PAW-X Status Update` to `PAW-X Status`
+
+**File**: All agent files (`agents/*.agent.md`)
+**Changes**:
+- Update handoff references from `PAW-X Status Update` to `PAW-X Status`
+
+#### 4. Documentation Updates
+**File**: `README.md`
+**Changes**:
+- Document the new `PAW: Get Work Status` command
+- Update any references to "PAW-X Status Update" to "PAW-X Status"
+- Add usage examples: "Use `PAW: Get Work Status` from the command palette to check workflow progress"
+
+**File**: `paw-specification.md`
+**Changes**:
+- Update agent filename reference: `PAW-X Status Update.agent.md` → `PAW-X Status.agent.md`
+
+### Success Criteria:
+
+#### Automated Verification:
+- [ ] Unit tests pass: `npm test`
+- [ ] TypeScript compilation succeeds: `npm run compile`
+- [ ] Agent linter passes for renamed status agent: `./scripts/lint-agent.sh "agents/PAW-X Status.agent.md"`
+- [ ] Linting passes: `npm run lint`
+- [ ] No references to old agent name `PAW-X Status Update` remain in codebase
+
+#### Manual Verification:
+- [ ] Command palette shows `PAW: Get Work Status`
+- [ ] QuickPick displays work items sorted by recency (most recent first)
+- [ ] QuickPick includes "Auto-detect from context" option at top
+- [ ] Selecting a work item opens Status Agent chat with Work ID
+- [ ] Selecting "Auto-detect" opens Status Agent chat without Work ID (agent determines context)
+- [ ] Status Agent responds correctly with both explicit Work ID and auto-detected context
+- [ ] All handoff commands still work with renamed agent (`status` → `PAW-X Status`)
+
+---
+
 ## Testing Strategy
 
 ### Unit Tests:

.paw/work/workflow-handoffs/WorkflowContext.md

@@ -11,4 +11,6 @@ Remote: origin
 Artifact Paths: auto-derived
 Additional Inputs: none
 
-Note: As part of this work we will also be implementing https://github.com/lossyrob/phased-agent-workflow/issues/60 - add this to the spec and implementation plan.
+Note: As part of this work we will also be implementing https://github.com/lossyrob/phased-agent-workflow/issues/60 - add this to the spec and implementation plan.
+
+Note: PAW-01A Specification.agent.md exceeds the 6500 token lint error limit (currently ~6831 tokens). This is a pre-existing issue that will be addressed separately. The agent linter failing for this file is expected and OK during this work item.

.paw/work/workflow-handoffs/context/phase4-voice-notes.md

@@ -0,0 +1,18 @@
+These are voice notes that were recorded when reviewing phase four of the implementation. 
+
+I have some comments on the PR about the handoff scenarios and so I just want to talk those through so I can think through the complete. Hand off set. For the specification agent, as I said in my comment, umm, there's a next stage that is either the code researcher. If the code research is, I mean sorry if the spec research is done and there's no sort of like if if if the spec is completed, then the next days would be code researcher. However, users can run the specification which can then generate a spec research that the spec research agent needs to go and run. And so that next stage is conditional about the state of whether this is like going to go to spec research, which then goes back to the spec Asian or if the spec generation is completed and now we're moving on to the code research. 
+
+For the implementation planner agent, there's this like for the planning hand off, it says all modes pause after planning that. We don't have to say that. It's gonna pause when it talks about the next step, so. Really, it's. And and yeah, so the stage is not. Definitely going to move on to the implementation phase one, because in the PR mode the user could make PR comments, in which case they asked the implementation planner to address. Those comments, right. So it's the same agent, it hands off sort of to itself, but in the review context where it's, it's looking at the PR and addressing the review comments. Or if the PR step is, you know, if it's not review strategy PRS, it's review strategy local, then it can, you know, it's basically just saying like ask me or like. Yeah, you can say there yeah there's just no review PR comment. What would what would happen is that the user would just chat with that implementation planner agent to make updates to the plan. So the hand off can mention something like you know ask me to update the plan. Or umm. We can move on to implementation and then that's where the options of like implement, which it shouldn't. It shouldn't require the user to say implement phase one. It should just say implement and then the implementer agent will figure out what phase to work on. Similarly, like the generate prompt for implementer phase one is too verbose, right? It should say. You know, some sort of like terse language like generate implementation prompt. Or generate implementation prompt file or something like that, and then you know if the user ends up saying generate implementation prompt file for phase 4, right, it will do that like the IT should. It should be smart enough to like know how to name those. So if there's not instructions on how prompt files are named, then we might need to include that. 
+
+For the implementer agent and maybe elsewhere where it says semi auto auto immediate handoff, we probably want to specify that's immediate hand off to reviewer. Just because there's two options, review and status, I think that the agent probably figure out which one was more appropriate, but might as well make that explicit. It also says after addressing review comments, hand off to Paw 03 B which is not a full agent name. So unless the agent unless the agent name is like mapped somewhere else. It should say the full agent name. When the user says an agent name, it should be a short name that should be like reviewer, not. Not anything that has like Paw or the numbers in it. It should be like a friendly name where it's you know. Spec. Reviewer. And if we're in the spec phase, it would know that it means spec reviewer. Oh, sorry, no, there's no spec reviewer. It should be spec researcher, and if it's in the spec phase then we know that's a spec researcher. Umm, planner, right? If it's the implementation planner, I should just be able to say planner. Like implementer, reviewer. So if we're in an implementation phase, it should mean the implementation reviewer. Docs PR these short phrases that are shipped from the context make the agent understand what we're talking about. In the implementation reviewer agent, it says all modes pause wait for human PR review. If it's not PR strategy, then that's not true. So if it's the review strategy PRS, yes, that like it'll have to stop there. If it's automatic then the handoff just goes to the next phase. So. That should be clear. 
+
+For the documentary agent. The documentation agent should understand the review process as well and so it should be able to like hand off to itself with a review prompt that says, you know, review the comments on the PR if we're in the PR phase or review strategy for the PR review strategy. I should be able to hand off to the documenter with the with the review sort of mode enabled so that it updates based on the. PR comments. 
+
+In the PR agent it says address review comments on PR number yadda yadda. I don't want to specify the PR. I wanted to know how to find that so and it already does so it should just be review again just like a short one word review. So if I'm in the PR agent and I say review. Or yeah, or I say review PR, right. It should be clear that what that means is to go to the implementer agent and with the expectation that there's APR, review. If I'm in the review strategy, P RS. 
+
+For the understanding agent, the umm. Next steps are conditional based on whether there's the, the. Baseline researcher has done its work right, so it needs to be. Not just going immediately to the impact analysis, right? If the baseline research is not done, then it will have created a prompt and that has to get handed off to the baseline researcher with specific instructions to run the prompt, that is. At the path that the relative path of that prompt file. That's important. And that's the same thing with the spec researcher. The spec researcher. I'm sorry, the spec agent. The spec agent can. Output a prompt file that, when run with the spec researcher, needs to hand off with that specific path, so it's important to make sure that that path is correct to the prompt file that was generated. 
+
+For the review phases, there's a pretty straightforward next step. And actually this might be true in a number of different cases. So we need to reason about the handoffs and if the user says continue to go with the sort of most reasonable next step, you know as if it were in auto or semi auto mode. If the user says continue, just do the next stage. That is like sort of the default stage. 
+
+
+

agents/PAW-01A Specification.agent.md

@@ -429,12 +429,30 @@ Specification Ready for Planning Stage:
 - [ ] All FRs & SCs traceable and testable
 - [ ] Assumptions & scope boundaries explicit
 - [ ] Quality Checklist fully passes (or explicit user-approved overrides listed)
-
-Next: Invoke Code Research Agent (Stage 02) to map relevant codebase areas. Optionally run Status Agent to update Issue.
 ```
 
 If research was skipped: include an Assumptions section and Risks section note summarizing potential ambiguity areas; user must explicitly accept before proceeding.
 
+{{HANDOFF_INSTRUCTIONS}}
+
+### Specification Handoff
+
+**Conditional next stage based on workflow state:**
+
+**If spec research prompt was generated** (research questions remain):
+- Next stage: PAW-01B Spec Researcher (which returns to Spec after research)
+- Manual: Present options - `research` (runs spec research), `code` (skip research, go to code research), `status`
+- Semi-Auto: Immediate handoff to Spec Researcher
+- Auto: Immediate handoff to Spec Researcher
+
+**If SpecResearch.md exists or research was skipped** (spec complete):
+- Next stage: PAW-02A Code Researcher
+- Manual: Present options - `code`, `status`, `generate prompt for code research`
+- Semi-Auto: Pause (decision point before Code Research)
+- Auto: Immediate handoff to Code Researcher
+
+In manual mode, always give users the option to skip spec research and proceed directly to code research, even when spec research is the default next stage.
+
 ### Working with Issues and PRs
 
 - For GitHub: ALWAYS use the **github mcp** tools to interact with issues and PRs. Do not fetch pages directly or use the gh cli.

agents/PAW-01B Spec Researcher.agent.md

@@ -133,6 +133,12 @@ I've completed research and saved findings to:
 .paw/work/<feature-slug>/SpecResearch.md
 
 Optional external/context questions (if any) appear in the "User-Provided External Knowledge" section for manual completion.
+```
+
+{{HANDOFF_INSTRUCTIONS}}
+
+### Spec Research Handoff
 
-Next: Return to Spec Agent with the completed SpecResearch.md to refine the specification.
-```
+**Next stage**: PAW-01A Specification (return to integrate research)
+- Manual: Present options - `spec`, `status`
+- Semi-Auto/Auto: Immediate handoff