howone 0.1.31 → 0.1.32

package/templates/vite/.howone/skills/howone/SKILL.md

@@ -1,110 +1,147 @@
 ---
 name: howone
-description: HowOne generated app platform. Scope follows the user request. Load for architecture; add entity-schema, ai-capabilities, or app-sdk tracks only when those surfaces are needed.
+description: 'Use when the task touches HowOne platform contracts or app runtime: designing/changing backend dynamic entity schemas, public/private access, Mongo-backed persisted data, AI capabilities/workflows, external-ai workflow create/update/status, syncing .howone manifests, generating src/lib/sdk.ts, auth/uploads, or app code that calls @howone/sdk/howone.*. Also use when files mention backend-api-design, ai-capability-design, sync_schema_artifacts, sync_ai_artifacts, external-ai-capability, .howone/database, or .howone/ai. Do not use for UI-only edits with no HowOne data, AI, auth, upload, manifest, or SDK surface.'
 ---
 
-# HowOne Skill
+# HowOne
 
-HowOne apps may be frontend-only, full-stack without AI, AI without custom backend, or full-stack
-with AI and persisted data. **Scope always follows the user's request.** This file is the index;
-processors defer here.
+HowOne builds generated full-stack AI apps. Platform contracts are separate from app implementation:
 
-## Mandatory flow
+- Backend: dynamic entity contracts backed by HowOne's MongoDB runtime.
+- AI: capability contracts and external workflow generation/editing.
+- SDK: app-side runtime bindings and calls after manifests are synced.
 
-1. `skill(name="howone")`
-2. `skill_read "01-architect/01-app-generation.md"` — always, before any platform design write
-3. `skill_read` the smallest set from the track index below that architect routing selects
-4. Platform design tools → sync → `{appRoot}/src/lib/sdk.ts` / app code — only for surfaces in scope
+Load only the track needed for the user's request. Do not read SDK files while designing backend or AI contracts unless the task has reached manifest-to-code implementation.
 
-Inspect-only platform calls do not replace step 2 before the first design write.
+## Trigger Preconditions
 
-## Tracks
+Use this skill before work when any condition is true:
 
-| Track | When needed | Design vs implement |
-|---|---|---|
-| `01-architect/` | Always (scope, feasibility, posture, order) | Plan |
-| `02-entity-schema/` | User needs HowOne persisted data | Design contracts |
-| `03-ai-capabilities/` | User needs HowOne AI | Design contracts |
-| `04-app-sdk/` | User calls HowOne via SDK after sync | Implement |
+- The user asks for persisted app data, backend schema, entity fields, access, indexes, public pages, private history, or Mongo-backed records.
+- The user asks for HowOne AI behavior, capability contracts, workflow generation/update/status, or `external-ai`.
+- The work reads or writes `.howone/database/*`, `.howone/ai/*`, `src/lib/sdk.ts`, or app code using `@howone/sdk` / `howone.*`.
+- The selected tool is `backend-api-design`, `ai-capability-design`, `sync_schema_artifacts`, `sync_ai_artifacts`, or `external-ai-capability`.
+- The implementation needs HowOne auth, upload URLs, public/private entity access, or manifest-to-SDK bindings.
 
-## Platform boundary (read architect for detail)
+Skip this skill only when the task is purely UI/static code and does not touch HowOne data, AI,
+auth, upload, manifests, or SDK calls.
 
-HowOne platform work must map to **contract evidence**: database manifest, AI manifest, AI service
-catalog, platform tool schemas, or a documented `04-app-sdk/` reference.
+## First Decision
 
-| Class | Meaning | Agent action |
-|---|---|---|
-| Platform in scope | Ask is expressible through the surfaces above | Use matching track + design tools |
-| App-owned | User's own ops stack, services, or infra (any technology) | Implement in `{appRoot}` app code/config; do not block |
-| Platform gap | User wants a **platform** feature with no contract evidence | Stop platform path; explain missing surface; Support Policy if needed |
+Classify the request before tool writes:
 
-Do not treat unrelated user infrastructure (orchestration, custom servers, third-party products, etc.) as platform stop-loss. Do not model app-owned systems as fake HowOne entities or AI capabilities.
+| User need | Track | Tools/files |
+|---|---|---|
+| Persist HowOne app data | Backend | `backend-api-design`, `sync_schema_artifacts`, backend files under `02-entity-schema/` |
+| Add/change HowOne AI behavior | AI | `ai-capability-design`, `sync_ai_artifacts`, `external-ai-capability`, `03-ai-capabilities/*` |
+| Call HowOne from generated app code | SDK | `src/lib/sdk.ts`, synced manifests, `04-app-sdk/*` |
+| UI only, no HowOne data or AI | None | edit app code only |
+| User-owned external services | App-owned | integrate in app code/config; do not fake platform contracts |
 
-## Track index (skill_read paths)
+If multiple tracks apply, process them in dependency order:
 
-Read only files required for the current request.
+```text
+architect -> backend contract and/or AI contract -> sync manifests -> SDK bindings -> UI
+```
 
-### `01-architect/`
+## Mandatory Reads
 
-| File | Use for |
-|---|---|
-| `01-app-generation.md` | Scope, platform vs app-owned, feasibility, data/auth posture, workflows, checklist |
-| `02-manifest-codegen.md` | Generate `src/lib/sdk.ts` from synced manifests |
+Always read `01-architect/01-app-generation.md` before the first write to a HowOne platform contract or SDK binding.
 
-### `02-entity-schema/`
+Then read the minimum track files:
 
-| File | Use for |
+| Track | Required before writes |
 |---|---|
-| `01-schema-design.md` | Entity contract shape, fields, access, indexes |
-| `02-schema-operations.md` | Preview/apply schema patches, versions |
-| `03-data-access-patterns.md` | Public/private/own access, sharing |
-| `04-query-dsl-and-responses.md` | Filters, sort, pagination, response mapping |
-| `05-ai-persistence-patterns.md` | Storing AI results in entities |
+| Backend contract | `02-entity-schema/01-schema-design.md`, `02-entity-schema/02-schema-operations.md` |
+| AI contract | `03-ai-capabilities/01-ai-capability-architecture.md`, `03-ai-capabilities/02-workflow-contract-rules.md`, `03-ai-capabilities/03-service-capability-catalog.md` |
+| External AI workflow submit/update | `03-ai-capabilities/04-workflow-operations.md` |
+| SDK binding/code | `01-architect/02-manifest-codegen.md` plus the relevant `04-app-sdk/` file |
+| AI output persistence | Backend required reads plus `02-entity-schema/05-ai-persistence-patterns.md` after AI output schema is known |
 
-### `03-ai-capabilities/`
+Do not load all references preemptively.
 
-| File | Use for |
-|---|---|
-| `01-ai-capability-architecture.md` | Layers, boundaries, feature flow |
-| `02-workflow-contract-rules.md` | Input/output JSON schemas for capabilities |
-| `03-service-capability-catalog.md` | What the workflow service supports (feasibility) |
-| `04-workflow-operations.md` | External workflow create/update/status |
-| `05-ai-feature-playbooks.md` | Recurring product patterns |
+## Tool Flow
 
-### `04-app-sdk/`
+Backend contract:
 
-| File | Use for |
-|---|---|
-| `01-client-setup.md` | `createClient`, env, provider |
-| `02-entity-operations.md` | `howone.entities` / public namespace |
-| `03-auth.md` | Login, session, custom auth |
-| `04-react-integration.md` | `HowOneProvider`, hooks |
-| `05-file-upload.md` | Uploads |
-| `06-raw-http.md` | Typed escape hatch |
-| `07-ai-action-calls.md` | `howone.ai.*` runtime calls |
-| `08-ai-manifest-handoff.md` | AI manifest → `src/lib/sdk.ts` |
-| `09-extension-boundaries.md` | Adapters, extension rules |
-| `10-workflow-execute-sse.md` | Documented workflow status/streaming wire format |
+```text
+get_current_schema -> apply_schema_patch -> sync_schema_artifacts -> read .howone/database/manifest.json
+```
 
-## Routing
+AI contract:
 
-All surface classification and minimum reads live in `01-architect/01-app-generation.md`. This
-skill index lists files; architect decides which apply.
+```text
+get_current_ai_capabilities -> apply_capability_patch -> sync_ai_artifacts -> external-ai-capability -> read .howone/ai/manifest.json
+```
 
-Mixed scope: read at least one file per touched track before writing.
+No contract dry-run step. Normal generation applies one well-formed patch directly. For destructive,
+narrowing, or public-access-expanding changes, stop for user alignment first, then apply the exact
+approved patch.
 
-## Design order
+SDK/code:
 
 ```text
-architect → (optional) entity-schema and/or ai-capabilities → sync → app-sdk → UI
+read synced manifests -> update src/lib/sdk.ts -> implement UI/server code using src/lib/sdk.ts imports
 ```
 
-Skip tracks the user did not require.
+## Source Of Truth
 
-## Rules
+- Backend fields/access/indexes: `{appRoot}/.howone/database/manifest.json` after sync.
+- AI names/workflow IDs/schemas: `{appRoot}/.howone/ai/manifest.json` after sync.
+- App runtime entry: `{appRoot}/src/lib/sdk.ts`.
+- Do not handwrite `.howone/` metadata.
+- Do not infer contract identifiers from prompts, memory, or dependency source.
 
-- When platform contracts apply: synced `{appRoot}/.howone/database/manifest.json` and/or
-  `{appRoot}/.howone/ai/manifest.json` plus tool results are source of truth.
-- `.howone/` holds manifests only—not generated app source.
-- Do not invent platform schemas, APIs, or identifiers absent from contracts/catalog/tools.
-- Platform stop-loss: architect. User-owned external systems: integrate in app code.
+## Track Index
+
+### Architect
+
+| File | Use |
+|---|---|
+| `01-architect/01-app-generation.md` | Scope classification, platform boundary, ordering |
+| `01-architect/02-manifest-codegen.md` | Synced manifests to `src/lib/sdk.ts` |
+
+### Backend
+
+| File | Use |
+|---|---|
+| `02-entity-schema/01-schema-design.md` | Entity fields, access, indexes |
+| `02-entity-schema/02-schema-operations.md` | Patch/apply/sync/version rules |
+| `02-entity-schema/03-access-models.md` | Backend authenticated/public access models |
+| `02-entity-schema/04-query-contracts.md` | Backend filter/sort/pagination/index contracts |
+| `02-entity-schema/05-ai-persistence-patterns.md` | Saving AI results into entities |
+
+### AI
+
+| File | Use |
+|---|---|
+| `03-ai-capabilities/01-ai-capability-architecture.md` | AI layers and design order |
+| `03-ai-capabilities/02-workflow-contract-rules.md` | Capability JSON schema rules |
+| `03-ai-capabilities/03-service-capability-catalog.md` | Supported workflow families |
+| `03-ai-capabilities/04-workflow-operations.md` | External workflow create/update/status |
+| `03-ai-capabilities/05-ai-feature-playbooks.md` | Reusable AI product patterns |
+
+### SDK
+
+| File | Use |
+|---|---|
+| `04-app-sdk/01-client-setup.md` | `createClient`, env, provider |
+| `04-app-sdk/02-entity-operations.md` | `howone.entities` and public namespace |
+| `04-app-sdk/03-auth.md` | Login/session/custom auth |
+| `04-app-sdk/04-react-integration.md` | Provider and hooks |
+| `04-app-sdk/05-file-upload.md` | Upload URLs/files |
+| `04-app-sdk/06-raw-http.md` | Typed escape hatch |
+| `04-app-sdk/07-ai-action-calls.md` | `howone.ai.*` runtime calls |
+| `04-app-sdk/08-ai-manifest-handoff.md` | AI manifest to SDK bindings |
+| `04-app-sdk/09-extension-boundaries.md` | Adapter/extension boundaries |
+| `04-app-sdk/10-workflow-execute-sse.md` | Workflow run/stream wire format |
+| `04-app-sdk/11-entity-data-access-patterns.md` | App entity access calls from synced manifest |
+| `04-app-sdk/12-query-dsl-and-responses.md` | App query/filter/sort/pagination calls |
+
+## Hard Rules
+
+- Backend and AI design references must not include SDK implementation work.
+- SDK references must not invent backend or AI contracts; they consume synced manifests.
+- AI workflows must not perform database CRUD; persistence is app code through entities.
+- User-owned infrastructure is app code, not a platform gap.
+- Platform gap means missing HowOne contract/tool/catalog support, not an unsupported technology name.