skill-grant

name	skill-grant
description	Grant proposal research and drafting with funder analysis. Invoke for grant tasks.
allowed-tools	Agent, Bash, Edit, Read, Write, AskUserQuestion

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: .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:

• 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

# 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):

# 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
  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

Update TODO.md: Use Edit tool to change status marker to the workflow-specific in-progress state.

Update plan file (for assemble workflow only):

# Update plan file status for assemble workflow
if [ "$workflow_type" = "assemble" ]; then
    .claude/scripts/update-plan-status.sh "$task_number" "$project_name" "IMPLEMENTING" 2>/dev/null || true
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, including the progress_track and fix_it_scan no-status-change cases, is a domain-specific behavior this conversion does not restructure), only the marker write itself moves onto the shared function:

source .claude/scripts/skill-base.sh
padded_num=$(printf "%03d" "$task_number")
skill_name="skill-grant"
skill_create_postflight_marker "$padded_num" "$project_name" "$session_id" "$skill_name" "$workflow_type"

---

Stage 4: Prepare Delegation Context

Extract pre-gathered forcing_data (if present from Stage 0):

# Extract forcing_data from task metadata
forcing_data=$(echo "$task_data" | jq -r '.forcing_data // null')

Detect revision mode (for assemble workflow):

# 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:

{
  "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 Agent tool to spawn the subagent.

Required Tool Invocation:

Tool: Agent (NOT Skill, NOT Plan)
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 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

Read the metadata file:

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")