admin/sp80
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
sp80/.opencode/get-shit-done/workflows/execute-plan.md
admin e72a3ab85c Add everything and anything
2026-03-13 15:46:10 +08:00

18 KiB
Raw Permalink Blame History

Execute a phase prompt (PLAN.md) and create the outcome summary (SUMMARY.md).

<required_reading> read STATE.md before any operation to load project context. read config.json for planning behavior settings.

@./.opencode/get-shit-done/references/git-integration.md </required_reading>

Load execution context (paths only to minimize orchestrator context): 
INIT=$(node "./.opencode/get-shit-done/bin/gsd-tools.cjs" init execute-phase "${PHASE}")
if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi

Extract from init JSON: executor_model, commit_docs, phase_dir, phase_number, plans, summaries, incomplete_plans, state_path, config_path.

If .planning/ missing: error.

```bash # Use plans/summaries from INIT JSON, or list files ls .planning/phases/XX-name/*-PLAN.md 2>/dev/null | sort ls .planning/phases/XX-name/*-SUMMARY.md 2>/dev/null | sort ```

Find first PLAN without matching SUMMARY. Decimal phases supported (01.1-hotfix/):

PHASE=$(echo "$PLAN_PATH" | grep -oE '[0-9]+(\.[0-9]+)?-[0-9]+')
# config settings can be fetched via gsd-tools config-get if needed
Auto-approve: `⚡ Execute {phase}-{plan}-PLAN.md [Plan X of Y for Phase Z]` → parse_segments. Present plan identification, wait for confirmation. ```bash PLAN_START_TIME=$(date -u +"%Y-%m-%dT%H:%M:%SZ") PLAN_START_EPOCH=$(date +%s) ``` ```bash grep -n "type=\"checkpoint" .planning/phases/XX-name/{phase}-{plan}-PLAN.md ```

Routing by checkpoint type:

Checkpoints Pattern Execution
None A (autonomous) Single subagent: full plan + SUMMARY + commit
Verify-only B (segmented) Segments between checkpoints. After none/human-verify → SUBAGENT. After decision/human-action → MAIN
Decision C (main) Execute entirely in main context

Pattern A: init_agent_tracking → spawn task(subagent_type="gsd-executor", model=executor_model) with prompt: execute plan at [path], autonomous, all tasks + SUMMARY + commit, follow deviation/auth rules, report: plan name, tasks, SUMMARY path, commit hash → track agent_id → wait → update tracking → report.

Pattern B: Execute segment-by-segment. Autonomous segments: spawn subagent for assigned tasks only (no SUMMARY/commit). Checkpoints: main context. After all segments: aggregate, create SUMMARY, commit. See segment_execution.

Pattern C: Execute in main using standard flow (step name="execute").

Fresh context per subagent preserves peak quality. Main context stays lean.

```bash if [ ! -f .planning/agent-history.json ]; then echo '{"version":"1.0","max_entries":50,"entries":[]}' > .planning/agent-history.json fi rm -f .planning/current-agent-id.txt if [ -f .planning/current-agent-id.txt ]; then INTERRUPTED_ID=$(cat .planning/current-agent-id.txt) echo "Found interrupted agent: $INTERRUPTED_ID" fi ```

If interrupted: ask user to resume (task resume parameter) or start fresh.

Tracking protocol: On spawn: write agent_id to current-agent-id.txt, append to agent-history.json: {"agent_id":"[id]","task_description":"[desc]","phase":"[phase]","plan":"[plan]","segment":[num|null],"timestamp":"[ISO]","status":"spawned","completion_timestamp":null}. On completion: status → "completed", set completion_timestamp, delete current-agent-id.txt. Prune: if entries > max_entries, remove oldest "completed" (never "spawned").

Run for Pattern A/B before spawning. Pattern C: skip.

Pattern B only (verify-only checkpoints). Skip for A/C.

  1. Parse segment map: checkpoint locations and types

  2. Per segment:

    • Subagent route: spawn gsd-executor for assigned tasks only. Prompt: task range, plan path, read full plan for context, execute assigned tasks, track deviations, NO SUMMARY/commit. Track via agent protocol.
    • Main route: execute tasks using standard flow (step name="execute")

  3. After ALL segments: aggregate files/deviations/decisions → create SUMMARY.md → commit → self-check:

    • Verify key-files.created exist on disk with [ -f ]
    • Check git log --oneline --all --grep="{phase}-{plan}" returns ≥1 commit
    • Append ## Self-Check: PASSED or ## Self-Check: FAILED to SUMMARY

    Known OpenCode bug (classifyHandoffIfNeeded): If any segment agent reports "failed" with classifyHandoffIfNeeded is not defined, this is a OpenCode runtime bug — not a real failure. Run spot-checks; if they pass, treat as successful.

```bash cat .planning/phases/XX-name/{phase}-{plan}-PLAN.md ``` This IS the execution instructions. Follow exactly. If plan references CONTEXT.md: honor user's vision throughout.

If plan contains <interfaces> block: These are pre-extracted type definitions and contracts. Use them directly — do NOT re-read the source files to discover types. The planner already extracted what you need.

```bash node "./.opencode/get-shit-done/bin/gsd-tools.cjs" phases list --type summaries --raw # Extract the second-to-last summary from the JSON result ``` If previous SUMMARY has unresolved "Issues Encountered" or "Next Phase Readiness" blockers: question(header="Previous Issues", options: "Proceed anyway" | "Address first" | "Review previous"). Deviations are normal — handle via rules below.
  1. read @context files from prompt
  2. Per task:
    • type="auto": if tdd="true" → TDD execution. Implement with deviation rules + auth gates. Verify done criteria. Commit (see task_commit). Track hash for Summary.
    • type="checkpoint:*": STOP → checkpoint_protocol → wait for user → continue only after confirmation.
  3. Run <verification> checks
  4. Confirm <success_criteria> met
  5. Document deviations in Summary

<authentication_gates>

Authentication Gates

Auth errors during execution are NOT failures — they're expected interaction points.

Indicators: "Not authenticated", "Unauthorized", 401/403, "Please run {tool} login", "Set {ENV_VAR}"

Protocol:

  1. Recognize auth gate (not a bug)
  2. STOP task execution
  3. Create dynamic checkpoint:human-action with exact auth steps
  4. Wait for user to authenticate
  5. Verify credentials work
  6. Retry original task
  7. Continue normally

Example: vercel --yes → "Not authenticated" → checkpoint asking user to vercel login → verify with vercel whoami → retry deploy → continue

In Summary: Document as normal flow under "## Authentication Gates", not as deviations.

</authentication_gates>

<deviation_rules>

Deviation Rules

You WILL discover unplanned work. Apply automatically, track all for Summary.

Rule Trigger Action Permission
1: Bug Broken behavior, errors, wrong queries, type errors, security vulns, race conditions, leaks Fix → test → verify → track [Rule 1 - Bug] Auto
2: Missing Critical Missing essentials: error handling, validation, auth, CSRF/CORS, rate limiting, indexes, logging Add → test → verify → track [Rule 2 - Missing Critical] Auto
3: Blocking Prevents completion: missing deps, wrong types, broken imports, missing env/config/files, circular deps Fix blocker → verify proceeds → track [Rule 3 - Blocking] Auto
4: Architectural Structural change: new DB table, schema change, new service, switching libs, breaking API, new infra STOP → present decision (below) → track [Rule 4 - Architectural] Ask user

Rule 4 format:

⚠️ Architectural Decision Needed

Current task: [task name]
Discovery: [what prompted this]
Proposed change: [modification]
Why needed: [rationale]
Impact: [what this affects]
Alternatives: [other approaches]

Proceed with proposed change? (yes / different approach / defer)

Priority: Rule 4 (STOP) > Rules 1-3 (auto) > unsure → Rule 4 Edge cases: missing validation → R2 | null crash → R1 | new table → R4 | new column → R1/2 Heuristic: Affects correctness/security/completion? → R1-3. Maybe? → R4.

</deviation_rules>

<deviation_documentation>

Documenting Deviations

Summary MUST include deviations section. None? → ## Deviations from Plan\n\nNone - plan executed exactly as written.

Per deviation: [Rule N - Category] Title — Found during: task X | Issue | Fix | Files modified | Verification | Commit hash

End with: Total deviations: N auto-fixed (breakdown). Impact: assessment.

</deviation_documentation>

<tdd_plan_execution>

TDD Execution

For type: tdd plans — RED-GREEN-REFACTOR:

  1. Infrastructure (first TDD plan only): detect project, install framework, config, verify empty suite
  2. RED: read <behavior> → failing test(s) → run (MUST fail) → commit: test({phase}-{plan}): add failing test for [feature]
  3. GREEN: read <implementation> → minimal code → run (MUST pass) → commit: feat({phase}-{plan}): implement [feature]
  4. REFACTOR: Clean up → tests MUST pass → commit: refactor({phase}-{plan}): clean up [feature]

Errors: RED doesn't fail → investigate test/existing feature. GREEN doesn't pass → debug, iterate. REFACTOR breaks → undo.

See ./.opencode/get-shit-done/references/tdd.md for structure. </tdd_plan_execution>

<task_commit>

task Commit Protocol

After each task (verification passed, done criteria met), commit immediately.

1. Check: git status --short

2. Stage individually (NEVER git add . or git add -A):

git add src/api/auth.ts
git add src/types/user.ts

3. Commit type:

Type When Example
feat New functionality feat(08-02): create user registration endpoint
fix Bug fix fix(08-02): correct email validation regex
test Test-only (TDD RED) test(08-02): add failing test for password hashing
refactor No behavior change (TDD REFACTOR) refactor(08-02): extract validation to helper
perf Performance perf(08-02): add database index
docs Documentation docs(08-02): add API docs
style Formatting style(08-02): format auth module
chore Config/deps chore(08-02): add bcrypt dependency

4. Format: {type}({phase}-{plan}): {description} with bullet points for key changes.

5. Record hash:

TASK_COMMIT=$(git rev-parse --short HEAD)
TASK_COMMITS+=("task ${TASK_NUM}: ${TASK_COMMIT}")

</task_commit>

On `type="checkpoint:*"`: automate everything possible first. Checkpoints are for verification/decisions only.

Display: CHECKPOINT: [Type] box → Progress {X}/{Y} → task name → type-specific content → YOUR ACTION: [signal]

Type Content Resume signal
human-verify (90%) What was built + verification steps (commands/URLs) "approved" or describe issues
decision (9%) Decision needed + context + options with pros/cons "Select: option-id"
human-action (1%) What was automated + ONE manual step + verification plan "done"

After response: verify if specified. Pass → continue. Fail → inform, wait. WAIT for user — do NOT hallucinate completion.

See ./.opencode/get-shit-done/references/checkpoints.md for details.

When spawned via task and hitting checkpoint: return structured state (cannot interact with user directly).

Required return: 1) Completed Tasks table (hashes + files) 2) Current task (what's blocking) 3) Checkpoint Details (user-facing content) 4) Awaiting (what's needed from user)

Orchestrator parses → presents to user → spawns fresh continuation with your completed tasks state. You will NOT be resumed. In main context: use checkpoint_protocol above.

If verification fails: STOP. Present: "Verification failed for task [X]: [name]. Expected: [criteria]. Actual: [result]." Options: Retry | Skip (mark incomplete) | Stop (investigate). If skipped → SUMMARY "Issues Encountered". ```bash PLAN_END_TIME=$(date -u +"%Y-%m-%dT%H:%M:%SZ") PLAN_END_EPOCH=$(date +%s)

DURATION_SEC=$(( PLAN_END_EPOCH - PLAN_START_EPOCH )) DURATION_MIN=$(( DURATION_SEC / 60 ))

if $DURATION_MIN -ge 60 ; then HRS=$(( DURATION_MIN / 60 )) MIN=$(( DURATION_MIN % 60 )) DURATION="${HRS}h ${MIN}m" else DURATION="${DURATION_MIN} min" fi

</step>

<step name="generate_user_setup">
```bash
grep -A 50 "^user_setup:" .planning/phases/XX-name/{phase}-{plan}-PLAN.md | head -50

If user_setup exists: create {phase}-USER-SETUP.md using template ./.opencode/get-shit-done/templates/user-setup.md. Per service: env vars table, account setup checklist, dashboard config, local dev notes, verification commands. Status "Incomplete". Set USER_SETUP_CREATED=true. If empty/missing: skip.

Create `{phase}-{plan}-SUMMARY.md` at `.planning/phases/XX-name/`. Use `./.opencode/get-shit-done/templates/summary.md`.

Frontmatter: phase, plan, subsystem, tags | requires/provides/affects | tech-stack.added/patterns | key-files.created/modified | key-decisions | requirements-completed (MUST copy requirements array from PLAN.md frontmatter verbatim) | duration ($DURATION), completed ($PLAN_END_TIME date).

Title: # Phase [X] Plan [Y]: [Name] Summary

One-liner SUBSTANTIVE: "JWT auth with refresh rotation using jose library" not "Authentication implemented"

Include: duration, start/end times, task count, file count.

Next: more plans → "Ready for {next-plan}" | last → "Phase complete, ready for transition".

Update STATE.md using gsd-tools: 
# Advance plan counter (handles last-plan edge case)
node "./.opencode/get-shit-done/bin/gsd-tools.cjs" state advance-plan

# Recalculate progress bar from disk state
node "./.opencode/get-shit-done/bin/gsd-tools.cjs" state update-progress

# Record execution metrics
node "./.opencode/get-shit-done/bin/gsd-tools.cjs" state record-metric \
  --phase "${PHASE}" --plan "${PLAN}" --duration "${DURATION}" \
  --tasks "${TASK_COUNT}" --files "${FILE_COUNT}"
From SUMMARY: Extract decisions and add to STATE.md: 
# Add each decision from SUMMARY key-decisions
# Prefer file inputs for shell-safe text (preserves `$`, `*`, etc. exactly)
node "./.opencode/get-shit-done/bin/gsd-tools.cjs" state add-decision \
  --phase "${PHASE}" --summary-file "${DECISION_TEXT_FILE}" --rationale-file "${RATIONALE_FILE}"

# Add blockers if any found
node "./.opencode/get-shit-done/bin/gsd-tools.cjs" state add-blocker --text-file "${BLOCKER_TEXT_FILE}"
Update session info using gsd-tools: 
node "./.opencode/get-shit-done/bin/gsd-tools.cjs" state record-session \
  --stopped-at "Completed ${PHASE}-${PLAN}-PLAN.md" \
  --resume-file "None"

Keep STATE.md under 150 lines.

If SUMMARY "Issues Encountered" ≠ "None": yolo → log and continue. Interactive → present issues, wait for acknowledgment. ```bash node "./.opencode/get-shit-done/bin/gsd-tools.cjs" roadmap update-plan-progress "${PHASE}" ``` Counts PLAN vs SUMMARY files on disk. Updates progress table row with correct count and status (`In Progress` or `Complete` with date). Mark completed requirements from the PLAN.md frontmatter `requirements:` field: 
node "./.opencode/get-shit-done/bin/gsd-tools.cjs" requirements mark-complete ${REQ_IDS}

Extract requirement IDs from the plan's frontmatter (e.g., requirements: [AUTH-01, AUTH-02]). If no requirements field, skip.

task code already committed per-task. Commit plan metadata: 
node "./.opencode/get-shit-done/bin/gsd-tools.cjs" commit "docs({phase}-{plan}): complete [plan-name] plan" --files .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md .planning/STATE.md .planning/ROADMAP.md .planning/REQUIREMENTS.md
If .planning/codebase/ doesn't exist: skip. 
FIRST_TASK=$(git log --oneline --grep="feat({phase}-{plan}):" --grep="fix({phase}-{plan}):" --grep="test({phase}-{plan}):" --reverse | head -1 | cut -d' ' -f1)
git diff --name-only ${FIRST_TASK}^..HEAD 2>/dev/null

Update only structural changes: new src/ dir → STRUCTURE.md | deps → STACK.md | file pattern → CONVENTIONS.md | API client → INTEGRATIONS.md | config → STACK.md | renamed → update paths. Skip code-only/bugfix/content changes.

node "./.opencode/get-shit-done/bin/gsd-tools.cjs" commit "" --files .planning/codebase/*.md --amend
If `USER_SETUP_CREATED=true`: display `⚠️ USER SETUP REQUIRED` with path + env/config tasks at TOP. 
ls -1 .planning/phases/[current-phase-dir]/*-PLAN.md 2>/dev/null | wc -l
ls -1 .planning/phases/[current-phase-dir]/*-SUMMARY.md 2>/dev/null | wc -l
Condition Route Action
summaries < plans A: More plans Find next PLAN without SUMMARY. Yolo: auto-continue. Interactive: show next plan, suggest /gsd-execute-phase {phase} + /gsd-verify-work. STOP here.
summaries = plans, current < highest phase B: Phase done Show completion, suggest /gsd-plan-phase {Z+1} + /gsd-verify-work {Z} + /gsd-discuss-phase {Z+1}
summaries = plans, current = highest phase C: Milestone done Show banner, suggest /gsd-complete-milestone + /gsd-verify-work + /gsd-add-phase

All routes: /new first for fresh context.

<success_criteria>

  • All tasks from PLAN.md completed
  • All verifications pass
  • USER-SETUP.md generated if user_setup in frontmatter
  • SUMMARY.md created with substantive content
  • STATE.md updated (position, decisions, issues, session)
  • ROADMAP.md updated
  • If codebase map exists: map updated with execution changes (or skipped if no significant changes)
  • If USER-SETUP.md created: prominently surfaced in completion output </success_criteria>
Reference in New Issue View Git Blame Copy Permalink