Add repository workflow docs

AGENTS.md

@@ -1,5 +1,11 @@
 # Using `sql2json` with AI Agents and LLMs
 
+> **Working on this repository?** Coding agents and maintainers should read
+> `WORKFLOW.md` and `WORKFLOW.local.md` first. They define the public-safe
+> branch/PR lifecycle, francisco-boards usage, validation gates, and release
+> discipline for this repo (`S2J`, base branch `master`). The rest of this file
+> explains how agents should use `sql2json` as a CLI/library.
+
 `sql2json` runs SQL queries via SQLAlchemy and outputs JSON or CSV to stdout. It is invoked as a CLI tool or imported as a Python package — no framework coupling, no MCP server required.
 
 > **Invocation:** examples below use the `sql2json` command, available **since v0.2.1**. On `0.2.0` and earlier — or when the package's scripts directory is not on `PATH` — substitute the equivalent `python -m sql2json ...` form (on Windows, `py -m sql2json ...`).

CLAUDE.md

@@ -1,6 +1,12 @@
 # CLAUDE.md
 
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+This file provides guidance to Claude Code (claude.ai/code) and other coding agents when working with code in this repository.
+
+## Read this first
+
+1. Follow `WORKFLOW.md` and `WORKFLOW.local.md` for board usage, branch naming, PR lifecycle, validation gates, and release discipline.
+2. This is a public repository. Keep commits, PR bodies, and checked-in docs public-safe: no secrets, local-only absolute paths, private board details, or agent-generated footers.
+3. Use `francisco-boards` for maintainer/agent task status. Project key: `S2J`; base branch: `master`; branch format: `feature/S2J-N`.
 
 ## Commands
 

WORKFLOW.local.md

@@ -0,0 +1,123 @@
+# sql2json workflow overlay
+
+Read `WORKFLOW.md` first, then apply this sql2json-specific overlay.
+
+## Project configuration
+
+- Board project key: `S2J`
+- Base branch: `master`
+- Branch format: `feature/S2J-N`
+- Public repository: keep commits, PR bodies, and checked-in docs public-safe.
+- Release targets: PyPI package `sql2json` and Docker Hub image
+  `docker.io/fsistemas/sql2json` (`linux/amd64` + `linux/arm64`).
+
+## Branches, commits, and PRs
+
+- Start every task from a clean, synced `master`.
+- Use one branch and one PR per board issue.
+- Branch names use only the issue identifier, for example `feature/S2J-2`.
+- Prefer concise conventional commits:
+  - `feat: add query discovery`
+  - `fix: handle CSV output path`
+  - `docs: update release workflow`
+  - `test: add integration coverage`
+  - `chore: bump version to 0.3.2`
+- Do not add agent attribution, generated-by footers, or private board details to
+  commits or PR bodies.
+
+## Validation gates
+
+Choose the smallest gate that proves the change, but do not skip required gates
+when code paths change.
+
+### Docs-only changes
+
+```bash
+uv run pytest
+```
+
+For shell-script docs or script changes, also run:
+
+```bash
+bash -n scripts/<script>.sh
+```
+
+### Python code changes
+
+```bash
+uv run --extra dev black --check .
+uv run --extra dev flake8
+uv run --extra dev mypy
+uv run --extra dev pytest --cov
+```
+
+### Database behavior changes
+
+Run the Python code gates plus the real-database integration suite:
+
+```bash
+uv run --extra dev --extra integration pytest -m integration tests/integration
+```
+
+If local container tooling is not available, use the wrapper that provisions a
+compose stack when appropriate:
+
+```bash
+./scripts/test-integration.sh
+```
+
+### CLI/output behavior changes
+
+Add or update unit tests for the CLI contract and run at least:
+
+```bash
+uv run pytest tests/test_cli.py tests/test_output_files.py tests/test_transformations.py
+```
+
+Run the full Python gate before opening the PR when practical.
+
+### Docker changes
+
+Run the relevant tests and a local image smoke test. The Dockerfile installs
+`sql2json` from PyPI, so pass a published version when verifying release-image
+behavior:
+
+```bash
+podman build --platform linux/amd64 --pull=always --build-arg VERSION=0.3.1 -t sql2json-test .
+podman run --rm sql2json-test --query "SELECT 1 AS a, 2 AS b"
+```
+
+Use `docker` equivalents if Docker is the available container runtime.
+
+## Release discipline
+
+Releases are maintainer-only. External contributors and agents should not bump
+versions, create tags, publish to PyPI, or publish Docker images unless the
+maintainer explicitly asks for release work.
+
+When release work is requested, follow `RELEASING.md` exactly:
+
+1. Bump `pyproject.toml`.
+2. Update `CHANGELOG.md`.
+3. Run the full quality gates.
+4. Commit the release metadata.
+5. Tag with a `v` prefix, for example `v0.3.2`.
+6. Push the commit and tag to `master`.
+7. Build and publish to PyPI with `uv build` / `uv publish`.
+8. Publish Docker Hub images only after the PyPI version exists.
+9. Push immutable Docker tag `X.Y.Z`; move `latest` only for stable releases.
+10. Verify the pushed image runs and reports the expected package version.
+
+For Docker Hub, preserve multi-architecture support (`linux/amd64` and
+`linux/arm64`) whenever publishing a stable release. Treat published PyPI and
+Docker version tags as immutable.
+
+## sql2json safety reminders
+
+- The CLI executes arbitrary SQL and commits writes by default.
+- Use `--read-only` for exploratory or agent-driven database inspection unless a
+  write is explicitly intended.
+- Tests should use in-memory SQLite, temporary files, testcontainers, or the
+  documented integration stack — never a real user database.
+- Keep `AGENTS.md`, `README.md`, `CLAUDE.md`, and `skills/sql2json/SKILL.md`
+  aligned when changing public CLI behavior.

WORKFLOW.md

@@ -0,0 +1,174 @@
+# Shared agent workflow
+
+This is the repository workflow for maintainers and coding agents that coordinate
+work with francisco-boards, git branches, pull requests, and CI.
+
+This project is public. Keep workflow notes, pull request text, commits, and
+checked-in documentation safe for public readers: no secrets, private tokens,
+local-only absolute paths, or noisy agent attribution in commits/PR bodies.
+
+Project-specific details live in `WORKFLOW.local.md`. When a local rule conflicts
+with this document, follow the local rule or ask the maintainer before
+proceeding.
+
+## 1) Source of truth
+
+Use francisco-boards as the source of truth for maintainer/agent task status,
+ownership, and handoff evidence.
+
+- Search before creating duplicate issues.
+- Do not create ad-hoc task/status files for project tracking.
+- Record durable evidence on board issues: commands run, tests passed or failed,
+  PR links, merge SHAs, blockers, and intentionally deferred scope.
+- Keep public PR bodies concise and evidence-backed; keep detailed internal
+  coordination on the board.
+
+Common discovery commands:
+
+```bash
+francisco-boards repo resolve "$PWD"
+francisco-boards project summary
+francisco-boards issue list
+francisco-boards issue search <PROJECT_KEY> "keywords"
+```
+
+## 2) Mandatory preflight
+
+Before starting a task, creating a branch, or opening a PR:
+
+1. Inspect the working tree and branch:
+   ```bash
+   git status -sb
+   git branch --show-current
+   ```
+2. Check for open PRs:
+   ```bash
+   gh pr list --state open --json number,title,headRefName,statusCheckRollup,mergeable,url
+   ```
+3. There must be zero open PRs before creating a new PR unless the maintainer
+   explicitly directs otherwise.
+   - If an existing PR is green and mergeable, finish it first: merge, sync the
+     local base branch, then mark its issue Done.
+   - If an existing PR is failing, stale, or conflicted, fix that PR first.
+   - Do not start or open another PR on top of a known failing PR.
+4. Sync the repo's base branch before branching:
+   ```bash
+   git checkout <BASE_BRANCH>
+   git pull --ff-only origin <BASE_BRANCH>
+   ```
+
+## 3) Board identity and evidence
+
+Every agent update should identify the agent on the board.
+
+- Claim before starting implementation.
+- Use the board actor/author fields (`--actor`, `--author`) when the CLI command
+  supports them.
+- Include a short signature in board notes/comments when useful, for example
+  `— Pi` or `— Claude`.
+
+Board signatures do not change commit/PR hygiene: do not add agent attribution,
+"generated by" footers, or co-author robot lines to commits or PR bodies.
+
+## 4) Branch and PR rules
+
+- One issue = one branch = one PR.
+- Work one issue at a time per checkout.
+- Never edit the base branch directly for task work.
+- Branches must use only the board issue identifier:
+  - Correct: `feature/PROJECT-KEY-N`
+  - Correct: `feature/S2J-2`
+  - Wrong: long auto-generated slugs, `linear/...`, or branches bundling several
+    issues.
+- Never stack task branches. A feature branch starts from current
+  `origin/<BASE_BRANCH>`.
+- Before opening a PR, verify the branch is not stacked:
+  ```bash
+  git fetch origin <BASE_BRANCH>
+  git log --oneline origin/<BASE_BRANCH>..HEAD
+  git diff --stat origin/<BASE_BRANCH>...HEAD
+  git status -sb
+  ```
+
+## 5) Per-issue lifecycle
+
+Every issue follows this loop:
+
+1. Search the board first; reuse or extend an existing issue if one covers the
+   work.
+2. Complete mandatory preflight (§2).
+3. Claim the issue and move it to `in_progress` before implementation.
+4. Start from a clean, synced base branch and create the task branch:
+   ```bash
+   git checkout <BASE_BRANCH>
+   git pull --ff-only origin <BASE_BRANCH>
+   git checkout -b feature/<ISSUE_ID>
+   ```
+5. Implement the smallest change that satisfies the issue.
+6. Validate before committing. Run the local gates from `WORKFLOW.local.md` and
+   any focused checks relevant to the change.
+7. Commit only after validation passes.
+8. Push and open exactly one PR for the issue.
+9. Move the board issue to `review` when the PR is ready for review.
+10. Wait for checks. If checks fail, fix the same branch and push again.
+11. Merge only when checks are green and the PR is mergeable.
+12. After merge, sync the local base branch:
+    ```bash
+    git checkout <BASE_BRANCH>
+    git pull --ff-only origin <BASE_BRANCH>
+    git status -sb
+    git rev-parse HEAD
+    git rev-parse origin/<BASE_BRANCH>
+    ```
+13. Only then mark the issue Done. The Done note should include the PR URL,
+    merge or synced base SHA, validation commands, and check result.
+
+An issue is not Done while its PR is open, files are uncommitted, checks are red,
+or the local base branch is not synced after merge.
+
+## 6) Validation and green-base discipline
+
+Validation gates are project-specific, but the shared rule is simple: do not
+claim Done over a red gate.
+
+- Run focused checks for the change.
+- Run the full local gate when practical or required by `WORKFLOW.local.md`.
+- If a gate reveals unrelated failures, isolate root causes and track unrelated
+  bugs separately.
+- A pre-existing red gate is not ignored just because your change did not cause
+  it; surface it clearly and ask the maintainer how to proceed if it blocks the
+  issue.
+
+## 7) Test/data safety
+
+- Do not let tests mutate real user data.
+- Scope temporary database/environment variables to the command that needs them.
+- Prefer isolated fixtures over shared state.
+- Treat production-like local data as valuable; verify destructive behavior on
+  disposable data first.
+
+## 8) Commit and PR hygiene
+
+- Keep commits scoped to the issue.
+- Use the repo's commit-message convention from `WORKFLOW.local.md`.
+- Do not include agent attribution or generated-by footers in commits or PR
+  bodies.
+- PR bodies should be public-safe and evidence-backed.
+- Put detailed process notes and tracker evidence on the board issue.
+
+## 9) Handoff format
+
+When handing work to another agent or maintainer, include:
+
+- issue ID
+- checkout/worktree path
+- exact scope
+- files changed or expected
+- validation commands run
+- blockers or follow-up work
+
+## 10) Workflow updates
+
+Durable workflow rules belong in checked-in documents, not private agent memory.
+When the maintainer clarifies a rule that affects future work, update this file
+or `WORKFLOW.local.md` as part of the relevant PR.