docs: add runnable quickstart example

.archeflow/config.yaml

@@ -1,7 +1,7 @@
 # ArcheFlow Configuration
 # Copy to your project's .archeflow/config.yaml and customize
 
-version: "0.5.0"
+version: "0.6.0"
 
 # Budget
 costs:

.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "archeflow",
   "description": "Multi-agent orchestration with Jungian archetypes. PDCA quality cycles, shadow detection, git worktree isolation. Zero dependencies — works with any Claude Code session.",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "author": {
     "name": "Chris Nennemann"
   },

CHANGELOG.md

@@ -2,6 +2,16 @@
 
 All notable changes to ArcheFlow are documented in this file.
 
+## [0.6.0] -- 2026-04-04
+
+### Added
+- Expanded attention-filters skill with prompt templates, token budgets, cycle-back filtering, and verification checklist
+- Explorer skip heuristic in plan-phase with decision table for when to skip/require research
+- Runnable quickstart example (`examples/runnable-quickstart.md`)
+
+### Fixed
+- Normalized agent persona frontmatter: added examples, moved isolation note to Rules, documented model choices
+
 ## [0.5.0] -- 2026-04-04
 
 ### Added
@@ -12,6 +22,19 @@ All notable changes to ArcheFlow are documented in this file.
 - Cross-run finding regression detection in `archeflow-memory.sh` — compares current findings against previously resolved fixes
 - Check-phase parallel reviewer spawning protocol with Guardian-first sequence, A2 fast-path evaluation, timeout handling, and re-check protocol
 
+## [0.4.0] -- 2026-04-04
+
+### Added
+- Confidence gate parsing with bash snippets for extracting scores from `plan-creator.md`
+- Mini-Explorer spawning when risk coverage < 0.5
+- Worktree merge flow with explicit pre-merge hooks and post-merge test validation
+- `archeflow-rollback.sh` for post-merge test failure auto-revert
+- Test-first validation gate in Do phase
+- Memory injection audit trail with `--audit` flag and `audit-check` command
+
+### Fixed
+- Unified feedback routing tables across orchestration, act-phase, artifact-routing
+
 ## [0.3.0] -- 2026-04-03
 
 ### Added

agents/explorer.md

@@ -4,7 +4,7 @@ description: |
   Spawn as the Explorer archetype for the Plan phase — researches codebase context, maps dependencies, identifies patterns, and synthesizes findings.
   <example>User: "Research the auth module before we redesign it"</example>
   <example>Part of ArcheFlow Plan phase</example>
-model: haiku
+model: haiku  # Cost optimization: research/exploration is analytical, cheaper model suffices
 ---
 
 You are the **Explorer** archetype 🔍. You gather context so the team can make informed decisions.

agents/maker.md

@@ -1,7 +1,7 @@
 ---
 name: maker
 description: |
-  Spawn as the Maker archetype for the Do phase — implements code from the Creator's proposal in an isolated git worktree. Always use with isolation: "worktree".
+  Spawn as the Maker archetype for the Do phase — implements code from the Creator's proposal.
   <example>Part of ArcheFlow Do phase</example>
 model: inherit
 ---
@@ -45,6 +45,7 @@ You turn plans into working, tested, committed code. Small steps, steady progres
 ```
 
 ## Rules
+- **Isolation:** Always spawn with `isolation: "worktree"` to work in a dedicated git worktree.
 - Follow the proposal. Don't redesign.
 - Tests before implementation. Always.
 - Commit after each logical step. Not one big commit at the end.

agents/skeptic.md

@@ -2,6 +2,7 @@
 name: skeptic
 description: |
   Spawn as the Skeptic archetype for the Check phase — challenges assumptions, identifies untested scenarios, and proposes alternatives the team hasn't considered.
+  <example>User: "Challenge the assumptions in this proposal"</example>
   <example>Part of ArcheFlow Check phase</example>
 model: inherit
 ---

agents/trickster.md

@@ -4,7 +4,7 @@ description: |
   Spawn as the Trickster archetype for the Check phase (thorough workflow only) — adversarial testing, boundary attacks, edge case exploitation, and chaos engineering.
   <example>User: "Try to break the new input handler"</example>
   <example>Part of ArcheFlow thorough Check phase</example>
-model: haiku
+model: haiku  # Cost optimization: adversarial testing is pattern-matching, cheaper model suffices
 ---
 
 You are the **Trickster** archetype 🃏. You break things so users don't have to.

docs/roadmap.md

@@ -2,6 +2,28 @@
 
 ## Completed
 
+### v0.6.0 (2026-04-04)
+- [x] Expanded attention-filters skill (prompt templates, token budgets, cycle-back filtering, verification checklist)
+- [x] Explorer skip heuristic in plan-phase skill
+- [x] Agent persona normalization (frontmatter examples, model comments, isolation notes)
+- [x] Runnable quickstart example
+
+### v0.5.0 (2026-04-04)
+- [x] Lib script validation at run initialization
+- [x] Hook points documentation with 6 lifecycle events
+- [x] Phase rollback support via `--to <phase>` flag
+- [x] Per-workflow model assignment with fallback chain
+- [x] Cross-run finding regression detection
+- [x] Check-phase parallel reviewer spawning protocol
+
+### v0.4.0 (2026-04-04)
+- [x] Confidence gate parsing with bash snippets
+- [x] Mini-Explorer spawning when risk coverage < 0.5
+- [x] Worktree merge flow with pre-merge hooks and post-merge test validation
+- [x] `archeflow-rollback.sh` for post-merge test failure auto-revert
+- [x] Test-first validation gate in Do phase
+- [x] Memory injection audit trail
+
 ### v0.3.0 (2026-04-03)
 - [x] Automated PDCA loop (`archeflow:run`) with `--start-from` and `--dry-run`
 - [x] Event-sourced process logging with DAG parent relationships
@@ -52,6 +74,9 @@
 
 | Date | Version | Changes |
 |------|---------|---------|
+| 2026-04-04 | v0.6.0 | Quality/polish: expanded attention filters, Explorer skip heuristic, agent persona normalization, quickstart example |
+| 2026-04-04 | v0.5.0 | Robustness: lib validation, hook points, phase rollback, per-workflow models, regression detection, parallel reviewers |
+| 2026-04-04 | v0.4.0 | Confidence gates, mini-Explorer, worktree merge flow, rollback script, test-first gate, memory audit |
 | 2026-04-03 | v0.3.0 | Process infrastructure: run automation, event sourcing, domain adapters, memory, multi-project, 8 lib scripts |
 | 2026-04-03 | v0.2.0 | Plugin consolidation, workflow intelligence, quality loop, parallel teams, extensibility |
 | 2026-04-02 | v0.1.0 | Initial release: 7 archetypes, 9 core skills, PDCA workflows, shadow detection, autonomous mode |

examples/runnable-quickstart.md

@@ -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

skills/attention-filters/SKILL.md

@@ -37,3 +37,73 @@ Verdict: APPROVED or REJECTED with findings."
 "Here is the full research, the full proposal, the full implementation,
 the full git log, and everything else we have..."
 ```
+
+## Prompt Construction Templates
+
+### Explorer
+- **Receives:** Task description, file tree (max 200 lines), prior-cycle feedback (if cycle 2+)
+- **Excludes:** Creator proposals, Maker diffs, reviewer outputs
+- **Token target:** ~2000 tokens input
+
+### Creator
+- **Receives:** Task description, Explorer research (if available), prior-cycle feedback (if cycle 2+)
+- **Excludes:** Maker diffs, reviewer outputs
+- **Token target:** ~3000 tokens input
+
+### Maker
+- **Receives:** Creator's proposal (full), test strategy section, file list
+- **Excludes:** Explorer research, reviewer outputs, prior-cycle feedback
+- **Token target:** ~2500 tokens input
+
+### Guardian
+- **Receives:** Maker's git diff, proposal risk section, test results
+- **Excludes:** Explorer research, Creator rationale, Skeptic/Sage outputs
+- **Token target:** ~2000 tokens input
+
+### Skeptic
+- **Receives:** Creator's proposal (assumptions + architecture decision), confidence scores
+- **Excludes:** Git diff details, Explorer raw research, other reviewer outputs
+- **Token target:** ~1500 tokens input
+
+### Trickster
+- **Receives:** Maker's git diff only, attack surface summary (file types + entry points)
+- **Excludes:** Proposal, research, other reviewer outputs
+- **Token target:** ~1500 tokens input
+
+### Sage
+- **Receives:** Creator's proposal, Maker's implementation summary + diff, test results
+- **Excludes:** Explorer raw research, other reviewer verdicts
+- **Token target:** ~2500 tokens input
+
+## Token Budget Targets
+
+| Archetype | Fast | Standard | Thorough |
+|-----------|------|----------|----------|
+| Explorer  | skip | 2000     | 3000     |
+| Creator   | 2000 | 3000     | 4000     |
+| Maker     | 2000 | 2500     | 3000     |
+| Guardian  | 1500 | 2000     | 2500     |
+| Skeptic   | skip | 1500     | 2000     |
+| Trickster | skip | skip     | 1500     |
+| Sage      | skip | 2500     | 3000     |
+
+"skip" means the archetype is not spawned in that workflow tier.
+
+## Cycle-Back Filtering
+
+When injecting prior-cycle feedback into cycle 2+:
+
+1. **Summary only** — pass the structured feedback table (issue, source, severity), not full reviewer artifacts
+2. **Strip resolved items** — if a finding was marked Fixed in the Act phase, exclude it
+3. **Compress context** — prior proposal diffs reduce to "What Changed" section only (not full re-proposal)
+4. **Cap at 500 tokens** — if feedback exceeds this, summarize by severity (CRITICAL first, then WARNING, drop INFO)
+
+## Filter Verification Checklist
+
+Before spawning each agent, verify:
+
+- [ ] Prompt contains ONLY the artifacts listed in that archetype's "Receives" above
+- [ ] No cross-contamination from other reviewers' outputs
+- [ ] Token count is within 20% of the target for the current workflow tier
+- [ ] Prior-cycle feedback (if any) is summarized, not raw
+- [ ] Excluded artifacts are genuinely absent (search for keywords like file paths from excluded sources)

skills/plan-phase/SKILL.md

@@ -117,3 +117,19 @@ When the Creator receives structured feedback from a prior cycle, the proposal m
 - **Disputed:** Disagrees with the finding. Must provide evidence or reasoning.
 
 CRITICAL findings cannot be deferred or disputed — they must be fixed or the proposal will be rejected again.
+
+## Explorer Skip Conditions
+
+Not every task needs Explorer research. Use this decision table:
+
+| Condition | Skip Explorer? | Reason |
+|-----------|---------------|--------|
+| Task names specific files (1-2) and change is clear | **Yes** | Context is already known |
+| Bug fix with stack trace or error message | **Yes** | Root cause is locatable without research |
+| High confidence + small scope (single function/class) | **Yes** | Creator can mini-reflect instead |
+| Task contains "investigate", "research", "explore" | **No** | Explicit research request |
+| Task affects >3 files or unknown scope | **No** | Need dependency mapping |
+| Unfamiliar area of codebase (no recent commits by team) | **No** | Need pattern discovery |
+| Security-sensitive change (auth, crypto, input handling) | **No** | Need risk surface mapping |
+
+When Explorer is skipped, Creator MUST include the **Mini-Reflect** section in its proposal to compensate for missing research context.

skills/presence/SKILL.md

@@ -89,12 +89,12 @@ Only show if the user explicitly asks or if `progress.dag_on_complete: true` in
 When ArcheFlow activates at session start (via the `using-archeflow` skill), show ONE line:
 
 ```
-archeflow v0.5.0 · 24 skills · writing domain detected
+archeflow v0.6.0 · 24 skills · writing domain detected
 ```
 
 Or for code projects:
 ```
-archeflow v0.5.0 · 24 skills · code domain
+archeflow v0.6.0 · 24 skills · code domain
 ```
 
 If ArcheFlow decides NOT to activate (simple task, single file):

skills/using-archeflow/SKILL.md

@@ -11,7 +11,7 @@ Multi-agent orchestration using archetypal roles and PDCA quality cycles.
 
 On activation, print ONE line:
 ```
-archeflow v0.5.0 · 25 skills · <domain> domain
+archeflow v0.6.0 · 25 skills · <domain> domain
 ```
 Where `<domain>` 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.