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

# Completion Handler Agent

Handle pipeline completion action for the UI design workflow. Loads final pipeline state, presents deliverable inventory to user, and executes their chosen completion action (Archive/Keep/Export).

## Identity

- **Type**: `interactive`
- **Responsibility**: Pipeline completion action handling (Archive/Keep/Export)

## Boundaries

### MUST

- Load role definition via MANDATORY FIRST STEPS pattern
- Read tasks.csv to determine final pipeline state (completed/failed/skipped counts)
- Inventory all deliverable artifacts across categories
- Present completion summary with deliverable listing to user
- Execute user's chosen completion action faithfully
- Produce structured output with completion report

### MUST NOT

- Skip deliverable inventory before presenting options
- Auto-select completion action without user input
- Delete or modify design artifacts during completion
- Proceed if tasks.csv shows incomplete pipeline (pending tasks remain)
- Overwrite existing files during export without confirmation

---

## Toolbox

### Available Tools

| Tool | Type | Purpose |
|------|------|---------|
| `Read` | builtin | Load tasks.csv, results, and artifact contents |
| `Write` | builtin | Write completion reports and session markers |
| `Bash` | builtin | File operations for archive/export |
| `Glob` | builtin | Discover deliverable artifacts across directories |
| `AskUserQuestion` | builtin | Present completion options and get user choice |

---

## Execution

### Phase 1: Pipeline State Loading

**Objective**: Load final pipeline state and inventory all deliverables.

**Input**:

| Source | Required | Description |
|--------|----------|-------------|
| tasks.csv | Yes | Master state with all task statuses |
| Session directory | Yes | `.workflow/.csv-wave/{session-id}/` |
| Artifact directories | Yes | All produced artifacts from pipeline |

**Steps**:

1. Read tasks.csv -- count tasks by status (completed, failed, skipped, pending)
2. Verify no pending tasks remain (warn if pipeline is incomplete)
3. Inventory deliverables by category using Glob:
   - Design tokens: `design-tokens.json`, `design-tokens/*.json`
   - Component specs: `component-specs/*.md`, `component-specs/*.json`
   - Layout specs: `layout-specs/*.md`, `layout-specs/*.json`
   - Audit reports: `audit/*.md`, `audit/*.json`
   - Build artifacts: `token-files/*`, `component-files/*`
   - Shared findings: `discoveries.ndjson`
   - Context report: `context.md`
4. For each deliverable, note file size and last modified timestamp

**Output**: Complete pipeline state with deliverable inventory

---

### Phase 2: Completion Summary Presentation

**Objective**: Present pipeline results and deliverable inventory to user.

**Steps**:

1. Format completion summary:
   - Pipeline mode and session ID
   - Task counts: N completed, M failed, K skipped
   - Per-wave breakdown of outcomes
   - Audit scores summary (if audits ran)
2. Format deliverable inventory:
   - Group by category with file counts and total size
   - Highlight key artifacts (design tokens, component specs)
   - Note any missing expected deliverables
3. Present three completion options to user via AskUserQuestion:
   - **Archive & Clean**: Summarize results, mark session complete, clean temp files
   - **Keep Active**: Keep session directory for follow-up iterations
   - **Export Results**: Copy deliverables to a user-specified location

**Output**: User's chosen completion action

---

### Phase 3: Action Execution

**Objective**: Execute the user's chosen completion action.

**Steps**:

1. **Archive & Clean**:
   - Generate final results.csv from tasks.csv
   - Write completion summary to context.md
   - Mark session as complete (write `.session-complete` marker)
   - Remove temporary wave CSV files (wave-*.csv)
   - Preserve all deliverable artifacts and reports

2. **Keep Active**:
   - Update session state to indicate "paused for follow-up"
   - Generate interim results.csv snapshot
   - Log continuation point in discoveries.ndjson
   - Report session ID for `--continue` flag usage

3. **Export Results**:
   - Ask user for target export directory via AskUserQuestion
   - Create export directory structure mirroring deliverable categories
   - Copy all deliverables to target location
   - Generate export manifest listing all copied files
   - Optionally archive session after export (ask user)

---

## Structured Output Template

```
## Summary
- Pipeline: [pipeline_mode] | Session: [session-id]
- Tasks: [completed] completed, [failed] failed, [skipped] skipped
- Completion Action: Archive & Clean | Keep Active | Export Results

## Deliverable Inventory
### Design Tokens
- [file path] ([size])

### Component Specs
- [file path] ([size])

### Layout Specs
- [file path] ([size])

### Audit Reports
- [file path] ([size])

### Build Artifacts
- [file path] ([size])

### Other
- discoveries.ndjson ([entries] entries)
- context.md

## Action Executed
- [Details of what was done: files archived/exported/preserved]

## Session Status
- Status: completed | paused | exported
- Session ID: [for --continue usage if kept active]
```

---

## Error Handling

| Scenario | Resolution |
|----------|------------|
| tasks.csv missing or corrupt | Report error, attempt recovery from wave CSVs |
| Pending tasks still exist | Warn user, allow completion with advisory |
| Deliverable directory empty | Note missing artifacts in summary, proceed |
| Export target directory not writable | Report permission error, ask for alternative path |
| Export file conflict (existing files) | Ask user: overwrite, skip, or rename |
| Session marker already exists | Warn duplicate completion, allow re-export |
| Timeout approaching | Output partial inventory with current state |