@bankung/agent-teams 0.1.0

package/.env.example

@@ -0,0 +1,289 @@
+# Copy to .env (`cp .env.example .env`) and tweak as needed.
+# .env is loaded by both docker-compose (variable substitution) and
+# pydantic-settings inside the FastAPI app (when running uvicorn locally).
+
+# ----- Postgres -----
+# Password used by the db container AND by DATABASE_URL below. Change in any
+# non-dev environment. (Dev default kept simple so docker compose up "just works".)
+POSTGRES_PASSWORD=postgres
+
+# Host port the db container is published on. Change if 5432 is already in use.
+POSTGRES_PORT=5432
+
+# ----- API -----
+# Host port the api container is published on. Change if 8456 is already in use.
+API_PORT=8456
+
+# Application env flags consumed by api/src/settings.py.
+APP_ENV=development
+APP_DEBUG=true
+
+# Secret key for session signing / CSRF / token generation.
+# Generate with: python -c "import secrets; print(secrets.token_urlsafe(48))"
+# NEVER use a short or guessable value in production — warnIfInsecure() will
+# flag SECRET_KEY that is empty, contains 'dev-secret', or is shorter than 32 chars.
+SECRET_KEY=
+
+# Async DSN for SQLAlchemy + Alembic.
+# This URL targets the compose db FROM OUTSIDE the network — i.e. when you run
+# `cd api && uvicorn src.main:app --reload` on the host against the same
+# compose-managed Postgres. Inside the compose network the api service uses
+# host=db (set automatically in docker-compose.yml), so this var is ignored
+# inside the api container.
+DATABASE_URL=postgresql+asyncpg://postgres:postgres@localhost:5432/agent_teams
+
+# Filesystem root of the repo — used by project auto-scaffold to locate
+# context/projects/<name>/.
+# Required — pydantic-settings raises ValidationError if unset.
+# For local dev (running uvicorn from api/), set to the absolute path of the repo root,
+# e.g. REPO_ROOT=/path/to/agent-teams. Inside docker-compose, the api service overrides
+# this to /repo via the compose env block.
+REPO_ROOT=
+
+# ----- Web (Phase 3) -----
+# Host port the web container is published on. Change if 5431 is already in use.
+# Project-scoped port (mirrors api=8456 pattern) — avoids collision with the
+# Next.js default 3000 that other scaffolded projects may use.
+WEB_PORT=5431
+
+# Browser-visible API base URL inlined into the Next.js client bundle at build time.
+# - Host-direct dev (developer hits http://localhost:5431 → bundle calls http://localhost:8456): use http://localhost:8456
+# - Compose network: the browser still runs on the host, so this stays the host URL — the
+#   container-internal SSR override is INTERNAL_API_URL below (NOT this var).
+# NEXT_PUBLIC_* vars are visible in client JS — never put secrets here.
+NEXT_PUBLIC_API_URL=http://localhost:8456
+
+# Operator-opt-in personal-use feature; default off for pilot installs.
+# Set to "true" to show P&L panels on the project board and dashboard.
+NEXT_PUBLIC_FINANCE_PANELS_ENABLED=false
+
+# SSR / Server Component base URL — used by web/lib/api.ts when typeof window === 'undefined'
+# (i.e. fetches issued by the Next.js server process, not the browser).
+# - Inside docker-compose: docker-compose.yml passes http://api:8456 to the web container so
+#   SSR stays on the compose network (Linux-portable; Windows / macOS Docker Desktop also OK).
+# - Host-direct dev (next dev on the host, no compose web container): leave unset — web/lib/api.ts
+#   falls back to NEXT_PUBLIC_API_URL, which already resolves locally.
+# Kanban #704 — without this on Linux compose, SSR would fetch localhost:8456 inside the
+# container (= the container itself, not the host) and fail.
+INTERNAL_API_URL=http://api:8456
+
+# ----- LangGraph (Phase 4, Kanban #849) -----
+# Host port the langgraph container is published on. Change if 8465 is in use.
+LANGGRAPH_PORT=8465
+
+# Which LLM provider the LangGraph engine uses. One of: anthropic, openai, ollama, deepseek, google.
+# Default: anthropic. Switching providers needs only this var + the matching API key
+# (or, for ollama, a local Ollama server). Kanban #891 added ollama; #1086 added deepseek;
+# #1951 added google (native Gemini — required for multi-turn tool-calling; see note below).
+LANGGRAPH_LLM_PROVIDER=anthropic
+
+# Provider keys — set the one matching LANGGRAPH_LLM_PROVIDER. Leave the others blank.
+# Never commit real keys; .env is gitignored. (Ollama needs no key — it runs locally.)
+ANTHROPIC_API_KEY=
+OPENAI_API_KEY=
+# DeepSeek API key (Kanban #1086). Get yours at https://platform.deepseek.com/api-keys.
+DEEPSEEK_API_KEY=
+# Google / Gemini API key (Kanban #1951). Get yours at https://aistudio.google.com/app/apikey.
+# IMPORTANT: use LANGGRAPH_LLM_PROVIDER=google (native SDK) for Gemini, NOT openai +
+# OPENAI_BASE_URL. The OpenAI-compat endpoint drops Gemini's thought_signature on turn 2
+# causing HTTP 400 on multi-turn tool-calling. The native google provider handles it correctly.
+GOOGLE_API_KEY=
+
+# Optional model override per provider. Defaults baked into llm.py (#853, #891).
+ANTHROPIC_MODEL=claude-sonnet-4-6
+OPENAI_MODEL=gpt-4o
+
+# Optional base URL override for the openai provider. Empty = real OpenAI.
+# Set to an OpenAI-compatible endpoint to drive another provider, e.g. Gemini:
+#   OPENAI_BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai/
+OPENAI_BASE_URL=
+
+# Ollama provider (free local; install separately from https://ollama.com/).
+# Used only when LANGGRAPH_LLM_PROVIDER=ollama. The langgraph container reaches
+# the host's Ollama process via host.docker.internal (works on Mac + Win; on
+# Linux compose, add `extra_hosts: ["host.docker.internal:host-gateway"]` to
+# the langgraph service if needed).
+OLLAMA_MODEL=llama3.2
+OLLAMA_BASE_URL=http://host.docker.internal:11434
+
+# DeepSeek provider (Kanban #1086). V3 Chat default; deepseek-reasoner = R1 (chain-of-thought).
+# Used only when LANGGRAPH_LLM_PROVIDER=deepseek. Requires DEEPSEEK_API_KEY above.
+LANGGRAPH_DEEPSEEK_MODEL=deepseek-chat
+LANGGRAPH_DEEPSEEK_BASE_URL=https://api.deepseek.com
+
+# Google / Gemini native provider (Kanban #1951). Uses ChatGoogleGenerativeAI from
+# langchain-google-genai — the ONLY path that makes multi-turn tool-calling work on
+# Gemini (native SDK preserves thought_signature; OpenAI-compat endpoint does not).
+# gemini-flash-latest has quota on the operator's key. gemini-2.0-flash has quota=0.
+# Used only when LANGGRAPH_LLM_PROVIDER=google. Requires GOOGLE_API_KEY above.
+GOOGLE_MODEL=gemini-flash-latest
+
+# ----- LangGraph background worker (Phase 4, Kanban #852) -----
+# Which Kanban project the worker polls for next-autorun tasks. The container
+# refuses to start without this set (it has no way to guess which project's
+# board to poll). Dogfood default: 1 (the agent-teams project itself).
+LANGGRAPH_PROJECT_ID=1
+
+# Polling interval (seconds). The worker waits this long between calls to
+# /api/tasks/next-autorun. Lower = snappier task pickup; higher = cheaper
+# polling on quiet boards. Must be a positive integer.
+LANGGRAPH_POLL_INTERVAL_SEC=30
+
+# Override the Kanban API base URL the worker talks to. Default is the
+# compose-internal hostname http://api:8456. Override e.g. to
+# http://host.docker.internal:8456 when running the worker against an api
+# instance on the host. Trailing slash is stripped.
+LANGGRAPH_KANBAN_API_BASE=http://api:8456
+
+# Token budget for the tool-use loop's conversation-history compaction
+# (Kanban #1717). Deterministic heuristic (~len/4); older tool-result payloads
+# are stubbed/dropped to keep the re-sent history under this many tokens.
+# Positive integer; malformed/<=0 falls back to 60000.
+LANGGRAPH_CONTEXT_TOKEN_BUDGET=60000
+
+# ----- HITL demo branch gate (Kanban #1107 — WARN-2 security fix) -----
+# Set to "1" to enable the `HITL demo —` title-prefix branch in
+# langgraph/nodes.py:general_node. Used for live demos / onboarding workshops
+# so the engine's interrupt → resume loop can be exercised end-to-end against
+# the live stack.
+#
+# Leave EMPTY in production — any other value (including unset) keeps the
+# demo path INACTIVE. CWE-489 / OWASP A05: without the gate, any authenticated
+# user with task-create permission can trigger the hardcoded interrupt branch
+# just by prefixing their task title with "HITL demo —".
+#
+# Dev compose default: docker-compose.yml passes `HITL_DEMO_ENABLED:-1` so
+# the #1073 smoke task + onboarding demos work on a fresh checkout.
+HITL_DEMO_ENABLED=
+
+# ----- pytest_runner role password (Kanban #1109 — L4 prevention) -----
+# Last-resort DB-engine-layer gate for the 2026-05-17 dev-DB-wipe incident.
+# The alembic migration 0034_pytest_runner_role creates a constrained PG
+# role `pytest_runner` with this password; api/tests/conftest.py binds
+# pytest connections to that role. The role has:
+#   - full DDL/DML on `agent_teams_test` (owns the DB)
+#   - SELECT-only on `agent_teams` (live) — every destructive op REVOKEd
+# Effect: even if all software defenses (L1 hook / L2 conftest invariant /
+# L3 settings) are bypassed, the DB itself refuses INSERT/UPDATE/DELETE/
+# TRUNCATE on live data during pytest with `permission denied for table ...`.
+#
+# Dev default fallback: the compose env passes
+# `pytest_runner_dev_only_NOT_FOR_PROD` if you leave this blank, so a fresh
+# checkout's `docker compose up` "just works". Conftest emits a loud
+# UserWarning at load when running on the fallback. PRODUCTION deployments
+# MUST set a real password here (rotate via re-running `alembic upgrade
+# head` — the migration is idempotent and ALTERs the existing role's
+# password to the current env value).
+#
+# Cross-ref: incidents/2026-05-17-dev-db-wipe.md.
+PYTEST_DB_PASSWORD=
+
+# ----- Off-site encrypted backup (Kanban #959 + L12 #1120) -----
+# Minimum pg_dump output size (bytes) below which BackupRunner.run_once()
+# aborts BEFORE uploading. Defense against silent backup corruption when the
+# api container starts pointed at an empty/rogue DB: a sub-100KB dump would
+# get uploaded, retention would eventually delete the older good backups,
+# and restore would yield an empty DB. Default 102400 (100 KB) — a populated
+# agent_teams DB is multi-MB. Override only if you have a deliberately tiny
+# DB and accept the risk. Cross-ref:
+# incidents/2026-05-17-dev-db-wipe.md (sibling L8 = lifespan DB allowlist).
+BACKUP_MIN_BYTES=102400
+
+# ----- Web Push / VAPID (Kanban #955.A) -----
+# Generate a fresh keypair ONCE per deployment:
+#     docker compose exec -T api python -m scripts.generate_vapid_keys
+# The script prints three lines (public, private, subject placeholder) — copy
+# them into the three vars below. NEVER commit the PRIVATE key. The PUBLIC
+# key is also handed to the FE via its own env var in slice 955.C; both
+# halves must come from the same generated pair.
+#
+# Subject MUST be `mailto:<email>` or `https://<url>` per RFC 8292. The
+# default below works for the operator's personal deployment; change it for
+# other operators / shared deployments.
+#
+# Empty values are valid — the notify_web_push.py adapter surfaces
+# `missing_env_VAPID_*` and the router falls through cleanly (same posture
+# as TELEGRAM_BOT_TOKEN). The api container will start; only push delivery
+# is disabled until the keys are filled in.
+#
+# Slice 955.C — the FE container reads VAPID_PUBLIC_KEY too (via the
+# docker-compose mapping `NEXT_PUBLIC_VAPID_PUBLIC_KEY: ${VAPID_PUBLIC_KEY}`)
+# so the browser bundle has the public half for PushManager.subscribe().
+# No separate FE env var to configure — both sides come from this same value.
+VAPID_PUBLIC_KEY=
+VAPID_PRIVATE_KEY=
+VAPID_SUBJECT=mailto:admin@example.com
+
+# ----- Credentials vault (Kanban #1326 M3) -----
+# Fernet url-safe base64 master key for the project_credentials.ciphertext
+# column. REQUIRED — the api container's lifespan calls get_fernet() and
+# refuses to start if this is missing or malformed.
+#
+# AUTO-GENERATED on first install: bin/install.ps1 (Windows) and bin/install.sh
+# (macOS/Linux/WSL) detect an empty/missing value here and automatically generate
+# a valid Fernet key (URL-safe base64 of 32 random bytes). You do NOT need to
+# set this manually on a fresh clone — just run the installer.
+#
+# Manual generation (if needed):
+#     docker compose exec -T api python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
+#
+# BACKUP WARNING: losing the key makes ALL stored vault credentials permanently
+# unrecoverable. After install, copy the generated value to a password manager
+# or offline storage (USB, encrypted vault, etc.). The installer prints a
+# reminder at generation time.
+#
+# Rotation procedure (decrypt-with-old + re-encrypt-with-new per row):
+# see _scratch/standards-draft-credentials-rotation.md (Lead promotes to
+# context/standards/security/credentials-rotation.md).
+#
+# NEVER commit the real value. Leave this placeholder in .env.example.
+# The installer replaces it in the real .env file.
+CREDENTIALS_MASTER_KEY=
+
+# ----- Operator-action key (Kanban #1857 / #1852 Phase 1) -----
+# The platform's operator-vs-AI write-authorization secret. Read via os.environ
+# inside the api container ONLY (services/operator_auth.py). It is how a gated
+# write proves "a HUMAN operator did this" vs "an AI agent did this".
+#
+# 🔒 OPERATOR-ONLY — MUST NOT appear in the langgraph worker env nor any
+# agent-readable env. An agent that wants to forge the `X-Operator-Token` header
+# has nothing to forge it WITH only because this secret never enters its scope.
+# This is the ONE load-bearing discipline of the whole scheme (design §7),
+# identical in kind to the CREDENTIALS_MASTER_KEY discipline above. A leak turns
+# the gate into a blanket day-pass an agent can self-issue.
+#
+# ACTIVATION (the gate is INACTIVE by default — fail-open when unset):
+#   1. Set a strong random value here in the real .env (e.g.
+#        docker compose exec -T api python -c "import secrets; print(secrets.token_urlsafe(32))"
+#   2. Add `OPERATOR_ACTION_KEY: ${OPERATOR_ACTION_KEY:-}` to the **api** service
+#      `environment:` block in docker-compose.yml (NOT the langgraph block), then
+#        docker compose -p agent-teams up -d --force-recreate api
+#   3. Wire the secret into your operator verify-flow as the `X-Operator-Token`
+#      header on the PATCH /api/tasks/{id} that sets verified_by='user'/'operator'.
+# While UNSET, gated writes are ALLOWED (a one-time WARN is logged) so the code
+# can land without breaking the running app.
+#
+# NEVER commit the real value. Leave this placeholder in .env.example.
+OPERATOR_ACTION_KEY=
+
+# ----- Email tools (Gmail + Outlook OAuth) — Kanban #1604/#1608 -----
+# These are read via os.environ inside the api container (gmail_client.py,
+# outlook_client.py, gate.py). They MUST live here (root .env) so docker-compose
+# can substitute them into the api service environment block. The api/.env.example
+# carries setup instructions for local (non-docker) uvicorn runs only.
+#
+# Gmail OAuth — see api/.env.example Kanban #1604 for Google Cloud Console steps.
+# GOOGLE_OAUTH_CLIENT_ID=
+# GOOGLE_OAUTH_CLIENT_SECRET=
+# GOOGLE_OAUTH_REDIRECT_URI=http://localhost:8456/api/tools/email/auth/gmail/callback
+#
+# Email-tools shared rate/audit config
+# EMAIL_TOOLS_DAILY_UNITS_CAP=5000
+# EMAIL_TOOLS_BULK_THRESHOLD=100
+# EMAIL_TOOLS_AUDIT_PATH=/repo/_scratch/email-tools-audit.jsonl
+#
+# Outlook OAuth — see api/.env.example Kanban #1608 for Azure portal steps.
+# AZURE_OAUTH_CLIENT_ID=
+# AZURE_OAUTH_CLIENT_SECRET=
+# AZURE_OAUTH_TENANT=consumers
+# AZURE_OAUTH_REDIRECT_URI=http://localhost:8456/api/tools/email/auth/outlook/callback

package/README.md

@@ -0,0 +1,143 @@
+# agent-teams
+
+**A self-hosted orchestration and governance layer that turns Claude Code or OpenAI Codex into a persistent, governed, multi-domain agent team.**
+
+You know the feeling: the coding session that started sharp is now drifting, re-explaining itself, and holding your entire plan hostage. A single CLI is a powerful brain with no memory across sessions, no project structure, and no safety rails.
+
+agent-teams closes that gap. It wraps your coding CLI with a Postgres-backed Kanban, a Lead meta-orchestrator that spawns fresh domain specialists per task, a five-zone context model, and a defense-in-depth safety layer. File the queue, step away, trust it's handled — the leverage of a whole team, without the burnout of being one.
+
+Everything runs locally in Docker. No cloud sign-up, no SaaS subscription, no code leaving your network.
+
+It is also **dogfooded**: agent-teams builds agent-teams. The repo's own commit history and Kanban are living proof.
+
+---
+
+## Why it's different
+
+Claude Code already gives you sub-agents, and you can keep several sessions open. agent-teams is the layer that makes that raw power actually land: every task becomes a clean, scoped contract instead of one sprawling chat you keep having to wrangle.
+
+| | Self-hosted | Persistent task/project state | Beyond code | Governance/safety layer | Form |
+|---|:--:|:--:|:--:|:--:|---|
+| Cloud SWE agents (Devin, Cursor, Windsurf) | ✗ | ✗ session/codebase | ✗ code-only | black-box | product / IDE |
+| AI assistant (GitHub Copilot) | ✗ | ✗ chat-scoped | ✗ code-only | black-box | product |
+| Agent frameworks (CrewAI, AutoGen, LangGraph) | ✓ lib | ✗ you build it | ✓ DIY | ✗ you build it | library |
+| Self-hosted platform (OpenHands) | ✓ | ~ less structured | ~ dev-focused | local isolation | product / SDK |
+| **agent-teams** | ✓ | ✓ Postgres Kanban + 5-zone context | ✓ team playbooks (dev/content/SEO/…) | ✓ defense-in-depth + AC + HITL + cost | **layer on Claude Code / Codex** |
+
+The gap it fills: a **self-hosted, persistent, governed, multi-domain orchestration layer** — the cloud agents and IDEs aren't self-hosted or persistent, and the frameworks hand you a toolbox and a weekend of plumbing. This is the part you'd otherwise build yourself, at night, instead of shipping: the state, the governance, and the team structure, already wired.
+
+---
+
+## What's genuinely special
+
+- **Tasks are contracts — with proof.** Every task carries structured acceptance criteria. Before a task can be marked done, each criterion is verified with evidence and stamped passed/failed. The system proves the work met the contract; it doesn't just claim "done." Hard cost guardrails (daily/monthly budget caps → `429`) and a full `tasks_history` audit trail are built in.
+
+- **Batch and parallel without context rot.** Queue tasks, run them back-to-back or in parallel — each spawns a fresh domain specialist with scoped context. No sprawling conversation, no bleed-through. The Kanban holds the plan; the agents hold nothing stale.
+
+- **Two execution modes.** Mode A (production today): Claude Code or Codex drives each specialist interactively with per-action approval — you keep control. Mode B (actively in development): flip a task to `auto_headless` and the LangGraph engine runs it with no terminal open, Postgres-checkpointed.
+
+- **Rich planning views.** Board · List · Calendar · Gantt in one switcher. Calendar supports week/month with drag-to-reschedule. Gantt doubles as the milestone home — drag a task straight onto a milestone and watch the progress rollup update.
+
+- **Extend without migrations.** Add a new team or new agent types by editing constants and dropping a markdown file — no DB migration required. 8 teams and ~39 specialist agent definitions ship today. → [How to add a team](readme_dev.md#team-roster--dev-team) · [Full onboarding runbook](context/teams/dev/team-onboarding-runbook.md)
+
+- **Self-hosted, local-first, dogfooded.** Runs in Docker on your machine. Anthropic, OpenAI, or fully-local Ollama — your choice, one `.env` variable. No code leaves your network. And the system building itself is the system you're reading about: the commit log and live Kanban are the proof.
+
+---
+
+## What it is — and isn't
+
+**It is:** an orchestration and governance layer on top of a coding CLI. Works today with **Claude Code** and **OpenAI Codex**.
+
+**It isn't:**
+- a frontier autonomous SWE agent like **Devin** — it orchestrates your coding agent, it doesn't replace one;
+- an IDE like **Cursor** or **Windsurf** — no editor here; keep your own;
+- a from-scratch agent framework like **CrewAI** / **AutoGen** / **LangGraph** — it actually *uses* LangGraph for its headless engine rather than reinventing it.
+
+**Honest status on the headless engine:** today the production path is Mode A — Claude Code / Codex CLI driven interactively (per-action approval). The `langgraph` service (supervisor → specialist graph, Postgres-checkpointed) is the Mode B path and is **actively in development**. Don't rely on it for critical work yet.
+
+---
+
+## Architecture at a glance
+
+```mermaid
+flowchart TD
+    Operator([Operator]) -->|files tasks, answers HITL| Kanban[(Kanban · Postgres)]
+    Operator -->|talks to| Lead[Lead · meta-orchestrator]
+    Lead -->|reads| Playbook[Team playbook]
+    Lead -->|resolves project, spawns| Specialists[Specialists: backend / frontend / tester / reviewer / …]
+    Specialists -->|run on| CLI[Claude Code / Codex CLI]
+    Lead <-->|read/write state| Context[(5-zone context:<br/>standards · team · project · role)]
+    Specialists -->|update| Kanban
+    CLI -.headless path.-> Engine[LangGraph engine · Postgres checkpoints]
+```
+
+The Lead reads the team playbook, resolves the active project, and spawns the right specialists. Specialists run on your coding CLI and write their results back to the Kanban and five context zones — no context leaks between tasks.
+
+---
+
+## CLI-agnostic by design
+
+The orchestration works across coding CLIs because the rules live in portable instruction files: [`CLAUDE.md`](CLAUDE.md) for Claude Code and [`AGENTS.md`](AGENTS.md) for Codex. Same governance, same lanes, same team structure — whichever CLI you run. You're not locked to one vendor.
+
+---
+
+## Get started
+
+1. Install [Docker Desktop](https://www.docker.com/products/docker-desktop/) and restart your computer.
+2. Open a terminal **in this folder** and run the installer:
+   - **macOS / Linux / WSL:** `./bin/install.sh`
+   - **Windows (PowerShell):** `.\bin\install.ps1` *(if scripts are blocked, run `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned` once first)*
+3. Open **http://localhost:5431** — your Kanban board. The installer seeds a `demo-tour` project to explore. Create tasks, queue them, and answer agent questions as they come up.
+
+Two ways to put agents to work:
+
+- **Mode A — Claude Code / Codex session (production today).** Open this repo in Claude Code or OpenAI Codex. The Lead resolves your project, loads the team playbook, and orchestrates specialists end-to-end. → **[CLAUDE-CODE-START.md](CLAUDE-CODE-START.md)**
+- **Mode B — One-click "Start" on the board *(in active development)*.** Flip a task to auto-run and the headless `langgraph` engine handles it with no terminal open. See "What it is — and isn't" above for the honest status.
+
+The installer is safe to re-run; services keep running after you close the terminal.
+
+**Multi-provider, local-first.** Switch models with one `.env` variable (`LANGGRAPH_LLM_PROVIDER`): **Anthropic** (default), **OpenAI**, or **Ollama** for fully local inference — no API key, no network egress. With Ollama, nothing leaves your machine.
+
+**Stop / reset:** `docker compose down` to stop; `.\bin\reset.ps1` (or `./bin/reset.sh`) to wipe and start fresh.
+
+---
+
+## Slash-command skills (tn-*)
+
+These are reusable Claude Code commands that encode Kanban API conventions, preventing common mistakes (missing project_id, incomplete acceptance criteria, status-change guard violations). They activate after a Claude Code restart and are auto-detected on live-reload.
+
+| Command | What it does |
+|---------|-------------|
+| **Tasks** | |
+| `/tn-task-create <description>` | Create a Kanban task correctly (project_id in request body, acceptance_criteria at creation). |
+| `/tn-task <id>` | Show one task with its acceptance criteria (read-only). |
+| `/tn-tasks-next [N]` | List the next N actionable tasks (current milestone first, blockers first, then priority; N defaults 10). |
+| `/tn-task-done <id>` | Verify every acceptance criterion, then flip the task to DONE (refuses if any criterion is unmet). |
+| `/tn-task-update <id> <changes>` | Guarded status/priority update (BLOCKED only via blocked_by; status changes carry a reason; DONE is redirected to /tn-task-done). |
+| `/tn-task-attach <task> <milestone>` | Attach a task to a milestone (same-project checked). |
+| **Milestones** | |
+| `/tn-milestone-create <title>` | Create a milestone (defaults to "planned"). |
+| `/tn-milestone-done <id>` | Release a milestone after checking its child tasks are complete. |
+| `/tn-milestones` | List milestones with their task rollup (done/total, progress %). |
+| **Workflow** | |
+| `/tn-intense-review <scope>` | 2-round adversarial review + test-hardening pass (reviewers + determinism loop). |
+| `/tn-spec <idea>` | 2 rounds of spec pushback + revision before creating a task. |
+| **Project** | |
+| `/tn-bind <project>` | Bind the session to a project by name (resolves + persists the active project). |
+| `/tn-audit [project]` | On-demand project health audit (3 metrics + continue/review/pause). |
+
+Each skill lives at `.claude/skills/<name>/SKILL.md` and is invoked as `/<name>` in Claude Code.
+
+---
+
+## Learn more
+
+Companion docs go deep so this README stays scannable:
+
+- **[QUICKSTART.md](QUICKSTART.md)** — 5-minute tour via the browser UI.
+- **[CLAUDE-CODE-START.md](CLAUDE-CODE-START.md)** — driving the team from a Claude Code terminal session.
+- **[USAGE-POWER.md](USAGE-POWER.md)** — parallel agents, auto-mode, multi-project workflows, mobile remote access.
+- **[readme_dev.md](readme_dev.md)** — architecture deep-dive: storage zones, team rosters, configuration, and extensibility (including how to add a new team or agent type).
+- **[context/teams/dev/team-onboarding-runbook.md](context/teams/dev/team-onboarding-runbook.md)** — full step-by-step runbook for adding teams and agents.
+
+For the full development history, browse the git log and the Kanban that drove it — dogfooding in action.

package/cli/README.md

@@ -0,0 +1,140 @@
+# agent-teams CLI
+
+Zero-dependency Node.js CLI that launches the agent-teams AI Kanban platform
+locally via Docker Compose.
+
+## Prerequisites
+
+**Docker Desktop** (or Docker Engine on Linux) must be installed and running
+before any CLI command will work. This package does NOT install Docker.
+
+**git** must be installed and on PATH. It is required when running the CLI
+outside a cloned repository (standalone mode — see below). This package does
+NOT install git.
+
+- Docker: <https://docs.docker.com/get-docker/>
+  - Windows / macOS: install Docker Desktop and start it.
+  - Linux: install Docker Engine + `docker compose` plugin and ensure the daemon
+    is running (`sudo systemctl start docker`).
+- git: <https://git-scm.com/downloads>
+
+## Quick start
+
+```bash
+npx @bankung/agent-teams up
+```
+
+This command works in several modes. Choose the one that fits your situation:
+
+### Model A — pull pre-built images (fastest, no clone)
+
+```bash
+npx @bankung/agent-teams up --images
+```
+
+Pulls pre-built images from the GitHub Container Registry (GHCR) and starts
+the full stack. **No git clone or local build required** — Docker just pulls
+the images. This is the recommended path for users who want to run the platform
+without modifying source code.
+
+Aliases: `--images` and `--pull` are equivalent.
+
+Requirements:
+- Docker Desktop (or Docker Engine) installed and running.
+- Images must be published to GHCR by the release CI (`v*` tag push). If you
+  want to pin a specific version set `AGENT_TEAMS_VERSION=1.2.3` in `.env`.
+
+### Model B — clone + build from source (default)
+
+#### Standalone mode (run from any empty directory)
+
+```bash
+mkdir my-agent-teams && cd my-agent-teams
+npx @bankung/agent-teams up
+```
+
+The CLI detects that `docker-compose.yml` is absent, clones
+`https://github.com/bankung/agent-teams.git` into `<cwd>/agent-teams`, then
+builds and starts the stack from that cloned directory.
+
+**Note:** Standalone mode requires the GitHub repository to be public.
+
+**Note:** The first `up` builds Docker images from source — this can take
+several minutes. Subsequent runs use the Docker layer cache and are fast.
+
+You can override the clone destination:
+
+```bash
+npx @bankung/agent-teams up /path/to/target-dir
+```
+
+#### In-repo mode (run from inside a cloned repository)
+
+```bash
+git clone https://github.com/bankung/agent-teams.git
+cd agent-teams
+npx @bankung/agent-teams up
+```
+
+The CLI detects `docker-compose.yml` in the package root and uses the existing
+checkout directly — no clone occurs.
+
+### What `up` does (both modes)
+
+1. Verifies the Docker daemon is reachable (clear error if not).
+2. **`--images` mode:** pulls pre-built GHCR images.
+   **Default mode:** resolves/clones the repo root, then runs `docker compose up -d --build`.
+3. Copies `.env.example` to `.env` if no `.env` exists yet.
+4. Generates a `CREDENTIALS_MASTER_KEY` (Fernet key) if the value is empty —
+   prints a backup reminder. **Back up this key to a password manager.**
+5. Applies database migrations (`alembic upgrade head`).
+6. Waits up to 60 seconds for the API to become healthy on port 8456.
+7. Runs the seed script (idempotent — safe to re-run).
+8. Prompts for your Claude Code plan (Max / Pro) and applies the matching tier
+   preset. Skipped automatically in non-interactive environments.
+9. Prints the Kanban URL and attempts to open it in your default browser.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `up [targetDir]` | Build and start all services. Idempotent — safe to run on an existing install. In standalone mode, clones the repo first. |
+| `up --images` | Pull pre-built images from GHCR and start all services. No clone or build. Alias: `--pull`. |
+| `down` | Stop all containers. Volumes (database data) are preserved. |
+| `status` | Show container health (`docker compose ps`) and probe the API on :8456. |
+| `reset` | **Destructive.** Wipes the Postgres volume (all data gone) and rebuilds. Prompts for confirmation (type `WIPE`) unless `--yes` is passed. |
+| `--help` / `help` | Print usage. |
+| `--version` | Print CLI version. |
+
+### `reset` bypass
+
+```bash
+# flag
+npx @bankung/agent-teams reset --yes
+
+# env var
+AGENT_TEAMS_RESET_YES=1 npx @bankung/agent-teams reset
+```
+
+### Pinning an image version
+
+Set `AGENT_TEAMS_VERSION` in your `.env` (or export it) to pull a specific
+release rather than `latest`:
+
+```bash
+echo "AGENT_TEAMS_VERSION=1.2.3" >> .env
+npx @bankung/agent-teams up --images
+```
+
+Images are published to GHCR by the GitHub Actions workflow
+`.github/workflows/release-images.yml` on every `v*` tag push. `npm publish`
+is performed by the operator separately.
+
+## Port defaults
+
+| Service | Default port | Override via .env |
+|---------|-------------|-------------------|
+| Web (Kanban UI) | 5431 | `WEB_PORT` |
+| API | 8456 | `API_PORT` |
+| PostgreSQL | 5432 | `POSTGRES_PORT` |
+| LangGraph | 8465 | `LANGGRAPH_PORT` |