@evolvehq/docflow 0.4.3

package/skills/new-adr/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: new-adr
+description: Author a new ADR — record a DECISION (what the system must do, or how it is built) in a documentation-led repo. Picks the next contiguous number, chooses the shape (capability vs technology), fills the template, sets status Proposed, regenerates INDEX, updates domain READMEs, handles supersede/deprecate linkage, commits. Use when the user says "add an ADR", "new ADR", "record a decision", "create an architecture decision record", or invokes /new-adr. NOT for queueing a unit of work against an existing decision (use /new-plan) and NOT for recording a reusable rule, practice, or naming/process standard (use /add-convention).
+---
+
+# new-adr
+
+Author one new ADR, consistent with this repo's conventions.
+
+## Step 0 — Preconditions and context
+
+1. Confirm the repo is bootstrapped: `AGENTS.md`, `CONVENTIONS.md`, and
+   an `adr/` directory with at least `adr/0000-template.md` must exist.
+   If not, stop and offer to run the **bootstrap** skill first.
+2. Read `CONVENTIONS.md` to learn this repo's choices: ADR shape
+   (single vs. capability/technology split and the cutoff number),
+   status lifecycle, language mandate (if any), whether `domains/`
+   groupings exist, and the multi-agent mode.
+3. Read `INDEX.md` and `ls adr/` to learn existing numbers and titles.
+
+## Step 1 — Determine shape and number
+
+- **Shape.** If the repo uses a single ADR shape, use
+  `adr/0000-template.md`. If it uses the split, decide capability vs.
+  technology from the user's intent (what the system must do →
+  capability; how it is built → technology); confirm with the user if
+  ambiguous. Use `adr/0000-template.md` (capability) or the technology
+  template (`adr/NNNN-template.md`).
+- **Number.** Next contiguous integer after the highest existing ADR,
+  zero-padded to 4 digits. No gaps, no reuse. For a split repo, keep
+  capability ADRs below the cutoff and technology ADRs at/above it.
+
+## Step 2 — Gather content
+
+Ask for the pieces the chosen template needs, one prompt at a time:
+- Title (sentence case), Context.
+- Capability ADR: capability statement, user stories, **numbered,
+  testable** acceptance criteria.
+- Technology ADR: decision, rationale (**name alternatives considered
+  and give specific rejection reasons** — reject "simpler"/"idiomatic"
+  as insufficient), consequences, acceptance criteria.
+
+Honour the language mandate if one is set.
+
+## Step 3 — Supersede / deprecate (only if replacing an ADR)
+
+If this ADR replaces an existing one:
+- Set `supersedes:` on the new ADR and `superseded-by:` on the old.
+- Advance the old ADR's `status:` to `Superseded`, append a Revision
+  History row noting the successor.
+- A pure deprecation (no successor) sets the target to `Deprecated`
+  with a Revision History row — and is usually done directly, not via
+  this skill.
+
+## Step 4 — Write
+
+- Copy the chosen template, fill all placeholders. Status `Proposed`,
+  today's date, owner = current agent/human.
+- Seed the Revision History with an `r1 — Initial draft` row. Leave the
+  Approvals table empty (it populates on Accepted).
+- **Do not invent acceptance criteria or rationale to fill space.** If
+  the user hasn't supplied enough to make a section meaningful, ask.
+
+## Step 5 — Wire up
+
+- Regenerate `INDEX.md` from ADR metadata.
+- If `domains/` exists, add the ADR to the owning domain's `README.md`
+  ADR list.
+- Multi-agent mode 2: claim the file in `_agent/LOCKS.md` before
+  editing, remove on commit. Mode 3: you are on a branch/worktree.
+
+## Step 6 — Commit
+
+Conventional Commit, `Rationale:` footer (this touches an ADR). No
+`Co-Authored-By` trailer unless the repo's Git contract requires one.
+
+## Step 7 — Offer the next step
+
+A new ADR is `Proposed`, not actionable yet. Offer to:
+- Walk it to `Accepted` (populate Approvals, change status, regen INDEX)
+  when the user is ready; and
+- Create a `plan/todo/` item for it (hand off to the **new-plan** skill).

package/skills/new-plan/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: new-plan
+description: Queue a UNIT OF WORK in the plan/todo queue of a documentation-led repo, tracing to an existing ADR — names the owning ADR(s), scope, exit criteria mapped to acceptance criteria, dependencies, and queue position. Use when the user says "add a plan item", "queue this work", "create a todo for ADR X", "new plan", "put this on the backlog", or invokes /new-plan. NOT for recording the decision itself (use /new-adr) and NOT for shipping/completing an item already queued (use /ship-item).
+---
+
+# new-plan
+
+Add one item to the implementation queue.
+
+## Step 0 — Preconditions and context
+
+1. Confirm the repo is bootstrapped and a `plan/` queue exists. If the
+   repo was bootstrapped without a plan folder (Q4a = skip), stop and
+   say so — there is no queue to add to.
+2. Read `CONVENTIONS.md` for the plan-folder convention and the
+   completion event, and `plan/README.md` if present.
+3. `ls plan/todo/` to learn existing numbers and priority ordering.
+
+## Step 1 — Identify the owning ADR(s)
+
+- Ask which ADR(s) this work implements. Validate they exist in
+  `adr/`.
+- Normally a queue item tracks an **Accepted** ADR. If the named ADR is
+  still `Proposed`, warn — you can queue ahead of acceptance, but the
+  work is not yet authorised. If it has no ADR at all, suggest running
+  the **new-adr** skill first; plan items should trace to a decision.
+
+## Step 2 — Pick number and position
+
+- `plan/todo/NNNN-<slug>.md`, zero-padded. **Lower numbers run first** —
+  ask where this sits in priority and renumber neighbours only if the
+  user wants it inserted ahead of existing items.
+
+## Step 3 — Write the item
+
+The file names, at minimum:
+- Owning ADR(s) by relative path.
+- Scope — what is in, what is explicitly out.
+- Exit criteria — map directly to the ADR's numbered acceptance
+  criteria where possible.
+- Dependencies — other plan items or ADRs that must land first.
+
+## Step 4 — Commit
+
+Conventional Commit. If the file references an ADR by number in its
+body that is fine (the plan queue is internal — the ADR-privacy rule
+only forbids ADR references in **user-visible product** surfaces).

package/skills/ship-item/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: ship-item
+description: Ship a plan/todo item in a documentation-led repo — run the verify gate, integrate per the repo's model (fast-forward or PR), git mv todo→done with a shipped footer, advance the owning ADR(s) to Implemented, regenerate INDEX, append WORKLOG, update the live snapshot. Use when the user says "ship this", "complete the plan item", "mark done", "close out the queue item", or invokes /ship-item.
+---
+
+# ship-item
+
+Execute the completion event for one queue item. This is the most
+order-sensitive operation in the system — follow the steps exactly.
+
+## Step 0 — Preconditions and context
+
+1. Confirm the repo is bootstrapped with a `plan/` queue.
+2. Read `CONVENTIONS.md` and `AGENTS.md` for: the **integration model**
+   (direct-to-main fast-forward vs. PR-based with required CI), the
+   **verify gate** command, the **multi-agent mode**, and the Git
+   contract (signed commits, tags, trailers).
+
+## Step 1 — Select the item
+
+Default to the lowest-numbered `plan/todo/` file, or the one the user
+names. Read it and the owning ADR(s) in full.
+
+## Step 2 — Verify
+
+Run the repo's verify gate. **Require a pass.** Do not bypass with
+`--no-verify` or equivalent. If it fails, stop, surface the failure,
+fix the root cause, re-run.
+
+## Step 3 — Integrate (per the repo's model)
+
+- **Direct-to-main, fast-forward:** `git merge --ff-only <branch>` (or
+  the work is already on `main`), then `git push origin main`. The
+  verify gate ran locally in Step 2.
+- **PR-based:** push the branch, `gh pr create --draft --fill`, wait
+  for CI green (`gh pr checks --watch`), `gh pr ready`, then
+  `gh pr merge` with the repo's strategy. Confirm the merge landed on
+  `main` before continuing.
+
+## Step 4 — Move the queue item
+
+Once the change is on `main`:
+- `git mv plan/todo/NNNN-<slug>.md plan/done/<YYYY-MM-DD>-<slug>.md`
+  (today's date prefix).
+- Amend the moved file with a footer: **"Shipped at HEAD `<sha>`"** plus
+  any artefact id, image tag, deploy id, or PR link.
+
+## Step 5 — Advance the ADR(s) and regenerate
+
+- Advance each owning ADR's `status:` from `Accepted` to `Implemented`.
+- Append a Revision History row if the status change is substantive
+  (it is). Regenerate `INDEX.md` to match.
+
+## Step 6 — Record
+
+- Append a one-line `_agent/WORKLOG.md` row: branch, HEAD, verify
+  result, any deferral.
+- Update the live snapshot: `_agent/CURRENT_FOCUS.md` in single-checkout
+  modes; in worktree mode (Q5 mode 3) remove this worktree's row from
+  `_agent/IN_FLIGHT.md` instead (CURRENT_FOCUS is local-only there).
+
+## Step 7 — Commit
+
+Conventional Commit, `Rationale:` footer (touches an ADR). Group the
+move + status advance + INDEX + WORKLOG into one coherent commit where
+possible so the completion event is atomic in history.