skill-implementer

# Implementer Skill Thin wrapper that delegates general implementation to `general-implementation-agent` subagent. **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: `.opencode/context/formats/return-metadata-file.md` - Metadata file schema - Path: `.opencode/context/patterns/postflight-control.md` - Marker file protocol - Path: `.opencode/context/patterns/subagent-continuation-loop.md` - Continuation loop pattern - Path: `.opencode/context/patterns/context-exhaustion-detection.md` - Context exhaustion heuristics - Path: `.opencode/context/patterns/file-metadata-exchange.md` - File I/O helpers - Path: `.opencode/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: - Task type is "general", "meta", or "markdown" - /implement command is invoked - Plan exists and task is ready for implementation --- ## Execution Flow ### Stage 1: Input Validation Validate required inputs: - `task_number` - Must be provided and exist in state.json - Task status must allow implementation (planned, implementing, partial) ```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 // "general"') status=$(echo "$task_data" | jq -r '.status') project_name=$(echo "$task_data" | jq -r '.project_name') description=$(echo "$task_data" | jq -r '.description // ""') # Validate status (only block terminal states) if [ "$status" = "completed" ] || [ "$status" = "abandoned" ] || [ "$status" = "expanded" ]; then return error "Task is in terminal state [$status]" fi ``` --- ### Stage 2: Preflight Status Update Update task status to "implementing" BEFORE invoking subagent. Run the centralized status update script, which atomically updates state.json, TODO.md (task entry + Task Order), and the plan file: ```bash bash .opencode/scripts/update-task-status.sh preflight "$task_number" implement "$session_id" ``` **Note**: The script handles all three updates (state.json status/timestamps/session_id, TODO.md `[PLANNED]` -> `[IMPLEMENTING]` in both task entry and Task Order, and plan file status -> `[IMPLEMENTING]`) in a single call. No additional Edit or jq operations are needed. --- ### Stage 3: Create Postflight Marker Create the marker file to prevent premature termination: ```bash # Ensure task directory exists padded_num=$(printf "%03d" "$task_number") mkdir -p "specs/${padded_num}_${project_name}" cat > "specs/${padded_num}_${project_name}/.postflight-pending" << EOF { "session_id": "${session_id}", "skill": "skill-implementer", "task_number": ${task_number}, "operation": "implement", "reason": "Postflight pending: status update, artifact linking, git commit", "created": "$(date -u +%Y-%m-%dT%H:%M:%SZ)", "stop_hook_active": false } EOF ``` --- ### Stage 3a: Calculate Artifact Number Read `next_artifact_number` from state.json and use (current-1) since summary stays in the same round as research/plan: ```bash # Read next_artifact_number from state.json next_num=$(jq -r --argjson num "$task_number" \ '.active_projects[] | select(.project_number == $num) | .next_artifact_number // 1' \ specs/state.json) # Implement uses (current - 1) to stay in the same round as research/plan # If next_artifact_number is 1 (no research yet), use 1 if [ "$next_num" -le 1 ]; then artifact_number=1 else artifact_number=$((next_num - 1)) fi # Fallback for legacy tasks: count existing summary artifacts if [ "$next_num" = "null" ] || [ -z "$next_num" ]; then padded_num=$(printf "%03d" "$task_number") count=$(ls "specs/${padded_num}_${project_name}/summaries/"*[0-9][0-9]*.md 2>/dev/null | wc -l) artifact_number=$((count + 1)) fi artifact_padded=$(printf "%02d" "$artifact_number") ``` **Note**: Implement does NOT increment `next_artifact_number`. Only research advances the sequence. --- ### Stage 4a: Memory Retrieval (Auto) Retrieve relevant memories from the memory system to inject into the delegation context. **Skip if**: `clean_flag` is true in the delegation context (from `--clean` command flag). ```bash # Check clean_flag if [ "$clean_flag" != "true" ]; then memory_context=$(bash .opencode/scripts/memory-retrieve.sh "$description" "$task_type" "" 2>/dev/null) || memory_context="" fi # memory_context will be empty string if: # - clean_flag is true (skipped) # - memory-index.json missing or empty # - no keywords matched any entries # - script exited with error ``` If `memory_context` is non-empty, it will be injected into the Stage 5 prompt alongside the format specification from Stage 4b. If empty, no memory block is injected. --- ### Stage 4: Prepare Delegation Context Prepare delegation context for the subagent: ```json { "session_id": "sess_{timestamp}_{random}", "delegation_depth": 1, "delegation_path": ["orchestrator", "implement", "skill-implementer"], "timeout": 7200, "task_context": { "task_number": N, "task_name": "{project_name}", "description": "{description}", "task_type": "{task_type}" }, "artifact_number": "{artifact_number from Stage 3a}", "effort_flag": "{effort_flag from command, null if not set}", "model_flag": "{model_flag from command, null if not set}", "plan_path": "specs/{NNN}_{SLUG}/plans/MM_{short-slug}.md", "metadata_file_path": "specs/{NNN}_{SLUG}/.return-meta.json" } ``` **Note**: The `artifact_number` field tells the agent which sequence number to use for artifact naming (e.g., `01`, `02`). Summary uses the same round number as the research and plan that preceded it. **Model/Effort Flags**: If `model_flag` is set (haiku, sonnet, opus), pass it as the `model` parameter on the Task tool to override the agent's frontmatter default. If `effort_flag` is set (fast, hard), include it as prompt context for reasoning depth guidance. > **CRITICAL: No Source Reading Before Delegation** -- Between preparing the delegation context (Stage 4) and spawning the sub-agent (Stage 5), the lead skill MUST NOT read, grep, glob, or analyze source files. The plan file and state.json are the only files the lead reads. All codebase exploration (reading source files, grepping for patterns, using MCP tools) is the exclusive responsibility of the sub-agent after it is spawned. --- ### Stage 4b: Read and Inject Format Specification Read the summary format file and prepare it for injection into the subagent prompt. This ensures the subagent always has the full format specification in its context, regardless of whether it reads the file itself. ```bash format_content=$(cat .opencode/context/formats/summary-format.md) ``` The format content will be included as a delimited section in the Stage 5 prompt (see below). --- ### Stage 5: Invoke Subagent **CRITICAL**: You MUST use the **Task** tool to spawn the subagent. **Required Tool Invocation**: ``` Tool: Task (NOT Skill) Parameters: - subagent_type: "general-implementation-agent" - prompt: [Include task_context, delegation_context, plan_path, metadata_file_path, AND the format specification from Stage 4b as shown below] - description: "Execute implementation for task {N}" ``` **Format Injection**: Include the format specification from Stage 4b in the prompt as a clearly-delimited section: ``` <artifact-format-specification> ## CRITICAL: Summary Format Requirements You MUST follow this format specification exactly when writing the implementation summary. Non-compliance will be caught by postflight validation. {format_content from Stage 4b} </artifact-format-specification> ``` Place this section AFTER the delegation context JSON and BEFORE any other instructions. **Memory Context Injection**: If `memory_context` from Stage 4a is non-empty, include it in the prompt as a separate block: ``` {memory_context from Stage 4a -- already wrapped in <memory-context> tags} ``` Place the memory context block AFTER the format specification and BEFORE the task-specific instructions. Do NOT inject an empty `<memory-context>` block when no memories were retrieved. **DO NOT** use `Skill(general-implementation-agent)` - this will FAIL. The subagent will: - Load implementation context files - Parse plan and find resume point - Execute phases sequentially - Create/modify files as needed - Create implementation summary - Write metadata to `specs/{NNN}_{SLUG}/.return-meta.json` - Return a brief text summary (NOT JSON) --- ### Stage 5a: Validate Subagent Return Format If the subagent's text return parses as valid JSON, log a warning (v1 pattern instead of v2 file-based pattern). Non-blocking -- continue to read metadata file regardless. --- ### Stage 5b: Self-Execution Fallback **CRITICAL**: If you performed the work above WITHOUT using the Task 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 status value `"implemented"` and the appropriate artifact information. If you DID use the Task tool (Stage 5), skip this stage -- the subagent already wrote the metadata. --- ### Stage 5c: Continuation Loop Init Initialize continuation tracking before entering the postflight loop: ```bash continuation_count=0 max_continuations=3 # Create loop-guard file to track count across potential interruptions task_dir="specs/${padded_num}_${project_name}" cat > "${task_dir}/.continuation-loop-guard" << EOF { "session_id": "${session_id}", "continuation_count": 0, "max_continuations": 3, "created": "$(date -u +%Y-%m-%dT%H:%M:%SZ)" } EOF ``` **Note**: The loop guard ensures that even if the skill is interrupted between iterations, the next invocation can read the count and enforce the limit. --- ## Postflight (ALWAYS EXECUTE) The following stages MUST execute after work is complete, whether the work was done by a subagent (Stage 5) or inline (Stage 5b). Do NOT skip these stages for any reason. ### Continuation Loop The postflight stages below run inside a loop. Each iteration processes the return from one subagent execution. If the subagent returns `partial` with a `handoff_path`, a successor subagent is spawned and the loop continues (up to `max_continuations`). ``` while true; do ``` #### Stage 6: Parse Subagent Return (Read Metadata File) Read the 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 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") phases_completed=$(jq -r '.metadata.phases_completed // 0' "$metadata_file") phases_total=$(jq -r '.metadata.phases_total // 0' "$metadata_file") # Extract completion_data fields (if present) completion_summary=$(jq -r '.completion_data.completion_summary // ""' "$metadata_file") roadmap_items=$(jq -c '.completion_data.roadmap_items // []' "$metadata_file") memory_candidates=$(jq -c '.memory_candidates // []' "$metadata_file") # Extract handoff_path for continuation loop (if present) handoff_path=$(jq -r '.partial_progress.handoff_path // ""' "$metadata_file") else echo "Error: Invalid or missing metadata file" status="failed" fi ``` --- ### Stage 6a: Validate Artifact Content