# impl-gh-issue

Adopt this skill: https://proskills.md/skills/other/bablsoft-accessflow-claude-skills-impl-gh-issue

Page: https://proskills.md/skills/other/bablsoft-accessflow-claude-skills-impl-gh-issue
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: .claude/skills/impl-gh-issue/SKILL.md
size: 8114
upstream: https://github.com/bablsoft/accessflow/blob/main/.claude/skills/impl-gh-issue/SKILL.md

```text
---
name: impl-gh-issue
description: Implement an AccessFlow GitHub issue end-to-end — fetch with gh, plan against docs/, follow CLAUDE.md conventions, update tests and docs, then open a PR. Trigger when the user says "implement issue #N", "work on AF-N / FE-N", or passes a GitHub issue URL/number.
---

# Implement a GitHub issue for AccessFlow

You are implementing a GitHub issue in the AccessFlow repo. **CLAUDE.md is the authoritative rulebook** — re-read it before writing code. This skill only adds a workflow on top.

## Inputs

The user passes one of:
- An issue number: `42`, `AF-58`, `FE-10`
- A full URL: `https://github.com/bablsoft/accessflow/issues/42`

Resolve the numeric issue with `gh issue view <n> --json number,title,body,labels,assignees,url,state`.

## Project map

- **Docs** (authoritative design):
  - `docs/01-overview.md` — product scope, goals, non-goals
  - `docs/02-architecture.md` — system architecture and request flow
  - `docs/03-data-model.md` — entities, columns, enums, indexes
  - `docs/04-api-spec.md` — REST + WebSocket spec (update before adding endpoints)
  - `docs/05-backend.md` — proxy engine, workflow state machine, AI analyzer, scheduled jobs
  - `docs/06-frontend.md` — directory layout, routing, state management
  - `docs/07-security.md` — auth, authorization matrix, encryption rules
  - `docs/08-notifications.md` — event types, channel configs, signed payloads
  - `docs/09-deployment.md` — Docker Compose, Helm, env-var reference
  - `docs/11-development.md` — coding standards, testing strategy, Git workflow
  - `docs/12-roadmap.md` — milestone scope
  - `docs/13-mcp.md` — MCP server, `@Tool` callbacks, user API keys
  - `docs/14-connectors.md` — connector catalog, manifests, SHA-256 pins
  - `docs/15-engine-sdk.md` — host↔plugin contract, add-an-engine checklist
  - `docs/16-iac.md` — Terraform/OpenTofu provider, CI templates, composite Actions
  - `docs/17-api-governance.md` — API access governance (`apigov`)
  - `docs/18-deployment-governance.md` — deployment approval governance (`deploygov`)
  - `docs/19-sql-review.md` — deterministic SQL review rules (`sqlreview`)
  - `docs/20-schema-change-governance.md` — schema change governance (`schemachange`)
  - `docs/21-aggregate-disclosure.md` — aggregate disclosure guard (design, #943)
  - `docs/22-service-accounts.md` — service accounts / non-human identities (`serviceaccounts`, epic #867)
- **Backend** at `backend/` — Java 25, Spring Boot 4, Spring Modulith. Modules under `com.bablsoft.accessflow.{core,proxy,workflow,ai,security,notifications,audit}`. Build: `mvn verify` (run from `backend/` — there is no Maven wrapper).
- **Frontend** at `frontend/` — React 19 + Vite + TS + Ant Design 6 + TanStack Query + Zustand. Build: `npm run lint && npm run typecheck && npm run test:coverage && npm run build`.
- **End-to-end** at `e2e/` — Playwright suite with its own `docker-compose.e2e.yml` that builds backend + frontend from the working tree and seeds a deterministic admin via the `bootstrap` module. Owns auth and (over time) all critical user flows. Run: `cd e2e && npm ci && npx playwright install --with-deps chromium && npm run stack:up && npm test`.
- **Website** at `website/` — public marketing site, static HTML/CSS/JS, no build step. Edits land directly in HTML.
  - `website/index.html` — landing page (pitch, supported databases, AI providers, auth methods, feature list, roadmap, quick-start commands, tech stack, docs chapter list, top-level URLs).
  - `website/docs/index.html` — public user documentation page (deployment instructions, configuration entities — Review Plans, AI configs, datasources, OAuth, SAML, SMTP, notification channels, user creation — RBAC role matrix, operator-facing env vars).
  - `website/README.md` — content-source map describing which app/`docs/` sections each website section is derived from; keep in sync when adding new website sections.
- **README** at the repo root — public-facing project overview and quick start. Keep in sync when changes affect setup, tech stack, features, project structure, or top-level documentation.

## Workflow

### 1. Read the issue and pick docs
- `gh issue view <n>` to load title, body, labels.
- From labels and body, pick the docs to read **before coding**:
  - DB / migration / entity → `03-data-model.md`, `05-backend.md`
  - New REST or WS endpoint → `04-api-spec.md` (update first), `05-backend.md`
  - Workflow / proxy / AI / scheduled job → `05-backend.md`
  - Auth / RBAC / encryption → `07-security.md`
  - UI page / component / store → `06-frontend.md`
  - Notifications → `08-notifications.md`
  - Env vars / Docker / Helm → `09-deployment.md`
  - MCP / connectors / engine SPI / IaC → `13-mcp.md`, `14-connectors.md`, `15-engine-sdk.md`, `16-iac.md`
  - API or deployment governance → `17-api-governance.md`, `18-deployment-governance.md`
  - SQL review rules / rulesets / editor lint → `19-sql-review.md`
  - Schema change sets / DDL gate / promotion / drift → `20-schema-change-governance.md`
  - Aggregate / group-size disclosure, classification-driven routing → `21-aggregate-disclosure.md`
  - Service accounts / API keys / MCP allow-list / rate limit / on-behalf-of → `22-service-accounts.md`
- Always re-skim CLAUDE.md sections relevant to the layer you're touching (Modulith rules, validation parity, i18n, scheduled-job locking, JaCoCo gate).

### 2. Branch
Branch names follow `docs/11-development.md` and CLAUDE.md:
- `feature/AF-<n>-<kebab-summary>` for backend features
- `fix/AF-<n>-<kebab-summary>` for backend fixes
- `feature/FE-<n>-…` / `fix/FE-<n>-…` for frontend-only work
- Branch off `main` (the repo currently merges PRs into `main`; check `git remote show origin` if unsure).

### 3. Implement
Follow CLAUDE.md exactly. Highlights worth re-checking before each PR:
- **Backend**: constructor injection, `*Entity` suffix and `internal/persistence/entity/` placement, Flyway `V{n}__…sql` (never edit existing), `@SchedulerLock` on every `@Scheduled`, no string-concat SQL, `@JsonIgnore` on encrypted fields, i18n keys in `messages.properties`, ≥ 90% line coverage with a dedicated `*Test` per concrete class.
- **Frontend**: TanStack Query for all server data (no `useEffect` fetching), Zustand only for client state, `t()` for every user-visible string with the key in `src/locales/en.json`, validation parity with backend Bean Validation, `≥ 90%` line / `≥ 80%` branch coverage on included modules.
- **End-to-end (`e2e/`)** — non-negotiable, per CLAUDE.md's "Do not let `e2e/` drift" rule. Before opening the PR, scan the diff for changes that touch user flows:
  - **Frontend change touches a route, page, form, store, or selector that an existing Playwright spec uses?** Update the spec in the same commit set. Don't merge a frontend change that you know will flip an e2e green run to red. Common drift sources: renaming an `id` / `aria-label` / button text used by a selector, changing the redirect target after login or logout, altering the auth-store or apiClient interface, moving the logout entry in the user menu.
  - **Frontend change introduces a new user-facing flow** (new route, auth path, user-driven mutation — submit query, approve a review, create a datasource, change a setting that has a server effect)? Add a spec under `e2e/tests/` in the same PR. The default is "add a spec"; if you're skipping it, justify why in the PR description.
  - **Backend change flips behaviour for an e2e-covered flow** (login payload, refresh-cookie semantics, `bootstrap` reconciler, setup-status endpoint)? Update the spec accordingly.
  - **Pure presentational refactors** (CSS-only, internal rename with no selector impact) don't need an e2e update — but verify your refactor doesn't break any selector first.
  - When in doubt, run `cd e2e && npm run stack:up && npm test` locally before the PR. The `e2e` CI job is the load-bearing check.

### 4. **Update docs AND the website in the same change**
Non-negotiable. The PR is incomplete until th
```

## File: README.md
upstream: https://github.com/bablsoft/accessflow/blob/main/README.md

```text
<p align="center">
  <img src="https://raw.githubusercontent.com/bablsoft/accessflow/main/website/favicon.svg" alt="AccessFlow logo" width="96" height="96">
</p>

<h1 align="center">AccessFlow</h1>

<p align="center">
  <strong>Open-source database, API &amp; deployment access governance platform</strong><br>
  A SQL, NoSQL, and API proxy — plus a CI/CD deployment gate — that puts review, approval, and audit between your team and production data, services, and releases.
</p>

<p align="center">
  <a href="https://github.com/bablsoft/accessflow/actions/workflows/ci.yml"><img src="https://github.com/bablsoft/accessflow/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  <a href="https://snyk.io/test/github/bablsoft/accessflow?targetFile=backend/pom.xml"><img src="https://snyk.io/test/github/bablsoft/accessflow/badge.svg?targetFile=backend/pom.xml" alt="Snyk Monitoring"></a>
  <img src="https://img.shields.io/badge/License-Apache_2.0-blue.svg" alt="License: Apache 2.0">
  <a href="https://accessflow.io/"><img src="https://img.shields.io/badge/Live%20Demo-accessflow.io-1f6feb?logo=githubpages&logoColor=white" alt="Live site"></a>
</p>

<p align="center">
  <a href="https://accessflow.io/">Website</a> ·
  <a href="https://accessflow.io/docs/">Live Docs</a> ·
  <a href="https://accessflow.io/changelog/">Changelog</a> ·
  <a href="#quick-start">Quick Start</a> ·
  <a href="docs/">Design Docs</a>
</p>

AccessFlow sits as a full query proxy in front of your databases — the relational engines PostgreSQL, MySQL, MariaDB, Oracle, and Microsoft SQL Server are supported out of the box via a declarative **connector catalog** (additional engines such as ClickHouse install with one click), any other JDBC-compatible engine can be added by uploading its driver JAR, the NoSQL document engines **MongoDB** and **Couchbase** (SQL++), the NoSQL key-value engine **Redis**, the NoSQL wide-column engines **Apache Cassandra** (CQL) and **ScyllaDB** (CQL-compatible), the NoSQL search engines **Elasticsearch** and **OpenSearch**, the NoSQL key-value engine **Amazon DynamoDB** (PartiQL), the NoSQL graph engine **Neo4j** (Cypher over Bolt), and the cloud data warehouses **Snowflake**, **Google BigQuery** (GoogleSQL), and **Databricks SQL** install the same way through on-demand native engine plugins. The catalog separates the **SQL** (relational) family, the cloud **data-warehouse** family, and the **NoSQL** umbrella of native engine-managed connectors. Every query a user submits — SQL, a MongoDB shell / JSON command, a Couchbase SQL++ statement, a Redis command, a Cassandra/ScyllaDB CQL statement, an Elasticsearch/OpenSearch query, a DynamoDB PartiQL statement, a Neo4j Cypher statement, or a Snowflake / BigQuery / Databricks warehouse SQL statement — is parsed, classified, optionally analyzed by AI, and routed through a configurable human-approval workflow before it ever reaches live data. The same governance extends beyond databases: outbound **REST, SOAP, GraphQL, and gRPC** calls against registered API connectors run through that identical pipeline — AI risk scoring, attribute-based routing, multi-stage approval — with response masking and immutable, downloadable response snapshots. Every request, decision, and execution is captured in a tamper-evident metadata audit log. Authentication is JWT (RS256) with optional SAML 2.0 SSO and OAuth 2.0 / OIDC sign-in (built-in templates for Google, GitHub, GitHub Enterprise Server, Microsoft, GitLab, and self-managed GitLab), and SCIM 2.0 provisioning lets the identity provider drive user & group lifecycle end to end. AccessFlow ships as a single open-source product under Apache 2.0 and is designed to run entirely inside your own infrastructure.

---

## Why AccessFlow

Most teams pick one of two extremes for database access:

- **Shared production credentials** — anyone with the password can run `DELETE`. Fast, but a single mistake is unbounded and there is no record of who did what.
- **Ticket-driven DBA access** — every change goes through a manual DBA queue. Safe, but slow enough that engineers route around it.

AccessFlow provides the missing middle: governed, self-service access where every query is reviewable, every approval is traceable, and AI catches the obvious problems before a human ever sees the request.

---

## See it in action

A glance at the day-to-day flows engineers and approvers actually use.

![SQL editor](https://raw.githubusercontent.com/bablsoft/accessflow/main/website/images/docs/editor-light.webp)

*Submit a query — CodeMirror 6 with dialect-aware highlighting, live schema autocomplete, and an inline review-plan preview that shows exactly which approvals the submission will trigger.*

![Review queue](https://raw.githubusercontent.com/bablsoft/accessflow/main/website/images/docs/reviews-queue-light.webp)

*Approve or reject pending writes from one place — the queue is scoped to queries assigned to you, with risk score, query type, and submitter at a glance. A user can never approve their own query.*

![Query history](https://raw.githubusercontent.com/bablsoft/accessflow/main/website/images/docs/queries-list-light.webp)

*Searchable, filterable history of every query — by status, type, risk, datasource, submitter, or date range — with CSV export. Each row links to the full request, AI analysis, approval timeline, and result set.*

![Configure a governed datasource](https://raw.githubusercontent.com/bablsoft/accessflow/main/website/images/docs/datasources-create-light.webp)

*Connect a database in the admin UI — credentials are AES-256-GCM encrypted at rest, the proxy holds them, and end users never see them.*

> **More walkthroughs** — the [Guides section](https://accessflow.io/docs/guides/) carries step-by-step manuals for the setup tasks: [your first governed query](https://accessflow.io/docs/guides/first-query/), [adding a datasource](https://accessflow.io/docs/guides/datasource/), [notifications and SMTP](https://accessflow.io/docs/guides/notifications/), [users and roles](https://accessflow.io/docs/guides/team/), [single sign-on](https://accessflow.io/docs/guides/sso/), [AI risk analysis](https://accessflow.io/docs/guides/ai-analysis/), [outbound API calls](https://accessflow.io/docs/guides/api-governance/), [gating a CI/CD pipeline](https://accessflow.io/docs/guides/deployment-approval/), [Terraform](https://accessflow.io/docs/guides/terraform/) and [the in-app help assistant](https://accessflow.io/docs/guides/help-assistant/) — which, once enabled, answers all of the above from inside the app. Review plans, AI provider configuration, notification channels (Email, Slack, Discord, Telegram, Teams, PagerDuty, ServiceNow, Jira, webhooks), OAuth 2.0 / OIDC sign-in, SAML 2.0 SSO, users & invitations, and system SMTP each have their own reference chapter with screenshots on the [public documentation site](https://accessflow.io/docs/).

---

## Features

- **Proxy-first execution** — no user ever holds production credentials; the proxy holds them encrypted and opens connections only after approval. Single SQL statements run with autocommit; multi-statement INSERT/UPDATE/DELETE batches wrapped in `BEGIN; … COMMIT;` execute atomically inside one JDBC transaction (mixed SELECT/DML batches are rejected at parse time), with homogeneous INSERT runs collapsed into JDBC `executeBatch()` for bulk-load throughput. Optional **multi-replica read load balancing**: attach any number of replica endpoints to a datasource and SELECT traffic round-robins across the healthy ones — per-node health checks with circuit-breaker failover skip downed replicas, and only full replica-set exhaustion falls back to the primary (with an audit row). Optional **SELECT result caching**: opt a datasource into a Redis-backed result cache (per-datasource TTL) keyed over the security-rewritten query — masking and row-level security still apply — and invalidated on any proxied write to a referenced table.
- **Configurable review workflows** — per-dat
```
