veritas-kanban/docs/BEST-PRACTICES.md

Best Practices & Anti-Patterns

Codify what works (and what burns us) when running Veritas Kanban with humans + AI agents.

---

Do This

1. Track time through the correct lifecycle owner

   • Humans and external agents start timers with vk begin when they pick up a task.
   • Managed harness runs let VK and the adapter own timing automatically.
   • 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 configured review requirements

   • Run independent or cross-model review only when the task, governance policy, issue owner, or release owner requires it.

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

   • Read summaries, inspect diffs, and enforce the review policy selected for the task.

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.

---

Advanced Features — Best Practices

11. Use task dependencies to enforce ordering

    • Set depends_on / blocks relationships so agents don't start work before prerequisites are complete.
    • The API's cycle detection prevents circular chains — trust it and model dependencies accurately.

12. Leverage crash-recovery checkpointing for long tasks

    • Call POST /api/tasks/:id/checkpoint periodically during multi-step agent work.
    • Secrets are auto-sanitized — don't worry about leaking credentials in checkpoint state.
    • Clear checkpoints after task completion to avoid stale data (DELETE /api/tasks/:id/checkpoint).

13. Capture observations for institutional memory

    • Log decisions, blockers, and insights as observations (POST /api/observations).
    • Use importance scoring (1–10) so future agents can filter by significance.
    • Search across all tasks with GET /api/observations/search?query=... to avoid repeating past mistakes.

14. Use the agent filter for workload visibility

    • Query GET /api/tasks?agent=name to see what each agent is working on before assigning new work.

15. Use workflows for repeatable multi-agent pipelines

    • If you're doing the same plan→implement→review cycle repeatedly, encode it as a YAML workflow.
    • Workflows provide retry policies, gate approvals, and real-time observability that ad-hoc scripts don't.

---

v4.0 Governance — Best Practices

16. Define policies before deploying agents

    • Set up tool/action policies (/api/policies) with guard rules before agents start work.
    • Use deny-first precedence for production; allow-first for development.

17. Monitor behavioral drift proactively

    • Configure baselines and alert thresholds via /api/drift for key agent metrics.
    • Review drift status regularly — warning → alert escalation means an agent is deviating.

18. Log decisions with assumptions

    • Every significant agent decision should include supporting evidence and explicit assumptions via /api/decisions.
    • Record outcomes after the fact to build institutional knowledge about what works.

19. Score agent outputs consistently

    • Create scoring profiles with weighted criteria for repeatable evaluation.
    • Use geometricMean composite scoring to penalize low scores in any single dimension.

20. Close the feedback loop

    • Collect user feedback on agent outputs with sentiment and category tags via /api/feedback.
    • Review feedback analytics weekly to catch quality regressions before they compound.

Stick to these rules and the board stays trustworthy even with dozens of agents in parallel.