feat/insforge-verify-skill

[CarmenDou]

Note

Add insforge-verify skill for full-stack preview end-to-end verification

• Adds a new agent skill insforge-verify under skills/insforge-verify/ with a SKILL.md manifest covering purpose, usage guidance, test scoping, and known gaps for private preview.
• Adds a detailed runbook at verify.md with step-by-step instructions: creating a preview branch, applying migrations, seeding users, deploying the frontend, running Playwright specs, backend truth checks, RLS isolation probes, re-verification, and teardown.
• Updates AGENTS.md to register the new skill in the repository tree.

Changes since #102 opened

• Introduced npx @insforge/cli verify, npx @insforge/cli verify truth, and npx @insforge/cli verify rls --table <t> --owner <col> commands for verifying persistence, backend truth, and cross-user RLS isolation [7246be8]
• Rewrote insforge-verify skill documentation to focus on verifying changes against the linked dev backend using Playwright MCP for UI flows and CLI verify commands for backend cross-checks [7246be8]
• Rewrote the verify runbook from an isolated branch preview and deployment flow to a direct verification workflow against the linked dev backend [7246be8]
• Added advisories in Frontend deployments section, RLS checklist section, and SDK integration documentation about verifying changes using CLI verify commands before deployment [7246be8]
• Added execution mode section documenting background subagent pattern for @insforge/cli verify [1a806b7]
• Updated default run instructions to recommend background subagent execution [1a806b7]
• Documented pre-authorization requirements for wildcard permissions in background subagent mode [1a806b7]

^{Macroscope summarized 165a146.}

---

Summary by cubic

Adds the insforge-verify skill for pre-ship full‑stack verification by driving your running app in a real browser and cross‑checking DB truth and cross‑user RLS on your linked dev backend; private preview. Docs now default verify to a background subagent so long UI runs don’t block your session.

• New Features

  • Adds skills/insforge-verify/SKILL.md and skills/insforge-verify/references/verify.md: light‑mode runbook — seed two users, point at your running app, drive the scoped UI via @playwright/mcp, confirm persistence with npx @insforge/cli verify truth and isolation with npx @insforge/cli verify rls, then clean up.
  • Adds verify nudges in sibling docs: skills/insforge-cli/SKILL.md (verify before deploy), skills/insforge-cli/references/database/access-control.md (RLS probe), and skills/insforge/database/sdk-integration.md (persistence check). Lists the skill in AGENTS.md with a light‑mode note; migration steps now use npx @insforge/cli db migrations up.
  • Sets default execution to a background subagent with foreground pre‑auth allowlist (npx @insforge/cli verify *, mcp__playwright__*), its own browser instance, and a clear foreground/background split; returns JSON findings from npx @insforge/cli verify truth/rls.

• Bug Fixes

  • Fail‑fast guards for empty anon key and empty login tokens to prevent silent false passes.
  • Seeds both verify-a and verify-b as runnable steps; fixes a runbook reference.

^{Written for commit 1a806b7. Summary will update on new commits.}

Summary by CodeRabbit

Release Notes

• Documentation
  • Added comprehensive guides for the InsForge Verify feature (private preview), including full-stack verification workflows for testing persistence and cross-user data isolation
  • Enhanced deployment guidance recommending verification checks before backend or full-stack changes go live
  • Clarified best practices for validating database access control policies and row-level isolation

[coderabbitai]

Walkthrough

Adds a new skills/insforge-verify/ skill directory containing a SKILL.md overview and a references/verify.md runbook for full-stack e2e verification (private preview). Updates AGENTS.md, insforge-cli/SKILL.md, access-control.md, and sdk-integration.md to cross-reference the new npx @insforge/cli verify commands.

Changes

InsForge Verify skill and cross-references

Layer / File(s)	Summary
InsForge Verify SKILL.md: overview, procedure, and known gaps skills/insforge-verify/SKILL.md	Creates the new skill document with front-matter metadata, a private-preview overview table, usage timing and scoping rules, a numbered end-to-end run procedure, concrete assertions to target, common mistakes, and known preview limitations.
Verification runbook: seeding, UI driving, DB truth, RLS, cleanup skills/insforge-verify/references/verify.md	Adds the step-by-step runbook: apply migrations and seed two verified users via the admin key, point the browser at the running app, drive the changed UI flow via Playwright MCP using browser_snapshot, cross-check DB truth with verify truth, validate cross-user RLS isolation with verify rls, loop on failure, and clean up seeded users and test rows.
Cross-reference updates in existing skill docs and AGENTS.md AGENTS.md, skills/insforge-cli/SKILL.md, skills/insforge-cli/references/database/access-control.md, skills/insforge/database/sdk-integration.md	Registers the new skill in the AGENTS.md repo tree; adds a pre-deploy npx @insforge/cli verify bullet to the CLI deployments guidance; adds RLS runtime-isolation vs. policy well-formedness clarification with the verify rls command; adds a warning that { error: null } does not guarantee persistence with a pointer to verify truth.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• InsForge/insforge-skills#79: Both PRs modify skills/insforge-cli/SKILL.md to adjust usage guidance for the insforge-cli.
• InsForge/insforge-skills#91: Both PRs touch the same RLS/access-control reference docs under skills/insforge-cli/references/database/access-control.md.
• InsForge/insforge-skills#104: Both PRs update skills/insforge/database/sdk-integration.md with RLS-related documentation and persistence verification guidance.

Suggested reviewers

• Fermionic-Lyu
• jwfing

Poem

🐇 A new skill hops into the grove,
With runbooks, snapshots, seeds to sow,
Two users—A and B—take their row,
RLS checked from top to toe,
False passes? Not today, let's go! ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The PR title 'feat/insforge-verify-skill' directly corresponds to the main change: introduction of the new insforge-verify agent skill for full-stack preview e2e verification.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/insforge-verify-skill

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[cubic-dev-ai]

2 issues found across 3 files

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[greptile-apps]

Greptile Summary

This PR introduces the insforge-verify agent skill for pre-ship full-stack verification: it seeds two authenticated test users on the linked dev backend, drives the changed UI flow via the Playwright MCP, then cross-checks persistence and cross-user RLS isolation with npx @insforge/cli verify truth/rls — catching false passes that a pure UI test cannot.

• New skills/insforge-verify/ — SKILL.md covers scoping, the foreground-prep / background-subagent execution model, and common pitfalls; references/verify.md is the step-by-step runbook (seed → drive → backend-truth + RLS probe → fix → cleanup).
• Advisory additions — pre-deploy verify nudge in insforge-cli/SKILL.md, static-vs-runtime RLS distinction in access-control.md, and a persistence-not-guaranteed note in sdk-integration.md.
• AGENTS.md — registers the new skill in the repo tree, though the references/ subdirectory is omitted from the listing.

Confidence Score: 5/5

Documentation-only additions with no executable code changes; safe to merge.

All changes are documentation and runbook files. The only defect found is that the AGENTS.md tree omits the references/ subdirectory that the PR actually adds — a cosmetic gap with no functional impact on the skill itself.

AGENTS.md — the tree entry for insforge-verify should include the references/ subdirectory to match the actual file structure added by this PR.

Important Files Changed

Filename	Overview
AGENTS.md	Registers insforge-verify in the repo tree; the new entry omits the references/ subdirectory that is actually added by this PR.
skills/insforge-verify/SKILL.md	New skill manifest covering purpose, scoping, execution mode (foreground prep + background subagent), and known gaps; well-structured with no logical issues.
skills/insforge-verify/references/verify.md	Full step-by-step runbook for the verify workflow; clear seeding, UI-drive, backend-truth, RLS probe, and cleanup steps.
skills/insforge-cli/SKILL.md	Adds a pre-deploy verify nudge in the Frontend deployments section; straightforward advisory addition.
skills/insforge-cli/references/database/access-control.md	Appends a note distinguishing static policy checks from runtime isolation, with a pointer to npx @insforge/cli verify rls; well-placed after the existing RLS checklist.
skills/insforge/database/sdk-integration.md	Adds a best-practice advisory that a successful write response doesn't guarantee DB persistence; links to verify truth for confirmation.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Start: backend or full-stack change complete] --> B[Scope the change\ngit diff --name-only]
    B --> C[Foreground: apply migration\nnpx @insforge/cli db migrations up --all]
    C --> D[Foreground: seed verify-a + verify-b\ncurl admin API]
    D --> E[Pre-authorize wildcards\nnpx @insforge/cli verify * + MCP tools]
    E --> F[Dispatch background subagent\nwith scoped git diff]
    F --> G[Subagent: point browser at running app\nlocalhost or existing deploy]
    G --> H[Subagent: drive changed UI flow\nvia @playwright/mcp]
    H --> I[Subagent: cross-check persistence\nnpx @insforge/cli verify truth]
    I --> J[Subagent: RLS isolation probe\nnpx @insforge/cli verify rls]
    J --> K{All green?}
    K -- No --> L[Subagent reports findings\nto main session]
    L --> M[You fix code / migration]
    M --> N[Re-apply migration if needed]
    N --> F
    K -- Yes --> O[Foreground: clean up\ndelete seeded users + test rows]
    O --> P[Verified ✓ — safe to ship]

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
flowchart TD
    A[Start: backend or full-stack change complete] --> B[Scope the change\ngit diff --name-only]
    B --> C[Foreground: apply migration\nnpx @insforge/cli db migrations up --all]
    C --> D[Foreground: seed verify-a + verify-b\ncurl admin API]
    D --> E[Pre-authorize wildcards\nnpx @insforge/cli verify * + MCP tools]
    E --> F[Dispatch background subagent\nwith scoped git diff]
    F --> G[Subagent: point browser at running app\nlocalhost or existing deploy]
    G --> H[Subagent: drive changed UI flow\nvia @playwright/mcp]
    H --> I[Subagent: cross-check persistence\nnpx @insforge/cli verify truth]
    I --> J[Subagent: RLS isolation probe\nnpx @insforge/cli verify rls]
    J --> K{All green?}
    K -- No --> L[Subagent reports findings\nto main session]
    L --> M[You fix code / migration]
    M --> N[Re-apply migration if needed]
    N --> F
    K -- Yes --> O[Foreground: clean up\ndelete seeded users + test rows]
    O --> P[Verified ✓ — safe to ship]

Loading

_{Reviews (5): Last reviewed commit: "docs(verify): default to background suba..." | Re-trigger Greptile}

[jwfing]

What's the difference b/w preview and branch?

[cubic-dev-ai]

1 issue found across 5 files (changes from recent commits).

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>