openspec-implementation-loop

name	openspec-implementation-loop
description	Orchestrates an end-to-end implementation loop for a single OpenSpec change: select a change, ask commit-only vs PR delivery, triage the change to determine an execution strategy (inline, single-implementor, or per-task) based on change size and complexity, implement tasks using the chosen strategy, run review and validation, feed findings back for fixes, push to origin, then either watch GitHub Actions on the branch (commit mode) or create a PR and delegate PR monitoring to the pr-monitoring-loop skill (PR mode). Use when the user wants to implement an approved OpenSpec proposal/change with iterative review and CI feedback.
license	MIT
compatibility	Requires openspec CLI, git, and GitHub CLI.
metadata	{"author":"openspec","version":"3.0"}

Orchestrate an implementation loop around a single OpenSpec change.

Input: Optionally specify a change name. If omitted, you MUST ask the user which change to implement.

High-level flow

1. Select the change
2. Ask delivery mode (commit vs PR) - do this immediately after selecting the change, not after implementation
3. Load OpenSpec context
4. Triage: determine execution strategy - classify as inline, single-implementor, or per-task based on change size and complexity
5. Determine remaining top-level tasks
6. Implement tasks using the chosen strategy
7. Run validation and review at the cadence determined by the strategy
8. Aggregate findings and fix; repeat until clean
9. Push the branch to origin
10. Commit mode: Watch GitHub Actions on the pushed branch/commit PR mode: Create a PR, then use the pr-monitoring-loop skill to monitor CI, reviews, comments, mergeability, and verify-openspec approval through watcher and delegate subagents
11. Report final outcome

Steps

1. Select exactly one change

   If a name is provided, use it.

   Otherwise:

   • Run openspec list --json
   • Use the AskUserQuestion tool to let the user choose a single active change
   • Show the change name, schema if available, and status

   IMPORTANT:

   • Do NOT guess
   • Do NOT auto-select
   • Do NOT implement multiple changes in one run

   Always announce: Using change: <name>.

2. Choose delivery mode (ask immediately - before loading context or starting the implementor)

   Use AskUserQuestion (or an equivalent explicit user prompt) right after step 1. Do not defer this until after implementation or push.

   Offer two options:

   • Commit-only: Push your work to origin on the current branch. After each push, monitor GitHub Actions for the branch / commits you pushed (same behavior as the historical workflow).
   • Pull request: After the initial push of the implementation loop, create a PR (for example with gh pr create). Then monitor PR workflow runs (checks on the PR), and actively handle PR reviews as described in step 11.

   Record the user's choice and refer to it from push onward (steps 9–11).

3. Load OpenSpec status and context

   Run:

   openspec status --change "<name>" --json
   openspec instructions apply --change "<name>" --json
   

   Parse the outputs to determine:

   • schemaName
   • current task progress
   • state
   • contextFiles
   • the ordered list of top-level tasks (for example 1, 2, 3) and which of them are still incomplete

   Read every file listed in contextFiles.

   Handle states:

   • If state: "blocked": stop and explain what artifact is missing; suggest continuing the change artifacts first

If the user chose commit-only in step 2:

After pushing:

• inspect workflow runs for the current branch and the commits you pushed (for example with gh run list filtered by branch, or gh against the latest commit SHA)
• watch or poll the latest relevant workflow runs until they complete
• expect the acceptance test suite to take around 15 minutes to complete
• once the only remaining jobs are long-running acceptance tests, poll less frequently instead of checking aggressively

If CI succeeds:

• finish with a concise summary (or continue to step 12 if you already reported)

If CI fails:

• collect the failing workflow, job, and relevant log details
• launch a fresh write-capable implementor subagent scoped only to resolving the CI failures
• ask it to fix the issues and commit the changes
• push again
• continue watching CI

Repeat until:

• CI is green, or
• a failure cannot be resolved without user input

11. PR mode: create PR, watch PR checks, poll reviews, address feedback

    If the user chose pull request in step 2:

    Create the PR after the initial push (step 9), if it does not already exist:

    • use gh pr create (or equivalent) with an appropriate title and body tied to the OpenSpec change
    • record the PR number or URL

    State file:

    • the script auto-uses .agents/skills/pr-monitoring-loop/scripts/state/.pr-monitor-<pr>.json (gitignored), so subagents can simply invoke check-pr-state.py <pr> and lastPolledAt / seen IDs persist across watcher restarts without any explicit path management
    • pass --state-file <path> only when you need isolation (e.g., parallel watchers on different branches that share a PR number, or tests). When you do override, pass the same path to every subagent in this loop
    • do NOT put the state file under .git/ - this repo uses git worktrees, where .git is a file that points at a worktree-specific git dir, which would fragment state across worktrees watching the same PR

    Delegate PR monitoring to pr-monitoring-loop:

    • load and follow the pr-monitoring-loop skill for the entire PR monitoring phase
    • start a delegate subagent for the PR instead of polling in this main implementation-loop agent
    • instruct the delegate to invoke .agents/skills/pr-monitoring-loop/scripts/check-pr-state.py <pr> on every cadence tick (or use --watch with the cadence guidance documented in pr-monitoring-loop) so CI (commit-pinned), reviews, PR comments, review comments, unresolved threads, merge conflicts, and stale branch state are checked together. Append --state-file <path> only if you decided to override the default path above.
    • allow the delegate to fix and push changes it judges simple, then perform the thread-resolution protocol for any addressed threads (reply with addressing commit SHA, then resolveReviewThread), and continue watching the new PR head
    • when the delegate returns delegate, launch a fresh delegate subagent scoped only to the reported failure or feedback (with the same --state-file); after the delegate commits, pushes, replies, and resolves addressed threads, restart the watch cycle for the new head commit with a new delegate

Recommended subagent responsibilities

Subagent usage scales with the chosen strategy:

• Implementor (single-implementor and per-task strategies): makes code changes, updates tasks, runs targeted validation, and creates small focused commits. Per-task uses one fresh implementor per top-level task; single-implementor uses one for the entire change.
• Validation runner (single-implementor and per-task strategies): a subagent that runs make lint, make build, and relevant acceptance tests, then reports a concise validation summary. Use a subagent so validation does not consume the orchestrator's context.
• Critical reviewer: reviews code quality and logic
• Spec reviewer: checks the implementation against the approved OpenSpec change
• Coverage reviewer: checks test coverage quality using the appropriate strategy
• PR watcher: a fresh subagent using pr-monitoring-loop to poll PR state, directly fix simple actionable issues, and return non-simple work to the main agent for delegation to a fresh subagent

For the inline strategy, the orchestrator fills the implementor and validation runner roles directly. Review subagents are spawned only when the change touches non-trivial logic.

Guardrails

• Operate on one change only
• Ask commit vs PR at the start (step 2), not when implementation is finished
• Always triage the change and announce the execution strategy before implementation
• The user can override the chosen strategy at the triage step
• Always read the OpenSpec context before implementation
• Per-task strategy: create a fresh implementor subagent for each top-level task; do not reuse one implementor across top-level tasks. Do not advance to the next top-level task until the current task has passed local review.
• Single-implementor strategy: use one implementor for all tasks; run one review round after all tasks complete
• Inline strategy: the orchestrator implements directly; spawn review subagents only for non-trivial logic changes
• Never archive a change in this workflow; only sync delta specs when needed
• Ignore tasks that request archiving the change proposal; verify-openspec will archive the change when it is happy
• For single-implementor and per-task strategies, run local validation in a dedicated subagent so the orchestrator does not spend its own context on lint/build/test execution
• Run the validation subagent in parallel with the other review subagents, not as a separate serial phase
• All strategies must include make lint, make build, and relevant acceptance tests run according to dev-docs/high-level/testing.md (or an explicit explanation when acceptance tests are not applicable)
• Run reviewers in parallel whenever possible
• Prefer actionable findings over style nitpicks
• Feed local review and commit-mode CI failures back into the loop instead of fixing them ad hoc outside the loop
• In PR mode, use pr-monitoring-loop; do not spend main-agent context on repeated PR polling
• Keep commit sizes small and purpose-specific
• Stop and ask the user if the process becomes ambiguous or stuck