@baldurpan/create-ai-workflow 0.3.0 → 0.4.0

package/README.md

@@ -39,7 +39,7 @@ starting point — nothing has to be looked up first.
 | `/feature-status` | read-only. Reconciles the ledger against the repo, then names **exactly one** next action |
 | `/feature-close` | retires a feature: a `history.md` row, a `git mv` into `archive/`, and a reviewed reference sweep |
 | `/orchestrate` | one ad-hoc, commit-sized change through the same gates — no entry, no ledger |
-| `/onboard` | fills in your own stubs, running each verification command before writing it down |
+| `/onboard` | fills in your own stubs, adopting what the repo already documented and running each verification command before writing it down |
 
 ## What makes it different
 
@@ -77,6 +77,12 @@ CLAUDE.md   a single @AGENTS.md line, and only when the file does not exist
 
 Nothing is committed. Review the diff yourself.
 
+**Onto a repository that already documents itself**, the installer only appends — your existing
+`AGENTS.md` prose is left exactly where it is. `/onboard` reconciles the two afterwards: it classifies
+each existing claim into `stack.md`, `verify.md` or `executors.md`, asks wherever a destination is
+unclear or the old text contradicts the installed workflow, and prunes the source only once the
+replacement is written and shown.
+
 ### The ownership boundary is a data structure, not a rule
 
 `context/.state/manifest.json` lists every tool-owned file with its hash. `update` walks that manifest —

package/dist/commands/install.js

@@ -71,6 +71,10 @@ export function install(root) {
     info(bold('Next'));
     info(`  1. Review the diff. ${dim('Nothing was committed — that is deliberate.')}`);
     info(`  2. Run ${cyan('/onboard')} in your agent to fill in verify.md, executors.md and stack.md.`);
+    if (before !== null) {
+        info(dim('     AGENTS.md already said things of its own — /onboard folds those into the three files\n' +
+            '     above and prunes what it moved, asking before anything is deleted.'));
+    }
     info(`  3. ${cyan('/roadmap "some idea"')} starts the loop.`);
     return 0;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@baldurpan/create-ai-workflow",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Overlay a tiered planning workflow — roadmap, plans, phase ledgers, verification gates — onto an existing repository, for coding agents.",
   "keywords": [
     "ai",

package/templates/blocks/agents-block.md

@@ -12,7 +12,7 @@ the standing rules, and every command cites it rather than restating it.
 | `/feature-status` | read-only "where do things stand". **Never a prerequisite** for anything |
 | `/feature-close` | retires a finished or abandoned feature into `context/archive/` |
 | `/orchestrate` | one ad-hoc, gated, commit-sized change — no roadmap entry, no ledger |
-| `/onboard` | fills in this project's own stubs: `verify.md`, `executors.md`, `stack.md` |
+| `/onboard` | fills in this project's own stubs — `verify.md`, `executors.md`, `stack.md` — adopting what an existing `AGENTS.md` already said |
 
 | Read | For |
 |---|---|

package/templates/context/workflow.md

@@ -35,7 +35,7 @@ never a prerequisite for anything.
 | `/feature-status` | nothing — read-only | — |
 | `/feature-close` | Tier 2 → retired | `history.md`, `archive/`, the reference sweep |
 | `/orchestrate` | one ad-hoc gated change | the code, and `findings.md` |
-| `/onboard` | the project-owned stubs | `verify.md`, `executors.md`, `stack.md` |
+| `/onboard` | the project-owned stubs | `verify.md`, `executors.md`, `stack.md`, and the pruning of what they replace |
 
 ## One source of truth per fact
 

package/templates/skills/onboard/SKILL.md

@@ -1,12 +1,13 @@
 ---
 name: onboard
-description: "Fill in this project's own workflow stubs — context/verify.md, context/executors.md and context/stack.md — by asking, and by running each candidate verification command and keeping only the ones that pass. Explicit invocation only — run this when the user types /onboard. Do NOT match on 'set up the project', 'get started', or general setup requests."
+description: "Fill in this project's own workflow stubs — context/verify.md, context/executors.md and context/stack.md — by adopting what the repository already documented, asking wherever a claim's destination is unclear, and running each candidate verification command so only the ones that pass are written down. Explicit invocation only — run this when the user types /onboard. Do NOT match on 'set up the project', 'get started', or general setup requests."
 ---
 
 # /onboard
 
-Fills the project-owned stubs the installer deliberately left empty. **Re-runnable** — run it again after
-the stack changes, and it re-proposes against what is there now.
+Fills the project-owned stubs the installer deliberately left empty, and folds whatever the repository
+already documented into them. **Re-runnable** — run it again after the stack changes, and it re-proposes
+against what is there now.
 
 **Asking is not guessing.** The installer could have detected a test command and written it in; that is
 exactly how a file ends up naming a command that has never run. This command asks, and where it can, it
@@ -21,10 +22,52 @@ Read [`context/workflow.md`](../../../context/workflow.md) for the tier model.
 | [`context/verify.md`](../../../context/verify.md) | the real Lint / Typecheck / Build / Test commands — **only ones that exited 0** |
 | [`context/executors.md`](../../../context/executors.md) | how this project dispatches a coder and a reviewer |
 | [`context/stack.md`](../../../context/stack.md) | runtime, layout, conventions |
+| [`AGENTS.md`](../../../AGENTS.md) | pruned, on confirmation, of what moved into those three. The region between the `ai-workflow` markers is never touched |
 
 Show every proposed edit before writing it, and **do not commit.** The user reviews and commits.
 
-## Step 1 — Coder dispatch
+## Step 1 — Adopt what the repository already says
+
+The installer appends its block to `AGENTS.md` and leaves the rest of that file alone, so a repository that
+documented itself before the overlay arrived now states some of the same things twice, in two places, with
+no rule about which wins. Resolving that is this step, and it runs first because what turns up here is the
+raw material for every step below.
+
+**Read, in this order:** everything in `AGENTS.md` *outside* the `ai-workflow` markers, then `CLAUDE.md`
+apart from its import line. If the repository carries other agent-instruction files — a nested `AGENTS.md`
+under a subdirectory, a directory of per-host instruction files — **list them and stop there.** Say they
+exist and that this command left them alone. A nested file usually scopes to its own subtree, and moving it
+up is a decision rather than a cleanup.
+
+Break what you read into claims — a paragraph, a table row, a bullet — and propose a destination for each:
+
+| A claim about | Goes to |
+|---|---|
+| what the project is, its layout, its conventions | `context/stack.md` |
+| a lint, typecheck, build or test command | a **candidate** for `context/verify.md` — Step 5 still has to run it |
+| how a coder or a reviewer is dispatched | `context/executors.md` |
+| a rule the bundled standards already state | nowhere — the standards own it. Ask before dropping |
+| planning or review process this workflow now owns | nowhere — superseded. Ask before dropping |
+| anything else — ownership, contacts, external links | stays in `AGENTS.md`, outside the block |
+
+**Show the whole table before moving anything**, one row per claim, and let the user correct any
+destination. Two kinds of row are never decided alone:
+
+- **Unsure** — a claim you cannot place, or that fits two files equally well. Ask. Do not quietly pick the
+  likelier one: a misfiled convention is a rule nobody reads again.
+- **Contradicts** — the existing prose and the installed workflow give different answers to the same
+  question. Where project-local skills live, what the review process is, which file is authoritative.
+  **Quote both and ask which stands.** Never resolve one silently in either direction — the older text is
+  often right about this project and wrong only about the overlay.
+
+An adopted claim is an *input* to the steps below, not a substitute for them. A command lifted out of the
+old file is a candidate like any other and still has to run.
+
+**Nothing is deleted here.** Pruning is Step 7, after the destination files exist.
+
+On a re-run, a claim its destination file already states is already adopted. Say so in a line and move on.
+
+## Step 2 — Coder dispatch
 
 Ask whether implementation runs **in-host** or is **offloaded** to an external coder CLI.
 
@@ -44,9 +87,9 @@ on that being true, and it is true of some executors and not others.
 4. If it comes back empty, guessed, or refused, record that **this executor needs content inline** — the
    one case where a brief carries file contents instead of paths.
 
-Never write down an invocation you have not run. This is the same rule as Step 4, for the same reason.
+Never write down an invocation you have not run. This is the same rule as Step 5, for the same reason.
 
-## Step 2 — Reviewer dispatch
+## Step 3 — Reviewer dispatch
 
 Ask how Gate 2 should get a review:
 
@@ -64,7 +107,7 @@ winner: it differs per host and changes underneath you. What ships is the contra
 Whatever is chosen, that contract stands: a review happens, every blocking finding carries a `P0`–`P3`
 severity, and a `FAIL` writes a finding before the loopback.
 
-## Step 3 — Standards source
+## Step 4 — Standards source
 
 `context/standards/` ships with a bundled default. Ask whether that is right for this project.
 
@@ -75,48 +118,73 @@ severity, and a `FAIL` writes a finding before the loopback.
   becomes project-owned from that point.
 
 Say plainly what the default is and that a wrong set is not inert — agents load from that README's
-conditional table unprompted, on every task.
+conditional table unprompted, on every task. If Step 1 turned up house rules that the bundled set already
+covers, this is the moment that matters: keeping both means the project has two answers.
 
-## Step 4 — Verification commands
+## Step 5 — Verification commands
 
 **This is the most valuable step in this command.** Do it properly.
 
-1. **Propose candidates.** Read `package.json` scripts, or the stack's equivalent — `Makefile`,
-   `composer.json`, `pyproject.toml`, `Cargo.toml`, the CI workflow. The CI config is the best source
-   available: it lists commands that demonstrably run in a clean checkout.
+1. **Propose candidates.** Take the command claims Step 1 adopted, then read `package.json` scripts, or the
+   stack's equivalent — `Makefile`, `composer.json`, `pyproject.toml`, `Cargo.toml`, the CI workflow. The
+   CI config is the best source available: it lists commands that demonstrably run in a clean checkout. A
+   command the old file named and CI does not is worth asking about — one of the two is stale.
 2. **Show the candidates and ask** which belong in Lint, Typecheck, Build and Test, and whether anything is
    missing. Ask about prerequisites too — a package manager version, an install step, a service that must
    be up.
 3. **Run each one.** Actually run it, from the repo root.
 4. **Write only the commands that exited 0.** For each one that failed, show the output and ask: fix it,
-   replace it, or leave that section empty. **Never write a command that has not passed.** An empty section
-   is skipped by Gate 1 and says so; a wrong command fails a gate on every task until someone notices.
+   replace it, or leave that section empty. **Never write a command that has not passed** — an inherited
+   one least of all, since it is the likeliest to have rotted. An empty section is skipped by Gate 1 and
+   says so; a wrong command fails a gate on every task until someone notices.
 5. Put anything that needs Docker, a cloud account or a deploy target under **Not run by Gate 1**, so
    nobody promotes it into a gate section by mistake.
 
 Explain what you are doing: this turns `verify.md` from someone's guess into something verified at install
 time, which is the one moment it is cheap to catch.
 
-## Step 5 — Stack
+## Step 6 — Stack
 
-A few questions, then write `context/stack.md`:
+Start from what Step 1 routed here, show it back as a draft, and ask only for the gaps:
 
 - What does this project do, in a paragraph — and anything about its history that explains its shape.
 - Runtime, package manager, database, storage, hosting.
 - The directories that matter, one line each.
 - **The conventions that would not be guessed** — what breaks in this runtime, what is deliberately kept
   separate, where local secrets live, what must never be run against production. This section is the one
-  that earns its keep; the rest is discoverable.
+  that earns its keep; the rest is discoverable. Inherited prose is usually strongest here and weakest at
+  describing layout, which drifts.
 
 Point out that anything else added under `context/` should be indexed in `stack.md`, not in
 `context/README.md`, which is tool-owned and replaced on update.
 
+## Step 7 — Prune the sources
+
+Only now, with the three stubs written, remove from `AGENTS.md` and `CLAUDE.md` what has landed elsewhere.
+Duplication left standing is the failure this step exists to prevent: two statements of one fact drift, and
+the stale copy is indistinguishable from the live one.
+
+- **Show the removal as a diff and ask before applying it.** Whole sections at a time, not scattered lines.
+- **Remove only what you can point at.** For each deletion name the file and section that now holds it. A
+  claim you could not place stays exactly where it is — an unpruned file is a smaller problem than a lost
+  rule.
+- **Never touch the region between the `ai-workflow` markers.** It is tool-owned and replaced on update, so
+  an edit there is an edit lost, and nothing migrates into it.
+- What should be left is what only `AGENTS.md` can say: the repository's own front matter, and the block's
+  pointer into `context/`.
+
+Keeping the original prose in place is a valid answer. If the user chooses it, write one line in
+`context/stack.md` saying which file is authoritative, so the next reader is not left to guess.
+
 ## Rules
 
+- **Copy before cut.** Nothing leaves `AGENTS.md` until the file that replaces it is written and shown.
 - **Never write a credential.** Write `$SENTRY_DSN`-style placeholders and name where the real value lives
-  — this command collects shell commands, which is the most likely place a token appears inline. See the
-  standing rule in [`context/workflow.md`](../../../context/workflow.md).
+  — this command collects shell commands, which is the most likely place a token appears inline. Inherited
+  prose gets the same read before it moves. See the standing rule in
+  [`context/workflow.md`](../../../context/workflow.md).
 - **Never write a command you have not run.**
+- **Never delete a claim you could not place.**
 - **Never touch a tool-owned file.** `README.md`, `workflow.md`, `plan-template*.md` and `roles/` are
   replaced on the next update; an edit there is an edit lost.
 - **Do not commit.**