feat: sync:commands pipeline + Pi agents como ponteiros canônicos

CLAUDE.md

@@ -36,6 +36,7 @@ keys or extra usage).
 npm test          # full suite (node test/run.mjs)
 npm run lint      # eslint
 npm run sync:skills   # regenerates .cursor/skills mirrors (never edit those by hand)
+npm run sync:commands # regenerates .cursor/commands from .claude + overlays
 ```
 
 ## Hard rules

DOCS.md

@@ -955,7 +955,7 @@ Going live and meta:
 | Command | What it does |
 | --- | --- |
 | `/launch` | From "runs on my machine" to LIVE, in rungs: **Ready** gate (lint/typecheck/test/build green, pushed, CI green) → **Safe** gate (the security skill's checklist walked top to bottom; two hard stops: open data-ownership and any committed secret) → **BETA** (public vercel.app + production backend: Convex prod deploy key, env promotion, deploy, smoke test) → **PRODUCTION** (own domain, `pk_live_`/`sk_live_`, prod webhooks, live payments with one real tested charge). Uses `node imp/scripts/fia-launch-check.mjs --json` as the source of truth when the FIA is installed; everything logged in `ai-docs/launch.md`; every outward step needs an explicit "yes". |
-| `/create-command [name] [description]` | Scaffolds a new professionally-structured slash command in `.claude/commands/` and mirrors it to `.cursor/commands/`. |
+| `/create-command [name] [description]` | Scaffolds a new professionally-structured slash command in `.claude/commands/`, registers it in `scripts/command-overlays.yaml`, and regenerates the Cursor twin via `npm run sync:commands`. |
 
 Every command that generates durable docs commits them via
 `node imp/scripts/docs-commit.mjs` (when the FIA is present) and guards its
@@ -2955,6 +2955,7 @@ node bin/create-iai.js my-test            # runs the installer locally
 npm test                                    # node --test (CLI unit tests)
 npm run lint && npm run format
 npm run sync:skills                         # regenerate harness/.cursor/skills
+npm run sync:commands                       # regenerate harness/.cursor/commands
 ```
 
 **Mirror rule (single source of truth):** shared skills are edited ONLY in
@@ -2966,15 +2967,21 @@ stamped project (Claude Code gets a symlink of its own to the same store).
 `test/consistency.test.js` fails on skill drift and `sync:skills:check`
 reports it without writing. Agents are the other way around: edit
 `harness/.claude/agents/`; `.cursor/agents/` and `.agents/agents/` are
-file symlinks to it. Commands (`.claude/commands` ↔ `.cursor/commands`)
-stay manual on purpose: their diffs are intentional (frontmatter,
-`.claude→.cursor` paths, Cursor-only extras like `bugbot`);
-`.agents/commands/` links at the Cursor copy. Cross-runtime knowledge
-follows the same principle: one canonical file + pointers (the
-semantic-fields catalog and the interaction catalog in the design-system
-skill; `test/semantic-fields.test.js` and `test/interaction-contracts.test.js`
-are the tripwires that no runtime — including the `.agents/` path Cursor
-actually opens — loses its pointer).
+file symlinks to it. Shared commands are edited ONLY in
+`harness/.claude/commands/` — `harness/.cursor/commands/` is GENERATED by
+`npm run sync:commands` from `scripts/command-overlays.yaml` (Cursor
+frontmatter plus intentional patchlets like `AskQuestion`, `bugbot`, and
+`.claude→.cursor` skill paths); `.agents/commands/` links at the Cursor
+copy. Pi harness agents (`.pi/agents/<name>.md` for the nine start/kit
+roster entries) are thin wrappers: FIA frontmatter + a pointer to
+`.claude/agents/<name>.md` — the rehearsal lives in one place. FIA-only
+agents (planner, builder, scout, reviewer, documenter) stay self-contained.
+`test/sync-commands.test.js` is the tripwire for command drift and Pi
+pointer regressions. Cross-runtime knowledge follows the same principle: one
+canonical file + pointers (the semantic-fields catalog and the interaction
+catalog in the design-system skill; `test/semantic-fields.test.js` and
+`test/interaction-contracts.test.js` are the tripwires that no runtime —
+including the `.agents/` path Cursor actually opens — loses its pointer).
 
 Structure: `bin/` (entrypoints: `create-iai.js` = `npx impactus`, `imp.js` =
 the launcher) · `src/main.js` (pipeline) · `src/config.js` (catalogs:

package.json

@@ -14,6 +14,8 @@
     "test": "node test/run.mjs",
     "sync:skills": "node scripts/sync-skills.mjs",
     "sync:skills:check": "node scripts/sync-skills.mjs --check",
+    "sync:commands": "node scripts/sync-commands.mjs",
+    "sync:commands:check": "node scripts/sync-commands.mjs --check",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
     "format": "prettier --write ."

pi-templates/.pi/agents/api-docs-researcher.md

@@ -7,6 +7,8 @@ thinking: medium
 inheritProjectContext: true
 ---
 
-You are the harness api-docs-researcher adapted for the FIA roster. Read `ai-docs/start.md` (or `ai-docs/map.yaml`) for project context, research the requested API (official docs first; use `web_search` to locate current pages and `fetch_content` to read them live), and write `ai-docs/apis/<api>.md`: auth, the endpoints THIS project needs, request/response examples, rate limits, and error handling — tailored to the project's use case, not a generic dump. Documentation only.
+You are the FIA roster entry for the **api-docs-researcher** harness agent.
 
-When the brief asks for tooling research (/stack always does), also check the FOUR dimensions — docs (+ `llms.txt` probe), official agent skills (`https://skills.sh/<org>`), official CLI (verify npm packages with `npm view <pkg> version`), official MCP server — and log each one right after checking it: `node imp/scripts/stack-research.mjs log <tech> --dim <d> --found "…" --source <url>` (or `--none --source <url>`). Never log from memory; every dimension needs a real source. Summarize the four rows in the doc's **Tooling** section.
+**Canonical prompt:** read and follow `.claude/agents/api-docs-researcher.md` in full. That file is the single source of truth for behavior, checklists, and contracts — do not restate or shorten it here.
+
+Runtime notes for Pi: use the tools in this frontmatter; when the FIA is installed, `imp/` paths and gates in the canonical prompt apply.

pi-templates/.pi/agents/component-architect.md

@@ -7,4 +7,8 @@ thinking: high
 inheritProjectContext: true
 ---
 
-You are the harness component-architect adapted for the FIA roster. FIRST seed the CORE KIT — always, before any app-specific analysis. No runnable scaffold (true greenfield): every row of `.claude/skills/design-system/references/core-kit.md` (buttons, inputs, MaskedInput, Select, Combobox, MultiSelect, DateInput/DatePicker/DateTimePicker, menus incl. ContextMenu, dialogs, toast, Skeleton, EmptyState, and the project `DataTable` on TanStack Table as `default` with REUI Data Grid as `alternative`) enters the registry as `planned` regardless of what map.yaml shows — the always-needed components are built up front by the `Kind: kit` task, never lazily by a feature task. A scaffold/codebase already exists (template install, `/kit` inventory, `/absorb`): seed AS-BUILT — one `installed` row per component the code actually has (real paths; duplicates for the same need → record both and flag), and `planned` rows only for needs the PRD/map data model shows; speculative needs enter through `/kit`'s gap audit, never by default. On a non-default stack keep every NEED and swap Origin/File/Install per `ai-docs/stack.md`. Then analyze `ai-docs/map.yaml` and existing docs in `ai-docs/components/`, and produce `ai-docs/components/ideal-components.md`: the full inventory of reusable components the app needs (forms with Zod validation, shadcn-based, accessible), each with props, variants, and usage guidance — tables default to the project DataTable's full contract (global fuzzy multi-word search with yellow highlights; header menu on click AND right-click; per-column type-adapted filters; a single Filter control + chips with an x — never a toolbar row of per-column filter buttons; visibility; pagination; selection + bulk bar; skeleton/empty/no-results; design-system `references/interaction.md`), never to REUI unless a screen explicitly asks. Then seed/update `ai-docs/components/registry.md` from that inventory: one row per component in the markdown table between the `<!-- registry:start -->` / `<!-- registry:end -->` markers (columns Component | Category | Origin | File | Install | URL | Status | Role | When to use), status `installed` for components the code already has and `planned` otherwise, role `default`/`alternative` when two entries serve the same need — the task briefs' reuse lock depends on this registry being seeded. Specification only — implementation belongs to FDAs or ui-component-page.
+You are the FIA roster entry for the **component-architect** harness agent.
+
+**Canonical prompt:** read and follow `.claude/agents/component-architect.md` in full. That file is the single source of truth for behavior, checklists, and contracts — do not restate or shorten it here.
+
+Runtime notes for Pi: use the tools in this frontmatter; when the FIA is installed, `imp/` paths and gates in the canonical prompt apply.

pi-templates/.pi/agents/screen-routes-generator.md

@@ -7,4 +7,8 @@ thinking: medium
 inheritProjectContext: true
 ---
 
-You are the harness screen-routes-generator adapted for the FIA roster. Read the PRD (`ai-docs/PRD.md`, or `ai-docs/prd.md` if that's the one that exists) and produce `ai-docs/screens-routes.md`: every screen, its route, navigation flow, per-screen components, and current implementation status found in the codebase. Output contract: routes go in markdown tables with columns `Route | Screen Component | File Location | Auth Required | Status`, status marked ✅ implemented / 🔄 partial / ⏳ to be implemented — the FIA viewer's Plan view parses exactly this shape. Documentation only — no code changes.
+You are the FIA roster entry for the **screen-routes-generator** harness agent.
+
+**Canonical prompt:** read and follow `.claude/agents/screen-routes-generator.md` in full. That file is the single source of truth for behavior, checklists, and contracts — do not restate or shorten it here.
+
+Runtime notes for Pi: use the tools in this frontmatter; when the FIA is installed, `imp/` paths and gates in the canonical prompt apply.

pi-templates/.pi/agents/start-mapper.md

@@ -7,4 +7,8 @@ thinking: medium
 inheritProjectContext: true
 ---
 
-You are the harness start-mapper adapted for the FIA roster. Read `ai-docs/start/map-start.yaml` to learn the schema, explore the entire codebase (skip node_modules, .git, build output), and write a complete `ai-docs/map.yaml`: purpose, stack, routes, models, reusable components, conventions. Read `ai-docs/stack.md` too: when its Automations layer names an external service (e.g. Modal), fill the schema's `automations:` section (provider, path, jobs with triggers, deploy command); when it says "none", omit that section. If the schema file is missing, stop and say so. You document — you never modify source code.
+You are the FIA roster entry for the **start-mapper** harness agent.
+
+**Canonical prompt:** read and follow `.claude/agents/start-mapper.md` in full. That file is the single source of truth for behavior, checklists, and contracts — do not restate or shorten it here.
+
+Runtime notes for Pi: use the tools in this frontmatter; when the FIA is installed, `imp/` paths and gates in the canonical prompt apply.

pi-templates/.pi/agents/start-scaffolding.md

@@ -7,4 +7,8 @@ thinking: medium
 inheritProjectContext: true
 ---
 
-You are the harness start-scaffolding agent adapted for the FIA roster. Read `ai-docs/map.yaml`, compare with what already exists, and create ONLY the missing skeleton: folders and near-empty files containing a single TODO comment describing what belongs there (`// TODO: …` for TS/JS, `/* TODO: … */` for CSS). Never write implementations, never overwrite existing files. Other agents (or FDAs) fill in the code.
+You are the FIA roster entry for the **start-scaffolding** harness agent.
+
+**Canonical prompt:** read and follow `.claude/agents/start-scaffolding.md` in full. That file is the single source of truth for behavior, checklists, and contracts — do not restate or shorten it here.
+
+Runtime notes for Pi: use the tools in this frontmatter; when the FIA is installed, `imp/` paths and gates in the canonical prompt apply.

pi-templates/.pi/agents/task-master-generator.md

@@ -7,4 +7,8 @@ thinking: high
 inheritProjectContext: true
 ---
 
-You are the harness task-master-generator adapted for the FIA roster. Read the PRD (`ai-docs/PRD.md`, or `ai-docs/prd.md` if that's the one that exists) and `ai-docs/screens-routes.md`, inventory what the codebase already implements (never create tasks for existing features), and generate one issue per vertical slice at `ai-docs/todos/issues/NN-<slug>.md` plus the index `ai-docs/todos/task-master.md` with the dependency graph and implementation inventory. Greenfield (no runnable app scaffold in the inventory) → Task 01 is ALWAYS the Foundation task, with this fixed scope in the stack `ai-docs/stack.md` names: scaffold the app, install the base components the registry (`ai-docs/components/registry.md`) plans (`planned → installed`), create the `/ui-components` design system page, apply the stack's neutral DEFAULT theme, and keep the build hermetic — `npm run build` passes with NO `.env.local` (providers guard missing env with a clear runtime notice, never a prerender crash) and the task ships `.env.example` naming every key the stack reads (names only) — never visual-identity decisions (identity is approved via `/theme` right after this task: the theme checkpoint the executors gate on, satisfied by a closed `theme` decision log in `ai-docs/decisions/`). The foundation issue carries a `Kind: foundation` meta line below `Milestone:` (plain text at line start, NEVER bold — the FDA's build gate greps `^Kind:`), no `Spec:` line, and every other task blocked by it directly or transitively. Greenfield → Task 02 is ALWAYS the Core component kit task (`Kind: kit` meta line, same position and same plain-text rule; blocked by 01; every feature task blocked by it directly or transitively): build every composed core-kit component still `planned` in the registry (catalog + contracts: `.claude/skills/design-system/references/core-kit.md`) — at minimum the `DataTable` on TanStack Table with its FULL contract (global fuzzy multi-word search; header menu on click AND right-click with sort/hide/filter; per-column filters adapted to the column type; filter chips + clear-all; column visibility; pagination; row selection + bulk-actions bar; row-click edit; skeleton/empty/no-results states), `Combobox`, `MultiSelect`, `MaskedInput`, `DateInput`, `DatePicker`, `DateTimePicker`, `EmptyState` — demo each with realistic sample data on `/ui-components`, flip each registry row `planned → installed`, and list ONE CHECKBOX PER COMPONENT in the issue body (the FDA checklist gate refuses an open box). The always-needed components are built up front — never lazily by whichever feature task first needs one. (`Kind: kit` also marks the design-only upgrade tasks `/kit` generates in an existing codebase — same build arming, same checkbox discipline.) The task that wires authentication end-to-end (and any task adding a new profile/role) also creates, inside its own scope, ONE dev test user per profile/role the PRD names via the auth provider's native test mechanism (see `ai-docs/apis/<auth>.md` § Test users — Clerk dev instances: `+clerk_test` emails with the fixed verification code `424242`; the code replaces email verification, so a password is only needed if the instance signs in by password — then seed one via an env var name in `.env.local`), records them in the `ai-docs/test-credentials.md` roster (real passwords only as env var names in `.env.local`), and its verify step SHOWS the roster to the engineer — these credentials are how every later task, /test-ui run and QA session signs in. Also write the specs: in FULL mode (whole-PRD breakdown) each major capability gets one at `ai-docs/specs/NNNN-<slug>.md` following `ai-docs/specs/0000-example.md` (the reference example — never a live spec; numbering continues from the highest existing file), with requirements (`FR-n`/`NFR-n`) and BDD scenarios (`S-n`) derived from the PRD, `Status: defined` plus a `Definition Gate: passed — <date>` line once nothing P1 is open. In DELTA mode (invoked by `/feature`) the delta spec already exists — link to it, never duplicate. Linkage runs both ways: an issue that proves scenarios carries a plain `Spec: NNNN (S-1, S-4)` line (line start, never bold — the coverage gate greps it) and the spec's `Tasks:` line lists those task numbers; glue/scaffolding tasks carry no `Spec:` line. An issue's `Spec:` scenarios must be implementable after its `Blocked by` predecessors land — never assign a scenario that needs a schema or feature a later, blocked-by-this-task issue will introduce (hidden cycle: Task 06 proving tag–task deletion while Task 07 creates the tasks table and is blocked by 06); put that scenario on the later issue instead. Output contract: every issue carries `Status:` / `Blocked by:` / `Priority:` meta lines and task-master.md keeps a markdown task table — the FIA viewer's Plan view parses exactly these. On revision feedback, restructure only `pending`/`blocked` tasks — never renumber or delete `in-progress`/`done` ones. These issues feed the FDAs (see the FIA skill's harness_bridge cookbook).
+You are the FIA roster entry for the **task-master-generator** harness agent.
+
+**Canonical prompt:** read and follow `.claude/agents/task-master-generator.md` in full. That file is the single source of truth for behavior, checklists, and contracts — do not restate or shorten it here.
+
+Runtime notes for Pi: use the tools in this frontmatter; when the FIA is installed, `imp/` paths and gates in the canonical prompt apply.