@jskit-ai/agent-docs 0.1.1

package/templates/APP_BLUEPRINT.md

@@ -0,0 +1,57 @@
+# App Blueprint
+
+## Product
+
+- App purpose:
+- Primary users:
+- Success criteria:
+
+## Platform Choices
+
+- Tenancy mode:
+- Database engine:
+- Auth provider:
+- Optional extras: realtime / assistant / uploads / other
+
+## Actors And Access
+
+- Actor list:
+- Permission boundaries:
+- Console/admin-only areas:
+
+## Surfaces
+
+- Global surfaces:
+- Workspace surfaces:
+- Settings surfaces:
+
+## Data Model
+
+| Entity | Purpose | Ownership | Notes |
+| --- | --- | --- | --- |
+| | | | |
+
+## Route And Screen Plan
+
+- Home/global routes:
+- Account routes:
+- Console routes:
+- Workspace app routes:
+- Workspace admin routes:
+
+## Package Plan
+
+- Baseline runtime packages:
+- Optional runtime packages:
+- Generator packages to use:
+
+## Implementation Notes
+
+- CRUDs to scaffold:
+- Non-CRUD pages to scaffold:
+- Custom code areas:
+
+## Verification
+
+- Commands to run:
+- Known open questions:

package/workflow/app-state.md

@@ -0,0 +1,33 @@
+# App State Gate
+
+Before planning, scaffolding, or implementing, classify the workspace into one of these states:
+
+- `empty`
+- `non_jskit_repo`
+- `partial_jskit_app`
+- `jskit_app`
+
+Use these markers for a real JSKIT app:
+
+- `package.json`
+- `config/public.js`
+- `src/main.js`
+- `packages/main/package.descriptor.mjs`
+- `.jskit/lock.json`
+
+State handling:
+
+- `empty`
+  - Start the initialize workflow.
+  - Ask only high-level questions first: app goal, tenancy shape, database engine, auth provider, optional assistant/realtime needs.
+  - Do not jump straight into detailed feature implementation.
+- `non_jskit_repo`
+  - Ask whether the JSKIT app should live here or in a new subdirectory.
+  - Do not overwrite unrelated project files.
+- `partial_jskit_app`
+  - 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.
+
+This state gate is intentionally strict. The agent must inspect first and only then choose initialize, recover, or extend.

package/workflow/bootstrap.md

@@ -0,0 +1,24 @@
+# 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.
+
+Version 0 sketch:
+
+1. Define the broad app shape before running generators.
+2. Capture only the first-round decisions:
+   - app purpose
+   - tenancy mode: `none`, `personal`, or `workspaces`
+   - 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.
+
+Baseline expectations after initialization:
+
+- create the app scaffold
+- install the baseline runtime packages in the documented order
+- install dependencies
+- run database migrations when the chosen package set requires them
+- 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/`.

package/workflow/feature-delivery.md

@@ -0,0 +1,21 @@
+# Feature Delivery Workflow
+
+For each feature, follow this order:
+
+1. Scope the feature inside the blueprint.
+2. 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.
+
+During implementation:
+
+- Prefer existing JSKIT helpers over local helper duplication.
+- 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.

package/workflow/review.md

@@ -0,0 +1,22 @@
+# Review Workflow
+
+Before calling a feature done, review it in three passes:
+
+1. Implementation gap review
+   - missing states
+   - broken flows
+   - incomplete ownership handling
+   - missing migrations or route wiring
+2. JSKIT review
+   - existing helper/runtime seam available?
+   - duplicate local code that should reuse kernel/runtime support?
+   - package metadata and actual behavior still aligned?
+3. Verification review
+   - run the smallest relevant verification commands
+   - note anything left unverified
+
+Minimum expectation:
+
+- list the files changed
+- list the commands run
+- list anything still unverified

package/workflow/scoping.md

@@ -0,0 +1,26 @@
+# Scoping Workflow
+
+Before implementing any feature or batch of features, write or update `templates/APP_BLUEPRINT.md` as the working app blueprint.
+
+The blueprint must capture at least:
+
+- product purpose
+- actors and permissions
+- tenancy mode
+- database engine
+- auth choice
+- core surfaces and route families
+- core entities
+- ownership model per entity: `public`, `user`, `workspace`, or `workspace_user`
+- package install plan
+- generator plan
+- custom-code areas
+
+Scoping rules:
+
+- Use `guide/agent/index.md` for fast navigation and `guide/human/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 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.