/os-tk-proposal

Inputs

• Request text (from $ARGUMENTS)
• Optional --id <change-id>
• Optional --require-plan (enforce approved plan gate)
• Optional --validate-plan (validate specific plan id)
• Optional --plan-id <id> (plan id to validate/require)

Resolve skill dir (for scripts)

SKILL_DIR=".pi/skills/os-tk-proposal"
if [[ ! -d "$SKILL_DIR" ]]; then SKILL_DIR="pi/skills/os-tk-proposal"; fi

Parse arguments

• eval "$(bash "$SKILL_DIR/scripts/parse-args.sh" "$@")" to populate:

- CHANGEID, REQUEST - REQUIREPLAN, VALIDATEPLAN, PLANID

Resolve plan id (NEW)

If PLAN_ID is empty, try to resolve automatically:

1. Check dev notes for Plan ID: line in .os-tk/dev-notes/<change-id>.md
2. Fall back to most recent file in .os-tk/plans/

if [[ -z "$PLAN_ID" ]]; then
  PLAN_ID=$(bash "$SKILL_DIR/scripts/resolve-plan-id.sh" --change-id "$CHANGE_ID" || true)
fi

If still empty:

• Continue without plan context (unless --require-plan is set)

Allocate change id (4 digits)

If CHANGE_ID is empty:

• eval "$(bash "$SKILL_DIR/scripts/allocate-change-id.sh" "$REQUEST")"

Ensure change folder

• bash "$SKILL_DIR/scripts/ensure-change-folder.sh"

Check for approved plan (NEW)

Run:

PLAN_TO_VALIDATE="${PLAN_ID:-$CHANGE_ID}"

bash "$SKILL_DIR/scripts/check-approved-plan.sh" \
  $( [[ "$REQUIRE_PLAN" == "true" ]] && echo "--require-plan" ) \
  $( [[ "$VALIDATE_PLAN" == "true" ]] && echo "--validate-plan" ) \
  $( [[ -n "$PLAN_TO_VALIDATE" ]] && echo "--plan-id $PLAN_TO_VALIDATE" )

• If plan required and not approved, error out and suggest creating plan
• If plan is marked pending/rejected, proposal is blocked until approved
• If validate-plan set, ensures specific plan is approved

Load plan file (NEW)

If PLAN_ID is set, load the persisted plan file for context:

PLAN_FILE=$(bash "$SKILL_DIR/scripts/get-plan-file.sh" --plan-id "$PLAN_ID")
PLAN_TEXT=$(cat "$PLAN_FILE")

If PLAN_ID was auto-resolved, note this in logs and continue.

Use this plan content as additional context for proposal writing.

Dev notes (mandatory when enabled)

• bash "$SKILLDIR/scripts/ensure-dev-notes.sh" (requires CHANGEID)

Scaffold proposal + specs + design + tasks

Run:

• bash "$SKILL_DIR/scripts/write-proposal.sh"
• bash "$SKILL_DIR/scripts/write-specs.sh"
• bash "$SKILL_DIR/scripts/write-design.sh"
• bash "$SKILL_DIR/scripts/write-tasks.sh"

These create skeleton files which the planner will overwrite with real content.

Parallel scouting + proposal writing (single subagent chain)

Use pi-async-subagents tool subagent with a parallel-in-chain fan-out/fan-in.

Important:

• The planner must NOT spawn any subagents.
• This chain is sync (async: false) because it includes a parallel step.

subagent({
  "agentScope": "both",
  "async": false,
  "chain": [
    {
      "parallel": [
        {
          "agent": "os-tk-repo-scout",
          "task": "Find existing patterns, conventions, related code paths, and test patterns relevant to: {task}"
        },
        {
          "agent": "os-tk-librarian",
          "task": "DOCS mode: Find official docs, breaking changes, and examples relevant to: {task}"
        }
      ],
      "concurrency": 2,
      "failFast": false
    },
    {
      "agent": "os-tk-planner",
      "task": "Create/update the OpenSpec change docs for ${CHANGE_ID}.\n\nRequest: ${REQUEST}\nChange: ${CHANGE_ID}\n\nPlan (if provided):\n${PLAN_TEXT}\n\nScout findings:\n{previous}\n\nDo the following (NO product code changes):\n1) Replace the scaffold content in:\n   - openspec/changes/${CHANGE_ID}/proposal.md\n   - openspec/changes/${CHANGE_ID}/specs/** (delta specs with ADDED/MODIFIED/REMOVED sections)\n   - openspec/changes/${CHANGE_ID}/design.md\n   - openspec/changes/${CHANGE_ID}/tasks.md\n2) Keep tasks small and focused, each with clear acceptance criteria.\n3) Add explicit exclusions (what NOT to change) to proposal.md.\n4) Ensure specs include Given/When/Then scenarios for key requirements.\n5) If dev-notes are enabled, update .os-tk/dev-notes/${CHANGE_ID}.md with decisions + validated snippets + open questions.\n\nDo NOT create tk tickets (that's /os-tk-bootstrap)."
    },
    {
      "agent": "os-tk-gap-analyst",
      "task": "Review the proposal/specs/design/tasks for gaps. Request: ${REQUEST}. Change: ${CHANGE_ID}.\n\nRead the files under openspec/changes/${CHANGE_ID}/ (proposal.md, specs/**, design.md, tasks.md) and report missing requirements, edge cases, risks, and tests."
    },
    {
      "agent": "os-tk-planner",
      "task": "Apply the gap analysis below to the OpenSpec change docs for ${CHANGE_ID}.\n\nGap analysis:\n{previous}\n\nUpdate (in place):\n- openspec/changes/${CHANGE_ID}/proposal.md\n- openspec/changes/${CHANGE_ID}/specs/**\n- openspec/changes/${CHANGE_ID}/design.md\n- openspec/changes/${CHANGE_ID}/tasks.md\n\nIf you change scope/assumptions, reflect them in proposal.md and dev-notes (if enabled)."
    }
  ]
})

Validate

• bash "$SKILL_DIR/scripts/validate-change.sh"

Stop condition

STOP after writing proposal/specs/design/tasks and validation. Ask the user to review:

• openspec/changes/${CHANGE_ID}/proposal.md
• openspec/changes/${CHANGE_ID}/specs/**
• openspec/changes/${CHANGE_ID}/design.md
• openspec/changes/${CHANGE_ID}/tasks.md

Prohibited

• No ticket creation (that’s /os-tk-bootstrap).
• No product code changes.