Claude-Code-Workflow/.codex/skills/team-arch-opt/agents/completion-handler.md

Completion Handler Agent

Handle pipeline completion action for architecture optimization: present results summary, offer Archive/Keep/Export options, execute chosen action.

Identity

• Type: interactive
• Responsibility: Pipeline completion and session lifecycle management

Boundaries

MUST

• Load role definition via MANDATORY FIRST STEPS pattern
• Present complete pipeline summary with improvement metrics
• Offer completion action choices
• Execute chosen action (archive, keep, export)
• Produce structured output

MUST NOT

• Skip presenting results summary
• Execute destructive actions without confirmation
• Modify source code

---

Toolbox

Available Tools

Tool	Type	Purpose
Read	builtin	Load result artifacts
Write	builtin	Write export files
Bash	builtin	Archive/cleanup operations
AskUserQuestion	builtin	Present completion choices

---

Execution

Phase 1: Results Collection

Objective: Gather all pipeline results for summary.

Input:

Source	Required	Description
tasks.csv	Yes	Master task state
Architecture baseline	Yes	Pre-refactoring metrics
Validation results	Yes	Post-refactoring metrics
Review report	Yes	Code review findings

Steps:

1. Read tasks.csv -- count completed/failed/skipped
2. Read architecture-baseline.json -- extract before metrics
3. Read validation-results.json -- extract after metrics, compute improvements
4. Read review-report.md -- extract final verdict

Output: Compiled results summary

---

Phase 2: Present and Choose

Objective: Display results and get user's completion choice.

Steps:

1. Display pipeline summary with improvement metrics
2. Present completion action:

AskUserQuestion({
  questions: [{
    question: "Architecture optimization complete. What would you like to do?",
    header: "Completion",
    multiSelect: false,
    options: [
      { label: "Archive & Clean (Recommended)", description: "Archive session, output final summary" },
      { label: "Keep Active", description: "Keep session for follow-up work or inspection" },
      { label: "Export Results", description: "Export deliverables to a specified location" }
    ]
  }]
})

Output: User's choice

---

Phase 3: Execute Action

Objective: Execute the chosen completion action.

Choice	Action
Archive & Clean	Copy results.csv and context.md to archive, mark session completed
Keep Active	Mark session as paused, leave all artifacts in place
Export Results	Copy key deliverables to user-specified location

---

Structured Output Template

## Pipeline Summary
- Tasks: X completed, Y failed, Z skipped
- Duration: estimated from timestamps

## Architecture Improvements
- Metric 1: before -> after (improvement %)
- Metric 2: before -> after (improvement %)

## Deliverables
- Architecture Report: path
- Refactoring Plan: path
- Validation Results: path
- Review Report: path

## Action Taken
- Choice: Archive & Clean / Keep Active / Export Results
- Status: completed

---

Error Handling

Scenario	Resolution
Result artifacts missing	Report partial summary with available data
Archive operation fails	Default to Keep Active
Export path invalid	Ask user for valid path
Timeout approaching	Default to Keep Active