@refactco/refact-os 1.5.0 → 1.5.2

package/CHANGELOG.md

@@ -2,7 +2,18 @@
 
 Notable changes to the refact-os standard and scaffolder.
 
-**Staying current:** a consumer repo updates with `npm run refact:update` (or `npx github:refactco/refact-os init`). That refreshes the package-managed `agent/` payload, **prunes** skills this package has removed or renamed (safe — only skills the package previously shipped, never your own), regenerates `.cursor/` + `.claude/`, and flags `agent/AGENTS.md` drift for a manual merge. The version it last applied is recorded in `.refact-os.json` under `_scaffold.version`, and `init` prints the `old → new` transition so you can scan the entries below for anything needing manual action. Run `npm run refact:validate` afterward.
+**Staying current:** a consumer repo updates with `npm run refact:update` (or `npx @refactco/refact-os init`). That refreshes the package-managed `agent/` payload, **prunes** skills this package has removed or renamed (safe — only skills the package previously shipped, never your own), regenerates `.cursor/` + `.claude/`, and flags `agent/AGENTS.md` drift for a manual merge. The version it last applied is recorded in `.refact-os.json` under `_scaffold.version`, and `init` prints the `old → new` transition so you can scan the entries below for anything needing manual action. Run `npm run refact:validate` afterward.
+
+## 1.5.2
+
+### Added
+- **npm auto-publish on tags.** A GitHub Actions workflow (`.github/workflows/publish.yml`) publishes to npm (with provenance) when a `vX.Y.Z` tag is pushed, after checking the tag matches `package.json`. Requires the repo secret `NPM_TOKEN` (an npm "Automation" token for the `refactco` org). Release flow: bump `package.json` + `CHANGELOG` → commit → `git tag vX.Y.Z` → `git push origin vX.Y.Z`.
+- **Restored the `--adopt` flag** (it was lost before reaching `main`). `refact-os init --adopt` forces gentle / agent-layer-only mode on any repo — to re-adopt one an older `init` over-scaffolded, or update an existing repo without re-imposing the `docs/` seed, `apps/`, or WordPress dirs. It's the opposite of `--seed` (force full scaffold); `--adopt` wins if both are passed.
+
+## 1.5.1
+
+### Changed
+- **Consumers now install from npm.** Scaffolded repos get `@refactco/refact-os` (`^1.5.0`) as their devDependency instead of the `github:refactco/refact-os` specifier. A repo scaffolded before the publish has its legacy GitHub devDependency **migrated** to the npm package on the next `init`/update (so it doesn't end up with two packages providing the same `refact-os` bin). README, the `adopt` / `update-package` skills, and the bootstrap commands now use `npx @refactco/refact-os …`.
 
 ## 1.5.0
 

package/README.md

@@ -8,27 +8,27 @@ You only ever edit one canonical folder, `agent/`. The tool generates the tool-s
 
 ## Get started
 
-> refact-os is **not** on the public npm registry. You install it straight from GitHub.
+> refact-os is published on npm as **`@refactco/refact-os`** (scoped, public).
 
 Create a project and scaffold it:
 
 ```bash
 mkdir my-project && cd my-project
-npx github:refactco/refact-os init
+npx @refactco/refact-os init
 ```
 
 Choose the project type up front (skips the prompt):
 
 ```bash
-npx github:refactco/refact-os init --type nextjs           # or: wordpress, blank
-npx github:refactco/refact-os init --type wordpress,nextjs  # hybrid: apply both overlays
+npx @refactco/refact-os init --type nextjs           # or: wordpress, blank
+npx @refactco/refact-os init --type wordpress,nextjs  # hybrid: apply both overlays
 ```
 
 `init` adapts to the repo. An **empty** repo gets the full scaffold (substrate seed + skills + overlays). An **existing** repo gets **only the agent layer** (skills, including `adopt`) so it never imposes folders over your structure — then `/adopt` plans the transition. Force the full scaffold on a non-empty repo with `--seed`. See the **Bringing an existing repo** note under [Commands](#commands) below.
 
 ## Run it inside your project (npm)
 
-After `init`, your `package.json` gets a `refact-os` dev-dependency and ready-made scripts. From then on you use plain **npm** — no more typing the long `npx github:…`:
+After `init`, your `package.json` gets a `@refactco/refact-os` dev-dependency and ready-made scripts. From then on you use plain **npm** — no more typing the full `npx @refactco/refact-os …`:
 
 ```jsonc
 "scripts": {
@@ -80,13 +80,13 @@ refact-os validate  [--target <dir>]                     # check structure + ski
 refact-os migrate   [--target <dir>]                     # move an older layout into the current one
 ```
 
-- **`init`** — scaffold a project. An **empty** repo gets the thin seed + base `agent/` skills + type overlays + adapters; an **existing** repo gets only the agent layer (then run `/adopt`). `--seed` forces the full scaffold on a non-empty repo; `--no-force` never overwrites existing files.
+- **`init`** — scaffold a project. An **empty** repo gets the thin seed + base `agent/` skills + type overlays + adapters; an **existing** repo gets only the agent layer (then run `/adopt`). `--seed` forces the full scaffold on a non-empty repo; `--adopt` forces agent-layer-only on any repo (re-adopt one an older `init` over-scaffolded, or update an existing repo without imposing structure); `--no-force` never overwrites existing files.
 - **`sync`** — after editing `agent/`, regenerate `.cursor/` and `.claude/`. Never edit those by hand.
 - **`validate`** — checks the required folders/files exist, every skill declares its resolver frontmatter (the fields the agent routes on — `name`, `pattern`, `description`, `when_to_use`, `when_not_to_use`, `next_skills`), the generated skill index isn't stale, and the adapters are in sync.
 - **`migrate`** — moves an old-layout repo into the current one and tops up the `package.json` scripts. Safe: it never overwrites an existing file, and merges old chat folders into the new location.
 - **`sync company`** — pulls Refact's shared company context (brand, team, pitch) from `refactco/refact-operation` into `docs/context/company/`. Re-syncable, so it never drifts permanently. Source + SHA are recorded in `.refact-os.json`.
 
-**Bringing an existing repo to the standard:** just run `npx github:refactco/refact-os init`. It detects that the repo isn't empty and adds **only the agent layer** — the skills (including `adopt`), root pointers, config, and adapters — *without* dropping a `docs/` seed or `apps/` over your existing structure, and without applying type overlays. Then run the **`adopt`** skill (`/adopt`): it surveys the repo, writes a phased transition plan to `docs/task/open/`, and reconciles your structure with the standard — asking before anything ambiguous — until `refact-os validate` is green. (Pass `--seed` if you actually want the full greenfield scaffold on a non-empty repo.)
+**Bringing an existing repo to the standard:** just run `npx @refactco/refact-os init`. It detects that the repo isn't empty and adds **only the agent layer** — the skills (including `adopt`), root pointers, config, and adapters — *without* dropping a `docs/` seed or `apps/` over your existing structure, and without applying type overlays. Then run the **`adopt`** skill (`/adopt`): it surveys the repo, writes a phased transition plan to `docs/task/open/`, and reconciles your structure with the standard — asking before anything ambiguous — until `refact-os validate` is green. (Pass `--seed` if you actually want the full greenfield scaffold on a non-empty repo.)
 
 ## What gets generated
 

package/bin/refact-os.js

@@ -26,7 +26,7 @@ function isAllowedTarget(target) {
 }
 
 function parseArgs(argv) {
-  const args = { command: "init", sub: undefined, target: process.cwd(), projectType: undefined, overlays: [], force: true, seed: false };
+  const args = { command: "init", sub: undefined, target: process.cwd(), projectType: undefined, overlays: [], force: true, seed: false, adopt: false };
   const raw = [...argv];
   if (raw[0] && !raw[0].startsWith("-")) args.command = raw.shift();
   if (raw[0] && !raw[0].startsWith("-")) args.sub = raw.shift();
@@ -37,6 +37,7 @@ function parseArgs(argv) {
     else if (token === "--target") args.target = raw.shift();
     else if (token === "--no-force") args.force = false;
     else if (token === "--seed") args.seed = true;
+    else if (token === "--adopt") args.adopt = true;
   }
   return args;
 }
@@ -47,6 +48,7 @@ async function runScaffold(args, { force }) {
     overlays: args.overlays,
     force,
     seed: args.seed,
+    adopt: args.adopt,
     interactive: process.stdin.isTTY,
   });
   console.log(`Scaffolded ${result.filesWritten} files in ${result.target}`);

package/lib/project-utils.js

@@ -104,20 +104,27 @@ const SCAFFOLD_SCRIPTS = {
   "refact:update": "refact-os init",
 };
 
-// refact-os is distributed from GitHub (not the npm registry). Adding it as a
-// devDependency is what lets the `refact:*` npm scripts above call the bare
-// `refact-os` binary (instead of fetching it via npx on every run).
+// refact-os is published to npm as @refactco/refact-os. Adding it as a
+// devDependency is what lets the `refact:*` npm scripts above call the
+// `refact-os` binary (which the package provides) instead of fetching it via npx.
 const SCAFFOLD_DEV_DEPENDENCIES = {
-  "refact-os": "github:refactco/refact-os",
+  "@refactco/refact-os": "^1.5.0",
 };
 
 // Add scaffold devDependencies that aren't already declared (in either
 // dependencies or devDependencies). Non-destructive; mutates `data` and
-// returns the names added.
+// returns the names added. Also migrates the legacy GitHub-specifier
+// devDependency (`refact-os: github:refactco/refact-os`) to the npm package, so
+// a repo scaffolded before the npm publish doesn't end up with both (two
+// packages providing the same `refact-os` bin).
 function _ensureDevDependencies(data) {
   const depsAdded = [];
   const deps = data.dependencies || {};
   const devDeps = data.devDependencies || {};
+  if (typeof devDeps["refact-os"] === "string" && /github:refactco\/refact-os/i.test(devDeps["refact-os"])) {
+    delete devDeps["refact-os"];
+    data.devDependencies = devDeps;
+  }
   for (const [name, spec] of Object.entries(SCAFFOLD_DEV_DEPENDENCIES)) {
     if (name in deps || name in devDeps) continue;
     devDeps[name] = spec;

package/lib/scaffold.js

@@ -216,13 +216,17 @@ async function scaffoldProject(targetDir, options = {}) {
   }
 
   // Brownfield vs greenfield. Decided once (at first init) and recorded, so a
-  // later `init`/update never suddenly imposes structure on an adopted repo.
-  // `--seed` (options.seed) forces the full scaffold and graduates a brownfield
-  // repo to it. On a brownfield repo we add ONLY the agent layer (base skills,
-  // root pointers, config, adapters) and defer the docs/ seed, apps/, and type
-  // overlays to the `adopt` skill, which reconciles them with existing dirs.
+  // later `init`/update never suddenly imposes structure on an adopted repo. On a
+  // brownfield repo we add ONLY the agent layer (base skills, root pointers,
+  // config, adapters) and defer the docs/ seed, apps/, and type overlays to the
+  // `adopt` skill. The two flags are opposites and override detection/recorded
+  // state: `--adopt` (options.adopt) forces gentle mode (re-adopt a repo an older
+  // init over-scaffolded, or update an existing one without imposing structure);
+  // `--seed` (options.seed) forces the full scaffold. `--adopt` wins if both pass.
   let brownfield;
-  if (options.seed) {
+  if (options.adopt) {
+    brownfield = true;
+  } else if (options.seed) {
     brownfield = false;
   } else if (!hadConfig) {
     brownfield = repoHasOwnContent(resolvedTarget);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@refactco/refact-os",
-  "version": "1.5.0",
+  "version": "1.5.2",
   "description": "Installable scaffolder for the agent-first repo standard: minimum-seed substrate + canonical agent/ skill catalog with generated tool adapters",
   "keywords": [
     "agent",

package/templates/base/agent/skills/adopt/SKILL.md

@@ -3,8 +3,8 @@ name: adopt
 pattern: procedure
 requires_approval: false
 description: Produce a PLAN for bringing an existing, non-conformant repo up to the agent-first standard. Surveys the repo and outputs a phased transition plan as its final response — it does NOT change anything.
-when_to_use: The user wants to understand what it would take to bring an existing repo to the standard — "adopt this repo", "make this repo agent-first", "what's the plan to conform this repo", "plan the migration". Run after `npx github:refactco/refact-os init --no-force` has laid the mechanical seed.
-when_not_to_use: For a brand-new empty project (use `npx github:refactco/refact-os init`). When the user explicitly asks you to EXECUTE a plan that already exists (this skill only plans — execution is a separate, explicit step the user approves).
+when_to_use: The user wants to understand what it would take to bring an existing repo to the standard — "adopt this repo", "make this repo agent-first", "what's the plan to conform this repo", "plan the migration". Run after `npx @refactco/refact-os init --no-force` has laid the mechanical seed.
+when_not_to_use: For a brand-new empty project (use `npx @refactco/refact-os init`). When the user explicitly asks you to EXECUTE a plan that already exists (this skill only plans — execution is a separate, explicit step the user approves).
 inputs:
   - the target repository (surveyed read-only, not fully read)
   - the standard at docs/agent-first-repo-best-practices.md (or the refact-os package copy)
@@ -29,9 +29,9 @@ Produce a **plan** for bringing an existing repo to the agent-first standard. Th
 ## Steps
 
 1. **Survey** the repo breadth-first (sub-agents per area). For each area note: what's there, which of the six roles it maps to (Evidence/Knowledge/Task/Output/Software/Agent), and anything load-bearing (scripts, automation, hardcoded paths).
-2. **Read the gaps:** run `npm run refact:validate` (read-only) and fold its findings in. If the script/binary isn't wired up yet, fall back to `npx github:refactco/refact-os validate` (read-only, touches nothing in the repo) — don't run `npm install` here, since this skill changes nothing.
+2. **Read the gaps:** run `npm run refact:validate` (read-only) and fold its findings in. If the script/binary isn't wired up yet, fall back to `npx @refactco/refact-os validate` (read-only, touches nothing in the repo) — don't run `npm install` here, since this skill changes nothing.
 3. **Write the plan** and present it as your final response. Structure it as ordered **phases**, each a small reviewable unit, with: the proposed moves/renames/**deletions**, the references that would need updating, and any open questions. Typical items:
-   - Missing seed → `npx github:refactco/refact-os init --no-force` (additive).
+   - Missing seed → `npx @refactco/refact-os init --no-force` (additive).
    - Duplicate canonical map (`INDEX.md` vs `docs/index.md`) → which is canonical; merge the other.
    - Duplicate contract (root `AGENTS.md` vs `agent/AGENTS.md`) → consolidate into `agent/AGENTS.md`, leave a thin root pointer.
    - Variant dirs (`docs/tasks` vs `docs/task`) → consolidate onto the standard name.

package/templates/base/agent/skills/update-package/SKILL.md

@@ -14,27 +14,27 @@ Use this when the user asks to update / bump / refresh / reinstall `refact-os` i
 
 ## Source
 
-`refact-os` installs from GitHub (`github:refactco/refact-os`) — it is **not** on the public npm registry, so `npm install refact-os@latest` will fail. Use the GitHub specifier unless the user explicitly names a local checkout (e.g. `../refact-os` for development).
+`refact-os` is published to npm as **`@refactco/refact-os`** (scoped public). Install it from npm unless the user explicitly names a local checkout (e.g. `../refact-os` for development). The binary it provides is still `refact-os`, so the `refact:*` npm scripts are unchanged.
 
 ## Workflow
 
 1. **Detect the package manager** from lockfiles: `pnpm-lock.yaml` → pnpm; `yarn.lock` → yarn; `package-lock.json` or none → npm.
 2. **Bump the package** (show the command first; let the user override the source):
-   - npm: `npm install github:refactco/refact-os`
-   - pnpm: `pnpm add github:refactco/refact-os`
-   - yarn: `yarn add github:refactco/refact-os`
+   - npm: `npm install -D @refactco/refact-os@latest`
+   - pnpm: `pnpm add -D @refactco/refact-os@latest`
+   - yarn: `yarn add -D @refactco/refact-os@latest`
 
-   Installing as a devDependency does **not** auto-scaffold (postinstall skips when refact-os is a project dependency), so apply the refresh explicitly in the next step.
+   Installing does **not** scaffold anything (there is no postinstall), so apply the refresh explicitly in the next step.
 3. **Refresh the payload:** `npx refact-os init` (or `npm run refact:update`). It is idempotent and:
    - force-copies package-managed files (the `agent/` skills, hooks, scripts, root pointers); your own files are preserved (`agent/AGENTS.md`, `README.md`, everything under `docs/`).
    - **prunes** skills the package removed or renamed since your last update (tracked via `_scaffold.shippedSkills` in `.refact-os.json`); skills you authored are never pruned.
    - regenerates `.cursor/` and `.claude/` from `agent/`.
    - prints the version transition (`old → new`) and any pruned skills.
 4. **Read the output** and surface to the user:
-   - the version transition — point them at `node_modules/refact-os/CHANGELOG.md` for what changed and whether anything needs manual action.
+   - the version transition — point them at `node_modules/@refactco/refact-os/CHANGELOG.md` for what changed and whether anything needs manual action.
    - any pruned skills.
    - the **`agent/AGENTS.md` drift warning** if it fired (the upstream contract template changed; your copy is never overwritten).
-5. **agent/AGENTS.md drift follow-up** (only if the warning fired): read the installed template at `node_modules/refact-os/templates/base/agent/AGENTS.md` and the project's `agent/AGENTS.md`, diff them, and surface the meaningful additions as *suggestions*. Wait for the user's go-ahead before editing; preserve project-specific values (stack, hosting, URLs, SSH) — never replace them with template placeholders.
+5. **agent/AGENTS.md drift follow-up** (only if the warning fired): read the installed template at `node_modules/@refactco/refact-os/templates/base/agent/AGENTS.md` and the project's `agent/AGENTS.md`, diff them, and surface the meaningful additions as *suggestions*. Wait for the user's go-ahead before editing; preserve project-specific values (stack, hosting, URLs, SSH) — never replace them with template placeholders.
 6. **Validate:** run `npm run refact:validate` and report the result. If it surfaces structural gaps (common when the standard adds folders/roles), suggest `/adopt` to reconcile them.
 7. **Report:** source used, installed version/SHA, version transition, files changed, pruned skills, whether the AGENTS.md drift fired, and follow-up steps (review the diff, run tests, commit).
 
@@ -45,7 +45,7 @@ If the user explicitly wants to install from a local clone (developing refact-os
 ## Guardrails
 
 - Prefer package-manager commands over hand-editing `package.json`.
-- Never reach for the npm registry as a fallback — the package isn't published there.
+- Prefer the published npm package (`@refactco/refact-os`); a local checkout (`../refact-os`) is opt-in for development only.
 - Never run destructive git commands.
 - If install fails, capture the exact error and suggest the smallest fix — don't silently retry with a different source.
 - The refresh prunes only skills the package previously shipped. If the user customized a package skill in place (discouraged — fork it with a project prefix instead), warn them it will be overwritten or pruned.