skill-grant

# Grant Skill Thin wrapper that delegates grant work to `grant-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/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 "present" and task_type is "grant" - Grant workflow requested via flags (--draft, --budget) or /implement routing - Present extension is available --- ## Workflow Type Routing This skill routes to grant-agent with one of five workflow types: | Workflow Type | Preflight Status | Success Status | TODO.md Markers | |---------------|-----------------|----------------|-----------------| | funder_research | researching | researched | [RESEARCHING] -> [RESEARCHED] | | proposal_draft | planning | planned | [PLANNING] -> [PLANNED] | | budget_develop | planning | planned | [PLANNING] -> [PLANNED] | | progress_track | (no change) | (no change) | (no change) | | assemble | implementing | completed | [IMPLEMENTING] -> [COMPLETED] | | fix_it_scan | (no change) | (no change) | (no change) | **Note**: The `assemble` workflow is triggered via `/implement N` command (not `/grant`), which routes to skill-grant when the task type is "present" and task_type is "grant". --- ## Input Parameters ### Required Parameters - `task_number` - Task number (must exist in state.json with language="present" and task_type="grant") - `workflow_type` - One of: funder_research, proposal_draft, budget_develop, progress_track, assemble - `session_id` - Session ID from orchestrator ### Optional Parameters - `focus` - Focus prompt for workflow direction (used by all workflow types) **Prompt Usage by Workflow Type**: | Workflow | focus Parameter | Example | |----------|-----------------|---------| | funder_research | Research focus | "Focus on NIH institutes" | | proposal_draft | Drafting guidance | "Emphasize innovation and methodology" | | budget_develop | Budget guidance | "Include 3 conferences/year, emphasize personnel" | | progress_track | Summary focus | "Focus on budget utilization" | | assemble | Assembly options | "Include executive summary" | --- ## Execution Flow ### Stage 1: Input Validation Validate required inputs: - `task_number` - Must be provided and exist in state.json - `workflow_type` - Must be one of: funder_research, proposal_draft, budget_develop, progress_track, assemble - `focus` - Optional prompt for workflow direction ```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 // "present"') status=$(echo "$task_data" | jq -r '.status') project_name=$(echo "$task_data" | jq -r '.project_name') description=$(echo "$task_data" | jq -r '.description // ""') # Validate language is "present" if [ "$task_type" != "present" ]; then return error "Task $task_number has language '$task_type', expected 'present'" fi # Validate workflow_type case "$workflow_type" in funder_research|proposal_draft|budget_develop|progress_track|assemble|fix_it_scan) ;; *) return error "Invalid workflow_type: $workflow_type. Expected one of: funder_research, proposal_draft, budget_develop, progress_track, assemble, fix_it_scan" ;; esac ``` --- ### Stage 2: Preflight Status Update Update task status based on workflow type BEFORE invoking subagent. **Status Mapping by Workflow Type**: | Workflow Type | state.json status | TODO.md marker | |---------------|------------------|----------------| | funder_research | researching | [RESEARCHING] | | proposal_draft | planning | [PLANNING] | | budget_develop | planning | [PLANNING] | | progress_track | (no change) | (no change) | | assemble | implementing | [IMPLEMENTING] | **Update state.json** (for workflows that change status): ```bash # Determine preflight status based on workflow type case "$workflow_type" in funder_research) preflight_status="researching" preflight_marker="[RESEARCHING]" ;; proposal_draft|budget_develop) preflight_status="planning" preflight_marker="[PLANNING]" ;; progress_track) preflight_status="" # No status change preflight_marker="" ;; assemble) preflight_status="implementing" preflight_marker="[IMPLEMENTING]" ;; fix_it_scan) preflight_status="" # No status change (non-destructive scan) preflight_marker="" ;; esac # Update state.json if status change needed if [ -n "$preflight_status" ]; then jq --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \ --arg status "$preflight_status" \ --arg sid "$session_id" \ '(.active_projects[] | select(.project_number == '$task_number')) |= . + { status: $status, last_updated: $ts, session_id: $sid }' specs/state.json > specs/tmp/state.json && mv specs/tmp/state.json specs/state.json fi ``` **Update TODO.md**: Use Edit tool to change status marker to the workflow-specific in-progress state. **Update plan file** (for assemble workflow only): ```bash # Update plan file status for assemble workflow if [ "$workflow_type" = "assemble" ]; then .opencode/scripts/update-plan-status.sh "$task_number" "$project_name" "IMPLEMENTING" 2>/dev/null || true fi ``` --- ### 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-grant", "task_number": ${task_number}, "operation": "${workflow_type}", "reason": "Postflight pending: status update, artifact linking, git commit", "created": "$(date -u +%Y-%m-%dT%H:%M:%SZ)", "stop_hook_active": false } EOF ``` --- ### Stage 4: Prepare Delegation Context **Extract pre-gathered forcing_data** (if present from Stage 0): ```bash # Extract forcing_data from task metadata forcing_data=$(echo "$task_data" | jq -r '.forcing_data // null') ``` **Detect revision mode** (for assemble workflow): ```bash # Check if task has parent_grant field (indicates revision task) parent_grant=$(echo "$task_data" | jq -r '.parent_grant // ""') revises_directory=$(echo "$task_data" | jq -r '.revises_directory // ""') if [ -n "$parent_grant" ] && [ "$workflow_type" = "assemble" ]; then is_revision="true" # Validate revises_directory exists if [ ! -d "$revises_directory" ]; then return error "Revision target not found: $revises_directory" fi else is_revision="false" revises_directory="" fi ``` Prepare delegation context for the subagent: ```json { "session_id": "sess_{timestamp}_{random}", "delegation_depth": 1, "delegation_path": ["orchestrator", "grant", "skill-grant"], "timeout": 3600, "task_context": { "task_number": N, "task_name": "{project_name}", "description": "{description}", "task_type": "present", "task_type": "grant" }, "workflow_type": "funder_research|proposal_draft|budget_develop|progress_track|assemble", "focus_prompt": "{optional focus - passed to agent for guidance}", "forcing_data": "{pre-gathered forcing data from Stage 0, or null}", "is_revision": "{boolean - true if task has parent_grant field}", "revises_directory": "{grants/{N}_{slug}/ - path to existing grant if revision}", "metadata_file_path": "specs/{NNN}_{SLUG}/.return-meta.json" } ``` --- ### 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: "grant-agent" - prompt: [Include task_context, delegation_context, workflow_type, focus_prompt, is_revision, revises_directory, metadata_file_path] - description: "Execute {workflow_type} workflow for task {N}" ``` **DO NOT** use `Skill(grant-agent)` - this will FAIL. The subagent will: - Execute the specified workflow (funder_research, proposal_draft, budget_develop, progress_track, assemble) - Use the focus_prompt to guide its output - Create workflow-specific artifacts in `specs/{NNN}_{SLUG}/{subdir}/` - Write metadata to `specs/{NNN}_{SLUG}/.return-meta.json` - Return a brief text summary (NOT JSON) --- ### Stage 5a: Validate Return Format Validate the return format: ``` If subagent returned JSON to console: - Log warning: "Subagent returned JSON to console instead of brief summary" - Continue with metadata file parsing (Stage 6) If subagent returned brief text summary: - This is expected behavior - Continue to Stage 6 ``` --- ### 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 the appropriate status value for this operation. If you DID use the Task 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 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 meta_status=$(jq -r '.status' "$metadata_file")