Add agentic development infrastructure (001-agentic-tooling)

- Agent rule files (.agents/rules/) for AI onboarding, feedback loop, and coding standards
- GitHub Actions workflows for automated Claude code review and rule governance gate
- Shared Claude tool permissions (.claude/settings.json) and SpecKit skill commands
- PR template, CODEOWNERS, and SpecKit scripts/templates (.specify/)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: Alex Fernandez

.agents/rules/ai-feedback-learning-loop.md

@@ -0,0 +1,50 @@
+# AI Feedback Learning Loop
+
+> Documents the process for AI agents to propose rule changes and await human approval. Prevents silent rule drift between sessions.
+
+## When to Propose a Change
+
+Propose a rule change when any of the following happen:
+
+- A human corrects your approach during development and the correction is worth preserving project-wide
+- You discover a pattern, constraint, or convention that recurs across multiple tasks and is not yet captured in `.agents/rules/`
+- A tool, command, or workflow behaves differently than what the rules describe
+- An accepted convention turns out to be incorrect or outdated
+
+Do not propose a change for one-off situations specific to a single task.
+
+## Proposal Format
+
+When you identify a change worth proposing, output the following block in your response:
+
+```
+## Rule Change Proposal
+
+**Triggered by**: [What correction or learning surfaced this]
+**Proposed rule**: [Exact text to add/change/remove in base.md]
+**Section**: [Which section of base.md this belongs in]
+**Rationale**: [Why this is worth preserving project-wide]
+
+Awaiting human approval before applying.
+```
+
+Include this block in-line in your response — do not create a file or modify any `.agents/rules/` file until the human explicitly approves.
+
+## One-at-a-Time Constraint
+
+Only propose one rule change per session. If multiple corrections surface, log them in `specs/<feature>/lessons-learned.md` and propose them one at a time in future sessions after the current proposal is resolved.
+
+## Human Approval Required
+
+AI agents MUST NOT self-apply rule changes. The rule files in `.agents/rules/` are governance documents — changes require human review and explicit approval. This prevents agents from silently shifting project conventions based on in-session learning that may be wrong or context-specific.
+
+Approval means the human explicitly says something like "approved", "apply it", or "go ahead and update base.md". Implicit agreement or lack of objection is not approval.
+
+## How to Apply After Approval
+
+Once a human explicitly approves a rule change:
+
+1. Open `.agents/rules/base.md` (or the relevant rule file)
+2. Apply the exact change described in the proposal — no scope creep
+3. Open a PR with the change; include `Rule-Change-Approval: <ref>` in the PR description (reference the conversation, issue, or comment where approval was given)
+4. CI will verify the approval reference is present before allowing the merge

.agents/rules/base.md

@@ -0,0 +1,157 @@
+# Base Agent Rules
+
+> Single source of truth for AI agent conventions in this project. Read this file at the start of every session before doing anything else.
+
+## Project Overview
+
+This is a full-stack web application with a Python backend and TypeScript/Node 22 frontend.
+
+**Backend**: Python 3.10+, FastAPI, SQLModel, PostgreSQL, managed with `uv`
+**Frontend**: TypeScript, Node 22, ESM-only, managed with `bun`
+**CI/CD**: GitHub Actions — automated tests, linting, Docker compose validation, Claude AI review
+**Infrastructure**: Docker Compose for local development and CI
+
+Architecture: HTTP API (backend) consumed by a single-page frontend. Services run in Docker containers locally and in staging/production via GitHub Actions deployments.
+
+```
+full-stack-agentic/
+  backend/          Python FastAPI application
+  frontend/         TypeScript/Node 22 frontend
+  .github/          CI workflows, PR templates, CODEOWNERS
+  .agents/rules/    AI agent conventions (this directory)
+  .claude/          Claude Code settings and commands
+  specs/            Feature specifications (SpecKit artifacts)
+```
+
+## Project Structure
+
+```
+.
+├── backend/
+│   ├── app/            Application source (routers, models, services)
+│   ├── tests/          pytest test suite
+│   └── pyproject.toml
+├── frontend/
+│   ├── src/            TypeScript source
+│   └── package.json
+├── .github/
+│   ├── workflows/      CI workflow files
+│   ├── CODEOWNERS      Auto-review assignments
+│   └── pull_request_template.md
+├── .agents/
+│   └── rules/          Agent rule files (base.md, coding-standards.md, ai-feedback-learning-loop.md)
+├── .claude/
+│   ├── commands/       SpecKit skill files
+│   └── settings.json   Shared Claude tool permissions
+└── specs/              Per-feature SpecKit artifacts
+```
+
+## Available Commands
+
+### Backend Tests
+
+```bash
+uv run pytest
+```
+
+```bash
+uv run python -m pytest
+```
+
+### Backend Lint
+
+```bash
+uv run ruff check .
+```
+
+```bash
+uv run ruff format .
+```
+
+### Backend Type Check
+
+```bash
+uv run ty check
+```
+
+### Frontend Tests
+
+```bash
+bun run test
+```
+
+### Frontend Lint
+
+```bash
+bun run lint
+```
+
+### Docker (local dev)
+
+```bash
+docker compose up
+```
+
+```bash
+docker compose down
+```
+
+### SpecKit Scripts
+
+```bash
+.specify/scripts/bash/<script-name>
+```
+
+## Testing Conventions
+
+- Backend tests live in `backend/tests/`, mirroring the `app/` package structure
+- Run with `uv run pytest` from the repo root or `backend/` directory
+- Frontend tests are colocated (`*.test.ts`) alongside source files
+- Run with `bun run test` from `frontend/`
+- Test behavior, not implementation — tests verify what code does, not how
+- Mock only boundaries: network, filesystem, external services
+- Every error path the code handles should have a test
+
+## SpecKit Workflow
+
+This project uses SpecKit for structured feature development. The phases are:
+`/speckit.specify` → `/speckit.clarify` → `/speckit.plan` → `/speckit.tasks` → `/speckit.implement`
+
+Artifacts live in `specs/<feature-id>-<feature-name>/`.
+
+### Retro Gate (mandatory)
+
+After every SpecKit phase command completes (`/speckit.specify`, `/speckit.plan`,
+`/speckit.tasks`, `/speckit.implement`), run `/speckit.retro` before starting
+the next phase. Do not proceed until the retro produces a "Ready" status.
+
+**Micro-retro** (after each task in `/speckit.implement`):
+1. Simplify the code just written
+2. Log anything unexpected to `specs/<feature>/lessons-learned.md`
+3. Check whether `tasks.md`, `plan.md`, or `spec.md` needs updating
+4. Suggest `/clear` before the next task
+
+**Phase retro** (after each phase command):
+1. Summarize what was produced
+2. Review `lessons-learned.md`
+3. Check all earlier artifacts for drift
+4. Propose constitution/rules updates (never self-apply — await human approval)
+5. Confirm readiness gate (5 items)
+6. Suggest `/clear` with specific files to re-read
+
+## Rule Proposal Process
+
+When you receive a correction or discover a pattern worth preserving project-wide, propose a rule change following the process in `.agents/rules/ai-feedback-learning-loop.md`.
+
+Key constraint: **never self-apply rule changes**. Always propose and wait for explicit human approval before modifying any file in `.agents/rules/`.
+
+## SDD Development Workflow
+
+1. **Branch**: Create a feature branch from `master` — `git checkout -b <id>-<short-name>`
+2. **Develop**: Implement the feature; run tests and linter locally before committing
+3. **PR**: Open a pull request against `master` using the PR template in `.github/pull_request_template.md`
+4. **CI**: GitHub Actions runs tests, lint, and automated Claude code review
+5. **Review**: CODEOWNERS auto-requests designated reviewers for affected paths
+6. **Merge**: Merge after CI passes and reviewers approve — no direct pushes to `master`
+
+Changes to `.agents/rules/base.md` require a `Rule-Change-Approval: <ref>` line in the PR description. CI will block the PR if absent.

.agents/rules/coding-standards.md

@@ -0,0 +1,82 @@
+# Coding Standards
+
+> Agreed-upon code quality standards for AI agents to apply consistently across this project.
+
+## Python Standards
+
+**Runtime**: Python 3.10+, managed with `uv`
+
+**Linting and formatting**: `ruff` — run `uv run ruff check .` and `uv run ruff format .`
+**Type checking**: `ty` — run `uv run ty check`
+
+**Naming**:
+- Modules, functions, variables: `snake_case`
+- Classes: `PascalCase`
+- Constants: `UPPER_SNAKE_CASE`
+
+**Type annotations**: Required on all non-trivial public functions and methods. Use `from __future__ import annotations` for forward references.
+
+**Import order** (enforced by ruff):
+1. Standard library
+2. Third-party packages
+3. Local application imports
+
+No relative imports (`..`) — use absolute imports only.
+
+**Function size**: Max 100 lines, cyclomatic complexity ≤ 8, max 5 positional parameters.
+
+**Docstrings**: Google-style on non-trivial public APIs. Code should be self-documenting — only add docstrings where the purpose isn't obvious from names and types.
+
+## TypeScript Standards
+
+**Runtime**: Node 22, ESM-only (`"type": "module"` in package.json)
+**Package manager**: `bun`
+
+**Linting and formatting**: `oxlint` and `oxfmt`
+
+**tsconfig.json** — enable all strictness flags:
+- `strict: true`
+- `noUncheckedIndexedAccess: true`
+- `exactOptionalPropertyTypes: true`
+- `noImplicitOverride: true`
+- `noPropertyAccessFromIndexSignature: true`
+- `verbatimModuleSyntax: true`
+- `isolatedModules: true`
+
+**Naming**:
+- Variables, functions: `camelCase`
+- Classes, types, interfaces: `PascalCase`
+- Constants: `UPPER_SNAKE_CASE`
+- Files: `kebab-case.ts`
+
+No relative imports (`../`) across package boundaries — use absolute imports configured via `tsconfig.json` paths.
+
+**Test files**: Colocated as `*.test.ts` alongside source files.
+
+## Testing Principles
+
+**Test behavior, not implementation.** Tests verify what the code does, not how. A refactor that doesn't change behavior must not break tests.
+
+**Test edges and errors, not just the happy path.** Empty inputs, boundary values, malformed data, missing files — bugs live in edges. Every error path the code handles should have a test that triggers it.
+
+**Mock only boundaries.** Mock things that are slow (network, filesystem), non-deterministic (time, randomness), or external services you don't control. Never mock internal application logic.
+
+**Verify tests catch failures.** Break the code, confirm the test fails, then fix. Tests that always pass regardless of implementation are useless.
+
+## Error Handling
+
+**Fail fast with clear, actionable messages.** When something goes wrong, raise immediately with context: what operation failed, what input caused it, and what the caller should do.
+
+**Never swallow exceptions silently.** No bare `except: pass` or `.catch(() => {})`. If an error is genuinely ignorable, add a comment explaining why.
+
+**Include context in error messages**: what operation was attempted, what the unexpected value was, and a suggested fix where possible.
+
+## Comments
+
+**Code should be self-documenting.** Choose names that make the purpose obvious. If a comment explains what the code does, the code probably needs refactoring.
+
+**No commented-out code.** Delete it. Version control exists to recover deleted code.
+
+**Comments explain why, not what.** The only valid use for a comment is to explain a non-obvious decision, a known limitation, or a gotcha that the code cannot express.
+
+**No `<!-- TODO -->` comments in rule files.** Open items go to `tasks.md`.