@evolvehq/docflow 0.9.2 → 0.9.3

package/README.md

@@ -39,23 +39,41 @@ and point you at `/bootstrap`.
 
 ## What `/bootstrap` installs
 
+Only the **core** is always written; everything else is an **opt-in layer**
+chosen during the assessment, so a minimal repo stays as light as a classic
+ADR catalogue.
+
+**Core (always):**
 - `AGENTS.md` — hard rules for coding agents (the entry point).
-- `CLAUDE.md` — one-liner re-exporting `AGENTS.md` so Claude Code picks
-  it up automatically.
-- `CONVENTIONS.md` — authoring rules for ADRs, naming, status
-  lifecycle, audit trail, and git contract.
+- `CLAUDE.md` — one-liner re-exporting `AGENTS.md` so Claude Code picks it
+  up automatically.
+- `CONVENTIONS.md` — authoring rules for ADRs, naming, status lifecycle,
+  audit trail, and git contract.
 - `INDEX.md` — generated table of all ADRs.
-- `adr/` — ADR catalogue with a capability-ADR template (and an
-  optional technology-ADR template).
-- `plan/todo/` and `plan/done/` — implementation queue. `git mv` from
-  `todo/` to `done/` is the completion event.
-- `_agent/` — multi-agent coordination: `ROLES.md`, `LOCKS.md`,
-  `WORKLOG.md`, `CURRENT_FOCUS.md`, `HANDOFF.md`, and an optional
-  unsupervised-run prompt under `prompts/`.
-
-Optional, off by default: `GLOSSARY.md`, `domains/<slug>/README.md`
-groupings, project-specific hard rules (vendor-naming restriction,
-regulated-evidence posture, language mandate, audit-stream separation).
+- `adr/0000-template.md` — the ADR template; the catalogue starts here.
+
+**Optional layers (opt-in):**
+- `plan/todo/` + `plan/done/` — the implementation queue (Q4a). `git mv`
+  from `todo/` to `done/` is the completion event.
+- `_agent/` — coordination (`ROLES`, `LOCKS`, `WORKLOG`, `CURRENT_FOCUS`,
+  `HANDOFF`, optional `prompts/`). **Q5 — choose *None* to omit it.**
+- `GLOSSARY.md`, `domains/<slug>/README.md` groupings, the technology-ADR
+  template, and project-specific hard rules (vendor-naming, regulated
+  evidence, language mandate, audit-stream separation) — Q7/Q10.
+
+Omitting any optional layer leaves a valid repo; a lifecycle skill that
+needs an absent layer refuses cleanly and says what's missing.
+
+**Placement:** `AGENTS.md` and `CLAUDE.md` always stay at the repository
+root; everything else lives under a configurable **artefact root** —
+`docs/` (the default), the repo root, or `.docflow/` — chosen at bootstrap
+and recorded in `CONVENTIONS.md`.
+
+**Seed ADR:** by default, bootstrap also writes **`adr/0001`** — a first
+ADR recording the decision to adopt this method (self-documenting, like the
+classic "use ADRs" convention). It references `CONVENTIONS.md` for the rules
+and is created `Implemented`. Decline it at sign-off if you want only the
+template.
 
 ## Why
 
@@ -87,6 +105,18 @@ repo boundary; consistency is declared at the edges and enforced by audit. See t
 [methodology](https://evolvehq.github.io/docflow/methodology/#5-scaling-to-many-repositories)
 for the full model.
 
+## No drafts in the catalogue
+
+docflow records **outcomes, not work-in-progress**. There is **no `Draft`
+status** and **no `brainstorming/` folder** — an ADR's first persisted
+status is `Proposed`, created only once a decision is approved. The
+`brainstorm` skill explores candidates **in conversation and writes
+nothing** until you approve them; only then does `new-adr` mint a numbered
+ADR. This keeps the catalogue free of half-formed drafts and the numbering
+clean — numbers go only to real decisions — following the lightweight-ADR
+tradition that an ADR captures the agreed decision, not the discussion that
+produced it.
+
 ## Install
 
 docflow ships from **one skill source** (`plugins/docflow/skills/`) to
@@ -173,6 +203,9 @@ OpenCode has no marketplace command for `SKILL.md` skills (its plugin
 system is for npm JS plugins), so a shared skills directory is the clean
 path. Skills auto-load by description.
 
+**OpenCode-compatible forks** — e.g. Xiaomi's *mimocode* — inherit this
+support via the same skill-discovery path; no separate packaging.
+
 ### Claude Code — local development (no install)
 
 ```

package/USAGE.md

@@ -165,6 +165,7 @@ After sign-off, the skill writes:
 | `CLAUDE.md` | `templates/CLAUDE.md` | Single line `@AGENTS.md`. |
 | `adr/0000-template.md` | `templates/adr-capability.md` | Capability-ADR template. |
 | `adr/NNNN-template.md` | `templates/adr-technology.md` | Technology-ADR template. Only if Q2 said split. `NNNN` is the project-defined cutoff (default 0100). |
+| `adr/0001-record-architecture-decisions.md` | `templates/adr-0001-seed.md` | **Seed ADR** recording the decision to adopt the method (`Implemented`, references `CONVENTIONS.md`). Default on; declined at sign-off if not wanted. |
 | `plan/README.md` | `templates/plan-README.md` | Plus empty `plan/todo/.gitkeep` and `plan/done/.gitkeep`. |
 | `_agent/ROLES.md` | `templates/_agent-ROLES.md` | Single `default-agent` by default. |
 | `_agent/LOCKS.md` | `templates/_agent-LOCKS.md` | Empty header. Created only if Q5 enabled LOCKS discipline. |
@@ -174,7 +175,7 @@ After sign-off, the skill writes:
 | `_agent/IN_FLIGHT.md` | `templates/_agent-IN_FLIGHT.md` | Only in Q5 mode 3 (worktree). Committed cross-worktree dashboard. |
 | `.gitattributes` (entry) | (none — inline) | Only in Q5 mode 3: appends `_agent/WORKLOG.md merge=union`. |
 | `.gitignore` (entry) | (none — inline) | Only in Q5 mode 3: adds `_agent/CURRENT_FOCUS.md` so it stays local-only. |
-| `INDEX.md` | (none — generated) | Stub header + empty table. |
+| `INDEX.md` | (none — generated) | Header + the seed ADR's row (empty table only if the seed was declined). |
 | `_agent/prompts/autonomous.md` | `templates/_agent-prompts-autonomous.md` | Only if Q8 confirmed a verify gate. |
 
 ## 5. After scaffolding
@@ -345,6 +346,11 @@ scheme:
   and `INDEX.md`).
 - **G3 — gate backstop:** the single-threaded merge gate rejects a
   duplicate; the later author renumbers.
+- **G4 — claim before do:** before implementing a queued item, claim it (a
+  draft PR referencing it, or an `IN_FLIGHT`/`owner` entry) so two writers
+  don't build the same unclaimed `plan/todo` item — G1–G3 protect the
+  *number*, G4 protects the *work assignment*; the audit's
+  duplicate-plan-ownership check is the backstop.
 
 `bootstrap` **pre-wires** these into `CONVENTIONS.md` + an `AGENTS.md`
 hard rule **only** for multi-agent (mode 2/3) or PR-based repos.
@@ -353,6 +359,26 @@ get none of this ceremony. Numbers are immutable once merged. (For
 orchestrated runs, `agent-wave` additionally *reserves* disjoint number
 blocks up front, so G2/G3 rarely fire.)
 
+### Numbering at scale, and grouping by domain
+
+ADR numbers are **integers**; the four-digit zero-padding is cosmetic and
+sorts **numerically**, so a catalogue is not capped at `9999` — widen the
+padding to five digits if you ever approach it (no real catalogue does).
+
+Two alternative identifier schemes are intentionally *not* used (the
+[methodology](https://evolvehq.github.io/docflow/methodology/#46-numbering-at-scale-and-alternatives-considered)
+has the full reasoning): **timestamp / opaque ids** — they trade away
+ordering and readability, and the guardrails above handle collisions
+instead; and **per-domain numbering** like `auth/0001` — the federation
+serves genuinely independent sequences, and within one repo you group
+rather than renumber.
+
+**Grouping by domain.** Opt in to `domains/<slug>/README.md` files that
+list the ADRs for each area (e.g. `domains/auth/`, `domains/billing/`). It
+is purely organisational: each ADR keeps its flat number and its `INDEX.md`
+row; the domain README is a curated view, not a namespace. Reach for it
+when a flat catalogue grows large enough to be hard to navigate.
+
 ## 6. Customising or extending
 
 The templates are deliberately small and self-contained. To customise:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evolvehq/docflow",
-  "version": "0.9.2",
+  "version": "0.9.3",
   "description": "ADR-driven documentation workflow: scaffold an Architecture Decision Record (ADR) catalogue, a plan/ queue, and AGENTS.md conventions into any repo, then author, queue, ship, audit, and roll up ADRs with lifecycle skills — across one repo or a multi-repo product. Works on Claude Code, Claude Cowork, pi, Codex, and OpenCode.",
   "keywords": [
     "pi-package",

package/plugins/docflow/skills/audit/SKILL.md

@@ -14,7 +14,9 @@ This is the enforcement `AGENTS.md` cannot guarantee on its own.
 2. Read `CONVENTIONS.md` to learn what to enforce: ADR shape and
    cutoff, status lifecycle, integration model, multi-agent mode,
    language mandate, optional artefacts present (GLOSSARY, domains/),
-   and any Q10 domain hard rules.
+   and any Q10 domain hard rules, and the **artefact root** (default:
+   repository root) — resolve `adr/`, `plan/`, `INDEX.md` against it and
+   honour it in the cross-reference and INDEX-sync checks.
 3. If a `federation.md` exists, this repo is part of a multi-repo
    product. Note its `Role` (`central` / `home` / `coordinator`
    index-holder, or a plain `member`) and read the recorded identity
@@ -49,7 +51,8 @@ relevant):
    `adr-0042`, `see ADR`, ADR titles — in UI copy, API responses,
    error messages, customer-facing logs, public docs, release notes.
    Report each suspect; this rule is easy to violate by reflex.
-10. **Coordination hygiene.** `_agent/LOCKS.md` has no stale claims
+10. **Coordination hygiene.** N/A if `_agent/` was omitted at bootstrap
+    (Q5 = None). Otherwise: `_agent/LOCKS.md` has no stale claims
     (mode 2); `_agent/IN_FLIGHT.md` rows match live worktrees (mode 3).
 11. **Cross-worktree collisions** (mode 3, or when auditing across
     unmerged branches). These catch semantic conflicts that a

package/plugins/docflow/skills/bootstrap/SKILL.md

@@ -57,6 +57,20 @@ questions.
   federation-index.md    # multi-repo only (Q11): member index — home repo only
 ```
 
+**Placement.** The tree above shows the **root** option. `AGENTS.md` and
+`CLAUDE.md` always sit at the repository root; `adr/`, `plan/`, `_agent/`,
+`INDEX.md`, and `CONVENTIONS.md` go under the **artefact root** chosen in
+Q12 (default `docs/`, e.g. `docs/adr/`, `docs/plan/`).
+
+**Core vs optional layers.** Only the **core** is always written:
+`AGENTS.md`, `CLAUDE.md`, `CONVENTIONS.md`, `adr/0000-template.md`, and
+`INDEX.md`. A repo with just these is a valid, lightweight docflow repo — a
+classic ADR catalogue with conventions. Everything else is an **opt-in
+layer**: the `plan/` queue (Q4a), the `_agent/` coordination set (Q5 —
+choose *None* to omit it), `GLOSSARY.md` and `domains/` (Q7). Omitting any
+optional layer is a valid state, not an error; a lifecycle skill that needs
+an absent layer refuses cleanly and names what is missing.
+
 For a **multi-repo product** (one product spread across several repos —
 see Q11), two extra files appear: `federation.md`, a small back-pointer
 every member repo carries, and `federation-index.md`, the authoritative
@@ -122,7 +136,7 @@ A standalone repo has none of them.
     doubt, ask whether a non-builder would ever see this string — if
     yes, the ADR reference comes out.
 
-## Step 4 — Assessment (10 questions, plus an optional federation question)
+## Step 4 — Assessment (10 questions, plus federation (Q11) and placement (Q12))
 
 **Ask the questions one at a time, not in a batch.** For each question,
 state a **recommended** option (label it "Recommended") with one short
@@ -136,7 +150,9 @@ ask in plain text, listing options as A/B/C and naming the recommended
 one.
 
 After the answers are in, summarise the resulting plan in 5–10
-lines and ask for sign-off before writing any files.
+lines and ask for sign-off before writing any files. Note in the summary
+that a **seed ADR `0001`** recording the adopted method is created by
+default (the operator may decline it — see Step 5 item 5b).
 
 1. **Project identity.** Name, one-line description, doc language
    (en-GB / en-US / other), and — if existing repo — what current files
@@ -173,8 +189,16 @@ lines and ask for sign-off before writing any files.
      marks ready, merges. Ask the user for merge strategy
      (squash / merge / rebase — default: squash for clean history,
      rebase if per-commit identity matters).
-5. **Multi-agent setup.** Pick one — the three options have different
-   coordination-file shapes, and switching later is not free:
+5. **Coordination — by number of writers.** Pick by how many people/agents
+   *write* to this repo and how they integrate — **writers (integration
+   concurrency), not how many agents you run.** A team of several developers
+   is multi-writer even with one agent each, and wants the worktree/PR
+   shape. This sets the `_agent/` shape (or omits it); switching later is
+   not free:
+   - **None — omit `_agent/`.** A solo human/agent with no coordination
+     need; no `_agent/` directory is written, and lifecycle skills skip the
+     WORKLOG/snapshot steps. The lightest footprint (the optional `_agent/`
+     layer is left out — see the core-vs-optional note in Step 2).
    - **(Recommended) Single agent.** `default-agent` in ROLES.
      LOCKS skipped. WORKLOG / CURRENT_FOCUS as standard single-file
      snapshots. Right for small projects and the "one human + one
@@ -259,6 +283,20 @@ lines and ask for sign-off before writing any files.
     repo; adding this repo to the member index is a deliberate edit in
     the home repo. A standalone repo (Q11 = No) writes none of these
     files and behaves exactly as a single-repo bootstrap.
+12. **Artefact placement.** Where the non-entry artefacts live — `adr/`,
+    `plan/`, `_agent/`, `INDEX.md`, `CONVENTIONS.md`:
+    - **(Recommended) `docs/`** — aligns with the common `doc/adr` / `docs/`
+      convention; keeps the repo root clean (`docs/adr/`, `docs/plan/`, …).
+    - **Repository root** — flat layout; decisions beside the code (good for
+      monorepos). This is docflow's own layout.
+    - **`.docflow/`** — hidden root; quietest footprint.
+
+    `AGENTS.md` and `CLAUDE.md` are **always** written to the repository
+    root (coding agents discover them there). The chosen root is recorded in
+    `CONVENTIONS.md`, and every lifecycle skill resolves `adr/`, `plan/`,
+    and `INDEX.md` against it. For an existing repo already laid out
+    differently, offer a documented migration (`git mv` into the chosen root
+    + update `CONVENTIONS.md`) — never force it.
 
 ## Step 4.5 — Cross-check before sign-off
 
@@ -287,6 +325,13 @@ Templates live in this skill's `templates/` directory. Read each
 template, fill its placeholders from the assessment answers, then
 write it into the repo.
 
+**Placement (Q12):** write `AGENTS.md` and `CLAUDE.md` to the repository
+root; write everything below under the chosen **artefact root** (default
+`docs/`) — e.g. `docs/adr/0000-template.md`, `docs/plan/`, `docs/INDEX.md`.
+Record the chosen root in `CONVENTIONS.md` so every lifecycle skill resolves
+paths against it, and adjust the `adr/`/`plan/` cross-paths in the filled
+`AGENTS.md` (and other templates) to the chosen root (e.g. `docs/adr/`).
+
 1. `CONVENTIONS.md` — from `templates/CONVENTIONS.md`. Spec other files
    reference. Include the **§Concurrency Guardrails** section only if Q5
    is mode 2/3 **or** Q4b is PR-based; omit it for single-agent
@@ -294,16 +339,29 @@ write it into the repo.
    (multi-repo)** section only if Q11 = yes; fill `<product>` and state
    the chosen identity scheme. Omit it for standalone repos.
 2. `AGENTS.md` — from `templates/AGENTS.md`. Include the concurrency
-   guardrails hard-rule bullet (G2/G3) under the same condition as the
+   guardrails hard-rule bullet (G2–G4) under the same condition as the
    CONVENTIONS section above; omit otherwise.
 3. `CLAUDE.md` — from `templates/CLAUDE.md` (single line `@AGENTS.md`).
 4. `adr/0000-template.md` — from `templates/adr-capability.md`.
 5. `adr/NNNN-template.md` — from `templates/adr-technology.md`, only if
    Q2 said split. `NNNN` is the number where capability ADRs end
    (project-defined, e.g. 0091; default 0100 if unspecified).
+5b. **Seed ADR (default on; opt-out at sign-off).** Write the seed
+   `adr/0001-record-architecture-decisions.md` from
+   `templates/adr-0001-seed.md`, filled from the assessment answers — it
+   records the **decision to adopt** the documentation-led, ADR-driven
+   method, status **`Implemented`**, and **references `CONVENTIONS.md`** for
+   the rules (it does not duplicate them). Keep it generic — no other
+   project's ADR numbers. **Skip only if the operator opted out.** For a
+   **split** repo (Q2) use the technology-ADR shape for the seed. If `plan/`
+   exists, also write a matching `plan/done/<date>-adopt-adr-method.md` (the
+   seed's completion event is this bootstrap), so plan-coverage stays
+   satisfied. On a **retrofit/backfill** (Step 6), the seed is `0001`, ahead
+   of the reconstructed decisions.
 6. `plan/README.md` — from `templates/plan-README.md`. Create empty
    `plan/todo/.gitkeep` and `plan/done/.gitkeep`.
-7. `_agent/ROLES.md` — from `templates/_agent-ROLES.md`. Mode 1
+7. `_agent/ROLES.md` — from `templates/_agent-ROLES.md`. **If Q5 = None,
+   skip items 7–11 entirely — no `_agent/` directory.** Otherwise: Mode 1
    keeps the `default-agent` block; modes 2 and 3 expand to named
    agents per Q5.
 8. `_agent/LOCKS.md` — from `templates/_agent-LOCKS.md`. **Skip in
@@ -319,7 +377,8 @@ write it into the repo.
     `_agent/IN_FLIGHT.md` from `templates/_agent-IN_FLIGHT.md` as
     the committed cross-worktree dashboard.
 11. `_agent/HANDOFF.md` — from `templates/_agent-HANDOFF.md`.
-12. Stub `INDEX.md` — header + empty table.
+12. `INDEX.md` — header + the seed ADR's row (item 5b); an empty table only
+    if the seed was declined.
 13. `_agent/prompts/autonomous.md` — from
     `templates/_agent-prompts-autonomous.md`, **only** if Q8 confirmed a
     verify gate. Keep the integration block matching Q4b: the

package/plugins/docflow/skills/bootstrap/templates/CONVENTIONS.md

@@ -4,6 +4,10 @@
 
 Project name: <name>.
 
+Artefact root: `<docs/ | . | .docflow/>` — `adr/`, `plan/`, `INDEX.md`, and
+this file live under this root; `AGENTS.md` and `CLAUDE.md` always stay at
+the repository root. Every lifecycle skill resolves paths against this root.
+
 <!-- 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
@@ -14,6 +18,14 @@ files." -->
 ADR filenames use `NNNN-kebab-case-slug.md`, zero-padded to 4 digits,
 with contiguous numbering and no reserved gaps.
 
+The number is an **integer**; the four-digit zero-padding is a display
+convention only — tools sort ADRs **numerically**, not lexically, so the
+catalogue is not capped at `9999` (widen the padding to five digits if you
+ever approach it; none do). Related ADRs may be **grouped** under
+`domains/<slug>/README.md` without changing their numbers — grouping is a
+curated view, not a separate namespace; the contiguous number stays the
+single identity.
+
 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.
@@ -31,6 +43,11 @@ Status lifecycle: `<from Q3>`.
 Terminal states (Superseded / Deprecated) are reachable from any prior
 state.
 
+The first **persisted** status is `Proposed` — there is no separate `Draft`
+state and no `brainstorming/`/`drafts/` folder. Work-in-progress lives in
+the brainstorm conversation; only an approved decision is written, as a
+numbered `Proposed` ADR.
+
 Cross-references link by relative path to `adr/NNNN-*.md`.
 
 ## ADR Shapes
@@ -165,6 +182,13 @@ once merged:
 - **G3 — gate backstop.** Integration is single-threaded; it rejects a
   duplicate number as the last line of defence, and the later author
   renumbers.
+- **G4 — claim before do.** Before implementing a queued item, **claim it**
+  so two writers don't build the same thing: open a draft PR referencing
+  the item (the authoritative claim in PR-based / worktree repos), or record
+  an `owner` / `_agent/IN_FLIGHT.md` entry. An unclaimed `plan/todo` item on
+  `main` (which G1 deliberately puts there) is otherwise an open invitation
+  to duplicate effort. G1–G3 protect the *number*; G4 protects the *work
+  assignment*. `/audit`'s duplicate-plan-ownership check is the backstop.
 -->
 
 <!-- Federation (multi-repo) — bootstrap INCLUDES this section

package/plugins/docflow/skills/bootstrap/templates/adr-0001-seed.md

@@ -0,0 +1,81 @@
+---
+adr: 0001
+title: Record architecture decisions as ADRs
+status: Implemented
+date: <YYYY-MM-DD>
+owner: <agent-id or human>
+supersedes:
+superseded-by:
+depends-on: []
+tags: [process, conventions]
+---
+
+# ADR 0001 — Record architecture decisions as ADRs
+
+<!-- Bootstrap writes this as the seed ADR (adr/0001) by default. It records
+the *decision* to adopt the method; the operative rules live in
+CONVENTIONS.md. Keep it generic — do not reference another project's ADR
+numbers. For a split-shape repo, adapt to the technology-ADR shape. -->
+
+## Context
+
+<Project> needs its significant decisions to be **discoverable, traceable,
+and durable** — not held in chat logs, pull-request threads, or one
+person's memory. The lightweight Architecture Decision Record practice
+(Michael Nygard, 2011; the markdown-ADR convention) records each decision
+as one small, numbered, immutable file stored beside the code, so the
+reasons behind the system are part of the repository.
+
+## Capability statement
+
+This repository is **documentation-led and ADR-driven**: every significant
+decision is recorded as a numbered ADR under `adr/`; the catalogue is the
+**source of truth** the running system is expected to match; and a status
+lifecycle drives a `plan/` work queue. The authoring rules — ADR shape,
+status lifecycle, numbering, audit trail, and git contract — live in
+`CONVENTIONS.md`. This ADR records the **decision to adopt the practice**,
+not the rules themselves.
+
+## User stories / scenarios
+
+- As a contributor, I find the reasons behind this system in the catalogue,
+  not by asking someone.
+- As a maintainer, each decision, the work that implements it, and the
+  commit that ships it are linked through one stable identifier.
+- As a new reader, the first ADR explains why this repository uses ADRs and
+  points me at where the rules live.
+
+## Acceptance criteria
+
+1. Significant decisions are recorded as numbered ADRs under `adr/`,
+   following `CONVENTIONS.md`.
+2. The catalogue is the source of truth; code is expected to match the
+   decisions it records.
+3. ADR authoring, the status lifecycle, and the `plan/` queue follow
+   `CONVENTIONS.md`.
+
+## Out of scope
+
+- The detailed authoring rules (ADR shape, lifecycle, numbering, git
+  contract) — these live in `CONVENTIONS.md`, not here.
+
+## Open questions
+
+- None.
+
+## References / cross-links
+
+- CONVENTIONS.md (the operative authoring rules)
+- Michael Nygard, "Documenting Architecture Decisions" — https://adr.github.io
+
+## Revision History
+
+| Date | Revision | Author | Change |
+|------|----------|--------|--------|
+| <YYYY-MM-DD> | r1 | <owner> | Adopted the documentation-led, ADR-driven method (seeded at bootstrap). |
+
+## Approvals
+
+| Role | Name | Date | Signature |
+|------|------|------|-----------|
+| <role> | <name> | <YYYY-MM-DD> | — |

package/plugins/docflow/skills/new-adr/SKILL.md

@@ -15,7 +15,9 @@ Author one new ADR, consistent with this repo's conventions.
 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.
+   groupings exist, the multi-agent mode, and the **artefact root**
+   (default: repository root) — resolve `adr/` and `INDEX.md` against it
+   (`AGENTS.md`/`CLAUDE.md` stay at the repo root).
 3. Read `INDEX.md` and `ls adr/` to learn existing numbers and titles.
 4. If a `federation.md` exists, this repo is part of a multi-repo
    product. Note the **identity scheme** and the **home** it records —

package/plugins/docflow/skills/new-plan/SKILL.md

@@ -13,7 +13,8 @@ Add one item to the implementation queue.
    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.
+   completion event, and `plan/README.md` if present. Resolve `plan/`
+   against the **artefact root** recorded there (default: repository root).
 3. `ls plan/todo/` to learn existing numbers and priority ordering.
 
 ## Step 0.5 — Assessment (run first)

package/plugins/docflow/skills/ship-item/SKILL.md

@@ -14,7 +14,9 @@ order-sensitive operation in the system — follow the steps exactly.
 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).
+   contract (signed commits, tags, trailers). Resolve `adr/`, `plan/`, and
+   `INDEX.md` against the **artefact root** recorded in `CONVENTIONS.md`
+   (default: repository root).
 
 ## Step 1 — Select the item
 
@@ -53,6 +55,9 @@ Once the change is on `main`:
 
 ## Step 6 — Record
 
+**If `_agent/` was omitted at bootstrap (Q5 = None), skip this step** — git
+history is the 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