[P1] Skill: Improve agent workflow with phase-based check-ins and structured deliverables

[jacob-petterle]

Overview

Update the Shipyard skill to guide agents through a better workflow pattern with phase-based check-ins and structured deliverables organized by phase.

---

Problem

Current skill guidance doesn't emphasize the most effective workflow patterns:

1. Agents don't consistently check in with users between phases
2. No structured way to organize deliverables by implementation phase
3. Missing guidance on post-plan-creation review cycle
4. User doesn't get time to review changes before agent moves to next phase

---

Proposed Workflow Improvements

1. Post-Plan Creation Review Cycle

After creating a plan, agent should:

1. Publish the plan (exit plan mode)
2. Send requestUserInput asking user to review:

   await requestUserInput({
     message: "Let me know once you've reviewed the plan and are ready for me to proceed. Add any comments or feedback you'd like me to address.",
     type: "confirm",
     timeout: 1800 // 30 minutes
   });

3. Wait for user confirmation
4. Read comments with readDiffComments() if any
5. Address feedback or proceed with implementation

Exception: If using Claude Code's built-in plan mode, skip this (plan approval is built-in).

2. Phase-Based Check-ins

For each implementation phase:

1. Complete phase work (code changes, tests, etc.)
2. Post update: postUpdate({ message: "Phase 1 complete: Authentication implementation" })
3. Request user review:

   await requestUserInput({
     message: "Phase 1 is complete. Please review the changes (check the Changes tab). Let me know when you're done reviewing so I can address any comments and move to the next phase.",
     type: "confirm",
     timeout: 1800
   });

4. Give user time to review (don't rush)
5. Read comments: readDiffComments({ includeLocal: true })
6. Address feedback before moving to next phase
7. Repeat for each phase

Benefits:

• User has clear checkpoints to review work
• Agent doesn't move forward with mistakes
• Tighter feedback loop
• Less rework at the end

---

Structured Deliverables by Phase

Current Problem

Deliverables are flat list:

- [ ] Screenshot of login page {#deliverable}
- [ ] Video of auth flow {#deliverable}
- [ ] Test results {#deliverable}
- [ ] Coverage report {#deliverable}

Hard to tell which deliverables belong to which phase.

Proposed: Phase Prefixes

Allow deliverables to be prefixed with phase identifier:

## Phase 1: Authentication Implementation
- [ ] Phase 1: Screenshot of login page {#deliverable}
- [ ] Phase 1: Video of auth flow {#deliverable}
- [ ] Phase 1: Test results for auth {#deliverable}

## Phase 2: Authorization & Permissions
- [ ] Phase 2: Screenshot of permissions UI {#deliverable}
- [ ] Phase 2: Test results for permissions {#deliverable}

## Phase 3: Integration & Polish
- [ ] Phase 3: End-to-end test video {#deliverable}
- [ ] Phase 3: Final coverage report {#deliverable}

UI Changes

Deliverables tab groups by phase:

┌─────────────────────────────────┐
│ Deliverables                    │
├─────────────────────────────────┤
│ Phase 1: Authentication (2/3)   │
│   ✅ Screenshot of login page   │
│   ✅ Video of auth flow          │
│   ⏳ Test results for auth       │
│                                 │
│ Phase 2: Authorization (0/2)    │
│   ⏳ Screenshot of permissions   │
│   ⏳ Test results for perms      │
└─────────────────────────────────┘

Phase progress indicator:

• Overall: 2/5 deliverables (40%)
• Phase 1: 2/3 (67%)
• Phase 2: 0/2 (0%)

---

Skill Updates

Update Skill Instructions

Current focus: Creating tasks, uploading artifacts
New focus: Iterative workflow with check-ins

Add sections:

1. Post-Plan Creation Review

   • Always request review after publishing plan (unless Claude Code plan mode)
   • Example requestUserInput call
   • Wait for confirmation before starting work

2. Phase-Based Implementation

   • Break work into phases
   • Check in after each phase
   • Give user time to review changes
   • Read and address comments before next phase

3. Structured Deliverables

   • Prefix deliverables with phase name
   • Example plan structure
   • Benefits of phase organization

4. Review Cycle Pattern

   • Post update when phase complete
   • Request user review
   • Read comments
   • Address feedback
   • Confirm before next phase

Update Examples

Add example plan structure:

# Authentication Feature Implementation

## Phase 1: Login UI
...
Deliverables:
- [ ] Phase 1: Login page screenshot {#deliverable}
- [ ] Phase 1: Login flow test results {#deliverable}

## Phase 2: Backend Integration
...
Deliverables:
- [ ] Phase 2: API integration tests {#deliverable}
- [ ] Phase 2: Auth service coverage report {#deliverable}

Add example workflow:

1. Create plan with phases
2. Exit plan mode
3. requestUserInput("Review plan and confirm")
4. Wait for confirmation
5. Implement Phase 1
6. postUpdate("Phase 1 complete")
7. requestUserInput("Review Phase 1 changes")
8. readDiffComments()
9. Address comments
10. Repeat for Phase 2, 3, etc.

---

Implementation Plan

Phase 1: Skill Documentation Updates

• Update skill instructions with new workflow pattern
• Add post-plan-creation review guidance
• Add phase-based check-in guidance
• Add structured deliverables examples
• Update workflow diagram/examples

Phase 2: Schema/Parser Updates

• Support phase prefixes in deliverable text parsing
• Extract phase name from deliverable (e.g., "Phase 1: Screenshot" → phase = "Phase 1")
• Group deliverables by phase in data model
• Maintain backward compatibility (unprefixed deliverables → "No Phase")

Phase 3: UI Updates

• Group deliverables by phase in Deliverables tab
• Show phase progress (X/Y per phase)
• Collapsible phase sections
• Phase completion badges

Phase 4: MCP Tool Enhancements (Optional)

• Add phase parameter to createTask
• Add currentPhase to task metadata
• Track which phase agent is working on
• Filter deliverables by phase in API

---

Example Updated Skill Snippet

## After Creating a Plan

1. Exit plan mode to publish the plan
2. **Send review request:**
   ```typescript
   const review = await requestUserInput({
     message: "I've created the implementation plan. Please review it and add any comments or feedback. Let me know when you're ready for me to proceed.",
     type: "confirm",
     timeout: 1800
   });
   
   if (!review.success) {
     // User declined or timeout - check what happened
   }

3. Check for feedback:

   const comments = await readDiffComments({ 
     includeLocal: true,
     includeResolved: false 
   });
   // Address any comments before starting

4. Begin implementation

During Implementation

For each phase:

1. Complete the work
2. Post status update
3. Request phase review:

   await requestUserInput({
     message: `Phase ${phaseNumber} is complete: ${phaseName}. Please review the changes in the Changes tab. Let me know when you're done so I can address any feedback before moving to the next phase.`,
     type: "confirm",
     timeout: 1800
   });

4. Read and address comments
5. Upload deliverables for this phase
6. Move to next phase

Structuring Deliverables

Prefix deliverables with phase identifier:

• Phase 1: Screenshot of login UI {#deliverable}
• Phase 2: Test results for API integration {#deliverable}

This helps organize proof-of-work by implementation stage.

---

## Acceptance Criteria

- [ ] Skill documentation updated with new workflow pattern
- [ ] Post-plan-creation review cycle documented with examples
- [ ] Phase-based check-in pattern documented
- [ ] Structured deliverables with phase prefixes documented
- [ ] Schema supports parsing phase from deliverable text
- [ ] UI groups deliverables by phase
- [ ] Phase progress shown per phase and overall
- [ ] Backward compatible with existing unprefixed deliverables

---

## Priority

**P1** - This significantly improves the agent-human collaboration workflow and makes the tool much more effective. It's not a bug fix but a workflow enhancement that addresses real friction in the current process.

---

## Related Issues

- Skill documentation and workflow guidance
- Deliverables system improvements
- Agent check-in patterns
- `requestUserInput` usage patterns

---

*Created 2026-01-28*

[jacob-petterle]

Additional Requirement: Show Task URL on Completion

When agent finishes work (all deliverables fulfilled or task complete), include the task URL in the final message:

Example:

Task complete! All deliverables have been uploaded.

View the task here: https://schoolai.github.io/shipyard/?d=...

Why:

• Easy access for user to review the completed work
• Shareable link to include in PRs, messages, etc.
• Reminder of where to find the task if they've been away

When to show:

• After uploading the last deliverable
• When task auto-completes
• Periodically during long sessions (if URL hasn't been shown in a while)

The URL is available from the createTask response and can be shown again at the end.