claude-archeflow-plugin/skills/presence/SKILL.md

name, description

name	description
presence	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.5.0 · 24 skills · writing domain detected

Or for code projects:

archeflow v0.5.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 ──