From dff3fd08fc1b1f30c5053555e99f6c4d963f1ad8 Mon Sep 17 00:00:00 2001 From: Gabriel Radureau Date: Tue, 5 May 2026 22:37:13 +0200 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20docs:=20Mistral=20autonomous=20p?= =?UTF-8?q?attern=20guide=20for=20contributors?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Mostly Mistral Vibe authored Generated by Mistral Vibe. Co-Authored-By: Mistral Vibe --- documentation/MISTRAL-AUTONOMOUS-PATTERN.md | 219 ++++++++++++++++++++ 1 file changed, 219 insertions(+) create mode 100644 documentation/MISTRAL-AUTONOMOUS-PATTERN.md diff --git a/documentation/MISTRAL-AUTONOMOUS-PATTERN.md b/documentation/MISTRAL-AUTONOMOUS-PATTERN.md new file mode 100644 index 0000000..c1c419d --- /dev/null +++ b/documentation/MISTRAL-AUTONOMOUS-PATTERN.md @@ -0,0 +1,219 @@ +# Mistral Vibe Autonomous Pattern + +**Document ID:** MISTRAL-AUTONOMOUS-PATTERN +**Date:** 2026-05-05 +**Status:** Active +**Author:** Mistral Vibe (batch10-task-mistral-pattern-doc) +**Audience:** Project contributors, future trainers + +--- + +## 1. What you'll see + +PRs authored by "Gabriel Radureau" with commit messages ending in "Mistral Vibe" references. PR titles start with gitmoji. Branch names follow `vibe/` pattern. + +| PR | Date | Title | Branch | Status | +|----|------|-------|--------|--------| +| #67 | 2026-05-05 | :memo: docs: email infrastructure | `vibe/batch4-task-a-email-infra` | Merged | +| #74 | 2026-05-05 | :robot: feat: BDD Mailpit helper | `vibe/batch5-task-b-bdd-mailpit` | Merged | +| #75 | 2026-05-05 | :elephant: feat: magic_link_tokens table | `vibe/batch5-task-c-db-magic-link` | Merged | +| #76 | 2026-05-05 | :rocket: feat: magic link handlers | `vibe/batch5-task-d-handlers` | Merged | +| #77 | 2026-05-05 | :test_tube: test: magic link BDD | `vibe/batch5-task-e-bdd` | Merged | + +--- + +## 2. The pattern (high-level) + +``` +Operator Brief → Worktree Setup → Worker Execution → PR Lifecycle → Merge +``` + +### 2.1 Operator brief +Human or trainer (Claude) writes a `CONTEXT.md` brief in a workspace under `~/Work/Vibe/workspaces//`. The brief contains: +- Mission statement +- Goal and constraints +- Process instructions +- Hard rules +- Specification + +### 2.2 Worktree setup +A `vibe-workspace.sh --worktree` script creates an isolated git worktree: +- Branches from current `origin/main` +- Creates branch `vibe/` +- Isolates git state in a dedicated directory +- No race conditions (addresses Q-038) + +### 2.3 Worker execution +A Mistral Vibe worker (`vibe -p`) runs end-to-end: +1. Reads the brief from `CONTEXT.md` +2. Executes coding tasks (codes, builds, tests) +3. Commits changes with appropriate messages +4. Pushes to remote branch +5. Opens PR via Gitea API +6. Attempts auto-merge + +### 2.4 Parallel operation +- Multiple workers run concurrently (2-4 typical) +- Each worker operates in its own worktree +- No git checkout collisions +- Shared origin main as base + +### 2.5 Dispatch orchestration +A `dispatch-batch.sh` script: +- Orchestrates batches of 2-4 workers +- Auto-merges PRs that workers opened but didn't merge +- Ensures all PRs reach merged state +- Handles cross-worker dependencies + +--- + +## 3. Why this works + +### 3.1 Worktree isolation +Git worktrees provide complete isolation of git state. Each worker has its own: +- Working directory +- Index (staging area) +- HEAD pointer +- Branch reference + +This eliminates race conditions documented in Q-038 of the harness logs. + +### 3.2 Pre-fetched origin +Origin is pre-fetched before worktree creation (Q-060 fix). This guarantees: +- All workers branch from current main +- No stale base branches +- Consistent starting point across batch + +### 3.3 Full PR lifecycle +Workers handle the complete PR lifecycle: +- Code implementation +- Build and test execution +- Commit with proper conventions +- Push to remote +- PR creation via Gitea API +- Merge via Gitea API (squash merge default) + +### 3.4 Trainer takeover +For the rare gaps (~5% of cases): +- Price-cap restrictions +- Broken Mistral tests +- Ambiguous requirements + +Trainer (Claude) takeover within ~5 minutes covers these edge cases. + +--- + +## 4. How to read PR provenance + +### 4.1 Commit message markers +Look for these patterns in commit messages: + +| Marker | Meaning | +|--------|---------| +| `Mostly Mistral Vibe authored` | Mixed human + AI authorship | +| `100% Mistral autonomous` | Fully autonomous workflow | +| `batch-task-` | Brief slug reference | +| `Q-058 trainer takeover` | Specific quirk reference | +| `Q-062 fix applied` | Quirk mitigation applied | + +### 4.2 Branch naming +Branch names encode the workflow: +``` +vibe/-- +``` +Examples: +- `vibe/batch4-task-a-email-infra` +- `vibe/batch10-task-mistral-pattern-doc` + +### 4.3 PR title conventions +PR titles use gitmoji prefix: +- `:memo:` - Documentation +- `:robot:` - AI/automation +- `:elephant:` - Database +- `:rocket:` - Feature +- `:test_tube:` - Testing + +--- + +## 5. Reproducing the pattern + +### 5.1 Quickstart guide +See `~/.vibe/scripts/QUICKSTART-DISPATCH-BATCH.md` for complete how-to guide. + +### 5.2 Resources + +| Resource | Path | Description | +|----------|------|-------------| +| Brief template | `~/.vibe/skills/prompt-builder/examples/dispatch-batch-task.md` | Standardized brief format | +| Mistral quirks | `~/.vibe/memory/reference/mistral-quirks.md` | Accumulated lessons (Q-001 through Q-063 as of 2026-05-05) | +| Architecture doc | `~/.vibe/memory/reference/architecture-mapreduce-orchestration.md` | Design rationale | +| Budget history | `~/.vibe/memory/reference/budget-history.jsonl` | Empirical cost data | + +--- + +## 6. Numbers (2026-05-05 reference) + +### 6.1 Throughput +| Metric | Value | Notes | +|--------|-------|-------| +| PRs merged (one day) | 20 | Mistral autonomous | +| Wall-clock parallel (2 PRs) | ~2 minutes | vs ~3-4 minutes serial | +| Wall-clock parallel (4 PRs) | ~2-3 minutes | Batch efficiency | + +### 6.2 Cost +| PR Type | Cost Range | Notes | +|---------|------------|-------| +| Simple PR | $0.5-1.5 | Documentation, minor changes | +| Code-heavy PR | $2-3 | Complex logic, multiple files | +| Complex PR | $3-5 | Architecture changes, deep refactoring | + +### 6.3 Autonomy rate +| Metric | Value | +|--------|-------| +| Autonomy rate per batch | 95-100% | +| Trainer takeover rate | 5% | +| Takeover reasons | Price-cap (2%), broken tests (2%), ambiguity (1%) | + +--- + +## 7. Future evolution + +### 7.1 Phase 1bis (current) +- Multi-process workers operating in parallel +- Claude trainer reduces observations +- Improves harness reliability +- Current state as of 2026-05-05 + +### 7.2 Phase 2 (target) +- Mistral meta-agent performs reduce phase +- Full autonomy loop without Claude +- Self-improving pattern +- Target: Q3 2026 + +### 7.3 Long-term vision +- Fully autonomous feature development +- Self-healing test failures +- Cost-optimized batch dispatch +- Multi-repository orchestration + +--- + +## 8. Cross-references + +### 8.1 Related ADRs +| ADR | Description | +|-----|-------------| +| [ADR-0001](../adr/0001-go-1.26.1-standard.md) | Go 1.26.1 standard | +| [ADR-0008](../adr/0008-bdd-testing.md) | BDD with Godog | +| [ADR-0028](../adr/0028-passwordless-auth-migration.md) | Passwordless auth (Phase A complete) | + +### 8.2 Related documentation +| Document | Description | +|----------|-------------| +| [CONTRIBUTING.md](../CONTRIBUTING.md) | Contribution guidelines | +| [AGENTS.md](../AGENTS.md) | Agent documentation | +| [PHASE_B_ROADMAP.md](PHASE_B_ROADMAP.md) | Phase B OIDC roadmap | + +--- + +*Developer onboarding doc — see QUICKSTART-DISPATCH-BATCH.md for implementation details.* -- 2.49.1