virtuewebagent-explainphase

name	VirtueWebAgent-ExplainPhase
description	Produce a unified, top-to-bottom markdown reference document for a selected phase (1, 2, or 3) — assembles the skill entry point, orchestrator pattern, task graph, shared procedures, and every task prompt in execution order
argument-hint	<phase-number>

VirtueWebAgent-ExplainPhase — Phase Documentation Generator

Phase argument: $ARGUMENTS

Validate the argument first. If it is not exactly 1, 2, or 3, print the following and stop:

Usage: /VirtueWebAgent-ExplainPhase <phase-number>

  phase-number   1, 2, or 3

Examples:
  /VirtueWebAgent-ExplainPhase 1
  /VirtueWebAgent-ExplainPhase 2
  /VirtueWebAgent-ExplainPhase 3

---

Phase Configuration Table

Resolve all paths from the argument before reading any files.

Field	Phase 1	Phase 2	Phase 3
Skill file	.claude/skills/VirtueWebAgent-Phase1/SKILL.md	.claude/skills/VirtueWebAgent-Phase2/SKILL.md	.claude/skills/VirtueWebAgent-Phase3/SKILL.md
Canonical tasks.json	prompts/phase1/tasks.json	prompts/phase2/tasks.json	prompts/phase3/tasks.json
Prompt directory	prompts/phase1/	prompts/phase2/	prompts/phase3/
State directory	state/phase1/	state/phase2/	state/phase3/
Output file	documentation/phase1-unified.md	documentation/phase2-unified.md	documentation/phase3-unified.md

---

Steps

Step 1 — Read Core Files in Parallel

Read all three of the following simultaneously:

1. The skill entry point file for the selected phase (path from Phase Configuration Table above)
2. The orchestrator-worker pattern at prompts/orchestrator-worker.md
3. The canonical tasks.json for the selected phase

Step 2 — Parse tasks.json

From the tasks.json, extract:

• Orchestrator block: goal, special_instructions, session_summary_file, model_map
• Task list: every task with all fields: name, prompt_file, prompt_extra, input_files, output_files, agent_task_summary_file, task_dependencies, failure_handling, parallel_group_label, model

Determine execution order:

Group tasks by parallel_group_label. Tasks with the same label run in parallel and form one group. Sort groups from first to last by computing the shallowest combined dependency depth of each group (groups whose dependencies are all already satisfied come first). Tasks whose parallel_group_label is absent or null form their own single-task group. Produce an ordered list of groups: [[task, task, ...], [task], ...].

Identify unique prompt files:

Collect all distinct values of prompt_file across all tasks, preserving the order of first appearance in the execution order. Many tasks in Phase 3 share a single prompt file — include shared prompts only once in the output document.

Identify shared procedures files:

List any .md files in the prompt directory whose filename does not start with task- and is not tasks.json. These are reference files read by multiple tasks. For Phase 2, this will find crawl-shared-procedures.md. For Phase 1 and Phase 3, none are expected.

Step 3 — Read Task Prompt Files and Shared Procedures Files

Read all unique prompt files identified in Step 2 in parallel. Also read any shared procedures files. Do this in a single parallel batch.

Step 4 — Build the Output Document

Assemble the content into the output file described below. Use the Write tool to write the complete document to the output file path from the Phase Configuration Table. Create the documentation/ directory if it does not exist:

mkdir -p documentation

---

Output Document Structure

Write the output file using the following structure exactly. Use the content read in Steps 1–3 to fill each section.

---

Document Header

# Phase N — <Phase Label from skill file>: Unified Reference

This document assembles the `/VirtueWebAgent-PhaseN` command, the orchestrator-worker pattern it
follows, the task graph, [any shared procedures,] and every task prompt in execution order into
a single readable reference.

Replace N with the phase number. Replace <Phase Label> with the value from the skill file (e.g., Login Discovery). Include the bracketed phrase about shared procedures only if the phase has shared procedures files.

---

Section 1 — Skill Entry Point

Heading: ## 1. Skill Entry Point

Sub-heading: **File:** <skill file path>

Render the full content of the skill file verbatim inside a markdown code block (``` fenced), with the frontmatter (the --- block) included.

---

Section 2 — Orchestrator-Worker Pattern

Heading: ## 2. Orchestrator-Worker Pattern

Sub-heading: **File:** prompts/orchestrator-worker.md

Render the full content of the orchestrator-worker pattern verbatim, preserving all headings, code blocks, and tables. Do not summarize or omit anything.

---

Section 3 — Orchestrator Configuration

Heading: ## 3. Orchestrator Configuration

Sub-heading: **Source:** <canonical tasks.json path>

Render four sub-sections:

3a. Goal

**Goal:** <orchestrator.goal value>

3b. Special Instructions

**Special Instructions:** <orchestrator.special_instructions value>

3c. Session Summary File

**Session Summary File:** <orchestrator.session_summary_file value>

3d. Model Map

Render as a markdown table:

Runtime	haiku tier	sonnet tier	opus tier
claude	...	...	...
gemini	...	...	...

---

Section 4 — Task Graph

Heading: ## 4. Task Graph

Sub-heading: **Source:** <canonical tasks.json path>

Render two sub-sections:

4a. Execution Groups (ASCII diagram)

For each execution group (in order from Step 2), render one block:

GROUP N (<parallel | serial>) — <parallel_group_label or "no label">
├── <task-name>    [<model tier>]  [<failure_handling>]
│     prompt:   <prompt_file path>
│     depends:  <dependency names, or "none">
│     inputs:   <input_files list, one per line, indented>
│     outputs:  <output_files list, one per line, indented>
│
└── <task-name>    [<model tier>]  [<failure_handling>]
      ...

Use ├── for all but the last task in a group; use └── for the last. Use │ continuation lines for the indented fields under each task. If a group has only one task, use └── alone.

Label the group parallel if it contains more than one task, serial if it contains exactly one.

4b. Shared Prompt Files (deduplication summary)

If two or more tasks share the same prompt_file, list each shared file and the tasks that reference it:

Shared prompt files:
  <prompt_file path>
    used by: task-a, task-b, task-c
  <prompt_file path>
    used by: task-x, task-y

If every task has a unique prompt file (no sharing), omit this sub-section.

---

Section 5 — Shared Procedures (Phase 2 only)

Include this section only if shared procedures files were identified in Step 2.

Heading: ## 5. Shared Procedures

For each shared procedures file found, add a sub-section:

Sub-heading: ### <filename> Path line: **File:** <full path>

Render the full content of the shared procedures file verbatim, preserving all headings, code blocks, and tables.

---

Section 6 — Task Prompts in Execution Order

Heading: ## 6. Task Prompts (in Execution Order) (use 5. if Section 5 was omitted)

For each execution group (in order), add a group heading and then one sub-section per unique prompt file used in that group.

Group heading:

### Group N — <parallel_group_label or "no label"> (<parallel | serial>)

Per unique prompt file in this group:

If a prompt file is used by exactly one task in the entire phase, use this format:

#### Task: `<task-name>`

**File:** `<prompt_file path>`
**Model:** <model tier> | **On Failure:** <failure_handling>
**Inputs:** <input_files as comma-separated list>
**Outputs:** <output_files as comma-separated list>

<full prompt file content verbatim>

If a prompt file is shared by multiple tasks (across the entire phase, not just this group), use this format for its first appearance:

#### Prompt: `<prompt_file path>` — used by: `task-a`, `task-b`, `task-c`

**Model:** <list distinct model tiers used across all tasks sharing this prompt> | **On Failure:** <list distinct failure_handling values>
**Tasks in this group:** <names of tasks in this specific group that use this prompt>
**Tasks in later groups:** <names of tasks in later groups that also use this prompt, if any>

<full prompt file content verbatim>

On subsequent appearances of the same shared prompt file (in a later group), do not repeat the prompt content. Instead, add a reference:

#### Prompt: `<prompt_file path>` — (content shown in Group M above)

**Tasks in this group using this prompt:** `task-x`, `task-y`

---

Section 7 — File Reference Index

Heading: ## 7. File Reference Index (adjust number if Section 5 was omitted)

Render a markdown table with two columns: Role and Path. Include one row per file that appears in the document:

Role	Path
Skill entry point	...
Orchestrator pattern	prompts/orchestrator-worker.md
Canonical tasks config	...
Working tasks config (runtime)	state/phaseN/tasks.json
Orchestrator state	state/phaseN/state.json
Orchestrator session summary	state/phaseN/session-summary.md
Shared procedures — <filename>	... (if applicable)
Task prompt — <task-name>	<prompt_file path>
(one row per unique prompt file)
Task output — <task-name>	<agent_task_summary_file path>
(one row per task)

---

Completion

After writing the output file, print one line:

Wrote documentation/phaseN-unified.md  (<N> tasks, <M> unique prompt files, <P> execution groups)

Replace N, M, P with the actual counts.