execution

Category: Testing & Security | Uploader: hack-ink | Downloads: 0 | Version: v1.0（Latest）
Use inside the plan plugin when the user wants to execute an existing implementation plan, continue from the authoritative Linear issue plan, or resume work after leaving Plan mode. Consumes the routed Linear issue identity plus the canonical linked-document `tracked-plan/1`, requires valid tracked-plan and plan-event helpers before execution, updates only tracked-plan runtime state, and appends validated progress events instead of inferring authority from chat.
Changelog: Source: GitHub https://github.com/hack-ink/codexlab
Directory Structure

Current level: tree/main/.codex/plugins/plan/skills/execution/
📄 SKILL.md 9.0 KB
SKILL.md

---
name: execution
description: Use inside the plan plugin when the user wants to execute an existing implementation plan, continue from the authoritative Linear issue plan, or resume work after leaving Plan mode. Consumes the routed Linear issue identity plus the canonical linked-document `tracked-plan/1`, requires valid tracked-plan and plan-event helpers before execution, updates only tracked-plan runtime state, and appends validated progress events instead of inferring authority from chat.
---

# Plan Execution

## Scope

- This plugin-local skill is the canonical consumer stage of the tracked-plan workflow.
- It consumes the routed Linear issue identity plus the canonical linked Linear document.
- It owns only runtime state transitions and append-only progress events.
- It must not repair or rewrite strategy itself.

Typical triggers:

- The user says "execute this plan" or links the authoritative Linear issue
- Work should continue from the current plan snapshot on the routed Linear issue
- A separate session is asked to implement a tracked plan
- A previously blocked tracked plan now needs to resume from its latest Linear state

## Plugin-owned assets

Use the plugin-local assets in this plugin as the contract surface:

- `templates/linked-plan-document.md`
- `templates/progress-event.md`
- `scripts/validate_tracked_plan.py`
- `scripts/read_tracked_plan.py`
- `scripts/validate_plan_event.py`
- `scripts/read_plan_events.py`
- `scripts/validate_execution_surface.py`
- `scripts/read_execution_surface.py`

## Hard gates

- Do not infer execution authority from chat, branch names, or earlier conversational plans.
- If there is no authoritative routed Linear issue, stop and route back to `writing`.
- If there is no linked Linear document or it does not contain a valid `tracked-plan/1` block, stop and route back to `writing`.
- If the routed Linear issue does not match the stored `issue_id`, stop and route back to `writing`.
- If the linked plan document in use does not match the stored `document_id`, stop and route back to `writing`.
- If the normalized ingress helper cannot reconcile the canonical linked document revision with the latest valid `plan-event/1` history, stop and route back to `writing`.
- Before any commit or push, follow the local commit/push gate.
- Treat tracked-plan completion as plan-local only. It does not bypass downstream review, merge, `delivery-closeout`, or worktree cleanup gates defined outside the tracked plan.

## Consumer ownership

`execution` may update only these runtime-owned fields on the authoritative plan surfaces:

- `state.phase`
- `state.current_task_id`
- `state.next_task_id`
- `state.task_states`
- `state.blockers`
- `state.evidence`
- `state.last_updated`
- `state.replan_reason`
- `state.latest_event_seq`
- append-only progress comments

It must not mutate the stable plan intent fields owned by `writing`:

- `spec.*` inside the linked document's `tracked-plan/1`
- the routed issue identity or linked document identity bound to the current plan
- any supporting strategy, task graph, option analysis, or prose context below the canonical `tracked-plan/1` block

## Progress-event contract

Each execution update should append one progress comment that is exactly one fenced JSON block whose `schema` is `plan-event/1`.

The event block should include:

- `plan_id`
- `document_id`
- `revision`
- `seq`
- `phase`
- `current_task_id`
- `next_task_id`
- `task_states`
- `blockers`
- `evidence`
- `replan_reason`
- `verification`
- `refs`
- `last_updated`

Use `templates/progress-event.md` as the default shape. Do not append prose below the JSON block; `scripts/validate_plan_event.py` must accept the entire comment as-is.

Write runtime updates in this order:

1. Append the new `plan-event/1` comment first.
2. Rewrite the linked document checkpoint second so `state.*` matches that new event and `state.latest_event_seq` catches up.

The ingress helper may accept the event log being ahead of the checkpoint by exactly one event. That state is recoverable and means the next execution pass must rewrite the linked document checkpoint before taking a new transition.

## Execution workflow

1. Read the authoritative Linear issue, the full linked-document set for that issue, the content of every linked document, the linked tracked-plan candidate documents, and the latest plan-event comments before doing implementation work.
2. Validate and read the tracked-plan candidate documents with `scripts/validate_tracked_plan.py` and `scripts/read_tracked_plan.py`.
3. Validate and read the full append-only candidate plan-event stream with `scripts/validate_plan_event.py` and `scripts/read_plan_events.py` when execution history exists. The event reader may return multiple plan histories for one issue comment stream.
4. Validate the cross-surface consistency of the routed Linear issue export, the routed `issue_id`, the routed linked `document_id`, the tracked-plan candidates, and the canonical latest valid event derived from the linked candidates with `scripts/validate_execution_surface.py` or `scripts/read_execution_surface.py`.
5. Treat the normalized validated execution surface emitted by the ingress helper as the execution-core source of truth. When the checkpoint and event log are in sync it mirrors the linked document; when the event log is one write ahead it mirrors the latest canonical event until the checkpoint is rewritten.
6. Treat the routed issue only as the authoritative parent work item and generic dispatch briefing surface.
7. Re-read only the files and verification commands needed for the current task.
8. Execute one coherent task or tightly related batch.
9. Append exactly one `plan-event/1` JSON block for the new runtime snapshot.
10. Rewrite only the runtime-owned fields in the linked document's `tracked-plan/1` state so the checkpoint matches that event.
11. Re-read the updated issue, linked tracked-plan document, and the full candidate progress-event set, and re-run the cross-surface validator so the helper itself derives the canonical latest event before reporting progress.

## Allowed transitions

- `ready -> executing`
- `executing -> blocked`
- `executing -> done`
- `blocked -> needs_replan`
- `needs_replan -> ready` only after `writing` revises the stable plan intent

If execution needs a strategy change, stop after recording the blocker and append a progress comment that makes the replan trigger explicit. Do not silently rewrite stable plan intent.
If the tracked plan does not explicitly include downstream review or landing tasks, reaching `done` means implementation under this tracked plan is complete, not that the broader delivery lifecycle is complete.

## Blocking rules

- No authoritative routed Linear issue: block and route to `writing`.
- Missing or invalid canonical `tracked-plan/1`: block and route to `writing`.
- Routed issue mismatch with stored `issue_id`: block and route to `writing`.
- Snapshot/document mismatch or missing linked-plan reference: block and route to `writing`.
- Routed issue exports that omit linked document content: block and re-read or route to `writing`.
- Supplied tracked-plan candidates do not cover every linked tracked-plan document on the routed issue: block and re-read or route to `writing`.
- Supplied tracked-plan candidate content for a linked tracked-plan document does not exactly match that linked document content: block and re-read or route to `writing`.
- Linked tracked-plan candidates disagree on plan lineage or revision metadata: block and route to `writing`.
- A tracked-plan revision claims to supersede a linked revision that is no longer attached to the routed issue: block and route to `writing`.
- Event history is ahead of the linked document checkpoint by more than one event, or references a different canonical revision: block and route to `writing`.
- "Use the plan we just discussed" with no materialized Linear plan surface: block and route to `writing`.

## Helper tools

Use the routed Linear MCP tools rather than repo-local plan files:

- read the issue and the latest comments first
- read every linked document on the routed issue and include each document's content, then let the helper prove which linked docs are tracked plans, whether the candidate set is complete, and whether the supplied candidate content matches the authoritative linked document content
- read the full candidate progress-event stream and let the ingress helper normalize it into one validated execution surface for the current canonical revision
- treat the issue body as generic dispatch context, not plugin-private schema
- append progress comments rather than rewriting history
- validate comments before trusting them as execution history

## Red flags

- Executing from chat memory instead of the authoritative Linear issue
- Editing stable plan intent fields to "repair" a blocked plan
- Rewriting old progress comments instead of appending a new execution event
- Continuing after the routed issue identity, linked tracked-plan document lineage, and latest valid event disagree
- Reporting progress without re-reading the updated issue, tracked plan document, and latest progress comment
Comments 0
Latest | Hot
Please login before commenting.
Loading comments...
execution

Directory Structure

SKILL.md

Report

Notice
