Skip to content

docs(skills): sync hand-written skills with main; drop duplicate skills and stale zip - #2010

Open
pyramation wants to merge 1 commit into
mainfrom
devin/1794873790-skills-sync-main
Open

pyramation wants to merge 1 commit into
mainfrom
devin/1794873790-skills-sync-main

Conversation

@pyramation

@pyramation pyramation commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Skills/docs only (no product code, no generated files). Applies the constructive part of the cross-repo skills audit (§2, §2.4, §4, §5) after re-verifying every statement against current main.

Per-skill changes and what each was verified against

pgpm — fixes a wrong statement.

  • references/cli.md (Admin Users): the example created platform_service with --bypassrls and said platform components use such a login. Platform logins are NOBYPASSRLS. Example now uses a generic migrator login, states the platform login is NOBYPASSRLS and must not get --bypassrls, and that --bypassrls cannot be combined with --test.
    • Verified: constructive-db/ci/rules.json (R11), constructive-db/docs/architecture/platform-access-rules.md (R11), constructive-db/docs/architecture/role-exposure-boundary.md, constructive-db/application/app/__tests__/request-database.provision.test.ts (rolbypassrls false), graphql/server/README.md, pgpm/cli/src/commands/admin-users/add.ts.
  • SKILL.md references table: one row pointing pgpm diff / import / transform at the existing pgpm-projections skill (it already documents pgpm diff in depth; no duplicate prose). Verified: pgpm/cli/src/commands/diff.ts.

graphile-search — fixes wrong names/inputs, adds BM25 filter semantics.

  • references/codegen-sdk-queries.md, SKILL.md: score/orderBy names were wrong — bm25ContentScore / BM25_CONTENT_SCORE_* → contentBm25Score / CONTENT_BM25_SCORE_*; embeddingDistance / EMBEDDING_DISTANCE_* → embeddingVectorDistance / EMBEDDING_VECTOR_DISTANCE_* (and the naming-pattern bullets). The rest of the skill already used the correct names.
    • Verified: graphile/graphile-search/src/plugin.ts (pgSearchScore, pgSearchOrderByEnum inflectors), src/__tests__/bm25-match-count.test.ts, src/__tests__/orderby-variable.test.ts.
  • SKILL.md, references/bm25-adapter.md, references/pgvector-adapter.md: filter input shapes were wrong — BM25 is { query, threshold } (no indexName input); pgvector is VectorNearbyInput { vector, model, metric, distance, includeChunks } (not VectorSearchInput { query, metric }).
    • Verified: graphile/graphile-search/src/adapters/bm25.ts, src/adapters/pgvector.ts.
  • references/bm25-adapter.md: new "Filter Semantics" — without threshold only matching rows (score < 0) are returned so totalCount matches; threshold is inclusive (<=); BM25 orderBy requires the filter (error names it), also for variable orderBy.
    • Verified: src/adapters/bm25.ts (matchClause), src/plugin.ts (orderBy validation), src/__tests__/bm25-match-count.test.ts, src/__tests__/orderby-variable.test.ts.

constructive-testing — adds missing coverage.

  • references/pgsql-test-transactions.md: new "Deferred Constraints Under Rollback Isolation" (db.deferredConstraints / DB_DEFERRED_CONSTRAINTS: off | check | immediate, db.checkConstraints(), what no mode covers). SKILL.md table row updated.
    • Verified: postgres/pgsql-test/src/test-client.ts (beforeEach, afterEach, checkConstraints, publish), postgres/pgsql-test/src/connect.ts, postgres/pgsql-test/README.md.

Removed duplicates (canonical home: constructive-io/constructive-skills)

Deleted .agents/skills/constructive-principals/ and .agents/skills/constructive-plan-cascade-sdk/. git grep found no references to either in this repo (AGENTS.md tables, other skills, docs), so there was nothing to repoint; the canonical copies are constructive-skills/.agents/skills/constructive-principals and constructive-skills/.agents/skills/constructive-billing.

Content in the deleted copies not present in constructive-skills main (checked by grepping constructive-skills/.agents/skills; listed so it can be merged there, not re-verified here):

  • constructive-principals/references/principal-fields.md (whole file): field reference for the principals table, the principal_entities junction table, and the create_principal / delete_principal mutations.
  • constructive-principals/SKILL.md: error codes PRINCIPAL_NOT_FOUND, NOT_OWNER; csdk ... create-principal CLI example; React hooks useCreatePrincipalMutation, usePrincipalsQuery; principal_entities mentions.
  • constructive-plan-cascade-sdk/SKILL.md: "Four Access-Control Layers" overview; 5-step plan configuration workflow; changing plans section; reading feature flags from the SDK; app-level defaults without plans (limit/cap/meter defaults); SDK table reference. Table names used there that constructive-skills does not mention: appPlanCap, appPlanMeterLimit, appMeterDefault, appPlanLimit, appPlanPricing, appPlanSubscription, appPlanOverride, defaultPlanLimit, resolve_cap. I did not verify these names against current main, so check them before carrying them over.

Removed stale zip

Deleted .agents/skills/constructive-starter-kits.zip (its folder had changed after the zip was built). No consumer found:

  • this repo: git grep for \.zip, constructive-starter-kits.zip, skills/*.zip across source, .github/workflows/*, all package.json, .gitignore/.npmignore. Only hits are unrelated test/report artifacts.
  • constructive-hub: grep for .zip, agents/skills, constructive-starter-kits. Only hits are Playwright artifacts (test-results-core.zip, *-report.zip).
  • constructive-skills/AGENTS.md: skill .zip packages are not committed.

Audit items rejected or not verified

  • Generated skills (cli-*, hooks-*, orm-*) stale: the audit's guess. cli-auth/hooks-auth/orm-auth were last regenerated 2026-11-05 and sdk/ changed after that (2026-11-16), so they may be stale. Not hand-edited; they need a regeneration run.
  • pgpm diff missing from the pgpm skill: partly wrong. pgpm-projections already covers it, so I only added a pointer. --ledger / --emit-ledger (backfilling an existing database's ledger) are left out because the platform is greenfield-only.
  • jobs raw-SQL, auth, and platform items in §2: these are about constructive-skills / constructive-db skill text, not skills in this repo. Not changed here.
  • image-field items: already done in docs(skills): file-reference column URLs and model-aware vector search #2009. Not touched.

Link to Devin session: https://app.devin.ai/sessions/8676620977654283a6a1db21557951ae
Open in Devin Desktop: https://app.devin.ai/desktop/session/8676620977654283a6a1db21557951ae?variant=devin
Requested by: @pyramation


🟢 Devin Review found nothing to fix · View findings

Devin Review

@devin-ai-integration

Copy link
Copy Markdown
Contributor

I'll fix CI failures and address comments from users with write access. I'll skip comments containing "(aside)".

  • Disable automatic comment, CI, and merge conflict monitoring

@luxor-code-review

luxor-code-review Bot commented Nov 17, 2026 •

Copy link
Copy Markdown

Review complete. No issues found — approved ✅.


This PR touches only .agents/skills/** markdown docs: it adds the constructive-principals skill, documents the new deferredConstraints option in pgsql-test (including DB_DEFERRED_CONSTRAINTS and db.checkConstraints()), renames graphile-search score fields and orderBy enums across the search skill references, and updates the PGPM skill with admin-user --bypassrls provisioning guidance and a pointer to the pgpm-projections skill.

Files Change
.agents/skills/constructive-testing/** Documents the deferred-constraints check/immediate modes, cross-referenced against the new pgsql-test harness behavior
.agents/skills/graphile-search/** Renames BM25/vector score fields, orderBy enums, and input types across the skill and its three reference docs
.agents/skills/pgpm/** Adds --bypassrls reconciliation guidance and renames the example user to migrator; adds a pgpm-projections cross-reference
.agents/skills/constructive-principals/** New skill documenting principal fields
.agents/skills/{constructive-plan-cascade-sdk,graphile-search/references/bm25-adapter.md} Minor edits; the plan-cascade-sdk skill is removed

Every documented field name, input shape, CLI flag, and harness API referenced by the changed docs was checked against the corresponding source (graphile-search plugin, pgpm CLI, pgsql-test) and found accurate; no stale references to the removed skills or old field names remain. No code changes are involved, so the merge risk is minimal.

Reviewed commit: bcbdc64

@devin-ai-integration devin-ai-integration Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no bugs or issues to report.

Devin Review

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant