elastic/.agents/skills/openspec-implementation-loop

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. Start a dedicated implementor subagent
5. Run review subagents in parallel
6. Send findings back to the implementor and repeat until clean
7. Push the branch to origin
8. Commit mode: Watch GitHub Actions on the pushed branch/commit
   PR mode: Create a PR, watch PR checks, add verify-openspec label after PR checks are successful, poll for PR reviews six times at 10-minute intervals, and address review feedback
9. 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 10.

   Record the user’s choice and refer to it from push onward (steps 8–10).

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

   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 state: "all_done": skip directly to the review stage
   • Otherwise: proceed to implementation

4. Start the implementor subagent

   Launch a dedicated write-capable subagent and keep reusing the same subagent for the full loop.

   The implementor prompt should instruct it to:

   • implement only the selected change
   • follow the openspec-apply-change skill/process for the change
   • read the OpenSpec context files before editing
   • keep changes minimal and focused
   • create small, focused git commits as coherent pieces of work are completed
   • run targeted validation while implementing
   • never push to remote

   Ask the implementor to report back with:

   • tasks completed
   • commits created
   • tests run
   • blockers or open questions

   If the implementor is blocked, stop and surface the blocker to the user.

5. Determine the review strategy

   Inspect the change artifacts and implementation to decide whether this is a Terraform entity change.

   Treat it as a Terraform entity change when the change is centered on a Terraform resource or data source, for example:

   • specs reference Resource implementation: or Data source implementation:
   • changed code is primarily in a resource/data source package

6. Run review subagents in parallel

   Launch the following review subagents at the same time after the implementor reports completion of a reviewable chunk:

   a. Critical code review

   • Review for coding standards, idiomatic Go/Terraform provider patterns, obvious logic issues, error handling gaps, and risky regressions
   • Return prioritized findings only

   b. Proposal compliance review

   • Run the openspec-verify-change skill/process for the same change
   • Return only actionable mismatches, missing work, or notable warnings

   c. Coverage review for Terraform entities

   • If this is a Terraform entity change, run the schema-coverage skill/process
   • Focus on untested or weakly tested high-risk attributes and behaviors

   d. Coverage review for non-entity changes

   • If this is not a Terraform entity change, run a thorough test analysis instead
   • Prefer explicit coverage tooling where possible, for example go test -cover
   • Identify high-risk code paths that lack direct test coverage

   Ask every reviewer to return:

   • severity
   • concise finding
   • evidence
   • recommended fix

7. Aggregate findings and decide whether to loop

   Combine the review outputs into a single actionable list.

   If there are no actionable findings:

   • proceed to push

   If there are actionable findings:

   • resume the same implementor subagent
   • give it the aggregated findings
   • ask it to fix them with minimal diffs and additional small focused commits
   • rerun the relevant reviews

   Repeat until:

   • local review is clear, or
   • the implementor becomes blocked, or
   • the same issue repeats without progress

   If the loop stalls, pause and ask the user how to proceed.

8. Push the branch

   After local review is clear:

   • verify the branch state is ready to push
   • push the current branch to origin
   • use upstream tracking if needed

   Example:

   git push -u origin HEAD
   

   Guardrails:

   • Never force-push unless the user explicitly asks
   • Do not push before local review passes

9. Commit-only mode: watch GitHub Actions (branch / commits)

   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 11 if you already reported)

   If CI fails:

   • collect the failing workflow, job, and relevant log details
   • resume the implementor subagent with those 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

10. 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 8), 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

    Watch GitHub Actions in PR context:

    • prefer PR-centric views: for example gh pr checks <pr> and/or workflow runs associated with the PR’s head branch or PR event
    • poll until required checks complete, with the same practical pacing as commit-only mode for long acceptance tests

    Add verify-openspec label after successful Github Actions:

    • Decide whether to add the label based on the current PR head commit, not an older green run. If new commits were pushed after the last successful checks, wait for checks on the new head commit to finish.
    • Add the label only when the PR is ready for OpenSpec verification: the PR exists, the relevant GitHub Actions for the latest head commit are green in PR context, and there is no unresolved CI failure you already know needs another fix push first.
    • Treat the label as a manual trigger for the OpenSpec verify workflow. It is appropriate once per green head commit when you want that workflow to review the current PR state.
    • Apply the label with GitHub CLI: gh pr edit <pr> --add-label verify-openspec
    • Or apply it in the GitHub UI: open the PR, use the labels control, and add verify-openspec.
    • After applying it, confirm the OpenSpec verify workflow starts for that PR. The workflow removes verify-openspec automatically after activation, so if later pushes need another verify pass, wait for checks on the new head commit to go green and then add the label again.

    PR reviews — six checks, ten minutes apart:

    • After the PR exists, perform six separate review polls for new or updated reviews.
    • Schedule: run the first poll as soon as the PR is created (or immediately after). Run polls two through six each after waiting 10 minutes since the previous poll (six polls total, ~50 minutes from first to last if no work interrupts the schedule).
    • If a poll triggers implementor work and pushes, you may pause the clock until checks rerun, then resume the remaining scheduled polls so review handling stays coherent.
    • On each pass, fetch current PR review state, for example:
      • gh pr view <pr> --json reviews,comments
      • and/or gh api repos/{owner}/{repo}/pulls/<number>/reviews and review comments as needed
    • If there are new or unresolved review threads (requested changes, comments, or reviews), treat them like CI failures:
      • summarize for the implementor
      • resume the implementor to address feedback with minimal commits
      • push updates; the PR updates automatically
      • re-check PR checks after pushes
      • when a review thread has been addressed, add a brief reply summarizing the fix and then resolve the thread
      • only resolve threads that are actually addressed by the current PR state; leave unresolved anything that still needs reviewer confirmation or additional changes
    • If a late review round arrives after the sixth poll, surface it to the user (or extend polling if they ask).

    If CI fails on the PR:

    • same loop as commit-only: collect logs, implementor fixes, push, re-watch checks

    Repeat until:

    • CI is green and review passes show nothing actionable (within the six-pass schedule), or
    • a failure or review cannot be resolved without user input

11. Report final outcome

    Summarize:

    • change name
    • schema
    • delivery mode (commit-only vs PR)
    • implementation/review/CI loop status
    • commits created during the loop
    • tests or coverage checks used
    • final CI state (and PR link if PR mode)
    • PR review handling summary if PR mode (including how many review passes ran)
    • any remaining blockers or risks

Recommended subagent responsibilities

• Implementor: makes code changes, updates tasks, runs targeted validation, creates small focused commits
• 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

Guardrails

• Operate on one change only
• Ask commit vs PR at the start (step 2), not when implementation is finished
• Always read the OpenSpec context before implementation
• Reuse the same implementor subagent through the whole loop
• Run reviewers in parallel whenever possible
• Prefer actionable findings over style nitpicks
• Feed review and CI failures back into the loop instead of fixing them ad hoc outside the loop
• Keep commit sizes small and purpose-specific
• Stop and ask the user if the process becomes ambiguous or stuck