diff --git a/.agents/skills/feature-plan/SKILL.md b/.agents/skills/feature-plan/SKILL.md new file mode 100644 index 0000000..2ecf609 --- /dev/null +++ b/.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/-handoffs` or `feat|mvp/-` branches + +## Branch names + +| Kind | Pattern | Example | +|------|---------|---------| +| Docs / planning stream | `docs/-handoffs` | `docs/mvp-handoffs` | +| Implementation | `feat/-` or `mvp/-` | `mvp/75-policy-versioning` | +| Tiny chore | `chore/` | optional handoff | + +Base branch: **`dev`**. + +## Handoff file + +Path: `docs/handoffs/YYYY-MM-DD-.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` + diff --git a/.agents/skills/feature-plan/handoff-template.md b/.agents/skills/feature-plan/handoff-template.md new file mode 100644 index 0000000..b9d7f37 --- /dev/null +++ b/.agents/skills/feature-plan/handoff-template.md @@ -0,0 +1,41 @@ +# HANDOFF — + +**Status:** Planned | In progress | Done +**Branch:** `` +**Issue(s):** # +**Owner / next reader:** +**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 + +- [ ] … diff --git a/.cursor/skills/feature-plan/SKILL.md b/.cursor/skills/feature-plan/SKILL.md new file mode 100644 index 0000000..2ecf609 --- /dev/null +++ b/.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/-handoffs` or `feat|mvp/-` branches + +## Branch names + +| Kind | Pattern | Example | +|------|---------|---------| +| Docs / planning stream | `docs/-handoffs` | `docs/mvp-handoffs` | +| Implementation | `feat/-` or `mvp/-` | `mvp/75-policy-versioning` | +| Tiny chore | `chore/` | optional handoff | + +Base branch: **`dev`**. + +## Handoff file + +Path: `docs/handoffs/YYYY-MM-DD-.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` + diff --git a/.cursor/skills/feature-plan/handoff-template.md b/.cursor/skills/feature-plan/handoff-template.md new file mode 100644 index 0000000..b9d7f37 --- /dev/null +++ b/.cursor/skills/feature-plan/handoff-template.md @@ -0,0 +1,41 @@ +# HANDOFF — + +**Status:** Planned | In progress | Done +**Branch:** `` +**Issue(s):** # +**Owner / next reader:** +**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 + +- [ ] … diff --git a/.gitignore b/.gitignore index 1b26af3..910aafa 100644 --- a/.gitignore +++ b/.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 diff --git a/AGENTS.md b/AGENTS.md index 5178efc..71637ae 100644 --- a/AGENTS.md +++ b/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/-handoffs` or `feat|mvp/-*` 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 …` diff --git a/docs/handoffs/2026-07-24-mvp-continuous-compliance-gate.md b/docs/handoffs/2026-07-24-mvp-continuous-compliance-gate.md new file mode 100644 index 0000000..21603db --- /dev/null +++ b/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/-*` / `mvp/-*` +**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 diff --git a/docs/handoffs/2026-07-24-stabilize-contracts-and-ci.md b/docs/handoffs/2026-07-24-stabilize-contracts-and-ci.md new file mode 100644 index 0000000..ac83ecd --- /dev/null +++ b/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 diff --git a/docs/handoffs/README.md b/docs/handoffs/README.md new file mode 100644 index 0000000..7798269 --- /dev/null +++ b/docs/handoffs/README.md @@ -0,0 +1,40 @@ +# Feature handoffs + +Per-feature (or per-workstream) handover docs — **not** the project-wide overview in [`docs/handover/`](../handover/README.md). + +Pattern inspired by Millia’s `docs/handoffs/` + feature branches: each meaningful slice of work gets a dated handoff on a sensible branch, so the next agent/human can pick up without re-deriving context. + +## Branch naming + +| Kind | Branch | What lands | +|------|--------|------------| +| Docs / planning stream | `docs/-handoffs` | One or more files under `docs/handoffs/` | +| Feature implementation | `feat/-` or `mvp/-` | Code **plus** an updated handoff for that issue | +| Quick spike | `chore/` | Optional short `docs/handoffs/YYYY-MM-DD-.md` | + +Examples: `docs/mvp-handoffs`, `feat/75-policy-versioning`, `mvp/79-presidio-pii`. + +## File naming + +``` +docs/handoffs/YYYY-MM-DD-.md +``` + +Use the template: [`_TEMPLATE.md`](_TEMPLATE.md). + +## When to write + +- Starting a feature plan (MVP sub-issue or new epic slice) → create the handoff **before** large code moves +- After a mergeable chunk ships → update “What shipped” / “Open follow-ups” +- Closing an issue → handoff should say Done / residual debt + +## Skill + +Agents: use project skill **`feature-plan`** (`.agents/skills/feature-plan/` and `.cursor/skills/feature-plan/`). + +## Index + +| Date | Handoff | Branch / issue | Status | +|------|---------|----------------|--------| +| 2026-07-24 | [stabilize-contracts-and-ci](2026-07-24-stabilize-contracts-and-ci.md) | `dev` / #61–#64, #73, #84 | Done | +| 2026-07-24 | [mvp-continuous-compliance-gate](2026-07-24-mvp-continuous-compliance-gate.md) | `docs/mvp-handoffs` / #74 | In progress | diff --git a/docs/handoffs/_TEMPLATE.md b/docs/handoffs/_TEMPLATE.md new file mode 100644 index 0000000..b9d7f37 --- /dev/null +++ b/docs/handoffs/_TEMPLATE.md @@ -0,0 +1,41 @@ +# HANDOFF — + +**Status:** Planned | In progress | Done +**Branch:** `` +**Issue(s):** # +**Owner / next reader:** +**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 + +- [ ] … diff --git a/docs/handover/README.md b/docs/handover/README.md index fa09de1..7d2137a 100644 --- a/docs/handover/README.md +++ b/docs/handover/README.md @@ -79,3 +79,7 @@ Or use root `docker-compose.yml` when bringing up DB-backed stacks. - Default branch for work: `dev` - Prefer small PRs mapped to MVP sub-issues - `agy` is available on the `idea` host for implementation jobs; keep changes scoped to the issue + +## Per-feature handoffs + +Feature-level continuity lives in [`docs/handoffs/`](../handoffs/) (see skill `feature-plan`). This page stays project-wide. diff --git a/docs/mvp/README.md b/docs/mvp/README.md index dc80cdb..40797ce 100644 --- a/docs/mvp/README.md +++ b/docs/mvp/README.md @@ -39,6 +39,8 @@ ## References +- [Per-feature handoffs](../handoffs/) + skill `feature-plan` + - [Handover](../handover/README.md) - [Onboarding](../ONBOARDING.md) - [Audit (historical)](../audit/README.md)