@orqint/cli 0.1.0 → 0.1.2

package/README.md

@@ -1,100 +1,73 @@
 # Orqint
 
-CLI orchestration for Cursor-native `think` / `plan` workflows. See [docs/PRD/PRD.md](docs/PRD/PRD.md).
+CLI orchestration for Cursor-native `think` / `plan` workflows (prepare in the CLI → work in Cursor → apply JSON back). Deep product spec: [docs/PRD/PRD.md](docs/PRD/PRD.md).
 
-**Maintainers:** CLI source lives under [`packages/cli/`](packages/cli/README.md). Root folder [`orqint/`](orqint/core/) holds **project state** (`memory.json`, etc.) for this repo only, not TypeScript sources. Full map: [docs/Repository-layout.md](docs/Repository-layout.md).
+## Use Orqint in your project
 
-## Prerequisites
-
-- Node.js (LTS)
-- [pnpm](https://pnpm.io/installation) (for developing this repo)
-- [npm](https://www.npmjs.com/) (ships with Node; used by `npx` and `orqint update`)
-
-## Run with `npx` (no global install)
-
-After the package is **published to npm** (see below):
+You need [Node.js](https://nodejs.org/) (LTS). From your **project root**:
 
 ```bash
-npx --yes @orqint/cli@latest version
 npx --yes @orqint/cli@latest init
 ```
 
-Check for updates (queries the registry):
-
-```bash
-npx --yes @orqint/cli@latest update
-```
+1. **`init`** creates the `orqint/` layout (`memory.json`, prompts, handoff folder, etc.).
+2. It also installs **user assets** when missing: **`AGENTS.md`**, **`ORQINT.md`**, and **`.cursor/rules/orqint-workflow.mdc`** (so Cursor can help with handoffs). Existing files are **not** overwritten — use **`orqint init --force-user-assets`** only if you want to refresh those from the package.
+3. Open **`ORQINT.md`** in your repo for the short workflow (commands and tables).
 
-Run the latest published CLI via npx (recommended when a newer version exists):
+Other commands (after init):
 
 ```bash
+npx --yes @orqint/cli@latest update
 npx --yes @orqint/cli@latest <command>
 ```
 
-`orqint update --install <args>` re-invokes `npx @orqint/cli@latest <args>` for you when a newer version is available.
+`orqint init --brownfield` can seed hints from your `package.json` / `README.md`. `orqint init --force` resets **Orqint runtime** (e.g. `memory.json`) and does **not** replace your root `AGENTS.md` / `ORQINT.md` / Cursor rules unless you also pass **`--force-user-assets`**.
 
-### Publish (maintainers)
+---
 
-From this repo, with an npm login that can publish to the `@orqint` scope:
+## Maintainers — this repository
 
-```bash
-npm run build
-npm publish
-```
+CLI source: [`packages/cli/`](packages/cli/README.md). Root [`orqint/`](orqint/core/) is **project state** for dogfooding (not TypeScript sources). Shipped **user-facing** files for npm live under **`user-assets/`** (see [user-assets/FOR_MAINTAINERS.md](user-assets/FOR_MAINTAINERS.md)). Layout map: [docs/Repository-layout.md](docs/Repository-layout.md).
 
-The package is scoped as `@orqint/cli`; `publishConfig.access` is `public` so `npm publish` does not require extra flags.
+### Prerequisites (development)
 
-## Install the `orqint` command (this machine)
+- Node.js (LTS)
+- [pnpm](https://pnpm.io/installation)
+- npm (for `npx` and `orqint update`)
 
-From the **root of this repository**:
+### Publish
 
 ```bash
-pnpm run cli:install
+npm run build
+npm publish
 ```
 
-This installs dependencies, builds `dist/`, and runs `pnpm link --global` so `orqint` is on your PATH.
+Scoped package **`@orqint/cli`**; `publishConfig.access` is `public`.
 
-On Windows (no `bash`), use:
+### Install `orqint` globally from this clone
 
 ```bash
-pnpm run cli:install:pnpm
+pnpm run cli:install
 ```
 
-If `orqint` is not found, add pnpm’s global bin directory to your PATH (run `pnpm bin -g` to see it).
+Windows (no bash): `pnpm run cli:install:pnpm`. If `orqint` is not on PATH, see `pnpm bin -g`.
 
-**Shell alternative (same steps):**
+Shell alternative: `bash scripts/setup-cli.sh`
 
-```bash
-bash scripts/setup-cli.sh
-```
-
-## Update after pulling changes
+### Update after pulling
 
 ```bash
 pnpm run cli:upgrade
 ```
 
-Or:
-
-```bash
-bash scripts/update-cli.sh
-```
-
-`cli:upgrade` runs `git pull --rebase` (when this folder is a git repo), then reinstalls and rebuilds. Your global link keeps pointing at this folder, so you immediately get the new build.
-
-After you `git pull` yourself (or without git), you can run:
-
-```bash
-pnpm run cli:upgrade:pnpm
-```
+Or `pnpm run cli:upgrade:pnpm` without `git pull` inside the script.
 
-## Use in a test project
+### Test project (local build)
 
-1. Build / install CLI as above.
-2. Open an empty folder in Cursor.
-3. Run `orqint init`, then follow [AGENTS.md](AGENTS.md) and [docs/orqint-cursor-starter.md](docs/orqint-cursor-starter.md).
+1. Build / link CLI as above.
+2. In a throwaway folder: `orqint init`, then follow **[user-assets/ORQINT.md](user-assets/ORQINT.md)** (same text users get) and [docs/orqint-cursor-starter.md](docs/orqint-cursor-starter.md).
 
-## Use without global install
+### Run CLI without global install (this repo)
 
 ```bash
 pnpm run build

package/dist/orqint/commands/init.d.ts

@@ -1,5 +1,6 @@
 export type InitOptions = {
     force?: boolean;
+    forceUserAssets?: boolean;
     brownfield?: boolean;
     migrateLegacy?: boolean;
 };

package/dist/orqint/commands/init.js

@@ -59,6 +59,12 @@ async function runInit(cwd, opts) {
     await fs.ensureDir(path.join(root, ".handoff"));
     await fs.ensureDir((0, paths_1.orqintSpecDir)(cwd));
     await fs.ensureDir((0, paths_1.orqintArchiveDir)(cwd));
+    const userAssetsCopied = await copyUserAssets(cwd, opts);
+    if (userAssetsCopied > 0) {
+        (0, logger_1.log)("info", "init_next_step", {
+            hint: "Open ORQINT.md in your project root for the workflow overview.",
+        });
+    }
     let memory = (0, memory_1.ensureDefaults)(JSON.parse(JSON.stringify(memory_1.EMPTY_MEMORY)));
     if (opts.brownfield) {
         memory = await seedFromRepo(cwd, memory);
@@ -70,6 +76,43 @@ async function runInit(cwd, opts) {
     await (0, memory_1.writeMemory)(cwd, memory);
     (0, logger_1.log)("info", "init_complete", { cwd, brownfield: !!opts.brownfield });
 }
+/** Installed package root (contains `user-assets/` next to `dist/`). */
+function packageRootDir() {
+    return path.join(__dirname, "..", "..", "..");
+}
+/** Paths relative to package root → relative to consumer cwd. */
+const USER_ASSET_MANIFEST = [
+    { from: path.join("user-assets", "AGENTS.md"), to: "AGENTS.md" },
+    { from: path.join("user-assets", "ORQINT.md"), to: "ORQINT.md" },
+    {
+        from: path.join("user-assets", "cursor-rules", "orqint-workflow.mdc"),
+        to: path.join(".cursor", "rules", "orqint-workflow.mdc"),
+    },
+];
+/** Copy shipped user assets; skip existing destinations unless `forceUserAssets`. Returns count copied. */
+async function copyUserAssets(cwd, opts) {
+    const pkgRoot = packageRootDir();
+    let copied = 0;
+    for (const { from: relFrom, to: relTo } of USER_ASSET_MANIFEST) {
+        const from = path.join(pkgRoot, relFrom);
+        const to = path.join(cwd, relTo);
+        if (!(await fs.pathExists(from))) {
+            (0, logger_1.log)("warn", "init_user_asset_missing", { from });
+            continue;
+        }
+        const destExists = await fs.pathExists(to);
+        const shouldCopy = opts.forceUserAssets || !destExists;
+        if (!shouldCopy) {
+            (0, logger_1.log)("info", "init_user_asset_skipped_exists", { file: relTo });
+            continue;
+        }
+        await fs.ensureDir(path.dirname(to));
+        await fs.copy(from, to, { overwrite: opts.forceUserAssets });
+        (0, logger_1.log)("info", "init_user_asset_copied", { file: relTo });
+        copied += 1;
+    }
+    return copied;
+}
 async function seedFromRepo(cwd, memory) {
     const pkgPath = path.join(cwd, "package.json");
     if (await fs.pathExists(pkgPath)) {

package/dist/orqint/index.js

@@ -49,7 +49,7 @@ No model API keys in this tool: use Cursor on the generated handoff files, then
 Commands:
   orqint version | --version | -V
   orqint update [--install] [<args>...]   check npm; --install runs npx ${name}@latest <args>
-  orqint init [--brownfield] [--migrate-legacy] [--force]
+  orqint init [--brownfield] [--migrate-legacy] [--force] [--force-user-assets]
   orqint think prepare "<intent>" [--override key=value ...]
   orqint think apply --file <path>
   orqint plan prepare [--force]
@@ -126,8 +126,10 @@ async function main() {
         }
         if (cmd === "init") {
             const args = argv.slice(1);
+            const forceUserAssets = takeFlag(args, "--force-user-assets");
             await (0, init_1.runInit)(cwd, {
                 force: takeFlag(args, "--force"),
+                forceUserAssets,
                 brownfield: takeFlag(args, "--brownfield"),
                 migrateLegacy: takeFlag(args, "--migrate-legacy"),
             });

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@orqint/cli",
-	"version": "0.1.0",
+	"version": "0.1.2",
 	"description": "CLI orchestration for Cursor-native think/plan workflows (Orqint)",
 	"keywords": [
 		"orqint",
@@ -21,7 +21,9 @@
 	"files": [
 		"dist",
 		"README.md",
-		"AGENTS.md"
+		"user-assets/AGENTS.md",
+		"user-assets/ORQINT.md",
+		"user-assets/cursor-rules/orqint-workflow.mdc"
 	],
 	"scripts": {
 		"prepublishOnly": "npm run build",

package/{AGENTS.md → user-assets/AGENTS.md}

@@ -10,17 +10,11 @@
 
 - Follow the JSON schema embedded in each handoff.
 - Honor `memory.override` from the sliced context.
-- No OpenAI (or other) API keys in the Orqint CLI; intelligence for `think`/`plan` runs here in Cursor.
+- No OpenAI (or other) API keys in the Orqint CLI; intelligence for `think`/`plan` runs in Cursor on the handoff files.
 
 ## Source of truth
 
 - **Canonical:** `orqint/core/memory.json`
 - **Derived:** `orqint-spec/`
 
-## Developing the Orqint CLI (this repository)
-
-- TypeScript: `packages/cli/src/`
-- Prompt templates to edit: `packages/cli/prompts/` (built into `dist/orqint/prompts/`)
-- **npm `version`:** bump per [docs/PRD/PRD.md](docs/PRD/PRD.md) §17 before each publish; see `.cursor/rules/orqint-versioning.mdc`.
-
-See [docs/Repository-layout.md](docs/Repository-layout.md), [docs/PRD/PRD.md](docs/PRD/PRD.md), and `.cursor/rules/orqint-workflow.mdc`.
+See **ORQINT.md** in this repository for commands and `init` options. Package: [@orqint/cli on npm](https://www.npmjs.com/package/@orqint/cli).

package/user-assets/ORQINT.md

@@ -0,0 +1,36 @@
+# Orqint — Cursor workflow (your project)
+
+Orqint drives **prepare → run in Cursor → apply**: the CLI writes handoff files; you run the Agent in Cursor on those files; you save **strict JSON** responses; the CLI merges into `orqint/core/memory.json`. No API keys are required in the CLI.
+
+## After `orqint init`
+
+- **Canonical state:** `orqint/core/memory.json`
+- **Derived docs:** `orqint-spec/`
+- **Handoffs:** `orqint/.handoff/`
+
+Read **`AGENTS.md`** in this repository for the short agent checklist (think/plan flow and rules). If `init` added **`.cursor/rules/orqint-workflow.mdc`**, Cursor can use it when you work in handoff files.
+
+## Commands (Phase 1)
+
+Use `npx @orqint/cli` or a local/global `orqint` binary the same way.
+
+| Step | Command |
+| --- | --- |
+| Think handoff | `orqint think prepare "<your intent>"` |
+| In Cursor | Open `orqint/.handoff/think.md`, run the Agent, write valid JSON to e.g. `orqint/.handoff/think.response.json` |
+| Merge think | `orqint think apply --file orqint/.handoff/think.response.json` |
+| Plan handoff | `orqint plan prepare` |
+| In Cursor | Same pattern → `orqint/.handoff/plan.response.json` |
+| Merge plan | `orqint plan apply --file orqint/.handoff/plan.response.json` |
+
+Follow the JSON schema embedded in each handoff file. Honor `memory.override` when the sliced context includes it.
+
+## Optional flags (`init`)
+
+- `orqint init --brownfield` — seed `memory.json` hints from `package.json` / `README.md` when present.
+- `orqint init --force` — re-initialize **Orqint runtime** (e.g. `memory.json`, layout). Does **not** overwrite existing **`AGENTS.md`**, **`ORQINT.md`**, or **`.cursor/rules/orqint-workflow.mdc`** in your project.
+- `orqint init --force-user-assets` — refresh those Orqint-shipped files from the package (overwrites the paths above). Use when you want the latest templates from your installed CLI version.
+
+## Package reference
+
+Published CLI: [@orqint/cli on npm](https://www.npmjs.com/package/@orqint/cli).

package/user-assets/cursor-rules/orqint-workflow.mdc

@@ -0,0 +1,18 @@
+---
+description: Orqint think/plan handoffs — Cursor agent rules (user project)
+globs: orqint/.handoff/**
+alwaysApply: false
+---
+
+# Orqint (Phase 1)
+
+When the user works with **Orqint handoffs** (`orqint/.handoff/think.md`, `plan.md`):
+
+1. **Read** the handoff file they open; it contains sliced memory, the prompt template, and the **exact JSON schema** for your reply.
+2. **Output only JSON** matching that schema (no markdown fences unless they ask to save to `.json` — the file on disk must be parseable JSON).
+3. **Respect `memory.override`** (and any human overrides in the handoff): they override model defaults (e.g. no_supabase, mobile_first).
+4. **Open questions:** at most **3–5** high-value questions in `open_questions` when confidence is low.
+5. **Do not** invent API keys or ask the user to put secrets in the repo; Orqint does not use CLI-side model APIs.
+6. After you produce JSON, the user runs `orqint think apply --file ...` or `orqint plan apply --file ...` — remind them if they forget.
+
+For step-by-step usage, see **ORQINT.md** in the project root.