@evolvehq/docflow 0.4.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eugenio Minardi / EvolveHQ
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,188 @@
+# docflow
+
+A plugin for **ADR-driven, documentation-led projects**, working on both
+the **pi** and **Claude Code** coding agents from the same skill files.
+It installs a `bootstrap` skill that scaffolds (or retrofits) an
+**Architecture Decision Record (ADR)** catalogue, a plan queue, and
+`AGENTS.md` conventions into any repository, plus a set of **lifecycle
+skills** that author, queue, ship, and audit ADRs — so the project can
+be driven by both humans and coding agents from a small set of canonical
+files.
+
+## Skills
+
+Slash commands below are the **Claude Code** form. On the **pi** coding
+agent the same skills are invoked as `/skill:<name>` (e.g.
+`/skill:bootstrap`, `/skill:new-adr`). See [Install](#install).
+
+| Skill | Slash command | Purpose |
+|-------|---------------|---------|
+| bootstrap | `/bootstrap` | Scaffold or retrofit the whole convention set. Start here. |
+| new-adr | `/new-adr` | Author one ADR — next contiguous number, right shape, INDEX + domain wiring, supersede linkage. |
+| new-plan | `/new-plan` | Add a `plan/todo` item tracing to its owning ADR(s). |
+| ship-item | `/ship-item` | Run the completion event: verify → integrate → `todo`→`done` → ADR `Accepted`→`Implemented` → INDEX/WORKLOG. |
+| add-convention | `/add-convention` | Assess whether a convention is worth codifying, route it to the right home (or to an ADR), then add it. |
+| audit | `/audit` | Lint the repo against its own conventions — numbering, INDEX sync, plan coverage, **ADR-privacy leaks**, more. |
+| brainstorm | `/brainstorm` | Decompose a problem into candidate ADRs + plan items (proposes drafts; writes nothing until approved). |
+| agent-wave | `/agent-wave` | Orchestrate a wave of parallel worktree subagents over the queue, with checkpoint or continuous supervision. |
+
+The lifecycle skills all **read `CONVENTIONS.md` first** and honour the
+choices the bootstrap recorded (ADR shape, status lifecycle, integration
+model, multi-agent mode). They refuse to run on an un-bootstrapped repo
+and point you at `/bootstrap`.
+
+## What `/bootstrap` installs
+
+- `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.
+- `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).
+
+## Why
+
+Documentation-led projects rot when conventions live in someone's head.
+This plugin makes the conventions explicit, machine-readable, and
+applied uniformly — so a fresh contributor (human or agent) can pick up
+the repo with no oral handover.
+
+It works equally well on **fresh repos** (scaffolds from zero) and on
+**existing repos** (retrofits, preserving and merging existing files
+rather than overwriting them).
+
+## Install
+
+docflow ships for two coding agents from the **same** skill files — only
+the manifest differs (`.claude-plugin/` for Claude Code, `package.json`
+for pi).
+
+### Claude Code — from this marketplace
+
+```
+/plugin marketplace add EvolveHQ/docflow
+/plugin install docflow@evolvehq
+```
+
+Invoke with `/bootstrap`, `/new-adr`, `/ship-item`, … (auto-triggers on
+matching requests too).
+
+### pi coding agent
+
+```
+pi install git:github.com/EvolveHQ/docflow
+```
+
+or, once published to npm, `pi install npm:@evolvehq/docflow`. Pi
+auto-discovers the `skills/` directory via the `pi` key in
+`package.json`. Invoke with `/skill:bootstrap`, `/skill:new-adr`,
+`/skill:ship-item`, … Pi does **not** auto-trigger skills from their
+descriptions the way Claude Code does — invoke them explicitly (the
+agent will also load a skill on-demand when a task clearly matches).
+
+The scaffolded output (`AGENTS.md`, `CONVENTIONS.md`, the ADR catalogue,
+`plan/`, `_agent/`) is plain Markdown and is read natively by pi's
+hierarchical `AGENTS.md` loading — no porting needed.
+
+### Claude Code — local development (no install)
+
+```
+claude --plugin-dir <path-to-this-repo>
+```
+
+### Direct skill clone (no plugin lifecycle)
+
+```
+git clone https://github.com/EvolveHQ/docflow ~/.claude/skills/docflow-src
+ln -s ~/.claude/skills/docflow-src/skills/bootstrap ~/.claude/skills/bootstrap
+```
+
+On Windows, copy `skills/bootstrap/` (and the other `skills/*` dirs you
+want) into `%USERPROFILE%\.claude\skills\` instead of symlinking.
+
+## Quick start
+
+In any repo, run:
+
+```
+/bootstrap
+```
+
+or just say *"set up documentation-led conventions in this repo"*,
+*"bootstrap ADRs and a plan queue"*, or *"scaffold AGENTS.md and the
+_agent/ layout"*. The skill auto-triggers on those phrasings.
+
+The skill will:
+
+1. Detect whether the repo is fresh or existing, and state which.
+2. Ask 10 assessment questions to tune the conventions to the project
+   — one at a time, with a recommended option for each.
+3. Summarise the resulting plan and ask for sign-off.
+4. Write (or Edit, for existing repos) the files.
+5. Commit each logical group with a Conventional Commit message.
+6. **On existing repos**, offer to backfill ADRs, `plan/done/`, and
+   `CONVENTIONS.md` additions from the existing code and git history
+   — drafts only, approved in batches before anything commits.
+
+## Updating
+
+Recipients refresh installations with:
+
+```
+/plugin marketplace update evolvehq
+/plugin install docflow@evolvehq
+```
+
+See [USAGE.md §Updating the plugin](USAGE.md#8-updating-the-plugin)
+for the author-side flow (version bumps, release tags) and recipient
+options including `/reload-plugins` for live sessions.
+
+## Full usage and customisation guide
+
+See [USAGE.md](USAGE.md) for the assessment questions, what each
+answer changes, the file-by-file output, the backfill flow, and how
+to extend or override the templates.
+
+## Layout
+
+```
+docflow/
+  .claude-plugin/
+    plugin.json          # Claude Code plugin manifest
+    marketplace.json     # Claude Code marketplace listing (repo is its own marketplace)
+  package.json           # pi package manifest (pi.skills -> ./skills) + npm metadata
+  skills/
+    bootstrap/
+      SKILL.md           # bootstrap: assessment + output sequence + backfill
+      templates/         # files the bootstrap reads and writes into target repos
+    new-adr/SKILL.md     # lifecycle skills — operate on a bootstrapped repo,
+    new-plan/SKILL.md    #   read CONVENTIONS.md, honour its choices
+    ship-item/SKILL.md
+    add-convention/SKILL.md
+    audit/SKILL.md
+    brainstorm/SKILL.md
+    agent-wave/SKILL.md
+  README.md
+  USAGE.md
+```
+
+Only the `bootstrap` skill uses `skills/bootstrap/templates/`. The
+lifecycle skills act on the copies the bootstrap wrote into the target
+repo (e.g. its `adr/0000-template.md`), so they carry no templates of
+their own.
+
+## License
+
+MIT. Use it, fork it, change it. If you improve a template, a PR is
+welcome.

package/USAGE.md

@@ -0,0 +1,289 @@
+# Using docflow
+
+This document explains how the `bootstrap` skill behaves end-to-end,
+what each of the 10 assessment questions actually changes in the
+output, and how to customise or extend the templates. The lifecycle
+skills are covered in §5a.
+
+For installation, see the [README](README.md).
+
+## 1. Triggering the bootstrap skill
+
+Once the plugin is installed (or `--plugin-dir`'d) into a Claude Code
+session, the skill is available in any repo. Three ways to trigger:
+
+1. **Slash command:** `/bootstrap`.
+2. **Natural language** matching the skill's description, e.g.
+   - "set up documentation-led conventions in this repo"
+   - "bootstrap ADRs and a plan queue"
+   - "scaffold AGENTS.md and the _agent/ layout"
+   - "retrofit this existing repo with the documentation conventions"
+3. **From another agent's prompt** — name the skill explicitly:
+   *"invoke the `bootstrap` skill on this repository."*
+
+## 2. The flow
+
+The skill runs in three phases.
+
+### Phase A — Detect
+
+The skill inspects the repo and states in one line whether it is:
+
+- **Fresh** — no source, no docs. It will scaffold from zero.
+- **Existing** — it reads any current `README.md`, `CONTRIBUTING.md`,
+  `AGENTS.md`, `CLAUDE.md`, `docs/`, `adr/`, `.github/` first.
+  Existing content is preserved; merges, not overwrites.
+
+If existing ADRs use a different format, the skill proposes a
+migration plan (renumber, keep, translate) instead of creating a
+parallel tree.
+
+### Phase B — Assess
+
+The skill asks the 10 assessment questions **one at a time**, in order.
+For each question it states a **recommended** option with one short
+sentence on why, plus the alternatives. You pick the recommended
+option, pick an alternative, or type a custom answer. After all 10
+answers are in, the skill summarises the resulting plan in 5–10 lines
+and asks for sign-off. **It does not write files before sign-off.**
+
+If the host CLI supports structured single-select (e.g. Claude Code's
+`AskUserQuestion`), the recommended option is labelled "(Recommended)"
+in the picker; otherwise the recommendation is named in plain text.
+
+### Phase C — Write
+
+After sign-off, the skill writes files in dependency order
+(`CONVENTIONS.md` first, then `AGENTS.md` + `CLAUDE.md`, then ADR
+templates, then `plan/`, then `_agent/`, then `INDEX.md` stub,
+optionally `_agent/prompts/autonomous.md`). For existing repos it
+prefers `Edit` over `Write` where files already exist, and calls out
+every merge decision in the commit message.
+
+### Phase D — Backfill (existing repos only)
+
+Once the scaffolding has landed, the skill **offers** to backfill
+ADRs, `plan/done/` entries, and `CONVENTIONS.md` additions from the
+existing code and git history. Skipped on fresh repos.
+
+If accepted, the backfill runs in four passes, each producing drafts
+you review before they commit:
+
+1. **Scan** (read-only): `git log`, top-level source dirs, existing
+   docs, dependency manifests.
+2. **Propose ADRs.** One per distinguishable decision or capability.
+   Capabilities go in as capability ADRs with status `Implemented`
+   (code already exists), Revision History citing the commits that
+   introduced the behaviour. Technology choices go in as technology
+   ADRs with reconstructed Rationale — anything speculative is flagged
+   so you can correct it. You see the proposed list (number + title +
+   status + scope) before any file is written.
+3. **Propose `plan/done/` entries.** One per ADR drafted as
+   `Implemented`, dated by the implementing commit's date. Approved as
+   a batch.
+4. **Propose `CONVENTIONS.md` additions.** De-facto patterns in the
+   repo (commit-message style, branch naming, test layout, file-naming
+   rules, tooling defaults) promoted to written rules. Diff shown
+   before applying.
+
+Each accepted pass commits with a Conventional Commit:
+`docs(adr): backfill ADRs 0001-00NN from code and history`,
+`docs(plan): backfill plan/done from shipped commits`,
+`docs: backfill conventions from de-facto patterns`. `INDEX.md` is
+regenerated after the ADR pass.
+
+**Guardrails.** Everything is a draft; you approve each pass. If
+history is sparse or unclear, the skill stops rather than invent
+rationale. Declining the backfill is fine — the scaffolding is
+already complete and the queue is just empty until the first
+hand-authored ADR.
+
+## 3. The 10 assessment questions
+
+Each question's answer changes specific files. Knowing the
+recommendation and what it changes up front helps you answer quickly.
+
+| # | Question | Recommended | What it changes |
+|---|----------|-------------|-----------------|
+| 1 | **Project identity** — name, one-liner, doc language, existing files to preserve. | *No default — project-specific.* | Header of `AGENTS.md`, `CONVENTIONS.md`, `README.md`; language mandate (if any) added to `CONVENTIONS.md` §Project. |
+| 2 | **ADR shape** — single vs. capability-vs-technology split. | **Single shape.** Start simple; split later if long-lived product requirements clearly outlive their implementations. | Whether `adr/NNNN-template.md` (technology) is created in addition to `adr/0000-template.md`. Section-order rules in `CONVENTIONS.md` §ADR Shapes and `AGENTS.md` §Hard rules. |
+| 3 | **Status lifecycle** — full or shorter. | **Full lifecycle.** The `Implemented` rung is cheap and gives a clear "what's shipped" signal. | Status table in `CONVENTIONS.md` §ADR Files and `plan/README.md` §Status semantics. Whether the `Implemented` rung exists at all. |
+| 4 | **Plan folder + integration model.** Q4a: use `plan/todo/` + `plan/done/` or skip. Q4b: how work reaches `main` — **direct-to-main (fast-forward)** or **PR-based (required CI green)**. Asked after Q5, because the Q4b recommendation depends on the multi-agent mode. | **Q4a: use it.** **Q4b: direct-to-main if Q5 = single agent; PR-based if Q5 = multi-agent.** | Whether `plan/` is created. The completion-event sentence in `CONVENTIONS.md` §Plan Folder, `plan/README.md`, `AGENTS.md` §Plan folder. The integration block in `AGENTS.md` / `CONVENTIONS.md` §Git contract. Which variant of `_agent/prompts/autonomous.md` Step 6 is kept (`git merge --ff-only` vs. `gh pr create` → CI → merge). |
+| 5 | **Multi-agent setup** — pick one of three: (1) single agent; (2) multi-agent, shared checkout; (3) multi-agent, separate worktrees / PR branches. The three options differ in LOCKS semantics, WORKLOG layout, and CURRENT_FOCUS handling — switching later is not free. | **Single agent.** Small projects shouldn't pay the coordination cost. | `_agent/ROLES.md` content. `AGENTS.md` §Multi-agent workflow and `CONVENTIONS.md` §Multi-Agent Rules pick one of three variants. Mode 2 turns LOCKS on as a filesystem mutex. Mode 3 sets LOCKS to advisory, adds `_agent/WORKLOG.md merge=union` to `.gitattributes`, gitignores `_agent/CURRENT_FOCUS.md`, and writes `_agent/IN_FLIGHT.md` as the committed cross-worktree dashboard. |
+| 6 | **Git contract** — Conventional Commits, `Rationale:` footer, signed commits, ADR-revision tags, `Co-Authored-By` trailer. | **Conventional Commits ON, `Rationale:` footer ON, signed commits ON, ADR-revision tags OFF, `Co-Authored-By` trailer OFF.** | `AGENTS.md` §Git contract and `CONVENTIONS.md` §Git Contract bullets. |
+| 7 | **Optional artefacts** — `GLOSSARY.md`, `domains/`, technology-ADR template. | **Defer all three.** Add when scale demands (terminology drift, >20 ADRs, technology decisions splitting from product). | Whether those files / directories are created. |
+| 8 | **Verify gate** — what command(s) decide a change is shippable. | *No default — project-specific.* | Whether `_agent/prompts/autonomous.md` is written. The skill **refuses** to write the autonomous prompt without a real verify gate. The Step 4 line of the prompt is filled with your command. |
+| 9 | **Existing-content conflicts** (existing repos only) — current commit format, branch policy, ADR style, status names the new layout must respect. | *No default — project-specific.* Skipped on fresh repos. | Merge behaviour during writes; commit-message notes calling out each compromise. |
+| 10 | **Domain-specific hard rules** to enforce from day one — e.g. vendor-naming restriction, regulated-evidence posture (attribution, retention, e-signatures), language mandate, mandatory user-story personas, separated audit streams. | **None from day one.** Add later when a concrete requirement appears; pre-emptive hard rules accumulate as cruft. | Additional sections in `CONVENTIONS.md` and additional bullets in `AGENTS.md` §Hard rules. |
+
+## 4. Output files
+
+After sign-off, the skill writes:
+
+| File | Source template | Notes |
+|------|-----------------|-------|
+| `CONVENTIONS.md` | `templates/CONVENTIONS.md` | Spec the other files reference. Written first. |
+| `AGENTS.md` | `templates/AGENTS.md` | Hard rules entry point. |
+| `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). |
+| `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. |
+| `_agent/WORKLOG.md` | `templates/_agent-WORKLOG.md` | Empty table header. |
+| `_agent/CURRENT_FOCUS.md` | `templates/_agent-CURRENT_FOCUS.md` | Live snapshot, initial state "none". |
+| `_agent/HANDOFF.md` | `templates/_agent-HANDOFF.md` | Fresh-agent entry point. |
+| `_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. |
+| `_agent/prompts/autonomous.md` | `templates/_agent-prompts-autonomous.md` | Only if Q8 confirmed a verify gate. |
+
+## 5. After scaffolding
+
+The repo is now ready for ADR-driven work. Typical first steps:
+
+1. **Author the first ADR.** Copy `adr/0000-template.md` to
+   `adr/0001-<slug>.md`. Fill in Context, Capability statement, User
+   stories, Acceptance criteria. Set status to `Proposed`.
+2. **Get it Accepted.** Update Approvals table, change status to
+   `Accepted`, regenerate `INDEX.md`.
+3. **Queue the work.** Create `plan/todo/0001-<slug>.md` naming the
+   owning ADR, scope, exit criteria. Lower-numbered files run first.
+4. **Implement.** Code against the ADR's numbered acceptance criteria.
+   Add tests that map back to those criteria.
+5. **Integrate.** Per the Q4b integration model: fast-forward to
+   `main` and push (direct-to-main), or open a PR, wait for CI green,
+   and merge (PR-based).
+6. **Ship.** Once on `main`:
+   `git mv plan/todo/0001-<slug>.md plan/done/<YYYY-MM-DD>-<slug>.md`,
+   amend the file with a "Shipped at HEAD `<sha>`" footer, advance the
+   ADR's `status:` from `Accepted` to `Implemented`, regenerate
+   `INDEX.md`, append a row to `_agent/WORKLOG.md`.
+
+## 5a. Lifecycle skills
+
+The manual workflow in §5 is exactly what the lifecycle skills
+automate. They all share three properties: they **read `CONVENTIONS.md`
+first** and honour the repo's recorded choices (ADR shape, status
+lifecycle, integration model, multi-agent mode); they **refuse on an
+un-bootstrapped repo** and point at `/bootstrap`; and they keep
+`INDEX.md` and the `_agent/` coordination files in sync as a side
+effect.
+
+| Skill | Replaces these manual steps |
+|-------|------------------------------|
+| `/new-adr` | §5 steps 1–2: pick number, choose shape, fill template, set `Proposed`, regen INDEX, wire domain README, supersede linkage. Offers to walk to `Accepted` and to create the plan item. |
+| `/new-plan` | §5 step 3: create `plan/todo/NNNN`, name owning ADR(s), scope, exit criteria, dependencies, queue position. |
+| `/ship-item` | §5 steps 5–6: verify gate → integrate (ff or PR per Q4b) → `git mv` todo→done with footer → ADR `Accepted`→`Implemented` → regen INDEX → WORKLOG → live snapshot. The most order-sensitive operation; let the skill do it. |
+| `/add-convention` | Assesses whether a convention is worth codifying (triages out one-offs, duplicates, churn-prone, vague), routes it to AGENTS.md / CONVENTIONS.md / GLOSSARY / an ADR, then writes it. |
+| `/audit` | Lints the repo against its own conventions and reports a punch list — numbering, INDEX sync, plan coverage, section completeness, status validity, cross-refs, language mandate, and **ADR-privacy leaks into user-visible code**. Offers to fix the mechanical issues. |
+| `/brainstorm` | Decomposes a problem into candidate ADRs + plan items with dependency edges and ordering. Proposes drafts only; writes nothing until approved, then hands off to `/new-adr` and `/new-plan`. |
+| `/agent-wave` | Orchestrates parallel worktree subagents over the queue. Asks wave width, budget (items/waves; hours as a soft cap), and supervision (checkpoint vs. continuous). Requires multi-agent mode; refuses mode 1. |
+
+### agent-wave: what it can and can't do
+
+In-session subagents are bounded by the session, not by wall-clock
+hours. `/agent-wave` therefore measures budget in **items and waves**,
+with hours as a *soft cap*. For a genuinely long-running, session-
+outliving fleet, schedule `_agent/prompts/autonomous.md` via
+`/schedule` (or use remote agents) instead — `/agent-wave` points you
+there rather than over-promising.
+
+It requires a multi-agent mode (Q5 mode 2 or 3) and works best in mode
+3 (separate worktrees), where each subagent gets an isolated checkout.
+Continuous-unsupervised runs are recommended only with PR-based
+integration, so CI gates each merge.
+
+## 6. Customising or extending
+
+The templates are deliberately small and self-contained. To customise:
+
+- **Edit a template.** Files in `skills/bootstrap/templates/` are read
+  verbatim by the `bootstrap` skill, then placeholders are filled from
+  the assessment answers. Change the template, the next bootstrap
+  reflects it.
+- **Add a new template.** Put it in `skills/bootstrap/templates/` and
+  reference it from `bootstrap/SKILL.md` §Step 5 (Output sequence).
+- **Tighten a skill's auto-trigger.** Edit the `description:`
+  frontmatter in that skill's `SKILL.md`. Skills match user requests
+  against this string — be specific about phrasings, be terse about
+  scope. With several skills in one plugin, watch for trigger collision
+  (e.g. "add a convention" vs. "add an ADR") and keep descriptions
+  distinct; the slash commands are the unambiguous entry point.
+- **Add a new lifecycle skill.** Create `skills/<name>/SKILL.md`. Follow
+  the shared pattern: a Step 0 that checks the repo is bootstrapped and
+  reads `CONVENTIONS.md`, then act in a way that honours the recorded
+  choices. Lifecycle skills act on the target repo's own files (e.g. its
+  `adr/0000-template.md`), so they need no templates of their own.
+- **Fork the plugin.** This repo is small enough to fork and host
+  internally if you want a private convention set.
+
+## 7. Re-running
+
+The skill is idempotent in spirit, but be careful: re-running on a
+repo that already has scaffolded files will trigger the "existing
+repo" path and ask Q9 about conflicts. Use it intentionally — to add
+the parts you skipped the first time, not to wipe and rebuild.
+
+## 8. Updating the plugin
+
+### As a recipient (someone who installed the plugin)
+
+When the plugin author pushes changes, refresh your installation:
+
+```
+/plugin marketplace update evolvehq
+/plugin install docflow@evolvehq
+```
+
+The first command pulls the latest marketplace listing (a `git fetch`
+behind the scenes against the marketplace repo). The second reinstalls
+the plugin at its now-current version. To pick up the changes in an
+*already-running* Claude Code session, run `/reload-plugins` instead
+of restarting.
+
+To check what's installed and the resolved version:
+
+```
+/plugin list
+```
+
+To remove the plugin entirely:
+
+```
+/plugin uninstall docflow@evolvehq
+```
+
+### As the author (you, maintaining this repo)
+
+1. Edit a skill body (`skills/<name>/SKILL.md`), the bootstrap templates
+   (`skills/bootstrap/templates/*.md`), or supporting docs.
+2. Bump the `version` field in `.claude-plugin/plugin.json` following
+   semver — patch for fixes, minor for new questions / templates,
+   major for breaking changes to the skill flow.
+3. Update this `USAGE.md` and `README.md` if behaviour changed.
+4. Commit with a Conventional Commit message
+   (`feat(skill): ...`, `fix(template): ...`, `docs: ...`).
+5. Push to `origin/main`. Recipients refresh per the section above.
+
+If you tag releases, use `git tag vX.Y.Z` matching `plugin.json`.
+Tags help recipients pin to a specific version via
+`/plugin install docflow@evolvehq@vX.Y.Z` (when supported by their
+Claude Code version).
+
+## 9. Troubleshooting
+
+- **Skill not appearing in the available-skills list.** Confirm the
+  plugin is installed (`/plugin list`) or `--plugin-dir` was passed.
+  Restart the Claude Code session.
+- **Slash command not found.** The bootstrap slash form is `/bootstrap`
+  (lowercase); lifecycle commands are `/new-adr`, `/new-plan`,
+  `/ship-item`, `/add-convention`, `/audit`, `/brainstorm`,
+  `/agent-wave`.
+- **Skill asks questions the project already answered.** That's by
+  design — the skill does not persist state between invocations.
+  Answer briefly; the second run is faster.
+- **Existing repo merge looks wrong.** Stop and surface it. The skill
+  is instructed to preserve existing content; if it overwrote
+  something, that's a bug — file an issue with the merge diff.

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@evolvehq/docflow",
+  "version": "0.4.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, and audit ADRs with lifecycle skills. Works with the pi coding agent and Claude Code.",
+  "keywords": [
+    "pi-package",
+    "adr",
+    "architecture-decision-records",
+    "documentation",
+    "claude-code"
+  ],
+  "license": "MIT",
+  "author": "Eugenio Minardi",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/EvolveHQ/docflow.git"
+  },
+  "homepage": "https://github.com/EvolveHQ/docflow",
+  "files": [
+    "skills/",
+    "README.md",
+    "USAGE.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "pi": {
+    "skills": ["./skills"]
+  }
+}

package/skills/add-convention/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: add-convention
+description: Assess and add a CONVENTION (a reusable rule, practice, or naming/process standard) to a documentation-led repo — decides FIRST whether it is worth codifying at all, then routes it to the right home (AGENTS.md hard rule, CONVENTIONS.md guidance, GLOSSARY term, or to /new-adr if it is really a one-off decision). Pushes back on premature or duplicate conventions. Use when the user says "add a convention", "make this a rule", "document this practice", "we should always X", or invokes /add-convention. NOT for recording a single architectural/product decision (use /new-adr) and NOT for queueing work (use /new-plan).
+---
+
+# add-convention
+
+Add a convention — but only after assessing whether it should exist and
+where it belongs. This skill is a gatekeeper and a router, not a
+stenographer.
+
+## Step 0 — Preconditions and context
+
+1. Confirm the repo is bootstrapped.
+2. Read `CONVENTIONS.md` and `AGENTS.md` in full so you can detect
+   overlap with existing rules and judge fit.
+
+## Step 1 — Assess: is this worth codifying?
+
+Apply triage. Recommend **against** adding when:
+- It is already covered (explicitly or implicitly) by an existing
+  convention — point to it instead of duplicating.
+- It is a one-off, not a recurring decision — codifying it adds noise.
+- It is likely to churn — premature rules become stale cruft.
+- It is too vague to be testable or actionable as written.
+
+Recommend **for** adding when it is a recurring decision whose ambiguity
+causes rework, it is stable, and it can be stated so an agent can follow
+it without further interpretation. State your recommendation and the
+reason before doing anything.
+
+## Step 2 — Route: where does it belong?
+
+Decide the home, and explain the choice:
+- **Hard rule agents must obey** → a bullet in `AGENTS.md` §Hard rules,
+  with the substance in `CONVENTIONS.md`. Use for non-negotiable
+  constraints.
+- **Authoring / process guidance** → a section in `CONVENTIONS.md`.
+  Use for "how we do things" that informs but doesn't gate.
+- **Shared term / definition** → `GLOSSARY.md` (if the repo has one).
+- **It is actually a decision, not a convention** (an architectural,
+  product, or technology choice with alternatives and consequences) →
+  this is an ADR. Stop and offer the **new-adr** skill; do not bury a
+  decision in
+  CONVENTIONS.
+
+If a convention is a triage/process rule (e.g. how incoming work is
+triaged), prefer `CONVENTIONS.md` with a hard-rule bullet in AGENTS.md
+only for the parts that are non-negotiable.
+
+## Step 3 — Draft and confirm
+
+Draft the exact wording for its home file. Keep it tight, testable, and
+in the repo's language. Show the diff. Confirm before writing.
+
+## Step 4 — Write and commit
+
+Apply the edit(s). If a convention rises to a hard rule, ensure
+`AGENTS.md` and `CONVENTIONS.md` stay consistent. Conventional Commit
+(`docs: ...`); no ADR touched means no `Rationale:` footer is required,
+but add one if the repo's contract asks for it on convention changes.