@produck/agent-toolkit 0.3.3 → 0.4.0

package/README.md

@@ -2,6 +2,40 @@
 
 Central CLI toolkit for organization-level AI execution workflows.
 
+## First-time bootstrap (downstream repositories)
+
+For a new or existing downstream repository that has not yet applied the
+organization baseline, run:
+
+```
+npm create @produck/agent-toolkit@latest
+```
+
+This command installs `@produck/create-agent-toolkit` and runs
+`enforce-node-baseline` in the current directory. No prior installation is
+required — npm handles the download automatically.
+
+What it does (in order):
+
+1. Syncs organization AI instruction files into `.github/instructions/produck/`
+2. Runs preflight to verify required files and directories
+3. Deploys the pinned `produck:coverage` script and `c8` devDependency
+4. Deploys `.husky/pre-commit` and `.husky/commit-msg`, and pins `c8`, `husky`,
+   `lerna`, `@produck/agent-toolkit` in root `devDependencies`
+
+After running, add the persistent enforcement entry to the repository
+`package.json`:
+
+```json
+"produck:baseline": "npm exec --package=@produck/agent-toolkit@latest -- agent-toolkit enforce-node-baseline --cwd ."
+```
+
+Then future enforcement runs via:
+
+```
+npm run produck:baseline
+```
+
 ## Commands
 
 - agent-toolkit enforce-node-baseline
@@ -27,24 +61,54 @@ Equivalent explicit form:
 npm exec -- agent-toolkit enforce-node-baseline --cwd .
 ```
 
-Run preflight checks:
+`enforce-node-baseline` runs four steps in fixed order and stops at the first
+failure:
+
+1. `sync-instructions` — distribute organization AI instruction files into
+   `.github/instructions/produck/`
+2. `preflight` — verify required files and directories exist
+3. `sync-coverage-script` — deploy pinned `produck:coverage` script and `c8`
+   devDependency into each workspace package
+4. `sync-husky-hooks` — deploy `.husky/pre-commit` and `.husky/commit-msg`,
+   and pin `c8`, `husky`, `lerna`, `@produck/agent-toolkit` in root
+   `devDependencies`
 
+Add to downstream repository root `package.json` for one-command enforcement:
+
+```json
+"produck:baseline": "npm exec --package=@produck/agent-toolkit@latest -- agent-toolkit enforce-node-baseline --cwd ."
 ```
-npm exec -- agent-toolkit preflight --cwd . --require package.json --ensure-dir logs
+
+Then run:
+
+```
+npm run produck:baseline
 ```
 
-Run one-shot mandatory baseline steps for downstream monorepo (1 -> 2 -> 3):
+Dry-run to preview changes without writing files:
 
 ```
-npm exec -- agent-toolkit enforce-node-baseline --cwd .
+npm exec -- agent-toolkit enforce-node-baseline --cwd . --dry-run
 ```
 
-Validate monorepo root workspace package.json baseline:
+Check-only mode to validate without writing:
+
+```
+npm exec -- agent-toolkit enforce-node-baseline --cwd . --check
+```
+
+Validate monorepo root `package.json` scripts and workspace structure:
 
 ```
 npm exec -- agent-toolkit preflight --cwd . --check-workspace-package-json package.json
 ```
 
+Run preflight with required-file and directory guards:
+
+```
+npm exec -- agent-toolkit preflight --cwd . --require package.json --ensure-dir logs
+```
+
 Capture long output safely:
 
 ```
@@ -70,9 +134,9 @@ Deploy organization local anti-drift husky hooks to repository root:
 npm exec -- agent-toolkit sync-husky-hooks --cwd .
 ```
 
-This command pins root local hook dependencies (`husky` and
-`@produck/agent-toolkit`) and syncs `.husky/pre-commit` and
-`.husky/commit-msg`.
+This command pins root local hook dependencies (`c8`, `husky`, `lerna`, and
+`@produck/agent-toolkit`) to organization baseline fixed versions and syncs
+`.husky/pre-commit` and `.husky/commit-msg`.
 
 Validate commit message format:
 
@@ -162,7 +226,8 @@ Workflow behavior:
 
 Release policy:
 
-- Default organization usage is @latest.
+- Central package is installed locally in downstream repositories at a fixed
+  version managed by `agent-toolkit sync-husky-hooks`.
 - Run format:check and test first, then workspace `publish:dry-run` before
   `publish`.
 - Keep rollback option by republishing previous stable version if needed.

package/bin/command/enforce-node-baseline/index.mjs

@@ -98,15 +98,10 @@ export function runEnforceNodeBaseline(options) {
     syncInstructionsArgs.push('--dry-run');
   }
 
-  const preflightArgs = [
-    'preflight',
-    '--cwd',
-    cwd,
-    '--require',
-    'package.json',
-    '--check-workspace-package-json',
-    'package.json',
-  ];
+  const preflightArgs = ['preflight', '--cwd', cwd, '--require', 'package.json'];
+  if (mode !== 'sync') {
+    preflightArgs.push('--check-workspace-package-json', 'package.json');
+  }
 
   const syncCoverageArgs = ['sync-coverage-script', '--cwd', cwd];
   for (const workspacePath of workspaces) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@produck/agent-toolkit",
-  "version": "0.3.3",
+  "version": "0.4.0",
   "description": "Central CLI toolkit for organization AI execution workflows",
   "type": "module",
   "repository": {
@@ -17,7 +17,8 @@
     "coverage:check": "npm exec --yes -- c8 --check-coverage --lines 100 --functions 100 --branches 100 --statements 100 node --test test/index.mjs",
     "test": "node --test test/index.mjs",
     "verify": "node ./bin/agent-toolkit.mjs --help && node ./bin/agent-toolkit.mjs preflight --cwd . --require package.json",
-    "pack:check": "npm pack --dry-run"
+    "pack:check": "npm pack --dry-run",
+    "produck:coverage": "c8@11.0.0 --reporter=lcov --reporter=html --reporter=text-summary npm test"
   },
   "files": [
     "bin",
@@ -30,5 +31,8 @@
     "node": ">=18.0.0"
   },
   "license": "MIT",
-  "gitHead": "45bc825ac6c290ca99b58881ee3b052bd0c2265e"
+  "gitHead": "c0aabcec12d70234cfc15cb741fe4ffcf5e4601e",
+  "devDependencies": {
+    "c8": "11.0.0"
+  }
 }