@jskit-ai/agent-docs 0.1.2 → 0.1.4

package/skills/jskit-review/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: jskit-review
+description: Review or deslop a JSKIT chunk or whole changeset. Use when the user asks to review, deslop, run a JSKIT best-practices audit, or verify a JSKIT feature, chunk, or whole changeset before sign-off.
+---
+
+# JSKIT Review
+
+Use this skill for independent review passes on JSKIT app work.
+
+Preferred execution mode:
+
+- Run this skill in a fresh review agent when the runtime supports delegation.
+- Use the current agent only when delegation is unavailable.
+- The same rule applies to chunk review and whole-changeset review.
+
+## Read first
+
+1. `../../workflow/review.md`
+2. `../../workflow/feature-delivery.md`
+
+Read these on demand:
+
+- `../../reference/autogen/KERNEL_MAP.md`
+- `../../reference/autogen/README.md`
+- `../../guide/agent/index.md`
+- `../../site/guide/index.md` when compressed guidance is ambiguous
+
+Inspect app-local files when they exist:
+
+- `.jskit/WORKBOARD.md`
+- `.jskit/APP_BLUEPRINT.md`
+
+## Review target
+
+Determine whether the target is:
+
+- the current chunk
+- or the whole changeset
+
+Use `.jskit/WORKBOARD.md` to determine the active chunk when available.
+
+## Required passes
+
+1. Deslop review
+2. JSKIT best-practices review
+3. Material Design and Vuetify review
+4. Verification review
+
+## Deslop review
+
+Check for:
+
+- repeated functions or duplicated local helpers
+- local helpers that should reuse kernel/runtime seams
+- placeholder, fake-complete, or vague UI/copy/code
+- dead code, unused imports/props, TODO-shaped gaps, or accidental abstractions
+- missing loading, empty, error, permission, or ownership states
+- broken route wiring, missing migrations, or incomplete flows
+
+## JSKIT review
+
+Check for:
+
+- missed reuse of existing JSKIT helpers or runtime seams
+- hand code that should have been a package, generator, or scaffold step
+- surface, route, ownership, and migration choices that violate JSKIT conventions
+- metadata that no longer matches actual behavior
+
+## Material Design and Vuetify review
+
+Check that user-facing screens:
+
+- follow Material Design and Vuetify best practices
+- use clear layout hierarchy, spacing, actions, and empty/error states
+- use coherent list, table, and form patterns
+- improve weak screens before sign-off rather than only recording the problem
+
+## Verification review
+
+Check that verification is appropriate for the target:
+
+- focused verification for a chunk
+- broad regression for a whole changeset
+- Playwright for meaningful user-facing flows
+- explicit handling of login/test-auth strategy when auth is required
+
+## Output format
+
+- Present findings first, ordered by severity, with file references.
+- If there are no findings, say so explicitly.
+- Always finish with:
+  - files reviewed
+  - commands run
+  - anything still unverified

package/skills/jskit-review/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "JSKIT Review"
+  short_description: "Deslop, audit JSKIT fit, and verify a chunk or changeset"
+  default_prompt: "Use $jskit-review to run a deslop pass, JSKIT best-practices audit, and verification review on the current JSKIT chunk or whole changeset."

package/templates/APP_BLUEPRINT.md

@@ -44,6 +44,8 @@
 - Baseline runtime packages:
 - Optional runtime packages:
 - Generator packages to use:
+- Package-owned workflows to accept as baseline:
+- Package-owned workflows to override or extend:
 
 ## Implementation Notes
 
@@ -51,7 +53,28 @@
 - Non-CRUD pages to scaffold:
 - Custom code areas:
 
+## CRUD Planning
+
+| CRUD | Operations | List Fields | View Form Shape | Edit/New Form Shape | Notes |
+| --- | --- | --- | --- | --- | --- |
+| | | | | | |
+
+## Delivery Plan
+
+| Chunk | Goal | Type | Depends on | Done when |
+| --- | --- | --- | --- | --- |
+| | | | | |
+
+Chunk notes:
+
+- One CRUD is usually one chunk.
+- Platform/auth/shell work may be its own chunk.
+- Each chunk must be independently reviewable and testable.
+
 ## Verification
 
 - Commands to run:
+- Playwright coverage plan:
+- Test auth strategy:
+- UI review expectations:
 - Known open questions:

package/templates/WORKBOARD.md

@@ -0,0 +1,46 @@
+# Workboard
+
+## Request
+
+- Request summary:
+- Current stage:
+- Current status:
+
+## Scope Snapshot
+
+- Platform decisions:
+- Current blueprint path:
+- Current workboard owner:
+
+## Chunk Tracker
+
+| Chunk | Goal | Status | Deslop | JSKIT Review | UI Review | Verification | Notes |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| | | | | | | | |
+
+Status guide:
+
+- `planned`
+- `active`
+- `implemented`
+- `reviewed`
+- `verified`
+- `done`
+- `blocked`
+
+## Current Focus
+
+- Active chunk:
+- Next action:
+- Blockers:
+
+## Verification Log
+
+- Commands run:
+- Playwright status:
+- Remaining unverified:
+
+## Notes
+
+- Decisions made:
+- Open questions:

package/templates/app/AGENTS.md

@@ -7,22 +7,47 @@ Read these workflow files in order:
 1. `node_modules/@jskit-ai/agent-docs/workflow/app-state.md`
 2. `node_modules/@jskit-ai/agent-docs/workflow/bootstrap.md` if the workspace is empty or no JSKIT app exists yet
 3. `node_modules/@jskit-ai/agent-docs/workflow/scoping.md`
-4. `node_modules/@jskit-ai/agent-docs/workflow/feature-delivery.md`
-5. `node_modules/@jskit-ai/agent-docs/workflow/review.md`
+4. `node_modules/@jskit-ai/agent-docs/workflow/workboard.md`
+5. `node_modules/@jskit-ai/agent-docs/workflow/feature-delivery.md`
+6. `node_modules/@jskit-ai/agent-docs/workflow/review.md`
 
 Use these references on demand:
 
 - `node_modules/@jskit-ai/agent-docs/reference/autogen/KERNEL_MAP.md`
 - `node_modules/@jskit-ai/agent-docs/reference/autogen/README.md`
 - `node_modules/@jskit-ai/agent-docs/guide/agent/index.md`
-- `node_modules/@jskit-ai/agent-docs/guide/human/index.md` when compressed guidance is ambiguous or missing nuance
+- `node_modules/@jskit-ai/agent-docs/site/guide/index.md` when compressed guidance is ambiguous or missing nuance
 - `node_modules/@jskit-ai/agent-docs/templates/APP_BLUEPRINT.md`
+- `node_modules/@jskit-ai/agent-docs/templates/WORKBOARD.md`
+- `node_modules/@jskit-ai/agent-docs/skills/jskit-review/SKILL.md` for review passes when your Codex environment supports packaged skills
 
 Core rules:
 
 - Inspect the workspace before assuming a JSKIT app exists.
+- Before non-trivial edits, print a short visible checkpoint using this format:
+  - `Problem: ...`
+  - `Fix: ...`
+  - `Why this sticks: ...`
+  - `Not doing: ...`
+- Keep that checkpoint compact. Do not expand it into a long preamble unless the developer asks for detail.
 - Reuse existing JSKIT helpers and runtime seams before adding new local helpers.
+- A freshly scaffolded JSKIT app can still be in Stage 1. If the app was just created and platform decisions are not settled yet, continue with the initialize workflow before adding runtime packages.
+- Do not treat a missing `config.tenancyMode` line or an untouched minimal scaffold as a final tenancy decision.
+- Do not install tenancy-sensitive packages until Stage 1 decisions are complete and the chosen tenancy is written into `config/public.js`.
+- Treat standard JSKIT package-owned workflows as the default baseline once the relevant package stack is chosen. Do not ask the developer to redesign those flows unless they want overrides, restrictions, or custom additions.
+- Example: if the app is workspace-capable and uses `workspaces-core` plus `workspaces-web`, assume the standard workspace invite flow is part of the baseline package behavior.
+- For baseline package setup, ask plainly for the exact local development values needed for the next install step, but only for the modules or packages that are actually selected.
+- Use the real env var names or option names instead of vague requests for "credentials". Values such as `DB_NAME`, `DB_USER`, `DB_PASSWORD`, `AUTH_SUPABASE_URL`, `AUTH_SUPABASE_PUBLISHABLE_KEY`, and `APP_PUBLIC_URL` are routine setup inputs when the relevant package stack needs them.
+- For CRUD chunks, ask the developer which operations are allowed, which fields belong in the list view if one exists, and the intended look of the view and edit/new forms before generating code.
+- Every user-facing screen must pass a Material Design and Vuetify quality review before the chunk is considered done.
 - Do not implement app features before the blueprint has the database, surfaces, ownership model, and route/screen plan written down.
+- For substantial or multi-chunk work, create or update `.jskit/WORKBOARD.md` as the per-request execution tracker.
+- Break planned work into reviewable chunks before implementing. One CRUD is usually one chunk, but auth/platform setup, shell work, and cross-cutting integrations can be their own chunks.
+- Do not move to the next chunk until the current chunk has passed implementation, deslop review, JSKIT best-practices review, Material Design/Vuetify review, and verification.
+- If a feature spans more than one chunk, run a final whole-changeset deslop pass, JSKIT pass, Material Design/Vuetify pass, and verification pass after the last chunk.
+- Prefer a fresh review agent for chunk and whole-changeset review when the runtime supports delegation.
+- Have that fresh review agent use the packaged `jskit-review` skill when it is available to the runtime.
+- If delegation or skills are unavailable, follow `workflow/review.md` manually in the current agent.
 - Use the compressed guide first for speed; fall back to the human guide when a workflow trap, migration caveat, or architectural boundary needs exact wording.
 - Treat generated reference maps and guide copies as vendor reference. Do not edit them manually.
 

package/workflow/app-state.md

@@ -28,6 +28,7 @@ State handling:
   - Explain which scaffold markers are missing.
   - Recover or finish the scaffold instead of re-initializing from scratch.
 - `jskit_app`
-  - Continue with scoping or feature delivery.
+  - If this is a fresh minimal scaffold and Stage 1 platform decisions are not settled yet, continue with the initialize workflow first.
+  - Otherwise continue with scoping or feature delivery.
 
 This state gate is intentionally strict. The agent must inspect first and only then choose initialize, recover, or extend.

package/workflow/bootstrap.md

@@ -1,6 +1,27 @@
 # Initialize Workflow
 
-Use this only when the app state gate resolves to `empty`, or when the user explicitly wants a brand-new JSKIT app in a new directory.
+Use this when:
+
+- the app state gate resolves to `empty`
+- the user explicitly wants a brand-new JSKIT app in a new directory
+- or a fresh minimal JSKIT scaffold exists but Stage 1 platform decisions are not settled yet
+
+Safe bootstrap paths:
+
+1. Empty directory path
+   - Ask the Stage 1 platform questions first.
+   - Once the high-level shape is clear, run `create-app` with the chosen tenancy mode.
+2. Fresh scaffold path
+   - If the app was just created with `npx @jskit-ai/create-app <app-name>` and `npm install`, treat that scaffold as provisional.
+   - Ask the Stage 1 platform questions before adding tenancy-sensitive packages.
+   - If the chosen tenancy is `personal` or `workspaces`, write it into `config/public.js` before installing workspace packages.
+   - Once a baseline package stack is chosen, assume its standard package-owned workflows unless the developer asks for overrides.
+
+Important constraint:
+
+- Do not install tenancy-sensitive packages while tenancy is still provisional.
+- In practice, that means `workspaces-core` and `workspaces-web` must wait until the Stage 1 tenancy decision is complete.
+- A missing `config.tenancyMode` line behaves like `none` at runtime. Treat it as provisional only if no tenancy-sensitive package install has happened yet.
 
 Version 0 sketch:
 
@@ -11,7 +32,20 @@ Version 0 sketch:
    - database engine: MySQL or Postgres
    - auth provider, with Supabase as the default documented path
    - whether the first baseline should include workspaces, realtime, or assistant
-3. Once those high-level choices are clear, continue into deeper scoping questions later.
+3. Treat Stage 1 as a package-stack decision, not a blank-slate workflow design exercise.
+4. Once those high-level choices are clear, continue into deeper scoping questions later.
+
+Ask setup values plainly:
+
+- Only ask for setup values that correspond to the modules or packages already chosen for the baseline.
+- When the next package install needs concrete local development values, ask for them directly using the exact env var names or option names.
+- Do not hide behind vague requests for "credentials" or "values after that boundary".
+- In this workflow, these are routine setup inputs:
+  - If the MySQL runtime is selected: `DB_NAME`, `DB_USER`, `DB_PASSWORD`
+  - If the MySQL host or port differs from the local default `127.0.0.1:3306`: `DB_HOST`, `DB_PORT`
+  - If Supabase auth is selected: `AUTH_SUPABASE_URL`, `AUTH_SUPABASE_PUBLISHABLE_KEY`
+  - If browser-facing auth callbacks are relevant: confirm whether `APP_PUBLIC_URL` should stay `http://localhost:5173`
+- Ask in plain language and continue once the developer provides the values.
 
 Baseline expectations after initialization:
 
@@ -19,6 +53,7 @@ Baseline expectations after initialization:
 - install the baseline runtime packages in the documented order
 - install dependencies
 - run database migrations when the chosen package set requires them
+- use the standard packaged workflows that come with those packages unless the blueprint records an override
 - leave the app in a reproducible, verified baseline state
 
-Do not improvise package order. Use the distributed guide chapters under `guide/agent/app-setup/` or `guide/human/app-setup/`.
+Do not improvise package order. Use the distributed guide chapters under `guide/agent/app-setup/` or `site/guide/app-setup/`.

package/workflow/feature-delivery.md

@@ -1,21 +1,63 @@
 # Feature Delivery Workflow
 
-For each feature, follow this order:
+Before implementation, break the planned work into chunks.
 
-1. Scope the feature inside the blueprint.
-2. Decide whether it is:
+Chunk rules:
+
+- One CRUD is usually one chunk.
+- Platform setup, shell/navigation, and cross-cutting integrations may be separate chunks.
+- A chunk must be independently reviewable and testable.
+- If a chunk is too broad to review confidently, split it before coding.
+
+For each chunk, follow this order:
+
+1. Scope the chunk inside the blueprint.
+2. Mark the chunk as active in `.jskit/WORKBOARD.md`.
+3. Decide whether it is:
    - package install
    - generator scaffolding
    - custom local code
    - or a combination
-3. Implement the smallest correct change.
-4. Review for implementation gaps.
-5. Review against JSKIT reuse and best practices.
-6. Verify with the relevant commands.
+4. Implement the smallest correct change.
+5. Deslop the chunk.
+6. Review the chunk against JSKIT reuse and best practices.
+7. Review user-facing screens against Material Design and Vuetify best practices, and improve any screens that do not meet that bar.
+8. Verify the chunk with the relevant commands, including Playwright for meaningful UI flows.
+9. Update `.jskit/WORKBOARD.md` with status, commands run, and anything still unverified.
+10. Only then move to the next chunk.
+
+For CRUD chunks:
+
+1. Decide the table shape first.
+2. If `crud-server-generator` is going to own the CRUD schema, do not hand-write a separate migration for that CRUD table.
+3. Scaffold the server side first with `crud-server-generator`.
+4. Only after the shared resource file exists, scaffold the client side against that resource.
+5. Do not guess CRUD operations or screen shape. Ask the developer:
+   - which operations are allowed
+   - which fields belong in the list view if one exists
+   - what the view form should look like
+   - what the edit/new form should look like
 
 During implementation:
 
 - Prefer existing JSKIT helpers over local helper duplication.
+- If a selected JSKIT package already ships the required baseline workflow, install and verify that workflow before inventing custom code around it.
+- Ask only about overrides, restrictions, or app-specific additions to packaged baseline workflows.
 - Use generated CRUD/UI scaffolds only after the route and ownership model are decided.
 - Keep runtime, UI, and data concerns separated.
 - Avoid “while I’m here” scope creep unless it is required for correctness.
+
+After the last chunk:
+
+- If there was only one chunk, the chunk review is the final review.
+- If there was more than one chunk, run one more whole-changeset pass:
+  - deslop the whole changeset
+  - review the whole changeset against JSKIT best practices
+  - review the whole changeset against Material Design and Vuetify best practices
+  - run the widest relevant verification, including Playwright
+  - update `.jskit/WORKBOARD.md` with the final result and any remaining gaps
+
+Playwright note:
+
+- When login is required, prefer a test-only impersonation or session bootstrap path over dependence on a live external auth provider.
+- If such a path does not exist yet, treat that as a testability gap and decide whether the chunk must add it before the feature is considered complete.

package/workflow/review.md

@@ -1,18 +1,38 @@
 # Review Workflow
 
-Before calling a feature done, review it in three passes:
+Preferred review mode:
 
-1. Implementation gap review
-   - missing states
-   - broken flows
-   - incomplete ownership handling
-   - missing migrations or route wiring
+- Prefer a fresh review agent for chunk and whole-changeset review when the runtime supports delegation.
+- Have that fresh review agent use the packaged `jskit-review` skill when it is available.
+- If delegation or skills are unavailable, follow this file manually in the current agent.
+
+Before calling a chunk or a whole changeset done, review it in four passes:
+
+1. Deslop review
+   - repeated functions or duplicated local helpers
+   - helpers reimplemented locally when a kernel/runtime seam already exists
+   - placeholder, fake-complete, or vague UI/copy/code structure
+   - dead code, unused props/imports, TODO-shaped gaps, or accidental abstractions
+   - missing loading, empty, error, permission, or ownership states
+   - broken flows, missing route wiring, or missing migrations
+   - surface or entity ownership mistakes: `public`, `user`, `workspace`, `workspace_user`
 2. JSKIT review
    - existing helper/runtime seam available?
    - duplicate local code that should reuse kernel/runtime support?
+   - should this have been a package install, generator step, or scaffold extension instead of hand code?
+   - are surface, route, ownership, and migration choices aligned with JSKIT conventions?
    - package metadata and actual behavior still aligned?
-3. Verification review
-   - run the smallest relevant verification commands
+3. UI standards review
+   - every user-facing screen follows Material Design and Vuetify best practices
+   - list screens use clear hierarchy, actions, density, empty states, and table/list patterns
+   - view and edit/new screens use clear form grouping, labels, helper text, validation, spacing, and action placement
+   - responsive layout, loading, disabled, success, and error states are coherent
+   - improve weak screens before sign-off; do not just note the problem and move on
+4. Verification review
+   - run the smallest relevant verification commands for a chunk
+   - run the widest relevant verification commands for a whole changeset
+   - include Playwright for meaningful user-facing flows
+   - if login is required, verify the chosen test-auth path or explicitly record that the lack of one is an open gap
    - note anything left unverified
 
 Minimum expectation:
@@ -20,3 +40,8 @@ Minimum expectation:
 - list the files changed
 - list the commands run
 - list anything still unverified
+- update `.jskit/WORKBOARD.md` with the review outcome
+
+Whole-changeset rule:
+
+- If the work was split into more than one chunk, repeat all four passes over the whole changeset after the final chunk is complete.

package/workflow/scoping.md

@@ -1,6 +1,13 @@
 # Scoping Workflow
 
-Before implementing any feature or batch of features, write or update `templates/APP_BLUEPRINT.md` as the working app blueprint.
+Before implementing any feature or batch of features, create or update an app-local working blueprint using `templates/APP_BLUEPRINT.md` as the template.
+
+Recommended location:
+
+- `.jskit/APP_BLUEPRINT.md`
+- `.jskit/WORKBOARD.md` for per-request progress tracking
+
+Do not edit the vendor template in `node_modules/` directly.
 
 The blueprint must capture at least:
 
@@ -15,12 +22,26 @@ The blueprint must capture at least:
 - package install plan
 - generator plan
 - custom-code areas
+- baseline package-owned workflows and any intended overrides
+- delivery plan broken into chunks
+- CRUD-specific operation and screen decisions where relevant
 
 Scoping rules:
 
-- Use `guide/agent/index.md` for fast navigation and `guide/human/index.md` for exact details.
+- Use `guide/agent/index.md` for fast navigation and `site/guide/index.md` for exact details.
 - Inspect packages and generators before choosing them.
 - Decide ownership early; do not treat it as a UI-only detail.
+- If Stage 1 platform choices are still provisional, finish them before installing tenancy-sensitive runtime packages.
+- Record which selected JSKIT package-owned workflows are accepted as baseline and which, if any, need custom behavior.
+- Do not ask the developer to redesign package-owned baseline workflows from scratch. Ask only whether the default behavior is accepted or whether the app needs overrides, restrictions, or extensions.
+- Create or refresh `.jskit/WORKBOARD.md` for substantial or multi-chunk work so the request has an explicit execution tracker.
+- Break delivery into chunks that can be independently reviewed and tested.
+- One CRUD is usually one chunk. Platform setup, shell work, and cross-cutting integrations may also be separate chunks.
+- For each CRUD chunk, decide these before implementation:
+  - which operations exist: `list`, `view`, `new`, `edit`, `delete`, or a narrower set
+  - which fields appear in the list view if a list exists
+  - the intended structure and visual hierarchy of the view form
+  - the intended structure and visual hierarchy of the edit/new form
 - If the package/runtime choice is unclear, stop and resolve it before writing implementation code.
 
-No feature implementation should start until the blueprint covers database, screens, and functional boundaries well enough that the implementation path is obvious.
+No feature implementation should start until the blueprint covers database, screens, functional boundaries, and chunk plan well enough that the implementation path is obvious.

package/workflow/workboard.md

@@ -0,0 +1,29 @@
+# Workboard Workflow
+
+Use a workboard for any substantial request, especially:
+
+- new app builds
+- multi-chunk feature work
+- requests that need scoping before coding
+- requests where verification spans several steps
+
+Recommended location:
+
+- `.jskit/WORKBOARD.md`
+
+Use `templates/WORKBOARD.md` as the starting template.
+
+Purpose:
+
+- track the current request
+- record the current stage and current chunk
+- track chunk status across implementation, deslop, JSKIT review, UI review, and verification
+- record blockers, open questions, and remaining gaps
+
+Workboard rules:
+
+- The workboard is the execution tracker for the current request.
+- The blueprint remains the durable product and architecture record.
+- Keep the workboard concise and current.
+- Update it when stage, chunk, blockers, or verification state changes.
+- When the request finishes, either reset it for the next request or leave a short final state that makes completion obvious.