155 lines
4.3 KiB
Markdown
155 lines
4.3 KiB
Markdown
# Workflow Improvement Backlog — From Hans' Session
|
|
|
|
**Date:** 2026-04-09
|
|
**Source:** First real agent workflow test (Hans on telemetry issues)
|
|
|
|
---
|
|
|
|
## 1. Daily Review Script — Self-Test Mode
|
|
|
|
**Problem:** Script had bugs (line 177 syntax error, false positives). Hans had to "check the checker."
|
|
|
|
**Fix:** Add `--self-test` flag
|
|
```bash
|
|
./scripts/daily-review.sh --self-test # Validates script logic without failing
|
|
./scripts/daily-review.sh --verbose # Shows all grep matches for debugging
|
|
```
|
|
|
|
**Status:** Script fixed in `6d5837c`, but `--self-test` not yet implemented.
|
|
|
|
---
|
|
|
|
## 2. Tea CLI Authentication — Undocumented
|
|
|
|
**Problem:** Remote commands (`issue close`, `assign`) failed. Had to describe commands for user to run.
|
|
|
|
**Solutions (pick one):**
|
|
|
|
| Option | Implementation | Effort |
|
|
|--------|---------------|--------|
|
|
| A | Add to `QUICKSTART.md`: `tea login add --name clavitor --url https://git.clavitor.ai --token $TOKEN` | 5 min |
|
|
| B | Create `skill name=gitea` with auth handling | 1 hour |
|
|
| C | Change workflow to PR-based (no issue state changes needed from agents) | 2 hours |
|
|
|
|
**Recommendation:** Option A immediately, Option B later.
|
|
|
|
---
|
|
|
|
## 3. Go Module Structure — Confusing
|
|
|
|
**Problem:** Telemetry has its own `go.mod`, not referenced by main vault. Hans created temp files to test.
|
|
|
|
**Fix Options:**
|
|
- Add telemetry to root `go.work` (workspace)
|
|
- Document: "cd clavis/clavis-telemetry && use its own go.mod"
|
|
- Add to Makefile: `make test-telemetry`
|
|
|
|
**Status:** Needs decision.
|
|
|
|
---
|
|
|
|
## 4. "Done" Signal — Ambiguous
|
|
|
|
**Problem:** After fixing, Hans asked "Want me to commit?" Should be automatic.
|
|
|
|
**Fix:** Update `QUICKSTART.md` workflow:
|
|
```
|
|
Agent completes work → git add → git commit -m "Fixes #N" → git push → Create PR
|
|
Wait for reviewer. DO NOT ask permission for each step.
|
|
```
|
|
|
|
**Status:** `QUICKSTART.md` updated, but could be clearer.
|
|
|
|
---
|
|
|
|
## 5. Build Tags — Not in QUICKSTART
|
|
|
|
**Problem:** Had to discover `-tags commercial` was required.
|
|
|
|
**Fix:** Add to `QUICKSTART.md`:
|
|
```bash
|
|
# Build commercial edition
|
|
go build -tags commercial .
|
|
|
|
# Test telemetry
|
|
go test -tags commercial ./...
|
|
```
|
|
|
|
**Status:** Not done.
|
|
|
|
---
|
|
|
|
## 6. Issue State Machine — Undocumented
|
|
|
|
**Problem:** Issues stay "open" even with "Fixes #N" in commit. Need manual close.
|
|
|
|
**Document Expected Flow:**
|
|
```
|
|
Open → Assigned to agent → Fixed in PR ("Fixes #N") → Reviewer approves
|
|
→ Reviewer closes issue → Done
|
|
```
|
|
|
|
**Not:** Agent closes issue (wrong — reviewer validates fix first)
|
|
|
|
**Status:** Not documented.
|
|
|
|
---
|
|
|
|
## 7. Task Pickup Skill — Missing
|
|
|
|
**Problem:** Had to guess which issues to work on. No clear "this is your task" signal.
|
|
|
|
**Proposed Skill:** `skill name=tasks`
|
|
```bash
|
|
# List my tasks, filtered and prioritized
|
|
skill name=tasks action=my-queue
|
|
|
|
Output:
|
|
=== Tasks for Hans ===
|
|
PRIORITY ISSUE TITLE
|
|
CRITICAL #2 Silent DB errors (Yurii) ← Work on this first
|
|
CRITICAL #3 Kuma silent failure (Yurii)
|
|
MEDIUM #1 Missing error codes (Yurii)
|
|
MEDIUM #4 Tarpit flush error (Yurii)
|
|
```
|
|
|
|
**Status:** Proposed, not implemented.
|
|
|
|
---
|
|
|
|
## Biggest Issue: Workflow Gap
|
|
|
|
**The Problem:** Handbook says "Pick up issue from git.clavitor.ai" but agents can't actually:
|
|
- Query issues assigned to them programmatically
|
|
- Change issue state (close, reassign)
|
|
- Link issues to PRs via CLI
|
|
|
|
**Creates friction:** Every agent session requires manual user intervention.
|
|
|
|
---
|
|
|
|
## Immediate Actions (This Week)
|
|
|
|
| Priority | Task | Owner |
|
|
|----------|------|-------|
|
|
| P1 | Fix QUICKSTART.md with tea login, build tags, clear "done" workflow | Johan |
|
|
| P2 | Document issue state machine in handbook | Johan |
|
|
| P3 | Add telemetry to Makefile or document standalone | Johan |
|
|
| P4 | Test daily-review.sh with `--self-test` | Charles/Sarah |
|
|
| P5 | Implement `skill name=tasks` for Gitea | Future |
|
|
|
|
---
|
|
|
|
## Foundation Question
|
|
|
|
Do we want:
|
|
- **A)** Agents fully autonomous (can query tasks, create PRs, full workflow) — requires skill development
|
|
- **B)** Agents assisted (describe what to do, user runs commands) — current state, more friction
|
|
- **C)** Hybrid (agents create local files, user imports to Gitea) — backup plan
|
|
|
|
**Current:** Between B and C. Needs decision to reach A.
|
|
|
|
---
|
|
|
|
*Captured from Hans' first workflow test. Real friction, real fixes needed.*
|