refactor: trim 11 secondary ArcheFlow skills from 3340 to 952 lines
Remove verbose YAML examples, bash pseudo-code, tutorial prose, and motivational content from configuration/integration skills while preserving all operational protocols, reference tables, and rules. Skills trimmed: domains, colette-bridge, multi-project, cost-tracking, git-integration, custom-archetypes, workflow-design, templates, autonomous-mode, progress, presence.
This commit is contained in:
@@ -1,221 +1,70 @@
|
||||
---
|
||||
name: autonomous-mode
|
||||
description: Use when the user wants to run ArcheFlow orchestrations unattended — overnight sessions, batch processing multiple tasks, or fully autonomous coding. Handles self-organization, progress logging, and safe stopping.
|
||||
description: Use when the user wants to run ArcheFlow orchestrations unattended -- overnight sessions, batch processing multiple tasks, or fully autonomous coding. Handles self-organization, progress logging, and safe stopping.
|
||||
---
|
||||
|
||||
# Autonomous Mode
|
||||
|
||||
ArcheFlow orchestrations can run fully autonomously because the archetypes self-organize through the PDCA cycle. The user sets the task queue, walks away, and reviews results later.
|
||||
|
||||
## How Autonomous Mode Works
|
||||
|
||||
The PDCA cycle provides natural quality gates at every turn of the spiral:
|
||||
- **Plan** phase produces a proposal — reviewable artifact
|
||||
- **Do** phase produces committed code in a worktree — isolated, reversible
|
||||
- **Check** phase produces approval/rejection — automatic quality control
|
||||
- **Act** phase either merges (safe) or cycles back (self-correcting)
|
||||
|
||||
No unreviewed code reaches the main branch. Ever. That's what makes overnight runs safe.
|
||||
|
||||
## Starting an Autonomous Session
|
||||
|
||||
```
|
||||
You are entering AUTONOMOUS MODE.
|
||||
|
||||
Task queue:
|
||||
1. "Add input validation to all API endpoints" (thorough)
|
||||
2. "Refactor auth middleware to use JWT" (standard)
|
||||
3. "Fix pagination bug in search results" (fast)
|
||||
4. "Add rate limiting to public endpoints" (standard)
|
||||
|
||||
Rules:
|
||||
- Process tasks sequentially (one orchestration at a time)
|
||||
- Log progress to .archeflow/session-log.md after each task
|
||||
- If a task fails after max cycles: log findings, skip to next task
|
||||
- If 3 consecutive tasks fail: STOP and wait for user
|
||||
- Commit and push after each successful merge
|
||||
- Never force-push. Never modify main history.
|
||||
```
|
||||
|
||||
## Session Log — Full Visibility
|
||||
|
||||
Every autonomous session writes to `.archeflow/session-log.md`:
|
||||
|
||||
```markdown
|
||||
# ArcheFlow Autonomous Session
|
||||
**Started:** 2026-04-02 22:00 UTC
|
||||
**Mode:** autonomous
|
||||
**Tasks:** 4 queued
|
||||
|
||||
---
|
||||
|
||||
## Task 1: Add input validation to all API endpoints
|
||||
**Workflow:** thorough | **Status:** COMPLETED
|
||||
**Cycles:** 2 of 3
|
||||
**Cycle 1:** Guardian REJECTED (missing sanitization on 2 endpoints)
|
||||
**Cycle 2:** All APPROVED
|
||||
**Files changed:** 8 | **Tests added:** 24
|
||||
**Branch:** merged to main (commit abc1234)
|
||||
**Duration:** 12 min | **Completed:** 22:12 UTC
|
||||
|
||||
---
|
||||
|
||||
## Task 2: Refactor auth middleware to use JWT
|
||||
**Workflow:** standard | **Status:** COMPLETED
|
||||
**Cycles:** 1 of 2
|
||||
**Cycle 1:** All APPROVED (clean implementation)
|
||||
**Files changed:** 5 | **Tests added:** 15
|
||||
**Branch:** merged to main (commit def5678)
|
||||
**Duration:** 8 min | **Completed:** 22:20 UTC
|
||||
|
||||
---
|
||||
|
||||
## Task 3: Fix pagination bug in search results
|
||||
**Workflow:** fast | **Status:** COMPLETED
|
||||
**Cycles:** 1 of 1
|
||||
**Cycle 1:** Guardian APPROVED
|
||||
**Files changed:** 2 | **Tests added:** 3
|
||||
**Branch:** merged to main (commit ghi9012)
|
||||
**Duration:** 4 min | **Completed:** 22:24 UTC
|
||||
|
||||
---
|
||||
|
||||
## Task 4: Add rate limiting to public endpoints
|
||||
**Workflow:** standard | **Status:** FAILED (max cycles)
|
||||
**Cycles:** 2 of 2
|
||||
**Cycle 1:** Skeptic REJECTED (Redis dependency not in Docker setup)
|
||||
**Cycle 2:** Guardian REJECTED (race condition in token bucket)
|
||||
**Unresolved:** Race condition in concurrent token bucket decrement
|
||||
**Branch:** archeflow/maker-xyz (NOT merged — available for manual review)
|
||||
**Duration:** 15 min | **Completed:** 22:39 UTC
|
||||
|
||||
---
|
||||
|
||||
## Session Summary
|
||||
**Completed:** 3 of 4 tasks
|
||||
**Failed:** 1 (rate limiting — needs human input on concurrency design)
|
||||
**Total duration:** 39 min
|
||||
**Files changed:** 15 | **Tests added:** 42
|
||||
**Ended:** 22:39 UTC
|
||||
```
|
||||
|
||||
## Safety Mechanisms
|
||||
|
||||
### Automatic Stop Conditions
|
||||
The session halts and waits for the user when:
|
||||
- **3 consecutive failures:** Something systemic is wrong
|
||||
- **Destructive action detected:** Force push, branch deletion, schema drop
|
||||
- **Shadow escalation:** Same shadow detected 3+ times across tasks
|
||||
- **Budget exceeded:** If cost tracking is enabled, stop at budget limit
|
||||
- **Test suite broken:** If existing tests fail after merge, halt immediately and revert
|
||||
|
||||
### Everything is Reversible
|
||||
- Code changes live on worktree branches until explicitly merged
|
||||
- Merges use `--no-ff` — every merge commit is individually revertable
|
||||
- The session log captures every decision for post-hoc review
|
||||
- Failed tasks leave their branches intact for manual inspection
|
||||
|
||||
### User Controls
|
||||
The user can at any time:
|
||||
- **Cancel:** Kill the session. All incomplete work stays on branches.
|
||||
- **Pause:** Stop after current task completes. Resume later.
|
||||
- **Skip:** Skip the current task, move to the next one.
|
||||
- **Review:** Read `.archeflow/session-log.md` for real-time progress.
|
||||
- **Intervene:** Jump into a worktree branch and fix something manually.
|
||||
ArcheFlow orchestrations run fully autonomously through the PDCA cycle's natural quality gates. No unreviewed code reaches main.
|
||||
|
||||
## Task Queue Formats
|
||||
|
||||
### Simple (inline)
|
||||
**Inline:**
|
||||
```
|
||||
Tasks:
|
||||
1. "Fix the login bug" (fast)
|
||||
2. "Add user profile page" (standard)
|
||||
```
|
||||
|
||||
### From File
|
||||
Create `.archeflow/queue.md`:
|
||||
**From file (`.archeflow/queue.md`):**
|
||||
```markdown
|
||||
- [ ] Fix the login bug | fast
|
||||
- [ ] Add user profile page | standard
|
||||
- [ ] Security audit of payment flow | thorough
|
||||
- [x] Refactor database queries | standard (completed)
|
||||
- [ ] Add user profile page | standard | depends: fix login
|
||||
- [ ] Security audit | thorough | done: Guardian approves AND load_test.sh passes
|
||||
```
|
||||
|
||||
### With Dependencies
|
||||
```markdown
|
||||
- [ ] Add user model (standard)
|
||||
- [ ] Add user API endpoints (standard) | depends: user model
|
||||
- [ ] Add user UI (standard) | depends: user API endpoints
|
||||
```
|
||||
Dependencies are processed in order: a task with `depends: X` waits until X completes successfully. Tasks without dependencies or with resolved dependencies can run in parallel (see Parallel Team Orchestration in the orchestration skill).
|
||||
Tasks with `depends:` wait for the named task to complete. Tasks with `done:` have completion criteria checked in the Act phase.
|
||||
|
||||
### With Completion Criteria
|
||||
```markdown
|
||||
- [ ] Fix login bug | fast | done: login_test.py passes
|
||||
- [ ] Add rate limiting | standard | done: Guardian approves AND load_test.sh passes
|
||||
```
|
||||
Completion criteria are checked in the Act phase. If the test command fails even when reviewers approve, the task cycles back.
|
||||
## Safety Mechanisms
|
||||
|
||||
### Automatic Stop Conditions
|
||||
|
||||
- **3 consecutive failures:** Something systemic is wrong
|
||||
- **Test suite broken:** Halt immediately, revert last merge
|
||||
- **Budget exceeded:** Stop at limit
|
||||
- **Shadow escalation:** Same shadow detected 3+ times across tasks
|
||||
- **Destructive action detected:** Force push, branch deletion, schema drop
|
||||
|
||||
### Everything is Reversible
|
||||
|
||||
- Code lives on worktree branches until explicitly merged
|
||||
- Merges use `--no-ff` (individually revertable)
|
||||
- Failed tasks leave branches intact for inspection
|
||||
|
||||
### User Controls
|
||||
|
||||
- **Cancel:** Kill session, incomplete work stays on branches
|
||||
- **Pause:** Stop after current task, resume later
|
||||
- **Skip:** Move to next task
|
||||
- **Review:** Read `.archeflow/session-log.md` for progress
|
||||
|
||||
## Session Log
|
||||
|
||||
Every session writes to `.archeflow/session-log.md` with per-task entries:
|
||||
- Workflow, status, cycles, reviewer verdicts
|
||||
- Files changed, tests added
|
||||
- Branch and commit info
|
||||
- Duration and timestamps
|
||||
- Session summary at the end
|
||||
|
||||
## Budget-Aware Scheduling
|
||||
|
||||
Set a token or cost budget for the session. The orchestrator tracks estimated cost per task and adapts:
|
||||
|
||||
```
|
||||
Budget: $5.00 (or ~2M tokens)
|
||||
```
|
||||
|
||||
| Budget Remaining | Action |
|
||||
|-----------------|--------|
|
||||
| > 50% | Run tasks at their selected workflow level |
|
||||
| 25-50% | Downgrade `thorough` → `standard`, `standard` → `fast` |
|
||||
| < 25% | Run remaining tasks as `fast` only |
|
||||
| Exhausted | Stop. Log remaining tasks as "skipped — budget exhausted" |
|
||||
| > 50% | Run at selected workflow level |
|
||||
| 25-50% | Downgrade thorough to standard, standard to fast |
|
||||
| < 25% | All tasks as fast only |
|
||||
| Exhausted | Stop, log remaining as skipped |
|
||||
|
||||
Budget is tracked per-task in the session log. Estimated cost per agent by model tier:
|
||||
## Auto-Resume
|
||||
|
||||
| Tier | Model | Est. Cost/Agent |
|
||||
|------|-------|----------------|
|
||||
| cheap | Haiku | ~$0.01 |
|
||||
| standard | Sonnet | ~$0.05 |
|
||||
| premium | Opus | ~$0.25 |
|
||||
|
||||
A standard workflow (6 agents, mostly Sonnet) costs ~$0.30. A thorough workflow (8 agents) costs ~$0.50. These are rough estimates — actual cost depends on context size and output length.
|
||||
|
||||
## Auto-Resume on Interruption
|
||||
|
||||
If a session is interrupted (crash, timeout, user cancel), save state for resumption:
|
||||
|
||||
### On Interruption
|
||||
Write `.archeflow/state.json`:
|
||||
```json
|
||||
{
|
||||
"session_id": "...",
|
||||
"current_task": 2,
|
||||
"current_phase": "check",
|
||||
"current_cycle": 1,
|
||||
"completed_tasks": [1],
|
||||
"queue": ["task3", "task4"],
|
||||
"worktree_branch": "archeflow/maker-abc",
|
||||
"timestamp": "2026-04-03T22:15:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
### On Next Session Start
|
||||
If `.archeflow/state.json` exists:
|
||||
1. Report: "Found interrupted ArcheFlow session from [timestamp]. Task [N] was in [phase] phase."
|
||||
2. Offer: "Resume from where we left off? Or start fresh?"
|
||||
3. If resume: pick up from the saved phase. The worktree branch is still intact.
|
||||
4. If fresh: clean up state file and worktrees, start over.
|
||||
|
||||
## Overnight Session Checklist
|
||||
|
||||
Before starting an autonomous overnight session:
|
||||
|
||||
1. **Clean working tree:** `git status` — no uncommitted changes
|
||||
2. **Tests passing:** Run the full test suite. Don't start on a broken baseline.
|
||||
3. **Task queue defined:** Either inline or in `.archeflow/queue.md`
|
||||
4. **Workflow selected per task:** Match risk level to workflow type
|
||||
5. **Budget set (optional):** If cost matters, set a token/dollar limit
|
||||
6. **Push access:** Verify git push works (SSH key, auth token)
|
||||
|
||||
Then: set it, forget it, read the session log in the morning.
|
||||
On interruption, save state to `.archeflow/state.json` (current task, phase, cycle, completed tasks, worktree branch). On next session start, offer to resume or start fresh.
|
||||
|
||||
@@ -9,384 +9,91 @@ description: |
|
||||
<example>User: "archeflow:run" in a project with colette.yaml</example>
|
||||
---
|
||||
|
||||
# Colette Bridge — Writing Context Auto-Loader
|
||||
# Colette Bridge -- Writing Context Auto-Loader
|
||||
|
||||
When ArcheFlow detects `colette.yaml` in the project root, this skill automatically loads voice profiles, personas, character sheets, and project rules into a context bundle that every agent receives (filtered by archetype role).
|
||||
When `colette.yaml` exists in the project root, this skill loads voice profiles, personas, character sheets, and project rules into a context bundle filtered per archetype.
|
||||
|
||||
## Prerequisites
|
||||
## Activation
|
||||
|
||||
- `archeflow:domains` — Colette Bridge sets domain to `writing` automatically
|
||||
- `archeflow:artifact-routing` — bundle is injected via the artifact routing system
|
||||
- `archeflow:run` — bridge hooks into run initialization
|
||||
|
||||
## Trigger
|
||||
|
||||
At `run.start`, after domain detection but before the Plan phase:
|
||||
|
||||
1. Check if `colette.yaml` exists in the project root
|
||||
2. If found, activate Colette Bridge
|
||||
3. If not found, skip silently (no error, no warning)
|
||||
|
||||
When the bridge activates, it emits a decision event:
|
||||
|
||||
```bash
|
||||
./lib/archeflow-event.sh "$RUN_ID" decision init "" \
|
||||
'{"what":"colette_bridge","chosen":"activated","signal":"colette.yaml found","files_resolved":<count>}'
|
||||
```
|
||||
|
||||
---
|
||||
At `run.start`, after domain detection but before Plan phase:
|
||||
1. Check for `colette.yaml` in project root
|
||||
2. If found: activate bridge, set domain to `writing`
|
||||
3. If not found: skip silently
|
||||
|
||||
## File Resolution
|
||||
|
||||
Colette projects reference files by ID (e.g., `vp-giesing-gschichten-v1`) but the actual YAML files may live in different locations. The bridge resolves files using this search order:
|
||||
Colette projects reference files by ID (e.g., `vp-giesing-gschichten-v1`). The bridge resolves them:
|
||||
|
||||
### Search Priority (highest first)
|
||||
| Priority | Location |
|
||||
|----------|----------|
|
||||
| 1 | Explicit path in `colette.yaml` (has `/` or `.yaml`) |
|
||||
| 2 | Project root subdirectories (`./profiles/<id>.yaml`) |
|
||||
| 3 | Parent `writing.colette/` dir (`../writing.colette/profiles/<id>.yaml`) |
|
||||
|
||||
| Priority | Location | Example |
|
||||
|----------|----------|---------|
|
||||
| 1 | Explicit path in `colette.yaml` | `voice.profile: ../writing.colette/profiles/custom.yaml` |
|
||||
| 2 | Project root subdirectories | `./profiles/vp-giesing-gschichten-v1.yaml` |
|
||||
| 3 | Parent directory + `writing.colette/` | `../writing.colette/profiles/vp-giesing-gschichten-v1.yaml` |
|
||||
**What gets resolved:**
|
||||
|
||||
### What Gets Resolved
|
||||
|
||||
| Source | colette.yaml field | Search paths |
|
||||
|--------|-------------------|-------------|
|
||||
| Voice profile | `voice.profile` | `profiles/<id>.yaml`, `../writing.colette/profiles/<id>.yaml` |
|
||||
| Persona | `writing.persona` or inferred from profile | `personas/<id>.yaml`, `../writing.colette/personas/<id>.yaml` |
|
||||
| Source | colette.yaml field | Search subdirs |
|
||||
|--------|-------------------|----------------|
|
||||
| Voice profile | `voice.profile` | `profiles/` |
|
||||
| Persona | `writing.persona` or inferred from profile | `personas/` |
|
||||
| Characters | Auto-discovered | `characters/*.yaml` |
|
||||
| Series config | `series` section (if present) | `colette.yaml` itself, `../writing.colette/series/<name>.yaml` |
|
||||
| Series config | `series` section | `colette.yaml` itself |
|
||||
| Project rules | Always | `CLAUDE.md` in project root |
|
||||
|
||||
### Resolution Procedure
|
||||
|
||||
```
|
||||
for each reference in colette.yaml:
|
||||
1. If the field contains a path (has / or .yaml) → use as-is, verify exists
|
||||
2. If the field contains an ID (e.g., "vp-giesing-gschichten-v1"):
|
||||
a. Check ./profiles/<id>.yaml (or ./personas/<id>.yaml)
|
||||
b. Check ../writing.colette/profiles/<id>.yaml (or ../writing.colette/personas/<id>.yaml)
|
||||
c. If not found → warn in event log, skip this file
|
||||
3. For characters/ → glob characters/*.yaml in project root
|
||||
4. For CLAUDE.md → check project root
|
||||
```
|
||||
|
||||
If a referenced file cannot be found at any location, emit a warning event but do not abort:
|
||||
|
||||
```bash
|
||||
./lib/archeflow-event.sh "$RUN_ID" decision init "" \
|
||||
'{"what":"colette_bridge_warning","chosen":"skip","file":"vp-giesing-gschichten-v1","reason":"not found in any search path"}'
|
||||
```
|
||||
|
||||
---
|
||||
Missing files emit a warning event but do not abort the run.
|
||||
|
||||
## Context Bundle
|
||||
|
||||
The bridge generates `.archeflow/context/colette-bundle.md` — a summarized, token-efficient Markdown file that agents receive as part of their prompt context.
|
||||
Generated at `.archeflow/context/colette-bundle.md`. Summarized, not raw YAML. Target: under 1500 tokens.
|
||||
|
||||
### Bundle Structure
|
||||
|
||||
```markdown
|
||||
# Writing Context (auto-loaded from Colette)
|
||||
|
||||
## Voice Profile: <id>
|
||||
**Tone:** <tone_summary from meta>
|
||||
**Perspective:** <perspektive>
|
||||
**Density:** <dichte>
|
||||
**Attitude:** <haltung>
|
||||
**Sharpness:** <schaerfe>
|
||||
**Humor:** <humor>
|
||||
**Tempo:** <tempo>
|
||||
**Reader relationship:** <leser_beziehung>
|
||||
|
||||
### Forbidden
|
||||
- <each item from verboten>
|
||||
|
||||
### Allowed
|
||||
- <each item from erlaubt>
|
||||
|
||||
### Style models
|
||||
- <each item from vorbilder, name only + one-word tag>
|
||||
|
||||
## Persona: <id>
|
||||
**Name:** <name>
|
||||
**Bio:** <bio, max 2 sentences>
|
||||
**Genres:** <genres, comma-separated>
|
||||
|
||||
### Rules
|
||||
- <each item from rules>
|
||||
|
||||
## Characters
|
||||
### <name> (<role>)
|
||||
- **Age:** <age>
|
||||
- **Key traits:** <first 3 personality items>
|
||||
- **Speech:** <speech_pattern, first sentence only>
|
||||
- **Relationships:** <key relationships, one line each>
|
||||
|
||||
[Repeated for each character in characters/*.yaml]
|
||||
|
||||
## Series Context
|
||||
[Only if series config found in colette.yaml]
|
||||
- **Shared concepts:** <list>
|
||||
- **Glossary:** <key terms>
|
||||
- **Forbidden cross-story:** <items>
|
||||
|
||||
## Project Rules (from CLAUDE.md)
|
||||
[Key writing rules extracted from CLAUDE.md, summarized as bullet points]
|
||||
- <rule 1>
|
||||
- <rule 2>
|
||||
- ...
|
||||
```
|
||||
|
||||
### Summarization Rules
|
||||
|
||||
The bundle is **summarized**, not a raw YAML dump. This reduces token cost:
|
||||
|
||||
- Voice profile dimensions: key name + value (no YAML formatting, no `dimensionen:` wrapper)
|
||||
- Verboten/erlaubt: bullet list, strip explanation after the dash if over 15 words
|
||||
**Summarization rules:**
|
||||
- Voice dimensions: key + value (no YAML wrapper)
|
||||
- Verboten/erlaubt: bullet list, truncate items over 15 words
|
||||
- Characters: name, role, age, top 3 traits, first sentence of speech pattern, relationships
|
||||
- Persona bio: max 2 sentences
|
||||
- CLAUDE.md: extract only rules/style sections, skip meta/git/cost config
|
||||
- Target: bundle should be under 1500 tokens for a typical project
|
||||
|
||||
---
|
||||
- CLAUDE.md: only writing rules, skip meta/git/cost config
|
||||
|
||||
## Caching
|
||||
|
||||
The bundle is regenerated only when source files have changed. Cache validation uses file modification times.
|
||||
|
||||
### Cache Check Procedure
|
||||
|
||||
```
|
||||
bundle_path = .archeflow/context/colette-bundle.md
|
||||
|
||||
if bundle_path does not exist → generate
|
||||
if bundle_path exists:
|
||||
bundle_mtime = mtime of bundle_path
|
||||
for each resolved source file:
|
||||
if source_mtime > bundle_mtime → regenerate, break
|
||||
if no source file is newer → use cached bundle
|
||||
```
|
||||
|
||||
When the cache is valid, emit:
|
||||
|
||||
```bash
|
||||
./lib/archeflow-event.sh "$RUN_ID" decision init "" \
|
||||
'{"what":"colette_bundle_cache","chosen":"reuse","reason":"all sources older than bundle"}'
|
||||
```
|
||||
|
||||
When regenerating:
|
||||
|
||||
```bash
|
||||
./lib/archeflow-event.sh "$RUN_ID" decision init "" \
|
||||
'{"what":"colette_bundle_cache","chosen":"regenerate","reason":"<file> modified since last bundle"}'
|
||||
```
|
||||
|
||||
---
|
||||
Bundle regenerated only when source file mtimes are newer than the bundle. If all sources are older, reuse cached bundle.
|
||||
|
||||
## Per-Agent Attention Filters
|
||||
|
||||
Not every agent needs the full bundle. The bridge defines attention filters that control which sections each archetype receives. This extends the base attention filters from `archeflow:attention-filters`.
|
||||
Not every agent needs the full bundle:
|
||||
|
||||
| Archetype | Bundle sections injected | Rationale |
|
||||
|-----------|------------------------|-----------|
|
||||
| **Explorer** | Full bundle | Needs all context for research — setting, characters, voice, rules |
|
||||
| **Creator** | Voice dimensions + persona rules + characters | Designs outline — needs to know who speaks how, who exists, what's allowed |
|
||||
| **Maker** | Full bundle | Writes prose — needs voice for style, characters for dialogue, rules for guardrails |
|
||||
| **Guardian** | Characters + series shared_concepts | Checks consistency — needs character facts and cross-story constraints |
|
||||
| **Sage** | Voice profile (full, including verboten/erlaubt) + persona rules | Checks voice drift — needs the complete voice spec and persona constraints |
|
||||
| **Trickster** | Characters + series glossary | Tests continuity — needs character facts and terminology for contradiction checks |
|
||||
| Archetype | Receives |
|
||||
|-----------|----------|
|
||||
| Explorer | Full bundle |
|
||||
| Creator | Voice dimensions + persona rules + characters |
|
||||
| Maker | Full bundle |
|
||||
| Guardian | Characters + series shared_concepts |
|
||||
| Sage | Full voice profile (incl. verboten/erlaubt) + persona rules |
|
||||
| Trickster | Characters + series glossary |
|
||||
|
||||
### Filter Implementation
|
||||
|
||||
When injecting the bundle into an agent prompt, extract only the relevant sections:
|
||||
|
||||
```
|
||||
# For Guardian:
|
||||
Extract: "## Characters" section (all characters)
|
||||
Extract: "## Series Context" section (if present)
|
||||
Skip: everything else
|
||||
|
||||
# For Sage:
|
||||
Extract: "## Voice Profile" section (full, with forbidden/allowed)
|
||||
Extract: "## Persona" section (rules subsection)
|
||||
Skip: characters, series, project rules
|
||||
|
||||
# For Explorer and Maker:
|
||||
Inject: full bundle as-is
|
||||
```
|
||||
|
||||
The filtering happens at prompt assembly time, not at bundle generation time. One bundle, multiple filtered views.
|
||||
|
||||
### Custom Archetypes
|
||||
|
||||
Custom archetypes (e.g., `story-explorer`, `story-sage`) inherit the filter of their closest base archetype:
|
||||
|
||||
| Custom archetype | Inherits filter from | Override |
|
||||
|-----------------|---------------------|----------|
|
||||
| `story-explorer` | Explorer | Full bundle |
|
||||
| `story-sage` | Sage | Full voice profile + persona rules |
|
||||
| `story-guardian` | Guardian | Characters + series |
|
||||
|
||||
If a custom archetype needs a different filter, define it in the archetype's markdown frontmatter:
|
||||
Custom archetypes inherit the filter of their closest base archetype. Override with `colette_filter` in archetype frontmatter:
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: story-sage
|
||||
colette_filter: [voice_profile, persona, characters]
|
||||
---
|
||||
```
|
||||
|
||||
The `colette_filter` field accepts section keys: `voice_profile`, `persona`, `characters`, `series`, `project_rules`, `full`.
|
||||
Section keys: `voice_profile`, `persona`, `characters`, `series`, `project_rules`, `full`.
|
||||
|
||||
---
|
||||
|
||||
## Integration with Run Skill
|
||||
|
||||
The Colette Bridge hooks into `archeflow:run` initialization. The sequence is:
|
||||
## Run Integration
|
||||
|
||||
```
|
||||
run.start
|
||||
├── Domain detection (from archeflow:domains)
|
||||
│ └── colette.yaml found → domain = writing
|
||||
├── Colette Bridge activation
|
||||
│ ├── Resolve files (voice profile, persona, characters, CLAUDE.md)
|
||||
│ ├── Check bundle cache
|
||||
│ ├── Generate/refresh bundle → .archeflow/context/colette-bundle.md
|
||||
│ └── Register bundle path in artifact routing
|
||||
└── Continue to Plan phase
|
||||
+-- Domain detection -> colette.yaml found -> domain = writing
|
||||
+-- Colette Bridge activation
|
||||
| +-- Resolve files
|
||||
| +-- Check/refresh bundle cache
|
||||
| +-- Register bundle in artifact routing
|
||||
+-- Continue to Plan phase
|
||||
```
|
||||
|
||||
### Artifact Routing Registration
|
||||
|
||||
The bundle path is registered so that every phase's context injection includes the (filtered) bundle:
|
||||
|
||||
```
|
||||
artifact_routing.register_context(
|
||||
path = ".archeflow/context/colette-bundle.md",
|
||||
inject_at = "all_phases",
|
||||
filter_by = "archetype" # Apply per-agent attention filters
|
||||
)
|
||||
```
|
||||
|
||||
In practice, this means the run skill prepends the filtered bundle content to each agent's prompt, after the standard task description but before phase-specific artifacts.
|
||||
|
||||
### Prompt Injection Order
|
||||
|
||||
```
|
||||
1. Archetype definition (from SKILL.md or custom archetype .md)
|
||||
2. Domain-specific review focus (from archeflow:domains)
|
||||
**Prompt injection order:**
|
||||
1. Archetype definition
|
||||
2. Domain-specific review focus
|
||||
3. Colette bundle (filtered for this archetype)
|
||||
4. Task description
|
||||
5. Phase-specific artifacts (Explorer output, Creator proposal, etc.)
|
||||
5. Phase-specific artifacts
|
||||
6. Cycle feedback (if cycle 2+)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Example: Giesing Gschichten
|
||||
|
||||
Given this `colette.yaml`:
|
||||
|
||||
```yaml
|
||||
project:
|
||||
name: "Giesing Gschichten"
|
||||
author: "C. Nennemann"
|
||||
language: de
|
||||
type: fiction
|
||||
|
||||
voice:
|
||||
profile: vp-giesing-gschichten-v1
|
||||
|
||||
writing:
|
||||
target_words: 6000
|
||||
style: "Ich-Erzaehler, lakonisch, Eberhofer-meets-Grossstadt"
|
||||
```
|
||||
|
||||
The bridge:
|
||||
|
||||
1. Reads `voice.profile: vp-giesing-gschichten-v1`
|
||||
2. Searches for `./profiles/vp-giesing-gschichten-v1.yaml` — not found
|
||||
3. Searches for `../writing.colette/profiles/vp-giesing-gschichten-v1.yaml` — found
|
||||
4. Infers persona from voice profile ID pattern or searches `personas/` — finds `giesinger.yaml` at `../writing.colette/personas/giesinger.yaml`
|
||||
5. Globs `characters/*.yaml` — finds `alex.yaml` (and others if present)
|
||||
6. Reads `CLAUDE.md` for writing rules
|
||||
7. Generates bundle:
|
||||
|
||||
```markdown
|
||||
# Writing Context (auto-loaded from Colette)
|
||||
|
||||
## Voice Profile: vp-giesing-gschichten-v1
|
||||
**Tone:** Lakonisch, warmherzig-genervt, trockener Humor
|
||||
**Perspective:** Ich-Erzaehler (Alex), nah dran, subjektiv
|
||||
**Density:** Alltagsdetails die Atmosphaere schaffen
|
||||
**Attitude:** Lakonisch, leicht genervt, aber mit Herz
|
||||
**Sharpness:** Beobachtungsscharf, sprachlich reduziert
|
||||
**Humor:** Trocken, Understatement, absurde Situationen
|
||||
**Tempo:** Gemaechlich mit Spannungsspitzen, Slow Burn
|
||||
**Reader relationship:** Kumpel am Stammtisch
|
||||
|
||||
### Forbidden
|
||||
- Hochdeutsch-Sterilitaet
|
||||
- Krimi-Klischees (CSI, Profiler, Tatort)
|
||||
- Lederhosen-Kitsch und Oktoberfest-Folklore
|
||||
- Dialekt-Overkill
|
||||
- Moralisieren oder Erklaeren
|
||||
- Kuenstliche Spannungsaufbauten
|
||||
- Adverb-Orgien und Adjektiv-Ketten
|
||||
- Infodumps
|
||||
|
||||
### Allowed
|
||||
- Bairische Einsprengsel in Hochdeutsch-Prosa
|
||||
- Essen und Trinken als Leitmotiv
|
||||
- Kiffer-Humor und Slow-Motion-Beobachtungen
|
||||
- Gentrification-Satire
|
||||
- Echte Giesinger Orte und Strassen
|
||||
- Skurrile Nachbarn
|
||||
- Kriminalplot aus dem Alltag
|
||||
- Kurze, lakonische Dialoge
|
||||
|
||||
### Style models
|
||||
- Rita Falk (Erzaehlton), Wolf Haas (lakonisch), Helmut Dietl (Muenchner Milieu), Friedrich Ani (duester), Bukowski (Anti-Held)
|
||||
|
||||
## Persona: giesinger
|
||||
**Name:** Der Giesinger
|
||||
**Bio:** Erzaehlt Geschichten aus Muenchen-Giesing. Eberhofer meets Grossstadt.
|
||||
**Genres:** Krimi, Kurzgeschichte, Milieustudie
|
||||
|
||||
### Rules
|
||||
- Ich-Erzaehler, immer — Alex erzaehlt
|
||||
- Hauptsaechlich Hochdeutsch mit bairischen Einsprengsel
|
||||
- Jede Geschichte hat einen Kriminalplot
|
||||
- Essen/Trinken in jeder Geschichte
|
||||
- Echte Giesinger Orte und Strassen
|
||||
- Humor durch Understatement
|
||||
- Alex ist kein Ermittler
|
||||
- Figuren reden wie echte Menschen
|
||||
|
||||
## Characters
|
||||
### Alex (protagonist)
|
||||
- **Age:** Mitte 30
|
||||
- **Key traits:** Lakonisch, funktionaler Kiffer, unmotiviert aber nicht dumm
|
||||
- **Speech:** Kurze Saetze, Hochdeutsch mit bairischen Einsprengsel.
|
||||
- **Relationships:** Mo — Nachbar, Kumpel und Unruhestifter
|
||||
|
||||
## Project Rules (from CLAUDE.md)
|
||||
- Jede Geschichte beginnt mit einer Alltagsszene
|
||||
- Kriminalplot ergibt sich organisch aus dem Alltag
|
||||
- Essen/Trinken in jeder Geschichte
|
||||
- Echte Giesinger Orte verwenden
|
||||
- Kein Moralisieren, kein Erklaerbaer
|
||||
- Ende muss nicht alles aufloesen
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Design Principles
|
||||
|
||||
1. **Summarize, don't dump.** Raw YAML wastes tokens and confuses agents. The bundle is a curated briefing.
|
||||
2. **Cache aggressively.** Voice profiles and characters rarely change mid-run. Only regenerate when mtimes change.
|
||||
3. **Filter per agent.** A Guardian checking plot consistency does not need the full voice profile. A Sage checking voice drift does not need character sheets.
|
||||
4. **Graceful degradation.** Missing files are warned about, not fatal. A project with `colette.yaml` but no characters/ still works — the Characters section is simply empty.
|
||||
5. **One bundle, filtered views.** Generate the full bundle once. Filter at injection time per archetype. This keeps caching simple.
|
||||
6. **Additive to existing skills.** The bridge does not replace domain detection or artifact routing — it hooks into them. Remove the bridge, everything still works (just without auto-loaded writing context).
|
||||
|
||||
@@ -8,320 +8,87 @@ description: |
|
||||
<example>Automatically active when budget is configured</example>
|
||||
---
|
||||
|
||||
# Cost Tracking — Budget-Aware Orchestration
|
||||
# Cost Tracking -- Budget-Aware Orchestration
|
||||
|
||||
Every ArcheFlow orchestration consumes LLM tokens. This skill tracks costs per agent and per run, enforces budgets, and recommends cost-optimal model assignments.
|
||||
Tracks costs per agent and per run, enforces budgets, and selects cost-optimal models.
|
||||
|
||||
## Model Pricing Table
|
||||
## Model Pricing
|
||||
|
||||
Current pricing (update when models change):
|
||||
| Model | Input ($/M tok) | Output ($/M tok) |
|
||||
|-------|----------------:|-----------------:|
|
||||
| claude-opus-4-6 | 15.00 | 75.00 |
|
||||
| claude-sonnet-4-6 | 3.00 | 15.00 |
|
||||
| claude-haiku-4-5 | 0.80 | 4.00 |
|
||||
|
||||
| Model | Input ($/M tokens) | Output ($/M tokens) | Notes |
|
||||
|-------|--------------------:|---------------------:|-------|
|
||||
| `claude-opus-4-6` | 15.00 | 75.00 | Highest quality, use sparingly |
|
||||
| `claude-sonnet-4-6` | 3.00 | 15.00 | Good balance of quality and cost |
|
||||
| `claude-haiku-4-5` | 0.80 | 4.00 | Cheap, fast, good for structured tasks |
|
||||
**Prompt caching:** 90% discount on cached input tokens. Structure system prompts for cache hits.
|
||||
**Batches API:** 50% discount. Use for non-time-sensitive bulk ops.
|
||||
|
||||
**Prompt caching** (when applicable): 90% discount on cached input tokens. The orchestrator should structure system prompts to maximize cache hits (archetype instructions, voice profiles, and domain context are cache-friendly since they repeat across agents in a run).
|
||||
|
||||
**Batches API**: 50% discount on all tokens. Use for non-time-sensitive bulk operations (validation passes, consistency checks).
|
||||
|
||||
## Per-Agent Cost Tracking
|
||||
|
||||
Every `agent.complete` event includes cost data:
|
||||
|
||||
```jsonl
|
||||
{
|
||||
"type": "agent.complete",
|
||||
"data": {
|
||||
"archetype": "story-explorer",
|
||||
"duration_ms": 87605,
|
||||
"tokens_input": 15000,
|
||||
"tokens_output": 6000,
|
||||
"tokens_cache_read": 8000,
|
||||
"model": "haiku",
|
||||
"estimated_cost_usd": 0.02,
|
||||
"summary": "3 plot directions developed, recommended C"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Cost Calculation
|
||||
## Cost Calculation
|
||||
|
||||
```
|
||||
cost = (tokens_input - tokens_cache_read) * input_price / 1_000_000
|
||||
+ tokens_cache_read * input_price * 0.10 / 1_000_000
|
||||
+ tokens_output * output_price / 1_000_000
|
||||
cost = (input - cache_read) * input_price/1M
|
||||
+ cache_read * input_price * 0.10/1M
|
||||
+ output * output_price/1M
|
||||
```
|
||||
|
||||
If exact token counts are unavailable (Claude Code doesn't always expose them), estimate based on character count:
|
||||
If exact tokens unavailable, estimate: `tokens ~= chars / 4`. Mark with `cost_estimated: true`.
|
||||
|
||||
```
|
||||
estimated_tokens = character_count / 4 # rough heuristic
|
||||
```
|
||||
## Default Model Assignments
|
||||
|
||||
Mark estimated costs with `"cost_estimated": true` in the event data so reports can distinguish measured from estimated values.
|
||||
| Archetype | Code | Writing |
|
||||
|-----------|------|---------|
|
||||
| Explorer | haiku | haiku |
|
||||
| Creator | sonnet | sonnet |
|
||||
| Maker | sonnet | **sonnet** |
|
||||
| Guardian | haiku | haiku |
|
||||
| Skeptic | haiku | haiku |
|
||||
| Sage | sonnet | **sonnet** |
|
||||
| Trickster | haiku | haiku |
|
||||
|
||||
## Run-Level Aggregation
|
||||
Opus is user-opt-in only (team preset `model_overrides`).
|
||||
|
||||
The `run.complete` event includes cost totals:
|
||||
**Resolution order:** team preset override > domain override > archetype default.
|
||||
|
||||
```jsonl
|
||||
{
|
||||
"type": "run.complete",
|
||||
"data": {
|
||||
"status": "completed",
|
||||
"total_tokens_input": 95000,
|
||||
"total_tokens_output": 33000,
|
||||
"total_tokens_cache_read": 42000,
|
||||
"total_cost_usd": 1.45,
|
||||
"budget_usd": 10.00,
|
||||
"budget_remaining_usd": 8.55,
|
||||
"agents_total": 5,
|
||||
"cost_by_phase": {
|
||||
"plan": 0.35,
|
||||
"do": 0.72,
|
||||
"check": 0.38
|
||||
},
|
||||
"cost_by_model": {
|
||||
"haiku": 0.12,
|
||||
"sonnet": 1.33
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
## Pre-Agent Cost Estimates
|
||||
|
||||
### Cost Summary in Orchestration Report
|
||||
| Archetype | Typical Input | Typical Output |
|
||||
|-----------|-------------:|---------------:|
|
||||
| Explorer | 8k | 4k |
|
||||
| Creator | 12k | 6k |
|
||||
| Maker | 15k | 12k |
|
||||
| Guardian | 10k | 3k |
|
||||
| Skeptic | 8k | 3k |
|
||||
| Sage | 12k | 4k |
|
||||
| Trickster | 8k | 4k |
|
||||
|
||||
After each orchestration, the report includes a cost section:
|
||||
|
||||
```markdown
|
||||
## Cost Summary
|
||||
| Phase | Model(s) | Tokens (in/out) | Cost |
|
||||
|-------|----------|-----------------|------|
|
||||
| Plan | haiku, sonnet | 32k / 12k | $0.35 |
|
||||
| Do | sonnet | 40k / 15k | $0.72 |
|
||||
| Check | haiku, sonnet | 23k / 6k | $0.38 |
|
||||
| **Total** | | **95k / 33k** | **$1.45** |
|
||||
|
||||
Budget: $10.00 | Spent: $1.45 | Remaining: $8.55
|
||||
```
|
||||
After 10+ runs, use actual averages from `metrics.jsonl` instead.
|
||||
|
||||
## Budget Configuration
|
||||
|
||||
Budgets are defined in team presets or `.archeflow/config.yaml`:
|
||||
|
||||
```yaml
|
||||
# .archeflow/config.yaml
|
||||
budget:
|
||||
per_run_usd: 10.00 # Max cost per orchestration run
|
||||
per_agent_usd: 3.00 # Max cost per individual agent
|
||||
daily_usd: 50.00 # Max daily spend across all runs
|
||||
warn_at_percent: 75 # Warn when this % of budget is consumed
|
||||
per_run_usd: 10.00
|
||||
per_agent_usd: 3.00
|
||||
daily_usd: 50.00
|
||||
warn_at_percent: 75
|
||||
```
|
||||
|
||||
```yaml
|
||||
# Team preset override
|
||||
name: story-development
|
||||
domain: writing
|
||||
budget:
|
||||
per_run_usd: 5.00 # Writing runs are usually cheaper
|
||||
```
|
||||
|
||||
Team preset budget overrides the global config for that run.
|
||||
|
||||
### Budget Precedence
|
||||
|
||||
1. Team preset `budget` (if set)
|
||||
2. `.archeflow/config.yaml` `budget`
|
||||
3. No budget (unlimited) — costs are still tracked but not enforced
|
||||
Team preset budget overrides global config. No budget = unlimited (costs still tracked).
|
||||
|
||||
## Budget Enforcement
|
||||
|
||||
Budget checks happen at two points:
|
||||
**Pre-agent:** Estimate cost. If > remaining budget: stop (autonomous) or warn (attended).
|
||||
|
||||
### 1. Pre-Agent Check (before spawning)
|
||||
**Post-agent:** Update total. Warn at threshold. Stop if budget exceeded.
|
||||
|
||||
Before each agent is spawned, estimate its cost and check against remaining budget:
|
||||
## Cost Optimization
|
||||
|
||||
```
|
||||
estimated_agent_cost = estimate_tokens(archetype, task_complexity) * model_price
|
||||
remaining_budget = budget - sum(costs_so_far)
|
||||
|
||||
if estimated_agent_cost > remaining_budget:
|
||||
WARN: "Estimated cost for {archetype} (${estimated}) would exceed remaining budget (${remaining}). Continue? [y/N]"
|
||||
```
|
||||
|
||||
**In autonomous mode**: if budget would be exceeded, STOP the run and report. Do not prompt — there is no one to answer.
|
||||
|
||||
**In attended mode**: warn and ask the user. They can approve the overage or stop.
|
||||
|
||||
### 2. Post-Agent Check (after completion)
|
||||
|
||||
After each agent completes, update the running total and check:
|
||||
|
||||
```
|
||||
if total_cost > budget * warn_at_percent / 100:
|
||||
WARN: "Budget ${warn_at_percent}% consumed (${total_cost} of ${budget})"
|
||||
|
||||
if total_cost > budget:
|
||||
STOP: "Budget exceeded (${total_cost} of ${budget}). Run halted."
|
||||
```
|
||||
|
||||
### Pre-Agent Cost Estimation
|
||||
|
||||
Rough token estimates by archetype (calibrate over time with actual data from `metrics.jsonl`):
|
||||
|
||||
| Archetype | Typical Input | Typical Output | Notes |
|
||||
|-----------|-------------:|---------------:|-------|
|
||||
| Explorer | 8k | 4k | Research, reads many files |
|
||||
| Creator | 12k | 6k | Receives Explorer output, produces plan |
|
||||
| Maker | 15k | 12k | Largest output (implementation/prose) |
|
||||
| Guardian | 10k | 3k | Reads diff, structured output |
|
||||
| Skeptic | 8k | 3k | Reads proposal, structured challenges |
|
||||
| Sage | 12k | 4k | Reads diff + proposal |
|
||||
| Trickster | 8k | 4k | Reads diff, generates test cases |
|
||||
|
||||
These are starting estimates. After 10+ runs, use actual averages from `metrics.jsonl` instead.
|
||||
|
||||
## Cost-Aware Model Selection
|
||||
|
||||
Each archetype has a recommended model tier based on the quality requirements of its role:
|
||||
|
||||
### Default Model Assignments (Code Domain)
|
||||
|
||||
| Archetype | Model | Rationale |
|
||||
|-----------|-------|-----------|
|
||||
| Explorer | haiku | Research is structured extraction — cheap model handles it well |
|
||||
| Creator | sonnet | Design decisions need reasoning quality |
|
||||
| Maker | sonnet | Implementation needs quality to avoid rework cycles |
|
||||
| Guardian | haiku | Security/risk review is checklist-driven — structured and cheap |
|
||||
| Skeptic | haiku | Challenge generation follows patterns — cheap |
|
||||
| Sage | sonnet | Holistic quality judgment needs nuance |
|
||||
| Trickster | haiku | Adversarial testing is systematic — cheap |
|
||||
|
||||
### Writing Domain Overrides
|
||||
|
||||
Writing tasks need higher quality for prose-generating agents:
|
||||
|
||||
| Archetype | Model | Rationale |
|
||||
|-----------|-------|-----------|
|
||||
| Explorer / story-explorer | haiku | Research is still cheap |
|
||||
| Creator | sonnet | Outline design needs narrative judgment |
|
||||
| Maker | **sonnet** | Prose quality is the product — cannot be cheap |
|
||||
| Guardian | haiku | Plot/continuity checks are structured |
|
||||
| Skeptic | haiku | Premise challenges are structured |
|
||||
| Sage / story-sage | **sonnet** | Voice and craft judgment need taste |
|
||||
| Trickster | haiku | Reader-confusion analysis is systematic |
|
||||
|
||||
**When to escalate to opus**: Only for final-pass prose polishing on high-stakes content (book manuscripts, not short stories). Never for review or research agents. The user must explicitly opt in via:
|
||||
|
||||
```yaml
|
||||
# Team preset
|
||||
model_overrides:
|
||||
maker: opus # Only for final polish pass
|
||||
```
|
||||
|
||||
### Domain-Driven Model Selection
|
||||
|
||||
The effective model for each agent is resolved in this order:
|
||||
|
||||
1. **Team preset `model_overrides`** (highest priority — explicit choice)
|
||||
2. **Domain `model_overrides`** (from `.archeflow/domains/<name>.yaml`)
|
||||
3. **Archetype default** (from the table above)
|
||||
4. **Custom archetype `model` field** (from archetype YAML frontmatter)
|
||||
|
||||
Example resolution for `story-sage` in a writing run:
|
||||
- Team preset says nothing about story-sage → skip
|
||||
- Writing domain says `story-sage: sonnet` → **use sonnet**
|
||||
- Archetype YAML says `model: sonnet` → would have been used if domain didn't specify
|
||||
|
||||
## Cost Optimization Strategies
|
||||
|
||||
### 1. Prompt Caching
|
||||
|
||||
Structure prompts so that stable content comes first (maximizes cache prefix hits):
|
||||
|
||||
```
|
||||
[System prompt — archetype instructions] ← cached across agents in same run
|
||||
[Domain context — voice profile, persona] ← cached across agents in same run
|
||||
[Phase context — Explorer output, proposal] ← changes per agent
|
||||
[Task-specific instructions] ← changes per agent
|
||||
```
|
||||
|
||||
Estimated savings: 30-50% on input tokens for runs with 5+ agents.
|
||||
|
||||
### 2. Guardian Fast-Path (A2)
|
||||
|
||||
When Guardian approves with 0 issues, skip Skeptic/Sage/Trickster. This saves 2-3 agent calls per cycle. See `archeflow:orchestration` skill, rule A2.
|
||||
|
||||
Typical savings: $0.30-0.80 per skipped cycle (depending on models).
|
||||
|
||||
### 3. Explorer Cache
|
||||
|
||||
Reuse recent Explorer research instead of re-running. See `archeflow:orchestration` skill, Explorer Cache section.
|
||||
|
||||
Typical savings: $0.02-0.05 per cache hit (haiku Explorer).
|
||||
|
||||
### 4. Batches API for Bulk Operations
|
||||
|
||||
When running consistency checks, validation passes, or other non-time-sensitive work across multiple files, use the Batches API (50% discount):
|
||||
|
||||
```yaml
|
||||
# Mark agents as batch-eligible in team presets
|
||||
batch_eligible:
|
||||
- guardian # Structured review, can wait
|
||||
- skeptic # Challenge generation, can wait
|
||||
```
|
||||
|
||||
Only use batches when the user is not waiting for real-time results (overnight runs, autonomous mode).
|
||||
|
||||
### 5. Early Termination
|
||||
|
||||
If the first cycle produces a clean Guardian pass (A2 fast-path) AND the Maker's self-review checklist is clean, skip the remaining cycles even if `max_cycles > 1`. This avoids spending tokens on unnecessary verification.
|
||||
1. **Prompt caching:** Stable content first (archetype instructions, voice profiles). Saves 30-50% on input.
|
||||
2. **Guardian fast-path (A2):** 0 issues = skip remaining reviewers. Saves $0.30-0.80/cycle.
|
||||
3. **Explorer cache:** Reuse recent research. Saves $0.02-0.05/hit.
|
||||
4. **Batches API:** For autonomous/overnight review passes (50% discount).
|
||||
5. **Early termination:** Clean Guardian + clean Maker self-review = skip remaining cycles.
|
||||
|
||||
## Daily Cost Tracking
|
||||
|
||||
Across runs, maintain a daily cost ledger:
|
||||
|
||||
```
|
||||
.archeflow/costs/<YYYY-MM-DD>.jsonl
|
||||
```
|
||||
|
||||
Each line is one run's cost summary:
|
||||
|
||||
```jsonl
|
||||
{"run_id":"2026-04-03-der-huster","cost_usd":1.45,"tokens_input":95000,"tokens_output":33000,"models":{"haiku":2,"sonnet":3},"domain":"writing"}
|
||||
{"run_id":"2026-04-03-auth-refactor","cost_usd":2.10,"tokens_input":120000,"tokens_output":45000,"models":{"haiku":3,"sonnet":2},"domain":"code"}
|
||||
```
|
||||
|
||||
Daily budget enforcement reads this file to check `daily_usd` limits before starting new runs.
|
||||
|
||||
### Cost Report Command
|
||||
|
||||
```bash
|
||||
# Show today's costs
|
||||
./lib/archeflow-costs.sh today
|
||||
|
||||
# Show costs for a date range
|
||||
./lib/archeflow-costs.sh 2026-04-01 2026-04-03
|
||||
|
||||
# Show costs for a specific run
|
||||
./lib/archeflow-costs.sh run 2026-04-03-der-huster
|
||||
```
|
||||
|
||||
## Integration with Other Skills
|
||||
|
||||
- **`orchestration`**: Calls pre-agent and post-agent budget checks. Includes cost summary in orchestration report.
|
||||
- **`process-log`**: Cost data is embedded in `agent.complete` and `run.complete` events. No separate cost events needed.
|
||||
- **`domains`**: Reads `model_overrides` from the active domain to determine effective model per agent.
|
||||
- **`autonomous-mode`**: Enforces budget strictly (no prompts — just stop on budget exceeded). Uses daily budget to limit overnight spend.
|
||||
- **`workflow-design`**: Custom workflows can specify per-phase model assignments that override domain defaults.
|
||||
|
||||
## Design Principles
|
||||
|
||||
1. **Track always, enforce optionally.** Cost data is in every event regardless of whether a budget is set. Budget enforcement is opt-in.
|
||||
2. **Estimate before spend.** Always estimate before spawning an agent. Surprises are worse than slightly inaccurate estimates.
|
||||
3. **Cheapest model that works.** Default to haiku. Upgrade to sonnet only when the task demonstrably needs it. Opus is user-opt-in only.
|
||||
4. **Transparent.** Every cost shows up in the orchestration report. No hidden token spend.
|
||||
5. **Learn from history.** After enough runs, replace estimates with actual averages from `metrics.jsonl`.
|
||||
Ledger at `.archeflow/costs/<YYYY-MM-DD>.jsonl`. One line per run with cost, tokens, models, domain. Daily budget enforcement reads this before starting new runs.
|
||||
|
||||
@@ -1,181 +1,58 @@
|
||||
---
|
||||
name: custom-archetypes
|
||||
description: Use when the user wants to create domain-specific archetypes — specialized agent roles beyond the 7 built-in ones. For example a database reviewer, compliance auditor, or accessibility tester.
|
||||
description: Use when the user wants to create domain-specific archetypes -- specialized agent roles beyond the 7 built-in ones.
|
||||
---
|
||||
|
||||
# Custom Archetypes
|
||||
|
||||
ArcheFlow's 7 built-in archetypes cover general software engineering. Custom archetypes add **domain expertise** — a database specialist, a compliance auditor, an accessibility reviewer.
|
||||
Add domain expertise beyond the 7 built-ins: database specialist, compliance auditor, accessibility reviewer, etc.
|
||||
|
||||
## When to Create One
|
||||
## When to Create
|
||||
|
||||
- A recurring review concern isn't covered by built-in archetypes
|
||||
- A recurring review concern isn't covered by built-ins
|
||||
- You need domain knowledge (GDPR, PCI-DSS, WCAG, SQL optimization)
|
||||
- The same custom instructions are used in multiple orchestrations
|
||||
- Same custom instructions used across multiple orchestrations
|
||||
|
||||
## Archetype Definition
|
||||
## Definition Format
|
||||
|
||||
Create a markdown file in your project at `.archeflow/archetypes/<id>.md`:
|
||||
Create `.archeflow/archetypes/<id>.md`:
|
||||
|
||||
```markdown
|
||||
# <Name>
|
||||
|
||||
## Identity
|
||||
**ID:** <lowercase-with-hyphens>
|
||||
**Role:** <one sentence — what this archetype does>
|
||||
**Lens:** <the question this archetype always asks>
|
||||
**Role:** <one sentence>
|
||||
**Lens:** <the one question this archetype always asks>
|
||||
**Model tier:** cheap | standard | premium
|
||||
|
||||
## Behavior
|
||||
<System prompt injected into the agent. Define:
|
||||
- What to look for
|
||||
- How to evaluate
|
||||
- What output format to use
|
||||
- Decision criteria for approve/reject>
|
||||
<System prompt: what to look for, how to evaluate, output format, decision criteria>
|
||||
|
||||
## Outputs
|
||||
<What message types this archetype produces>
|
||||
- Research (if it gathers info)
|
||||
- Proposal (if it designs)
|
||||
- Challenge (if it critiques)
|
||||
- RiskAssessment (if it assesses risk)
|
||||
- QualityReport (if it reviews quality)
|
||||
- Implementation (if it writes code)
|
||||
<Message types: Research, Proposal, Challenge, RiskAssessment, QualityReport, Implementation>
|
||||
|
||||
## Shadow
|
||||
**Name:** <the dysfunction>
|
||||
**Strength inverted:** <how the core strength becomes destructive>
|
||||
**Symptoms:**
|
||||
- <observable behavior 1>
|
||||
- <observable behavior 2>
|
||||
- <observable behavior 3>
|
||||
**Name:** <dysfunction name>
|
||||
**Strength inverted:** <how core strength becomes destructive>
|
||||
**Symptoms:** <3 observable behaviors>
|
||||
**Correction:** <specific prompt to course-correct>
|
||||
```
|
||||
|
||||
## Examples
|
||||
## Composition
|
||||
|
||||
### Database Specialist
|
||||
```markdown
|
||||
# Database Specialist
|
||||
Combine two archetypes into a focused super-reviewer:
|
||||
|
||||
## Identity
|
||||
**ID:** db-specialist
|
||||
**Role:** Reviews database schemas, queries, and migration safety
|
||||
**Lens:** "Will this scale? Will this corrupt data?"
|
||||
**Model tier:** standard
|
||||
|
||||
## Behavior
|
||||
You review database changes for:
|
||||
1. Schema design — normalization, index coverage, constraint integrity
|
||||
2. Query performance — would an EXPLAIN ANALYZE show problems?
|
||||
3. Migration safety — backward compatible? Zero-downtime possible?
|
||||
4. Data integrity — foreign keys, unique constraints, NOT NULL where needed
|
||||
|
||||
Output APPROVED or REJECTED with findings including:
|
||||
- Table/column/query location
|
||||
- Severity (CRITICAL/WARNING/INFO)
|
||||
- Specific fix
|
||||
|
||||
## Outputs
|
||||
- Challenge
|
||||
- QualityReport
|
||||
|
||||
## Shadow
|
||||
**Name:** Schema Perfectionist
|
||||
**Strength inverted:** Database expertise becomes over-normalization and premature optimization
|
||||
**Symptoms:**
|
||||
- Demanding 3NF for a 10-row config table
|
||||
- Requiring indexes for queries that run once a day
|
||||
- Blocking on theoretical scale issues for an app with 50 users
|
||||
**Correction:** "Optimize for the current order of magnitude. If the app has 1000 users, design for 10,000. Not for 10 million."
|
||||
```
|
||||
|
||||
### Compliance Auditor
|
||||
```markdown
|
||||
# Compliance Auditor
|
||||
|
||||
## Identity
|
||||
**ID:** compliance-auditor
|
||||
**Role:** Verifies code changes against regulatory requirements
|
||||
**Lens:** "Could this get us fined?"
|
||||
**Model tier:** premium
|
||||
|
||||
## Behavior
|
||||
You audit changes against:
|
||||
1. GDPR — personal data handling, consent, right to deletion
|
||||
2. PCI-DSS — payment data storage, transmission, access controls
|
||||
3. Logging — are sensitive fields being logged? PII in error messages?
|
||||
4. Data retention — are we keeping data longer than allowed?
|
||||
|
||||
Reference specific regulation articles in findings.
|
||||
|
||||
## Outputs
|
||||
- RiskAssessment
|
||||
|
||||
## Shadow
|
||||
**Name:** Regulation Zealot
|
||||
**Strength inverted:** Compliance awareness becomes impossible-to-satisfy requirements
|
||||
**Symptoms:**
|
||||
- Citing regulations irrelevant to the change
|
||||
- Requiring legal review for non-PII code
|
||||
- Blocking internal tools with customer-facing compliance standards
|
||||
**Correction:** "Match the compliance level to the data classification. Internal admin tools don't need PCI-DSS Level 1 controls."
|
||||
```
|
||||
|
||||
## Using Custom Archetypes
|
||||
|
||||
Reference them by ID when orchestrating:
|
||||
|
||||
```
|
||||
# In the orchestration skill, add to Check phase:
|
||||
Agent(
|
||||
description: "db-specialist: review schema changes",
|
||||
prompt: "<contents of .archeflow/archetypes/db-specialist.md>
|
||||
Review the changes in branch: <maker's branch>
|
||||
..."
|
||||
)
|
||||
```
|
||||
|
||||
Or in a custom workflow, include them in the check phase archetypes list.
|
||||
|
||||
## Archetype Composition
|
||||
|
||||
Combine two archetypes into a focused super-reviewer when you need a specific perspective but don't want to spawn two agents:
|
||||
|
||||
```markdown
|
||||
# .archeflow/archetypes/security-breaker.md
|
||||
|
||||
## Identity
|
||||
**ID:** security-breaker
|
||||
**Composed of:** Guardian + Trickster
|
||||
**Role:** Security review with active exploitation attempts
|
||||
**Lens:** "Can I break the security model? How?"
|
||||
**Model tier:** standard
|
||||
|
||||
## Behavior
|
||||
Combine Guardian's checklist-driven security review with Trickster's
|
||||
adversarial testing. For each Guardian finding, attempt to exploit it.
|
||||
Only report findings you can actually reproduce.
|
||||
|
||||
## Shadow
|
||||
**Name:** Security Theater
|
||||
**Strength inverted:** Both shadows compound — paranoid blocking + noise
|
||||
**Correction:** "Only report findings with reproduction steps. Max 5."
|
||||
```
|
||||
|
||||
**Rules for composition:**
|
||||
- Max 2 archetypes combined (more defeats the purpose)
|
||||
- Max 2 archetypes combined
|
||||
- Combined shadow must address both source shadows
|
||||
- Use when spawning both separately would waste tokens on overlapping context
|
||||
|
||||
## Team Presets
|
||||
|
||||
Save common team configurations for your project in `.archeflow/teams/`:
|
||||
Save team configs in `.archeflow/teams/<name>.yaml`:
|
||||
|
||||
```yaml
|
||||
# .archeflow/teams/backend.yaml
|
||||
name: backend
|
||||
description: Standard backend development team
|
||||
plan: [explorer, creator]
|
||||
do: [maker]
|
||||
check: [guardian, sage]
|
||||
@@ -183,23 +60,12 @@ exit: all_approved
|
||||
max_cycles: 2
|
||||
```
|
||||
|
||||
```yaml
|
||||
# .archeflow/teams/security-audit.yaml
|
||||
name: security-audit
|
||||
description: Security-focused review team
|
||||
plan: [explorer, creator]
|
||||
do: [maker]
|
||||
check: [guardian, trickster, compliance-auditor]
|
||||
exit: all_approved
|
||||
max_cycles: 3
|
||||
```
|
||||
Reference custom archetypes by ID in the `check` (or any phase) list.
|
||||
|
||||
Use in orchestration: `"Use the backend team preset"` or `"Run security-audit workflow on this change"`
|
||||
## Rules
|
||||
|
||||
## Design Principles
|
||||
|
||||
1. **One concern per archetype.** Don't make a "full-stack reviewer."
|
||||
2. **Concrete shadow.** Vague shadows don't get detected. Use observable symptoms.
|
||||
3. **Right model tier.** Analytical → cheap. Creative → standard. Judgment-heavy → premium.
|
||||
4. **Specific lens.** The one question the archetype asks. This focuses behavior.
|
||||
5. **Composition over sprawl.** Combine before creating from scratch. 2 composed > 3 separate.
|
||||
1. One concern per archetype
|
||||
2. Concrete shadow with observable symptoms
|
||||
3. Right model tier: analytical = cheap, creative = standard, judgment = premium
|
||||
4. Specific lens question focuses behavior
|
||||
5. Compose before creating from scratch
|
||||
|
||||
@@ -10,363 +10,92 @@ description: |
|
||||
|
||||
# Domain Adapter System
|
||||
|
||||
ArcheFlow's PDCA pipeline and archetype system are domain-agnostic. This skill defines how to adapt them to specific domains (writing, code, research, etc.) so that events, metrics, reviews, and context use terminology that makes sense for the work being done.
|
||||
Adapts the PDCA pipeline and archetype system to specific domains (writing, code, research) so events, metrics, reviews, and context use domain-appropriate terminology.
|
||||
|
||||
## Domain Registry
|
||||
|
||||
Domain definitions live in `.archeflow/domains/<name>.yaml`. Each domain maps ArcheFlow's generic concepts to domain-specific equivalents and configures what metrics to track, what reviewers should focus on, and what context agents need.
|
||||
Domain definitions live in `.archeflow/domains/<name>.yaml`. Each maps generic concepts to domain-specific equivalents.
|
||||
|
||||
### Writing Domain
|
||||
### Concept Mapping
|
||||
|
||||
```yaml
|
||||
# .archeflow/domains/writing.yaml
|
||||
name: writing
|
||||
description: "Creative writing — stories, novels, non-fiction"
|
||||
| Generic Concept | Code | Writing | Research |
|
||||
|----------------|------|---------|----------|
|
||||
| implementation | code changes | draft/prose | draft/analysis |
|
||||
| tests | automated tests | consistency checks | citation verification |
|
||||
| files_changed | files changed | word count delta | section count |
|
||||
| test_coverage | test coverage % | voice drift score | source coverage |
|
||||
| code_review | code review | prose review | peer review |
|
||||
| build | build/compile | compile/export | compile (LaTeX/PDF) |
|
||||
| deploy | deploy | publish | submit/publish |
|
||||
| bug | bug | continuity error | unsupported claim |
|
||||
| feature | feature | scene/chapter | section |
|
||||
|
||||
# Concept mapping — how generic ArcheFlow terms translate
|
||||
concepts:
|
||||
implementation: "draft/prose"
|
||||
tests: "consistency checks"
|
||||
files_changed: "word count delta"
|
||||
test_coverage: "voice drift score"
|
||||
code_review: "prose review"
|
||||
build: "compile/export"
|
||||
deploy: "publish"
|
||||
refactor: "revision"
|
||||
bug: "continuity error"
|
||||
feature: "scene/chapter"
|
||||
PR: "manuscript submission"
|
||||
### Metrics by Domain
|
||||
|
||||
# Metrics — what to track instead of lines/files/tests
|
||||
metrics:
|
||||
- word_count
|
||||
- voice_drift_score
|
||||
- dialect_density
|
||||
- essen_count # Giesing Gschichten rule: food in every scene
|
||||
- scene_count
|
||||
- dialogue_ratio
|
||||
| Code | Writing | Research |
|
||||
|------|---------|----------|
|
||||
| files_changed | word_count | word_count |
|
||||
| lines_added/removed | voice_drift_score | citation_count |
|
||||
| tests_added | dialect_density | source_diversity |
|
||||
| tests_passing | scene_count | claim_count |
|
||||
| coverage_delta | dialogue_ratio | unsupported_claims |
|
||||
|
||||
# Review focus areas — override default Guardian/Sage lenses
|
||||
review_focus:
|
||||
guardian:
|
||||
- plot_coherence
|
||||
- character_consistency
|
||||
- timeline_accuracy
|
||||
- continuity
|
||||
sage:
|
||||
- voice_consistency
|
||||
- prose_quality
|
||||
- dialect_authenticity
|
||||
- forbidden_pattern_violations
|
||||
skeptic:
|
||||
- premise_strength
|
||||
- character_motivation
|
||||
- ending_satisfaction
|
||||
trickster:
|
||||
- reader_confusion_points
|
||||
- pacing_dead_spots
|
||||
- suspension_of_disbelief_breaks
|
||||
### Review Focus by Domain
|
||||
|
||||
# Context injection — what extra files agents should read per phase
|
||||
context:
|
||||
always:
|
||||
- "voice profile YAML (profiles/*.yaml)"
|
||||
- "persona YAML (personas/*.yaml)"
|
||||
- "character sheets (characters/*.yaml)"
|
||||
plan_phase:
|
||||
- "series config (colette.yaml)"
|
||||
- "previous stories (if series, for continuity)"
|
||||
- "story brief / premise"
|
||||
do_phase:
|
||||
- "scene outline from Creator"
|
||||
- "voice profile (for style reference)"
|
||||
check_phase:
|
||||
- "voice profile (for Sage drift scoring)"
|
||||
- "outline (for Guardian coherence check)"
|
||||
- "character sheets (for consistency)"
|
||||
| Reviewer | Code | Writing | Research |
|
||||
|----------|------|---------|----------|
|
||||
| Guardian | security, breaking changes, deps, error handling | plot coherence, character consistency, timeline, continuity | factual accuracy, citation validity, logic, methodology |
|
||||
| Sage | code quality, coverage, docs, patterns | voice consistency, prose quality, dialect authenticity | argument structure, clarity, tone, completeness |
|
||||
| Skeptic | design assumptions, scalability, edge cases | premise strength, motivation, ending satisfaction | (default) |
|
||||
| Trickster | malformed input, races, error paths, dep failures | reader confusion, pacing dead spots, disbelief breaks | (default) |
|
||||
|
||||
# Model preferences — domain-specific overrides
|
||||
model_overrides:
|
||||
maker: sonnet # Prose quality matters more than for code
|
||||
story-sage: sonnet # Needs taste for voice evaluation
|
||||
```
|
||||
### Model Overrides
|
||||
|
||||
### Code Domain (Default)
|
||||
Domains can override default model assignments:
|
||||
|
||||
```yaml
|
||||
# .archeflow/domains/code.yaml
|
||||
name: code
|
||||
description: "Software development — applications, libraries, infrastructure"
|
||||
| Domain | Override | Rationale |
|
||||
|--------|----------|-----------|
|
||||
| Writing | maker: sonnet | Prose quality is the product |
|
||||
| Writing | story-sage: sonnet | Voice evaluation needs taste |
|
||||
| Research | maker: sonnet | Analysis quality matters |
|
||||
| Code | (none) | Defaults are calibrated for code |
|
||||
|
||||
concepts:
|
||||
implementation: "code changes"
|
||||
tests: "automated tests"
|
||||
files_changed: "files changed"
|
||||
test_coverage: "test coverage %"
|
||||
code_review: "code review"
|
||||
build: "build/compile"
|
||||
deploy: "deploy"
|
||||
refactor: "refactor"
|
||||
bug: "bug"
|
||||
feature: "feature"
|
||||
PR: "pull request"
|
||||
### Context Injection by Domain
|
||||
|
||||
metrics:
|
||||
- files_changed
|
||||
- lines_added
|
||||
- lines_removed
|
||||
- tests_added
|
||||
- tests_passing
|
||||
- coverage_delta
|
||||
Domains declare which extra files agents should read per phase. Context injection is additive (on top of standard ArcheFlow context).
|
||||
|
||||
review_focus:
|
||||
guardian:
|
||||
- security_vulnerabilities
|
||||
- breaking_changes
|
||||
- dependency_risks
|
||||
- error_handling
|
||||
sage:
|
||||
- code_quality
|
||||
- test_coverage
|
||||
- documentation
|
||||
- pattern_consistency
|
||||
skeptic:
|
||||
- design_assumptions
|
||||
- scalability
|
||||
- alternative_approaches
|
||||
- edge_cases
|
||||
trickster:
|
||||
- malformed_input
|
||||
- concurrency_races
|
||||
- error_path_exploitation
|
||||
- dependency_failures
|
||||
|
||||
context:
|
||||
always:
|
||||
- "README.md"
|
||||
- ".archeflow/config.yaml"
|
||||
plan_phase:
|
||||
- "relevant source files (Explorer identifies)"
|
||||
- "existing tests for affected area"
|
||||
do_phase:
|
||||
- "Creator's proposal"
|
||||
- "test fixtures and helpers"
|
||||
check_phase:
|
||||
- "git diff from Maker"
|
||||
- "proposal risk section"
|
||||
|
||||
model_overrides: {}
|
||||
# Code domain uses default archetype model assignments
|
||||
```
|
||||
|
||||
### Research Domain (Example Extension)
|
||||
|
||||
```yaml
|
||||
# .archeflow/domains/research.yaml
|
||||
name: research
|
||||
description: "Academic or technical research — papers, analysis, literature review"
|
||||
|
||||
concepts:
|
||||
implementation: "draft/analysis"
|
||||
tests: "citation verification"
|
||||
files_changed: "section count"
|
||||
test_coverage: "source coverage"
|
||||
code_review: "peer review"
|
||||
build: "compile (LaTeX/PDF)"
|
||||
deploy: "submit/publish"
|
||||
|
||||
metrics:
|
||||
- word_count
|
||||
- citation_count
|
||||
- source_diversity
|
||||
- claim_count
|
||||
- unsupported_claims
|
||||
|
||||
review_focus:
|
||||
guardian:
|
||||
- factual_accuracy
|
||||
- citation_validity
|
||||
- logical_coherence
|
||||
- methodology_soundness
|
||||
sage:
|
||||
- argument_structure
|
||||
- prose_clarity
|
||||
- academic_tone
|
||||
- completeness
|
||||
|
||||
context:
|
||||
always:
|
||||
- "bibliography/references"
|
||||
- "research brief"
|
||||
plan_phase:
|
||||
- "prior literature notes"
|
||||
- "methodology constraints"
|
||||
check_phase:
|
||||
- "citation database"
|
||||
- "claims vs. evidence mapping"
|
||||
|
||||
model_overrides:
|
||||
maker: sonnet # Research writing needs quality
|
||||
```
|
||||
| Phase | Code | Writing |
|
||||
|-------|------|---------|
|
||||
| always | README.md, config.yaml | voice profile, persona, characters |
|
||||
| plan | relevant source files, existing tests | series config, previous stories, brief |
|
||||
| do | Creator's proposal, test fixtures | scene outline, voice profile |
|
||||
| check | git diff, risk section | voice profile (Sage), outline (Guardian), characters |
|
||||
|
||||
## Domain Detection
|
||||
|
||||
ArcheFlow auto-detects the domain based on project markers. Detection runs once at `run.start` and the result is stored in the run's event stream.
|
||||
Auto-detects at `run.start`. Result stored in event stream.
|
||||
|
||||
### Detection Priority (highest first)
|
||||
|
||||
| Priority | Signal | Domain | Rationale |
|
||||
|----------|--------|--------|-----------|
|
||||
| 1 | CLI flag `--domain <name>` | as specified | Explicit override always wins |
|
||||
| 2 | Team preset has `domain: <name>` | as specified | Preset knows its domain |
|
||||
| 3 | `colette.yaml` exists in project root | `writing` | Colette is the writing platform |
|
||||
| 4 | `*.bib` or `references/` exists | `research` | Bibliography signals research |
|
||||
| 5 | `package.json` exists | `code` | Node.js project |
|
||||
| 6 | `Cargo.toml` exists | `code` | Rust project |
|
||||
| 7 | `pyproject.toml` exists | `code` | Python project |
|
||||
| 8 | `go.mod` exists | `code` | Go project |
|
||||
| 9 | `Makefile` or `CMakeLists.txt` exists | `code` | C/C++ project |
|
||||
| 10 | No markers found | `code` | Default fallback |
|
||||
|
||||
### Detection in Team Presets
|
||||
|
||||
Team presets can declare their domain explicitly:
|
||||
|
||||
```yaml
|
||||
# .archeflow/teams/story-development.yaml
|
||||
name: story-development
|
||||
domain: writing # <-- explicit domain
|
||||
description: "Kurzgeschichten-Entwicklung"
|
||||
plan: [story-explorer, creator]
|
||||
do: [maker]
|
||||
check: [guardian, story-sage]
|
||||
```
|
||||
|
||||
When `domain` is set in the preset, detection is skipped entirely.
|
||||
|
||||
### Detection Event
|
||||
|
||||
Domain detection emits a decision event:
|
||||
|
||||
```jsonl
|
||||
{"ts":"...","run_id":"...","seq":1,"parent":[],"type":"decision","phase":"init","agent":null,"data":{"what":"domain_detection","chosen":"writing","signal":"colette.yaml exists","alternatives":[{"id":"code","reason_rejected":"No code project markers found"}]}}
|
||||
```
|
||||
|
||||
## How Domains Affect Orchestration
|
||||
|
||||
### 1. Concept Translation in Reports
|
||||
|
||||
The orchestration report and session log use domain-translated terms:
|
||||
|
||||
```markdown
|
||||
# Code domain report
|
||||
- **Files changed:** 4 files, +120 -30 lines
|
||||
- **Tests added:** 8 new tests
|
||||
|
||||
# Writing domain report (same data, different framing)
|
||||
- **Word count delta:** +6004 words across 7 scenes
|
||||
- **Consistency checks:** voice drift 0.12, 2 continuity fixes applied
|
||||
```
|
||||
|
||||
### 2. Domain-Specific Event Data
|
||||
|
||||
Events include domain-relevant metrics in their `data` payload:
|
||||
|
||||
```jsonl
|
||||
// Writing domain — agent.complete
|
||||
{"type":"agent.complete","data":{"archetype":"maker","duration_ms":180000,"word_count":6004,"voice_drift":0.12,"scenes":7,"dialogue_ratio":0.35,"essen_count":4}}
|
||||
|
||||
// Code domain — agent.complete
|
||||
{"type":"agent.complete","data":{"archetype":"maker","duration_ms":90000,"files_changed":5,"tests_added":12,"coverage_delta":"+3%","lines_added":245,"lines_removed":80}}
|
||||
|
||||
// Writing domain — run.complete
|
||||
{"type":"run.complete","data":{"status":"completed","word_count":6004,"voice_drift_final":0.08,"scenes":7,"dialect_density":0.15,"cycles":1}}
|
||||
|
||||
// Code domain — run.complete
|
||||
{"type":"run.complete","data":{"status":"completed","files_changed":4,"tests_total":20,"coverage":"87%","cycles":2}}
|
||||
```
|
||||
|
||||
### 3. Review Focus Override
|
||||
|
||||
When a domain defines `review_focus`, reviewers receive domain-specific instructions instead of the defaults:
|
||||
|
||||
```
|
||||
# Without domain adapter (code defaults):
|
||||
Guardian → "Check for security vulnerabilities, breaking changes..."
|
||||
|
||||
# With writing domain adapter:
|
||||
Guardian → "Check for plot coherence, character consistency, timeline accuracy, continuity..."
|
||||
```
|
||||
|
||||
The orchestration skill reads the domain's `review_focus` and injects it into the reviewer prompt. The archetype's base personality (virtue, shadow, lens) stays the same — only the checklist changes.
|
||||
|
||||
### 4. Context Injection
|
||||
|
||||
The domain's `context` config tells the orchestrator which additional files to pass to each agent:
|
||||
|
||||
```
|
||||
# Plan phase in writing domain:
|
||||
# Orchestrator automatically includes voice profile, persona, character sheets, series config
|
||||
# alongside the standard task description and Explorer output
|
||||
|
||||
# Check phase in writing domain:
|
||||
# Guardian gets the outline (for coherence)
|
||||
# Sage gets the voice profile (for drift scoring)
|
||||
```
|
||||
|
||||
Context injection is additive — domain context is added on top of ArcheFlow's standard context rules (task description, prior phase output, etc.).
|
||||
|
||||
### 5. Model Overrides
|
||||
|
||||
If the domain specifies `model_overrides`, those override the default model assignment for the listed archetypes:
|
||||
|
||||
```
|
||||
# Default: Maker uses whatever the workflow assigns (often haiku for cheap tasks)
|
||||
# Writing domain: Maker uses sonnet (prose quality matters)
|
||||
# Research domain: Maker uses sonnet (analysis quality matters)
|
||||
```
|
||||
|
||||
Model overrides interact with cost tracking — the cost-tracking skill reads the effective model assignment (after domain overrides) for its estimates.
|
||||
| Priority | Signal | Domain |
|
||||
|----------|--------|--------|
|
||||
| 1 | CLI `--domain <name>` | as specified |
|
||||
| 2 | Team preset `domain:` field | as specified |
|
||||
| 3 | `colette.yaml` exists | writing |
|
||||
| 4 | `*.bib` or `references/` exists | research |
|
||||
| 5 | `package.json`, `Cargo.toml`, `pyproject.toml`, `go.mod`, `Makefile` | code |
|
||||
| 6 | No markers | code (default) |
|
||||
|
||||
## Adding a New Domain
|
||||
|
||||
1. Create `.archeflow/domains/<name>.yaml` following the schema above
|
||||
2. Add detection signals to the priority table (or rely on `--domain` / team preset)
|
||||
3. Define custom archetypes if needed (e.g., `story-explorer` for writing)
|
||||
4. Test with `--domain <name> --dry-run` to verify detection and context injection
|
||||
1. Create `.archeflow/domains/<name>.yaml` with `name`, `concepts`, `metrics` (minimum required)
|
||||
2. Optionally add `review_focus`, `context`, `model_overrides`
|
||||
3. Missing sections fall back to `code` domain defaults
|
||||
4. Test with `--domain <name> --dry-run`
|
||||
|
||||
### Minimum Viable Domain
|
||||
## How Domains Affect Orchestration
|
||||
|
||||
Only `name`, `concepts`, and `metrics` are required. Everything else has sensible defaults:
|
||||
|
||||
```yaml
|
||||
name: legal
|
||||
description: "Legal document drafting and review"
|
||||
|
||||
concepts:
|
||||
implementation: "draft"
|
||||
tests: "compliance checks"
|
||||
code_review: "legal review"
|
||||
|
||||
metrics:
|
||||
- clause_count
|
||||
- citation_count
|
||||
- compliance_score
|
||||
```
|
||||
|
||||
Missing sections fall back to the `code` domain defaults.
|
||||
|
||||
## Integration with Other Skills
|
||||
|
||||
- **`orchestration`**: Reads domain config at `run.start`, applies concept translation, context injection, model overrides, and review focus throughout the run
|
||||
- **`process-log`**: Domain-specific event data fields are included in `agent.complete` and `run.complete` payloads
|
||||
- **`cost-tracking`**: Reads `model_overrides` from the active domain to calculate accurate cost estimates
|
||||
- **`custom-archetypes`**: Domain-specific archetypes (e.g., `story-explorer`, `story-sage`) are defined per-project and referenced in team presets
|
||||
- **`workflow-design`**: Custom workflows can reference a domain explicitly
|
||||
|
||||
## Design Principles
|
||||
|
||||
1. **Additive, not replacing.** Domains add context and translate terms. They do not change the PDCA cycle, archetype system, or event schema.
|
||||
2. **Graceful degradation.** If no domain config exists, everything works as before (code domain defaults).
|
||||
3. **One domain per run.** A run operates in exactly one domain. Multi-domain projects use separate runs.
|
||||
4. **Domain config is data, not code.** YAML files, no scripts. Portable across projects.
|
||||
- **Reports** use domain-translated terms (e.g., "word count delta" instead of "files changed")
|
||||
- **Events** include domain-relevant metrics in `agent.complete` and `run.complete` payloads
|
||||
- **Reviewers** receive domain-specific focus checklists (archetype personality stays the same)
|
||||
- **Context injection** adds domain-declared files to each agent's prompt
|
||||
- **Model overrides** change which model an archetype uses (interacts with cost-tracking)
|
||||
- **One domain per run.** Multi-domain projects use separate runs.
|
||||
|
||||
@@ -6,263 +6,86 @@ description: |
|
||||
Enables rollback to any phase boundary and full audit trail via git history.
|
||||
<example>Automatically loaded by archeflow:run when git.enabled is true</example>
|
||||
<example>User: "archeflow rollback --to plan"</example>
|
||||
<example>User: "Show me the git history for this run"</example>
|
||||
---
|
||||
|
||||
# Git Integration — Per-Phase Commit Strategy
|
||||
# Git Integration -- Per-Phase Commit Strategy
|
||||
|
||||
Every ArcheFlow run creates a dedicated branch. Each phase transition and agent completion produces a commit. At run completion, the branch is merged back to the base branch. On failure, the branch stays intact for inspection or rollback.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- `archeflow:orchestration` — workflow rules and safety constraints
|
||||
- `archeflow:process-log` — event schema (git events are emitted alongside process events)
|
||||
- `archeflow:artifact-routing` — artifact paths that get committed
|
||||
|
||||
## Helper Script
|
||||
|
||||
All git operations go through the helper script:
|
||||
|
||||
```bash
|
||||
./lib/archeflow-git.sh <command> <run_id> [args...]
|
||||
```
|
||||
|
||||
See `lib/archeflow-git.sh` for full usage. The skill describes *when* to call the script; the script handles *how*.
|
||||
|
||||
---
|
||||
Every run creates branch `archeflow/<run_id>`. Each phase transition and agent completion produces a commit. On success, merge back. On failure, branch stays for inspection.
|
||||
|
||||
## Branch Strategy
|
||||
|
||||
```
|
||||
main (or current base branch)
|
||||
└── archeflow/<run_id> # Created at run.start
|
||||
├── commit: "archeflow(plan): explorer research"
|
||||
├── commit: "archeflow(plan): creator outline"
|
||||
├── commit: "archeflow(plan→do): phase transition"
|
||||
├── commit: "archeflow(do): maker draft"
|
||||
├── commit: "archeflow(do→check): phase transition"
|
||||
├── commit: "archeflow(check): guardian review"
|
||||
├── commit: "archeflow(check): sage review"
|
||||
├── commit: "archeflow(check→act): phase transition"
|
||||
├── commit: "archeflow(act): apply 6 fixes"
|
||||
├── commit: "archeflow(act): cycle 1 complete"
|
||||
└── commit: "archeflow(run): complete — <summary>"
|
||||
main
|
||||
+-- archeflow/<run_id>
|
||||
+-- archeflow(plan): explorer research
|
||||
+-- archeflow(plan): creator outline
|
||||
+-- archeflow(plan->do): phase transition
|
||||
+-- archeflow(do): maker draft
|
||||
+-- archeflow(check): guardian review
|
||||
+-- archeflow(act): cycle 1 complete
|
||||
+-- archeflow(run): complete
|
||||
```
|
||||
|
||||
Branch naming: `archeflow/<run_id>` (e.g., `archeflow/2026-04-03-jwt-auth`).
|
||||
|
||||
---
|
||||
|
||||
## Commit Points
|
||||
|
||||
| Trigger | What to commit | Message format |
|
||||
|---------|---------------|----------------|
|
||||
| After `agent.complete` | Agent artifacts + any created/modified files | `archeflow(<phase>): <archetype> <summary>` |
|
||||
| After `phase.transition` | All artifacts from completed phase | `archeflow(<from>→<to>): phase transition` |
|
||||
| After each `fix.applied` | The fixed file | `archeflow(fix): <source> — <finding summary>` |
|
||||
| After `cycle.boundary` | Everything staged | `archeflow(act): cycle <N> <status>` |
|
||||
| After `run.complete` | Final state + process report | `archeflow(run): complete — <summary>` |
|
||||
|
||||
---
|
||||
| Trigger | Message format |
|
||||
|---------|----------------|
|
||||
| `agent.complete` | `archeflow(<phase>): <archetype> <summary>` |
|
||||
| `phase.transition` | `archeflow(<from>-><to>): phase transition` |
|
||||
| `fix.applied` | `archeflow(fix): <source> -- <finding>` |
|
||||
| `cycle.boundary` | `archeflow(act): cycle <N> <status>` |
|
||||
| `run.complete` | `archeflow(run): complete -- <summary>` |
|
||||
|
||||
## Commit Protocol
|
||||
|
||||
1. **Stage only relevant files.** Never `git add -A`. Stage:
|
||||
- `.archeflow/artifacts/<run_id>/` — artifacts produced by the current agent/phase
|
||||
- `.archeflow/events/<run_id>.jsonl` — updated event log
|
||||
- Any project files created or modified by the current agent (from `do-maker-files.txt` or explicit file list)
|
||||
2. **Exclude ephemeral files.** Never commit:
|
||||
- `.archeflow/progress.md` (live progress display, ephemeral)
|
||||
- `.archeflow/explorer-cache/` (local cache, not run-specific)
|
||||
- `.archeflow/session-log.md` (separate concern)
|
||||
3. **Use conventional commit format:** `archeflow(<scope>): <message>`
|
||||
4. **Signing:** If `git.signing_key` is configured, pass `-c user.signingkey=<key>` to `git commit`.
|
||||
- Stage only relevant files: `.archeflow/artifacts/<run_id>/`, event log, project files from maker
|
||||
- Never `git add -A`
|
||||
- Exclude: `progress.md`, `explorer-cache/`, `session-log.md`
|
||||
- Use conventional commit format
|
||||
- Signing opt-in via `git.signing_key` config
|
||||
|
||||
### Integration with the Run Skill
|
||||
## All operations go through `./lib/archeflow-git.sh`:
|
||||
|
||||
The `archeflow:run` skill calls git operations at these points:
|
||||
| Run event | Command |
|
||||
|-----------|---------|
|
||||
| `run.start` | `init <run_id>` (create+switch branch) |
|
||||
| `agent.complete` | `commit <run_id> <phase> "<msg>" [files]` |
|
||||
| `phase.transition` | `phase-commit <run_id> <phase>` |
|
||||
| `run.complete` (ok) | `merge <run_id> [--squash|--no-ff]` |
|
||||
| `run.complete` (fail) | branch preserved |
|
||||
|
||||
```
|
||||
run.start → ./lib/archeflow-git.sh init <run_id>
|
||||
agent.complete → ./lib/archeflow-git.sh commit <run_id> <phase> "<archetype> <summary>" [files...]
|
||||
phase.transition → ./lib/archeflow-git.sh phase-commit <run_id> <phase>
|
||||
fix.applied → ./lib/archeflow-git.sh commit <run_id> fix "<source> — <finding>"
|
||||
cycle.boundary → ./lib/archeflow-git.sh commit <run_id> act "cycle <N> <status>"
|
||||
run.complete (ok) → ./lib/archeflow-git.sh merge <run_id> [--squash|--no-ff]
|
||||
run.complete (fail) → branch preserved, not merged
|
||||
```
|
||||
## Merge
|
||||
|
||||
---
|
||||
|
||||
## Run Lifecycle
|
||||
|
||||
### 1. Initialization (`run.start`)
|
||||
|
||||
```bash
|
||||
./lib/archeflow-git.sh init <run_id>
|
||||
```
|
||||
|
||||
This will:
|
||||
1. Verify a clean working tree (or stash uncommitted changes)
|
||||
2. Create branch `archeflow/<run_id>` from current HEAD
|
||||
3. Switch to the new branch
|
||||
|
||||
### 2. During Execution (phase commits)
|
||||
|
||||
After each agent completes or phase transitions, the run skill calls:
|
||||
|
||||
```bash
|
||||
# After an agent completes:
|
||||
./lib/archeflow-git.sh commit <run_id> plan "explorer research" \
|
||||
.archeflow/artifacts/<run_id>/plan-explorer.md
|
||||
|
||||
# After a phase transition:
|
||||
./lib/archeflow-git.sh phase-commit <run_id> plan
|
||||
```
|
||||
|
||||
The `commit` command stages artifact directories and event logs automatically. Additional files can be passed as trailing arguments.
|
||||
|
||||
The `phase-commit` command stages all artifacts matching the phase prefix and commits with a transition message.
|
||||
|
||||
### 3. Completion (merge)
|
||||
|
||||
```bash
|
||||
# Success — squash merge (default):
|
||||
./lib/archeflow-git.sh merge <run_id> --squash
|
||||
|
||||
# Success — preserve history:
|
||||
./lib/archeflow-git.sh merge <run_id> --no-ff
|
||||
|
||||
# Failure or user abort:
|
||||
# Do nothing. Branch stays for inspection.
|
||||
echo "Branch archeflow/<run_id> preserved for inspection."
|
||||
```
|
||||
|
||||
The merge command:
|
||||
1. Verifies all changes on the branch are committed
|
||||
2. Switches to the base branch (main or wherever the run started)
|
||||
3. Merges with the chosen strategy
|
||||
4. If squash: creates a single commit with `feat: <task summary>`
|
||||
5. Does NOT delete the branch (user may want to inspect)
|
||||
|
||||
### 4. Cleanup (optional, after inspection)
|
||||
|
||||
```bash
|
||||
./lib/archeflow-git.sh cleanup <run_id>
|
||||
```
|
||||
|
||||
Deletes the branch after the user has confirmed the merge is correct.
|
||||
|
||||
---
|
||||
1. Verify all changes committed
|
||||
2. Switch to base branch
|
||||
3. Merge with configured strategy (squash default)
|
||||
4. Branch NOT auto-deleted (user may inspect)
|
||||
|
||||
## Rollback
|
||||
|
||||
Roll back to the end of any completed phase:
|
||||
`./lib/archeflow-git.sh rollback <run_id> --to <target>`
|
||||
|
||||
```bash
|
||||
./lib/archeflow-git.sh rollback <run_id> --to plan
|
||||
```
|
||||
Targets: `plan`, `do`, `check`, `act`, `cycle-N`. Only works on `archeflow/<run_id>` branch. Resets to last commit for target phase and trims event JSONL.
|
||||
|
||||
This will:
|
||||
1. Find the last commit for the target phase by searching commit messages
|
||||
2. Show the user what commits will be lost (everything after the target)
|
||||
3. Perform `git reset --hard <commit>` on the branch
|
||||
4. Trim the events JSONL to remove events that occurred after the rollback point
|
||||
## Post-Merge Validation
|
||||
|
||||
**Supported rollback targets:** `plan`, `do`, `check`, `act`, or any cycle number (`cycle-1`, `cycle-2`).
|
||||
|
||||
**Safety:** Rollback only works on the run's branch, never on main. The script verifies you are on `archeflow/<run_id>` before proceeding.
|
||||
|
||||
---
|
||||
|
||||
## Status
|
||||
|
||||
View the git state of a run:
|
||||
|
||||
```bash
|
||||
./lib/archeflow-git.sh status <run_id>
|
||||
```
|
||||
|
||||
Output:
|
||||
```
|
||||
Branch: archeflow/2026-04-03-jwt-auth
|
||||
Base: main (3 commits ahead)
|
||||
|
||||
Commits:
|
||||
abc1234 archeflow(plan): explorer research
|
||||
def5678 archeflow(plan): creator outline
|
||||
ghi9012 archeflow(plan→do): phase transition
|
||||
jkl3456 archeflow(do): maker implementation
|
||||
|
||||
Current phase: do
|
||||
Files changed (total): 8
|
||||
Uncommitted changes: none
|
||||
```
|
||||
|
||||
---
|
||||
After merge, runs project test suite (from `test_command` in config) with 5-min timeout. If tests fail: `git revert --no-edit HEAD`.
|
||||
|
||||
## Configuration
|
||||
|
||||
In `.archeflow/config.yaml` or a team preset:
|
||||
|
||||
```yaml
|
||||
git:
|
||||
enabled: true # Default: true. Set false to disable all git operations.
|
||||
branch_prefix: "archeflow/" # Default. The run_id is appended.
|
||||
commit_style: conventional # conventional (archeflow(<scope>): msg) | simple (<phase>: msg)
|
||||
merge_strategy: squash # squash | no-ff | rebase
|
||||
auto_push: false # Push branch to remote after each commit
|
||||
signing_key: null # SSH key path for signed commits (e.g., ~/.ssh/id_ed25519.pub)
|
||||
enabled: true
|
||||
branch_prefix: "archeflow/"
|
||||
merge_strategy: squash # squash | no-ff | rebase
|
||||
auto_push: false
|
||||
signing_key: null
|
||||
```
|
||||
|
||||
The helper script reads this config if it exists. All values have sensible defaults.
|
||||
|
||||
---
|
||||
|
||||
## Post-Merge Rollback
|
||||
|
||||
After merging, the run skill validates the merge by running the project's test suite. If tests fail, the merge is automatically reverted.
|
||||
|
||||
### Script
|
||||
|
||||
```bash
|
||||
./lib/archeflow-rollback.sh <run_id> [--test-cmd <cmd>]
|
||||
```
|
||||
|
||||
**Behavior:**
|
||||
1. Reads `test_command` from `.archeflow/config.yaml` (or uses `--test-cmd` override)
|
||||
2. Runs the test suite with a 5-minute timeout
|
||||
3. If tests pass: exits 0 (merge is good)
|
||||
4. If tests fail: runs `git revert --no-edit HEAD`, emits a `decision` event, exits 1
|
||||
5. Verifies HEAD is an ArcheFlow merge commit before reverting (warning if not, proceeds anyway)
|
||||
|
||||
**Integration with run skill:** Called in section 4c (All Approved) after `archeflow-git.sh merge`. If it returns non-zero, the orchestrator cycles back with "integration test failure" feedback or reports to the user if max cycles are reached.
|
||||
|
||||
**Configuration:** Set `test_command` in `.archeflow/config.yaml`:
|
||||
```yaml
|
||||
test_command: "npm test" # or "pytest", "cargo test", etc.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Safety Rules
|
||||
|
||||
These rules are inherited from `archeflow:orchestration` and reinforced here:
|
||||
|
||||
1. **Never force-push.** No `--force`, no `--force-with-lease`. If a push fails, diagnose and fix.
|
||||
2. **Never modify main history.** Merges are forward-only. No rebasing main.
|
||||
3. **Branch stays intact on failure.** If a run fails or is aborted, the branch is preserved for inspection. Never auto-delete failed branches.
|
||||
4. **All commits are individually revertable.** Each commit represents a discrete unit of work.
|
||||
5. **Worktree mode compatibility.** If the Maker runs in a worktree, git-integration commits go to the worktree's branch. The merge happens at the run level, not the worktree level. The Maker's worktree branch is a sub-branch of `archeflow/<run_id>`.
|
||||
6. **Clean merge or abort.** If a merge produces conflicts, do not force-resolve. Report the conflict, leave the branch intact, and let the user decide.
|
||||
7. **No signing by default.** Signing is opt-in via config. If configured, all commits on the branch are signed.
|
||||
|
||||
---
|
||||
|
||||
## Design Principles
|
||||
|
||||
1. **Git is the audit trail.** Every phase transition is a commit. `git log` tells the full story of a run.
|
||||
2. **Rollback is cheap.** Reset to any phase boundary, re-run from there. No need to start over.
|
||||
3. **Merge strategy is a project decision.** Squash for clean history, no-ff for detailed history. Both are valid.
|
||||
4. **Events + git = full observability.** Process events capture *what happened* (decisions, verdicts, timing). Git captures *what changed* (files, diffs). Together they provide complete run archaeology.
|
||||
5. **Fail-safe by default.** Every safety rule defaults to the conservative option. The user must explicitly opt in to destructive operations.
|
||||
- Never force-push
|
||||
- Never modify main history
|
||||
- Branch stays intact on failure
|
||||
- Clean merge or abort (no force-resolve on conflicts)
|
||||
- Worktree-compatible (Maker's worktree branch is sub-branch of run branch)
|
||||
|
||||
@@ -6,624 +6,138 @@ description: |
|
||||
and enforces a shared budget. Each sub-run uses the standard `run` skill internally.
|
||||
<example>User: "archeflow:multi-project" with a multi-run.yaml</example>
|
||||
<example>User: "Run this across archeflow, colette, and giesing"</example>
|
||||
<example>User: "archeflow:multi-project --dry-run"</example>
|
||||
---
|
||||
|
||||
# Multi-Project Orchestration
|
||||
|
||||
Coordinates ArcheFlow runs across multiple projects in a workspace. Each project gets its own
|
||||
PDCA run (via the standard `run` skill), but dependencies between projects are respected, artifacts
|
||||
are shared, and budget is tracked globally.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Load these skills (they are referenced throughout):
|
||||
- `archeflow:run` — single-project PDCA execution loop
|
||||
- `archeflow:process-log` — event schema and DAG parent rules
|
||||
- `archeflow:artifact-routing` — artifact naming, context injection, cycle archiving
|
||||
- `archeflow:cost-tracking` — cost aggregation and budget enforcement
|
||||
- `archeflow:domains` — domain detection per project
|
||||
|
||||
## Invocation
|
||||
|
||||
```
|
||||
archeflow:multi-project # Read from .archeflow/multi-run.yaml
|
||||
archeflow:multi-project --config path/to.yaml # Explicit config file
|
||||
archeflow:multi-project --dry-run # Plan phase only for all projects, show cost estimate
|
||||
archeflow:multi-project --resume <multi-run-id> # Resume a failed/paused multi-run
|
||||
```
|
||||
|
||||
---
|
||||
Coordinates ArcheFlow runs across multiple projects. Each project gets its own PDCA run (via `run` skill), but dependencies are respected, artifacts shared, and budget tracked globally.
|
||||
|
||||
## Multi-Run Definition
|
||||
|
||||
A multi-run is defined in YAML, either in `.archeflow/multi-run.yaml` or passed via `--config`.
|
||||
Defined in `.archeflow/multi-run.yaml` or passed via `--config`.
|
||||
|
||||
```yaml
|
||||
name: "giesing-gschichten-v2"
|
||||
description: "Write second story with improved ArcheFlow + Colette integration"
|
||||
|
||||
projects:
|
||||
- id: archeflow
|
||||
path: "../archeflow" # Relative to workspace root, or absolute
|
||||
path: "../archeflow"
|
||||
task: "Add memory injection to run skill"
|
||||
workflow: fast # fast | standard | thorough (optional, auto-select if omitted)
|
||||
domain: code # Optional, auto-detected if omitted
|
||||
depends_on: [] # No dependencies — can start immediately
|
||||
|
||||
workflow: fast
|
||||
depends_on: []
|
||||
- id: colette
|
||||
path: "../writing.colette"
|
||||
task: "Add story-specific voice validation command"
|
||||
workflow: standard
|
||||
domain: code
|
||||
depends_on: [] # Independent of archeflow — runs in parallel
|
||||
|
||||
task: "Add voice validation command"
|
||||
depends_on: []
|
||||
- id: giesing
|
||||
path: "."
|
||||
task: "Write story #2 using improved tools"
|
||||
task: "Write story #2"
|
||||
workflow: kurzgeschichte
|
||||
domain: writing
|
||||
depends_on: [archeflow, colette] # Waits for both to complete
|
||||
|
||||
depends_on: [archeflow, colette]
|
||||
budget:
|
||||
total_usd: 15.00 # Hard cap — stops all projects when exceeded
|
||||
per_project_usd: 10.00 # Soft cap — warns but does not stop
|
||||
|
||||
parallel: true # Run independent projects concurrently (default: true)
|
||||
total_usd: 15.00
|
||||
per_project_usd: 10.00
|
||||
```
|
||||
|
||||
### Definition Rules
|
||||
**Rules:** Unique `id` per project. `depends_on` references other `id` values. Cycles rejected at validation. At least one project must have empty `depends_on`. `workflow` and `domain` auto-select if omitted.
|
||||
|
||||
- `id` must be unique within the multi-run.
|
||||
- `path` is resolved relative to the directory containing the YAML file unless absolute.
|
||||
- `depends_on` references other project `id` values. Cycles are rejected at validation time.
|
||||
- `workflow` and `domain` are optional. If omitted, the `run` skill auto-selects per project.
|
||||
- At least one project must have an empty `depends_on` (otherwise the DAG has no entry point).
|
||||
## Dependency Resolution
|
||||
|
||||
---
|
||||
|
||||
## Workspace Registry Integration
|
||||
|
||||
If `docs/project-registry.md` exists at the workspace root, the multi-project skill can:
|
||||
|
||||
1. **Auto-discover paths:** When `path` is omitted from a project entry, look up the project `id` in the registry to find its directory.
|
||||
2. **Validate existence:** Before starting, verify that every project path exists on disk. Abort with a clear error if a path is missing.
|
||||
3. **Show registry status:** In the progress table, include the project's current sprint goal from the registry alongside the multi-run status.
|
||||
4. **Update registry:** After the multi-run completes, update each project's status in the registry if meaningful changes were made (new features, completed sprint goals).
|
||||
|
||||
---
|
||||
|
||||
## Execution Steps
|
||||
|
||||
### 0. Validate and Initialize
|
||||
|
||||
**0a. Parse and validate the multi-run definition:**
|
||||
Topological sort of the project DAG determines execution order.
|
||||
|
||||
```
|
||||
1. Read the YAML file.
|
||||
2. Validate all required fields (name, projects with id/path/task).
|
||||
3. Resolve all paths to absolute paths.
|
||||
4. Verify each path exists on disk.
|
||||
5. Build the dependency DAG.
|
||||
6. Check for cycles — abort if any detected.
|
||||
7. Identify the entry-point projects (depends_on is empty).
|
||||
8. Verify at least one entry-point exists.
|
||||
Layer 0 (immediate): [archeflow, colette] # No deps, start now
|
||||
Layer 1: [giesing] # Depends on Layer 0
|
||||
```
|
||||
|
||||
**0b. Generate multi-run ID and directory structure:**
|
||||
Independent projects in the same layer run in parallel. When a project completes, downstream projects with all deps met move to the ready queue.
|
||||
|
||||
```bash
|
||||
MULTI_RUN_ID="$(date -u +%Y-%m-%d)-${name}"
|
||||
Cycle detection via Kahn's algorithm. If sorted list is shorter than project list, report the cycle and abort.
|
||||
|
||||
# Master event file
|
||||
mkdir -p .archeflow/events
|
||||
touch .archeflow/events/${MULTI_RUN_ID}.jsonl
|
||||
## Parallel Execution
|
||||
|
||||
# Cross-project artifact directory
|
||||
mkdir -p .archeflow/artifacts/${MULTI_RUN_ID}
|
||||
for project in ${PROJECT_IDS}; do
|
||||
mkdir -p .archeflow/artifacts/${MULTI_RUN_ID}/${project}
|
||||
done
|
||||
For each ready project, start a sub-run as a parallel subagent with `isolation: "worktree"`. Each sub-run invokes `archeflow:run` with its own run_id, workflow, domain, and budget slice.
|
||||
|
||||
# Progress file
|
||||
touch .archeflow/multi-progress.md
|
||||
```
|
||||
When `parallel: false`, run sequentially in topological order.
|
||||
|
||||
**0c. Emit `multi.start`:**
|
||||
## Cross-Project Artifacts
|
||||
|
||||
```jsonl
|
||||
{"ts":"...","run_id":"<MULTI_RUN_ID>","seq":1,"parent":[],"type":"multi.start","phase":"init","agent":null,"data":{"name":"giesing-v2","description":"...","projects":["archeflow","colette","giesing"],"parallel":true,"budget_total_usd":15.00,"dag":{"archeflow":[],"colette":[],"giesing":["archeflow","colette"]}}}
|
||||
```
|
||||
When project B depends on A, B's Explorer receives upstream artifact summaries:
|
||||
- Only summaries injected (not full artifacts)
|
||||
- Large artifacts (>200 lines): extract summary section only
|
||||
- Cross-project injection happens only in Plan phase
|
||||
- Downstream Explorer has filesystem access to full artifacts if needed
|
||||
|
||||
**Track state throughout the multi-run:**
|
||||
- `MULTI_RUN_ID` — unique multi-run identifier
|
||||
- `MULTI_SEQ` — master event sequence counter
|
||||
- `PROJECT_STATUS` — map of project_id to status (`pending | running | completed | failed | blocked | skipped`)
|
||||
- `PROJECT_RUN_IDS` — map of project_id to its sub-run_id
|
||||
- `TOTAL_COST` — running cost total across all projects
|
||||
- `REMAINING_BUDGET` — budget minus total cost
|
||||
Artifact directory: `.archeflow/artifacts/<MULTI_RUN_ID>/<project_id>/`
|
||||
|
||||
---
|
||||
## Budget Coordination
|
||||
|
||||
### 1. Dependency Resolution
|
||||
|
||||
Build a topological sort of the project DAG. This determines execution order.
|
||||
|
||||
```
|
||||
Given:
|
||||
archeflow: depends_on=[]
|
||||
colette: depends_on=[]
|
||||
giesing: depends_on=[archeflow, colette]
|
||||
|
||||
Topological layers:
|
||||
Layer 0 (immediate): [archeflow, colette] # No deps, start now
|
||||
Layer 1: [giesing] # Depends on Layer 0
|
||||
```
|
||||
|
||||
**Algorithm:**
|
||||
1. Find all projects with zero unmet dependencies. These form the current layer.
|
||||
2. When a project completes, remove it from the dependency lists of all downstream projects.
|
||||
3. Any project whose dependency list becomes empty moves to the ready queue.
|
||||
4. Repeat until all projects are complete, failed, or blocked.
|
||||
|
||||
**Cycle detection:** Before starting, verify the DAG is acyclic. Use Kahn's algorithm — if after processing all nodes the sorted list is shorter than the project list, there is a cycle. Report which projects form the cycle and abort.
|
||||
|
||||
---
|
||||
|
||||
### 2. Parallel Execution
|
||||
|
||||
For each project in the ready queue, start a sub-run. Independent projects run concurrently.
|
||||
|
||||
**Starting a sub-run:**
|
||||
|
||||
```
|
||||
For each ready project:
|
||||
1. Set PROJECT_STATUS[project_id] = "running"
|
||||
2. Generate sub-run ID: MULTI_RUN_ID/project_id
|
||||
(e.g., "2026-04-03-giesing-v2/archeflow")
|
||||
3. Emit project.start to master event file
|
||||
4. cd into the project's path
|
||||
5. Invoke archeflow:run with:
|
||||
- run_id = MULTI_RUN_ID/project_id
|
||||
- workflow = project.workflow (or auto-select)
|
||||
- domain = project.domain (or auto-detect)
|
||||
- budget = min(per_project_budget, remaining_total_budget)
|
||||
- artifact_dir = .archeflow/artifacts/MULTI_RUN_ID/project_id/
|
||||
6. The sub-run emits its own events to its own JSONL file
|
||||
inside the project's directory (standard run behavior)
|
||||
```
|
||||
|
||||
**Concurrency model:**
|
||||
|
||||
When `parallel: true` (default), spawn independent projects as parallel subagents:
|
||||
|
||||
```
|
||||
Agent(
|
||||
description: "Multi-project sub-run: <project_id> — <task>",
|
||||
prompt: "Run archeflow:run in <path> with task: <task>.
|
||||
Run ID: <MULTI_RUN_ID>/<project_id>
|
||||
Workflow: <workflow>
|
||||
Domain: <domain>
|
||||
Budget: $<per_project_budget>
|
||||
Save artifacts to: .archeflow/artifacts/<MULTI_RUN_ID>/<project_id>/
|
||||
When complete, report: status, cost, artifact list, and any issues.",
|
||||
isolation: "worktree",
|
||||
mode: "bypassPermissions"
|
||||
)
|
||||
```
|
||||
|
||||
Launch all Layer 0 projects simultaneously. As each completes, check if any Layer 1+ projects become unblocked.
|
||||
|
||||
When `parallel: false`, run projects sequentially in topological order. Still respect dependencies — a project does not start until all its dependencies have completed.
|
||||
|
||||
---
|
||||
|
||||
### 3. Master Events
|
||||
|
||||
All multi-run-level events are written to `.archeflow/events/<MULTI_RUN_ID>.jsonl`. These track the overall orchestration, not individual PDCA phases (those go to each project's own event file).
|
||||
|
||||
#### Master Event Types
|
||||
|
||||
| Event | When | Key Data |
|
||||
| Level | Type | Behavior |
|
||||
|-------|------|----------|
|
||||
| `multi.start` | Multi-run begins | Project list, DAG, budget |
|
||||
| `project.start` | A sub-run launches | project_id, run_id, path |
|
||||
| `project.complete` | A sub-run finishes successfully | project_id, status, cost, artifacts |
|
||||
| `project.failed` | A sub-run fails | project_id, error, cost_so_far |
|
||||
| `project.blocked` | A dependency failed, blocking this project | project_id, blocked_by |
|
||||
| `project.unblocked` | All dependencies met, project can start | project_id, unblocked_by |
|
||||
| `project.skipped` | User chose to skip a blocked project | project_id, reason |
|
||||
| `budget.warning` | Budget threshold crossed | spent, budget, percent |
|
||||
| `budget.exceeded` | Hard budget cap hit | spent, budget, halted_projects |
|
||||
| `multi.complete` | All projects done (or halted) | status, projects_completed, total_cost |
|
||||
| `total_usd` | Hard cap | Stops ALL projects when exceeded |
|
||||
| `per_project_usd` | Soft cap | Warns but continues |
|
||||
|
||||
#### Example Master Event Stream
|
||||
**Enforcement points:**
|
||||
1. Before starting a sub-run: estimate cost, halt if > remaining budget
|
||||
2. After each sub-run: update total, emit `budget.warning` at threshold, emit `budget.exceeded` at cap
|
||||
|
||||
```jsonl
|
||||
{"seq":1,"type":"multi.start","phase":"init","data":{"name":"giesing-v2","projects":["archeflow","colette","giesing"],"parallel":true,"budget_total_usd":15.00}}
|
||||
{"seq":2,"type":"project.start","phase":"run","data":{"project":"archeflow","run_id":"2026-04-03-giesing-v2/archeflow","path":"/home/c/projects/archeflow"}}
|
||||
{"seq":3,"type":"project.start","phase":"run","data":{"project":"colette","run_id":"2026-04-03-giesing-v2/colette","path":"/home/c/projects/writing.colette"}}
|
||||
{"seq":4,"type":"project.complete","phase":"run","data":{"project":"archeflow","status":"completed","run_id":"2026-04-03-giesing-v2/archeflow","cost_usd":1.20,"artifacts":["plan-explorer.md","plan-creator.md","do-maker.md","check-guardian.md"]}}
|
||||
{"seq":5,"type":"project.complete","phase":"run","data":{"project":"colette","status":"completed","run_id":"2026-04-03-giesing-v2/colette","cost_usd":1.80,"artifacts":["plan-creator.md","do-maker.md","check-guardian.md","check-sage.md"]}}
|
||||
{"seq":6,"type":"project.unblocked","phase":"run","data":{"project":"giesing","unblocked_by":["archeflow","colette"]}}
|
||||
{"seq":7,"type":"project.start","phase":"run","data":{"project":"giesing","run_id":"2026-04-03-giesing-v2/giesing","path":"/home/c/projects/book.giesing-gschichten"}}
|
||||
{"seq":8,"type":"project.complete","phase":"run","data":{"project":"giesing","status":"completed","run_id":"2026-04-03-giesing-v2/giesing","cost_usd":3.50,"artifacts":["plan-explorer.md","plan-creator.md","do-maker.md","check-guardian.md","check-sage.md"]}}
|
||||
{"seq":9,"type":"multi.complete","phase":"done","data":{"status":"completed","projects_completed":3,"projects_failed":0,"total_cost_usd":6.50,"budget_remaining_usd":8.50}}
|
||||
```
|
||||
Each sub-run receives `min(per_project_usd, remaining_total_budget)` as its budget.
|
||||
|
||||
---
|
||||
|
||||
### 4. Cross-Project Artifacts
|
||||
|
||||
When project B depends on project A, B's agents can access A's artifacts. This is the primary mechanism for cross-project information flow.
|
||||
|
||||
#### Artifact Directory Layout
|
||||
|
||||
```
|
||||
.archeflow/artifacts/<MULTI_RUN_ID>/
|
||||
├── archeflow/ # Sub-run artifacts from archeflow
|
||||
│ ├── plan-explorer.md
|
||||
│ ├── plan-creator.md
|
||||
│ ├── do-maker.md
|
||||
│ ├── do-maker-files.txt
|
||||
│ └── check-guardian.md
|
||||
├── colette/ # Sub-run artifacts from colette
|
||||
│ ├── plan-creator.md
|
||||
│ ├── do-maker.md
|
||||
│ └── check-sage.md
|
||||
└── giesing/ # Sub-run artifacts from giesing (depends on both)
|
||||
├── plan-explorer.md # Explorer can reference upstream artifacts
|
||||
├── plan-creator.md
|
||||
├── do-maker.md
|
||||
└── check-guardian.md
|
||||
```
|
||||
|
||||
#### Cross-Project Context Injection
|
||||
|
||||
When a dependent project's sub-run starts, inject upstream artifact summaries into the Explorer's prompt:
|
||||
|
||||
```markdown
|
||||
## Upstream Project Results
|
||||
|
||||
### archeflow (completed)
|
||||
Summary: Added memory injection to run skill.
|
||||
Key artifacts:
|
||||
- plan-creator.md: <first 20 lines or summary section>
|
||||
- do-maker.md: <implementation summary>
|
||||
|
||||
### colette (completed)
|
||||
Summary: Added story-specific voice validation command.
|
||||
Key artifacts:
|
||||
- plan-creator.md: <first 20 lines or summary section>
|
||||
- do-maker.md: <implementation summary>
|
||||
|
||||
Use these results as context. The changes from these projects are available in their
|
||||
respective directories and have been committed to their branches.
|
||||
```
|
||||
|
||||
**Rules for cross-project injection:**
|
||||
- Only inject summaries, not full artifacts (keep context small).
|
||||
- If an upstream artifact is large (>200 lines), extract the summary/overview section only.
|
||||
- The dependent project's Explorer has filesystem access to read full upstream artifacts if needed.
|
||||
- Cross-project injection happens ONLY in the Plan phase (Explorer and Creator). The Maker works from the Creator's proposal, which already incorporates upstream context.
|
||||
|
||||
---
|
||||
|
||||
### 5. Budget Coordination
|
||||
|
||||
The multi-run has a shared budget across all projects.
|
||||
|
||||
#### Budget Hierarchy
|
||||
|
||||
```
|
||||
total_usd: 15.00 # Hard cap — stops ALL projects when exceeded
|
||||
per_project_usd: 10.00 # Soft cap — warns but does not stop individual project
|
||||
```
|
||||
|
||||
#### Budget Tracking
|
||||
|
||||
Maintain a running total across all sub-runs:
|
||||
|
||||
```
|
||||
TOTAL_COST = sum of all project costs reported in project.complete events
|
||||
REMAINING = total_usd - TOTAL_COST
|
||||
```
|
||||
|
||||
#### Budget Enforcement Points
|
||||
|
||||
1. **Before starting a sub-run:**
|
||||
- Estimate the sub-run cost (based on workflow and domain).
|
||||
- If estimated cost > REMAINING: warn and ask user (attended) or halt (autonomous).
|
||||
|
||||
2. **After each sub-run completes:**
|
||||
- Update TOTAL_COST with actual cost from the sub-run.
|
||||
- If TOTAL_COST > total_usd * warn_at_percent: emit `budget.warning`.
|
||||
- If TOTAL_COST > total_usd: emit `budget.exceeded`, halt remaining projects.
|
||||
|
||||
3. **Per-project soft cap:**
|
||||
- Each sub-run receives `min(per_project_usd, REMAINING)` as its budget.
|
||||
- The `run` skill's own budget enforcement handles the per-project cap.
|
||||
- If a project exceeds per_project_usd, it warns but continues (soft cap).
|
||||
|
||||
#### Budget Events
|
||||
|
||||
```jsonl
|
||||
{"seq":5,"type":"budget.warning","data":{"spent_usd":11.50,"budget_usd":15.00,"percent":77,"message":"Budget 77% consumed"}}
|
||||
{"seq":8,"type":"budget.exceeded","data":{"spent_usd":15.30,"budget_usd":15.00,"halted_projects":["giesing"],"message":"Hard budget cap exceeded. Halting remaining projects."}}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 6. Failure Handling
|
||||
|
||||
Failures in one project affect downstream projects but not independent ones.
|
||||
|
||||
#### Failure Scenarios
|
||||
## Failure Handling
|
||||
|
||||
| Scenario | Action |
|
||||
|----------|--------|
|
||||
| Project fails (run error, test failure, max cycles) | Mark as `failed` in master events. Independent projects continue. |
|
||||
| Dependency of project X failed | Mark X as `blocked`. Do not start X. |
|
||||
| Budget exceeded mid-run | Halt the current project. Mark remaining as `blocked`. |
|
||||
| All entry-point projects fail | Entire multi-run fails. No downstream projects can start. |
|
||||
| Project fails | Mark `failed`. Independent projects continue. |
|
||||
| Dependency failed | Mark downstream as `blocked`. Do not start. |
|
||||
| Budget exceeded | Halt current project. Skip downstream. |
|
||||
| All entry-points fail | Entire multi-run fails. |
|
||||
|
||||
#### Blocked Project Resolution
|
||||
**Blocked project resolution:**
|
||||
- Autonomous mode: skip blocked projects, continue independent ones
|
||||
- Attended mode: offer skip / retry / abort
|
||||
|
||||
When a project is blocked because a dependency failed, offer three options:
|
||||
## Progress Tracking
|
||||
|
||||
1. **Skip:** Mark the blocked project as `skipped`. Continue with other independent projects.
|
||||
2. **Retry:** Re-run the failed dependency. If it succeeds, unblock downstream projects.
|
||||
3. **Abort:** Stop the entire multi-run. Report what completed and what did not.
|
||||
|
||||
In **autonomous mode**, the default action is `skip` — blocked projects are skipped, independent projects continue, and the multi-run completes with partial results.
|
||||
|
||||
In **attended mode**, prompt the user with the options above.
|
||||
|
||||
#### Failure Events
|
||||
|
||||
```jsonl
|
||||
{"seq":4,"type":"project.failed","data":{"project":"archeflow","error":"Max cycles reached with unresolved CRITICAL findings","cost_usd":2.10}}
|
||||
{"seq":5,"type":"project.blocked","data":{"project":"giesing","blocked_by":["archeflow"],"reason":"Dependency 'archeflow' failed"}}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 7. Progress Tracking
|
||||
|
||||
Maintain a live progress file at `.archeflow/multi-progress.md`. Update it after every project state change.
|
||||
Live progress at `.archeflow/multi-progress.md`, updated after every project state change:
|
||||
|
||||
```markdown
|
||||
# Multi-Run: giesing-v2
|
||||
Started: 2026-04-03T14:00:00Z
|
||||
|
||||
| Project | Status | Domain | Phase | Detail |
|
||||
|---------|--------|--------|-------|--------|
|
||||
| archeflow | completed | code | -- | 1 cycle, $1.20 |
|
||||
| colette | running | code | DO | maker drafting |
|
||||
| giesing | blocked | writing | -- | waiting for colette |
|
||||
|
||||
## Budget
|
||||
| | Amount |
|
||||
|---|--------|
|
||||
| Spent | $3.00 |
|
||||
| Budget | $15.00 |
|
||||
| Remaining | $12.00 |
|
||||
| Utilization | 20% |
|
||||
|
||||
## Dependency Graph
|
||||
```
|
||||
archeflow ----\
|
||||
+---> giesing
|
||||
colette ------/
|
||||
Budget: $3.00 / $15.00 (20%)
|
||||
```
|
||||
|
||||
## Timeline
|
||||
- 14:00:00 — Started archeflow, colette (parallel)
|
||||
- 14:05:23 — archeflow completed ($1.20, 1 cycle)
|
||||
- 14:06:10 — colette DO phase, maker drafting
|
||||
```
|
||||
## Master Events
|
||||
|
||||
Update this file after:
|
||||
- A project starts
|
||||
- A project changes phase (via status polling or sub-agent reporting)
|
||||
- A project completes or fails
|
||||
- A project becomes unblocked
|
||||
- Budget threshold is crossed
|
||||
Written to `.archeflow/events/<MULTI_RUN_ID>.jsonl`:
|
||||
|
||||
---
|
||||
| Event | When |
|
||||
|-------|------|
|
||||
| `multi.start` | Multi-run begins |
|
||||
| `project.start` | Sub-run launches |
|
||||
| `project.complete` | Sub-run succeeds |
|
||||
| `project.failed` | Sub-run fails |
|
||||
| `project.blocked` | Dependency failed |
|
||||
| `project.unblocked` | All deps met |
|
||||
| `budget.warning` | Threshold crossed |
|
||||
| `budget.exceeded` | Hard cap hit |
|
||||
| `multi.complete` | All projects done |
|
||||
|
||||
### 8. Completion
|
||||
## Dry-Run and Resume
|
||||
|
||||
When all projects are complete (or blocked/skipped with no more actionable items):
|
||||
**`--dry-run`:** Validates DAG, runs `archeflow:run --dry-run` per project, shows cost estimate. Does not execute.
|
||||
|
||||
**8a. Emit `multi.complete`:**
|
||||
**`--resume <id>`:** Reconstructs state from master events. Retries failed projects, starts pending ones with deps met.
|
||||
|
||||
```jsonl
|
||||
{"seq":9,"type":"multi.complete","phase":"done","data":{"status":"completed","projects_completed":3,"projects_failed":0,"projects_skipped":0,"total_cost_usd":6.50,"budget_remaining_usd":8.50,"duration_ms":600000}}
|
||||
```
|
||||
## Workspace Registry
|
||||
|
||||
Status values:
|
||||
- `completed` — all projects finished successfully
|
||||
- `partial` — some projects completed, some failed/skipped
|
||||
- `failed` — no projects completed successfully
|
||||
- `halted` — stopped due to budget or user abort
|
||||
If `docs/project-registry.md` exists: auto-discover paths by project id, validate existence, update registry after meaningful changes.
|
||||
|
||||
**8b. Generate multi-run report:**
|
||||
## Completion
|
||||
|
||||
```markdown
|
||||
# Multi-Run Report: giesing-v2
|
||||
Status values: `completed` (all done), `partial` (some failed/skipped), `failed` (none completed), `halted` (budget/abort).
|
||||
|
||||
## Summary
|
||||
| Metric | Value |
|
||||
|--------|-------|
|
||||
| Projects | 3 |
|
||||
| Completed | 3 |
|
||||
| Failed | 0 |
|
||||
| Total cost | $6.50 / $15.00 |
|
||||
| Duration | 10m 00s |
|
||||
|
||||
## Per-Project Results
|
||||
### archeflow
|
||||
- **Status:** completed
|
||||
- **Task:** Add memory injection to run skill
|
||||
- **Workflow:** fast (1 cycle)
|
||||
- **Cost:** $1.20
|
||||
- **Key artifacts:** plan-creator.md, do-maker.md
|
||||
|
||||
### colette
|
||||
- **Status:** completed
|
||||
- **Task:** Add story-specific voice validation command
|
||||
- **Workflow:** standard (1 cycle)
|
||||
- **Cost:** $1.80
|
||||
- **Key artifacts:** plan-creator.md, do-maker.md, check-sage.md
|
||||
|
||||
### giesing
|
||||
- **Status:** completed
|
||||
- **Task:** Write story #2 using improved tools
|
||||
- **Workflow:** kurzgeschichte (2 cycles)
|
||||
- **Cost:** $3.50
|
||||
- **Key artifacts:** plan-explorer.md, do-maker.md, check-guardian.md
|
||||
|
||||
## Dependency Graph Execution
|
||||
archeflow (Layer 0) ----> completed
|
||||
colette (Layer 0) ----> completed
|
||||
giesing (Layer 1) ----> unblocked ----> completed
|
||||
|
||||
## Cost Breakdown
|
||||
| Project | Plan | Do | Check | Total |
|
||||
|---------|------|----|-------|-------|
|
||||
| archeflow | $0.20 | $0.60 | $0.40 | $1.20 |
|
||||
| colette | $0.30 | $0.80 | $0.70 | $1.80 |
|
||||
| giesing | $0.50 | $2.00 | $1.00 | $3.50 |
|
||||
| **Total** | **$1.00** | **$3.40** | **$2.10** | **$6.50** |
|
||||
```
|
||||
|
||||
**8c. Update master event index:**
|
||||
|
||||
Append to `.archeflow/events/index.jsonl`:
|
||||
|
||||
```jsonl
|
||||
{"run_id":"2026-04-03-giesing-v2","ts":"2026-04-03T14:10:00Z","type":"multi","task":"Write second story with improved ArcheFlow + Colette integration","status":"completed","projects":3,"total_cost_usd":6.50}
|
||||
```
|
||||
|
||||
**8d. Update workspace registry (if applicable):**
|
||||
|
||||
If `docs/project-registry.md` exists and project statuses changed meaningfully, update the registry entries for affected projects.
|
||||
|
||||
---
|
||||
|
||||
## Dry-Run Mode
|
||||
|
||||
When `--dry-run` is specified:
|
||||
|
||||
1. Validate the multi-run definition (DAG, paths, budget).
|
||||
2. For each project (in topological order), run `archeflow:run --dry-run` to get a cost estimate and plan preview.
|
||||
3. Display a summary:
|
||||
|
||||
```
|
||||
Multi-Run Dry Run: giesing-v2
|
||||
Projects: 3
|
||||
Dependency layers: 2
|
||||
Parallel execution: yes
|
||||
|
||||
Layer 0 (parallel):
|
||||
archeflow — fast workflow, code domain
|
||||
Estimated cost: $0.50-1.50
|
||||
colette — standard workflow, code domain
|
||||
Estimated cost: $1.00-3.00
|
||||
|
||||
Layer 1 (after Layer 0):
|
||||
giesing — kurzgeschichte workflow, writing domain
|
||||
Estimated cost: $2.00-5.00
|
||||
|
||||
Total estimated cost: $3.50-9.50
|
||||
Budget: $15.00 (sufficient)
|
||||
|
||||
Proceed? [y/n]
|
||||
```
|
||||
|
||||
4. Do NOT emit `multi.complete`. The multi-run is paused.
|
||||
5. If user says yes, start the full multi-run using the validated config.
|
||||
|
||||
---
|
||||
|
||||
## Resume Mode
|
||||
|
||||
When `--resume <multi-run-id>` is specified:
|
||||
|
||||
1. Read the master event file `.archeflow/events/<multi-run-id>.jsonl`.
|
||||
2. Reconstruct `PROJECT_STATUS` from events (which projects completed, failed, are pending).
|
||||
3. Identify resumable projects:
|
||||
- `failed` projects can be retried.
|
||||
- `blocked` projects whose blockers are now `completed` (e.g., after manual fix) can start.
|
||||
- `pending` projects that were never started can start if their deps are met.
|
||||
4. Display current state and ask for confirmation.
|
||||
5. Continue the multi-run from where it left off, appending to the existing master event file.
|
||||
|
||||
Resume emits a `multi.resume` event:
|
||||
|
||||
```jsonl
|
||||
{"seq":10,"type":"multi.resume","phase":"init","data":{"resumed_from":"2026-04-03-giesing-v2","projects_completed":["archeflow"],"projects_to_run":["colette","giesing"]}}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Integration with Existing Skills
|
||||
|
||||
| Skill | Integration Point |
|
||||
|-------|-------------------|
|
||||
| `run` | Each sub-run is a standard `archeflow:run` invocation. The multi-project skill wraps and coordinates multiple runs. |
|
||||
| `process-log` | Master events follow the same schema (ts, run_id, seq, parent, type, phase, agent, data). Sub-run events use the standard event types. |
|
||||
| `artifact-routing` | Each sub-run follows standard artifact routing internally. Cross-project artifacts follow the injection rules in Section 4. |
|
||||
| `cost-tracking` | Per-project costs come from sub-run `run.complete` events. The multi-project skill aggregates them and enforces the shared budget. |
|
||||
| `domains` | Each project auto-detects its domain independently. Different projects in the same multi-run can have different domains. |
|
||||
| `git-integration` | Each sub-run manages its own branch. The multi-project skill does not merge across repos — each project's Act phase handles its own merge. |
|
||||
| `autonomous-mode` | Multi-project runs are autonomous-mode-friendly. Budget enforcement is strict (halt, don't prompt). Blocked projects are skipped. |
|
||||
|
||||
---
|
||||
|
||||
## Progress Display
|
||||
|
||||
Throughout the multi-run, display live progress:
|
||||
|
||||
```
|
||||
━━━ ArcheFlow Multi-Run: giesing-v2 ━━━━━━━━━━━━━━━━━━━
|
||||
Projects: 3 | Budget: $15.00 | Parallel: yes
|
||||
|
||||
[archeflow] fast/code -> running (Plan: Creator designing...)
|
||||
[colette] standard/code -> running (Do: Maker implementing...)
|
||||
[giesing] kurzgeschichte/writing -> blocked (waiting: archeflow, colette)
|
||||
|
||||
Cost: $1.80 / $15.00 (12%)
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
```
|
||||
|
||||
Update the display when:
|
||||
- A project changes state (start, phase change, complete, fail, unblock)
|
||||
- Budget thresholds are crossed
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Error | Response |
|
||||
|-------|----------|
|
||||
| YAML parse error | Abort before starting. Report the parse error with line number. |
|
||||
| Dependency cycle detected | Abort. Report which projects form the cycle. |
|
||||
| Project path does not exist | Abort. Report the missing path. |
|
||||
| Sub-run agent fails to return | Mark project as failed (5-min timeout per the `run` skill). Continue independent projects. |
|
||||
| Master event write fails | Log warning. Continue orchestration. Events are observation, not control flow. |
|
||||
| Artifact directory creation fails | Abort the affected project. This is blocking for cross-project artifact sharing. |
|
||||
| Budget exceeded mid-project | Halt that project immediately. Emit `budget.exceeded`. Skip downstream dependents. |
|
||||
|
||||
---
|
||||
|
||||
## Design Principles
|
||||
|
||||
1. **Each project is autonomous.** Sub-runs use the standard `run` skill without modification. The multi-project skill is a coordinator, not a replacement.
|
||||
2. **DAG over sequence.** Dependencies are declared, not implied by order. Independent projects always run in parallel when possible.
|
||||
3. **Shared budget, independent domains.** Budget is global, but each project detects its own domain, selects its own workflow, and manages its own artifacts.
|
||||
4. **Fail forward.** A failure in one project does not halt independent projects. Only downstream dependents are blocked.
|
||||
5. **Artifacts are the interface.** Projects communicate through saved artifacts, not shared memory or direct agent-to-agent messaging.
|
||||
6. **Resume over restart.** Multi-runs can be resumed from any point. Master events provide enough state to reconstruct progress.
|
||||
7. **Registry-aware.** When a workspace registry exists, use it for discovery and keep it updated. When it does not exist, everything still works.
|
||||
Final report includes per-project results, cost breakdown by phase, and dependency graph execution timeline.
|
||||
|
||||
@@ -1,160 +1,59 @@
|
||||
---
|
||||
name: presence
|
||||
description: |
|
||||
Defines how ArcheFlow communicates its activity to the user — visible but not noisy.
|
||||
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 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.
|
||||
## Output Rules
|
||||
|
||||
## 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.
|
||||
1. Show outcomes, not mechanics
|
||||
2. One line per phase, not per agent
|
||||
3. Numbers over words
|
||||
4. Silence on clean passes
|
||||
5. Value summary at the end
|
||||
|
||||
## Status Line Format
|
||||
|
||||
At key moments during a run, output a compact status line:
|
||||
|
||||
### Run Start
|
||||
**Run start:**
|
||||
```
|
||||
── archeflow ── <task> ── <workflow> (<max_cycles> cycles) ──
|
||||
```
|
||||
Example:
|
||||
```
|
||||
── archeflow ── Write story "Der Huster" ── kurzgeschichte (2 cycles) ──
|
||||
-- archeflow -- <task> -- <workflow> (<max_cycles> cycles) --
|
||||
```
|
||||
|
||||
### Phase Complete (only if something happened worth mentioning)
|
||||
**Phase complete (only if noteworthy):**
|
||||
```
|
||||
✓ 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
|
||||
V plan explorer: 3 directions -> chose C | creator: 6 scenes
|
||||
V do 6004 words drafted
|
||||
T check guardian: 1 fix needed | sage: 5 voice adjustments
|
||||
V act 6 fixes applied
|
||||
```
|
||||
Symbols: V = clean, T = issues found, X = failed/blocked.
|
||||
|
||||
Symbols:
|
||||
- `✓` — phase clean, no issues
|
||||
- `△` — phase found issues (fixes needed)
|
||||
- `✗` — phase failed (blocked, needs user input)
|
||||
|
||||
### Run Complete
|
||||
**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 ──
|
||||
-- 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:
|
||||
**Activation indicator (session start, one line):**
|
||||
```
|
||||
── 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]
|
||||
───────────────────────────────────────────────
|
||||
archeflow v0.7.0 . 24 skills . writing domain detected
|
||||
```
|
||||
|
||||
## 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
|
||||
- Agent spawning/completion lifecycle
|
||||
- Event emission
|
||||
- Artifact routing
|
||||
- Clean review passes (0 findings)
|
||||
- Phase transitions with no 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.7.0 · 24 skills · writing domain detected
|
||||
```
|
||||
|
||||
Or for code projects:
|
||||
```
|
||||
archeflow v0.7.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 ──
|
||||
```
|
||||
- Run start and complete (always)
|
||||
- Findings found and fixes applied
|
||||
- Budget warnings
|
||||
- Shadow detected
|
||||
- User decision needed
|
||||
|
||||
@@ -3,37 +3,20 @@ name: progress
|
||||
description: |
|
||||
Live progress file for ArcheFlow orchestrations. Regenerates `.archeflow/progress.md`
|
||||
after every event emission, giving users real-time visibility into run status, budget
|
||||
usage, and DAG shape — watchable from a second terminal.
|
||||
usage, and DAG shape -- watchable from a second terminal.
|
||||
<example>User: "What's happening with my run?"</example>
|
||||
<example>watch -n 2 cat .archeflow/progress.md</example>
|
||||
---
|
||||
|
||||
# Live Progress — Real-Time Run Visibility
|
||||
# Live Progress -- Real-Time Run Visibility
|
||||
|
||||
During long-running orchestrations (Maker drafting, parallel reviews), users have no visibility into what is happening. This skill solves that by maintaining a live progress file that is regenerated after every event.
|
||||
|
||||
## Progress File
|
||||
|
||||
**Location:** `.archeflow/progress.md`
|
||||
|
||||
Updated after every event emission during a run. Users can watch it from a second terminal:
|
||||
|
||||
```bash
|
||||
# Simple polling
|
||||
watch -n 2 cat .archeflow/progress.md
|
||||
|
||||
# Continuous mode (built-in)
|
||||
./lib/archeflow-progress.sh <run_id> --watch
|
||||
|
||||
# Programmatic consumption
|
||||
./lib/archeflow-progress.sh <run_id> --json
|
||||
```
|
||||
Maintains `.archeflow/progress.md`, updated after every event during a run.
|
||||
|
||||
## Progress File Format
|
||||
|
||||
```markdown
|
||||
# ArcheFlow Run: 2026-04-03-der-huster
|
||||
**Status:** DO phase — maker running (3/6 scenes drafted)
|
||||
**Status:** DO phase -- maker running (3/6 scenes drafted)
|
||||
**Started:** 14:32 | **Elapsed:** 8 min
|
||||
**Budget:** $1.45 / $10.00 (14%)
|
||||
|
||||
@@ -47,145 +30,40 @@ watch -n 2 cat .archeflow/progress.md
|
||||
- [ ] ACT: Apply fixes
|
||||
|
||||
## Latest Event
|
||||
#6 agent.start — maker (do) — 14:40
|
||||
|
||||
## DAG (so far)
|
||||
#1 run.start
|
||||
├── #2 story-explorer ✓
|
||||
│ ├── #3 decision ✓
|
||||
│ └── #4 creator ✓
|
||||
├── #5 plan→do ✓
|
||||
└── #6 maker ← running
|
||||
#6 agent.start -- maker (do) -- 14:40
|
||||
```
|
||||
|
||||
## How to Use
|
||||
## Usage
|
||||
|
||||
### During Orchestration (run skill integration)
|
||||
|
||||
The `run` skill should call `archeflow-progress.sh` after each event emission. This keeps progress decoupled from the event emitter itself — no modification to `archeflow-event.sh` is needed.
|
||||
|
||||
Add this call after every `archeflow-event.sh` invocation in the run loop:
|
||||
|
||||
```bash
|
||||
# After emitting an event:
|
||||
./lib/archeflow-event.sh "$RUN_ID" agent.complete plan explorer '{"archetype":"explorer",...}'
|
||||
|
||||
# Update progress:
|
||||
./lib/archeflow-progress.sh "$RUN_ID"
|
||||
The `run` skill calls `archeflow-progress.sh` after each event emission:
|
||||
```
|
||||
|
||||
This is a fast operation (reads JSONL, writes one markdown file) and adds negligible overhead.
|
||||
|
||||
### From a Second Terminal
|
||||
|
||||
```bash
|
||||
# One-shot: see current state
|
||||
./lib/archeflow-progress.sh <run_id>
|
||||
cat .archeflow/progress.md
|
||||
|
||||
# Continuous: auto-refresh every 2 seconds
|
||||
./lib/archeflow-progress.sh <run_id> --watch
|
||||
|
||||
# JSON output for dashboards or scripts
|
||||
./lib/archeflow-progress.sh <run_id> --json
|
||||
```
|
||||
|
||||
### Reactive Mode (via JSONL tail)
|
||||
**From a second terminal:**
|
||||
- One-shot: `cat .archeflow/progress.md`
|
||||
- Continuous: `./lib/archeflow-progress.sh <run_id> --watch`
|
||||
- JSON output: `./lib/archeflow-progress.sh <run_id> --json`
|
||||
|
||||
```bash
|
||||
tail -f .archeflow/events/<run_id>.jsonl | while read line; do
|
||||
./lib/archeflow-progress.sh <run_id>
|
||||
done
|
||||
```
|
||||
## How the Script Works
|
||||
|
||||
## Progress Script
|
||||
|
||||
**Location:** `lib/archeflow-progress.sh`
|
||||
|
||||
```
|
||||
Usage:
|
||||
archeflow-progress.sh <run_id> # Generate/update progress.md
|
||||
archeflow-progress.sh <run_id> --watch # Continuous update mode (2s interval)
|
||||
archeflow-progress.sh <run_id> --json # Output as JSON (for dashboards)
|
||||
```
|
||||
|
||||
### What the Script Does
|
||||
|
||||
1. **Read** `.archeflow/events/<run_id>.jsonl` — the event stream for this run
|
||||
2. **Determine** current phase and active agent from the latest events
|
||||
3. **Build checklist** — mark completed agents with timing/cost data, show pending agents as unchecked
|
||||
4. **Show partial DAG** — completed nodes with checkmarks, running node with arrow indicator
|
||||
5. **Calculate budget** — sum `estimated_cost_usd` from `agent.complete` events, compare to budget from `run.start` config or `.archeflow/config.yaml`
|
||||
6. **Compute elapsed time** — difference between `run.start` timestamp and now
|
||||
7. **Write** to `.archeflow/progress.md`
|
||||
|
||||
### Output Modes
|
||||
|
||||
**Default (markdown):** Writes `.archeflow/progress.md` and prints the same content to stdout.
|
||||
|
||||
**`--watch`:** Clears the terminal every 2 seconds, re-reads the JSONL, and regenerates the display. Exits when a `run.complete` event is found.
|
||||
|
||||
**`--json`:** Outputs a structured JSON object to stdout (does not write progress.md):
|
||||
|
||||
```json
|
||||
{
|
||||
"run_id": "2026-04-03-der-huster",
|
||||
"status": "running",
|
||||
"phase": "do",
|
||||
"active_agent": "maker",
|
||||
"elapsed_seconds": 480,
|
||||
"budget_used_usd": 1.45,
|
||||
"budget_total_usd": 10.00,
|
||||
"budget_percent": 14,
|
||||
"completed": [
|
||||
{"agent": "explorer", "phase": "plan", "duration_s": 87, "tokens": 21000, "cost_usd": 0.02},
|
||||
{"agent": "creator", "phase": "plan", "duration_s": 167, "tokens": 26000, "cost_usd": 0.08}
|
||||
],
|
||||
"pending": ["guardian", "sage"],
|
||||
"latest_event": {"seq": 6, "type": "agent.start", "agent": "maker", "phase": "do"},
|
||||
"total_events": 6
|
||||
}
|
||||
```
|
||||
1. Read `.archeflow/events/<run_id>.jsonl`
|
||||
2. Determine current phase and active agent
|
||||
3. Build checklist from events (only started/completed agents shown)
|
||||
4. Calculate budget from `agent.complete` cost data
|
||||
5. Write `.archeflow/progress.md`
|
||||
|
||||
## Checklist Construction
|
||||
|
||||
The progress checklist is built from events, not from a predefined workflow definition. Each event type maps to a checklist entry:
|
||||
|
||||
| Event Type | Checklist Entry |
|
||||
|-----------|----------------|
|
||||
| Event Type | Entry |
|
||||
|-----------|-------|
|
||||
| `agent.complete` | `- [x] PHASE: archetype (duration, tokens, cost)` |
|
||||
| `agent.start` (no matching complete) | `- [ ] **PHASE: archetype** <- running (elapsed)` |
|
||||
| `agent.start` (no complete) | `- [ ] **PHASE: archetype** <- running` |
|
||||
| `phase.transition` | `- [x] PHASE -> PHASE transition` |
|
||||
| `review.verdict` | `- [x] CHECK: archetype -> VERDICT` |
|
||||
| `fix.applied` | `- [x] ACT: Fix (source)` |
|
||||
| `cycle.boundary` | `- [x] Cycle N complete` |
|
||||
|
||||
Pending agents (not yet started) are NOT shown in the checklist — only started or completed agents appear. This avoids guessing which agents will be spawned.
|
||||
Pending (not-yet-started) agents are NOT shown to avoid guessing.
|
||||
|
||||
## Budget Display
|
||||
|
||||
Budget information comes from two sources:
|
||||
|
||||
1. **`run.start` event** — may contain `config.budget_usd`
|
||||
2. **`.archeflow/config.yaml`** — global `budget.per_run_usd`
|
||||
|
||||
If no budget is configured, the budget line shows cost only (no percentage):
|
||||
|
||||
```
|
||||
**Cost:** $1.45 (no budget set)
|
||||
```
|
||||
|
||||
## Integration with Other Skills
|
||||
|
||||
- **`run`**: Should call `archeflow-progress.sh` after each event emission
|
||||
- **`process-log`**: Progress reads the same JSONL that process-log defines
|
||||
- **`cost-tracking`**: Budget data and cost calculations follow cost-tracking conventions
|
||||
- **`autonomous-mode`**: Progress file is useful for monitoring autonomous overnight runs
|
||||
|
||||
## Design Principles
|
||||
|
||||
1. **Read-only on events.** Progress never modifies the JSONL. It is a derived view.
|
||||
2. **Fast.** One JSONL read + one markdown write. No jq streaming, no databases.
|
||||
3. **Decoupled.** No hooks in `archeflow-event.sh`. The `run` skill calls progress explicitly.
|
||||
4. **Optional.** If progress is never called, orchestration works fine. No side effects.
|
||||
5. **Terminal-friendly.** Output is plain markdown — renders well in `cat`, `bat`, `glow`, or any terminal.
|
||||
Source: `run.start` event or `.archeflow/config.yaml`. If no budget configured: show cost only.
|
||||
|
||||
@@ -7,316 +7,79 @@ description: |
|
||||
<example>User: "archeflow init writing-short-story"</example>
|
||||
<example>User: "archeflow template save my-backend-setup"</example>
|
||||
<example>User: "archeflow template list"</example>
|
||||
<example>User: "archeflow init --from ../book.giesing-gschichten"</example>
|
||||
---
|
||||
|
||||
# Template Gallery — Shareable ArcheFlow Configurations
|
||||
# Template Gallery -- Shareable ArcheFlow Configurations
|
||||
|
||||
Workflows, team presets, custom archetypes, and domain configs should be reusable across projects. This skill defines the template system that makes ArcheFlow setups portable and shareable.
|
||||
Makes ArcheFlow setups portable and reusable across projects.
|
||||
|
||||
## Template Storage
|
||||
|
||||
Templates live in two locations, with project-local overriding global:
|
||||
|
||||
| Location | Scope | Precedence |
|
||||
|----------|-------|------------|
|
||||
| `.archeflow/templates/` | Project-local | Higher (checked first) |
|
||||
| `~/.archeflow/templates/` | Global (user-wide) | Lower (fallback) |
|
||||
|
||||
### Directory Structure
|
||||
Subdirectories: `workflows/`, `teams/`, `archetypes/`, `domains/`, `bundles/`.
|
||||
|
||||
```
|
||||
~/.archeflow/templates/
|
||||
├── workflows/
|
||||
│ ├── kurzgeschichte.yaml
|
||||
│ ├── feature-implementation.yaml
|
||||
│ └── security-review.yaml
|
||||
├── teams/
|
||||
│ ├── story-development.yaml
|
||||
│ ├── backend.yaml
|
||||
│ └── fullstack.yaml
|
||||
├── archetypes/
|
||||
│ ├── story-explorer.md
|
||||
│ ├── story-sage.md
|
||||
│ └── db-specialist.md
|
||||
├── domains/
|
||||
│ ├── writing.yaml
|
||||
│ ├── code.yaml
|
||||
│ └── research.yaml
|
||||
└── bundles/
|
||||
├── writing-short-story/
|
||||
│ ├── manifest.yaml
|
||||
│ ├── team.yaml
|
||||
│ ├── workflow.yaml
|
||||
│ ├── archetypes/
|
||||
│ │ ├── story-explorer.md
|
||||
│ │ └── story-sage.md
|
||||
│ └── domain.yaml
|
||||
└── backend-feature/
|
||||
├── manifest.yaml
|
||||
├── team.yaml
|
||||
├── workflow.yaml
|
||||
└── domain.yaml
|
||||
```
|
||||
## Bundles
|
||||
|
||||
Individual templates (workflows/, teams/, archetypes/, domains/) are single files that can be used standalone. Bundles are complete setups that include everything a project needs.
|
||||
A bundle is a complete setup (team + workflow + archetypes + domain) in one directory.
|
||||
|
||||
---
|
||||
|
||||
## Bundle Manifest
|
||||
|
||||
Every bundle has a `manifest.yaml` that declares what it contains, what it requires, and what variables it exposes.
|
||||
**Manifest (`manifest.yaml`):**
|
||||
|
||||
```yaml
|
||||
name: writing-short-story
|
||||
description: "Complete setup for short fiction writing with ArcheFlow"
|
||||
version: 1
|
||||
description: "Complete setup for short fiction writing"
|
||||
domain: writing
|
||||
includes:
|
||||
team: story-development.yaml
|
||||
workflow: kurzgeschichte.yaml
|
||||
archetypes:
|
||||
- story-explorer.md
|
||||
- story-sage.md
|
||||
archetypes: [story-explorer.md, story-sage.md]
|
||||
domain: writing.yaml
|
||||
requires:
|
||||
- colette.yaml # Project must have this file
|
||||
requires: [colette.yaml]
|
||||
variables:
|
||||
target_words: 6000 # Default, can be overridden at init time
|
||||
max_cycles: 2 # Default, can be overridden at init time
|
||||
target_words: 6000
|
||||
max_cycles: 2
|
||||
```
|
||||
|
||||
### Manifest Fields
|
||||
|
||||
| Field | Required | Description |
|
||||
|-------|----------|-------------|
|
||||
| `name` | Yes | Bundle identifier (used in `archeflow init <name>`) |
|
||||
| `name` | Yes | Bundle identifier for `archeflow init <name>` |
|
||||
| `description` | Yes | Human-readable description |
|
||||
| `version` | No | Bundle version (integer, default 1) |
|
||||
| `domain` | No | Domain this bundle is designed for |
|
||||
| `includes` | Yes | Map of file types to filenames within the bundle |
|
||||
| `requires` | No | List of files that must exist in the target project |
|
||||
| `variables` | No | Key-value pairs with defaults, overridable at init |
|
||||
|
||||
### Includes Types
|
||||
|
||||
| Key | Target location in `.archeflow/` | Accepts |
|
||||
|-----|----------------------------------|---------|
|
||||
| `team` | `teams/<filename>` | Single YAML file |
|
||||
| `workflow` | `workflows/<filename>` | Single YAML file |
|
||||
| `archetypes` | `archetypes/<filename>` | List of Markdown files |
|
||||
| `domain` | `domains/<filename>` | Single YAML file |
|
||||
| `hooks` | `hooks.yaml` | Single YAML file |
|
||||
|
||||
---
|
||||
| `includes` | Yes | File types to filenames within bundle |
|
||||
| `requires` | No | Files that must exist in target project |
|
||||
| `variables` | No | Key-value defaults, overridable at init |
|
||||
|
||||
## Operations
|
||||
|
||||
### `archeflow init <bundle-name>`
|
||||
**`archeflow init <bundle-name>`**
|
||||
1. Find bundle (project-local, then global)
|
||||
2. Check `requires` files exist
|
||||
3. Warn before overwriting existing `.archeflow/` config
|
||||
4. Copy files to `.archeflow/` (teams/, workflows/, archetypes/, domains/)
|
||||
5. Generate `.archeflow/config.yaml` with variables
|
||||
|
||||
Initialize a project's `.archeflow/` directory from a named bundle.
|
||||
**`archeflow init --from <project-path>`**
|
||||
- Copy teams/, workflows/, archetypes/, domains/, config.yaml, hooks.yaml
|
||||
- Skip run-specific data: events/, artifacts/, context/, templates/
|
||||
|
||||
**Procedure:**
|
||||
**`archeflow template save <name>`**
|
||||
- Package current `.archeflow/` into `~/.archeflow/templates/bundles/<name>/`
|
||||
- Auto-generate manifest.yaml
|
||||
|
||||
1. Search for the bundle:
|
||||
- `.archeflow/templates/bundles/<name>/manifest.yaml` (project-local)
|
||||
- `~/.archeflow/templates/bundles/<name>/manifest.yaml` (global)
|
||||
- If not found: error with list of available bundles
|
||||
2. Read `manifest.yaml`
|
||||
3. Check `requires`:
|
||||
- For each required file, verify it exists in the project root
|
||||
- If missing: error with `"Required file not found: <file>. This bundle requires it."`
|
||||
4. Check for existing `.archeflow/` setup:
|
||||
- If `.archeflow/teams/`, `.archeflow/workflows/`, etc. already contain files: warn and ask before overwriting
|
||||
- Never silently overwrite existing configuration
|
||||
5. Copy files from bundle to `.archeflow/`:
|
||||
- `team` → `.archeflow/teams/<filename>`
|
||||
- `workflow` → `.archeflow/workflows/<filename>`
|
||||
- `archetypes` → `.archeflow/archetypes/<filename>` (each file)
|
||||
- `domain` → `.archeflow/domains/<filename>`
|
||||
- `hooks` → `.archeflow/hooks.yaml`
|
||||
6. Create `.archeflow/config.yaml` with variables from manifest:
|
||||
```yaml
|
||||
# Generated by archeflow init from bundle: <name>
|
||||
bundle: <name>
|
||||
bundle_version: <version>
|
||||
initialized: <timestamp>
|
||||
variables:
|
||||
target_words: 6000
|
||||
max_cycles: 2
|
||||
```
|
||||
7. Print setup summary:
|
||||
```
|
||||
ArcheFlow initialized from bundle: <name>
|
||||
Team: <team filename> → .archeflow/teams/
|
||||
Workflow: <workflow filename> → .archeflow/workflows/
|
||||
Archetypes: <count> files → .archeflow/archetypes/
|
||||
Domain: <domain filename> → .archeflow/domains/
|
||||
Config: .archeflow/config.yaml (variables: target_words=6000, max_cycles=2)
|
||||
|
||||
Ready to run: archeflow:run
|
||||
```
|
||||
|
||||
### `archeflow init --from <project-path>`
|
||||
|
||||
Clone another project's ArcheFlow setup into the current project.
|
||||
|
||||
**Procedure:**
|
||||
|
||||
1. Verify `<project-path>/.archeflow/` exists
|
||||
2. Copy these subdirectories (if they exist):
|
||||
- `teams/`
|
||||
- `workflows/`
|
||||
- `archetypes/`
|
||||
- `domains/`
|
||||
- `config.yaml`
|
||||
- `hooks.yaml`
|
||||
3. Do NOT copy (run-specific data):
|
||||
- `events/`
|
||||
- `artifacts/`
|
||||
- `context/` (generated by colette-bridge, project-specific)
|
||||
- `templates/` (project-local templates stay local)
|
||||
4. Warn if target `.archeflow/` already has files
|
||||
5. Print summary of what was copied
|
||||
|
||||
### `archeflow template save <name>`
|
||||
|
||||
Save the current project's `.archeflow/` setup as a reusable template bundle.
|
||||
|
||||
**Procedure:**
|
||||
|
||||
1. Verify `.archeflow/` exists and has content
|
||||
2. Create bundle directory: `~/.archeflow/templates/bundles/<name>/`
|
||||
- If it already exists: warn and ask before overwriting
|
||||
3. Copy from `.archeflow/` to bundle:
|
||||
- `teams/*.yaml` → bundle `team` (first file, or prompt if multiple)
|
||||
- `workflows/*.yaml` → bundle `workflow` (first file, or prompt if multiple)
|
||||
- `archetypes/*.md` → bundle `archetypes/`
|
||||
- `domains/*.yaml` → bundle `domain` (first file, or prompt if multiple)
|
||||
- `hooks.yaml` → bundle (if exists)
|
||||
4. Generate `manifest.yaml`:
|
||||
```yaml
|
||||
name: <name>
|
||||
description: "Saved from <project directory name>"
|
||||
version: 1
|
||||
domain: <from domain yaml if present>
|
||||
includes:
|
||||
team: <filename>
|
||||
workflow: <filename>
|
||||
archetypes: [<filenames>]
|
||||
domain: <filename>
|
||||
requires: []
|
||||
variables: <from config.yaml variables section if present>
|
||||
```
|
||||
5. Print summary:
|
||||
```
|
||||
Template saved: <name>
|
||||
Location: ~/.archeflow/templates/bundles/<name>/
|
||||
Files: <count> files
|
||||
Use with: archeflow init <name>
|
||||
```
|
||||
|
||||
### `archeflow template list`
|
||||
|
||||
List all available templates — both individual files and bundles, from both global and project-local locations.
|
||||
|
||||
**Output format:**
|
||||
|
||||
```
|
||||
ArcheFlow Templates
|
||||
====================
|
||||
|
||||
Bundles:
|
||||
writing-short-story Complete setup for short fiction writing [global]
|
||||
backend-feature Backend feature implementation [global]
|
||||
my-project-setup Saved from book.giesing-gschichten [global]
|
||||
|
||||
Individual Templates:
|
||||
Workflows:
|
||||
kurzgeschichte.yaml [global]
|
||||
feature-implementation.yaml [global]
|
||||
Teams:
|
||||
story-development.yaml [global]
|
||||
backend.yaml [global]
|
||||
Archetypes:
|
||||
story-explorer.md [global]
|
||||
story-sage.md [global]
|
||||
Domains:
|
||||
writing.yaml [global]
|
||||
code.yaml [global]
|
||||
```
|
||||
|
||||
### `archeflow template share <name> <path>`
|
||||
|
||||
Export a template bundle to a directory for sharing (e.g., via git, email, file share).
|
||||
|
||||
**Procedure:**
|
||||
|
||||
1. Find the bundle (global or local)
|
||||
2. Copy the entire bundle directory to `<path>/<name>/`
|
||||
3. Print the path and a one-liner for importing:
|
||||
```
|
||||
Exported: <path>/<name>/
|
||||
To import: cp -r <path>/<name> ~/.archeflow/templates/bundles/
|
||||
```
|
||||
|
||||
---
|
||||
**`archeflow template list`**
|
||||
- Show all bundles and individual templates (global + project-local)
|
||||
|
||||
## Variable Substitution
|
||||
|
||||
Bundle manifests can define variables with defaults. These are stored in `.archeflow/config.yaml` after init and can be overridden:
|
||||
Variables in manifests are stored in `.archeflow/config.yaml` after init. Substitution happens at run time, not template time.
|
||||
|
||||
- At init time: `archeflow init writing-short-story --set target_words=8000`
|
||||
- After init: edit `.archeflow/config.yaml` directly
|
||||
Override at init: `archeflow init writing-short-story --set target_words=8000`
|
||||
|
||||
Variables are available to workflows and the run skill via config:
|
||||
## Individual Templates
|
||||
|
||||
```yaml
|
||||
# In a workflow, reference variables:
|
||||
phases:
|
||||
do:
|
||||
description: |
|
||||
Draft the story. Target: ${target_words} words.
|
||||
```
|
||||
|
||||
Variable substitution happens at run time, not at init time. The workflow file contains the `${variable}` placeholder; the run skill reads `.archeflow/config.yaml` and substitutes before passing to agents.
|
||||
|
||||
---
|
||||
|
||||
## Individual Template Usage
|
||||
|
||||
Not everything needs a bundle. Individual templates can be copied directly:
|
||||
|
||||
```bash
|
||||
# Copy a single workflow
|
||||
cp ~/.archeflow/templates/workflows/kurzgeschichte.yaml .archeflow/workflows/
|
||||
|
||||
# Copy a single archetype
|
||||
cp ~/.archeflow/templates/archetypes/story-explorer.md .archeflow/archetypes/
|
||||
|
||||
# Copy a team preset
|
||||
cp ~/.archeflow/templates/teams/story-development.yaml .archeflow/teams/
|
||||
```
|
||||
|
||||
The `archeflow init` command handles bundles. For individual files, manual copy or the helper script (`lib/archeflow-init.sh`) can be used.
|
||||
|
||||
---
|
||||
|
||||
## Integration with Other Skills
|
||||
|
||||
- **`archeflow:run`** — Reads `.archeflow/config.yaml` for variables, applies them during run initialization
|
||||
- **`archeflow:domains`** — Domain YAML from templates is loaded like any other domain config
|
||||
- **`archeflow:custom-archetypes`** — Archetype .md files from templates work identically to hand-written ones
|
||||
- **`archeflow:workflow-design`** — Workflow YAML from templates follows the same schema
|
||||
- **`archeflow:colette-bridge`** — Bundle `requires: [colette.yaml]` ensures the bridge has what it needs
|
||||
|
||||
---
|
||||
|
||||
## Design Principles
|
||||
|
||||
1. **Bundles are self-contained.** Everything needed to set up a project is in the bundle directory. No external dependencies beyond `requires`.
|
||||
2. **Never silently overwrite.** Init warns before replacing existing files. Templates are helpers, not bulldozers.
|
||||
3. **Global + local layering.** Project-local templates override global ones. This allows per-project customization without polluting the global registry.
|
||||
4. **Skip run data.** Events, artifacts, and context are run-specific. Templates carry only configuration.
|
||||
5. **Variables are late-bound.** Substitution happens at run time, not template time. This keeps templates generic.
|
||||
6. **Plain files, no magic.** Templates are just directories of YAML and Markdown files. No databases, no registries, no lock files.
|
||||
Single files can be copied directly without a bundle:
|
||||
- `~/.archeflow/templates/workflows/<name>.yaml`
|
||||
- `~/.archeflow/templates/archetypes/<name>.md`
|
||||
- `~/.archeflow/templates/teams/<name>.yaml`
|
||||
|
||||
@@ -1,248 +1,70 @@
|
||||
---
|
||||
name: workflow-design
|
||||
description: Use when designing custom orchestration workflows — choosing which archetypes run in each PDCA phase, setting exit conditions, and configuring PDCA cycles.
|
||||
description: Use when designing custom orchestration workflows -- choosing which archetypes run in each PDCA phase, setting exit conditions, and configuring PDCA cycles.
|
||||
---
|
||||
|
||||
# Workflow Design — PDCA Cycles
|
||||
# Workflow Design -- PDCA Cycles
|
||||
|
||||
ArcheFlow's PDCA cycles spiral upward through iterations — each cycle incorporates feedback from the previous one, producing progressively better results. Each cycle incorporates feedback from the previous one.
|
||||
|
||||
```
|
||||
╱ Act ──────────── Done ✓
|
||||
╱ ↑
|
||||
╱ Check (review)
|
||||
╱ ↑
|
||||
╱ Do (implement)
|
||||
╱ ↑
|
||||
╱ Plan (design) ← Cycle 2 (with feedback from Cycle 1)
|
||||
╱ ↑
|
||||
╱ Act ─┘ (issues found → feed back)
|
||||
│ ↑
|
||||
│ Check (review)
|
||||
│ ↑
|
||||
│ Do (implement)
|
||||
│ ↑
|
||||
│ Plan (design) ← Cycle 1 (initial)
|
||||
```
|
||||
|
||||
## Strategy vs Workflow
|
||||
|
||||
A **strategy** defines the execution shape: PDCA is cyclic (Plan-Do-Check-Act with feedback loops), pipeline is linear (Plan-Implement-Review-Verify, no cycle-back). A **workflow** defines the depth: fast uses fewer agents and cycles, thorough uses more. Strategy and workflow are orthogonal — you can run a `fast` workflow with either strategy, though `thorough` always uses PDCA because linear flows cannot iterate on findings.
|
||||
PDCA cycles spiral upward: each cycle incorporates feedback from the previous one.
|
||||
|
||||
## Built-in Workflows
|
||||
|
||||
### `fast` — Single Turn
|
||||
```
|
||||
Plan: Creator designs
|
||||
Do: Maker implements (worktree)
|
||||
Check: Guardian reviews
|
||||
Act: Approve or reject (1 cycle max)
|
||||
```
|
||||
**Use for:** Bug fixes, small changes, low-risk tasks.
|
||||
|
||||
### `standard` — Two Cycles
|
||||
```
|
||||
Plan: Explorer researches → Creator designs
|
||||
Do: Maker implements (worktree)
|
||||
Check: Guardian + Skeptic + Sage review (parallel)
|
||||
Act: Approve or cycle (2 cycles max)
|
||||
```
|
||||
**Use for:** Features, refactors, moderate-risk changes.
|
||||
|
||||
### `thorough` — Three Cycles
|
||||
```
|
||||
Plan: Explorer researches → Creator designs
|
||||
Do: Maker implements (worktree)
|
||||
Check: Guardian + Skeptic + Sage + Trickster (parallel)
|
||||
Act: Approve or cycle (3 cycles max)
|
||||
```
|
||||
**Use for:** Security-critical, public APIs, infrastructure changes.
|
||||
| Workflow | Plan | Do | Check | Exit | Max Cycles |
|
||||
|----------|------|----|-------|------|------------|
|
||||
| `fast` | Creator | Maker | Guardian | approve/reject | 1 |
|
||||
| `standard` | Explorer + Creator | Maker | Guardian + Skeptic + Sage | all_approved | 2 |
|
||||
| `thorough` | Explorer + Creator | Maker | Guardian + Skeptic + Sage + Trickster | all_approved | 3 |
|
||||
|
||||
## Designing Custom Workflows
|
||||
|
||||
### Step 1: Identify the Concern
|
||||
**Step 1: Identify the concern**
|
||||
|
||||
What's the primary risk?
|
||||
| Risk | Emphasize in Check |
|
||||
|------|-------------------|
|
||||
| Security | Guardian + Trickster |
|
||||
| Correctness | Skeptic + Sage |
|
||||
| Performance | Custom `perf-tester` |
|
||||
| Compliance | Custom `compliance-auditor` |
|
||||
| Data integrity | Custom `db-specialist` |
|
||||
|
||||
| Primary Risk | Emphasize |
|
||||
|-------------|-----------|
|
||||
| Security | Guardian + Trickster in Check |
|
||||
| Correctness | Skeptic + Sage in Check |
|
||||
| Performance | Custom `perf-tester` archetype |
|
||||
| Compliance | Custom `compliance-auditor` archetype |
|
||||
| Data integrity | Custom `db-specialist` archetype |
|
||||
| User experience | Custom `ux-reviewer` archetype |
|
||||
**Step 2: Phase assignment rules**
|
||||
- Plan always includes Creator
|
||||
- Do always includes Maker
|
||||
- Check needs at least one reviewer
|
||||
- Max 3 archetypes per phase
|
||||
- Explorer goes in Plan only; Maker goes in Do only
|
||||
|
||||
### Step 2: Assign Phases
|
||||
**Step 3: Exit conditions**
|
||||
|
||||
Rules:
|
||||
- **Plan** always includes Creator (someone must propose)
|
||||
- **Do** always includes Maker (someone must build)
|
||||
- **Check** needs at least one reviewer
|
||||
- Max 3 archetypes per phase (diminishing returns beyond that)
|
||||
- Explorer goes in Plan only (research before design)
|
||||
- Maker goes in Do only (build from plan, not from scratch)
|
||||
| Condition | Cycle ends when |
|
||||
|-----------|----------------|
|
||||
| `all_approved` | Every reviewer says APPROVED |
|
||||
| `no_critical` | No CRITICAL findings |
|
||||
| `convergence` | No new issues vs previous cycle |
|
||||
| `always` | Runs all maxCycles unconditionally |
|
||||
|
||||
### Step 3: Set Exit Conditions
|
||||
|
||||
| Condition | When Cycle Ends | Best For |
|
||||
|-----------|----------------|----------|
|
||||
| `all_approved` | Every Check reviewer says APPROVED | Consensus-driven (default) |
|
||||
| `no_critical` | No CRITICAL findings in Check output | Speed with safety net |
|
||||
| `convergence` | No new issues vs. previous cycle | Diminishing returns detection |
|
||||
| `always` | Runs all maxCycles unconditionally | Research, exploration |
|
||||
|
||||
### Step 4: Set Max Cycles
|
||||
|
||||
- **1 cycle:** Fast, low-risk (fast workflow)
|
||||
- **2 cycles:** Balanced — one shot + one fix (standard workflow)
|
||||
- **3 cycles:** Thorough — usually converges by cycle 3
|
||||
- **4+ cycles:** Rarely useful. If 3 cycles don't converge, the task needs human input.
|
||||
|
||||
## Example Custom Workflows
|
||||
|
||||
### Security-First
|
||||
```
|
||||
Plan: Explorer (threat modeling) → Creator
|
||||
Do: Maker
|
||||
Check: Guardian + Trickster (parallel)
|
||||
Exit: all_approved, max 3 cycles
|
||||
```
|
||||
|
||||
### Research-Heavy
|
||||
```
|
||||
Plan: Explorer (deep research) → Creator
|
||||
Do: Maker
|
||||
Check: Skeptic + Sage (parallel)
|
||||
Exit: all_approved, max 2 cycles
|
||||
```
|
||||
|
||||
### Domain-Specific (with custom archetypes)
|
||||
```
|
||||
Plan: Explorer → Creator
|
||||
Do: Maker
|
||||
Check: Guardian + db-specialist + compliance-auditor (parallel)
|
||||
Exit: all_approved, max 2 cycles
|
||||
```
|
||||
|
||||
### Minimal Validation
|
||||
```
|
||||
Plan: Creator (no research)
|
||||
Do: Maker
|
||||
Check: Guardian
|
||||
Exit: no_critical, max 1 cycle
|
||||
```
|
||||
**Step 4: Max cycles** -- 1 (fast), 2 (balanced), 3 (thorough). 4+ rarely useful.
|
||||
|
||||
## Hook Points
|
||||
|
||||
Add project-specific validation at key moments in the PDCA cycle. Define hooks in `.archeflow/hooks.yaml`:
|
||||
Define in `.archeflow/hooks.yaml`:
|
||||
|
||||
```yaml
|
||||
# .archeflow/hooks.yaml
|
||||
pre-plan:
|
||||
- command: "npm run lint"
|
||||
description: "Ensure clean baseline before planning"
|
||||
fail_action: abort # abort | warn | ignore
|
||||
|
||||
post-check:
|
||||
- command: "npm test"
|
||||
description: "Run tests after review to verify reviewer suggestions"
|
||||
fail_action: cycle_back
|
||||
|
||||
pre-merge:
|
||||
- command: "./scripts/check-migrations.sh"
|
||||
description: "Verify migration safety before merging"
|
||||
fail_action: abort
|
||||
|
||||
post-merge:
|
||||
- command: "npm run integration-test"
|
||||
description: "Full integration test after merge"
|
||||
fail_action: revert
|
||||
```
|
||||
|
||||
**Available hook points:**
|
||||
| Hook | When | Typical Use |
|
||||
| Hook | When | Typical use |
|
||||
|------|------|-------------|
|
||||
| `pre-plan` | Before Explorer/Creator start | Lint, ensure clean baseline |
|
||||
| `post-plan` | After Creator's proposal | Validate proposal against constraints |
|
||||
| `pre-do` | Before Maker starts | Check worktree setup |
|
||||
| `post-do` | After Maker commits | Quick smoke test |
|
||||
| `post-check` | After reviewers finish | Run test suite |
|
||||
| `pre-merge` | Before merging to main | Migration safety, API compatibility |
|
||||
| `post-merge` | After merge completes | Integration tests, deploy checks |
|
||||
| `pre-plan` | Before Explorer/Creator | Lint, clean baseline |
|
||||
| `post-plan` | After Creator's proposal | Validate constraints |
|
||||
| `pre-do` | Before Maker | Check worktree |
|
||||
| `post-do` | After Maker commits | Smoke test |
|
||||
| `post-check` | After reviewers | Run test suite |
|
||||
| `pre-merge` | Before merge | Migration safety |
|
||||
| `post-merge` | After merge | Integration tests |
|
||||
|
||||
## Workflow Template Library
|
||||
|
||||
Pre-built workflows for common scenarios. Use as-is or as starting points for custom workflows.
|
||||
|
||||
### API Design
|
||||
```yaml
|
||||
name: api-design
|
||||
description: New or changed API endpoints
|
||||
plan: [explorer, creator]
|
||||
do: [maker]
|
||||
check: [guardian, skeptic] # Guardian for security, Skeptic for API design assumptions
|
||||
exit: all_approved
|
||||
max_cycles: 2
|
||||
hooks:
|
||||
post-check: "npm run api-compatibility-check"
|
||||
```
|
||||
|
||||
### Database Migration
|
||||
```yaml
|
||||
name: migration
|
||||
description: Schema changes and data migrations
|
||||
plan: [explorer, creator]
|
||||
do: [maker]
|
||||
check: [guardian, db-specialist] # Requires custom db-specialist archetype
|
||||
exit: all_approved
|
||||
max_cycles: 2
|
||||
hooks:
|
||||
pre-merge: "./scripts/check-migration-reversibility.sh"
|
||||
```
|
||||
|
||||
### Dependency Upgrade
|
||||
```yaml
|
||||
name: dep-upgrade
|
||||
description: Upgrading dependencies (major versions, security patches)
|
||||
plan: [creator] # No Explorer needed — changelog is the research
|
||||
do: [maker]
|
||||
check: [guardian]
|
||||
exit: no_critical
|
||||
max_cycles: 1
|
||||
hooks:
|
||||
post-do: "npm audit"
|
||||
post-merge: "npm test && npm run e2e"
|
||||
```
|
||||
|
||||
### Documentation Rewrite
|
||||
```yaml
|
||||
name: docs-rewrite
|
||||
description: Major documentation changes
|
||||
plan: [explorer, creator]
|
||||
do: [maker]
|
||||
check: [sage] # Quality/consistency only — no security review needed
|
||||
exit: all_approved
|
||||
max_cycles: 1
|
||||
```
|
||||
|
||||
### Hotfix
|
||||
```yaml
|
||||
name: hotfix
|
||||
description: Emergency production fix
|
||||
plan: [creator]
|
||||
do: [maker]
|
||||
check: [guardian]
|
||||
exit: no_critical
|
||||
max_cycles: 1
|
||||
hooks:
|
||||
post-merge: "npm test"
|
||||
```
|
||||
Each hook has `command`, `description`, and `fail_action` (abort / warn / ignore / cycle_back / revert).
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
- **Kitchen sink:** Putting all 7 archetypes in Check. Most can't add value simultaneously.
|
||||
- **Runaway cycles:** maxCycles > 4 burns tokens without convergence.
|
||||
- **Reviewerless Do:** Skipping Check phase "to save time." You'll pay in bugs.
|
||||
- **Maker in Plan:** Maker should implement from a proposal, not design on the fly.
|
||||
- **Solo orchestration:** One archetype in every phase. That's just a single agent with extra steps.
|
||||
- All 7 archetypes in Check (diminishing returns)
|
||||
- maxCycles > 4 (burns tokens without convergence)
|
||||
- Skipping Check phase
|
||||
- Maker in Plan phase
|
||||
- One archetype in every phase (just a single agent with overhead)
|
||||
|
||||
Reference in New Issue
Block a user