Complete Work

Complete Work

Close out a finished unit of work: archive the OpenSpec change, commit with trailers, transition the Jira issue to Done, push, and verify CI.

When to use

• All tasks in an active OpenSpec change are implemented and tested.
• The user says "complete work", "wrap up", "finish this one", or names a change to close out.
• Work needs to land on main/master with a clean audit trail.

Steps

1. Find the active OpenSpec change in openspec/changes/. If multiple exist, ask the user which change to complete.
2. Read the proposal (openspec/changes/<id>/proposal.md) to extract the issue key (look for a Jira key pattern like PROJ-123 in the metadata or body) and the title.
3. If an issue key was found: Fetch the issue details using af jira get <issue-key> to verify it exists and get the summary. If no issue key was found: Skip all Jira operations (steps 3, 6) and omit the Issue= trailer in step 5.
4. Archive the OpenSpec change (if not already archived):
   • Check if openspec/changes/<id>/ directory exists
   • If it exists, invoke the openspec-archive-change skill (Skill tool) with the <change-id>
   • If the directory does not exist (already archived), skip this step
5. Commit with trailers:

   git add -A
   git commit -m "<summary>" \
     [--trailer "Issue=<issue-key>"] \
     --trailer "OpenSpec-Id=<change-id>"
   

   Where <summary> is derived from the Jira issue (if available) or from the OpenSpec proposal title. Only include the --trailer "Issue=<issue-key>" flag when an issue key is present.
6. If an issue key was found: Transition the issue to "Done", always supplying a resolution so the issue does not close with an empty Resolution field:

   af jira transition <issue-key> --to "Done" --resolution "Fixed" --comment "<change-id> archived and pushed"
   

   Status and resolution names are workflow-specific. If this fails, run af jira transitions <issue-key> — it lists the available transitions and the fields each one's screen requires — then retry with the correct --to / --resolution names (add --field name=value for any other required screen field). If no issue key: Skip this step.
7. Push to remote: git push

CI Verification

8. Read the Jenkins job path from the project's CLAUDE.md (e.g., Jenkins job: folder/pipeline-name). If not configured, skip this phase. Job paths use / to separate folder/pipeline/branch segments, so the path to poll is the branch build the push just triggered: <job-path>/<branch> — not the bare <job-path>, which is the multibranch parent. (af jenkins branches <job-path> lists the per-branch build statuses.)

9. Wait ~30 seconds for Jenkins to pick up the push, then poll build status:

   af jenkins build <job-path>/<branch> --json
   

   Repeat every 30 seconds until the build is no longer in progress (check the building field or result field in JSON output).

10. If build succeeds: Done.

11. If build fails:

    • Run af jenkins stages <job-path>/<branch> to identify the failing stage
    • Run af jenkins stage-log <job-path>/<branch> "<failing-stage>" to read the error output (arg order is <name> <stage> [number|latest])
    • Fix the code based on the failure
    • Commit the fix using the same git add -A && git commit -m "<summary>" --trailer ... pattern from step 5, push, and poll again

    Escape valve: If the build still fails after 3 CI attempts, STOP and report the failing stage, error output, and what fixes were attempted.

Reference

• Run openspec --help for OpenSpec CLI options
• See the jira skill, or run bare af jira (not af jira --help, which is only a stub) for the full CLI reference
• See the jenkins skill for job paths, polling, and stage logs; run bare af jenkins for the full CLI reference