161 lines
5.7 KiB
Markdown
161 lines
5.7 KiB
Markdown
---
|
|
name: presence
|
|
description: |
|
|
Defines how ArcheFlow communicates its activity to the user — visible but not noisy.
|
|
Show value, not process. Auto-loaded by the run skill.
|
|
---
|
|
|
|
# ArcheFlow Presence — Visible Value, Not Noise
|
|
|
|
ArcheFlow should feel like a skilled colleague working alongside you: you know they're there, you see results, but they don't narrate every keystroke.
|
|
|
|
## Principles
|
|
|
|
1. **Show outcomes, not mechanics.** "Guardian caught a timeline bug" — good. "Spawning Guardian agent with attention filters..." — noise.
|
|
2. **One line per phase, not per agent.** The user sees phases complete, not individual agent lifecycle.
|
|
3. **Numbers over words.** "2 fixes applied" beats "We have successfully applied two fixes to the codebase."
|
|
4. **Silence is fine.** If a phase completes cleanly with no findings, don't announce it. Clean passes are the expected case.
|
|
5. **Value at the end.** The completion summary is the most important output — what was built, what was caught, what was fixed.
|
|
|
|
## Status Line Format
|
|
|
|
At key moments during a run, output a compact status line:
|
|
|
|
### Run Start
|
|
```
|
|
── archeflow ── <task> ── <workflow> (<max_cycles> cycles) ──
|
|
```
|
|
Example:
|
|
```
|
|
── archeflow ── Write story "Der Huster" ── kurzgeschichte (2 cycles) ──
|
|
```
|
|
|
|
### Phase Complete (only if something happened worth mentioning)
|
|
```
|
|
✓ plan explorer: 3 directions → chose C (Koffer) | creator: 6 scenes
|
|
✓ do 6004 words drafted
|
|
△ check guardian: 1 fix needed | sage: 5 voice adjustments
|
|
✓ act 6 fixes applied
|
|
```
|
|
|
|
Symbols:
|
|
- `✓` — phase clean, no issues
|
|
- `△` — phase found issues (fixes needed)
|
|
- `✗` — phase failed (blocked, needs user input)
|
|
|
|
### Run Complete
|
|
```
|
|
── done ── 1 cycle · 5 agents · 6 fixes · ~22 min ──
|
|
```
|
|
|
|
If value was delivered, add a one-liner:
|
|
```
|
|
── done ── 1 cycle · 5 agents · 6 fixes · ~22 min ──
|
|
story drafted, reviewed, and polished. see stories/01-der-huster.md
|
|
```
|
|
|
|
### Run Complete (with DAG, if terminal supports it)
|
|
Only show if the user explicitly asks or if `progress.dag_on_complete: true` in config:
|
|
```
|
|
── archeflow ── complete ──────────────────────
|
|
#1 run.start
|
|
├── #2 explorer → #3 decision (C) → #4 creator
|
|
├── #6 maker (6004 words)
|
|
├── #8 guardian △1 · #9 sage △5
|
|
└── #12 complete [6 fixes]
|
|
───────────────────────────────────────────────
|
|
```
|
|
|
|
## When to Be Silent
|
|
|
|
- **Agent spawning/completion** — don't announce
|
|
- **Event emission** — internal bookkeeping, never visible
|
|
- **Artifact routing** — internal
|
|
- **Clean review passes** — if Guardian says APPROVED with 0 findings, skip it
|
|
- **Phase transitions** — only show if the phase produced visible output
|
|
|
|
## When to Speak
|
|
|
|
- **Run start** — always (user should know ArcheFlow activated)
|
|
- **Findings found** — always (this is the value)
|
|
- **Fixes applied** — always (this is the outcome)
|
|
- **Run complete** — always (closure)
|
|
- **Budget warnings** — always (user needs to know)
|
|
- **Shadow detected** — always (something went wrong)
|
|
- **User decision needed** — always (blocking)
|
|
|
|
## Activation Indicator
|
|
|
|
When ArcheFlow activates at session start (via the `using-archeflow` skill), show ONE line:
|
|
|
|
```
|
|
archeflow v0.6.0 · 24 skills · writing domain detected
|
|
```
|
|
|
|
Or for code projects:
|
|
```
|
|
archeflow v0.6.0 · 24 skills · code domain
|
|
```
|
|
|
|
If ArcheFlow decides NOT to activate (simple task, single file):
|
|
```
|
|
(nothing — silence is correct for simple tasks)
|
|
```
|
|
|
|
## Integration with Progress File
|
|
|
|
The `.archeflow/progress.md` file is the detailed view for users who want more. The status lines above are the default — brief, inline, part of the conversation flow.
|
|
|
|
Users who want the full picture: `archeflow-progress.sh <run_id> --watch` in a second terminal.
|
|
|
|
## Anti-Patterns (Don't Do This)
|
|
|
|
```
|
|
❌ "I'm now activating the ArcheFlow orchestration framework..."
|
|
❌ "Spawning Explorer agent with model haiku and attention filter..."
|
|
❌ "The Guardian archetype has completed its security review and found..."
|
|
❌ "Let me run the convergence detection algorithm to check..."
|
|
❌ "According to the ArcheFlow process-log event schema..."
|
|
```
|
|
|
|
These expose internal mechanics. The user doesn't care about archetypes, attention filters, or event schemas. They care about: what was done, what was found, what was fixed.
|
|
|
|
## Examples: Good Presence
|
|
|
|
### Example 1: Feature Implementation
|
|
```
|
|
── archeflow ── Add JWT auth ── standard (2 cycles) ──
|
|
✓ plan 3 files affected, JWT + middleware approach
|
|
✓ do implemented (auth.ts, middleware.ts, tests)
|
|
△ check guardian: missing token expiry check
|
|
✓ act 1 fix applied
|
|
── done ── 1 cycle · 4 agents · 1 fix · ~8 min ──
|
|
```
|
|
|
|
### Example 2: Story Writing
|
|
```
|
|
── archeflow ── Write "Der Huster" ── kurzgeschichte (2 cycles) ──
|
|
✓ plan 3 plot directions → chose C (Mo krank + Koffer)
|
|
✓ do 6004 words, 7 scenes
|
|
△ check 1 timeline bug, 5 voice adjustments
|
|
✓ act 6 fixes applied
|
|
── done ── 1 cycle · 5 agents · 6 fixes · ~22 min ──
|
|
stories/01-der-huster.md ready
|
|
```
|
|
|
|
### Example 3: Quick Fix (minimal output)
|
|
```
|
|
── archeflow ── Fix pagination bug ── fast ──
|
|
✓ fix applied, tests pass
|
|
── done ── 1 cycle · 3 agents · ~4 min ──
|
|
```
|
|
|
|
### Example 4: Multi-Project
|
|
```
|
|
── archeflow ── giesing-story-v2 ── 3 projects ──
|
|
✓ archeflow artifact routing improved
|
|
✓ colette voice validation added
|
|
✓ giesing story #2 drafted (5800 words)
|
|
── done ── 3 projects · 12 agents · ~35 min ──
|
|
```
|