aidlc-fast 0.0.0-stage → 0.6.0

package/README.md

@@ -1,3 +1,92 @@
-# Temporary Holding Version
+# aidlc-fast
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Thinned [AI-DLC](https://builder.aws.com/content/3GnQs6zaYp4mAx9FWBulDkhWnBo/ai-dlc-v2-core-concepts)-inspired orchestrator: **code routes, model works**.
+
+**For teammates:** one slash command and checkboxes in chat. No AIDLC vocabulary required.
+
+## Install once (project)
+
+Requires [Bun](https://bun.sh) on PATH for the CLI runtime.
+
+```bash
+npm install -D file:../aidlc-fast   # or published aidlc-fast
+npx aidlc-fast config --harness generic,cursor,claude
+```
+
+(`npx` is only for this install step.)
+
+## How humans use it
+
+In **Cursor** or **Claude Code** chat:
+
+```text
+/aidlc-fast Add crash reports and show logs in the app
+```
+
+Then answer checkboxes when asked:
+
+```text
+## Plan check
+- [ ] Approve this plan
+- [ ] Change the plan: …
+- [ ] Different idea: …
+```
+
+Later:
+
+```text
+## Ship check
+- [ ] Ship it
+- [ ] Not yet: …
+```
+
+Continue a run: `/aidlc-fast` (empty).
+
+**You never type APPROVE in a terminal.** The agent advances gates from your chat reply.
+
+## Flow (plain language)
+
+```text
+/aidlc-fast + intent
+  → Understanding (may ask checkboxes)
+  → Plan check
+  → Building (+ quiet quality checks)
+  → Ship check
+  → Done
+```
+
+`express` scope skips Plan check / review / learn — still runs verify + e2e + Ship check.
+
+## Agent / CLI (hidden from humans)
+
+The CLI still owns state: `start`, `complete`, `rework`, `approve --human-reply "…"`, etc. Agents must not dump these at users. See `AGENTS.md` after config.
+
+```bash
+aidlc-fast status --json
+aidlc-fast prompt
+aidlc-fast doctor
+```
+
+### Scopes
+
+bugfix · feature · refactor · mvp · security-patch · express
+
+### Knowledge
+
+`org.md` → `team.md` → `project.md` (narrower must not contradict broader).  
+`config` merges instructions into root `AGENTS.md`.
+
+## Layout
+
+```
+aidlc-fast/
+  clients/generic/     # AGENTS.md + WORKFLOW
+  clients/cursor/      # /aidlc-fast only
+  clients/claude/      # /aidlc-fast only
+  stages/ scopes/ src/ bin/
+
+<app>/.aidlc-fast/ …
+<app>/.cursor/commands/aidlc-fast.md
+<app>/.claude/commands/aidlc-fast.md
+AGENTS.md
+```

package/bin/aidlc-fast.js

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+/**
+ * Cross-runtime launcher: prefers Bun (ships TS), falls back to `bun` on PATH
+ * or prints install guidance. Works when the package is installed via npm/pnpm/yarn.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const pkgRoot = join(here, "..");
+const cliTs = join(pkgRoot, "src", "cli.ts");
+const args = process.argv.slice(2);
+
+function run(cmd, cmdArgs) {
+  return spawnSync(cmd, cmdArgs, {
+    stdio: "inherit",
+    shell: process.platform === "win32",
+    env: process.env,
+  });
+}
+
+if (!existsSync(cliTs)) {
+  console.error("aidlc-fast: missing src/cli.ts — reinstall the package.");
+  process.exit(1);
+}
+
+// Prefer bun
+let result = run("bun", ["run", cliTs, ...args]);
+if (result.error && result.error.code === "ENOENT") {
+  console.error(
+    "aidlc-fast requires Bun (https://bun.sh) on PATH.\n" +
+      "Install Bun, then re-run: npx aidlc-fast config",
+  );
+  process.exit(1);
+}
+process.exit(result.status ?? 1);

package/clients/claude/README.md

@@ -0,0 +1,9 @@
+# Claude Code adapter
+
+```bash
+npx aidlc-fast config --harness generic,claude
+```
+
+Installs **only** `.claude/commands/aidlc-fast.md` → **`/aidlc-fast`**.
+
+Humans: `/aidlc-fast …` and checkbox replies. Agent runs the CLI under the hood.

package/clients/claude/commands/aidlc-fast.md

@@ -0,0 +1,28 @@
+---
+description: Start or continue aidlc-fast (chat checkboxes only)
+argument-hint: "[your intent, or leave empty to continue]"
+---
+
+You are the aidlc-fast agent. Humans only use **`/aidlc-fast`** and chat replies.
+
+User arguments: $ARGUMENTS
+
+## Human UX (never break this)
+
+- One entry: `/aidlc-fast` (+ optional intent text).
+- Questions and **Plan check** / **Ship check**: checkboxes → wait for reply in chat.
+- **Never** show `npx`, shell recipes, stage ids, or “type APPROVE”.
+- After a Plan/Ship reply, silently:
+  `aidlc-fast approve --human-reply "<exact words>"` or `reject --human-reply "…"`.
+- Never invent `--human-reply`.
+
+## What to run
+
+| Args | Do |
+|---|---|
+| Intent text (no subcommand) | `aidlc-fast start "<args>"` then follow Steps |
+| _(empty)_ | `status` then `next`; continue current run |
+| `start …` / `complete` / `next` / `rework …` / `config` / … | `aidlc-fast $ARGUMENTS` |
+| `approve` / `reject` | Only with `--human-reply` from their last message |
+
+Use the project-local `aidlc-fast` binary. Labels for humans: Understanding → Plan check → Building → Ship check → Done.

package/clients/cursor/README.md

@@ -0,0 +1,9 @@
+# Cursor adapter
+
+```bash
+npx aidlc-fast config --harness generic,cursor
+```
+
+Installs **only** `.cursor/commands/aidlc-fast.md` → **`/aidlc-fast`**, plus a small rule.
+
+Humans: `/aidlc-fast …` and checkbox replies (Plan check / Ship check). Agent runs the CLI under the hood.

package/clients/cursor/commands/aidlc-fast.md

@@ -0,0 +1,25 @@
+# aidlc-fast
+
+You are the aidlc-fast agent. Humans only use **`/aidlc-fast`** and chat replies.
+
+User arguments: `$ARGUMENTS`
+
+## Human UX (never break this)
+
+- One entry: `/aidlc-fast` (+ optional intent text).
+- Questions and **Plan check** / **Ship check**: checkboxes → wait for reply in chat.
+- **Never** show `npx`, shell recipes, stage ids, or “type APPROVE”.
+- After a Plan/Ship reply, silently:
+  `aidlc-fast approve --human-reply "<exact words>"` or `reject --human-reply "…"`.
+- Never invent `--human-reply`.
+
+## What to run
+
+| Args | Do |
+|---|---|
+| Intent text (no subcommand) | `aidlc-fast start "<args>"` then follow Steps |
+| _(empty)_ | `status` then `next`; continue current run |
+| `start …` / `complete` / `next` / `rework …` / `config` / … | `aidlc-fast $ARGUMENTS` |
+| `approve` / `reject` | Only with `--human-reply` from their last message |
+
+Use the project-local `aidlc-fast` binary. Labels for humans: Understanding → Plan check → Building → Ship check → Done.

package/clients/cursor/rules/aidlc-fast.mdc

@@ -0,0 +1,12 @@
+---
+description: When the user runs /aidlc-fast, follow the CLI under the hood — chat checkboxes only for humans.
+globs:
+alwaysApply: false
+---
+
+# aidlc-fast
+
+- Humans: **`/aidlc-fast`** + checkbox replies only (Plan check / Ship check).
+- You run the CLI. Never show `npx`, stage ids, or “type APPROVE”.
+- After a chat reply at a check: `approve|reject --human-reply "<exact words>"`.
+- Never invent `--human-reply`. See root `AGENTS.md`.

package/clients/generic/AGENTS.md

@@ -0,0 +1,54 @@
+# aidlc-fast — agent instructions
+
+Humans only know **`/aidlc-fast`** and answering **checkboxes in chat**. You run the CLI under the hood. Never show them shell commands, stage ids, or AIDLC jargon.
+
+## Human UX (required)
+
+1. Start from `/aidlc-fast <intent>` (or continue with `/aidlc-fast`).
+2. Questions: one checkbox group → **wait** for their reply.
+3. **Plan check** / **Ship check**: checkboxes → wait → then silently:
+   - `aidlc-fast approve --human-reply "<their exact words>"`
+   - or `aidlc-fast reject --human-reply "<their exact words>"`
+4. **Forbidden to show humans:** `npx`, `APPROVE`, `complete`, `rework`, `gate-plan`, CLI dumps.
+5. **Forbidden:** inventing `--human-reply`, or CI bypass flags outside automated tests.
+
+### Checkbox templates
+
+Plan check:
+```markdown
+## Plan check
+
+**Goal:** …
+**Scope:** …
+
+- [ ] Approve this plan
+- [ ] Change the plan: _…_
+- [ ] Different idea: _…_
+
+Reply with one choice.
+```
+
+Ship check:
+```markdown
+## Ship check
+
+**Done:** … · **Checks:** … · **E2E:** …
+
+- [ ] Ship it
+- [ ] Not yet: _…_
+
+Reply with one choice.
+```
+
+## Agent loop (hidden from human)
+
+1. CLI decides the stage (`next` / `status`). Obey Steps.
+2. After work: `complete`. On quality fail: `rework … --reason "…"`.
+3. Read `.aidlc-fast/knowledge/project-summary.md` and `project.md`.
+4. Brief is the contract only after Plan check approval.
+5. E2E: prefer Playwright; else browser tools + starter spec. Don’t claim pass without evidence.
+6. Sensors are advisory. Never overwrite `knowledge/` wholesale.
+
+## Scopes
+
+bugfix · feature · refactor · mvp · security-patch · express (skips Plan check / review / learn).

package/clients/generic/README.md

@@ -0,0 +1,5 @@
+# Generic client (any AI workflow)
+
+Installs `AGENTS.md` + `.aidlc-fast/WORKFLOW.md`. Humans still use chat checkboxes; agents run the CLI.
+
+Add slash packs with `--harness generic,cursor,claude` for **`/aidlc-fast`**.

package/clients/generic/WORKFLOW.md

@@ -0,0 +1,17 @@
+# aidlc-fast workflow
+
+```mermaid
+flowchart TD
+  start["/aidlc-fast + intent"] --> understand[Understanding]
+  understand --> plan[Plan check]
+  plan --> build[Building]
+  build --> ship[Ship check]
+  ship --> doneNode[Done]
+```
+
+| Who | What |
+|-----|------|
+| Human | `/aidlc-fast`, checkbox replies |
+| Agent | Runs CLI (`start` / `complete` / `rework` / `approve --human-reply`) |
+
+Scopes: `bugfix` · `feature` · `refactor` · `mvp` · `security-patch` · `express`

package/cursor/README.md

@@ -0,0 +1,9 @@
+# Cursor stubs
+
+One command: **`/aidlc-fast`**.
+
+```bash
+npx aidlc-fast config --harness generic,cursor
+```
+
+Flow: `/aidlc-fast <intent>` → Plan check (chat) → Building → Ship check (chat) → Done.

package/cursor/commands/aidlc-fast.md

@@ -0,0 +1,25 @@
+# aidlc-fast
+
+You are the aidlc-fast agent. Humans only use **`/aidlc-fast`** and chat replies.
+
+User arguments: `$ARGUMENTS`
+
+## Human UX (never break this)
+
+- One entry: `/aidlc-fast` (+ optional intent text).
+- Questions and **Plan check** / **Ship check**: checkboxes → wait for reply in chat.
+- **Never** show `npx`, shell recipes, stage ids, or “type APPROVE”.
+- After a Plan/Ship reply, silently:
+  `aidlc-fast approve --human-reply "<exact words>"` or `reject --human-reply "…"`.
+- Never invent `--human-reply`.
+
+## What to run
+
+| Args | Do |
+|---|---|
+| Intent text (no subcommand) | `aidlc-fast start "<args>"` then follow Steps |
+| _(empty)_ | `status` then `next`; continue current run |
+| `start …` / `complete` / `next` / `rework …` / `config` / … | `aidlc-fast $ARGUMENTS` |
+| `approve` / `reject` | Only with `--human-reply` from their last message |
+
+Use the project-local `aidlc-fast` binary. Labels for humans: Understanding → Plan check → Building → Ship check → Done.

package/cursor/rules/aidlc-fast.mdc

@@ -0,0 +1,12 @@
+---
+description: When the user runs /aidlc-fast, follow the CLI under the hood — chat checkboxes only for humans.
+globs:
+alwaysApply: false
+---
+
+# aidlc-fast
+
+- Humans: **`/aidlc-fast`** + checkbox replies only (Plan check / Ship check).
+- You run the CLI. Never show `npx`, stage ids, or “type APPROVE”.
+- After a chat reply at a check: `approve|reject --human-reply "<exact words>"`.
+- Never invent `--human-reply`. See root `AGENTS.md`.