Claude-Code-Workflow/.codex/skills/team-lifecycle/phases/05-completion-report.md

Phase 5: Completion Report

COMPACT PROTECTION: This is an execution document. After context compression, phase instructions become summaries only. You MUST immediately re-read this file via Read("~/~ or <project>/.codex/skills/team-lifecycle/phases/05-completion-report.md") before continuing. Never execute based on summaries.

Objective

Summarize pipeline results, list all deliverable artifacts, update session status to completed, close any remaining agents, and present the user with next-step options.

---

Input

Input	Source	Required
sessionDir	Phase 2 output	Yes
state	team-session.json (final)	Yes
state.pipeline	All tasks with final status	Yes
state.mode	Pipeline mode	Yes
state.started_at	Session start timestamp	Yes

---

Execution Steps

Step 5.1: Load Final State

const state = JSON.parse(Read("<session-dir>/team-session.json"))

Step 5.2: Agent Cleanup

Close any remaining active agents (defensive -- should be none at this point).

for (const agentEntry of state.active_agents) {
  try {
    close_agent({ id: agentEntry.agent_id })
  } catch (e) {
    // Agent already closed, ignore
  }
}
state.active_agents = []

Step 5.3: Compute Summary Statistics

const totalTasks = state.pipeline.length
const completedTasks = state.pipeline.filter(t => t.status === "completed").length
const failedTasks = state.pipeline.filter(t => t.status === "failed").length
const partialTasks = state.pipeline.filter(t => t.status === "partial").length
const revisionTasks = state.pipeline.filter(t => t.revision_of !== null).length

const startTime = new Date(state.started_at)
const endTime = new Date()
const durationMs = endTime - startTime
const durationMin = Math.round(durationMs / 60000)

const successRate = totalTasks > 0
  ? Math.round((completedTasks / totalTasks) * 100)
  : 0

Step 5.4: Collect Deliverable Artifacts

Scan completed tasks for artifact paths. Group by pipeline phase.

const artifacts = {
  spec: [],
  plan: [],
  impl: [],
  test: [],
  review: [],
  discussions: [],
  qa: []
}

for (const task of state.pipeline) {
  if (task.status !== "completed" || !task.artifact_path) continue

  if (task.id.startsWith("RESEARCH") || task.id.startsWith("DRAFT") || task.id.startsWith("QUALITY")) {
    artifacts.spec.push({ task_id: task.id, path: task.artifact_path })
  } else if (task.id.startsWith("PLAN")) {
    artifacts.plan.push({ task_id: task.id, path: task.artifact_path })
  } else if (task.id.startsWith("IMPL") || task.id.startsWith("DEV-FE")) {
    artifacts.impl.push({ task_id: task.id, path: task.artifact_path })
  } else if (task.id.startsWith("TEST")) {
    artifacts.test.push({ task_id: task.id, path: task.artifact_path })
  } else if (task.id.startsWith("REVIEW")) {
    artifacts.review.push({ task_id: task.id, path: task.artifact_path })
  } else if (task.id.startsWith("QA-FE")) {
    artifacts.qa.push({ task_id: task.id, path: task.artifact_path })
  }
}

// Also collect discussion records
const discussionFiles = Glob("<session-dir>/discussions/*.md")
for (const df of discussionFiles) {
  artifacts.discussions.push({ path: df })
}

Step 5.5: Collect Wisdom Summary

Read wisdom files to include key findings in the report.

const wisdomSummary = {
  learnings: Read("<session-dir>/wisdom/learnings.md") || "(none)",
  decisions: Read("<session-dir>/wisdom/decisions.md") || "(none)",
  conventions: Read("<session-dir>/wisdom/conventions.md") || "(none)",
  issues: Read("<session-dir>/wisdom/issues.md") || "(none)"
}

Step 5.6: Check for Consensus Warnings

Collect any consensus-blocked results across the pipeline.

const consensusIssues = state.pipeline
  .filter(t => t.discuss_verdict === "consensus_blocked")
  .map(t => ({
    task_id: t.id,
    severity: t.discuss_severity,
    revision: t.revision_of ? `revised as ${state.revision_chains[t.revision_of]}` : null
  }))

Step 5.7: Update Session Status

state.status = "completed"
state.updated_at = new Date().toISOString()
state.completed_at = new Date().toISOString()

Write("<session-dir>/team-session.json",
  JSON.stringify(state, null, 2))

// Update message bus meta.json status
const meta = JSON.parse(Read("<session-dir>/.msg/meta.json"))
meta.status = "completed"
meta.updated_at = new Date().toISOString()
Write("<session-dir>/.msg/meta.json", JSON.stringify(meta, null, 2))

// Log completion event to message bus
const msgCounter = getLastMsgCounter("<session-dir>/.msg/messages.jsonl") + 1
logToMessageBus("<session-dir>", msgCounter, {
  from: "coordinator",
  type: "shutdown",
  summary: `Pipeline completed: ${completedTasks}/${totalTasks} tasks (${successRate}%)`,
  data: {
    tasks_completed: completedTasks,
    tasks_total: totalTasks,
    success_rate: successRate,
    duration_min: durationMin,
    failed_tasks: failedTasks
  }
})

Step 5.8: Output Completion Report

Format and display the final report to the user.

==============================================================
[orchestrator] PIPELINE COMPLETE
==============================================================

Session: <session-id>
Mode: <mode>
Duration: <duration-min> minutes
Progress: <completed>/<total> tasks (<success-rate>%)

--------------------------------------------------------------
TASK SUMMARY
--------------------------------------------------------------
| Task ID | Agent | Status | Discuss | Artifact |
|---------|-------|--------|---------|----------|
| RESEARCH-001 | analyst | V | DISCUSS-001: reached | spec/discovery-context.json |
| DRAFT-001 | writer | V | DISCUSS-002: reached | spec/product-brief.md |
| ... | ... | ... | ... | ... |

V=completed  X=failed  ~=partial  R=revision

--------------------------------------------------------------
DELIVERABLES
--------------------------------------------------------------

Specification:
  <artifact-list from artifacts.spec>

Plan:
  <artifact-list from artifacts.plan>

Implementation:
  <artifact-list from artifacts.impl>

Testing:
  <artifact-list from artifacts.test>

Review:
  <artifact-list from artifacts.review>

Discussions:
  <discussion-file-list>

QA:
  <artifact-list from artifacts.qa>

--------------------------------------------------------------
CONSENSUS NOTES
--------------------------------------------------------------
<if consensusIssues.length > 0>
  <for each issue>
    <task-id>: consensus_blocked (<severity>) <revision-note>
  <end>
<else>
  All discussions reached consensus.
<end>

--------------------------------------------------------------
WISDOM HIGHLIGHTS
--------------------------------------------------------------
Key learnings: <summary from wisdom/learnings.md>
Key decisions: <summary from wisdom/decisions.md>
Issues flagged: <summary from wisdom/issues.md>

--------------------------------------------------------------
NEXT STEPS
--------------------------------------------------------------
Available actions:
  1. Exit - session complete
  2. View artifacts - read specific deliverable files
  3. Extend - add more tasks to this pipeline
  4. New session - start a fresh lifecycle
  5. Generate lite-plan - create a lightweight implementation plan from spec

Session directory: <session-dir>
==============================================================

Step 5.9: Handle User Response

After presenting the report, wait for user input.

User Choice	Action
exit / done	Final cleanup, orchestrator stops
view <artifact-path>	Read and display the specified artifact
extend <description>	Re-enter Phase 1 with extend context, resume session
new <description>	Start fresh Phase 1 (new session)
lite-plan	Generate implementation plan from completed spec

For "extend": the orchestrator reads the existing session, appends new requirements, and re-enters Phase 3 to create additional tasks appended to the existing pipeline.

For "view": simply read the requested file and display contents, then re-present the next steps menu.

---

Output

Output	Type	Destination
Completion report	Text	Displayed to user
Updated state	JSON	team-session.json with status="completed"
User choice	String	Determines post-pipeline action

---

Success Criteria

• All agents closed (no orphaned agents)
• State file updated to status="completed"
• All artifact paths verified (files exist)
• Completion report includes all task statuses
• Consensus issues documented
• Wisdom highlights extracted
• Next steps presented to user

---

Error Handling

Error	Resolution
State file read error	Attempt to reconstruct from available artifacts
Artifact file missing	Report as "(artifact missing)" in deliverables list
Agent close failure	Ignore (agent already closed)
Wisdom file empty	Report "(no entries)" for that category
User input not recognized	Re-present available options

---

Post-Pipeline

This is the final phase. The orchestrator either stops (exit) or loops back to an earlier phase based on user choice.

User choice routing:
  exit     -> orchestrator stops
  view     -> display file -> re-present Step 5.9
  extend   -> Phase 1 (with resume context) -> Phase 3 -> Phase 4 -> Phase 5
  new      -> Phase 1 (fresh) -> Phase 2 -> Phase 3 -> Phase 4 -> Phase 5
  lite-plan -> generate plan from spec artifacts -> present to user