change-workflow

Files (4)

• SKILL.md
• publish-review.md · references/
• run_log_digest.ts · scripts/
• run_log_digest_test.ts · scripts/

SKILL.md (first lines)

# Change Workflow

Follow this for every tracked-file change. It orders the steps and holds
their mechanics; each rule it follows has one owner, named where the step
needs it:

- `.agents/knowledge/spec-workflow.md` — the lifecycle, the approval
  gates, the archive executor and the freeze.
- `.agents/knowledge/agent-authority.md` — publishing, review admission,
  pending decisions, what is never yours.
- `.agents/knowledge/github-workflow.md` — branches, merging, issues,
  labels, triage.

When a check, policy, or permission blocks you, follow
`agent-authority.md ## No self-escalation`.

## 1. Gate tooling and authorization

```bash
command -v gh && gh --version && gh auth status
command -v openspec && openspec --version
```

If `gh` is missing, stop and direct the user to <https://cli.github.com/>;
if authentication fails, ask the user to run `gh auth login` — never start
it yourself. If `openspec` is missing, run `just setup`.

List the remote writes the task may need — issue, push, PR, ready, review
request, labels — and obtain the authorization
`agent-authority.md ## Publishing` requires for them.

Done when: `gh auth status` succeeds and the allowed remote operations are
recorded, or the workflow has stopped with exact setup or authorization
needs.

## 2. Take or create the issue

Derive `OWNER/REPO` from `git remote get-url origin`. An issue is optional
(`github-workflow.md`, Decomposition):

- **Taking one**: read it, confirm it is open and nobody else is assigned,
  and confirm its acceptance — the scenarios of the change its
  Specification field names, or executable criteria. An issue with no
  change yet is taken by proposing the change (step 3); an issue whose
  change is still under discussion waits for the maintainer's closing.
  Assign yourself, re-read, confirm you are the sole assignee.
- **Creating one**: only when authorized. Build the body by mirroring the
  form's `### <label>` headings in `.github/ISSUE_TEMPLATE/`
  (non-interactive creation ignores forms) and apply the form's labels
  explicitly; `issues / triage` derives `priority/*` and `catalog/*`.
  Issues for planned work derive from the change's `tasks.md`, each
  naming the scenarios it closes (`spec-workflow.md ## Specifications
  and tracked work`).

Record the issue number or a one-line reason there is none.

## 3. Establish the branch, the change, and its approval

1. Confirm the worktree is clean enough to isolate the requested change;
   fetch `origin` when remote reads are allowed.
2. Create the branch from `origin/main` as
   `github-workflow.md ## Branches and merging` names it.
3. Write the approval package on that branch with the `openspec-*`
   skills. A skill change: propose (`openspec/changes/<slug>/`), clarify
   with `plan-clarification`, write the design the schema asks for. A
   repository change: `openspec new change <slug>`, then
   `skip_specs: true` in its `.openspec.yaml`, then the proposal and the
   design. Run `just spec-validate` and commit the package. The
   `spec-driven-development` skill supplies the loop's general rules;
   `spec-workflow.md` overrides it here.
4. Run the publish gate (step 6) and open the draft pull request with the
   package as its first content, at the point
   `spec-workflow.md ## Lifecycle` sets. Then stop.
5. Push each record change the maintainer directs in conversation through
   the publish gate. When asking for the package approval, ask the
   maintainer to add `spec/approved`, then push nothing to the package and
   poll `just spec-approval <n>` until the record appears
   (`spec-workflow.md ## Approval gates`, including the bootstrap).
6. Reconcile each closing — this one and the implementation closing in
   step 7:
   - read the comments with `gh pr view <n> --json comments` and the
     review threads with `just review-threads <n>` (field `isResolved`);
   - list every unresolved thread, every requested adjustment the record
     does not carry, and every contradiction;
   - ask the maintainer to confirm the open items; proceed only when
     nothing is open or the open items are confirmed;
   - update the `Approval:` line, and after the package closing set
     `Phase: implementation`, through the publish gate.
7. Write `tasks.md`, run `just spec-validate`, commit, then implement.

A change too small to plan skips the loop with `Spec: none — <reason>`
(`spec-workflow.md ## Specifications and tracked work`).

## 4. Implement in atomic commits

Work task by task from `tasks.md`. Each commit is the smallest
independently valid logical change:

1. Group files that must land together for checks to pass; split what can
   stand alone.
2. Stage one group; run the applicable checks (`just check-skill <dir>` for
   a skill, `just spec-validate` after touching `openspec/`).
3. Commit. The `commit-safety` pre-commit hook checks the author email
   and staged credentials; the `git-commit` skill's gates and `AGENTS.md`
   Commits govern the message.

A deviation from the spec stops the work (`spec-workflow.md
## Lifecycle`).

Checkpoints inside a task are commits, never stashes: commit drafts as
you go, and before ticking the task squash them into its one atomic
commit non-interactively — `git reset --soft <task start commit>`, then
one commit under the rules above (interactive rebase is unavailable).
Draft commits never leave the machine: push only after the task commit,
as `agent-authority.md ## Publishing` says. The per-commit hooks — secret
scans, validators, lint — run on every draft, so every draft commit must
pass them; keep them fast. A task is done only when no draft commit
remains on the branch.

From ryan-minato/skills, Apache-2.0.

More from ryan-minato/skills