db-context-postgres

db-context-postgres

Act as a senior/staff engineering database context capture for the active task, scoped to a generic Postgres deployment (GCP Cloud SQL, GKE Autopilot Postgres, self-hosted, AWS RDS, etc.) accessed via psql or pg_dump.

Goal: Validate that connection params resolve to a reachable Postgres instance, introspect a user-scoped subset of the schema (extensions, tables, columns, indexes, foreign keys, and optionally RLS policies and functions), and persist the result as DB_CONTEXT.md inside the active task folder so the task has a grounded, point-in-time schema reference for planning, implementation, and review.

This command is opt-in. It is not part of the default task initialization flow; run it after task-init only when the task actually touches Postgres data, schema, or RLS.

Mandatory context bootstrap (before any output):

• Read these sections in WORKFLOW_OPERATING_SYSTEM.md first:
  • ## LLM execution contract
  • ## Editor mode policy (mode definitions only; the tool mapping table is lazy-loaded in wos/editor-mode-mappings.md and needed only for non-Claude-Code tools)
  • ## Global output contract (including Adaptive handoff and Mode selection rule)
  • ## Cross-cutting workflow guardrails
• Bootstrap tiers: the light-weight commands (branch-commit, what-next, where-we-at, slice-closure, compact-task-memory) plus the high-frequency implement-approved-slice and sync-task-state (v3 wave1 item D) read the four sections above with two subsections of ## Cross-cutting workflow guardrails skipped: ### External web access (centralized) and ### Sequencing heuristics (by phase). Everything else is read at every tier, including ### Proposal vs approved persistence and ### Substrate peer ownership (per ADR-0034), since all seven write substrate sections and reason about PROPOSED (state-reconcile stays on the full tier for cross-artifact judgment). The full tier is measured at 12109 tokens, the four always-read sections combined; the two skipped subsections are 1,034 of those (measured 2026-09-28), so the reduced tier is about 11,074. The leaf-reviewer tier (verify-against-rubric, ADR-0226) reads only ## Global output contract, measured at 5215 tokens, plus its rubric.
• Session bootstrap reuse (skip-if-unchanged; v3 wave1 item D): WHEN this conversation already read the bootstrap sections in an earlier turn still VISIBLE in the context window AND WORKFLOW_OPERATING_SYSTEM.md has not changed since, the command MAY skip the re-read and cite the earlier one, emitting one Command transcript line: Bootstrap: reusing turn <N> read, WOS unchanged. Scoped exception to the context-budget re-fetch rule (wos/context-budget.md, "The re-fetch rule"), because these sections are one large, static, byte-identical read repeated every turn; every other tool result still re-fetches. VISIBLE means the section text itself is still present and quotable now, not merely that a record of the earlier read exists: a harness that clears a tool result while the record survives (ADR-0114) has not satisfied VISIBLE, and self-declared memory after a compaction never qualifies. A stateless-per-turn harness is excluded. The transcript line is mandatory; a silent skip is invalid output.
• Resolving the spec and wos/<topic>.md: canonical repository FIRST. Otherwise use active-adapter docs: ~/.claude/workflow-docs (CLAUDE_WORKFLOW_DOCS_DIR), ~/.cursor/workflow-docs (WORKFLOW_DOCS_DIR; project .cursor/workflow-docs on project installs), ~/.codex/workflow-docs (CODEX_WORKFLOW_DOCS_DIR), or <kimi-home>/workflow-docs (KIMI_WORKFLOW_DOCS_DIR). Nonempty overrides win. Kimi home: KIMI_CODE_HOME, else existing ~/.kimi-code, else existing ~/.kimi, default ~/.kimi-code. Use one root for both paths; try other adapters if absent or unknown. Report resolved root, fallback to other adapters, or missing mandatory context in ### Command transcript. Installed snapshots refresh and prune retired topics only on sync.
• Read additional sections only when relevant to this command's role.
• Align all routing recommendations and next-command suggestions with the current command set.
• Official next-command names only: recommendations, including Run now, use registered names from commands/<name>.md or commands/<name>/SKILL.md; installed mode uses the available Fhorja command or skill inventory. No invented aliases. Run now: none with Mode: N/A ends only if no honest next step exists, defined under ### Official command names (routing integrity) (ADR-0126). Required inputs:
• active task path (or enough context to resolve projects/<client>__<project>/active/YYYY-MM-DD_<task-slug>/)
• connection params, provided via one of:
  • environment variables PGHOST, PGPORT, PGUSER, PGDATABASE, PGPASSWORD (or PGSSLMODE)
  • a DATABASE_URL (postgres://user:pass@host:port/dbname?sslmode=...)
  • a ~/.pgpass entry plus host/db identifiers
• scope of introspection, supplied by the user as one or more of:
  • list of table names (qualified schema.table or unqualified for the default public schema)
  • list of schemas to include in full (use sparingly; large schemas should be narrowed)
• depth flag (one of):
  • tables-only: tables, columns with types, primary keys, not-null flags, indexes, foreign keys
  • tables+rls (default): tables-only plus row-level security policies for each in-scope table when RLS is in use
  • full: tables+rls plus relevant functions, triggers, extensions, and server version metadata
• optional: refresh flag (refresh to regenerate; default is to fail with NO_OP_TRACE if a non-stale DB_CONTEXT.md already exists for the same scope)