@akanjs/cli 2.3.9-rc.1 → 2.3.9-rc.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/cli",
-  "version": "2.3.9-rc.1",
+  "version": "2.3.9-rc.3",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -34,7 +34,7 @@
     "@langchain/openai": "^1.4.6",
     "@tailwindcss/node": "^4.3.0",
     "@trapezedev/project": "^7.1.4",
-    "akanjs": "2.3.9-rc.1",
+    "akanjs": "2.3.9-rc.3",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "daisyui": "5.5.23",

package/templates/workspaceRoot/.cursor/rules/akan.mdc.template

@@ -17,7 +17,14 @@ alwaysApply: true
   `lib/useServer.ts`.
 - Prefer Akan MCP workflows before direct source edits: use `akan mcp --mode plan` for workflow discovery and
   planning, then `akan mcp --mode apply` only for allowlisted apply, validation, and repair tools.
+- If `plan_workflow` returns `planPath` or `next.tool=apply_workflow`, call `apply_workflow({ planPath })` before
+  editing source files directly.
+- After `apply_workflow`, run `run_validation` with `validationTarget` when present; otherwise use `applyReportPath`.
 - Direct source edits are denied when an allowlisted Akan workflow or repair tool can perform the change.
+- Direct edits are fallback only after `list_workflows`/`explain_workflow` show no matching workflow, or after
+  `apply_workflow` reports unsupported/no-op/failed diagnostics that require manual action.
+- For compound requests, split the request into workflows and apply each `planPath` in order, such as `create-module`
+  followed by `add-field`.
 - If generated output is stale or broken, update the owning source file and run `akan repair generated` or
   `akan sync <app-or-lib>` instead of patching generated files.
 - For new domain behavior, inspect sibling `constant`, `dictionary`, `signal`, `document`, `service`, `store`, and UI

package/templates/workspaceRoot/AGENTS.md.template

@@ -63,17 +63,19 @@ Use the local module shape before adding a new abstraction.
 1. Read the nearby module and convention before creating files. If `*.abstract.md` exists, read it first.
 2. Put new files in the established Akan location instead of adding parallel architecture.
 3. Prefer Akan MCP workflows before direct source edits. Start with `akan mcp --mode plan` for `list_workflows`, `explain_workflow`, and `plan_workflow`.
-4. Use `akan mcp --mode apply` only for allowlisted `apply_workflow`, `run_validation`, and repair tools.
-5. Direct source edits are denied when an allowlisted Akan workflow or repair tool can perform the change.
-6. If no workflow exists, edit only the owning source files and never patch generated files directly.
-7. Keep page and layout files server-oriented: route-level `usePage`, headers, static layout, and `akanjs/ui` `Tab` composition belong there.
-8. Put interactive loading, submit/import actions, local form state, and `router.push` in client `Util`, `Template`, or `Zone` components.
-9. Prefer `Tab` for static mode selection instead of extra `useState`; render one focused client component inside each `Tab.Panel`.
-10. Keep server-only logic out of client surfaces and client-only code out of server imports.
-11. Treat `AKAN_PUBLIC_*` env vars as public. Never put secrets in them.
-12. Add or update tests when behavior, contracts, or CLI output changes.
-13. Update `*.abstract.md` when business invariants, workflows, or public behavior change.
-14. Run the smallest relevant verification command after changes.
+4. If `plan_workflow` returns `planPath` or `next.tool=apply_workflow`, call `apply_workflow({ planPath })` before direct source edits.
+5. Use `akan mcp --mode apply` only for allowlisted `apply_workflow`, `run_validation`, and repair tools.
+6. After `apply_workflow`, run `run_validation` with `validationTarget` when present; otherwise use `applyReportPath`.
+7. Direct source edits are denied when an allowlisted Akan workflow or repair tool can perform the change.
+8. If no workflow exists, or apply reports unsupported/no-op/failed diagnostics that require manual action, edit only the owning source files and never patch generated files directly.
+9. Keep page and layout files server-oriented: route-level `usePage`, headers, static layout, and `akanjs/ui` `Tab` composition belong there.
+10. Put interactive loading, submit/import actions, local form state, and `router.push` in client `Util`, `Template`, or `Zone` components.
+11. Prefer `Tab` for static mode selection instead of extra `useState`; render one focused client component inside each `Tab.Panel`.
+12. Keep server-only logic out of client surfaces and client-only code out of server imports.
+13. Treat `AKAN_PUBLIC_*` env vars as public. Never put secrets in them.
+14. Add or update tests when behavior, contracts, or CLI output changes.
+15. Update `*.abstract.md` when business invariants, workflows, or public behavior change.
+16. Run the smallest relevant verification command after changes.
 
 ## Common Commands
 
@@ -134,15 +136,23 @@ Almost every Akan.js change follows this pattern. **Missing sync or repair is th
    # use list_workflows, explain_workflow, and plan_workflow
    ```
 
-2. **Apply or edit source** — Use allowlisted apply/repair tools when available. If no workflow exists, edit only
-   owning source files such as `task.constant.ts`, `task.dictionary.ts`, `Task.Template.tsx`, or `Task.Unit.tsx`.
-   Never edit generated files.
+2. **Apply the plan** — If `plan_workflow` returns `planPath` or `next.tool=apply_workflow`, call
+   `apply_workflow({ planPath })`. Do not copy the workflow plan into direct source edits.
    ```
    akan mcp --mode apply
    # use apply_workflow, run_validation, repair_generated, repair_imports, or repair_module_shape
    ```
 
-3. **Sync or repair** — Regenerate barrel files so Akan discovers your change. This regenerates:
+   Direct edits are fallback only: use them after `list_workflows`/`explain_workflow` confirm no matching workflow, or
+   after apply reports unsupported/no-op/failed diagnostics that require manual action. Keep fallback edits to owning
+   source files such as `task.constant.ts`, `task.dictionary.ts`, `Task.Template.tsx`, or `Task.Unit.tsx`.
+
+3. **Validate the apply report** — Use the apply report artifact, not the original raw plan, when it is available.
+   ```
+   # run_validation with validationTarget first; otherwise use applyReportPath
+   ```
+
+4. **Sync or repair** — Regenerate barrel files so Akan discovers your change. This regenerates:
    `cnst.ts`, `db.ts`, `srv.ts`, `sig.ts`, `st.ts`, `dict.ts`, `useClient.ts`, `useServer.ts`,
    `ui/index.ts`, `webkit/index.ts`, `srvkit/index.ts`, `common/index.ts`, and all module `index.ts` files.
    ```
@@ -152,7 +162,7 @@ Almost every Akan.js change follows this pattern. **Missing sync or repair is th
    **CRITICAL**: Sync after EVERY file add, delete, or rename. Without sync, other modules cannot
    `import * as cnst from "../cnst"` and find your new model.
 
-4. **Check** — Verify your change compiles and lints.
+5. **Check** — Verify your change compiles and lints.
    ```
    akan start <%= appName %>   # dev server with live feedback (preferred)
    akan lint <%= appName %>    # quick lint-only check
@@ -163,6 +173,10 @@ Almost every Akan.js change follows this pattern. **Missing sync or repair is th
    - `akan build <%= appName %>` — full rebuild catches type errors sync may miss
    - Re-run `akan create-module <name> --app <%= appName %>` if the scaffold is corrupted
 
+For compound natural-language requests, split the request into workflows and apply each artifact in order. For example,
+"create a project module and add a budget field" should run `create-module` plan/apply first, then `add-field`
+plan/apply, then validation/doctor on the returned `validationTarget`.
+
 ## Quick Decision Matrix — "Where do I put this code?"
 
 | You want to... | Create in... | Run after... |

package/templates/workspaceRoot/package.json.template

@@ -8,8 +8,25 @@
     "lint": "akan lint",
     "typecheck": "akan typecheck",
     "test": "akan test",
-    "setup:agent": "akan agent install all",
-    "build": "akan build"
+    "build": "akan build",
+    "setup:agent": "akan agent install all --force",
+    "agent:setup": "akan agent install all --force",
+    "agent:doctor": "akan doctor --strict --format json",
+    "agent:context": "akan context --format json",
+    "agent:mcp:readonly": "akan mcp-install cursor --mode readonly --force",
+    "agent:mcp:plan": "akan mcp-install cursor --mode plan --force",
+    "agent:mcp:apply": "akan mcp-install cursor --mode apply --force",
+    "agent:workflows": "akan workflow list",
+    "agent:sample:context": "akan context --format markdown --app <%= appName %> --module project",
+    "agent:sample:service": "akan create-service billing <%= appName %> --format json",
+    "agent:sample:module": "akan create-module project <%= appName %> --page=true --format json",
+    "agent:sample:field": "akan add-field --app <%= appName %> --module project --field budget --type Int --default 0 --format json",
+    "agent:sample:status": "akan add-enum-field --app <%= appName %> --module project --field status --values draft,active,archived --default draft --format json",
+    "agent:sample:sync": "akan sync <%= appName %>",
+    "agent:sample:check": "akan doctor --strict --format json",
+    "agent:sample:workflow:explain": "akan workflow explain add-field",
+    "agent:sample:workflow:plan": "akan workflow plan add-field --app <%= appName %> --module task --field priority --type enum --values low,medium,high --default medium --format json --out .akan/workflows/plans/task-priority.json",
+    "agent:sample:workflow:dry-run": "akan workflow apply .akan/workflows/plans/task-priority.json --dry-run --format json"
   },
   "dependencies": {},
   "devDependencies": {},