# Complete Work

> Archive an OpenSpec change and transition the Jira issue to Done. Use when the user says "complete work", "finish this change", "wrap up", or otherwise signals the work is done and should be closed out. Handles archive, commit with trailers, Jira transition, push, and CI verification.

- Skill: `avantmedialtd/complete-work` (Agent Skill)
- Install (CLI): `npx skillmds@latest add avantmedialtd/complete-work`
- Raw SKILL.md: https://api.skillmd.com/api/skills/avantmedialtd/complete-work/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: avantmedialtd (https://skillmd.com/u/avantmedialtd)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/avantmedialtd/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:
   ```bash
   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:
   ```bash
   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:
   ```bash
   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