From 6e8dedeb2fbd89f27f856d2707834cf1275be350 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=B0=8F=E5=A2=A8?= Date: Mon, 25 May 2026 09:54:40 +0000 Subject: [PATCH] docs: move cursor rules to docs/, add project rules to CLAUDE.md Also bump @uncaged/json-cas* to ^0.5.2 --- .cursor/rules/no-dynamic-import.mdc | 28 +------- .cursor/rules/sync-readme.mdc | 68 +------------------ CLAUDE.md | 5 ++ docs/no-dynamic-import.md | 27 ++++++++ docs/sync-readme.md | 67 ++++++++++++++++++ packages/cli-workflow/package.json | 4 +- packages/workflow-agent-builtin/package.json | 2 +- .../workflow-agent-claude-code/package.json | 2 +- packages/workflow-agent-hermes/package.json | 2 +- packages/workflow-agent-kit/package.json | 4 +- packages/workflow-protocol/package.json | 4 +- 11 files changed, 112 insertions(+), 101 deletions(-) create mode 100644 docs/no-dynamic-import.md create mode 100644 docs/sync-readme.md diff --git a/.cursor/rules/no-dynamic-import.mdc b/.cursor/rules/no-dynamic-import.mdc index 45de02a..216f8e6 100644 --- a/.cursor/rules/no-dynamic-import.mdc +++ b/.cursor/rules/no-dynamic-import.mdc @@ -1,27 +1,3 @@ ---- -description: Ban dynamic import() in production code — use static imports instead -globs: packages/*/src/**/*.ts -alwaysApply: true ---- +# No Dynamic Import -# No Dynamic Import in Production Code - -## Rule - -Do NOT use `await import()` or dynamic `import()` expressions in production source code. -Always use static top-level `import` statements. - -## Exception (must include a comment explaining why) - -1. **Bundle loader** — loads user-authored workflow bundles whose paths are only known at runtime - -When suppressing, add a comment directly above: - -```ts -// Dynamic import required: user bundle path resolved at runtime -const mod = await import(bundlePath); -``` - -## Test Files - -Test files (`__tests__/**`) are exempt. +See [docs/no-dynamic-import.md](../../docs/no-dynamic-import.md) for full rules. diff --git a/.cursor/rules/sync-readme.mdc b/.cursor/rules/sync-readme.mdc index e807006..2d207ae 100644 --- a/.cursor/rules/sync-readme.mdc +++ b/.cursor/rules/sync-readme.mdc @@ -1,67 +1,3 @@ -# Sync README +# Sync Readme -When updating README.md files in this monorepo, follow these conventions. - -## Scope - -- Root `README.md` — project overview and navigation hub -- Per-package `packages/*/README.md` — each package self-contained - -## Root README Structure - -The root README should have these sections in order: - -1. **Title and one-liner** — stateless workflow engine driven by single-step CLI -2. **Overview** — 2-3 paragraphs explaining what it does and key concepts -3. **Architecture** — dependency layer diagram (text-based) -4. **Packages** — table with ALL packages from packages/ directory, columns: Package, Description, Type (cli/lib/agent/app) -5. **Quick Start** — install, build, register workflow, start thread, run step -6. **CLI Reference** — brief command list, detailed usage in cli-workflow README -7. **Development** — bun install / build / check / test - -## Per-Package README Structure - -Each package README should have: - -1. **Title** — package name -2. **One-line description** — matching package.json -3. **Overview** — what it does, where it sits in the architecture, dependencies -4. **Installation** — bun add (for libs) or "included as binary" (for cli/agents) -5. **API** (lib packages) — all exports from src/index.ts with type signatures, grouped by category, minimal usage examples -6. **CLI Usage** (cli/agent packages) — command reference with examples -7. **Internal Structure** — brief src/ file organization -8. **Configuration** (if applicable) - -## Execution Steps - -### Step 1: Gather current state -For each package read: -- package.json (name, version, description, dependencies, bin) -- src/index.ts (public API exports) -- Existing README.md (preserve hand-written content worth keeping) - -### Step 2: Update root README -- Ensure ALL packages in packages/ directory are listed in the table -- Update CLI command reference from uwf --help output -- Keep Quick Start examples valid - -### Step 3: Write/update each package README -- Follow the per-package structure -- API section MUST match actual src/index.ts exports — never invent -- For agent packages: document CLI binary name, how it is invoked -- For lib packages: document exported types and functions -- Internal structure: list actual files in src/ - -### Step 4: Verify -- All relative links work -- Package names match package.json -- No references to removed/renamed packages -- bun run build still passes - -## Guidelines - -- Only document what src/index.ts actually exports -- Root README summarizes, package READMEs go into detail -- Verify CLI examples against actual commands -- Preserve existing good prose when updating -- English for all README content +See [docs/sync-readme.md](../../docs/sync-readme.md) for full rules. diff --git a/CLAUDE.md b/CLAUDE.md index 300969f..1255718 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -285,6 +285,11 @@ moderator → agent → extract — one step per invocation, repeat until $ 2. **Register** — `uwf workflow put ` parses YAML, registers output schemas, stores `WorkflowPayload` in CAS 3. **Run** — `uwf thread start` creates a thread, `uwf thread step` executes one cycle per invocation +## Project Rules + +- [docs/sync-readme.md](docs/sync-readme.md) — README sync conventions +- [docs/no-dynamic-import.md](docs/no-dynamic-import.md) — no dynamic import in production code + ## Commit Convention ``` diff --git a/docs/no-dynamic-import.md b/docs/no-dynamic-import.md new file mode 100644 index 0000000..45de02a --- /dev/null +++ b/docs/no-dynamic-import.md @@ -0,0 +1,27 @@ +--- +description: Ban dynamic import() in production code — use static imports instead +globs: packages/*/src/**/*.ts +alwaysApply: true +--- + +# No Dynamic Import in Production Code + +## Rule + +Do NOT use `await import()` or dynamic `import()` expressions in production source code. +Always use static top-level `import` statements. + +## Exception (must include a comment explaining why) + +1. **Bundle loader** — loads user-authored workflow bundles whose paths are only known at runtime + +When suppressing, add a comment directly above: + +```ts +// Dynamic import required: user bundle path resolved at runtime +const mod = await import(bundlePath); +``` + +## Test Files + +Test files (`__tests__/**`) are exempt. diff --git a/docs/sync-readme.md b/docs/sync-readme.md new file mode 100644 index 0000000..e807006 --- /dev/null +++ b/docs/sync-readme.md @@ -0,0 +1,67 @@ +# Sync README + +When updating README.md files in this monorepo, follow these conventions. + +## Scope + +- Root `README.md` — project overview and navigation hub +- Per-package `packages/*/README.md` — each package self-contained + +## Root README Structure + +The root README should have these sections in order: + +1. **Title and one-liner** — stateless workflow engine driven by single-step CLI +2. **Overview** — 2-3 paragraphs explaining what it does and key concepts +3. **Architecture** — dependency layer diagram (text-based) +4. **Packages** — table with ALL packages from packages/ directory, columns: Package, Description, Type (cli/lib/agent/app) +5. **Quick Start** — install, build, register workflow, start thread, run step +6. **CLI Reference** — brief command list, detailed usage in cli-workflow README +7. **Development** — bun install / build / check / test + +## Per-Package README Structure + +Each package README should have: + +1. **Title** — package name +2. **One-line description** — matching package.json +3. **Overview** — what it does, where it sits in the architecture, dependencies +4. **Installation** — bun add (for libs) or "included as binary" (for cli/agents) +5. **API** (lib packages) — all exports from src/index.ts with type signatures, grouped by category, minimal usage examples +6. **CLI Usage** (cli/agent packages) — command reference with examples +7. **Internal Structure** — brief src/ file organization +8. **Configuration** (if applicable) + +## Execution Steps + +### Step 1: Gather current state +For each package read: +- package.json (name, version, description, dependencies, bin) +- src/index.ts (public API exports) +- Existing README.md (preserve hand-written content worth keeping) + +### Step 2: Update root README +- Ensure ALL packages in packages/ directory are listed in the table +- Update CLI command reference from uwf --help output +- Keep Quick Start examples valid + +### Step 3: Write/update each package README +- Follow the per-package structure +- API section MUST match actual src/index.ts exports — never invent +- For agent packages: document CLI binary name, how it is invoked +- For lib packages: document exported types and functions +- Internal structure: list actual files in src/ + +### Step 4: Verify +- All relative links work +- Package names match package.json +- No references to removed/renamed packages +- bun run build still passes + +## Guidelines + +- Only document what src/index.ts actually exports +- Root README summarizes, package READMEs go into detail +- Verify CLI examples against actual commands +- Preserve existing good prose when updating +- English for all README content diff --git a/packages/cli-workflow/package.json b/packages/cli-workflow/package.json index 41e1266..073b3c1 100644 --- a/packages/cli-workflow/package.json +++ b/packages/cli-workflow/package.json @@ -11,8 +11,8 @@ "uwf": "./src/cli.ts" }, "dependencies": { - "@uncaged/json-cas": "^0.4.0", - "@uncaged/json-cas-fs": "^0.4.0", + "@uncaged/json-cas": "^0.5.2", + "@uncaged/json-cas-fs": "^0.5.2", "@uncaged/workflow-agent-kit": "workspace:^", "@uncaged/workflow-moderator": "workspace:^", "@uncaged/workflow-protocol": "workspace:^", diff --git a/packages/workflow-agent-builtin/package.json b/packages/workflow-agent-builtin/package.json index ebc0a4e..ff7b7e0 100644 --- a/packages/workflow-agent-builtin/package.json +++ b/packages/workflow-agent-builtin/package.json @@ -21,7 +21,7 @@ "test": "bun test" }, "dependencies": { - "@uncaged/json-cas": "^0.4.0", + "@uncaged/json-cas": "^0.5.2", "@uncaged/workflow-agent-kit": "workspace:^", "@uncaged/workflow-util": "workspace:^" }, diff --git a/packages/workflow-agent-claude-code/package.json b/packages/workflow-agent-claude-code/package.json index 4a54820..a8917d1 100644 --- a/packages/workflow-agent-claude-code/package.json +++ b/packages/workflow-agent-claude-code/package.json @@ -21,7 +21,7 @@ "test": "bun test" }, "dependencies": { - "@uncaged/json-cas": "^0.4.0", + "@uncaged/json-cas": "^0.5.2", "@uncaged/workflow-agent-kit": "workspace:^", "@uncaged/workflow-util": "workspace:^" }, diff --git a/packages/workflow-agent-hermes/package.json b/packages/workflow-agent-hermes/package.json index d8a1fb3..3028815 100644 --- a/packages/workflow-agent-hermes/package.json +++ b/packages/workflow-agent-hermes/package.json @@ -21,7 +21,7 @@ "test": "bun test" }, "dependencies": { - "@uncaged/json-cas": "^0.4.0", + "@uncaged/json-cas": "^0.5.2", "@uncaged/workflow-agent-kit": "workspace:^", "@uncaged/workflow-protocol": "workspace:^", "@uncaged/workflow-util": "workspace:^" diff --git a/packages/workflow-agent-kit/package.json b/packages/workflow-agent-kit/package.json index 1be9724..355e3ed 100644 --- a/packages/workflow-agent-kit/package.json +++ b/packages/workflow-agent-kit/package.json @@ -18,8 +18,8 @@ "test": "bun test" }, "dependencies": { - "@uncaged/json-cas": "^0.4.0", - "@uncaged/json-cas-fs": "^0.4.0", + "@uncaged/json-cas": "^0.5.2", + "@uncaged/json-cas-fs": "^0.5.2", "@uncaged/workflow-protocol": "workspace:^", "@uncaged/workflow-util": "workspace:^", "dotenv": "^16.6.1", diff --git a/packages/workflow-protocol/package.json b/packages/workflow-protocol/package.json index acf290f..58947e6 100644 --- a/packages/workflow-protocol/package.json +++ b/packages/workflow-protocol/package.json @@ -15,8 +15,8 @@ } }, "dependencies": { - "@uncaged/json-cas": "^0.4.0", - "@uncaged/json-cas-fs": "^0.4.0" + "@uncaged/json-cas": "^0.5.2", + "@uncaged/json-cas-fs": "^0.5.2" }, "devDependencies": { "typescript": "^5.8.3"