scriptoriumadmin/veritas-kanban
1
0
Fork 0
mirror of https://github.com/BradGroux/veritas-kanban.git synced 2026-09-11 07:31:02 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 1
veritas-kanban/docs/BEST-PRACTICES.md
Brad Groux eeb11ba219 feat(US-1600): Complete SOP Sprint + fix GH-86 & GH-87 
Documentation (8 new files in docs/):
- GETTING-STARTED.md: 5-min quickstart, BoardKit insights, sanity checks
- SOP-agent-task-workflow.md: Full lifecycle (claim → work → complete)
- SOP-sprint-planning.md: Epic → sprint → task hierarchy + estimation
- SOP-multi-agent-orchestration.md: PM + worker roles, handoff patterns
- SOP-cross-model-code-review.md: Claude ↔ GPT gate, checklist, RF-002 ref
- BEST-PRACTICES.md: 10 DOs + 10 DON'Ts based on real usage
- EXAMPLES-agent-workflows.md: 6 copy/pasteable recipes (feature, bug fix, docs, audit, content, research)
- TIPS-AND-TRICKS.md: CLI shortcuts, keyboard shortcuts, integrations (MCP, git worktrees, Obsidian)
- README.md: Added 'Documentation Map' linking all new docs

Bug Fixes:
- fix(GH-86): BulkActionsBar now handles archive errors gracefully
  * Per-task error tracking (replaces Promise.all)
  * Toast notifications on success/partial/failure
  * Logs individual failures to console

- fix(GH-87): Sidebar metrics now stay in sync with board state
  * Invalidate metrics cache when task status changes
  * Prevents up-to-30s lag in sidebar counts
  * Preserves timer state during mutations

Scripts:
- scripts/dev-clean.sh: Added explicit pnpm path resolution for launchd
- scripts/dev-watchdog.sh: Fixed restart storm prevention + pnpm path

BREAKING: None
TESTING:
- Manual: Bulk archive Done column tasks, verify toasts appear
- Manual: Move tasks between columns, verify sidebar counts update <2s
- Unit: Consider regression tests for metrics invalidation
2026-02-04 08:18:01 -06:00

2.7 KiB
Raw Permalink Blame History

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.