docs: per-feature handoffs + feature-plan skill

.agents/skills/feature-plan/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: feature-plan
+description: >-
+  Plan and track a ComplyAIgent feature with a sensible git branch and a
+  docs/handoffs dated handoff markdown. Use when starting a feature, MVP
+  sub-issue, feature plan, handoff doc, or docs/*-handoffs branch — not for
+  one-line typo PRs.
+disable-model-invocation: false
+---
+
+# Feature plan (branch + handoff)
+
+## Goal
+
+Every non-trivial feature gets:
+
+1. A **sensible branch name**
+2. A **dated handoff** under `docs/handoffs/` (from the template)
+3. A link to the **GitHub issue** (prefer MVP epic children under #74)
+
+Do **not** invent a parallel docs tree. Do **not** copy skills or process from other repos; follow this repo only.
+
+## When to invoke
+
+- User asks to plan / start a feature, MVP workstream, or handoff
+- Opening work on issues #75–#81 (or new enhancement issues)
+- Creating `docs/<topic>-handoffs` or `feat|mvp/<issue>-<slug>` branches
+
+## Branch names
+
+| Kind | Pattern | Example |
+|------|---------|---------|
+| Docs / planning stream | `docs/<topic>-handoffs` | `docs/mvp-handoffs` |
+| Implementation | `feat/<issue>-<slug>` or `mvp/<issue>-<slug>` | `mvp/75-policy-versioning` |
+| Tiny chore | `chore/<slug>` | optional handoff |
+
+Base branch: **`dev`**.
+
+## Handoff file
+
+Path: `docs/handoffs/YYYY-MM-DD-<slug>.md`  
+Start from: [`docs/handoffs/_TEMPLATE.md`](../../../docs/handoffs/_TEMPLATE.md)
+
+Required sections (keep headings even if short):
+
+- Status / Branch / Issue(s) / Last updated
+- Bottom line
+- Current state
+- What shipped (table)
+- Hook points (files)
+- Open follow-ups
+- How to verify (commands)
+- Done means (checkboxes)
+
+Update the index table in [`docs/handoffs/README.md`](../../../docs/handoffs/README.md).
+
+## Workflow
+
+1. `git fetch && git checkout dev && git pull`
+2. Create branch with the naming table above
+3. Copy template → new dated handoff; fill Bottom line + Current state + Done means from the issue
+4. Link issue in the handoff; comment on the issue with the handoff path + branch
+5. Implement in small PRs; each mergeable chunk updates **What shipped** and **Open follow-ups**
+6. Before marking the issue done: fill **How to verify**, tick **Done means**, set Status to Done
+7. Open PR into `dev` (docs-only PRs are fine for `docs/*-handoffs`)
+
+## Anti-patterns
+
+- Single mega `docs/handover/README.md` dump for a feature (that file is project-wide only)
+- Feature branch with no handoff
+- Handoff that only restates the issue title
+- Closing an MVP issue without verify commands
+
+## Related docs
+
+- Epic: https://github.com/liitkud/complyaigent/issues/74
+- `docs/mvp/README.md` · `docs/ROADMAP.md` · `docs/handover/README.md`
+

.agents/skills/feature-plan/handoff-template.md

@@ -0,0 +1,41 @@
+# HANDOFF — <short title>
+
+**Status:** Planned | In progress | Done  
+**Branch:** `<branch>`  
+**Issue(s):** #<n>  
+**Owner / next reader:** <who>  
+**Last updated:** YYYY-MM-DD
+
+## Bottom line
+
+One paragraph: what this workstream is, why it exists, and what “done” means for *this* phase.
+
+## Current state
+
+- What’s true in the repo / deploy right now
+- What is declared but unwired
+- What must not be re-solved (already fixed)
+
+## What shipped
+
+| PR / commit | Delivers |
+|-------------|---------|
+| #… | … |
+
+## Hook points (files to touch)
+
+- `path/to/file` — why
+
+## Open follow-ups
+
+- [ ] …
+
+## How to verify
+
+```bash
+# commands a fresh agent can run
+```
+
+## Done means
+
+- [ ] …

.cursor/skills/feature-plan/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: feature-plan
+description: >-
+  Plan and track a ComplyAIgent feature with a sensible git branch and a
+  docs/handoffs dated handoff markdown. Use when starting a feature, MVP
+  sub-issue, feature plan, handoff doc, or docs/*-handoffs branch — not for
+  one-line typo PRs.
+disable-model-invocation: false
+---
+
+# Feature plan (branch + handoff)
+
+## Goal
+
+Every non-trivial feature gets:
+
+1. A **sensible branch name**
+2. A **dated handoff** under `docs/handoffs/` (from the template)
+3. A link to the **GitHub issue** (prefer MVP epic children under #74)
+
+Do **not** invent a parallel docs tree. Do **not** copy skills or process from other repos; follow this repo only.
+
+## When to invoke
+
+- User asks to plan / start a feature, MVP workstream, or handoff
+- Opening work on issues #75–#81 (or new enhancement issues)
+- Creating `docs/<topic>-handoffs` or `feat|mvp/<issue>-<slug>` branches
+
+## Branch names
+
+| Kind | Pattern | Example |
+|------|---------|---------|
+| Docs / planning stream | `docs/<topic>-handoffs` | `docs/mvp-handoffs` |
+| Implementation | `feat/<issue>-<slug>` or `mvp/<issue>-<slug>` | `mvp/75-policy-versioning` |
+| Tiny chore | `chore/<slug>` | optional handoff |
+
+Base branch: **`dev`**.
+
+## Handoff file
+
+Path: `docs/handoffs/YYYY-MM-DD-<slug>.md`  
+Start from: [`docs/handoffs/_TEMPLATE.md`](../../../docs/handoffs/_TEMPLATE.md)
+
+Required sections (keep headings even if short):
+
+- Status / Branch / Issue(s) / Last updated
+- Bottom line
+- Current state
+- What shipped (table)
+- Hook points (files)
+- Open follow-ups
+- How to verify (commands)
+- Done means (checkboxes)
+
+Update the index table in [`docs/handoffs/README.md`](../../../docs/handoffs/README.md).
+
+## Workflow
+
+1. `git fetch && git checkout dev && git pull`
+2. Create branch with the naming table above
+3. Copy template → new dated handoff; fill Bottom line + Current state + Done means from the issue
+4. Link issue in the handoff; comment on the issue with the handoff path + branch
+5. Implement in small PRs; each mergeable chunk updates **What shipped** and **Open follow-ups**
+6. Before marking the issue done: fill **How to verify**, tick **Done means**, set Status to Done
+7. Open PR into `dev` (docs-only PRs are fine for `docs/*-handoffs`)
+
+## Anti-patterns
+
+- Single mega `docs/handover/README.md` dump for a feature (that file is project-wide only)
+- Feature branch with no handoff
+- Handoff that only restates the issue title
+- Closing an MVP issue without verify commands
+
+## Related docs
+
+- Epic: https://github.com/liitkud/complyaigent/issues/74
+- `docs/mvp/README.md` · `docs/ROADMAP.md` · `docs/handover/README.md`
+

.cursor/skills/feature-plan/handoff-template.md

@@ -0,0 +1,41 @@
+# HANDOFF — <short title>
+
+**Status:** Planned | In progress | Done  
+**Branch:** `<branch>`  
+**Issue(s):** #<n>  
+**Owner / next reader:** <who>  
+**Last updated:** YYYY-MM-DD
+
+## Bottom line
+
+One paragraph: what this workstream is, why it exists, and what “done” means for *this* phase.
+
+## Current state
+
+- What’s true in the repo / deploy right now
+- What is declared but unwired
+- What must not be re-solved (already fixed)
+
+## What shipped
+
+| PR / commit | Delivers |
+|-------------|---------|
+| #… | … |
+
+## Hook points (files to touch)
+
+- `path/to/file` — why
+
+## Open follow-ups
+
+- [ ] …
+
+## How to verify
+
+```bash
+# commands a fresh agent can run
+```
+
+## Done means
+
+- [ ] …

.gitignore

@@ -56,8 +56,10 @@ coverage_report.txt
 # testing cache
 .pytest_cache
 
-# spec-kit
-.agents/
+# spec-kit / local agent state — keep versioned skills
+.agents/*
+!.agents/skills/
+!.agents/skills/**
 
 # Test files
 *.db

AGENTS.md

@@ -7,6 +7,11 @@
 - [docs/ONBOARDING.md](docs/ONBOARDING.md) — local setup
 - Epic: https://github.com/liitkud/complyaigent/issues/74
 
+## Feature plans & handoffs
+- Skill: `feature-plan` (`.agents/skills/feature-plan/`, `.cursor/skills/feature-plan/`)
+- Per-feature docs: [`docs/handoffs/`](docs/handoffs/) — dated handoffs on `docs/<topic>-handoffs` or `feat|mvp/<issue>-*` branches
+- Project-wide overview only: [`docs/handover/`](docs/handover/README.md)
+
 ## Defaults
 - Branch from `dev`; small PRs mapped to MVP sub-issues (#75–#81)
 - Backend: `cd backend && uv sync && uv run …`

docs/handoffs/2026-07-24-mvp-continuous-compliance-gate.md

@@ -0,0 +1,50 @@
+# HANDOFF — MVP: Continuous Compliance Gate
+
+**Status:** In progress  
+**Branch:** `docs/mvp-handoffs` (planning); implementation on `feat/<issue>-*` / `mvp/<issue>-*`  
+**Issue(s):** Epic [#74](https://github.com/liitkud/complyaigent/issues/74) · sub-issues #75–#81 (#82 docs done)  
+**Last updated:** 2026-07-24
+
+## Bottom line
+
+Ship a minimum viable continuous compliance gate: ingest → versioned policy → CLI A1 + `/validate` poll → live HITL → structured verdict logs (+ PII / A1 regex safety). Not a hackathon demo pack.
+
+## Current state
+
+- Epic + sub-issues exist; project board: ComplyAIgent Roadmap
+- Project overview: `docs/mvp/README.md`, `docs/ROADMAP.md`, `docs/handover/README.md`
+- Per-feature handoffs under this folder; **this file is the epic umbrella**
+- Child handoffs should be added as each sub-issue starts (same template)
+
+## Workstreams → issues → expected child handoff
+
+| Issue | Workstream | Child handoff (create when starting) |
+|-------|------------|--------------------------------------|
+| #75 | Policy storage schema & versioning | `docs/handoffs/YYYY-MM-DD-policy-versioning.md` |
+| #76 | Structured verdict logging schema | `…-verdict-log-schema.md` |
+| #77 | Loki / sink push | `…-verdict-loki-push.md` |
+| #78 | E2E + live HITL | `…-e2e-live-hitl.md` |
+| #79 | Presidio PII on `/validate` | `…-presidio-pii.md` |
+| #80 | A1 regex validation / ReDoS | `…-a1-regex-guard.md` |
+| #81 | Sample policy pack | `…-mvp-sample-policies.md` |
+| #82 | Docs sync | Done via #83 |
+
+## Deferred (do not stuff into MVP)
+
+#22 load test · #14 RAG tune · #13 regulatory simulator
+
+## Hook points (orientation)
+
+- Backend: `backend/app/api/validate.py`, `services/pipeline.py`, `models/`
+- CLI: `cli/cmd/scan.go`
+- Frontend: `frontend/services/api.ts`, HITL components
+- Compose: `docker-compose.yml`
+
+## How to verify (epic-level)
+
+See DoD checklist on #74 and `docs/mvp/README.md`.
+
+## Done means
+
+- [ ] All MVP sub-issues closed with their own handoff updated to Done
+- [ ] Epic #74 DoD checkboxes complete

docs/handoffs/2026-07-24-stabilize-contracts-and-ci.md

@@ -0,0 +1,45 @@
+# HANDOFF — Stabilize contracts & CI
+
+**Status:** Done  
+**Branch:** `dev` (merged)  
+**Issue(s):** #61 #62 #63 #64 #73 #84  
+**Last updated:** 2026-07-24
+
+## Bottom line
+
+Unblocked the repo after hackathon handoff: CLI↔API validate contract, lazy LLM clients, test schemas, Makefile typo, pinned ruff/ty CI, file-mode cleanup. Do **not** reopen these as MVP blockers.
+
+## What shipped
+
+| PR | Delivers |
+|----|----------|
+| #61 | CLI Makefile `go fmt ./...` |
+| #62 | Integration test `/validate` payload schema |
+| #63 | Lazy-load ChatOpenAI clients |
+| #64 | CLI polls `GET /validate/{id}` after 202 |
+| #73 | Pin ruff/ty + ruff config; CI green |
+| #83 | MVP roadmap + project handover docs |
+| #84 | Normalize file modes; drop stale `requirements.txt`; refresh `AGENTS.md` |
+
+## Current state
+
+- `dev` Code Check (py_check) green
+- LLM clients lazy; missing keys should not crash import
+- Secrets baseline: `backend/.secrets.baseline` (root symlink)
+
+## Open follow-ups
+
+- [ ] Still open from audit: A1 regex ReDoS gate → MVP #80
+- [ ] Constitution symlink content quality (file exists; keep accurate)
+
+## How to verify
+
+```bash
+cd backend && uv run ruff check . && uv run ruff format . --check && uv run ty check
+cd ../cli && go test ./...
+```
+
+## Done means
+
+- [x] Contract + CI fixes merged to `dev`
+- [x] Documented so MVP work does not rediscover them