@shanyucoder/flowgrid 0.1.0

package/harness/docs/skills/openapi/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: openapi
+description: /openapi — generate 02-openapi.yaml from 01-backend-spec.yaml on the docs hub (bộ docs).
+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.
+
+# /openapi — OpenAPI YAML (docs hub)
+
+**Owner:** bộ docs (`--type=docs`). OpenAPI is a **docs artifact**, not bộ code.
+
+One generator: **OpenAPI 3.0.3** from `01-backend-spec.yaml`. Merge/UI stays `openapi:render` + Redocly bundle.
+
+---
+
+## Rule: Generation Commands
+
+- **[MANDATORY]** Generate `02-openapi.yaml` from the corresponding `01`:
+  ```bash
+  flowgrid openapi_gen --spec surfaces/<surface>/CMP-*/<NN…>/api/<seq>/01-backend-spec.yaml
+  # Or from docs hub root (all 01-backend-spec.yaml under surfaces):
+  flowgrid openapi_gen
+  # Validate only:
+  flowgrid check --spec …/01-backend-spec.yaml
+  ```
+- **[MANDATORY]** After generation: run `flowgrid openapi_render` to merge fragments into `docs/openapi/api.yaml`.
+
+---
+
+## Rule: Patch vs Reinvent
+
+- **[MANDATORY]** If fragment is too thin (error $refs, missing examples): patch **`01-backend-spec.yaml`** and regenerate.
+- **[STRICTLY FORBIDDEN]** Do NOT hand-edit `02-openapi.yaml` as SSOT.
+- **[STRICTLY FORBIDDEN]** Do NOT run bộ code `--type=docs` or `nestjs --openapi`. Do NOT invent a second generator per stack.
+- **[STRICTLY FORBIDDEN]** BE `/api` generates implementation code from the contract — it does NOT own OpenAPI YAML.

package/harness/docs/skills/overview/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: overview
+description: /overview — Handles the Overview root folder (Operational areas).
+disable-model-invocation: true
+extractBundle: architecture-core
+---
+
+> [!CRITICAL] MANDATORY PRE-FLIGHT
+> **[MANDATORY]** Re-read this entire `SKILL.md` via file-read tool. STRICTLY FORBIDDEN to rely on memory.
+
+# /overview — Operational Areas Overview
+
+**Target Paths:** `overview/operational-areas/[Admin operations | Workforce operations | …]`
+
+---
+
+## Rule: Content Boundary
+
+- **[MANDATORY]** Overview MUST be a pure business document written in user domain language: personas, operational areas, high-level system purpose.
+- **[STRICTLY FORBIDDEN]** Do NOT include technical details (database schemas, cloud infrastructure configurations, internal routing mechanisms).
+- **[MANDATORY]** When mentioning 3rd-party systems, use business names only (e.g. "Payment Gateway"), not technical specifications or protocols.
+
+---
+
+## Rule: `common` Modifier
+
+- **[MANDATORY]** When called with `common` (e.g. `/overview common`) → check if `overview/common` exists; create it if not present.
+
+---
+
+## Modifier: `/legacy`
+
+- **[MANDATORY]** Reference source mappings from `legacy-repos.local.json`.
+- **[MANDATORY]** Map legacy actors/personas and subsystems into Operational Areas. Write output with `legacy-` prefix (e.g. `overview/legacy-overview.md`).
+
+---
+
+## Verification Checklist
+
+- [ ] `overview` directory structure verified/created.
+- [ ] Content uses business language only — free of technical architecture details.
+- [ ] Handled `common` modifier properly if passed.

package/harness/docs/skills/qa-resolve/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: qa-resolve
+extractBundle: docs-hub
+description: EXCLUSIVE /qa-resolve — close one qa/open file. Prompt is QA id + solution. Do not use for full-screen grill or first-time /spec.
+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.
+
+# /qa-resolve — Close One Open QA
+
+**When:** Member provides `QA-<page-id>-NNNN` (or `QA-<feature.id>-NNNN`) **along with** an explicit decision/solution.
+
+**Not this skill:**
+- Unknown answers needing brainstorming → `/grill-bqa` / `/grill-dev` / `/grill-docs` / `/api-spec`
+- FE delta without an existing QA file → `/update-spec`
+- Portal/BE sync without closing QA files → `/api-update`
+
+**Extract:** `.cursor/extracts/qa-inbox.md`
+
+---
+
+## Rule: Load Policy
+
+| Read (whole file) | Write | NEVER do |
+|---|---|---|
+| `qa/open/<id>.yaml` | Patch `target.path` only | Read generated `*.md` as SSOT |
+| Target bundle **or** `01-backend-spec.yaml` (entire file) | Delete QA file after patch | Author `openQuestions` |
+| `ir/design.yaml` — ONLY to locate field if `at` is a design pointer | `flowgrid split` after patch | Full-screen rewrite (use `/spec`) |
+
+---
+
+## Rule: Missing Solution Handling
+
+- **[MANDATORY]** If user prompt includes a solution → treat as confirmed decision. **Do NOT** re-trigger AskQuestion wizard.
+- **[MANDATORY]** If user prompt provides **no solution**: trigger `AskQuestion` wizard with **≥3 options** (1. Recommended, 2. Other, 3. "Log as Tech Debt") + include `options[]` from the QA file if present. Then **STOP**.
+- **[STRICTLY FORBIDDEN]** Do NOT invent solutions. Do NOT inject business data absent from user prompt.
+
+---
+
+## Rule: Resolving the QA File
+
+- **[MANDATORY]** Step 1: Locate `qa/open/<id>.yaml`. If missing, glob `qa/open/QA-*-NNNN.yaml` matching `id:`.
+  - Zero matches → **STOP**, list available `qa/open/` IDs to user.
+  - Multiple matches → **STOP**, prompt user to clarify which file to close.
+- **[MANDATORY]** Step 2: Read `target.path`, `target.at`, `kind`, `skill`, and `question` from the QA file.
+
+---
+
+## Rule: Patch Logic (One SSOT)
+
+- **[MANDATORY]** Use `target.path` to locate patch destination — never guess path:
+
+  | `target.path` | Patch Action |
+  |---|---|
+  | `*.bundle.yaml` | Patch `target.at` field only. Never patch `spec.api`. |
+  | `…/api/<seq>/01-backend-spec.yaml` or `common/yaml/<slug>/01-backend-spec.yaml` | Patch that `01`. Drop `pendingTechDebt[]` row for this QA id. Regenerate `02` via `flowgrid openapi_gen --spec <01>`. |
+  | Missing / invalid path | **STOP** — do not invent a fallback path. |
+
+- **[MANDATORY]** Post-patch execution:
+  1. Write solution into field at `target.at` (replacing `#missing_info` / empty / placeholder).
+  2. Remove this ID from `#missing_info QA-…`, `#tech-debt:QA-…`, and all tag lists.
+  3. **Delete** `qa/open/<id>.yaml`.
+  4. Run `flowgrid split` / `pnpm docs:split` so `ir/spec.yaml` Q&A removes this ID.
+- **[MANDATORY]** Preserve existing error matrices (`onSuccess` / `onCommonError` / `onSpecificError`, `#err:*`) unless solution specifically alters those fields.
+
+---
+
+## Rule: Out of Scope
+
+- **[STRICTLY FORBIDDEN]** Do NOT close multiple QA IDs in a single invocation (strictly one ID per prompt).
+- **[STRICTLY FORBIDDEN]** No codegen, prototype, or Playwright generation. No inventing API endpoints or UI inventory.
+
+---
+
+## Handoff (after close)
+
+- `01` still missing `codegen.profile` / `#gen:*` / `action` → instruct member to run **`/grill-api-spec`**.
+- `bundle.gen` still empty while grill-dev was pending → **`/grill-dev`**.
+- Otherwise: execution complete.
+
+---
+
+## Verification Checklist
+
+- [ ] Read `qa/open/<id>.yaml`; patched only `target.path` field.
+- [ ] Solution sourced strictly from user prompt (or single AskQuestion turn).
+- [ ] QA file deleted; `pendingTechDebt` + `#missing_info` references removed for this ID.
+- [ ] `flowgrid split` executed; `ir/spec.yaml` Q&A reflects closed status.
+- [ ] Did not author `openQuestions` or `bundle.spec.api`.

package/harness/docs/skills/spec/SKILL.md

@@ -0,0 +1,240 @@
+---
+name: spec
+extractBundle: spec-requirement
+description: EXCLUSIVE /spec — ONLY for authoring design bundle (feature.bundle.yaml). DO NOT trigger for grill or testcase skills.
+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.
+> **[MANDATORY]** Read `.flowgrid/templates/feature.bundle.yaml` + `.flowgrid/templates/bundle-authoring.md` BEFORE generating any YAML.
+> If templates are missing → STOP: *"Template missing. Run `flowgrid init` to generate templates."*
+> Physical interlocks: `AGENTS.md` + `SSOT_AGENT_PROTOCOL.md` (Laws 1–7). Chat-only done = **FAILED**.
+
+# /spec — Function detail (design)
+
+**Mindset:** Author a **complete** bundle from the template when information exists. Build a **dynamic** `design.sections[]` tree for that page; leaf controls in `items[]`. Do **not** copy a login (or any) sample as the default layout.
+
+**Business layer:** Screen `W-*` / API `API-*` inside a module. **Standards:** C4 only (no new arc42 chapters per screen).
+
+---
+
+## Rule: Missing Information Handling & Workload Threshold (Law 2)
+
+- **[MANDATORY]** When required fields are absent from user prompt or context, evaluate total missing items:
+  - **Small Scope (≤5 gaps):** Run `AskQuestion` wizard — **one question at a time**, **≥3 options**: (1) `(Recommended)`, (2) Alternative, (3) `Log as Tech Debt (Pending)`. Show next question only after member answers current one.
+  - **Large Scope (≥10 gaps OR multi-screen scope):** **[MANDATORY HARD STOP IN CHAT]**. Do not spam single questions in chat. Generate an implementation plan / Plan Mode document partitioned into Phases (3–5 questions/fields per phase) to prevent session token overflow.
+  - ❌ Never invent, assume, or silently skip missing fields.
+- **[MANDATORY]** If member chooses "Log as Tech Debt" → create `qa/open/QA-<page-id>-NNNN.yaml` + tag `#missing_info QA-…`. Do not block on it.
+- **[RECOMMENDED]** Brainstorm business text (context, input, output, screen descriptions) proactively in Vietnamese for Non-tech audience — do not wait to be told.
+
+---
+
+## Rule: Page Type Detection
+
+- **[MANDATORY]** Before running audit or bundle generation, the Agent **MUST** detect the page type:
+  - Read `gen.codegen.profile` inside existing bundle (if present).
+  - OR infer from prompt keywords:
+    - "list", "table", "danh sách" → `list`
+    - "form", "create", "new", "tạo mới" → `create`
+    - "detail", "view", "chi tiết" → `detail`
+    - "login", "auth", "đăng nhập" → `auth`
+    - "CRUD", "management", "quản lý" → `admin-crud`
+  - The detected page type is passed to: `--type` audit script parameter + zone-based analysis partitioning.
+
+---
+
+## Rule: Audit Interlock
+
+- **[MANDATORY]** If bundle file already exists: run `flowgrid audit spec <path-to-bundle.yaml> --type <pageType>` first.
+  - `<pageType>` = page type đã xác định ở bước trên (list | create | detail | admin-crud | auth | ...).
+  - Script output:
+    - `gaps[]` → required fields missing → Agent patches bundle directly.
+    - `confirms[]` → optional / UX (`category: ux`, codes `UX_*`, `CONFIRM_UX_*`) → AskQuestion; `(Recommended)` must match audit option text or `flowgrid-ux-common` checklist proposals.
+    - Summary fields: `uxAffordanceGaps`, `uxAffordanceConfirms`.
+  - **Threshold Interlock (Law 2):** If audit script outputs ≥10 gaps + confirms, HALT chat wizard immediately → create an implementation plan / Plan Mode document partitioned into sequential phases.
+  - ❌ Do not skip audit and proceed to authoring directly.
+  - ❌ Do not run audit without `--type` parameter.
+
+---
+
+## Rule: Common Catalog Reuse (Anti-Copy-Paste Guard)
+
+- **[MANDATORY]** When authoring or updating specs (`/spec`, `/legacy /spec`), Agent **MUST inspect Section 5 (Common Catalog Candidates)** inside `adoption-inventory.md` (if present).
+- **[ANTI-COPY-PASTE ENFORCEMENT]**: 
+  - If the new feature or screen uses UI Controls, API Handlers, or DTOs already defined in the Common Catalog (`CMN-UI-*`, `CMN-API-*`, `CMN-DTO-*`), the Agent **MUST reference and inherit these Common codes/specs**.
+  - **STRICTLY FORBIDDEN to copy-paste legacy code/specs into isolated new classes/files** in the new project.
+
+---
+
+## Rule: Target / ID Resolution
+
+- **[MANDATORY]** Resolve screen ID, module ID, slug, or Draft ID before generating any file.
+  - Draft ID `1-1-2` → pad each segment → `01/01/02/`
+  - Bundle ID: module prefix + padded segments, e.g. `CMP-ADM-002` + `02-01-02` → `page-id: cmp-adm-002-02-01-02`
+- **[MANDATORY]** Search for input `.md` file at resolved path. If found, read it as primary requirement source — do NOT say "I cannot hallucinate" or ask user for input that is already present.
+- **[STRICTLY FORBIDDEN]** Do NOT demand full filesystem path from user when ID or slug is given.
+
+---
+
+## Rule: Load Policy
+
+- **[MANDATORY]** Write the **entire** `*.bundle.yaml` (authoring SSOT).
+- **[MANDATORY]** After split exists: re-read **entire** `ir/design.yaml` + `ir/spec.yaml`; do not skim partial keys.
+- **[STRICTLY FORBIDDEN]** Do NOT read generated `*.md` files.
+
+---
+
+## Workflow
+
+1. Confirm `CMP-*` exists and `CTR-*` is identified — otherwise stop for lead/owner.
+2. Detect page type from prompt or existing bundle's `codegen.profile`.
+3. Run audit: `flowgrid audit spec <bundle> --type <pageType>` (if bundle exists).
+4. Process audit output: fill `gaps[]` directly; ask member about `confirms[]` via wizard.
+5. **Zone-based multi-turn authoring** (see rule below): chia page thành zones, phân tích từng zone trong turn riêng.
+6. Write/update `*.bundle.yaml` with `specOrigin: requirement`.
+7. Apply **existing** common/DSL extracts (consume only — promote via `/common-spec`).
+8. Run `pnpm docs:split -- <bundle>` → `pnpm docs:render` (design MD only).
+9. Update `.harness/progress.md`.
+10. Handoff → `/testcase` from acceptance criteria.
+
+---
+
+## Rule: Zone-Based Multi-Turn Analysis (anti lost-in-middle)
+
+- **[MANDATORY]** Do not analyze and write the full page in a single turn.
+- **[MANDATORY]** Split the page into **dynamic zones** from the real bundle content (not a fixed template). Examples: HEADER (title, breadcrumb, summary), CONTENT slices (toolbar, table, form groups), FOOTER/ACTIONS (pagination, stateMatrix, outcomes).
+- **[MANDATORY]** If one zone is too large (>5 fields, >3 sections, >2 relationships) → split into sub-zones.
+
+### Per-zone pipeline (DSL first, then UX gaps)
+
+Each zone turn — **in order**:
+
+1. Announce zone name (e.g. `Zone CONTENT: toolbar + table`).
+2. **DSL / registry pass:** Match controls to `design.registry.json` (when present), common catalog, `#shell:`, `#pattern:`, `#ui:`, `#widget:`. Write matched structure into `*.bundle.yaml` for this zone.
+3. **Unmapped structure:** Shadcn primitive → `#ui: <Primitive>`. ≥2 domain structural blocks → `#needs-component: MoBlockName`. Unknown widget → `#needs-ui:` (never invent primitive names). See **Common Pattern Resolution** below.
+4. **Affordance gaps** (still unmapped or thin spec): apply **`flowgrid-ux-common.mdc`** + `.cursor/extracts/ux-common-patterns.md` — only **Recognize / Propose** checklist items that apply; use the rule’s proposal output format. No open-ended UX brainstorming.
+5. **Member decisions:** `confirms[]` from audit + any checklist-derived proposals → `AskQuestion` wizard — one question at a time, ≥3 options: `(Recommended)` = top structured proposal from steps 3–4, Alternative, `Log as Tech Debt (Pending)` (Law 2).
+6. Persist zone YAML; update matching **`userStories.scenarios` steps** and **`acceptanceCriteria`** (Vietnamese business prose) for the same affordance — see `bundle-authoring.md` § UX affordance ↔ userStories.
+7. Proceed to next zone.
+
+- **[STRICTLY FORBIDDEN]** All-in-one zone dumps. Redundant YAML for patterns already covered by DSL. AskQuestion options not grounded in DSL mapping, audit output, or UX checklists. **Tech-only `design` patches without `userStories` sync before split.**
+
+---
+
+## Rule: Content Requirements per Section
+
+### Rule: User Stories (`userStories`)
+- **[MANDATORY]** Generate complete `primary` (asA, iWant, soThat), `contextAndHandoff`, `scenarios` (5 core + **6th “Affordances UX”** when delete/filter/breadcrumb/disabled/import apply), `acceptanceCriteria` (include UX AC lines from template when applicable).
+- **[MANDATORY]** After resolving audit `UX_*` gaps or `CONFIRM_UX_*` answers: mirror behavior in `userStories` (use `suggestedStoryPatch` from audit JSON when present).
+- **[MANDATORY]** `contextAndHandoff.screenAccess` MUST be one of: `directRoute` | `sidebarMenu` | `contextualAction`.
+- **[MANDATORY]** 5 scenarios: (1) Initial data load, (2) Input entry & Form validation errors, (3) Successful submission, (4) Exception handling / UI error states, (5) Background operations (if applicable). All descriptive texts generated for user consumption MUST be in clear Vietnamese.
+
+### Rule: Meaning vs Purpose
+- **[MANDATORY]** Every section, item, column, filter, action MUST declare both:
+  - `meaning`: Business essence / meaning (value delivered, which workflow it impacts).
+  - `purpose`: Interaction purpose (what user does with this control on the UI).
+  - ✅ `meaning: "Xác nhận danh tính thành viên"` / `purpose: "Nhập email đăng nhập"`
+  - ❌ `meaning: "Email field"` — too generic; not business-meaningful.
+
+### Rule: UI Section Attributes & Custom Component Deep-Grill
+- **Reusable / Base Components (Shadcn UI & Base Kit):**
+  - If a component/section uses an existing base component or Shadcn primitive:
+    - Declare `primitive`: Shadcn tag (`#ui: Card`, `#ui: Form`, `#ui: Table`, `#ui: Dialog`, `#ui: Select`, `#ui: Input`, `#ui: Badge`, …).
+    - Declare `visual.colorToken` (e.g. `#common:card-surface`, `#common:primary`) and standard Tailwind layout classes.
+- **New / Custom Non-standard UI Blocks (`custom` / Novel Widgets):**
+  - **[MANDATORY DEEP-GRILL INTERLOCK]**: Whenever a UI section or component is novel, custom, or not in the standard base library, the Agent **STRICTLY FORBIDDEN** from leaving vague descriptions. The Agent MUST deeply drill down and specify:
+    1. **`customWidgetType`**: Exact functional archetype (e.g. `interactive-timeline`, `kanban-lane`, `drag-drop-uploader`, `signature-pad`).
+    2. **Dimension & Geometry Specifications**: Explicit width, height, min/max constraints, aspect ratio, responsive breakpoints (`mobileBreakpoints`, `desktopLayout`).
+    3. **Color & Surface Palette**: Exact token hierarchy — `backgroundToken`, `borderToken`, `accentToken`, `hoverStateColor`, `activeStateColor`, and dark/light contrast semantics.
+    4. **Typography & Text Metrics**: Header hierarchy (`h1`-`h6`), font-weight, line-height, text truncation behavior (`truncate`, `line-clamp-2`).
+    5. **Micro-Interactions & States**: Loading skeleton structure, empty/error state UI, hover transition curves, and disabled visual opacity.
+- **[PROACTIVE OPTIONS ONLY]**: Novel custom blocks without dimensions/colors → propose 2–3 concrete specs (design tokens) via `AskQuestion`; `(Recommended)` must be one of those specs — not vague “how should this look?” prompts. Affordance gaps (breadcrumb, delete feedback, disabled reason, …) → `flowgrid-ux-common.mdc` checklists, not ad-hoc UX ideas.
+
+### Rule: Dynamic 5-Tier Validation & Messages
+- **[MANDATORY]** Never accept superficial `validation: { required: true }`. The Agent **MUST proactively brainstorm and specify** the full 5-tier validation profile for all form fields:
+  1. **Prototype format:** Assign standard presets (`email`, `phone_vn`, `tax_code`, `slug_uppercase`, `currency_vnd`, `date_range`, `password_strong`).
+  2. **Boundary limits:** Explicit `min` / `max` length or numeric values.
+  3. **Conditional & Cross-field dependencies:** Declare `conditionalRules` (`requiredWhen`, `disabledWhen`, `greaterThan`).
+  4. **Remote / Async verification:** Declare `remoteCheck` for unique DB constraints (endpoint, trigger `onBlur`, debounce, params).
+  5. **Explicit Vietnamese error copy:** Every single rule MUST declare its exact human-readable error message.
+- **[PROACTIVE AI BRAINSTORMING INTERLOCK]**: When user inputs are sparse, the Agent **STRICTLY FORBIDDEN** from leaving fields minimally validated. The Agent MUST actively infer and propose realistic validation rules and confirm with user via Wizard options.
+
+### Rule: Action Flow Specification (6 Mandatory Technical Blocks)
+- **[MANDATORY]** Every mutation/submit button MUST specify all 6 technical blocks:
+  1. `preconditions`: UI form validity, record lifecycle status (`record.status in [...]`), required RBAC permissions, and `disabledReason`.
+  2. `interactionControl`: `preventDoubleSubmit: true` (immediate button lock), `debounceMs`, `loadingIndicator` text, and `confirmDialog` (for destructive actions).
+  3. `payloadTransformation`: String trimming, XSS sanitation, and type casting rules (e.g. currency string $\to$ integer).
+  4. `executionContract`: Target `apiRef`, HTTP method, `idempotencyKey` header, timeout SLA, and concurrency strategy (`optimistic_locking`).
+  5. `outcomes`: 4-tier matrix:
+     - `onSuccess`: Toast copy, navigation target, background event dispatch.
+     - `onBusinessErrors` (422, 409): Field-level inline error mapping and duplicate warnings.
+     - `onSecurityErrors` (401, 403): Session expiry localStorage preservation and IDOR safety redirects.
+     - `onSystemErrors` (500, 504, Client Offline): Timeout resubmit lock, offline data preservation banner.
+  6. `stateMatrix`: Link action behavior with screen record status and role permission visibility.
+- **[STRICTLY FORBIDDEN]** Do NOT skip concurrency, double-submit protection, or network timeout handling.
+
+### Rule: Layout Structure
+- **[MANDATORY]** Map every visible control into nested `design.sections[]` (or flat `zones[]`).
+- **[MANDATORY]** App pages: declare `design.nav.sidebar.levels` + breadcrumb.
+- **[MANDATORY]** API endpoints → `/api-spec` (not `spec.api` on this bundle).
+
+---
+
+## Rule: Common Pattern Resolution (DSL consume)
+
+- **[MANDATORY]** Before authoring each zone: scan upward `common/yaml/` (function → module → cluster → surface → global); read `templates/shared/patterns/*.pattern.yaml`; match `design.registry.json` when the FE checkout pointer exists.
+- **[MANDATORY]** Tag from structural cues only (never invented business fields):
+  - `>8 columns` → `#split-hook:columns`; `>3 filters` → `#split-hook:filters`; export → `#split-hook:export`; form >6 fields → `#split-hook:form-sections`
+  - `≥2 domain structural blocks` → `#needs-component: MoBlockName` (NOT shadcn primitives)
+  - Delete → `#pattern: delete-flow`; list/table → `#pattern: CRUD`; confirm/overwrite → `common-confirm-dialog`
+- **[MANDATORY]** Inject resolved patterns into `design.patterns[]` and zone `items[]` with `#ui:` / `#widget:` as applicable.
+- **[STRICTLY FORBIDDEN]** Tag shadcn primitives as `#needs-component`. Duplicate full common IR into the screen bundle when DSL already covers the widget.
+
+---
+
+## Rule: YAML Authoring Safety
+
+- **[MANDATORY]** Output MUST be `*.bundle.yaml`. Do NOT write `.md` directly — Markdown is generated by `pnpm docs:split`.
+- **[MANDATORY]** All strings with `:`, `[]`, or leading symbols MUST be double-quoted or use YAML block scalar (`|`).
+  - ✅ `summary: "Màn hình: Đăng nhập hệ thống"`
+  - ❌ `summary: Màn hình: Đăng nhập`
+- **[MANDATORY]** File path: `surfaces/<surface>/CMP-*/<NN>/<NN>/<NN>/<slug>.bundle.yaml` (numeric segments, no text in path).
+
+---
+
+## Modifiers
+
+### `/legacy` modifier
+- **[MANDATORY]** Lookup `adoption-inventory.md` at workspace root. If missing → STOP: *"Run `/docs-hub /adopt` first."*
+- **[MANDATORY]** Set `specOrigin: legacy`; use legacy source path from inventory mapping.
+- **[STRICTLY FORBIDDEN]** Do NOT read `adoption-inventory.md` for Greenfield (non-legacy) commands.
+
+---
+
+## Tools
+
+- `flowgrid_docs_bundle_split` / `flowgrid split -- <bundle>` (prefer MCP when installed)
+- `docs_render` / `flowgrid render …`
+- Local fallback: `pnpm docs:split` · `pnpm docs:render`
+
+---
+
+## Verification Checklist
+
+- [ ] Module `CMP-*` confirmed; `CTR-*` identified.
+- [ ] Audit script run (if bundle existed); all gaps resolved or QA-tagged.
+- [ ] `userStories`: 5 scenarios + `screenAccess` typed + `acceptanceCriteria` present.
+- [ ] `meaning` + `purpose` on every section, item, column, action.
+- [ ] Shadcn `primitive` + `visual.className` + `states` on every `design.sections[]` block.
+- [ ] Dynamic 5-Tier Validator: `prototype`, boundaries (`min`/`max`), regex/format, `conditionalRules`, `remoteCheck` DB unique.
+- [ ] `validation.messages` in Vietnamese on every validated field (no vague error text).
+- [ ] `stateMatrix` defined: Record Status ↔ Fields State ↔ Visible Buttons ↔ RBAC Overrides.
+- [ ] 6-Block Action Flows specified: Preconditions, Interaction Lock (Double-submit), Payload Transform, API Contract, 4-Tier Outcomes Matrix (Success, 422/409, 401/403, 500/504/Offline).
+- [ ] Custom UI Blocks: Dimensions, Palette semantic tokens, Typography, and Micro-interactions defined if novel.
+- [ ] Common patterns tagged in `design.patterns[]`; DSL-mapped zones written; `#needs-component` / `#needs-ui` only where registry/common does not cover.
+- [ ] UX gap questions used checklist-backed `(Recommended)` options (`flowgrid-ux-common.mdc`), not open brainstorming.
+- [ ] `userStories` scenarios/AC reflect UX affordances patched in `design` (incl. audit `suggestedStoryPatch`).
+- [ ] YAML strings with `:` or `[]` are double-quoted. No `.md` written by hand.
+- [ ] `pnpm docs:split` + `pnpm docs:render` run with zero errors; rendered `spec.md` verified clean of raw YAML dumps.
+- [ ] Handoff → `/testcase` created.

package/harness/docs/skills/surfaces/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: surfaces
+description: "/surfaces — Manage business/interaction surfaces (who does what on which channel)."
+disable-model-invocation: true
+extractBundle: architecture-core
+---
+
+> [!CRITICAL] MANDATORY PRE-FLIGHT
+> **[MANDATORY]** Re-read this entire `SKILL.md` via file-read tool. STRICTLY FORBIDDEN to rely on memory.
+
+# /surfaces — Business/Interaction Surfaces
+
+**Definition:** A surface = business interface or interaction channel (Admin Portal, Customer Web, Mobile App, Integration Gateway) — NOT a repository or project.
+
+---
+
+## Rule: Target Resolution
+
+- **[MANDATORY]** Use `flowgrid_docs_route` or `flowgrid_docs_get_element` (or glob) to resolve the target surface directory under `surfaces/[Surface Name]/`.
+- **[STRICTLY FORBIDDEN]** Do NOT confuse an API with a surface. APIs belong to architecture containers or function-level API contracts.
+
+---
+
+## Rule: `common` Scope
+
+- **[MANDATORY]** `surfaces/common` — ONLY when a rule/API is used by **≥2 surfaces**. Never use as a default dumping ground.
+- **[MANDATORY]** `surfaces/[Surface]/common` — share between modules on this specific surface (not within a single `CMP-*`).
+- For sharing within one `CMP-*` → use `/module CMP-… common`.
+
+---
+
+## Rule: Overview Alignment
+
+- **[MANDATORY]** When authoring a surface overview, describe: target actors, their actions, interaction channels, and assigned business responsibilities. Keep descriptions in business terms rather than technical architecture.
+- **[MANDATORY]** Surface technical boundary: UI layout, component states, props, single-API data schemas specific to that screen.
+- **[STRICTLY FORBIDDEN]** Do NOT include system-level architecture details (backend server configuration, load balancers, database schemas) in surface documentation.
+
+---
+
+## Modifier: `/legacy`
+
+- **[MANDATORY]** If `adoption-inventory.md` is missing at workspace root → STOP: *"Run `/docs-hub /adopt` first."*
+- **[MANDATORY]** If file exists: look up surface ID → get legacy app/repo path → write `surfaces/[Surface]/legacy-surface.md`.
+- **[STRICTLY FORBIDDEN]** Do NOT read `adoption-inventory.md` for Greenfield commands.
+
+---
+
+## Verification Checklist
+
+- [ ] Target surface folder located or created under `surfaces/[Surface Name]/`.
+- [ ] Business responsibilities (actors, channels, scope) documented in business language.
+- [ ] `surfaces/common` reserved strictly for rules shared across ≥2 surfaces.

package/harness/docs/skills/update-spec/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: update-spec
+extractBundle: update-spec
+description: /update-spec — delta update bundle/spec.
+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.
+
+# /update-spec — Controlled Spec Delta
+
+**Extracts:** `extractBundle: update-spec` → `.cursor/extracts/extract-registry.docs.json`
+Doc hub: `platform/toolchain/UPDATE-SPEC-FLOW.md` · `platform/toolchain/FEATURE-ARTIFACT-FLOWS.md`
+
+---
+
+## Rule: Load Policy
+
+| Read (whole file) | Write | NEVER |
+|---|---|---|
+| **`ir/design.yaml`** — current tech/UI | Patch `*.bundle.yaml` → then split | Write generated `*.md`; write to `ir/*` directly |
+| **`ir/spec.yaml`** — ONLY when delta involves requirements/acceptance prose | | Read only `design.sections` / `spec.ui` partial slices |
+
+---
+
+## Rule: Scope Boundaries
+
+- **[MANDATORY]** Scope: patch bundle (delta only); emit `#update:*` tags; bump `specRevision`; run `flowgrid split/check`.
+- **[STRICTLY FORBIDDEN]** Full rewrite → `/spec`. Close `qa/open` item → `/qa-resolve`. Legacy re-mine → `/update-spec-legacy`. Production code → NOT this skill.
+
+---
+
+## Rule: Missing Information Handling & Workload Threshold (Law 2)
+
+- **[MANDATORY]** Gaps or ambiguity regarding delta scope, evaluate total gap volume:
+  - **Small Scope (≤5 questions):** Trigger `AskQuestion` wizard — one question at a time, **≥3 options**: (1) `(Recommended)`, (2) `Other`, (3) `Log as Tech Debt (Pending)`.
+  - **Large Scope (≥10 gaps):** **[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 gaps per phase) with disk offloading at boundaries.
+  - ✅ If "Log as Tech Debt" is selected → create `qa/open/` entry; do not invent business data.
+  - ❌ Never invent delta scope or novel business fields without explicit user confirmation.
+- Path SSOT: `surfaces/<surface>/CMP-*/<slug>/` — NO `modules/` segment.
+
+---
+
+## Rule: Patch Guardrails
+
+- **[MANDATORY]** Patch minimal YAML sections in **bundle** only (not `ir/*`).
+- **[MANDATORY]** When the delta touches `design.actions`, `design.sections`, or `spec.ui` (list/form/detail, filters, row actions): run the **UX ↔ userStories** checklist in `templates/shared/bundle-authoring.md` — sync `userStories.scenarios` / `acceptanceCriteria` prose when behavior or affordances change (do not leave business story stale).
+- **[MANDATORY]** Before split/merge: run `flowgrid audit spec <bundle.yaml> --type <pageType>` and resolve or explicitly defer `UX_*` / gap codes; do not hand off FE/tests with a fresh structural delta and no re-audit.
+- **[MANDATORY]** Preserve error matrices: when patching actions/API endpoints, ensure `onSuccess`, `onCommonError`, `onSpecificError` + `#err:*` tags are preserved and updated accordingly.
+  - ✅ Add new `onSpecificError.409` entry alongside existing `onSuccess` block.
+  - ❌ Overwrite or delete existing error handling blocks that are unrelated to this delta.
+- **[MANDATORY]** If `featureStatus` was `wire` → update to `need-update`.
+- **[STRICTLY FORBIDDEN]** Do NOT add `codegen` / `gen:` blocks without Dev alignment — hand off to `/grill-dev` instead.
+- **[STRICTLY FORBIDDEN]** Do NOT strip legacy evidence or unrelated blocks.
+- **[STRICTLY FORBIDDEN]** Do NOT clear `#update:*` tags — those are cleared exclusively at `/wire`.
+
+---
+
+## Workflow
+
+1. Identify delta scope (one scenario / block / API field at a time).
+2. Patch minimal YAML sections in bundle per `spec-update-delta.md` (not `ir/*`).
+3. Emit matching `#update:*` tags; bump `specRevision`.
+4. Update `featureStatus` if needed.
+5. Record harness notes when present.
+6. `flowgrid audit spec <bundle.yaml> --type <pageType>` — mandatory after delta (see Patch Guardrails).
+7. `flowgrid_docs_bundle_split` / `flowgrid split -- <bundle>` (fallback: `pnpm docs:split`).
+8. `flowgrid_docs_bundle_check` / `flowgrid split --check -- <bundle>` (fallback: `pnpm docs:check`).
+9. User runs `docs_render` / `flowgrid render` (fallback: `pnpm docs:render`).
+10. Follow-up per patch type: handoff FE `/prototype` or `/grill-dev` / `/grill-bqa`; if API contract changed → `/api-update` before `openapi:gen`.
+
+---
+
+## Verification Checklist
+
+- [ ] Delta scoped to one scenario/block/field.
+- [ ] Patched bundle only (not `ir/*` directly).
+- [ ] `#update:*` tags emitted; `specRevision` bumped.
+- [ ] Error matrices (`onSuccess`, `onCommonError`, `onSpecificError`, `#err:*`) preserved and updated.
+- [ ] `flowgrid audit spec` re-run after delta; UX/gap codes addressed or deferred.
+- [ ] `flowgrid split` + `flowgrid split --check` passed with zero errors.
+- [ ] No `codegen` / `gen` added without `/grill-dev` handoff.

package/harness/fe/adapters/dotnet-line/skills/framework-rules/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: framework-rules
+description: .NET Line (WinForms) client conventions — gen-first, thin UI, clear boundaries
+disable-model-invocation: true
+---
+
+# Platform Base (.NET Line / WinForms)
+
+**Owner:** Platform DNA (`--type=fe|monolith --fe-adapter=dotnet-line`)
+
+WinForms Line client · bộ code grill/gen first when applicable.  
+Not Nuxt/Next — do not apply web FE layer rules here.
+
+## Gen trước (code)
+
+1. Prefer codegen / existing Line templates before free-form UI scaffolding
+2. AI fills gaps only — do not duplicate generated surfaces
+
+## Boundaries
+
+- Keep UI (forms/controls) thin; push rules into services/view-models as the stack already does
+- Prefer existing Line module/layout conventions in this repo over inventing new trees
+
+## Checklist
+
+- [ ] No web FE assumptions (no Pinia / Playwright / `$apiFetch` patterns)
+- [ ] Contracts align with docs / Integration BE when present

package/harness/fe/adapters/nextjs/skills/framework-rules/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: framework-rules
+description: Next.js FE conventions — layers, testId, gen-first; see invariants (glob)
+disable-model-invocation: true
+---
+
+# Platform Base (Next.js FE)
+
+**Owner:** Platform DNA (`--type=fe --adapter=nextjs`)
+
+Auth-first Next.js · App Router · shadcn · Playwright. Code under `src/`.
+
+**Rules (FE globs):** `platform-invariants.mdc` · contract-naming · `framework-rules-*` · size/split/import · design-vocab (product repo).
+
+## Gen trước (code)
+
+1. bộ code `gen` / repo shim from IR already grilled
+2. AI only fills gaps: Mo* / `#needs-*` not yet in registries
+3. Do not write boilerplate when codegen already covers it
+
+## Layers
+
+`app|pages/components` → hooks/composables → services → models/validations → `apiFetch`  
+Form + contract follow the stack in this repo. testId + Playwright: `/test`.
+
+## Checklist
+
+- [ ] Clean layers · testId on interactive controls
+- [ ] E2E scripts → `/test`; plans YAML on tests hub

package/harness/fe/adapters/nuxt4/skills/framework-rules/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: framework-rules
+description: Nuxt 4 FE conventions — layers, testId, gen-first; see invariants (glob)
+disable-model-invocation: true
+---
+
+# Platform Base (Nuxt 4 FE)
+
+**Owner:** Platform DNA (`--type=fe --adapter=nuxt4`)
+
+Auth-first Nuxt 4 · Pinia · vee-validate+Zod · shadcn · Playwright.
+
+**Rules (FE globs):** `platform-invariants.mdc` · `platform-contract-naming.mdc` · `framework-rules-*` · size/split/import · design-vocab (product repo).
+
+## Gen trước (code)
+
+1. bộ code `gen` / repo shim from IR already grilled
+2. AI only fills gaps: Mo* / `#needs-*` not yet in `registries/`
+3. Do not write layer boilerplate when codegen already covers it
+
+## Layers
+
+`pages/components` → `composables` → `services`+`stores` → `models`+`validations` → `$apiFetch`  
+No `$apiFetch` in page/component. Form: `useApiForm`.
+
+UI: `ui/` → `Mo*` → `Data*|OrGlobal*` · shell `DataListPage`.
+
+testId: `{module}-{field|action}-input|btn|dialog|alert` · `page.getByTestId()`.
+
+## Checklist
+
+- [ ] 4 layers · lean files · testId on interactive controls
+- [ ] E2E scripts → `/test` (Playwright); plans YAML live on tests hub