docs: add runnable quickstart example
This commit is contained in:
109
examples/runnable-quickstart.md
Normal file
109
examples/runnable-quickstart.md
Normal file
@@ -0,0 +1,109 @@
|
|||||||
|
# Runnable Quickstart
|
||||||
|
|
||||||
|
A step-by-step walkthrough of an ArcheFlow run from scratch.
|
||||||
|
|
||||||
|
## 1. Create a temp project
|
||||||
|
|
||||||
|
```bash
|
||||||
|
mkdir /tmp/af-demo && cd /tmp/af-demo
|
||||||
|
git init && echo "# Demo" > README.md && git add . && git commit -m "init"
|
||||||
|
```
|
||||||
|
|
||||||
|
## 2. Initialize ArcheFlow
|
||||||
|
|
||||||
|
```
|
||||||
|
/af-init quick-fix
|
||||||
|
```
|
||||||
|
|
||||||
|
This creates `.archeflow/config.yaml` with sensible defaults (fast workflow, budget $5).
|
||||||
|
|
||||||
|
Expected output:
|
||||||
|
```
|
||||||
|
archeflow v0.6.0 initialized (quick-fix bundle)
|
||||||
|
config: .archeflow/config.yaml
|
||||||
|
workflow: fast (Creator -> Maker -> Guardian)
|
||||||
|
```
|
||||||
|
|
||||||
|
## 3. Run a task
|
||||||
|
|
||||||
|
```
|
||||||
|
/af-run "Create a fibonacci function with edge case tests" --workflow fast
|
||||||
|
```
|
||||||
|
|
||||||
|
## 4. Expected output at each phase
|
||||||
|
|
||||||
|
### Plan phase (Creator only -- Explorer skipped)
|
||||||
|
|
||||||
|
The fast workflow skips Explorer because the task is small and specific.
|
||||||
|
Creator produces a proposal:
|
||||||
|
|
||||||
|
```
|
||||||
|
-- archeflow -- Create fibonacci function -- fast --
|
||||||
|
Creator: fibonacci(n) with memoization, handles n<0 and n>46 overflow
|
||||||
|
```
|
||||||
|
|
||||||
|
Behind the scenes, Creator wrote a proposal with:
|
||||||
|
- Architecture decision: iterative approach with memoization
|
||||||
|
- File list: `fibonacci.py`, `test_fibonacci.py`
|
||||||
|
- Confidence: task understanding 0.9, solution completeness 0.9, risk coverage 0.8
|
||||||
|
|
||||||
|
### Do phase (Maker)
|
||||||
|
|
||||||
|
Maker implements in an isolated worktree:
|
||||||
|
|
||||||
|
```
|
||||||
|
Maker: 2 files, 4 tests, all passing
|
||||||
|
```
|
||||||
|
|
||||||
|
Maker followed the proposal: wrote tests first (negative input, zero, small values, large values), then implemented.
|
||||||
|
|
||||||
|
### Check phase (Guardian)
|
||||||
|
|
||||||
|
Guardian reviews the diff:
|
||||||
|
|
||||||
|
```
|
||||||
|
Guardian: APPROVED (1 INFO -- consider adding type hints)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Act phase
|
||||||
|
|
||||||
|
All reviewers approved. Merge to main:
|
||||||
|
|
||||||
|
```
|
||||||
|
-- done -- 1 cycle . 3 agents . ~4 min --
|
||||||
|
fibonacci.py + test_fibonacci.py merged
|
||||||
|
```
|
||||||
|
|
||||||
|
## 5. Expected file tree
|
||||||
|
|
||||||
|
```
|
||||||
|
/tmp/af-demo/
|
||||||
|
README.md
|
||||||
|
fibonacci.py # iterative fibonacci with memoization
|
||||||
|
test_fibonacci.py # 4 test cases (negative, zero, small, overflow)
|
||||||
|
.archeflow/
|
||||||
|
config.yaml # ArcheFlow configuration
|
||||||
|
runs/
|
||||||
|
run-001.jsonl # event log for this run
|
||||||
|
progress.md # final progress snapshot
|
||||||
|
```
|
||||||
|
|
||||||
|
## 6. What just happened
|
||||||
|
|
||||||
|
Each phase maps to an archetype with a specific role:
|
||||||
|
|
||||||
|
| Phase | Archetype | What it did |
|
||||||
|
|-------|-----------|-------------|
|
||||||
|
| Plan | Creator | Designed the solution: iterative fibonacci, memoization, test cases. Skipped Explorer (task is specific, files are known). |
|
||||||
|
| Do | Maker | Implemented in isolated worktree. Tests first, then code. Committed after each step. |
|
||||||
|
| Check | Guardian | Reviewed the diff for security, correctness, and quality. Found no blockers. |
|
||||||
|
| Act | Orchestrator | All approved -- merged Maker's worktree branch into main. |
|
||||||
|
|
||||||
|
The fast workflow used 3 agents in 1 cycle. A `standard` workflow would add Explorer (research) + Skeptic (assumptions) + Sage (quality). A `thorough` workflow adds Trickster (adversarial testing) on top.
|
||||||
|
|
||||||
|
## Next steps
|
||||||
|
|
||||||
|
- Try `--workflow standard` for a more thorough run
|
||||||
|
- Try `/af-status` to see run details after completion
|
||||||
|
- Try `/af-dag` to see the process DAG
|
||||||
|
- Try `/af-report` for a full markdown report
|
||||||
Reference in New Issue
Block a user