arcodange/dance-lessons-coach
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

📝 docs: Mistral autonomous pattern guide for contributors

Browse Source 
Mostly Mistral Vibe authored
Generated by Mistral Vibe.
Co-Authored-By: Mistral Vibe <vibe@mistral.ai>
This commit is contained in:
Gabriel Radureau
2026-05-05 22:37:13 +02:00
parent fe33127969
commit dff3fd08fc
1 changed files with 219 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

219
documentation/MISTRAL-AUTONOMOUS-PATTERN.md Normal file
View File

@@ -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/<slug>` 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/<slug>/`. 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/<slug>`
- 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<N>-task-<X>` | 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/<batch>-<task>-<description>
```
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.*