diff --git a/skills/presence/SKILL.md b/skills/presence/SKILL.md new file mode 100644 index 0000000..56e355f --- /dev/null +++ b/skills/presence/SKILL.md @@ -0,0 +1,160 @@ +--- +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 ── ── ( 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.3.0 · 24 skills · writing domain detected +``` + +Or for code projects: +``` +archeflow v0.3.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 --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 ── +``` diff --git a/skills/using-archeflow/SKILL.md b/skills/using-archeflow/SKILL.md index 02018a2..f38868d 100644 --- a/skills/using-archeflow/SKILL.md +++ b/skills/using-archeflow/SKILL.md @@ -7,6 +7,16 @@ description: Use at session start when implementing features, reviewing code, de Multi-agent orchestration using archetypal roles and PDCA quality cycles. +## Session Start + +On activation, print ONE line: +``` +archeflow v0.3.0 · 25 skills · domain +``` +Where `` is auto-detected: `writing` if `colette.yaml` exists, `research` if paper/thesis files exist, `code` otherwise. Then proceed silently — no further announcement unless `archeflow:run` is invoked. + +During runs, follow the `archeflow:presence` skill for output format: show outcomes not mechanics, one line per phase, value at the end. + ## IMPORTANT: When to Activate You MUST use ArcheFlow orchestration (load `archeflow:orchestration` skill and follow its steps) for any task that matches: