@shanyucoder/flowgrid 0.1.5 → 0.1.9

package/harness/docs/skills/api-integration/SKILL.md

@@ -1,110 +0,0 @@
----
-name: api-integration
-description: EXCLUSIVE /api-integration — ONLY for backend integration contracts (partner APIs, webhooks). DO NOT merge multiple integrations into single markdown files.
-disable-model-invocation: true
----
-
-> [!CRITICAL] MANDATORY PRE-FLIGHT
-> **[MANDATORY]** Re-read this entire `SKILL.md` via file-read tool. STRICTLY FORBIDDEN to rely on memory.
-
-# /api-integration — Integration Contract (no Portal FE)
-
-Shared extracts: `api-integration-spec.md`, `entity-relationship.md`, `call-external.md`, `agent-discipline.md`, `verify-gate.md`
-
----
-
-## Rule: When to Use (vs `/api-spec`)
-
-- **[MANDATORY]** Use `/api-integration` for: inbound/outbound webhooks, REST APIs exported to partners/3rd parties, public APIs with dedicated versioning, reverse-engineering legacy handlers or provider OpenAPI specs.
-- **[STRICTLY FORBIDDEN]** If a Portal FE spec exists for the same user journey → use `/api-spec`, not this command.
-
----
-
-## Rule: Audit Interlock
-
-- **[MANDATORY]** If an integration bundle already exists: run an audit before making modifications.
-  - ✅ Check for existing endpoints under `surfaces/integrations/` using `flowgrid_docs_route` or glob search before authoring a new contract trio.
-  - ❌ Never re-define routes that already exist; link and reuse them.
-
----
-
-## Rule: Missing Information Handling & Workload Threshold (Law 2)
-
-- **[MANDATORY]** When signature verification, retry policy, or retention policy is unknown, evaluate total missing volume:
-  - **Small Scope (≤5 questions):** Trigger `AskQuestion` wizard — one question at a time, **≥3 options**: (1) `(Recommended)`, (2) `Other` (free text), (3) `Log as Tech Debt (Pending)`.
-  - **Large Scope (≥10 gaps/endpoints):** **[MANDATORY HARD STOP IN CHAT]**. Do not spam single questions in chat. Generate an implementation plan / Plan Mode document partitioned into sequential Phases (3–5 endpoints/gaps per phase) with disk offloading at boundaries.
-  - ✅ If "Log as Tech Debt" is selected → create `qa/open/QA-<feature.id>-NNNN.yaml`. Set `integrationBacklog[]` (NOT portal `pendingTechDebt`).
-  - ❌ Never write `openQuestions` in YAML. Never invent HMAC secrets or partner-specific validation logic.
-
----
-
-## Rule: Folder Structure
-
-- **[MANDATORY]** Every integration contract must be placed under:
-  ```
-  surfaces/integrations/<provider>/<slug>/api/<seq>/
-  ├── 01-backend-spec.yaml    # feature.source.kind + integrationRefs (tech SSOT)
-  ├── 02-openapi.yaml         # generated by: flowgrid openapi_gen --spec <01>
-  └── 03-mock-data.yaml
-  ```
-- **[MANDATORY]** One `01` = one primary domain entity. Never dump all provider actions into one single file.
-- **[STRICTLY FORBIDDEN]** Never write `.md` directly. Never combine multiple integrations into one gross monolithic file.
-
----
-
-## Rule: Explicit URI Naming
-
-- **[MANDATORY]** All integration endpoints MUST use explicit action suffixes:
-  - Inbound webhook: `POST /api/v1/integrations/<provider>/webhook`
-  - Inbound event action: `POST /api/v1/integrations/<provider>/{id}/sync` (or `/receive`)
-  - Outbound partner API: `POST /…/create`, `PUT /…/{id}/update`
-- **[STRICTLY FORBIDDEN]** Never use ambiguous RESTful routes lacking explicit action semantics.
-
----
-
-## Rule: Integration Error Handling
-
-- **[MANDATORY]** Document explicit error responses using `#err:*` tags for:
-  - `#err:unauthorized` — invalid API key / expired token
-  - `#err:signature-invalid` — HMAC signature mismatch on webhook
-  - `#err:rate-limit` — partner throttling limit reached
-  - `#err:validation` — malformed payload
-  - `#err:system` — internal processing failure
-- **[RECOMMENDED]** Global errors (500/503/401) → delegate to OpenAPI `$ref` schemas; do NOT duplicate across each endpoint.
-- **[MANDATORY]** Provide partner-facing error code mappings in both `01-backend-spec.yaml` and `02-openapi.yaml`.
-
----
-
-## Rule: YAML & Tagging
-
-- **[MANDATORY]** Configure: `feature.source.kind`, `base: none`, `integrationRefs[]`, empty `portalRefs`, `contexts.portalLayout: none`, and `contexts.auth` (API key / HMAC / OAuth).
-- **[MANDATORY]** Use domain tags only: `#webhook-inbound`, `#webhook-outbound`, `#partner-api`, `#public-api`, `#call-external`, `#err:*`.
-- **[STRICTLY FORBIDDEN]** No `codegen`, no `#gen:*`, no `approval` beyond `draft` — specialized grill handles those downstream.
-- **[MANDATORY]** All strings with `:` in YAML must be double-quoted.
-
----
-
-## Workflow
-
-1. Configure source metadata: `feature.source.kind`, `base: none`, `integrationRefs[]`.
-2. Scan `surfaces/integrations/` for existing endpoints; apply reuse if found.
-3. Set `contexts.portalLayout: none`; document `contexts.auth`.
-4. Inventory events/endpoints from provider documentation or legacy source — mark `inferredFromCode` in `notes`.
-5. Specify entities, idempotency keys, deduplication, and raw payload retention policies in `decisions` / `beOnlyRequirements`.
-6. Author `api.endpoints` with explicit action URIs.
-7. Apply integration error storming `#err:*` tags.
-8. Run `flowgrid openapi_gen --spec …/api/<seq>/01-backend-spec.yaml` → generates `02-openapi.yaml`.
-9. Author mock data (representative webhook payload JSON + acknowledgement response).
-10. Run AskQuestion wizard for unresolved unknowns (signature, retry, retention).
-11. Update `.harness/progress.md`.
-
----
-
-## Verification Checklist
-
-- [ ] Folder structure: contract trio located under `surfaces/integrations/<provider>/<slug>/api/<seq>/`.
-- [ ] `01-backend-spec.yaml`, `02-openapi.yaml`, `03-mock-data.yaml` all generated and populated.
-- [ ] Partner-facing error codes and `#err:*` tags fully documented.
-- [ ] Explicit URI action suffixes strictly applied.
-- [ ] No `.md` authored directly. No gross monolithic files created.
-- [ ] All YAML strings containing `:` are double-quoted.

package/harness/docs/skills/grill-integration-spec/SKILL.md

@@ -1,51 +0,0 @@
----
-name: grill-integration-spec
-description: EXCLUSIVE /grill-integration-spec — ONLY for auditing backend integration contracts under surfaces/integrations/. DO NOT generate Markdown reports.
-disable-model-invocation: true
----
-
-> [!CRITICAL] MANDATORY PRE-FLIGHT
-> **[MANDATORY]** Re-read this entire `SKILL.md` via file-read tool. STRICTLY FORBIDDEN to rely on memory.
-
-# /grill-integration-spec — Integration Contract Audit
-
-After `/api-integration`. Before bộ code BE `/api`. No code on docs hub.
-
-Shared extracts: `api-integration-spec.md`, `api-codegen-readiness.md`, `api-codegen-tags.md`, `call-external.md`, `entity-relationship.md`, `agent-discipline.md`, `verify-gate.md`
-
----
-
-## Rule: Goal & Scope
-
-- **[MANDATORY]** Contract must be sufficient to implement webhook and partner APIs.
-- **[MANDATORY]** OpenAPI `securitySchemes` and mock definitions must match `01-backend-spec.yaml`.
-- **[MANDATORY]** Codegen-ready: `flowgrid check` + `flowgrid openapi_gen` / `openapi:render` must pass.
-- **[STRICTLY FORBIDDEN]** Do NOT use `ir/design.yaml` as BE input (integrations usually have no FE IR).
-- **[STRICTLY FORBIDDEN]** No BQA reports, no framework code snippets, no writing `ir/*`.
-
----
-
-## Rule: Workflow Steps
-
-- **[MANDATORY]** Step 1: Resolve `surfaces/integrations/<provider>/<slug>/api/<seq>/01-backend-spec.yaml`. Never a `01` directly on the slug leaf.
-- **[MANDATORY]** Step 2: Audit authentication, `securitySchemes`, idempotency keys, retry policies, and non-CRUD actions.
-- **[MANDATORY]** Step 3: Enrich `01` with codegen tags (`#gen:*`, `#manual-service`, `#call-external`), `codegen.profile|entity|module`, and `endpoints[].action`.
-- **[MANDATORY]** Step 4: Run gates:
-  - `flowgrid check --spec surfaces/integrations/<provider>/<slug>/api/<seq>/01-backend-spec.yaml`
-  - `flowgrid openapi_gen --spec …/01-backend-spec.yaml`
-  - `flowgrid openapi_render`
-- **[MANDATORY]** Step 5: Set `approval.status: reviewed` (or `approved`) in YAML.
-
----
-
-## Verification Checklist
-
-- [ ] Target: `01-backend-spec.yaml` under `…/integrations/…/api/<seq>/`.
-- [ ] Auth + idempotency keys + retry policy verified and populated.
-- [ ] Gates executed: `api:check` + `openapi:gen` + `openapi:render` exit 0.
-- [ ] `approval.status` set to `reviewed` or `approved`.
-- [ ] No `openQuestions` in YAML; no `.md` written directly.
-
-## Handoff
-
-- `approval.status: approved` → bộ code `--type=be` `/api` with `--spec …/01-backend-spec.yaml`