@ui8kit/uxdx 0.1.0 → 0.1.2

package/README.md

@@ -1,20 +1,33 @@
 # UXDX
 
-CLI to accumulate operator and developer experience packs. One binary, two
-commands. Package name: [`@ui8kit/uxdx`](https://www.npmjs.com/package/@ui8kit/uxdx).
+CLI for operator files and SDLC harness packs. One binary (`uxdx`), two
+commands. Package: [`@ui8kit/uxdx`](https://www.npmjs.com/package/@ui8kit/uxdx).
 
-Homepage: [github.com/ui8kit/uxdx](https://github.com/ui8kit/uxdx)
+Repo: [github.com/ui8kit/uxdx](https://github.com/ui8kit/uxdx)
 
-```text
+## Run
+
+Prefer Bun (no Node `punycode` warning from `npx`):
+
+```bash
+bunx @ui8kit/uxdx --help
+bunx @ui8kit/uxdx -p
+bunx @ui8kit/uxdx -s --level light
+```
+
+Same via npm:
+
+```bash
 npx @ui8kit/uxdx --help
-npx @ui8kit/uxdx project | p | -p | --project  [init] [--dir <path>] [--rules] [--force]
-npx @ui8kit/uxdx sdlc    | s | -s | --sdlc     [init] [--dir <path>] --level light|core|full [--force] [--no-install]
+npx @ui8kit/uxdx -p
+npx @ui8kit/uxdx -s --level light
 ```
 
-Same via Bun: `bunx @ui8kit/uxdx --help`.
+`npx` may print `DEP0040` / `punycode`. That comes from npm’s Node, not this
+CLI. The command still runs if you then see `uxdx: project init` or
+`uxdx: sdlc …`.
 
-The binary is still `uxdx`. After a local or global install you can call it
-without the scope:
+After a local or global install the binary is unscoped:
 
 ```bash
 npm i -g @ui8kit/uxdx
@@ -24,15 +37,78 @@ npm i -D @ui8kit/uxdx
 npx uxdx --help
 ```
 
-- `project` writes `README.md`, `.gitignore`, `.cursorignore`, and `.manual/`.
-- `sdlc` copies a vendored harness pack into `.sdlc/`. `--level` is required.
-- After copy, `sdlc` runs `.sdlc/sdlc.sh install` unless `--no-install`.
+## Commands
+
+Aliases are equivalent. `init` is the default and may be omitted.
+
+```text
+uxdx [--help]
+uxdx project | p | -p | --project  [init] [--dir <path>] [--rules] [--force]
+uxdx sdlc    | s | -s | --sdlc     [init] [--dir <path>] --level light|core|full [--force] [--no-install]
+```
+
+| Flag | Command | Meaning |
+| --- | --- | --- |
+| `--dir <path>` | both | Target repo (default: cwd) |
+| `--force` | both | Overwrite files this tool owns |
+| `--rules` | `project` | Stub `.cursor/rules/uxdx.mdc` if missing |
+| `--level` | `sdlc` | Required: `light`, `core`, or `full` |
+| `--no-install` | `sdlc` | Copy `.sdlc/` only; skip `sdlc.sh install` |
+
+### `project` (`-p`)
+
+Writes the default operator layout. Existing filled files are left alone
+unless `--force`. If `.manual/` already exists, it is not touched.
+
+```bash
+bunx @ui8kit/uxdx -p
+bunx @ui8kit/uxdx -p --dir ./my-repo --rules
+```
+
+Creates or updates:
+
+- `README.md` (only if missing)
+- `.gitignore` (`.manual/*` + `!.manual/.gitkeep`)
+- `.cursorignore` (`.manual/`)
+- `.project/README.md` stub
+- `.manual/.gitkeep` (only if `.manual/` is missing)
 
-## Local
+Success:
+
+```text
+uxdx: project init in <dir>
+  README.md
+  .gitignore
+  .cursorignore
+  .project/
+  .manual/
+```
+
+### `sdlc` (`-s`)
+
+Copies one vendored pack into `.sdlc/`. `--level` is required (no silent
+`full`). Then runs `.sdlc/sdlc.sh install` unless `--no-install`.
+
+```bash
+bunx @ui8kit/uxdx -s --level light
+bunx @ui8kit/uxdx -s --level core --dir ./my-repo
+bunx @ui8kit/uxdx -s --level full --no-install
+```
+
+Do not stack two levels in one repo. Use `--force` only to replace a
+different level.
+
+Pack source: `packages/sdlc/harness/`.
+
+## This checkout
 
 ```bash
 bun install
 bun test
-bun run uxdx -- --help
 bun run build
+bun run uxdx -- --help
+bun run uxdx -- -p --help
+bun run uxdx -- -s --help
 ```
+
+`--` after `bun run uxdx` is required so flags go to the CLI, not to Bun.

package/dist/uxdx.mjs

@@ -1,6 +1,3 @@
-import { createRequire } from "node:module";
-var __require = /* @__PURE__ */ createRequire(import.meta.url);
-
 // packages/cli/src/parse.ts
 var LEVELS = new Set(["light", "core", "full"]);
 function takeFlag(rest, name) {
@@ -91,7 +88,7 @@ Usage:
   uxdx project | p | -p | --project  [init] [--dir <path>] [--rules] [--force]
   uxdx sdlc    | s | -s | --sdlc     [init] [--dir <path>] --level light|core|full [--force] [--no-install]
 
-  -p / --project   Scaffold README, ignores, and .manual/
+  -p / --project   Scaffold README, ignores, and .manual/.gitkeep if missing
   -s / --sdlc      Install an SDLC harness pack into .sdlc/
 
 Run uxdx project --help or uxdx sdlc --help for command flags.
@@ -141,6 +138,35 @@ function writeIfMissing(file, body, force) {
     return;
   writeFileSync(file, body);
 }
+function ensureManualGitignore(file) {
+  const block = `.manual/*
+!.manual/.gitkeep
+`;
+  if (!existsSync(file)) {
+    writeFileSync(file, block);
+    return;
+  }
+  const cur = readFileSync(file, "utf8");
+  const lines = cur.split(/\r?\n/);
+  if (lines.some((l) => l.trim() === ".manual/*")) {
+    ensureLine(file, "!.manual/.gitkeep", false);
+    return;
+  }
+  const withoutFull = lines.filter((l) => l.trim() !== ".manual/");
+  const next = withoutFull.join(`
+`);
+  const nl = next.endsWith(`
+`) || next.length === 0 ? "" : `
+`;
+  writeFileSync(file, `${next}${nl}${block}`);
+}
+function ensureManualDir(root) {
+  const dir = join(root, ".manual");
+  if (existsSync(dir))
+    return;
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, ".gitkeep"), "");
+}
 function initProject(opts) {
   const root = opts.dir;
   mkdirSync(root, { recursive: true });
@@ -150,7 +176,7 @@ function initProject(opts) {
   writeIfMissing(readme, `# ${name}
 `, opts.force);
   done.push("README.md");
-  ensureLine(join(root, ".gitignore"), ".manual/", opts.force);
+  ensureManualGitignore(join(root, ".gitignore"));
   done.push(".gitignore");
   ensureLine(join(root, ".cursorignore"), ".manual/", opts.force);
   done.push(".cursorignore");
@@ -161,7 +187,7 @@ function initProject(opts) {
 Operator notes for this repository. See \`intent.md\` when present.
 `, opts.force);
   done.push(".project/");
-  mkdirSync(join(root, ".manual"), { recursive: true });
+  ensureManualDir(root);
   done.push(".manual/");
   if (opts.rules) {
     const rulesDir = join(root, ".cursor", "rules");
@@ -288,9 +314,6 @@ function run(argv) {
     return 1;
   }
 }
-if (__require.main == __require.module) {
-  process.exit(run(process.argv));
-}
-export {
-  run
-};
+
+// packages/cli/src/bin.ts
+process.exit(run(process.argv));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ui8kit/uxdx",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "CLI to accumulate operator and developer experience packs",
   "type": "module",
   "bin": {
@@ -37,8 +37,8 @@
   "license": "MIT",
   "homepage": "https://github.com/ui8kit/uxdx",
   "scripts": {
-    "build": "bun build packages/cli/src/main.ts --outfile dist/uxdx.mjs --target node",
-    "uxdx": "bun packages/cli/src/main.ts",
+    "build": "bun build packages/cli/src/bin.ts --outfile dist/uxdx.mjs --target node",
+    "uxdx": "bun packages/cli/src/bin.ts",
     "test": "bun test",
     "prepack": "bun run build",
     "prepublishOnly": "bun test && bun run build",

package/packages/sdlc/harness/README.md

@@ -1,18 +1,28 @@
 # SDLC harness packs (solo)
 
-Copy-paste packs for the AI-native loop, sized for one operator. Source method:
-[`.manual/sdlc-en`](../.manual/sdlc-en/README.md). Which product gets which pack:
-[`.project/sdlc-scope.md`](../.project/sdlc-scope.md).
+Copy-ready packs for the AI-native loop, sized for one operator. Method:
+[The AI-Native SDLC Playbook](https://academy.claude.com/courses/ai-native-sdlc-playbook)
+(public course). Map `plan.md` / `CLAUDE.md` onto Cursor Plan mode and
+`AGENTS.md`.
 
-Later this tree can move to its own repo or a CLI (`sdlc init --level full`).
-Until then the consumer copies **one** pack into **`.sdlc/`**.
+This tree is the source of truth. Install a pack with the published CLI:
+
+```text
+npx @ui8kit/uxdx sdlc --level light|core|full
+```
+
+That copies **one** pack into the target repo’s `.sdlc/` and, unless
+`--no-install`, overlays Cursor rules/skills and merges `AGENTS.md`.
+Never stack two levels. Do not copy this tree by hand.
+
+Package: [`@ui8kit/uxdx`](https://www.npmjs.com/package/@ui8kit/uxdx)
 
 ## How it works
 
 ```
-hinddy/brainstorm/.harness-sdlc/<level>/     (this gym)
+@ui8kit/uxdx  packages/sdlc/harness/<level>/
         │
-        │  copy (do not merge levels)
+        │  npx @ui8kit/uxdx sdlc --level <level>
         ▼
 your-repo/.sdlc/                             artifacts + overlay text
         │
@@ -23,9 +33,15 @@ your-repo/.sdlc/                             artifacts + overlay text
         └── cursor/rules/                    copy → .cursor/rules/
 ```
 
-1. Pick **full**, **core**, or **light** from `sdlc-scope.md`. Never stack two packs.
-2. Copy the pack directory contents into `<repo>/.sdlc/` (keep `manifest.yaml`).
-3. **Activate Cursor** (rules/skills are not loaded from `.sdlc` by default):
+1. Pick **full**, **core**, or **light**. Never stack two packs.
+2. Run `npx @ui8kit/uxdx sdlc --level <level>` (add `--dir` if needed).
+3. **Activate Cursor** is done by `sdlc.sh install` (default). To copy only:
+
+   ```text
+   npx @ui8kit/uxdx sdlc --level <level> --no-install
+   ```
+
+   then overlay yourself:
 
    ```bash
    mkdir -p .cursor/rules .cursor/skills
@@ -33,26 +49,29 @@ your-repo/.sdlc/                             artifacts + overlay text
    cp -R .sdlc/skills/* .cursor/skills/
    ```
 
-4. **AGENTS.md**: if the repo already has a product `AGENTS.md` (SiteStarter, YPanel, …), **append** a short pointer. Do not replace stack-contract text. If there is no root file, copy `.sdlc/AGENTS.md` to the repo root.
-5. For each change: copy `intent.md` / `spec.md` / `plan.md` into `.sdlc/changes/<slug>/` and fill them. Leave the pack-root files as templates.
-6. Existing product rules (`.cursor/rules/stack-contract.mdc`, …) stay. The harness adds SDLC rules; it does not own Codex IA.
+4. **AGENTS.md**: if the repo already has one, the install **appends** a
+   marked overlay. Do not replace product contract text. If there is no root
+   file, install writes `.sdlc/AGENTS.md` to the repo root.
+5. For each change: copy templates into `.sdlc/changes/<slug>/` (`sdlc.sh
+   start <slug>`) and fill them. Leave the pack-root files as templates.
+6. Existing product rules stay. The harness adds SDLC rules only.
 
-Human still merges. The agent writes artifacts and code; you accept `plan.md` before a large diff.
+Human still merges. The agent writes artifacts and code; you accept `plan.md`
+before a large diff.
 
 ## Levels
 
 | Pack | Use when | Artifacts | Extra |
 | --- | --- | --- | --- |
-| `light/` | Product on an existing contract; small blast radius | `plan.md` required; `intent.md` optional; skip `spec.md` unless IA changes | No evals, no maintain bands |
-| `core/` | Kernel, API, ARIA, shared library | `intent.md` + `plan.md`; compressed `spec.md` on boundary changes | Invariant skills; short `REVIEW.md` |
-| `full/` | Portable Codex path, YPanel, anything that ships + is pinned | Full chain including `spec.md` | `REVIEW.md`, `evals/` stub, `bands.yaml` stub |
-
-## Future CLI (not built)
+| `light/` | Product already has a contract; small blast radius | `plan.md` required; `intent.md` optional; skip `spec.md` unless the public contract changes | No evals, no maintain bands |
+| `core/` | Kernel, API, or shared library | `intent.md` + `plan.md`; short `spec.md` on boundary changes | Invariant skills; short `REVIEW.md` |
+| `full/` | Shipping product or high-stakes operator surface | Full chain including `spec.md` | `REVIEW.md`, `evals/` stub, `bands.yaml` stub |
 
-Suggested commands, matching `manifest.yaml` in each pack:
+## Commands
 
-- `sdlc init --level full` → copy pack to `.sdlc`, overlay rules/skills, patch root `AGENTS.md` between markers
-- `sdlc change start <slug>` → copy templates into `.sdlc/changes/<slug>/`
-- `sdlc change accept` → remind to commit artifacts with the diff
-
-Do not invent a second content REST or product kinds from this harness.
+```text
+npx @ui8kit/uxdx sdlc --level full
+bash .sdlc/sdlc.sh install
+bash .sdlc/sdlc.sh start <slug>
+bash .sdlc/sdlc.sh status
+```

package/packages/sdlc/harness/core/AGENTS.md

@@ -1,7 +1,7 @@
 <!-- sdlc-harness:begin -->
 ## SDLC harness (core)
 
-This repo uses the **core** pack (`.harness-sdlc/core` → `.sdlc/`).
+This repo uses the **core** pack from [`@ui8kit/uxdx`](https://www.npmjs.com/package/@ui8kit/uxdx) (`.sdlc/`).
 
 - Boundary, API, and policy changes: `intent.md` + short `spec.md` + `plan.md`.
 - Mechanical fixes: `plan.md` only, still name the invariant you must not break.

package/packages/sdlc/harness/core/README.md

@@ -1,9 +1,12 @@
 # Core harness
 
 For kernels, shared libraries, and high blast-radius contracts.
-Examples: FormSet, Framework, Panel, ui8kit/aria, Context.
 
-Copy this directory to `<repo>/.sdlc/`. Overlay Cursor files — `../README.md`.
+Install:
+
+```text
+npx @ui8kit/uxdx sdlc --level core
+```
 
 ## Per change
 

package/packages/sdlc/harness/full/AGENTS.md

@@ -1,7 +1,7 @@
 <!-- sdlc-harness:begin -->
 ## SDLC harness (full)
 
-This repo uses the **full** pack (`.harness-sdlc/full` → `.sdlc/`).
+This repo uses the **full** pack from [`@ui8kit/uxdx`](https://www.npmjs.com/package/@ui8kit/uxdx) (`.sdlc/`).
 
 Loop: accepted `intent.md` → `spec.md` → `plan.md` → diff + existing verify
 → PR against `.sdlc/REVIEW.md` → you merge. Optional later: `evals/` on

package/packages/sdlc/harness/full/README.md

@@ -1,9 +1,12 @@
 # Full harness
 
-For the portable Codex path and high-stakes operators.
-Examples: SiteStarter, GoBackend, SvelteCMS, YPanel.
+For shipping products and high-stakes operator surfaces.
 
-Copy this directory to `<repo>/.sdlc/`. Overlay Cursor files — `../README.md`.
+Install:
+
+```text
+npx @ui8kit/uxdx sdlc --level full
+```
 
 Solo adaptation: no MDM, no weekly committee. You still accept `spec.md` and
 `plan.md`, merge PRs, and authorize production.
@@ -20,4 +23,4 @@ Solo adaptation: no MDM, no weekly committee. You still accept `spec.md` and
 
 ## Per change
 
-`mkdir -p .sdlc/changes/<slug>` and copy `intent.md`, `spec.md`, `plan.md`.
+`bash .sdlc/sdlc.sh start <slug>` (copies `intent.md`, `spec.md`, `plan.md`).

package/packages/sdlc/harness/full/hooks/README.md

@@ -12,6 +12,6 @@ repo, for example:
 Keep approval prompts off the build hot path so parallel sessions are not
 serialized. Production gates belong at deploy, not on every file save.
 
-Example PreToolUse shape lives in the playbook
-(`.manual/sdlc-en/10-hooks-as-approval-gates.md`). Do not enable managed-only
-enterprise settings unless you actually operate MDM.
+Example PreToolUse shape lives in the public playbook
+([hooks as approval gates](https://academy.claude.com/courses/ai-native-sdlc-playbook/hooks-as-approval-gates)).
+Do not enable managed-only enterprise settings unless you actually operate MDM.

package/packages/sdlc/harness/light/AGENTS.md

@@ -1,7 +1,7 @@
 <!-- sdlc-harness:begin -->
 ## SDLC harness (light)
 
-This repo uses the **light** pack from `hinddy/brainstorm` (`.harness-sdlc/light`).
+This repo uses the **light** pack from [`@ui8kit/uxdx`](https://www.npmjs.com/package/@ui8kit/uxdx).
 Working copy: `.sdlc/`. Per-change artifacts: `.sdlc/changes/<slug>/`.
 
 - Non-trivial work starts in plan mode. Commit `plan.md` before a large diff.

package/packages/sdlc/harness/light/README.md

@@ -1,15 +1,17 @@
 # Light harness
 
-For product repos that already have a contract (`AGENTS.md`, stack rules, tests).
-Examples: AlexY OS, GitCourse, Lab, BrandOSS, ui8px-cli, FastyGo UI.
+For product repos that already have a contract (`AGENTS.md`, rules, tests).
 
-Copy this directory to `<repo>/.sdlc/`. Then overlay Cursor files — see
-`../README.md`.
+Install:
+
+```text
+npx @ui8kit/uxdx sdlc --level light
+```
 
 ## Per change
 
-1. `mkdir -p .sdlc/changes/<slug>`
-2. Copy `plan.md` into that folder and fill it.
-3. Add `intent.md` only if the origin is unclear (incident, external request).
-4. Skip `spec.md` unless you are changing published IA or a user-visible contract.
-5. Run the repo's existing verify command before calling the task done.
+1. `bash .sdlc/sdlc.sh start <slug>` (or `mkdir -p .sdlc/changes/<slug>`).
+2. Fill `plan.md` in that folder.
+3. Add `intent.md` only if the origin is unclear.
+4. Skip `spec.md` unless you are changing a published or user-visible contract.
+5. Run the repo’s existing verify command before calling the task done.

package/packages/sdlc/harness/light/skills/sdlc-light/SKILL.md

@@ -2,7 +2,8 @@
 name: sdlc-light
 description: >-
   Light AI-native SDLC for a solo developer. Use when planning or implementing
-  work in a repo that copied .harness-sdlc/light into .sdlc. Write plan.md,
+  work in a repo whose `.sdlc` was installed with `@ui8kit/uxdx` at level
+  light. Write plan.md,
   skip spec.md unless IA changes, run existing verify commands.
 ---