VibeGuard: ExecPlan

Core Concept (from OpenAI Harness Engineering)

• Long-term tasks require self-contained execution documents that can be resumed in new sessions by themselves
• Progress is the only chapter that allows checklist, the rest are described in prose
• Decision Log records all decisions that deviate from SPEC to ensure traceability
• ExecPlan is a living document that is continuously updated with execution

Three modes

Mode	Usage	Description
init	/vibeguard:exec-plan init [spec path]	Generate ExecPlan from SPEC
update	/vibeguard:exec-plan update <execplan path>	Append Discovery/Decision/completion status
status	/vibeguard:exec-plan status <execplan path>	View Progress progress summary

Trigger condition

• SPEC generated and confirmed via /vibeguard:interview
• Tasks expected to be completed across 2+ sessions
• Scenarios where execution context needs to be restored across sessions

Guardrails

• init mode does not make any code modifications, only generates documentation
• update mode only modifies the ExecPlan file itself
• Does not replace preflight - ExecPlan defines "what to do", preflight defines "what not to do"

---

Mode: init

Generate ExecPlan files from SPEC.

Steps

1. Read SPEC

   • If spec path ($ARGUMENTS) is provided, read the file
   • If not provided, search for SPEC.md in the project root directory
   • If there is no SPEC, prompt the user to run /vibeguard:interview first

2. Analyze SPEC and break down milestones

   • Extract milestones from SPEC functional requirements (FR-XX)
   • Each milestone contains 1-3 specific steps
   • Identify dependencies between milestones

3. Scan project context

   • Identify languages/frameworks and key entry files
   • Check if there is a preflight constraint set to reference
   • Document existing code locations related to SPEC

3.5. Capture the W-20 execution snapshot

• Create ${VIBEGUARD_HOME:-${HOME}/.vibeguard}/artifacts/execplan/<project-name>/ outside the target repository, then write the active runtime, model, tool/MCP/skill names, and stable description hashes to its <task>-tool-inventory.txt; each non-comment line must be <kind> <name> <description_sha256>
• Resolve the installed source as ${VIBEGUARD_DIR:-${HOME}/.vibeguard/installed} and verify that its drift guard and rules/claude-rules directory exist
• Run bash "${VIBEGUARD_DIR:-${HOME}/.vibeguard/installed}/guards/universal/check_runtime_drift.sh" snapshot --snapshot "${VIBEGUARD_HOME:-${HOME}/.vibeguard}/artifacts/execplan/<project-name>/<task>-runtime.snapshot" --tool-inventory "${VIBEGUARD_HOME:-${HOME}/.vibeguard}/artifacts/execplan/<project-name>/<task>-tool-inventory.txt" --rules-dir "${VIBEGUARD_DIR:-${HOME}/.vibeguard/installed}/rules/claude-rules"
• Stop if the inventory or snapshot cannot be created; do not generate a resumable ExecPlan without them

1. Generate ExecPlan

   • Populate 8 chapters by template (workflows/plan-flow/references/execplan-template.md)
   • Purpose extracted directly from the SPEC overview
   • Progress is mapped to a milestone list with checkbox
   • Concrete Steps aligns the Step format of plan-template.md (status/target/file/change/test/judgment)
   • Nyquist Rule: Each Step must contain the verify_cmd field - a verification command that can be executed within 60 seconds (such as cargo test --lib, curl localhost:8080/health). Steps that cannot be verified within 60s are marked as unverifiable and need to be split or supplemented with verification methods.
   • Validation converted from SPEC acceptance criteria (AC-XX)
   • Decision Log is initially empty and records the selection decisions during generation.
   • Record the W-20 snapshot and tool-inventory paths in Context.

2. Save and Confirm

   • Save to <project name>-execplan.md (project root directory)
   • Display Progress and Concrete Steps summaries for user confirmation
   • Use AskUserQuestion to confirm if adjustments are needed