@evolvehq/docflow 0.4.3

package/skills/bootstrap/templates/CONVENTIONS.md

@@ -0,0 +1,165 @@
+# Conventions
+
+## Project
+
+Project name: <name>.
+
+<!-- Q1 language: if a language mandate is set, state it here.
+Example: "Language: en-GB throughout. Use forms such as organisation,
+behaviour, prioritise, catalogue, authorisation consistently across all
+files." -->
+
+## ADR Files
+
+ADR filenames use `NNNN-kebab-case-slug.md`, zero-padded to 4 digits,
+with contiguous numbering and no reserved gaps.
+
+Each ADR describes one decision. If a decision splits, supersede the
+original ADR and create new ADRs rather than expanding scope inside a
+single document.
+
+Status lifecycle: `<from Q3>`.
+
+| Status | Meaning |
+|---|---|
+| Proposed | Draft. Decision authored but not yet approved. |
+| Accepted | Decision approved; implementation authorised. Work item lives in `plan/todo/`. |
+| Implemented | Code shipped per Q4 completion event. Work item moved to `plan/done/`. ADR is the authoritative spec the running system matches. |
+| Superseded | Replaced by another ADR. The successor is named in `superseded-by:` metadata. |
+| Deprecated | Was real; the world moved on; no successor. Capability is not being rebuilt. |
+
+Terminal states (Superseded / Deprecated) are reachable from any prior
+state.
+
+Cross-references link by relative path to `adr/NNNN-*.md`.
+
+## ADR Shapes
+
+<!-- Single shape (Q2): -->
+This project uses a single ADR shape. ADRs use `adr/0000-template.md`
+and contain these sections in order: Context, Capability statement,
+User stories / scenarios, Acceptance criteria, Out of scope, Open
+questions, References, Revision History, Approvals.
+
+<!-- Split (Q2): -->
+<!--
+Capability ADRs (`0001`-`NNNN`) describe what the system must do. They
+use `adr/0000-template.md` with sections: Context, Capability
+statement, User stories / scenarios, Acceptance criteria, Out of
+scope, Open questions, References, Revision History, Approvals.
+
+Technology ADRs (`NNNN+1` onwards) describe how the system is built.
+They use `adr/NNNN-template.md` with sections: Context, Decision,
+Rationale, Consequences, Acceptance criteria, Out of scope, Open
+questions, References, Revision History, Approvals.
+
+Technology ADR Rationale must name alternatives considered and give
+specific reasons they were rejected. Generic rationale such as
+"simpler" or "more idiomatic" is not sufficient.
+-->
+
+<!-- Q10 domain-specific rules go here, each as its own section.
+Examples:
+## Vendor Name Rule
+## Audit-Plane Distinction
+## Regulated Evidence
+## Mandatory user-story personas
+-->
+
+## ADR Privacy
+
+ADRs are internal artefacts. ADR numbers, ADR titles, and the
+existence of the ADR catalogue must never appear in any string the
+product emits to users: UI copy, API response bodies, error messages,
+customer-visible log lines, public documentation, release notes,
+marketing copy, or support communications.
+
+Allowed references:
+- Inline code comments tying a non-obvious choice to its ADR
+  (`// see adr/0042-foo.md`).
+- Commit messages and PR descriptions.
+- Internal documents: `AGENTS.md`, `INDEX.md`, the `plan/` queue,
+  `_agent/` files, internal runbooks.
+
+Rule of thumb: if a non-builder could ever read the string, the ADR
+reference comes out. Refer to the behaviour by its product-level name
+instead.
+
+## Multi-Agent Rules
+
+<!-- Mode 1 — single agent. Keep this line, drop the alternatives. -->
+A single agent owns this repo. The `_agent/` directory tracks live
+state and history; no LOCKS discipline.
+
+<!-- Mode 2 — multi-agent, shared checkout. Replace with:
+Work is partitioned across named agents (see `_agent/ROLES.md`).
+Claim a file in `_agent/LOCKS.md` before editing; remove the line on
+commit. Append to `_agent/WORKLOG.md` on commit.
+`_agent/CURRENT_FOCUS.md` is the single in-flight snapshot.
+Regenerate `INDEX.md` after any ADR status change or new ADR.
+-->
+
+<!-- Mode 3 — multi-agent, separate worktrees / PR branches. Replace
+with:
+Work is partitioned across named agents (see `_agent/ROLES.md`).
+Each agent works in its own worktree / PR branch.
+- GitHub draft PRs are the authoritative lock; `_agent/LOCKS.md` is
+  advisory only.
+- `_agent/WORKLOG.md` is `merge=union` (see `.gitattributes`);
+  append on every commit.
+- `_agent/CURRENT_FOCUS.md` is gitignored (local-only per worktree);
+  the committed cross-worktree dashboard is `_agent/IN_FLIGHT.md` —
+  one row per active worktree.
+- Regenerate `INDEX.md` after any ADR status change or new ADR.
+-->
+
+## Plan Folder
+
+Pending and shipped work live in `plan/` at the repository root:
+
+- `plan/todo/NNNN-<slug>.md` — pending work, lower numbers run first.
+  Each file names the owning ADR(s), scope, and exit criteria.
+- `plan/done/<YYYY-MM-DD>-<slug>.md` — shipped work, chronological. A
+  `git mv` from `todo/` to `done/` is the completion event.
+
+The completion event is: `<from Q4>`.
+
+When a `plan/todo/` item ships, the file moves to `plan/done/` AND the
+owning ADR(s)' `status:` advances from `Accepted` to `Implemented`.
+`INDEX.md` is regenerated to match.
+
+## Audit Trail Policy
+
+Every substantive change to an Accepted ADR appends a new row to its
+Revision History table.
+
+Editorial changes — typos, formatting, link fixes — are excluded from
+Revision History but must be flagged "editorial" in the commit message.
+
+The Approvals table is populated when an ADR transitions to Accepted
+and updated on every subsequent substantive revision.
+
+## Git Contract
+
+Commit messages follow Conventional Commits with a mandatory
+`Rationale:` footer for any commit that touches an ADR.
+
+<!-- Per Q6:
+- Signed commits: <yes/no>
+- ADR-revision tags `adr-NNNN-rN`: <yes/no>
+- Co-Authored-By trailer on agent commits: <yes/no>
+-->
+
+<!-- Integration model per Q4b — keep one paragraph.
+
+Direct-to-main:
+Changes are fast-forwarded onto `main`; no merge commits. The verify
+gate runs locally and must pass before push. A change is "shipped"
+when it is on `main` and pushed.
+
+PR-based:
+Every change ships via a pull request with required CI. The verify
+gate runs in CI on the PR. Merge strategy is <squash | merge |
+rebase>. A change is "shipped" when its PR is merged to `main` with
+CI green.
+-->

package/skills/bootstrap/templates/_agent-CURRENT_FOCUS.md

@@ -0,0 +1,32 @@
+# Current Focus
+
+This file is the LIVE SNAPSHOT of any in-flight session. It is short on
+purpose — the durable record lives in git (`git log`),
+`_agent/WORKLOG.md`, and `plan/done/`. The queued work lives in
+`plan/todo/`.
+
+<!-- Mode 3 (worktree) note — the skill adds this file to
+`.gitignore` and leaves this comment in place:
+
+Under separate-worktree mode, this file is gitignored and stays local
+to each worktree. The cross-worktree dashboard is `_agent/IN_FLIGHT.md`
+(committed). Update freely; this file never merges.
+-->
+
+If status files and git disagree, git is authoritative; correct this
+file.
+
+## Active state
+
+- **Branch:** main
+- **Active item:** none — no work in flight.
+- **Blockers:** none.
+- **Uncommitted work:** none.
+
+## Last shipped
+
+<commit-sha> — <one-line description>.
+
+## Next item
+
+`ls plan/todo/` for the queue; the lowest-numbered file runs next.

package/skills/bootstrap/templates/_agent-HANDOFF.md

@@ -0,0 +1,28 @@
+# Handoff
+
+Entry point for a fresh agent picking up this repo. Read these files
+in order before any tool calls:
+
+1. `AGENTS.md` — hard rules. Read in full.
+2. `CONVENTIONS.md` — authoring rules + ADR status semantics + plan
+   folder convention.
+3. `plan/README.md` — the queue's own README.
+4. `_agent/CURRENT_FOCUS.md` — short live snapshot of any in-flight
+   session: active branch, active queue item, blockers, uncommitted
+   work.
+5. `INDEX.md` — the ADR catalogue. Look up an ADR's filename and
+   dependency chain. Sorted by ADR number, not by work order.
+6. Tail of `_agent/WORKLOG.md` (last 30 lines) — confirms what landed.
+7. The next queue item at `plan/todo/NNNN-*.md` — and the ADR(s) it
+   names — read in full before implementing.
+
+## Stop conditions
+
+Stop and surface the issue rather than guessing if:
+
+- The verify gate fails.
+- The queue is empty.
+- A `plan/todo/` item references an ADR whose status is not Accepted.
+- An ADR's acceptance criteria are ambiguous or untestable as written.
+- Two `plan/todo/` items at the same priority both target the same
+  files (lock contention).

package/skills/bootstrap/templates/_agent-IN_FLIGHT.md

@@ -0,0 +1,16 @@
+# In Flight
+
+Cross-worktree dashboard. One row per active worktree. Updated by the
+agent owning the worktree when it opens, and removed when the worktree
+closes (PR merged or abandoned).
+
+Useful when several agents work in separate worktrees / PR branches —
+this file replaces the single-checkout `_agent/CURRENT_FOCUS.md` as
+the shared "what's happening right now" view. `CURRENT_FOCUS.md` is
+gitignored under this mode and stays local to each worktree.
+
+If this file disagrees with reality, reality wins — check
+`git worktree list` and the live PRs, then correct here.
+
+| Agent | Worktree branch | Queue item | Started (ISO-8601) | PR link |
+|-------|-----------------|------------|---------------------|---------|

package/skills/bootstrap/templates/_agent-LOCKS.md

@@ -0,0 +1,17 @@
+# Agent Locks
+
+Append a row before editing a file. Remove the row on commit.
+
+Format: `<agent-id> | <path> | <ISO-8601 timestamp>`
+
+<!-- Mode 3 (worktree) advisory header — the skill leaves this in
+place when Q5 selected separate-worktrees mode:
+
+**Advisory only under separate-worktree mode.** GitHub draft PRs and
+branch assignment are the authoritative lock; LOCKS rows are an
+intent declaration to help coordinate before a PR exists. Do not
+rely on this file as a filesystem mutex — the filesystem can't
+conflict across worktrees in the first place.
+-->
+
+---

package/skills/bootstrap/templates/_agent-ROLES.md

@@ -0,0 +1,23 @@
+# Agent Roles
+
+<!-- Single agent (Q5 default): -->
+## default-agent
+
+The default agent owns all ADRs and implementation work until the
+project splits into named domains.
+
+<!-- Multi-agent — replace the block above with one section per agent.
+Example:
+
+## frontend-agent
+The frontend agent owns UI, components, design tokens, and front-end
+build pipeline ADRs.
+
+## backend-agent
+The backend agent owns API surface, data model, persistence, and
+backend infrastructure ADRs.
+
+## docs-agent
+The docs agent owns README, GLOSSARY, INDEX regeneration, and external
+documentation outputs.
+-->

package/skills/bootstrap/templates/_agent-WORKLOG.md

@@ -0,0 +1,16 @@
+# Agent Worklog
+
+Append one row per commit. Newest at the bottom.
+
+<!-- Mode 3 (worktree) note — the skill leaves this comment in place
+when Q5 selected separate-worktrees mode:
+
+This file uses `merge=union` via the repo's `.gitattributes` so
+concurrent appends from multiple worktrees concatenate cleanly rather
+than conflicting. Row ordering reflects merge order, not commit order
+— include the commit SHA in the row so the true sequence is
+recoverable.
+-->
+
+| Date | Commit | Branch | Item | Notes |
+|------|--------|--------|------|-------|

package/skills/bootstrap/templates/_agent-prompts-autonomous.md

@@ -0,0 +1,100 @@
+# Autonomous-completion prompt
+
+You are this project's autonomous agent. Your task: drive the
+implementation queue in `plan/todo/` to completion, unsupervised,
+committing per-item with the verify gate green, until the queue is
+empty or a documented stop condition fires.
+
+## Step 1 — Orient
+
+Read these files IN ORDER, in full, before any tool calls:
+
+1. `AGENTS.md` — hard rules.
+2. `CONVENTIONS.md` — authoring rules + ADR status semantics + plan
+   folder convention.
+3. `plan/README.md` — the queue convention.
+4. `_agent/CURRENT_FOCUS.md` — live session snapshot.
+5. `INDEX.md` — ADR catalogue.
+6. Tail of `_agent/WORKLOG.md` (last 30 lines).
+7. The queue item file at `plan/todo/NNNN-*.md` you are about to work,
+   and the ADR(s) it names.
+
+## Step 2 — Pick the next item
+
+`ls plan/todo/` and pick the lowest-numbered file (priority order).
+
+## Step 3 — Implement
+
+Implement against the ADR's numbered acceptance criteria. Add or
+update tests that map back to those criteria.
+
+## Step 4 — Verify
+
+Run the project's verify gate: `<command from Q8>`.
+
+Do not proceed if the gate fails. Surface the failure, fix the root
+cause, re-run. Do not bypass with `--no-verify` or equivalent.
+
+## Step 5 — Commit
+
+Conventional Commits per `AGENTS.md` §Git contract. `Rationale:`
+footer required on any commit touching an ADR.
+
+## Step 6 — Integrate
+
+<!-- Integration model per Q4b — keep ONE of the two blocks below,
+delete the other. -->
+
+<!-- Direct-to-main (fast-forward only). Keep this block for mode 1 /
+direct-to-main projects:
+
+- Fast-forward the work branch onto `main`:
+  `git merge --ff-only <work-branch>` (or commit directly on `main`
+  if that is the project's flow).
+- Push: `git push origin main`.
+- The verify gate has already passed locally (Step 4); no CI wait.
+-->
+
+<!-- PR-based (required CI green). Keep this block for mode 2/3 /
+PR-based projects:
+
+- Push the work branch: `git push -u origin <work-branch>`.
+- Open a draft PR: `gh pr create --draft --fill`.
+- Wait for CI: `gh pr checks --watch`. The verify gate runs in CI;
+  do not proceed until it is green.
+- Mark ready: `gh pr ready`.
+- Merge with the project's strategy:
+  `gh pr merge --squash --auto` (or `--merge` / `--rebase`).
+- Confirm the merge landed on `main` before treating the item as
+  shipped.
+-->
+
+## Step 7 — Ship the queue item
+
+Once the change is on `main` (fast-forwarded or PR-merged):
+
+- `git mv plan/todo/NNNN-<slug>.md plan/done/<YYYY-MM-DD>-<slug>.md`.
+- Amend the moved file with a "Shipped at HEAD `<sha>`" footer (and
+  any artefact id, image tag, deploy id, PR link).
+- Advance the owning ADR(s)' `status:` from `Accepted` to
+  `Implemented`; regenerate `INDEX.md`.
+
+## Step 8 — Record
+
+- Append a one-line `_agent/WORKLOG.md` entry naming the branch, the
+  HEAD, the verify result, any deferral.
+- Update `_agent/CURRENT_FOCUS.md` so the slim live snapshot reads
+  the new state. (In worktree mode this file is local-only; update
+  `_agent/IN_FLIGHT.md` to remove your worktree's row instead.)
+
+## Stop conditions
+
+- Verify gate fails and the cause is not understood.
+- Queue empty.
+- A queue item references an ADR whose status is not Accepted.
+- Acceptance criteria are ambiguous or untestable as written.
+- Lock contention on the same files between two same-priority items.
+
+When a stop condition fires, stop cleanly: leave the repo in a
+committed state, record the reason in `_agent/CURRENT_FOCUS.md`, and
+surface to the human.

package/skills/bootstrap/templates/adr-capability.md

@@ -0,0 +1,58 @@
+---
+adr: NNNN
+title: <Title in sentence case>
+status: Proposed
+date: YYYY-MM-DD
+owner: <agent-id or human>
+supersedes:
+superseded-by:
+depends-on: []
+tags: []
+---
+
+# ADR NNNN — <Title>
+
+## Context
+
+<Why this decision exists. Forces at play. What problem are we solving
+and what constraints shape the answer.>
+
+## Capability statement
+
+<One paragraph. What the system must do. Stated as capability, not
+implementation.>
+
+## User stories / scenarios
+
+- As a <role>, I want <capability>, so that <outcome>.
+- As a <role>, I want <capability>, so that <outcome>.
+
+## Acceptance criteria
+
+1. <Testable, observable criterion.>
+2. <Testable, observable criterion.>
+3. ...
+
+## Out of scope
+
+- <Explicit non-goals — what this ADR does not cover.>
+
+## Open questions
+
+- <Unresolved items. Empty when ADR transitions to Accepted.>
+
+## References / cross-links
+
+- adr/NNNN-<other>.md
+- <External links, specs, prior art.>
+
+## Revision History
+
+| Date | Revision | Author | Change |
+|------|----------|--------|--------|
+| YYYY-MM-DD | r1 | <id> | Initial draft. |
+
+## Approvals
+
+| Role | Name | Date | Signature |
+|------|------|------|-----------|

package/skills/bootstrap/templates/adr-technology.md

@@ -0,0 +1,67 @@
+---
+adr: NNNN
+title: <Title in sentence case>
+status: Proposed
+date: YYYY-MM-DD
+owner: <agent-id or human>
+supersedes:
+superseded-by:
+depends-on: []
+tags: []
+---
+
+# ADR NNNN — <Title>
+
+## Context
+
+<Why this decision exists. Constraints, forces, and the surface area of
+the choice.>
+
+## Decision
+
+<One paragraph stating the choice in plain terms. What is being adopted
+and at what scope.>
+
+## Rationale
+
+<Why this choice over the alternatives. List alternatives considered
+with specific rejection reasons. Generic rationale ("simpler", "more
+idiomatic") is not sufficient.>
+
+- Alternative A — rejected because <specific reason>.
+- Alternative B — rejected because <specific reason>.
+
+## Consequences
+
+- Positive: <what this enables.>
+- Negative: <what this costs or constrains.>
+- Follow-up work implied by this decision: <list.>
+
+## Acceptance criteria
+
+1. <Testable criterion that confirms the decision is in effect.>
+2. ...
+
+## Out of scope
+
+- <What this ADR deliberately does not decide.>
+
+## Open questions
+
+- <Unresolved items. Empty when ADR transitions to Accepted.>
+
+## References
+
+- adr/NNNN-<other>.md
+- <External specs, RFCs, vendor docs.>
+
+## Revision History
+
+| Date | Revision | Author | Change |
+|------|----------|--------|--------|
+| YYYY-MM-DD | r1 | <id> | Initial draft. |
+
+## Approvals
+
+| Role | Name | Date | Signature |
+|------|------|------|-----------|

package/skills/bootstrap/templates/plan-README.md

@@ -0,0 +1,37 @@
+# Plan
+
+This folder holds the project's implementation queue — one file per
+unit of work. The queue mirrors the ADR catalogue (`INDEX.md`) but
+tracks the human ordering of work, not the ADR catalogue ordering.
+
+## Layout
+
+- `plan/todo/NNNN-<slug>.md` — pending work, ordered by priority
+  (lower numbers run first). Each file names the owning ADR(s), the
+  scope, the exit criteria, and any dependencies.
+- `plan/done/<YYYY-MM-DD>-<slug>.md` — shipped work, ordered
+  chronologically. The `git mv` from `todo/` to `done/` is the
+  completion event; the file's body is amended with a "Shipped"
+  footer naming the HEAD SHA and any artefact id.
+
+## Convention
+
+- A pending item gets a `plan/todo/` file BEFORE work starts.
+- When work ships, the file is `git mv`'d to `plan/done/` with a new
+  date prefix and the body amended with the shipped footer.
+- A small fix that doesn't justify a plan file (a typo, a one-line
+  tweak, a dependency bump) skips the ceremony. Use judgement.
+- The status of the owning ADR(s) advances when the work ships:
+  `Accepted` → `Implemented`.
+
+## Status semantics on the owning ADRs
+
+| ADR status | Meaning |
+|---|---|
+| Proposed | Draft; decision authored but not yet approved. |
+| Accepted | Decision approved; implementation authorised. Sits in `plan/todo/`. |
+| Implemented | Shipped per the project's completion event. Sits in `plan/done/`. |
+| Superseded | Replaced by another ADR (named in `superseded-by:`). |
+| Deprecated | Was real; the world moved on; no successor. |
+
+See `CONVENTIONS.md` §Status lifecycle for the canonical definition.

package/skills/brainstorm/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: brainstorm
+description: Decompose a problem, feature, or goal into candidate ADRs and plan items for a documentation-led repo — one decision per ADR, dependency edges, suggested ordering. Proposes drafts for review and writes nothing until approved. Use when the user says "brainstorm ADRs", "break this down into decisions", "what ADRs do we need for X", "plan out the work", or invokes /brainstorm.
+---
+
+# brainstorm
+
+Turn a fuzzy problem into a structured set of candidate ADRs and plan
+items. This skill is **generative and read/propose-only** — it never
+writes ADRs or plan files directly. On approval it hands each candidate
+to the **new-adr** and **new-plan** skills.
+
+## Step 0 — Preconditions and context
+
+1. Confirm the repo is bootstrapped (or note that the output can seed a
+   fresh run of the **bootstrap** skill).
+2. Read `CONVENTIONS.md` for ADR shape and lifecycle, and skim
+   `INDEX.md` + existing ADRs so candidates don't duplicate or
+   contradict what already exists, and so dependencies point at real
+   ADRs.
+
+## Step 1 — Understand the problem
+
+Ask for the goal/feature/problem if not given. Probe for scope
+boundaries, constraints, and the regulatory/quality concerns that
+matter for this repo. Do not start decomposing until the goal is clear.
+
+## Step 2 — Decompose
+
+Produce a candidate list. For each candidate ADR:
+- Proposed number (next available, contiguous), working title, shape
+  (capability vs. technology if the repo splits).
+- One-line scope — the single decision it captures.
+- Dependencies on other candidates or existing ADRs.
+
+**One decision per ADR.** If a candidate bundles several decisions,
+split it and say why. If a candidate is really an existing ADR needing
+revision, say that instead of proposing a new number.
+
+## Step 3 — Order the work
+
+Propose a plan ordering (which `plan/todo/` items, in what sequence)
+respecting the dependency edges. Note where work can parallelise (useful
+input for the **agent-wave** skill).
+
+## Step 4 — Review and hand off
+
+Present the full set as a reviewable outline (candidates + dependencies
++ ordering). Take edits. **Write nothing yet.** Once the user approves,
+create them by invoking the **new-adr** skill per candidate and the
+**new-plan** skill per
+queued item — or hand the approved outline to those skills.
+
+Guardrail: if the problem is too vague to decompose without inventing
+requirements, say so and ask for more, rather than producing
+speculative ADRs.