skill-slides

# Slides Skill Thin wrapper that delegates slides work to the appropriate subagent based on workflow type and output format: - **slides-research-agent**: Material synthesis into slide-mapped research reports - **pptx-assembly-agent**: PowerPoint generation from research reports - **slidev-assembly-agent**: Slidev project generation from research reports **Note**: Plan workflow (`/plan present:slides`) is handled by `skill-slide-planning`, not this skill. **IMPORTANT**: This skill implements the skill-internal postflight pattern. After the subagent returns, this skill handles all postflight operations (status update, artifact linking, git commit) before returning. This eliminates the "continue" prompt issue between skill return and orchestrator. ## Context References Reference (do not load eagerly): - Path: `.claude/context/formats/return-metadata-file.md` - Metadata file schema - Path: `.claude/context/patterns/postflight-control.md` - Marker file protocol - Path: `.claude/context/patterns/file-metadata-exchange.md` - File I/O helpers - Path: `.claude/context/patterns/jq-escaping-workarounds.md` - jq escaping patterns (Issue #1132) Note: This skill is a thin wrapper with internal postflight. Context is loaded by the delegated agent. ## Trigger Conditions This skill activates when: - `/slides` command with task number input - `/research` on a task with `task_type: "present:slides"` - `/implement` on a task with `task_type: "present:slides"` (assemble workflow) - Present extension is available --- ## Workflow Type Routing This skill routes to the appropriate subagent based on workflow type and output format: | Workflow Type | Preflight Status | Success Status | TODO.md Markers | |---------------|-----------------|----------------|-----------------| | slides_research | researching | researched | [RESEARCHING] -> [RESEARCHED] | | assemble | implementing | completed | [IMPLEMENTING] -> [COMPLETED] | **Note**: Assembly agents read `design_decisions.theme` with a fallback chain: design_decisions -> research report "Recommended Theme" -> default `academic-clean`. --- ## Input Parameters ### Required Parameters - `task_number` - Task number (must exist in state.json with task_type="present:slides") - `session_id` - Session ID from orchestrator ### Optional Parameters - `workflow_type` - One of: slides_research, assemble (default: slides_research) --- ## Execution Flow ### Stage 1: Input Validation Validate required inputs: - `task_number` - Must be provided and exist in state.json - Verify task_type is "present:slides" ```bash # Lookup task task_data=$(jq -r --argjson num "$task_number" \ '.active_projects[] | select(.project_number == $num)' \ specs/state.json) # Validate exists if [ -z "$task_data" ]; then return error "Task $task_number not found" fi # Extract fields task_type=$(echo "$task_data" | jq -r '.task_type // ""') status=$(echo "$task_data" | jq -r '.status') project_name=$(echo "$task_data" | jq -r '.project_name') description=$(echo "$task_data" | jq -r '.description // ""') # Validate task_type (supports "present:slides" or legacy "slides") if [ "$task_type" != "present:slides" ] && [ "$task_type" != "slides" ]; then return error "Task $task_number is not a slides task (task_type=$task_type)" fi ``` --- ### Stage 2: Preflight Status Update Update task status based on workflow type BEFORE invoking subagent. | Workflow Type | state.json status | TODO.md marker | |---------------|------------------|----------------| | slides_research | researching | [RESEARCHING] | | plan | planning | [PLANNING] | | assemble | implementing | [IMPLEMENTING] | ```bash # Extract output_format from forcing_data (default: "slidev" for backward compatibility) output_format=$(echo "$task_data" | jq -r '.forcing_data.output_format // "slidev"') case "$workflow_type" in slides_research) preflight_status="researching" preflight_marker="[RESEARCHING]" ;; assemble) preflight_status="implementing" preflight_marker="[IMPLEMENTING]" ;; esac # Update state.json if [ -n "$preflight_status" ]; then bash .claude/scripts/state-write.sh \ '(.active_projects[] | select(.project_number == $num)) |= . + { status: $status, last_updated: $ts, session_id: $sid }' \ --session-id "$session_id" \ --argjson num "$task_number" \ --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \ --arg status "$preflight_status" \ --arg sid "$session_id" fi ``` --- ### Stage 3: Create Postflight Marker Source `skill-base.sh` once, then follow `@.claude/context/patterns/skill-preflight-flow.md`'s Stage 3 (marker creation) — the preceding Stage 2 status transition is intentionally left as its own conditional block above (per-workflow-type dispatch is a domain-specific behavior this conversion does not restructure), only the marker write itself moves onto the shared function: ```bash source .claude/scripts/skill-base.sh padded_num=$(printf "%03d" "$task_number") skill_name="skill-slides" skill_create_postflight_marker "$padded_num" "$project_name" "$session_id" "$skill_name" "$workflow_type" ``` --- ### Stage 4: Prepare Delegation Context Resolve the target agent based on workflow_type and output_format: ```bash case "$workflow_type" in slides_research) target_agent="slides-research-agent" ;; assemble) case "$output_format" in pptx) target_agent="pptx-assembly-agent" ;; *) target_agent="slidev-assembly-agent" ;; esac ;; esac ``` **Delegation context**: ```json { "session_id": "sess_{timestamp}_{random}", "delegation_depth": 1, "delegation_path": ["orchestrator", "slides", "skill-slides", "{target_agent}"], "timeout": 3600, "task_context": { "task_number": N, "task_name": "{project_name}", "description": "{description}", "task_type": "present:slides" }, "workflow_type": "slides_research|assemble", "output_format": "slidev|pptx (extracted from forcing_data, default: slidev)", "forcing_data": "{from state.json task metadata, includes output_format}", "metadata_file_path": "specs/{NNN}_{SLUG}/.return-meta.json" } ``` --- ### Stage 5: Invoke Subagent **CRITICAL**: Use the **Agent** tool to spawn the subagent. Use the `target_agent` resolved in Stage 4. ``` Tool: Agent (NOT Skill, NOT Plan) Parameters: - subagent_type: "{target_agent}" - prompt: [Include task_context, delegation_context, workflow_type, forcing_data, metadata_file_path] - description: "Execute {workflow_type} for task {N}" ``` **Routing table**: | workflow_type | output_format | target_agent | |---------------|---------------|--------------| | `slides_research` | any | `slides-research-agent` | | `assemble` | `pptx` | `pptx-assembly-agent` | | `assemble` | `slidev` (default) | `slidev-assembly-agent` | **DO NOT** use `Skill(...)` - this will FAIL. Always use `Task`. --- ### Stage 5b: Self-Execution Fallback **CRITICAL**: If you performed the work above WITHOUT using the Agent tool (i.e., you read files, wrote artifacts, or updated metadata directly instead of spawning a subagent), you MUST write a `.return-meta.json` file now before proceeding to postflight. Use the schema from `return-metadata-file.md` with the appropriate status value for this operation. If you DID use the Agent tool, skip this stage -- the subagent already wrote the metadata. --- ## Postflight (ALWAYS EXECUTE) The following stages MUST execute after work is complete, whether the work was done by a subagent or inline (Stage 5b). Do NOT skip these stages for any reason. ### Stage 6: Read Metadata File ```bash metadata_file="specs/${padded_num}_${project_name}/.return-meta.json" if [ -f "$metadata_file" ] && jq empty "$metadata_file" 2>/dev/null; then meta_status=$(jq -r '.status' "$metadata_file") artifact_path=$(jq -r '.artifacts[0].path // ""' "$metadata_file") artifact_type=$(jq -r '.artifacts[0].type // ""' "$metadata_file") artifact_summary=$(jq -r '.artifacts[0].summary // ""' "$metadata_file") else echo "Error: Invalid or missing metadata file" meta_status="failed" fi ``` --- ### Stage 7: Update Task Status (Postflight) | Workflow Type | Meta Status | Final state.json | Final TODO.md | |---------------|-------------|-----------------|---------------| | slides_research | researched | researched | [RESEARCHED] | | slides_research | partial | researching | [RESEARCHING] | | assemble | assembled | completed | [COMPLETED] | | assemble | partial | implementing | [IMPLEMENTING] | | any | failed | (keep preflight) | (keep preflight marker) | --- ### Stage 8: Link Artifacts Add artifact to state.json with summary. Use the two-step jq pattern to avoid Issue #1132. **Update TODO.md**: Link artifact per `@.claude/context/patterns/artifact-linking-todo.md` with `field_name=**Summary**`, `next_field=**Description**`. --- ### Stage 9: Git Commit ```bash case "$workflow_type" in slides_research) commit_action="complete slides research" ;; assemble) # Branch commit message on output_format if [ "$output_format" = "pptx" ]; then commit_action="assemble PPTX presentation" else commit_action="assemble Slidev presentation" fi ;; esac # Targeted staging per .claude/context/standards/git-staging-scope.md — never a repo-wide add padded_num=$(printf "%03d" "$task_number") bash .claude/scripts/git-commit-scoped.sh \ --message "task ${task_number}: ${commit_action}" \ --session "${session_id}" \ --honest-index-rows "${task_number}" \ -- "specs/${padded_num}_${project_name}/" "specs/TODO.md" "specs/state.json" ``` --- ### Stage 10: Cleanup