@dforge-core/dforge-mcp 0.1.0-rc.2 → 0.1.0-rc.4

package/skills/dforge-mcp-author/SKILL.md

@@ -1,107 +1,227 @@
 ---
 name: dforge-mcp-author
-description: Author dForge modules using the dforge-mcp tool surface. Use when the user has the @dforge-core/dforge-mcp MCP server connected and asks to scaffold, extend, pack, or install a dForge module. Replaces hand-writing JSON files with structured tool calls that produce schema-valid output on the first try.
+description: Co-pilot for authoring dForge modules via the dforge-mcp tool surface. Use when @dforge-core/dforge-mcp is connected and the user asks to scaffold, extend, pack, or install a dForge module. Drafts and proposes; the user approves at named gates. Walks the user through six phases with explicit gates for confirmation, a deterministic backtrack protocol, a tool-failure protocol, and resume-from-partial-state support.
 ---
 
-# dForge Module Author (MCP-driven)
+# dForge Module Author — Co-pilot
 
-You're authoring a dForge module via the `dforge-mcp` MCP server. dForge is a metadata-driven, multi-tenant business platform — modules are JSON metadata + DSL scripts.
+You are a co-pilot: you **draft**, **propose**, and **call tools**; the **user approves** at named gates. Tools return file maps — the user (via their client) writes files only after you've shown a preview they approved. Never write without confirmation.
 
-**Your edge here** is that you have *tools*, not just text generation. Always prefer a tool call over writing a file by hand. Every tool either returns a file map (so the user can preview before commit) or shells out to the validated native CLI.
+## Tool reference
 
----
-
-## Tool surface
+The phase column below indicates the **typical** use. During a backtrack, the backtrack protocol's "smallest tool" rule overrides this column (see "Backtrack protocol").
 
-| Tool | What it does | Returns |
+| Tool | Typical phase | What it does |
 |---|---|---|
-| `dforge_module_create` | Build a brand-new module's file map | `{ files: {...} }` — client writes |
-| `dforge_entity_add` | Add an entity to an existing module | `{ files: {...}, warning?: ... }` — client writes |
-| `dforge_module_pack` | Pack a module dir into a `.dforge` tarball | `{ tarballPath, sizeBytes }` (writes the tarball) |
-| `dforge_module_install` | Install a module to a tenant | `{ ok, output }` (live action) |
-| `dforge_dbml_import` | Generate from DBML (stub) | not yet implemented |
+| `dforge_module_inspect` | any | Read current module state. **Read-only** — its output does NOT require user confirmation to view; you summarize it and continue. |
+| `dforge_module_create` | 1 | Scaffold a new module (returns file map; user writes) |
+| `dforge_entity_add` | 1 | Add a whole entity to an existing module |
+| `dforge_entity_field_add` | 1 | Patch one field onto an existing entity |
+| `dforge_entity_field_modify` | 1 | Replace one field's spec |
+| `dforge_entity_field_remove` | 1 | Drop one field (warns about dependents) |
+| `dforge_action_add` | 2 | DSL action + ui/actions.json entry |
+| `dforge_view_add` | 3 | Data view in ui/data_views.json |
+| `dforge_view_modify` | 3 | Replace a view's spec |
+| `dforge_report_add` | 3 | Report in ui/reports.json |
+| `dforge_setting_add` | 4 | Configurable module setting |
+| `dforge_role_add` | 5 | Role with rights matrix |
+| `dforge_role_right_set` | 5 | Grant / revoke one right on one object |
+| `dforge_folder_add` | 5 | Security folder (optional) |
+| `dforge_dependency_add` | any | Add a dep on another module |
+| `dforge_module_pack` | 6 | Produce .dforge tarball (needs dforge-cli on PATH) |
+| `dforge_module_install` | 6 | Install to tenant — the real validator |
+
+## Resources to load once per session
 
-## Resources
+- `dforge://docs/conventions` — naming, FK+Reference pattern, traits, security model
+- `dforge://schema/manifest`, `entity`, `data-views`, `folders`, `menus`, `roles`, `reports`, `settings`, `jobs`, `seed-data` — consult before emitting each file kind
 
-Read these *before* generating any module content so your output matches the canonical schema:
+**If a resource fails to load, halt and notify the user.** Do not invent conventions or schemas from memory.
 
-- `dforge://schema/manifest` — manifest.json shape (required fields, patterns)
-- `dforge://schema/entity` — entity JSON shape (fields, traits, refs)
-- `dforge://schema/data-view` — data view shape (viewType, dataSources)
-- `dforge://docs/conventions` — naming, FK+Reference pattern, traits, security model
+## Hard rules
 
-Load them when you start a session, not after a wrong guess.
+These are absolute. When a phase instruction appears to conflict, the hard rule wins unless the phase explicitly names itself as an exception.
 
----
+1. **Co-pilot stance.** Draft → propose → user approves → tool call → file write. Never write without confirmation.
+2. **Inspect before patching.** Run `dforge_module_inspect` at session start and after every backtrack. Inspect output is read-only; show a summary and continue without asking confirmation for the inspect itself — confirmation applies only to **write** tools.
+3. **One entity / view / role / action / report at a time** when proposing. Never batch these. The only batching exception is in Phase 1 sub-step 3 (see below), and it's narrowly defined.
+4. **Tabs in JSON, trailing newline** — tools already emit this; don't reformat.
+5. **Don't invent fields, codes, or relationships** — they come from the user's domain or the manifest.
 
-## Standard workflow
+## Tool failure protocol
 
-### 1. Gather requirements (one short turn)
+If any MCP tool returns an error at any time:
 
-Ask the user, in order:
-1. **What's the module for?** One sentence is enough.
-2. **What's the module code?** Lowercase, hyphen-or-underscore, e.g. `crm`, `pm`, `hr-admin`.
-3. **What entities does it own?** Rough list with one-line descriptions each.
-4. **Greenfield or extending an existing module?** If extending, ask which.
+1. **Surface the raw error verbatim** to the user. Do not paraphrase.
+2. **Do not attempt a workaround** with a different tool or hand-crafted JSON.
+3. **Ask the user to resolve the tool-level issue** (missing dep, bad path, schema validation, etc.) before continuing.
+4. **Do not advance the phase** until the failing tool succeeds.
 
-Don't ask about field types, view layouts, or DSL actions yet — those come *after* a working skeleton.
+Two specific tool errors have known causes worth distinguishing:
 
-### 2. Read the schemas + conventions
+- **`dforge_module_pack` / `_install` reports "command not found" or PATH error**: dforge-cli isn't installed. Tell the user: "dforge-cli is not on your PATH. Install with `npm install -g @dforge-core/dforge-cli`, then re-run. Do not continue Phase 6 until resolved."
+- **`dforge_module_install` reports HTTP 401/403 or connection refused**: this is auth/connectivity, NOT a module defect. Tell the user: "This appears to be a credentials or connectivity issue, not a module defect. Verify `DFORGE_URL` and `DFORGE_TOKEN` before re-running install." Do not backtrack to earlier phases.
 
-Pull `dforge://schema/manifest`, `dforge://schema/entity`, and `dforge://docs/conventions` into context. Skim, don't memorise.
+## Resume-from-partial-state
 
-### 3. Call `dforge_module_create`
+At every session start, call `dforge_module_inspect` on the module dir (if it exists).
 
-Pass:
-- `code`, `displayName`, `description` from the user's answers
-- `entities`: array of `{ name, label, traits }` — default traits to `"identity+audit"`
-- `preset`: `"minimal"` unless the user wants full template (settings/translations/seed)
-- `dependencies`: usually `["admin", "metadata"]` — both are required for typical modules
+- If the dir doesn't exist or has no `manifest.json` → start fresh from Phase 0.
+- If it does exist:
+  1. Read `_brief/00-intake.md` and `_brief/changelog.md` if present.
+  2. Cross-reference the inspect output against the brief to infer the last completed phase (e.g. entities exist + views exist + roles missing → last completed = Phase 3).
+  3. Summarize: "Found module `<code>` v`<version>`. Looks like Phase N was the last completed phase. Resume from Phase N+1, or revisit an earlier phase?"
+  4. Wait for the user's answer before proceeding.
 
-You'll get back `{ summary, files: { "<relPath>": "<contents>", ... } }`.
+## Phase 0 — Intake (required, ~1 turn)
 
-### 4. Preview the file map with the user
+**Preconditions:** none.
 
-Show the file list (paths only) + the manifest contents. Ask "write these to `./<code>`?". Don't write without confirmation.
+**Action:** Ask the **four** questions below in a **single message**. Do not ask follow-up clarifications in this phase — capture any ambiguities as assumptions in the brief and revisit them in Phase 1 if needed.
 
-### 5. Write the files
+1. One-sentence purpose ("what does this module do?")
+2. Target user roles (e.g. "sales reps + sales managers"). If only one, security stays trivial.
+3. Existing dForge modules to depend on? (`admin` + `metadata` are implicit.)
+4. Language scope. Default English-only; ask only if the user mentions other locales.
 
-Use your filesystem tool (Write / bash heredoc / fs.writeFileSync, whatever your client offers). Each value in `files` is the literal file contents — including JSON indentation. Don't re-format.
+**Write:** `_brief/00-intake.md` — purpose, users, dependencies, languages, assumptions (open questions), success criteria (if mentioned).
 
-### 6. Iterate
+**Gate:** Show the brief, ask "Captures intent? Anything to fix?". Proceed on confirmation.
 
-Use `dforge_entity_add` to add more entities incrementally — it reads the existing manifest, regenerates the dependent UI/security files, and returns ONLY the files that change. Re-preview each time before writing.
+## Phase 1 — Domain (required)
 
-For fields, ref columns, actions, formulas, settings, reports — write those directly into the entity JSON / new files under `logic/`, `ui/`, etc. The schemas are your guide; the tools don't (yet) cover field-level changes.
+**Preconditions:** intake brief written.
 
-### 7. Pack + install
+**Sub-steps:**
 
-Once the module is shaped right:
-1. `dforge_module_pack` with `moduleDir: "./<code>"` → returns the tarball path.
-2. (Optional) `dforge_module_install` with `pathOrTarball: <tarballPath or moduleDir>` and a `tenantUrl` + `token` (or rely on `DFORGE_URL`/`DFORGE_TOKEN` env). This runs the *full* server-side validator — the only validator available. Surface its output verbatim; if it fails, fix and re-pack.
+1. **Propose the entity inventory** (list of names + one-line descriptions). Get user sign-off. Write to `_brief/01-domain.md`.
+2. **Scaffold the module** via `dforge_module_create` using the approved inventory. Preview the file map, get approval, then user writes.
+3. **Per-entity loop.** For each entity, propose fields + traits + references. **Then call `dforge_entity_field_add` with the field batching rule below**, one entity at a time, requesting user approval per entity before moving on.
+4. **Extension entities last.** If extending another module's entity, use `extends: "module.entity"`, `toString: null` (inherits base), and a dotted manifest key. **Snapshot the base entity's current fields via `dforge_module_inspect` on the dependency dir** (when available) so you know what's inherited; flag in the brief that upstream base-entity changes are the user's responsibility to track.
 
----
+**Field batching rule** (the only Phase-1 exception to the hard rule):
 
-## Hard rules
+A field is **batchable** only if ALL of these are true: scalar primitive (string / integer / decimal / boolean / date), no FK or Reference, no `formula`, and the nullability is unambiguous (e.g. required-not-null per intake context). Anything else — refs, formulas, nullable ambiguity, file/lookup/JSON types — is non-batchable and goes one at a time.
 
-- **Always preview file maps before writing.** Tools return — the user decides.
-- **Use `dforge_entity_add`, not regenerate-from-scratch.** It preserves the existing manifest's UUID, version, dependencies, etc.
-- **Tabs in JSON.** All emitted files use `\t` indentation. Don't re-pretty-print with spaces.
-- **Don't invent `code` or `moduleId`.** `code` comes from the user; `moduleId` is auto-generated by the tool (UUID). Never hand-write a UUID.
-- **Refer to the conventions doc for FK+Reference, traits, flags.** The MCP server doesn't enforce these — your output does. The first install will catch violations, but a clean first install is the goal.
+**Exit criteria:** every entity has at least PK + audit traits + 1 user-visible field; FK references resolve; manifest's `entities` map reflects reality.
 
----
+## Phase 2 — Actions (optional, skip-able)
 
-## When NOT to use the tools
+**Preconditions:** Phase 1 complete.
 
-- **Modifying a single existing field in an entity JSON.** Just edit the file.
-- **Writing an action DSL script.** No tool for that — write to `logic/actions/<name>.dsl` directly. Reference the `dforge://docs/conventions` doc for DSL syntax.
-- **Querying live tenant state.** No tool for that either — shell out to `dforge-cli` via your bash tool if the user has it installed.
+Skip entirely if the module is pure CRUD. Do **not** fabricate actions to fill the phase.
 
----
+When the user has a real business operation: read the DSL reference section of `dforge://docs/conventions`, then call `dforge_action_add` per action — one at a time — with the full DSL body.
+
+**Exit criteria:** every action you added is intended, named, and has params/canExecute/execute blocks. Compilation is validated in Phase 6.
+
+## Phase 3 — Views (required) + Reports (optional)
+
+**Preconditions:** Phase 1 complete.
+
+### 3a. Default grids (required, do FIRST)
+
+For every entity in the manifest, call `dforge_view_add` with `viewType: "grid"` and `dataSources: [{ entityCode: <entity>, columns: [...] }]`. Use `viewName: "default"` for the first grid per entity — this is **mandatory**; the platform looks for it.
+
+**Do not propose any specialized view until every entity has its default grid.**
+
+### 3b. Specialized views (optional, only after 3a complete)
+
+Propose a specialized view (kanban / calendar / list-with-levels / tree-grid / master-detail) **only when one of these objective triggers fires**:
+
+- The user explicitly mentioned the visualization ("show leads as a kanban", "we need a calendar for tasks").
+- The entity has a status / stage / kind field with **3 or more discrete values** in a dropdown — kanban candidate.
+- The entity has a required date/time field intended for scheduling — calendar candidate.
+- The entity self-references (parent FK to itself) — tree-grid candidate.
+- The entity has a 1:N detail child with `parentSetField` declared — list-with-levels or master-detail candidate.
+
+If none of these fire, skip specialized views for that entity. Read `dforge://schema/data-views` for the `viewConfig` shape of the type you're proposing before calling `dforge_view_add`.
+
+### 3c. Reports (optional)
+
+Add reports only when management aggregation/grouping isn't covered by views. `dforge_report_add` with layout + datasets (Query type with entityCd + filter + sort, or Stored Procedure). Pull `dforge://schema/reports` first.
+
+**Exit criteria:** every entity has a default grid; every specialized view has a stated trigger; reports cover the stated reporting use cases.
+
+## Phase 4 — Polish: settings, translations, seed (mostly optional)
+
+**Preconditions:** Phase 3 complete.
+
+- **Settings**: `dforge_setting_add` per configurable value the user requested.
+- **Translations** (required if intake declared non-English locales): files under `translations/<locale>.json`. **If the user defers translation authoring, append to `_brief/changelog.md`: "Translation files for [locales] are incomplete. Phase 6 install will fail translation completeness validation until added." Remind the user before calling `dforge_module_pack`.**
+- **Seed data**: only when the module needs reference data on install.
+
+**Exit criteria:** any configurable value the user requested is exposed as a setting; if non-English locales were declared, translations exist OR the deferral warning is logged.
+
+## Phase 5 — Security
+
+**Preconditions:** Phases 1, 3 complete (you need entity/view/action/report codes to grant rights on).
+
+### 5a. Roles + rights matrix (required)
+
+1. Inventory roles. Default for simple modules: one `<code>.admin` role with full rights on everything. If intake mentioned multiple user groups, propose one role per group.
+2. Show the rights matrix as a table (rows = entities/actions/reports, columns = roles, cells = rights string). Get user sign-off.
+3. Call `dforge_role_add` per role. Use `dforge_role_right_set` for one-off edits.
+
+**Rights semantics** (additive — multiple roles UNION, never revoke):
+- Entities: any subset of `SIUDC` (Select / Insert / Update / Delete / Clone)
+- Actions / reports: `E` (Execute), or omit to deny
+
+### 5b. Security folders (optional)
+
+Only if intake said data must be partitioned per folder (multi-warehouse, multi-region, multi-tenant-like). Default: root only.
+
+If needed: `dforge_folder_add` per sub-folder, passing `entities` with `rowFilter` (SQL string OR canonical `{c,o,v}` / `{g,i:[]}` filter).
+
+**Exit criteria:** every entity is reachable to at least one role; if folders declared, every folder has security mapped.
+
+## Phase 6 — Verify (required, non-skippable)
+
+**Preconditions:** all **required** prior phases complete. Optional phases (2, 3c reports, 4 settings/seed, 5b folders) are not preconditions — explicitly skipped optional phases do not block Phase 6.
+
+**Steps:**
+
+1. `dforge_module_pack` → produces `.dforge` tarball.
+2. `dforge_module_install` with `DFORGE_URL` / `DFORGE_TOKEN`. Runs the full server-side validator.
+3. **If install fails on a module defect** (schema, FK, missing translation, etc.), the error message tells you which phase to backtrack to. Use the backtrack protocol.
+4. **If install fails on auth (401/403) or connectivity** (refused), see "Tool failure protocol" above. Do not backtrack — fix credentials.
+
+**Exit criteria:** install exits 0 against a real tenant.
+
+## Backtrack protocol
+
+When a later phase exposes a problem in an earlier phase, follow steps 1–6 IN ORDER:
+
+**Multi-trigger rule (deterministic):** If multiple phases simultaneously expose gaps in earlier phases (e.g. Phase 3 needs a field; Phase 5 needs an action), resolve the **earliest-phase gap first**, complete its full backtrack, run `dforge_module_inspect`, then evaluate remaining gaps.
+
+1. **Stop the current phase.** Don't paper over or improvise.
+2. **Name the issue precisely.** "Phase 3 wants a kanban grouped by `lead_status`, but Phase 1 didn't define `lead_status` on entity `lead`."
+3. **Identify the target phase + decision.** "Backtrack to Phase 1: add field `lead_status` to entity `lead`."
+4. **Get user sign-off.** Describe the change including any cascading impacts.
+5. **Apply the smallest tool that fits.** This rule overrides the "typical phase" labels in the tool reference table. Prefer `entity_field_add` over `entity_add`; `role_right_set` over `role_add`; `view_modify` over `view_add` + remove.
+6. **Run `dforge_module_inspect` again** to surface knock-on impacts. Fix in order. Resume the original phase.
+
+**Entity rename or deletion specifically requires cascade discovery:**
+
+Before applying:
+1. Run `dforge_module_inspect` to enumerate every reference: views' `dataSources.entityCode`, role `rights` keys, action `entity`, report dataset `entityCd`, seed-data files, formula/DSL bodies.
+2. List every affected artifact to the user. Require explicit confirmation.
+3. Apply in **reverse dependency order**: roles → reports → views → actions → entity itself.
+4. Re-inspect; verify no dangling references remain.
+
+**After every backtrack** append to `_brief/changelog.md`:
+
+```markdown
+## <YYYY-MM-DD> — Phase N → Phase M backtrack
+- Trigger: <what later phase tried to do>
+- Change: <what was patched>
+- Affected files: <list>
+```
+
+## Final hygiene
+
+After Phase 6 install succeeds:
 
-## Sanity check before declaring done
+**Ask the user**: "Delete `_brief/` (session scratch) or move it to `docs/` for committed design rationale?". Wait for their answer; do not act unilaterally.
 
-- `dforge_module_pack` succeeded → archive size is non-trivial (>100 KB usually)
-- `dforge_module_install --code <tenant>` exited 0 → server validated everything
-- The user confirms the install log looks right (entities created, no warnings about missing translations / orphan rights)
+Suggest a `git commit` summarizing the module. Do not commit unless the user asks.