diff --git a/README.md b/README.md index a087a903..863d8c0b 100644 --- a/README.md +++ b/README.md @@ -59,6 +59,17 @@ Open [http://localhost:3000](http://localhost:3000) — that's it. The board aut --- +## 📚 Documentation Map + +- [Getting Started Guide](docs/GETTING-STARTED.md) — zero ➝ agent-ready in 5 minutes, plus sanity checks and prompt registry tips. +- [Agent Task Workflow SOP](docs/SOP-agent-task-workflow.md) — lifecycle, API/CLI snippets, prompts. +- [Sprint Planning SOP](docs/SOP-sprint-planning.md) — epic → sprint → task breakdown. +- [Multi-Agent Orchestration](docs/SOP-multi-agent-orchestration.md) — PM + worker handoffs. +- [Cross-Model Code Review](docs/SOP-cross-model-code-review.md) — enforce Claude ↔ GPT reviews. +- [Best Practices](docs/BEST-PRACTICES.md) & [Tips + Tricks](docs/TIPS-AND-TRICKS.md) — patterns, shortcuts, integrations. +- [Real-World Examples](docs/EXAMPLES-agent-workflows.md) — copy/pasteable agent recipes. +- [Troubleshooting](docs/TROUBLESHOOTING.md) — deeper diagnostics when things wobble. + ## ⚠️ Agentic AI Safety > [!CAUTION] diff --git a/docs/BEST-PRACTICES.md b/docs/BEST-PRACTICES.md new file mode 100644 index 00000000..4a140384 --- /dev/null +++ b/docs/BEST-PRACTICES.md @@ -0,0 +1,75 @@ +# Best Practices & Anti-Patterns + +Codify what works (and what burns us) when running Veritas Kanban with humans + AI agents. + +--- + +## Do This + +1. **Always track time** + - Start timers with `vk begin` the moment you pick up a task. + - If you forgot, add a manual entry with reason. Time data fuels estimation and billing. + +2. **Use subtasks as living checklists** + - Break work into 3–8 subtasks. + - Mark them complete as you progress; unfinished subtasks make blockers obvious. + +3. **Write acceptance criteria inside the task description** + - Bullet list or checklist. Agents need crisp definitions of done. + +4. **Post completion summaries + links** + - Final comment should include what changed, where to find artifacts, and next steps. + +5. **Keep tasks atomic** + - One deliverable per task. If work spans >3 days or mixes unrelated goals, split it. + +6. **Update SOP files after every lesson** + - Mistake → update AGENTS.md/CLAUDE.md + Lessons Learned field. + +7. **Respect cross-model review** + - Treat it like CI. No code ships without the opposite model’s signoff. + +8. **Mirror important artifacts to Brain/knowledge base** + - Use `scripts/brain-write.sh` or equivalent so humans can find deliverables later. + +9. **Use Agent Status + comments for visibility** + - Set `vk agent working` when you start; leave concise updates in comments instead of DM spam. + +10. **Archive aggressively** + - Done column should stay lean. Use multi-select + archive (bug tracked separately) at sprint end. + +--- + +## Don’t Do This + +1. **Tasks without acceptance criteria** + - Leads to rework and ambiguous reviews. + +2. **Skipping time tracking** + - “It was quick” is not data. Even 5-minute fixes get tracked. + +3. **Giant grab-bag tasks** + - “Implement feature + write docs + shoot video” belongs in separate tasks. + +4. **Auto-piloting agents without supervision** + - Always read summaries, review diffs, enforce cross-model review. + +5. **Letting prompts drift** + - Keep prompt registry updated or agents will regress. + +6. **Leaving example tasks in production boards** + - Clear the seed tasks before real work to avoid confusion. + +7. **Treating planning as a board status** + - Planning is a checklist/subtask, not `TaskStatus`. Valid statuses: todo, in-progress, blocked, done. + +8. **Storing secrets in tasks** + - Use vault/secret manager references, never raw credentials. + +9. **Ignoring Lessons Learned** + - If you uncover a process flaw and don’t log it, you’ll repeat it next sprint. + +10. **Copy/pasting unvetted external code** + - Run security review (see RF-002) and cite sources. + +Stick to these rules and the board stays trustworthy even with dozens of agents in parallel. diff --git a/docs/EXAMPLES-agent-workflows.md b/docs/EXAMPLES-agent-workflows.md new file mode 100644 index 00000000..5dd829c1 --- /dev/null +++ b/docs/EXAMPLES-agent-workflows.md @@ -0,0 +1,94 @@ +# Real-World Agent Workflow Examples + +Steal these end-to-end flows when building your own automations. Each example shows the goal, prompts, API/CLI calls, and outputs we expect. + +--- + +## 1. Feature Development Sprint (BrainMeld PRD excerpt) + +**Goal:** Build "Lessons Learned" field. + +1. **Create task** + ```bash + vk create "Feature: Lessons Learned field" --project veritas-kanban --type feature --priority medium + ``` +2. **Prompt (worker)** + ``` + Implement markdown lessonsLearned field on tasks (UI + API). Include migration + docs. Cross-model review required. + ``` +3. **Workflow** + - `vk begin ` + - Implement server -> shared -> web changes + - Update docs + tests + - `vk done "Added lessons learned field"` +4. **Outputs** + - Task summary with PR link + - Lessons Learned comment describing future usage + +--- + +## 2. Bug Fix (Archive bulk action) + +**Goal:** Sprint archive button fails. + +1. Create bug task referencing GitHub Issue #86. +2. Subtasks: + - Reproduce in dev + - Inspect network requests + - Patch bulk archive handler + - Add regression test (Playwright) +3. CLI flow: `vk begin`, fix, `vk done "Bulk archive now calls API"` +4. Cross-model review ensures UI + API parity. + +--- + +## 3. Documentation Update + +**Goal:** Add sanity checks to Getting Started. + +1. Task description includes sections to cover (API, UI, agent pickup). +2. Agent edits `docs/GETTING-STARTED.md` + `docs/TROUBLESHOOTING.md` references. +3. Completion summary links to diff + screenshot placeholders. + +--- + +## 4. Security Audit (RF-002 style) + +**Goal:** Run cross-model audit on repo. + +1. Task -> `type=security`, `project=veritas-kanban`. +2. Subtasks: scope, run Codex audit, run Claude review, compile findings, create issues. +3. Agents spawn using research prompt template, save results to `refactoring/rf-002/*`. +4. Deliverables: Markdown report, HTML deck, GitHub issues. + +--- + +## 5. Content Production (Podcast clip → LinkedIn post) + +1. Task `type=content` with acceptance criteria (summary, caption, schedule time). +2. Agent fetches transcript, writes summary, drafts LinkedIn copy, saves assets to `projects/start-small-think-big/...`. +3. Completion summary includes copy + asset path; lessons learned capture platform insights. + +--- + +## 6. Research & Report (Champions) + +1. Task `type=research`, project `social`, sprint `CHAMP-02`. +2. Prompt includes dossier template, required sources, HTML deck requirement. +3. Agent workflow: gather sources, write Markdown, generate HTML via script, `brain-write.sh` to mirror. +4. Final comment: TL;DR + links to both artifacts. + +--- + +## Pattern to Copy + +For any workflow: + +1. **Task** with crystal-clear done definition. +2. **Prompt** stored in registry. +3. **API/CLI** calls scripted (vk begin/done, time tracking, status updates). +4. **Artifacts** saved to predictable paths and mirrored to Brain/engram if needed. +5. **Cross-model review** if code/critical. +6. **Lessons learned** field updated for systemic knowledge. + +Use these recipes as seeds for your own automation playbooks. diff --git a/docs/GETTING-STARTED.md b/docs/GETTING-STARTED.md new file mode 100644 index 00000000..075a3a86 --- /dev/null +++ b/docs/GETTING-STARTED.md @@ -0,0 +1,266 @@ +# Getting Started with Veritas Kanban + +> **Credit:** This guide exists because **Neal (@nealmummau)** asked how to get Veritas Kanban working with AI agents in under five minutes. Thank you for pushing us to document the real workflow. + +Whether you are standing up the board for yourself or for a fleet of agents, this guide walks you from zero ➝ working board ➝ agents picking up work. Each section is short, copy/paste friendly, and mirrors how we run Veritas Kanban internally. + +--- + +## Table of Contents + +1. [Prerequisites (30 seconds)](#prerequisites-30-seconds) +2. [Installation & Setup Wizard (manual today, guided tomorrow)](#installation--setup-wizard-manual-today-guided-tomorrow) +3. [Create Your First Task (UI path)](#create-your-first-task-ui-path) +4. [Create Your First Task (API/CLI path)](#create-your-first-task-apicli-path) +5. [Connect an Agent + Agent Pickup Checklist](#connect-an-agent--agent-pickup-checklist) +6. [Sanity Checks & Quick Fixes](#sanity-checks--quick-fixes) +7. [Shared Resources & Prompt Registry](#shared-resources--prompt-registry) +8. [Documentation Freshness & Repo Rules](#documentation-freshness--repo-rules) +9. [Multi-Repo / Multi-Agent Notes](#multi-repo--multi-agent-notes) +10. [OpenClaw Browser Relay (Optional but recommended)](#openclaw-browser-relay-optional-but-recommended) +11. [What’s Next?](#whats-next) + +--- + +## Prerequisites (30 seconds) + +| What | Command | Notes | +| ----------------- | ------------------ | -------------------------------------------------- | +| Node.js | `node -v` | Requires **22+**. Install via Volta/nvm if older. | +| pnpm | `pnpm -v` | Requires **9+**. `npm install -g pnpm` if missing. | +| Git | `git --version` | Any current version works. | +| (Optional) Docker | `docker --version` | Needed only if you prefer containers. | + +That’s it. No database, no extra services. + +--- + +## Installation & Setup Wizard (manual today, guided tomorrow) + +A scripted setup wizard (`vk setup`) is on the roadmap. Until it ships, follow the manual wizard below (same phases you’ll see in the UI later): + +### 1. Clone & install + +```bash +git clone https://github.com/BradGroux/veritas-kanban.git +cd veritas-kanban +pnpm install +``` + +### 2. Configure server + +a. Copy the sample env + +```bash +cp server/.env.example server/.env +``` + +b. Edit the new file: + +- `VERITAS_ADMIN_KEY` → 32+ chars (use `node -e "console.log(crypto.randomBytes(32).toString('hex'))"`) +- `VERITAS_AUTH_ENABLED=true` (default) +- `VERITAS_AUTH_LOCALHOST_BYPASS=true` to avoid auth friction locally +- Optional: set `HOST=127.0.0.1` (avoids proxy ambiguity) + +### 3. Start the dev stack + +```bash +pnpm dev +``` + +Web boots on **3000**, API on **3001**. First boot seeds demo tasks so you have something to look at. + +![Dev stack running](../assets/demo-overview.gif) + +### 4. Run the in-app setup + +Visit [http://localhost:3000](http://localhost:3000) → follow the onboarding form: + +- Create your admin password +- Save the recovery key (seriously; it’s the only way to regain access) +- Log in and confirm you can see the seeded board + +> 🧙 **Setup Wizard roadmap:** v1.5 will ship an interactive `vk setup` CLI that steps through these same actions, validates ports, and optionally provisions starter API keys. + +--- + +## Create Your First Task (UI path) + +1. Click **New Task** on the board. +2. Fill title, description (Markdown), pick a type + priority. +3. Optional: assign a sprint/project. +4. Hit **Create** and watch it appear in **Todo**. +5. Drag it to **In Progress** to feel the flow. + +![Creating a task via UI](../assets/demo-task.gif) + +> Need a clean slate? Remove the example tasks: `rm tasks/active/task_example_*.md` + +--- + +## Create Your First Task (API/CLI path) + +### REST call (curl) + +```bash +curl -X POST http://localhost:3001/api/tasks \ + -H "Content-Type: application/json" \ + -H "X-API-Key: " \ + -d '{ + "title": "Wire up MCP server", + "description": "Create CLI + MCP parity", + "type": "feature", + "priority": "high" + }' +``` + +### CLI (after `cd cli && npm link`) + +```bash +vk create "Wire up MCP server" --type feature --priority high +vk list --status todo +``` + +CLI commands fully mirror the API and are the fastest way to script agent workflows. + +![CLI workflow demo](../assets/demo-drag_drop.gif) + +--- + +## Connect an Agent + Agent Pickup Checklist + +Agents interact through HTTP + WebSocket; nothing is hard-coded to a particular provider. Follow this checklist to verify they can pick up work: + +1. **Create an agent API key** in `server/.env`: + ``` + VERITAS_API_KEYS=my-agent:super-secret-key:agent,ops:another-key:admin + ``` +2. **Restart** `pnpm dev` so the key loads. +3. **Create an agent request** (UI → Start Agent) or drop a JSON file in `.veritas-kanban/agent-requests/`. +4. **Watch pending agents** in the UI or via CLI: + ```bash + vk agents:pending + ``` +5. **Agent workflow** (example prompt to OpenClaw): + ``` + Hey Veritas, pick up task . Set status to in-progress, start the timer, do the work, then call `vk done "summary"` when finished. Use cross-model review if you wrote code. + ``` +6. **Agent completion** + - Verify `tasks/active/...` reflects status/time tracking + - Check `.veritas-kanban/logs/agents.log` for run details + - Confirm UI Agent Status indicator flips back to **Idle** + +![Agent status indicator](../assets/demo-task.gif) + +> **Automation tip:** Keep a `prompts/` folder (see below) so agents get consistent instructions for sprint planning, reviews, research, etc. + +--- + +## Sanity Checks & Quick Fixes + +These cover the “something feels off” moments before you deep-dive logs. + +### 1. API health (up in <1s) + +```bash +curl -s http://localhost:3001/api/health | jq +``` + +Expect `{ "ok": true, "service": "veritas-kanban", ... }`. If the call hangs or returns HTML, something else is on the port. + +### 2. UI health + +- Browser hard refresh (`Cmd/Ctrl + Shift + R`) +- If blank, open devtools → Console for errors. +- Verify WebSocket indicator (top right) shows **Connected**; if not, check proxies/CORS. + +### 3. Agent pickup sanity + +- `.veritas-kanban/agent-requests/` should have JSON per request. If files accumulate, agents are not acknowledging them. +- `vk agents:pending` returning nothing while UI shows pending usually means API key mismatch; regenerate and restart. + +### 4. Common failure modes & instant fixes + +| Symptom | Quick Fix | +| --------------------------- | ------------------------------------------------------------- | +| Ports collide / UI hung | `pnpm dev:clean` | +| Health endpoint returns 404 | Wrong project running on 3001 (restart) | +| Auth spamming rate limit | Ensure request IP is `127.0.0.1` or increase limiter | +| Agents “never pick up” | Verify API key role `agent`, check firewall/Docker networking | + +For deeper debugging see [docs/TROUBLESHOOTING.md](TROUBLESHOOTING.md). + +--- + +## Shared Resources & Prompt Registry + +BoardKit Orchestrator inspired us here: keep prompts, skills, and guidelines in one place so every repo/agent stays in sync. + +**Until first-class registry lands in v1.5, do this manually:** + +1. Create `shared/prompt-registry/` at the repo root (git-tracked). +2. Add Markdown files per workflow, e.g.: + - `shared/prompt-registry/sprint-planning.md` + - `shared/prompt-registry/code-review.md` + - `shared/prompt-registry/research-report.md` +3. Reference them inside tasks (`See prompt: shared/prompt-registry/...`). +4. When spawning agents (OpenClaw `sessions_spawn`), paste the relevant prompt so the run is reproducible. + +> **Future state:** US-1611 will move this into `.veritas-kanban/templates/prompts.json` with UI + API surfaces. Document your prompts now so migration is painless later. + +--- + +## Documentation Freshness & Repo Rules + +Stale docs = hallucinating AI. Keep these files current: + +| File | Purpose | +| ------------------------------ | -------------------------------------------------------------- | +| `AGENTS.md` | Personality, escalation rules, cross-model review requirement. | +| `SOUL.md` | “Who are we?” — tone/voice used by agents. | +| `CLAUDE.md` / `GPT.md` | Model-specific guardrails or lessons learned. | +| `docs/BEST-PRACTICES.md` (new) | Patterns and anti-patterns all agents follow. | + +**Cadence:** + +- Update immediately after a mistake or new learning. +- Mirror to Brain/knowledge base if you use one (see `scripts/brain-write.sh`). +- During sprint closure, skim the “Lessons Learned” field on each task and propagate anything evergreen into AGENTS/CLAUDE. + +--- + +## Multi-Repo / Multi-Agent Notes + +Running multiple projects or repos with the same agent pool? Borrow BoardKit’s approach: + +- Keep shared assets (skills, prompts, SOPs) under a top-level `shared/` folder. +- For each repo, mount/symlink only what you need (manual today; native support in US-1611). +- Use consistent naming for agent API keys so dashboards stay readable (`project-agent-name`). +- Record sub-agent usage with `vk agent sub-agent ` so the Agent Status sidebar matches reality. + +--- + +## OpenClaw Browser Relay (Optional but Recommended) + +For auth-required workflows (LinkedIn research, dashboards behind Okta, etc.) you’ll want OpenClaw’s Browser Relay: + +1. Install the extension + helper from the [OpenClaw docs](https://github.com/openclaw/openclaw). +2. Launch the relay; attach your tab. +3. Agents can now run headless instructions through your actual browser session while respecting your credentials. + +This is invaluable for Champions-style research tasks or anything needing a real login flow. + +--- + +## What’s Next? + +1. Read the SOPs: + - [Agent Task Workflow](SOP-agent-task-workflow.md) + - [Sprint Planning with AI Agents](SOP-sprint-planning.md) + - [Multi-Agent Orchestration](SOP-multi-agent-orchestration.md) + - [Cross-Model Code Review](SOP-cross-model-code-review.md) +2. Align on [Best Practices](BEST-PRACTICES.md) & [Tips + Tricks](TIPS-AND-TRICKS.md). +3. Browse [Real-world Examples](EXAMPLES-agent-workflows.md) and steal the prompts. +4. Keep `docs/TROUBLESHOOTING.md` handy for deeper diagnostics. + +You now have a board, agents that can pick up work, and a safety net when things wobble. Go ship something. diff --git a/docs/SOP-agent-task-workflow.md b/docs/SOP-agent-task-workflow.md new file mode 100644 index 00000000..23925124 --- /dev/null +++ b/docs/SOP-agent-task-workflow.md @@ -0,0 +1,120 @@ +# SOP: Agent Task Workflow (Create → Work → Complete) + +Use this playbook anytime an agent (human or LLM) takes a task from **todo** to **done**. It standardizes status changes, time tracking, summaries, and ensures telemetry stays usable. + +--- + +## Roles + +| Role | Responsibilities | +| ------------------ | --------------------------------------------------------------------------------------- | +| **Human / PM** | Defines clear task + acceptance criteria, reviews results, enforces cross-model review. | +| **Worker Agent** | Picks up a task, updates status/time, posts results, flags blockers. | +| **Reviewer Agent** | Opposite-model reviewer for code or high-risk work (see Cross-Model SOP). | + +--- + +## Lifecycle Overview + +| Stage | Action | Required? | +| ----------- | ------------------------------------------------------------------------------------------------- | ----------- | +| 0. Intake | Task created with clear title, description, acceptance criteria, type, project, sprint. | ✅ | +| 1. Claim | Agent sets status `in-progress`, starts timer, sets Agent Status → working. | ✅ | +| 2. Work | Agent executes subtasks; marks subtasks complete as it goes. | ✅ | +| 3. Update | Post intermediate comment(s) or blockers; set status `blocked` if waiting on human. | As needed | +| 4. Complete | Stop timer, set status `done`, provide completion summary + attachments, capture lessons learned. | ✅ | +| 5. Review | Trigger cross-model review if code touched or risk level ≥ medium. | ✅ for code | + +--- + +## API Flow + +```bash +# Claim +curl -X PATCH http://localhost:3001/api/tasks/ \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -d '{"status":"in-progress"}' + +curl -X POST http://localhost:3001/api/tasks//time/start \ + -H "Authorization: Bearer " + +curl -X POST http://localhost:3001/api/agent/status \ + -H "Authorization: Bearer " \ + -d '{"status":"working","taskId":"","taskTitle":"Fix CLI"}' + +# Update (optional comment) +curl -X POST http://localhost:3001/api/tasks//comments \ + -H "Authorization: Bearer " \ + -d '{"text":"Blocked on dependency"}' + +# Complete +curl -X POST http://localhost:3001/api/tasks//time/stop \ + -H "Authorization: Bearer " + +curl -X PATCH http://localhost:3001/api/tasks/ \ + -H "Authorization: Bearer " \ + -d '{ + "status":"done", + "completionSummary":"Added OAuth + tests", + "lessonsLearned":"Always stub the provider" + }' +``` + +--- + +## CLI Flow (fast path) + +```bash +vk begin # sets in-progress, starts timer, agent status → working +# ...do the work... +vk done "Added OAuth + regression test" +``` + +Optional helpers: + +```bash +vk block "Waiting on design" # sets blocked + comment +vk unblock # returns to in-progress, restarts timer +vk time show # verify time entries before completing +``` + +--- + +## Prompt Template (Worker Agent) + +``` +Task: — +URL: http://localhost:3000/task/<ID> + +1. Set status to in-progress and start the timer (vk begin <id>). +2. Work each subtask; add notes/comments as you go. +3. If blocked, set status blocked + explain why. +4. When finished: + - Stop timer + set status done (vk done <id> "summary"). + - Attach deliverables / link to repo. + - Fill the lessons learned field if anything should go into AGENTS/CLAUDE. +5. If you touched code, queue cross-model review task before marking done. +``` + +Store this under `shared/prompt-registry/agent-task-workflow.md` so every agent run is consistent. + +--- + +## Lessons Learned & Notifications + +- Always populate the **Completion Summary**. This becomes the notification that humans skim. +- If the task produced a reusable insight, add it to the **Lessons Learned** field so it surfaces in the global lessons feed (future docs). +- Notify humans via CLI: `vk comment <id> "@channel shipped" --author Veritas` + +--- + +## Escalation + +| Situation | Action | +| ----------------------- | ------------------------------------------------------------------------------- | +| Blocked > 15 minutes | Set status `blocked`, leave blocker comment, ping PM. | +| Time tracking forgotten | Start timer immediately, add manual entry for elapsed time with reason. | +| Reviewer disagrees | Re-open task, create subtasks for fixes, keep cross-model reviewer in the loop. | + +Follow this SOP and every task stays audit-friendly, searchable, and trustworthy. diff --git a/docs/SOP-cross-model-code-review.md b/docs/SOP-cross-model-code-review.md new file mode 100644 index 00000000..690b7760 --- /dev/null +++ b/docs/SOP-cross-model-code-review.md @@ -0,0 +1,96 @@ +# SOP: Cross-Model Code Review (Claude ↔ GPT) + +**Rule (non-negotiable):** If Claude wrote it, GPT reviews it. If GPT wrote it, Claude reviews it. The author may self-check during development, but the final gate must be a different model. + +--- + +## When to Trigger + +| Work Type | Review Required? | +| -------------------------------- | ----------------------------------- | +| Application code, infra, scripts | ✅ Always | +| Docs/content | ⚠️ Only if accuracy/safety critical | +| Research summaries | Optional (human discretion) | + +If in doubt, review. + +--- + +## Workflow + +1. **Authoring task completes** (status remains `in-progress`). +2. **Create review task** referencing the original: + - Title: `Review: <orig task title>` + - Type: `code` + - Sprint/project identical + - Description includes acceptance criteria + diff link(s) +3. **Assign to opposite model** (via OpenClaw or other orchestrator): + ``` + Hey Codex, review PR for task_1234. Checklist below. + ``` +4. **Reviewer steps**: + - Pull branch / run tests (if applicable) + - Use `docs/SOP-agent-task-workflow.md` for lifecycle + - Log findings as subtasks or checklist entries + - Severity tagging: High / Medium / Low / Nit +5. **Outcomes**: + - ✅ No issues → comment summary + mark review task done → original task can go to `done` + - ❌ Issues → create fix subtasks on original task, set status `blocked` until resolved +6. **Comms**: Reviewer leaves structured comment: + ``` + ## Findings + - [High] Path traversal (see notes) + - [Low] Missing aria-label + ## Verdict + Changes required. + ``` +7. **Audit trail**: Update commit message or PR description with `[author: claude-sonnet-4-5][reviewed-by: gpt-5.1-codex]`. + +--- + +## Review Checklist + +| Category | Questions | +| ----------------- | ---------------------------------------------------------------- | +| **Security** | Auth enforced? Input validated? Path traversal? Secrets handled? | +| **Reliability** | Error handling? Race conditions? Timeouts? File locking? | +| **Performance** | Avoid O(n²)? Streaming vs buffering? Caching appropriate? | +| **Accessibility** | Keyboard support? aria-labels? Color contrast? | +| **Docs** | README/docs updated? Migration notes? Tests updated? | + +Adapt per task type. + +--- + +## Prompt Template (Reviewer) + +``` +You are the cross-model reviewer. The code was authored by <model>. Apply the checklist: +1. Pull latest branch <branch>. +2. Run tests (if any). +3. For each issue, note severity (High/Medium/Low/Nit) + file/line + fix suggestion. +4. Summarize verdict: Approve or Changes Required. +5. Update task <id> with findings and completion summary. +``` + +Store in `shared/prompt-registry/cross-model-review.md`. + +--- + +## Recording Findings + +- Add subtasks under the original task for each confirmed bug. +- Reference GitHub issues if they existed. +- Use Lessons Learned to capture systemic insights (e.g., “Always use withFileLock() when touching JSON stores”). + +--- + +## Escalation + +| Scenario | Action | +| ----------------------------------------------- | ------------------------------------------------- | +| Reviewer disagrees with author but fix is minor | Leave comment + request change. | +| Reviewer finds high severity bug | Block task, ping human immediately. | +| Author disputes reviewer findings | Create triage meeting or ask human to adjudicate. | + +This SOP preserved a 91% accuracy rate in RF-002. Keep following it. diff --git a/docs/SOP-multi-agent-orchestration.md b/docs/SOP-multi-agent-orchestration.md new file mode 100644 index 00000000..52a9b905 --- /dev/null +++ b/docs/SOP-multi-agent-orchestration.md @@ -0,0 +1,89 @@ +# SOP: Multi-Agent Orchestration (PM + Workers) + +When you ask “Hey Veritas, can you be the PM for this sprint and assign sub-agents?”, this is the playbook. One agent (usually Claude/Opus) acts as the project manager, spawns worker agents (Codex, Gemini, etc.), and reports back. + +--- + +## Roles + +| Role | Description | +| ---------------- | ------------------------------------------------------------------------------------------- | +| **PM Agent** | Owns the sprint, breaks work into tasks/subtasks, assigns/monitors workers, posts progress. | +| **Worker Agent** | Executes a single task end-to-end following the Agent Task SOP. | +| **Human Lead** | Creates the sprint, reviews PM outputs, handles escalations. | + +--- + +## PM Agent Checklist + +1. **Read context**: AGENTS.md, sprint description, active tasks. +2. **Plan**: If tasks missing, create them (see Sprint Planning SOP). +3. **Assign**: For each task, either: + - Self-assign if it’s planning/reporting work. + - Spawn worker agent with clear instructions + acceptance criteria. +4. **Track**: + - Update Agent Status panel using `vk agent sub-agent <count>`. + - Make sure each worker uses `vk begin/done` so timers stay accurate. +5. **Review**: + - Run cross-model review before marking tasks done. + - Request fixes via subtasks or comments. +6. **Report**: + - Post updates in task comments and daily standups (`vk summary standup --text`). + - Ping human lead when blockers persist > 30 minutes. + +--- + +## Worker Handoff Template + +``` +Task: <ID> — <Title> +Context: <link to research/requirements> +Deliverable: <clear definition of done> +Steps: +1. Run vk begin <id>. +2. Complete subtasks in order. Leave notes if deviations occur. +3. If blocked, set status blocked + explain. +4. On completion, vk done <id> "summary". +5. Request cross-model review by creating task <new id> tagged review. +Uploads: <where to store artifacts> +``` + +Store under `shared/prompt-registry/worker-handoff.md`. + +--- + +## Status Reporting Expectations + +| Cadence | Mechanism | Owner | +| --------------------------- | ---------------------------------------------------- | ----------- | +| Start of day | Comment on sprint tracker task summarizing plan. | PM | +| After each worker completes | Worker comment + PM reaction (✅/request changes). | Worker + PM | +| Daily standup | `vk summary standup --text` posted to comms channel. | PM | +| Sprint end | Archive tasks, write lessons learned, close sprint. | PM | + +Use emojis/reactions sparingly; detailed summaries live in comments. + +--- + +## Error Escalation + +| Issue | PM action | +| -------------------------- | ---------------------------------------------------------- | +| Worker exceeds time budget | Stop timer, leave comment, ping human. | +| Tooling failure (API down) | Run `pnpm dev:clean`, file issue, reassign. | +| Reviewer rejects work | Re-open task, create fix subtasks, keep reviewer looped. | +| PM stuck | Escalate immediately — PMs should not be blocked > 15 min. | + +--- + +## Example: Opus PM orchestrating Codex workers + +1. **Human**: `sessions_spawn` Opus with task “Be PM for US-1600”. +2. **Opus (PM)**: Reads sprint tasks, assigns `US-1601` to itself (docs) and `US-1602` to Codex. +3. **Opus**: Runs `vk agent sub-agent 1` to show a worker is active. +4. **Opus**: Spawns Codex worker with handoff template; instructs to run `vk begin task_...` etc. +5. **Codex**: Executes, posts completion summary, requests cross-model review from Claude. +6. **Opus**: Reviews, marks done, updates sprint recap comment. +7. **Opus**: Sets agent status back to idle once all workers complete (`vk agent idle`). + +Following this SOP keeps human oversight minimal while preserving accountability. diff --git a/docs/SOP-sprint-planning.md b/docs/SOP-sprint-planning.md new file mode 100644 index 00000000..b6b7f913 --- /dev/null +++ b/docs/SOP-sprint-planning.md @@ -0,0 +1,134 @@ +# SOP: Sprint Planning with AI Agents + +Turn vague goals into a structured sprint the way we do internally: epics → sprint → tasks → subtasks. Agents can run most of this, but only if we give them a repeatable script. + +--- + +## Hierarchy Refresher + +| Level | Description | Example | +| --------------------- | -------------------------------------------- | ------------------------------ | +| **Epic / Initiative** | Multi-sprint outcome, named scope-of-record. | "MessageMeld Launch" | +| **Sprint** | Time-boxed slice (`US-1600`, `BM-01`). | "US-1600 — SOP Sprint" | +| **Task** | Single deliverable tracked on the board. | "US-1601: 5-Minute Quickstart" | +| **Subtask** | Checklist item inside a task. | "Add screenshots" | + +Use `project` to represent product buckets (veritas-kanban, brainmeld, digital-meld) and `sprint` for the current iteration name. + +--- + +## Prompt Template (Sprint Planner Agent) + +``` +Goal: <describe epic> +Project: <project name> +Sprint name: US-XXXX — <tagline> +Timebox: <dates or length> + +1. Break the goal into 4-8 tasks (type, priority, acceptance criteria). +2. For each task add 3-8 subtasks that can be completed in under a day. +3. Tag each task with the sprint and project. +4. Assign task types (code, feature, research, docs, etc.). +5. Output JSON payload ready for POST /api/tasks (array of tasks). +6. After creation, post a summary comment to the sprint lead. +``` + +Store the final prompt under `shared/prompt-registry/sprint-planning.md`. + +--- + +## API Creation Flow + +Use the bulk endpoint to create the entire sprint quickly: + +```bash +curl -X POST http://localhost:3001/api/tasks/bulk \ + -H "Authorization: Bearer <admin-key>" \ + -H "Content-Type: application/json" \ + -d '{ + "tasks": [ + { + "title": "US-1601: 5-Minute Quickstart", + "description": "Guide that takes users from zero ➝ agent-ready in 5 min", + "project": "veritas-kanban", + "sprint": "US-1600", + "type": "docs", + "priority": "high", + "subtasks": [ + {"title": "Prereqs section"}, + {"title": "Install steps"}, + {"title": "Agent hookup"} + ] + } + ] + }' +``` + +CLI alternative: + +```bash +vk create "US-1601: 5-Minute Quickstart" \ + --project veritas-kanban \ + --sprint US-1600 \ + --type docs \ + --priority high +``` + +Add subtasks via UI or `vk update --subtask "Add screenshots"` (coming soon). + +--- + +## Estimation Pattern + +We track estimates implicitly via subtasks: each subtask ≈ half-day of effort. Keep tasks between **1–3 days** of work. If it needs more, split it before the sprint starts. + +1. Count subtasks (N). +2. Multiply by 0.5 days to get a gut-check estimate. +3. Compare against sprint capacity (agents × days × focus factor). + +Example: 6 tasks × 4 subtasks × 0.5d = 12 agent-days. With 3 agents @ 4 days focus → 12 days capacity → sprint is feasible. + +--- + +## Assignment Workflow + +1. Tag each task with `owner` only if it is truly pre-assigned. Otherwise leave unassigned so agents can pull. +2. Use **Projects** to separate product lines; use board filters when assigning. +3. Start timers at task pickup (`vk begin`). +4. Use the Agent Status sidebar to confirm at most 1 active task per agent. + +--- + +## Example Sprint (excerpt) + +| Task | Type | Priority | Notes | +| ---------------------------------- | ---- | -------- | ------------------------- | +| US-1601: 5-Min Quickstart | docs | high | This guide. | +| US-1602: Task Workflow SOP | docs | high | Defines lifecycle. | +| US-1603: Sprint Planning SOP | docs | medium | This document. | +| US-1604: Multi-Agent Orchestration | docs | medium | PM + workers. | +| US-1605: Cross-Model Review | docs | medium | Opposite model gate. | +| US-1606: Best Practices | docs | medium | Patterns + anti-patterns. | + +Clone this pattern for your own projects; rename sprint `US-YYYY` and fill tasks accordingly. + +### Example: Bug Fix Sprint (RF-002 cleanup) + +| Task | Type | Priority | Notes | +| ---------------------------------- | ------ | -------- | ----------------------------------------- | +| RF-002-A: Harden archive API | bugfix | high | Add withFileLock + validation. | +| RF-002-B: Fix sidebar counts | bugfix | medium | Sync TaskRepository + StatusHistory. | +| RF-002-C: Add regression tests | qa | medium | Playwright coverage for archive + counts. | +| RF-002-D: Update docs + postmortem | docs | medium | Summarize lessons in AGENTS.md + README. | + +This mirrors how we handled the RF-002 audit sprint: tight scope, cross-functional subtasks, and clear notes for each fix. + +--- + +## After Planning + +- Drop sprint recap in `docs/` or `memory/` so the team has context. +- Create GitHub Milestone matching the sprint name (keeps issues + tasks aligned). +- Schedule daily standup summary: `vk summary standup --date today`. + +Planning done right means agents always know what to pick up next. diff --git a/docs/TIPS-AND-TRICKS.md b/docs/TIPS-AND-TRICKS.md new file mode 100644 index 00000000..6c6995a1 --- /dev/null +++ b/docs/TIPS-AND-TRICKS.md @@ -0,0 +1,94 @@ +# Tips & Tricks — Power User Features + +Little things that keep Veritas Kanban fast when you live in it all day. + +--- + +## CLI Shortcuts + +| Command | What it does | +| --------------------------- | ---------------------------------------------------------------- | +| `vk begin <id>` | Sets status → in-progress, starts timer, agent status → working. | +| `vk done <id> "summary"` | Stops timer, sets done, posts summary, agent status → idle. | +| `vk block <id> "reason"` | Blocks task + leaves blocker comment. | +| `vk unblock <id>` | Restarts timer and sets in-progress. | +| `vk time` | Shows today’s breakdown (per task + total). | +| `vk summary standup --text` | Generates markdown standup summary. | + +Pipe outputs to `jq` or `fzf` for custom dashboards. + +--- + +## Keyboard Shortcuts (Web) + +| Shortcut | Action | +| ------------------ | ----------------------------------------------- | +| `Cmd/Ctrl + K` | Command palette (jump to projects/tasks/views). | +| Arrow keys + Enter | Navigate board cards → open detail panel. | +| `Esc` | Close modals/panels quickly. | +| `/` | Focus global search (from palette). | + +> Command palette replaces the old shortcuts dialog — type to filter actions, tasks, or navigation targets. + +--- + +## Command Palette Power Moves + +- Type `create` to spawn new tasks anywhere. +- Type `filter` to jump between saved filters (Today, Blocked, etc.). +- Use `>` to execute actions (“>start timer task_123”). + +--- + +## WebSocket Awareness + +- Connection status indicator (header) shows live state. +- When offline, the app increases polling frequency; you can throttle it in Settings → Data. +- Use `/api/health` + WebSocket inspector to debug proxies. + +--- + +## MCP Server & Claude Desktop + +1. Build once: `cd mcp && pnpm build` +2. Configure Claude Desktop `settings.json`: + ```json + { + "command": "node", + "args": ["/path/to/veritas-kanban/mcp/dist/index.js"], + "env": { + "VK_API_URL": "http://localhost:3001", + "VK_API_KEY": "<admin-key>" + } + } + ``` +3. Claude can now list tasks, create tasks, and update statuses via MCP. + +Combine MCP + prompt registry to let Claude act as your PM. + +--- + +## Git Worktree Integration + +- Start a worktree from any task via the UI (“Create worktree”). +- Branch naming follows `tasks/task_<id>` pattern — align commit messages with `[author: model]` tags. +- Use `scripts/git-sync.sh` (if configured) to push to multiple remotes. + +--- + +## Obsidian / Knowledge Vault Integration + +- Store deliverables under `Brain/dm-bg/...` (or your equivalent) using `scripts/brain-write.sh` to mirror workspace ↔ Brain. +- Link from tasks: `See Brain/dm-bg/projects/...` for quick retrieval. +- For bidirectional linking, mirror CLAUDE/AGENTS updates back into the vault after each sprint. + +--- + +## Miscellaneous Quality-of-Life + +- **Dev cleanup:** `pnpm dev:clean` frees hung ports/watchers. +- **Watchdog:** `pnpm dev:watchdog` auto-restarts when `/api/health` fails. +- **Archive page:** Use the full-page Archive (accessible from board navigation) instead of the sidebar for faster search and filtering. +- **Notifications:** Configure Teams/Slack/webhooks once; agents can trigger them via the API. + +Know a trick that belongs here? Add it and mirror to the knowledge base so agents learn it too. diff --git a/scripts/dev-clean.sh b/scripts/dev-clean.sh index c3c6570e..d547d016 100755 --- a/scripts/dev-clean.sh +++ b/scripts/dev-clean.sh @@ -10,6 +10,16 @@ set -euo pipefail REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" +# launchd sessions often have a minimal PATH; resolve pnpm explicitly. +PNPM_BIN="$(command -v pnpm || true)" +if [[ -z "${PNPM_BIN}" && -x "/opt/homebrew/bin/pnpm" ]]; then + PNPM_BIN="/opt/homebrew/bin/pnpm" +fi +if [[ -z "${PNPM_BIN}" ]]; then + echo "[dev-clean] ERROR: pnpm not found in PATH and /opt/homebrew/bin/pnpm missing" >&2 + exit 1 +fi + SERVER_PORT="${PORT:-3001}" WEB_PORT="${WEB_PORT:-3000}" @@ -73,4 +83,4 @@ sleep 0.5 echo "[dev-clean] starting pnpm dev" cd "${REPO_ROOT}" -exec pnpm dev +exec "${PNPM_BIN}" dev diff --git a/scripts/dev-watchdog.sh b/scripts/dev-watchdog.sh index 7b6970fb..1a859061 100755 --- a/scripts/dev-watchdog.sh +++ b/scripts/dev-watchdog.sh @@ -12,9 +12,20 @@ PORT="${PORT:-3001}" INTERVAL_SECONDS="${WATCHDOG_INTERVAL_SECONDS:-30}" FAIL_THRESHOLD="${WATCHDOG_FAIL_THRESHOLD:-3}" +# launchd sessions often have a minimal PATH; resolve pnpm explicitly. +PNPM_BIN="$(command -v pnpm || true)" +if [[ -z "${PNPM_BIN}" && -x "/opt/homebrew/bin/pnpm" ]]; then + PNPM_BIN="/opt/homebrew/bin/pnpm" +fi +if [[ -z "${PNPM_BIN}" ]]; then + echo "[dev-watchdog] ERROR: pnpm not found in PATH and /opt/homebrew/bin/pnpm missing" >&2 + exit 1 +fi + URL="http://localhost:${PORT}/api/health" fails=0 +LOCK_FILE="${WATCHDOG_LOCK_FILE:-/tmp/veritas-kanban-dev-clean.lock}" echo "[dev-watchdog] repo=${REPO_ROOT}" echo "[dev-watchdog] url=${URL} interval=${INTERVAL_SECONDS}s threshold=${FAIL_THRESHOLD}" @@ -30,9 +41,23 @@ while true; do fi if [[ "${fails}" -ge "${FAIL_THRESHOLD}" ]]; then - echo "[dev-watchdog] unhealthy threshold reached -> restarting via pnpm dev:clean" + echo "[dev-watchdog] unhealthy threshold reached -> restarting via scripts/dev-clean.sh" + # Prevent restart storms (e.g., if health endpoint is down for an extended period) + if [[ -f "${LOCK_FILE}" ]]; then + lock_pid="$(cat "${LOCK_FILE}" 2>/dev/null || true)" + if [[ -n "${lock_pid}" ]] && kill -0 "${lock_pid}" 2>/dev/null; then + echo "[dev-watchdog] restart already in progress (pid=${lock_pid}); waiting" + fails=0 + sleep "${INTERVAL_SECONDS}" + continue + fi + fi + cd "${REPO_ROOT}" - exec pnpm dev:clean + # Run dev-clean in background so the watchdog can keep monitoring. + (bash "${REPO_ROOT}/scripts/dev-clean.sh") & + echo $! > "${LOCK_FILE}" + fails=0 fi sleep "${INTERVAL_SECONDS}" diff --git a/web/src/components/board/BulkActionsBar.tsx b/web/src/components/board/BulkActionsBar.tsx index 7dc8ba10..7eb2c8a4 100644 --- a/web/src/components/board/BulkActionsBar.tsx +++ b/web/src/components/board/BulkActionsBar.tsx @@ -2,6 +2,7 @@ import { useState, useMemo } from 'react'; import { X, Trash2, Archive, ArrowRight, Inbox } from 'lucide-react'; import { Button } from '@/components/ui/button'; import { Select, SelectContent, SelectItem, SelectTrigger } from '@/components/ui/select'; +import { useToast } from '@/hooks/useToast'; import { AlertDialog, AlertDialogAction, @@ -52,6 +53,7 @@ interface BulkActionsBarProps { export function BulkActionsBar({ tasks }: BulkActionsBarProps) { const { selectedIds, isSelecting, toggleSelecting, selectAll, toggleGroup, clearSelection } = useBulkActions(); + const { toast } = useToast(); const updateTask = useUpdateTask(); const deleteTask = useDeleteTask(); @@ -123,8 +125,43 @@ export function BulkActionsBar({ tasks }: BulkActionsBarProps) { const handleArchiveSelected = async () => { setIsProcessing(true); + const taskIds = Array.from(selectedIds); + let successful = 0; + let failed = 0; + try { - await Promise.all(Array.from(selectedIds).map((id) => archiveTask.mutateAsync(id))); + // Archive each task individually to track success/failure + for (const id of taskIds) { + try { + await archiveTask.mutateAsync(id); + successful++; + } catch (error) { + failed++; + console.error(`Failed to archive task ${id}:`, error); + } + } + + // Show appropriate feedback + if (failed > 0 && successful > 0) { + toast({ + variant: 'default', + title: 'Partial Archive', + description: `Archived ${successful} of ${taskIds.length} tasks. ${failed} failed.`, + }); + } else if (failed > 0) { + toast({ + variant: 'destructive', + title: 'Archive Failed', + description: `Failed to archive all ${taskIds.length} selected tasks.`, + }); + } else if (successful > 0) { + toast({ + variant: 'default', + title: 'Success', + description: `Archived ${successful} task${successful !== 1 ? 's' : ''}.`, + }); + } + clearSelection(); } finally { setIsProcessing(false); diff --git a/web/src/hooks/useTasks.ts b/web/src/hooks/useTasks.ts index 1aa3fc74..ec81e7cd 100644 --- a/web/src/hooks/useTasks.ts +++ b/web/src/hooks/useTasks.ts @@ -114,13 +114,21 @@ export function useUpdateTask() { const cachedTask = queryClient.getQueryData<Task>(['tasks', serverTask.id]); queryClient.setQueryData(['tasks', serverTask.id], mergeWithCachedTimeTracking(cachedTask)); + + // GH-87: Invalidate metrics cache if status changed to keep sidebar in sync. + // The sidebar relies on useMetrics() which has a 30s refetch interval + 10s staleTime. + // Without this, sidebar counts can lag behind the actual board state. + if (input.status) { + queryClient.invalidateQueries({ queryKey: ['metrics'] }); + } }, - // NOTE: No onSettled invalidation here. The onSuccess handler already + // NOTE: No general onSettled invalidation here. The onSuccess handler already // patches the cache with the server response (preserving timer state). // An aggressive invalidateQueries would trigger a background refetch // whose response could overwrite timer state that was patched between // the mutation start and the refetch completing. The WebSocket // task:changed events and polling handle eventual consistency. + // Status-specific metrics invalidation is handled above (GH-87). }); }