docs: rewrite README, add CHANGELOG, update skill index and roadmap
- README: complete rewrite with all 24 skills, 8 scripts, architecture overview - CHANGELOG: v0.1.0 → v0.2.0 → v0.3.0 with full feature history - using-archeflow: updated skill reference to all 24 skills in 6 categories - plugin.json: version bump to 0.3.0 - roadmap: updated with v0.3.0 features
This commit is contained in:
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"name": "archeflow",
|
||||
"description": "Multi-agent orchestration with Jungian archetypes. PDCA quality cycles, shadow detection, git worktree isolation. Zero dependencies — works with any Claude Code session.",
|
||||
"version": "0.1.0",
|
||||
"version": "0.3.0",
|
||||
"author": {
|
||||
"name": "Chris Nennemann"
|
||||
},
|
||||
|
||||
71
CHANGELOG.md
Normal file
71
CHANGELOG.md
Normal file
@@ -0,0 +1,71 @@
|
||||
# Changelog
|
||||
|
||||
All notable changes to ArcheFlow are documented in this file.
|
||||
|
||||
## [0.3.0] -- 2026-04-03
|
||||
|
||||
### Added
|
||||
- Automated PDCA execution loop (`archeflow:run`) with `--start-from` and `--dry-run` support
|
||||
- Event-sourced process logging (`archeflow:process-log`) with DAG parent relationships
|
||||
- ASCII DAG renderer (`archeflow-dag.sh`) with color output
|
||||
- Markdown process report generator (`archeflow-report.sh`) with summary and DAG modes
|
||||
- Live progress file (`archeflow:progress`) watchable from a second terminal
|
||||
- Domain adapter system (`archeflow:domains`) for writing, research, and custom domains
|
||||
- Cost tracking skill (`archeflow:cost-tracking`) with budget enforcement and model tier recommendations
|
||||
- Cross-run memory system (`archeflow:memory`) that learns recurring findings and injects lessons
|
||||
- Convergence detection (`archeflow:convergence`) to prevent wasted cycles from stalling or oscillation
|
||||
- Colette bridge (`archeflow:colette-bridge`) for automatic writing platform integration
|
||||
- Template gallery (`archeflow:templates`) with init, save, clone, and list operations
|
||||
- Archetype effectiveness scoring (`archeflow:effectiveness`) across signal-to-noise, fix rate, cost efficiency
|
||||
- Git-per-phase commit strategy (`archeflow:git-integration`) with branch-per-run and rollback
|
||||
- Multi-project orchestration (`archeflow:multi-project`) with dependency DAG and shared budget
|
||||
- Act phase skill (`archeflow:act-phase`) for post-Check decision logic and fix routing
|
||||
- Artifact routing skill (`archeflow:artifact-routing`) for inter-phase artifact management
|
||||
- `archeflow-event.sh` -- structured JSONL event appender
|
||||
- `archeflow-git.sh` -- per-phase commits, branch creation, merge, and rollback
|
||||
- `archeflow-init.sh` -- template gallery script (init, save, clone, list)
|
||||
- `archeflow-memory.sh` -- cross-run memory management (add, list, decay, forget)
|
||||
- `archeflow-progress.sh` -- live progress file generator
|
||||
- `archeflow-score.sh` -- archetype effectiveness scoring from completed runs
|
||||
- Short fiction workflow example (`kurzgeschichte.yaml`) with custom archetypes and Colette integration
|
||||
- Story-explorer and story-sage custom archetype examples
|
||||
|
||||
## [0.2.0] -- 2026-04-03
|
||||
|
||||
### Added
|
||||
- Plugin consolidation into single shareable `archeflow/` directory
|
||||
- Workflow intelligence with conditional escalation, fast-path, and confidence triggers
|
||||
- Quality loop with self-review, convergence detection, dedup, and completion promises
|
||||
- Parallel teams with auto-resume and budget scheduling
|
||||
- Extensibility: archetype composition, team presets, hook points, workflow templates
|
||||
- Mini-reflect fallback for non-ArcheFlow single-file changes (Ralph Loop integration)
|
||||
- Comprehensive README with install, usage, debugging, and examples
|
||||
- DX improvements: structured confidence, alternatives surfacing
|
||||
|
||||
### Fixed
|
||||
- Redesigned adaptation rules per Guardian review to resolve race conditions
|
||||
- Synced Creator agent definition with orchestration skill expectations
|
||||
- Wired hooks correctly and added cost table documentation
|
||||
|
||||
## [0.1.0] -- 2026-04-02
|
||||
|
||||
### Added
|
||||
- Initial release: 7 Jungian archetypes (Explorer, Creator, Maker, Guardian, Skeptic, Trickster, Sage)
|
||||
- PDCA orchestration engine with fast, standard, and thorough workflows
|
||||
- Shadow detection with quantitative heuristics per archetype
|
||||
- Cross-cycle structured feedback with routing and resolution tracking
|
||||
- Attention filters for per-archetype context optimization
|
||||
- Autonomous mode for unattended overnight sessions
|
||||
- Custom archetypes and workflow design skills
|
||||
- SessionStart hook for automatic activation
|
||||
- `archeflow-dag.sh` and `archeflow-report.sh` process visualization scripts
|
||||
|
||||
### Changed
|
||||
- Removed ArcheHelix branding, adopted plain PDCA language
|
||||
- Trimmed phase skills to reduce token waste
|
||||
- Simplified to one shadow per archetype for clearer detection
|
||||
|
||||
### Fixed
|
||||
- Rewrote SessionStart hook in pure Node for portability (no bash/awk/sed dependencies)
|
||||
- Made hook robust with graceful fallbacks (no `set -e`)
|
||||
- Corrected repository URLs
|
||||
432
README.md
432
README.md
@@ -1,12 +1,20 @@
|
||||
# ArcheFlow
|
||||
# ArcheFlow -- Multi-Agent Orchestration for Claude Code
|
||||
|
||||
**Multi-agent orchestration with Jungian archetypes for Claude Code.**
|
||||
**Structured quality through archetypal collaboration.** ArcheFlow coordinates multiple Claude Code agents through PDCA cycles, where each agent embodies a Jungian archetype with defined strengths and known failure modes.
|
||||
|
||||
ArcheFlow gives Claude Code a structured way to coordinate multiple agents through quality cycles. Instead of one agent doing everything, specialized archetypes collaborate through **PDCA cycles** — Plan, Do, Check, Act — where each iteration builds on feedback from the last.
|
||||
Zero dependencies. No build step. Install and go.
|
||||
|
||||
Zero dependencies. No build step. Just install and go.
|
||||
## What It Does
|
||||
|
||||
## Install
|
||||
Large coding tasks benefit from multiple perspectives, but "just spawn more agents" creates chaos. Agents duplicate work, miss each other's output, argue in circles, or go rogue. The problem is not intelligence -- it is coordination.
|
||||
|
||||
ArcheFlow solves this by giving each agent an *archetype*: a behavioral protocol that defines what the agent cares about, what context it receives, and how its output feeds into the next phase. Seven archetypes collaborate through **Plan-Do-Check-Act cycles**, where each iteration builds on structured feedback from the last. No unreviewed code reaches your main branch.
|
||||
|
||||
The key insight: archetypes are not just system prompts. Each one has a **virtue** (its unique contribution) and a **shadow** (the dysfunction it falls into when pushed too far). ArcheFlow monitors for shadow activation and course-corrects automatically -- replacing an agent that blocks everything, reining in one that researches forever, or escalating when a maker goes off-script.
|
||||
|
||||
## Quick Start
|
||||
|
||||
### 1. Install
|
||||
|
||||
```bash
|
||||
# From Git
|
||||
@@ -16,141 +24,159 @@ claude plugin install --url https://git.xorwell.de/c/claude-archeflow-plugin
|
||||
claude --plugin-dir ./archeflow
|
||||
```
|
||||
|
||||
ArcheFlow activates automatically at session start and kicks in when you give implementation tasks.
|
||||
### 2. Run your first orchestration
|
||||
|
||||
## How It Works
|
||||
|
||||
When you give Claude an implementation task, ArcheFlow automatically:
|
||||
|
||||
1. **Assesses the task** and picks a workflow (fast/standard/thorough)
|
||||
2. **Plan** — Explorer researches, Creator designs a proposal
|
||||
3. **Do** — Maker implements in an isolated git worktree
|
||||
4. **Check** — Reviewers assess in parallel
|
||||
5. **Act** — All approved? Merge. Issues? Cycle back with structured feedback.
|
||||
|
||||
No unreviewed code reaches your main branch. Ever.
|
||||
Just describe a task. ArcheFlow activates automatically for multi-file changes:
|
||||
|
||||
```
|
||||
Plan → Explorer researches, Creator proposes
|
||||
Do → Maker implements in isolated worktree
|
||||
Check → Reviewers assess in parallel (approve/reject)
|
||||
Act → All approved? Merge. Issues? Cycle back to Plan.
|
||||
> Add input validation to all API endpoints
|
||||
```
|
||||
|
||||
Or invoke it explicitly:
|
||||
|
||||
```
|
||||
> archeflow:run "Add JWT authentication" --workflow standard
|
||||
```
|
||||
|
||||
### 3. What happens
|
||||
|
||||
ArcheFlow selects a workflow (fast, standard, or thorough) and runs a PDCA cycle:
|
||||
|
||||
```
|
||||
Plan --> Explorer researches codebase context, Creator designs a proposal
|
||||
Do --> Maker implements in an isolated git worktree
|
||||
Check --> Reviewers assess in parallel (Guardian, Skeptic, Sage, Trickster)
|
||||
Act --> All approved? Merge. Issues found? Cycle back with structured feedback.
|
||||
|
||||
Each cycle catches what the last one missed.
|
||||
```
|
||||
|
||||
Progress is visible in real time:
|
||||
|
||||
```
|
||||
--- ArcheFlow: Add JWT authentication ---------
|
||||
Workflow: standard (2 cycles max)
|
||||
|
||||
🔍 [Plan] Explorer researching... done (35s)
|
||||
🏗️ [Plan] Creator designing proposal... done (25s, confidence: 0.8)
|
||||
⚒️ [Do] Maker implementing... done (90s, 4 files, 8 tests)
|
||||
🛡️ [Check] Guardian reviewing... APPROVED
|
||||
🤔 [Check] Skeptic challenging... APPROVED (1 INFO)
|
||||
📚 [Check] Sage reviewing... APPROVED
|
||||
[Act] All approved -- merging... merged to main
|
||||
|
||||
--- Complete: 3m 10s, 1 cycle -----------------
|
||||
```
|
||||
|
||||
## The Seven Archetypes
|
||||
|
||||
Each archetype has a **virtue** (its unique contribution) and a **shadow** (dysfunction when pushed too far). ArcheFlow detects shadows and course-corrects automatically.
|
||||
| Archetype | Phase | Virtue | Shadow | Role |
|
||||
|-----------|-------|--------|--------|------|
|
||||
| 🔍 **Explorer** | Plan | Contextual Clarity | Rabbit Hole | Researches codebase, maps dependencies, synthesizes findings |
|
||||
| 🏗️ **Creator** | Plan | Decisive Framing | Over-Architect | Designs solution proposals with architecture decisions and test strategy |
|
||||
| ⚒️ **Maker** | Do | Execution Discipline | Rogue | Implements code in an isolated git worktree, commits per phase |
|
||||
| 🛡️ **Guardian** | Check | Threat Intuition | Paranoid | Reviews for security vulnerabilities, reliability risks, breaking changes |
|
||||
| 🤔 **Skeptic** | Check | Assumption Surfacing | Paralytic | Challenges assumptions, identifies untested scenarios, proposes alternatives |
|
||||
| 🃏 **Trickster** | Check | Adversarial Creativity | False Alarm | Adversarial testing, boundary attacks, edge case exploitation |
|
||||
| 📚 **Sage** | Check | Maintainability Judgment | Bureaucrat | Holistic quality review -- code quality, test coverage, engineering judgment |
|
||||
|
||||
| Archetype | Virtue | Shadow | Phase |
|
||||
|-----------|--------|--------|-------|
|
||||
| **Explorer** | Contextual Clarity | Rabbit Hole | Plan |
|
||||
| **Creator** | Decisive Framing | Over-Architect | Plan |
|
||||
| **Maker** | Execution Discipline | Rogue | Do |
|
||||
| **Guardian** | Threat Intuition | Paranoid | Check |
|
||||
| **Skeptic** | Assumption Surfacing | Paralytic | Check |
|
||||
| **Trickster** | Adversarial Creativity | False Alarm | Check |
|
||||
| **Sage** | Maintainability Judgment | Bureaucrat | Check |
|
||||
Shadow detection is quantitative, not vibes. Explorer output exceeding 2000 words without a recommendation triggers Rabbit Hole. Guardian blocking three consecutive items triggers Paranoid. First detection: correction prompt. Second: replace agent. Third: escalate to user.
|
||||
|
||||
## Skills Reference
|
||||
|
||||
ArcheFlow ships with 24 skills organized by function.
|
||||
|
||||
### Core Orchestration
|
||||
|
||||
| Skill | Description |
|
||||
|-------|-------------|
|
||||
| `archeflow:run` | Automated PDCA execution loop -- single-command orchestration with `--start-from`, `--dry-run`, and cycle-back |
|
||||
| `archeflow:orchestration` | Step-by-step PDCA execution guide for manual orchestration |
|
||||
| `archeflow:plan-phase` | Explorer and Creator output formats and protocols |
|
||||
| `archeflow:do-phase` | Maker implementation rules and worktree commit strategy |
|
||||
| `archeflow:check-phase` | Shared reviewer protocols and output format |
|
||||
| `archeflow:act-phase` | Post-Check decision logic: collect findings, route fixes, exit or cycle |
|
||||
|
||||
### Quality and Safety
|
||||
|
||||
| Skill | Description |
|
||||
|-------|-------------|
|
||||
| `archeflow:shadow-detection` | Quantitative dysfunction detection and automatic correction |
|
||||
| `archeflow:attention-filters` | Context optimization per archetype -- each agent gets only what it needs |
|
||||
| `archeflow:convergence` | Detects convergence, stalling, and oscillation in multi-cycle runs |
|
||||
| `archeflow:artifact-routing` | Inter-phase artifact protocol -- naming, storage, routing, archiving |
|
||||
|
||||
### Process Intelligence
|
||||
|
||||
| Skill | Description |
|
||||
|-------|-------------|
|
||||
| `archeflow:process-log` | Event-sourced JSONL logging with DAG parent relationships |
|
||||
| `archeflow:memory` | Cross-run memory that learns recurring findings and injects lessons |
|
||||
| `archeflow:effectiveness` | Archetype scoring on signal-to-noise, fix rate, cost efficiency |
|
||||
| `archeflow:progress` | Live progress file watchable from a second terminal |
|
||||
|
||||
### Integration
|
||||
|
||||
| Skill | Description |
|
||||
|-------|-------------|
|
||||
| `archeflow:colette-bridge` | Bridges ArcheFlow with the Colette writing platform |
|
||||
| `archeflow:git-integration` | Git-per-phase commits, branch-per-run, rollback to any phase boundary |
|
||||
| `archeflow:multi-project` | Cross-repo orchestration with dependency DAG and shared budget |
|
||||
|
||||
### Configuration
|
||||
|
||||
| Skill | Description |
|
||||
|-------|-------------|
|
||||
| `archeflow:custom-archetypes` | Create domain-specific roles (database reviewer, compliance auditor, etc.) |
|
||||
| `archeflow:workflow-design` | Design custom workflows with per-phase archetype assignment and exit conditions |
|
||||
| `archeflow:domains` | Domain adapters for writing, research, and other non-code workflows |
|
||||
| `archeflow:cost-tracking` | Budget enforcement, per-agent cost aggregation, model tier recommendations |
|
||||
| `archeflow:templates` | Template gallery for sharing workflows, teams, and setup bundles |
|
||||
| `archeflow:autonomous-mode` | Unattended overnight sessions with progress logging and safe stopping |
|
||||
|
||||
### Meta
|
||||
|
||||
| Skill | Description |
|
||||
|-------|-------------|
|
||||
| `archeflow:using-archeflow` | Session-start skill -- activation criteria, workflow selection, quick reference |
|
||||
|
||||
## Library Scripts
|
||||
|
||||
Eight shell scripts in `lib/` power the process infrastructure.
|
||||
|
||||
| Script | Purpose | Usage |
|
||||
|--------|---------|-------|
|
||||
| `archeflow-event.sh` | Append structured JSONL events to a run log | `archeflow-event.sh <run_id> <type> <phase> <agent> '<json>'` |
|
||||
| `archeflow-dag.sh` | Render ASCII DAG from JSONL events | `archeflow-dag.sh events.jsonl --color` |
|
||||
| `archeflow-report.sh` | Generate Markdown process report | `archeflow-report.sh events.jsonl --output report.md --dag` |
|
||||
| `archeflow-progress.sh` | Regenerate live progress file from events | `archeflow-progress.sh <run_id>` |
|
||||
| `archeflow-score.sh` | Score archetype effectiveness from completed runs | `archeflow-score.sh extract events.jsonl` |
|
||||
| `archeflow-memory.sh` | Cross-run memory: add, list, decay, inject lessons | `archeflow-memory.sh add "Always check for null"` |
|
||||
| `archeflow-git.sh` | Per-phase commits, branch creation, merge, rollback | `archeflow-git.sh commit <run_id> <phase>` |
|
||||
| `archeflow-init.sh` | Template gallery: init, save, clone, list | `archeflow-init.sh init writing-short-story` |
|
||||
|
||||
## Workflows
|
||||
|
||||
### Built-in Workflows
|
||||
|
||||
| Workflow | Cycles | Archetypes | Best For |
|
||||
|----------|:---:|------------|----------|
|
||||
|----------|:------:|------------|----------|
|
||||
| `fast` | 1 | Creator, Maker, Guardian | Bug fixes, small changes |
|
||||
| `standard` | 2 | Explorer + Creator, Maker, Guardian + Skeptic + Sage | Features, refactors |
|
||||
| `thorough` | 3 | Explorer + Creator, Maker, All 4 reviewers | Security-critical, public APIs |
|
||||
|
||||
ArcheFlow picks the workflow automatically, or you can specify:
|
||||
ArcheFlow picks the workflow automatically based on task complexity, or you can specify:
|
||||
|
||||
```
|
||||
"Implement input validation for the API (use thorough workflow)"
|
||||
> Implement input validation for the API (use thorough workflow)
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
### Just describe your task
|
||||
|
||||
```
|
||||
> Add user authentication with JWT tokens
|
||||
|
||||
# ArcheFlow activates automatically:
|
||||
# Explorer researches auth patterns in codebase
|
||||
# Creator designs JWT implementation
|
||||
# Maker implements in worktree
|
||||
# Guardian reviews for security
|
||||
# Skeptic challenges JWT assumptions
|
||||
# Sage checks code quality
|
||||
# All approved → merged to main
|
||||
```
|
||||
|
||||
### Force a workflow
|
||||
|
||||
```
|
||||
> Fix the off-by-one error in pagination (use fast workflow)
|
||||
```
|
||||
|
||||
### Autonomous mode — queue tasks and walk away
|
||||
|
||||
```
|
||||
> Enter autonomous mode with these tasks:
|
||||
> 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)
|
||||
```
|
||||
|
||||
### Dry run
|
||||
|
||||
```
|
||||
> What would ArcheFlow do for "Add JWT authentication"?
|
||||
|
||||
Dry run for: "Add JWT authentication"
|
||||
Workflow: standard (2 cycles)
|
||||
Agents: Explorer → Creator → Maker → Guardian + Skeptic + Sage
|
||||
Est. agents: 6 per cycle, 12 max
|
||||
Worktree: yes (isolated branch)
|
||||
Proceed? [y/n]
|
||||
```
|
||||
|
||||
## When ArcheFlow Activates (and When It Doesn't)
|
||||
|
||||
**Activates for:** New features (2+ files), refactoring, security changes, bug fixes with unclear root cause, code review requests.
|
||||
|
||||
**Stays out of the way for:** Single-line fixes, answering questions, exploring code, single-file configs, git operations.
|
||||
|
||||
## Key Features
|
||||
|
||||
**Cross-Cycle Feedback** — When a reviewer rejects, findings are structured and routed to the right agent. Guardian findings go to Creator (design must change). Sage findings go to Maker (implementation refinement). Resolution is tracked across cycles.
|
||||
|
||||
**Attention Filters** — Each archetype receives only relevant context. Guardian gets the diff + risk section, not the full research report. Saves 30-50% tokens per agent.
|
||||
|
||||
**Shadow Detection** — Quantitative thresholds detect dysfunction. Explorer output >2000 words without a recommendation? Rabbit Hole. Guardian blocking everything? Paranoid. First detection: correction prompt. Second: replace agent. Third: escalate to user.
|
||||
|
||||
**Workflow Adaptation** — Workflows adjust at runtime. If Guardian finds 2+ CRITICALs in a fast workflow, it escalates to standard. If Guardian finds nothing in standard, it fast-paths past the remaining reviewers.
|
||||
|
||||
**Parallel Teams** — Run up to 3 independent tasks through their own PDCA cycles simultaneously. Each team gets its own worktree. First-finished-first-merged.
|
||||
|
||||
## Extending ArcheFlow
|
||||
|
||||
### Custom Archetypes
|
||||
|
||||
Add domain-specific roles (database reviewer, compliance auditor, etc.). Put them in your project's `.archeflow/archetypes/`:
|
||||
|
||||
```markdown
|
||||
# .archeflow/archetypes/db-specialist.md
|
||||
---
|
||||
name: db-specialist
|
||||
description: Reviews database schemas and migration safety
|
||||
model: sonnet
|
||||
---
|
||||
|
||||
You are the **Database Specialist**.
|
||||
Your lens: "Will this scale? Will this corrupt data?"
|
||||
...
|
||||
```
|
||||
Workflows adapt at runtime. If Guardian finds 2+ CRITICALs in a fast workflow, it escalates to standard. If reviewers find nothing in standard, it fast-paths past the remaining cycle.
|
||||
|
||||
### Custom Workflows
|
||||
|
||||
Define your own workflows in `.archeflow/workflows/`:
|
||||
|
||||
```yaml
|
||||
# .archeflow/workflows/api-design.yaml
|
||||
name: api-design
|
||||
@@ -161,67 +187,151 @@ pdca:
|
||||
act: { exit_when: all_approved, max_cycles: 2 }
|
||||
```
|
||||
|
||||
See `examples/` for complete examples including custom archetypes, team presets, and workflows.
|
||||
### Example: Short Fiction Workflow
|
||||
|
||||
## Skills Reference
|
||||
ArcheFlow is not limited to code. The included `kurzgeschichte` workflow orchestrates short story development with custom archetypes (story-explorer, story-sage), Colette voice profile integration, and scene-by-scene commits:
|
||||
|
||||
| Skill | What it does |
|
||||
|-------|-------------|
|
||||
| `archeflow:orchestration` | Step-by-step PDCA execution guide |
|
||||
| `archeflow:shadow-detection` | Dysfunction detection and correction |
|
||||
| `archeflow:autonomous-mode` | Unattended overnight sessions |
|
||||
| `archeflow:plan-phase` | Explorer + Creator output formats |
|
||||
| `archeflow:do-phase` | Maker implementation rules |
|
||||
| `archeflow:check-phase` | Shared reviewer protocols |
|
||||
| `archeflow:attention-filters` | Context optimization per archetype |
|
||||
| `archeflow:custom-archetypes` | Creating domain-specific roles |
|
||||
| `archeflow:workflow-design` | Designing custom workflows |
|
||||
```yaml
|
||||
# examples/workflows/kurzgeschichte.yaml
|
||||
name: kurzgeschichte
|
||||
team: story-development
|
||||
phases:
|
||||
plan:
|
||||
archetypes: [story-explorer, creator]
|
||||
do:
|
||||
archetypes: [maker]
|
||||
check:
|
||||
archetypes: [guardian, story-sage]
|
||||
act:
|
||||
exit_when: all_approved
|
||||
max_cycles: 2
|
||||
```
|
||||
|
||||
## Plugin Structure
|
||||
## Domain Adapters
|
||||
|
||||
ArcheFlow defaults to code-oriented terminology, but domain adapters remap concepts for other workflows:
|
||||
|
||||
| Domain | What Changes |
|
||||
|--------|-------------|
|
||||
| `code` | Default. Diffs, tests, security review, merge to main. |
|
||||
| `writing` | Prose quality, voice consistency, dialect authenticity. Auto-activates when `colette.yaml` is detected. |
|
||||
| `research` | Source quality, argument coherence, citation accuracy. |
|
||||
|
||||
Custom domains can be defined in `.archeflow/domains/`.
|
||||
|
||||
## Examples
|
||||
|
||||
The `examples/` directory contains complete walkthroughs:
|
||||
|
||||
- `feature-implementation.md` -- End-to-end feature build with standard workflow
|
||||
- `security-review.md` -- Thorough review of security-sensitive code
|
||||
- `custom-workflow.yaml` -- Template for defining your own workflow
|
||||
- `custom-archetypes/` -- Story-explorer and story-sage for fiction writing
|
||||
- `teams/` -- Team preset for story development
|
||||
- `workflows/kurzgeschichte.yaml` -- Short fiction workflow with Colette integration
|
||||
|
||||
## Configuration
|
||||
|
||||
### Project Configuration
|
||||
|
||||
Create `.archeflow/config.yaml` in your project root:
|
||||
|
||||
```yaml
|
||||
workflow: standard # Default workflow
|
||||
budget: 50000 # Max tokens per run
|
||||
git:
|
||||
enabled: true # Per-phase commits
|
||||
merge_strategy: squash # squash or no-ff
|
||||
```
|
||||
|
||||
### Custom Archetypes
|
||||
|
||||
Add domain-specific roles in `.archeflow/archetypes/`:
|
||||
|
||||
```markdown
|
||||
# .archeflow/archetypes/db-specialist.md
|
||||
---
|
||||
name: db-specialist
|
||||
description: Reviews database schemas and migration safety
|
||||
model: sonnet
|
||||
---
|
||||
|
||||
You are the **Database Specialist**.
|
||||
Your lens: "Will this scale? Will this corrupt data?"
|
||||
```
|
||||
|
||||
### Team Presets
|
||||
|
||||
Define reusable teams in `.archeflow/teams/`:
|
||||
|
||||
```yaml
|
||||
# .archeflow/teams/backend-review.yaml
|
||||
name: backend-review
|
||||
archetypes: [explorer, creator, maker, guardian, db-specialist]
|
||||
```
|
||||
|
||||
### Environment Variables
|
||||
|
||||
- `ARCHEFLOW_BUDGET` -- Override default token budget
|
||||
- `ARCHEFLOW_WORKFLOW` -- Override default workflow selection
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
archeflow/
|
||||
├── .claude-plugin/plugin.json # Plugin manifest
|
||||
├── agents/ # 7 archetype personas
|
||||
│ ├── explorer.md
|
||||
│ ├── creator.md
|
||||
│ ├── maker.md
|
||||
│ ├── guardian.md
|
||||
│ ├── skeptic.md
|
||||
│ ├── trickster.md
|
||||
│ └── sage.md
|
||||
├── skills/ # 10 behavioral skills
|
||||
│ ├── using-archeflow/ # Auto-loaded at session start
|
||||
│ ├── orchestration/ # PDCA execution guide
|
||||
│ ├── plan-phase/ # Plan phase protocols
|
||||
│ ├── do-phase/ # Do phase protocols
|
||||
│ ├── check-phase/ # Check phase protocols
|
||||
├── .claude-plugin/plugin.json # Plugin manifest (v0.3.0)
|
||||
├── agents/ # 7 archetype personas (behavioral protocols)
|
||||
│ ├── explorer.md # Plan: research and context mapping
|
||||
│ ├── creator.md # Plan: solution design and proposals
|
||||
│ ├── maker.md # Do: implementation in isolated worktree
|
||||
│ ├── guardian.md # Check: security and reliability review
|
||||
│ ├── skeptic.md # Check: assumption challenging
|
||||
│ ├── trickster.md # Check: adversarial testing
|
||||
│ └── sage.md # Check: holistic quality review
|
||||
├── skills/ # 24 behavioral skills
|
||||
│ ├── run/ # Automated PDCA loop
|
||||
│ ├── orchestration/ # Manual PDCA execution guide
|
||||
│ ├── plan-phase/ # Plan protocols
|
||||
│ ├── do-phase/ # Do protocols
|
||||
│ ├── check-phase/ # Check protocols
|
||||
│ ├── act-phase/ # Act phase decision logic
|
||||
│ ├── shadow-detection/ # Dysfunction detection
|
||||
│ ├── attention-filters/ # Context optimization
|
||||
│ ├── convergence/ # Cycle convergence detection
|
||||
│ ├── artifact-routing/ # Inter-phase artifact protocol
|
||||
│ ├── process-log/ # Event-sourced JSONL logging
|
||||
│ ├── memory/ # Cross-run learning
|
||||
│ ├── effectiveness/ # Archetype scoring
|
||||
│ ├── progress/ # Live progress file
|
||||
│ ├── colette-bridge/ # Colette writing platform bridge
|
||||
│ ├── git-integration/ # Per-phase git commits
|
||||
│ ├── multi-project/ # Cross-repo orchestration
|
||||
│ ├── custom-archetypes/ # Domain-specific roles
|
||||
│ ├── workflow-design/ # Custom workflow design
|
||||
│ ├── domains/ # Domain adapters
|
||||
│ ├── cost-tracking/ # Budget and cost management
|
||||
│ ├── templates/ # Template gallery
|
||||
│ ├── autonomous-mode/ # Unattended sessions
|
||||
│ ├── custom-archetypes/ # Creating new roles
|
||||
│ └── workflow-design/ # Custom workflows
|
||||
├── hooks/ # Auto-activation
|
||||
│ ├── hooks.json
|
||||
│ └── session-start
|
||||
├── examples/ # Walkthroughs + templates
|
||||
│ ├── feature-implementation.md
|
||||
│ ├── security-review.md
|
||||
│ ├── custom-workflow.yaml
|
||||
│ ├── custom-archetypes/
|
||||
│ ├── teams/
|
||||
│ └── workflows/
|
||||
└── docs/
|
||||
└── roadmap.md
|
||||
│ └── using-archeflow/ # Session-start activation
|
||||
├── lib/ # 8 shell scripts (process infrastructure)
|
||||
├── hooks/ # Auto-activation (SessionStart)
|
||||
├── examples/ # Walkthroughs, templates, custom archetypes
|
||||
└── docs/ # Roadmap, changelog
|
||||
```
|
||||
|
||||
The flow: skills define behavioral rules (what agents should do), agents define personas (how they think), lib scripts handle tooling (event logging, git, reporting), and hooks wire it all together at session start. Events are emitted at every phase transition, forming a DAG that can be rendered, reported, or scored after the run.
|
||||
|
||||
## Philosophy
|
||||
|
||||
1. **Strength has a shadow.** Every capability becomes destructive when unchecked. The Explorer who won't stop researching. The Guardian who blocks everything. The Maker who ships without review. ArcheFlow names these shadows and corrects them.
|
||||
1. **Strength has a shadow.** Every capability becomes destructive when unchecked. The Explorer who never stops researching. The Guardian who blocks everything. The Maker who ships without review. ArcheFlow names these shadows and corrects them automatically.
|
||||
|
||||
2. **Quality is a spiral, not a gate.** A single review pass misses things. PDCA cycles spiral upward — each cycle catches what the previous one missed, until the reviewers have nothing left to find.
|
||||
2. **Quality is a spiral, not a gate.** A single review pass misses things. PDCA cycles spiral upward -- each iteration catches what the previous one missed, until the reviewers have nothing left to find.
|
||||
|
||||
3. **Autonomy needs structure.** Agents given clear roles, typed communication, and quality gates produce exceptional work — even overnight, even unattended.
|
||||
3. **Autonomy needs structure.** Agents given clear roles, typed communication, and quality gates produce exceptional work -- even overnight, even unattended.
|
||||
|
||||
## Version History
|
||||
|
||||
See [CHANGELOG.md](CHANGELOG.md) for detailed release notes.
|
||||
|
||||
## License
|
||||
|
||||
|
||||
@@ -2,6 +2,34 @@
|
||||
|
||||
## Completed
|
||||
|
||||
### v0.3.0 (2026-04-03)
|
||||
- [x] Automated PDCA loop (`archeflow:run`) with `--start-from` and `--dry-run`
|
||||
- [x] Event-sourced process logging with DAG parent relationships
|
||||
- [x] ASCII DAG renderer and Markdown report generator
|
||||
- [x] Live progress file watchable from second terminal
|
||||
- [x] Domain adapter system (code, writing, research)
|
||||
- [x] Cost tracking with budget enforcement and model tier recommendations
|
||||
- [x] Cross-run memory system (recurring findings, lesson injection)
|
||||
- [x] Convergence detection (stalling, oscillation prevention)
|
||||
- [x] Colette writing platform bridge
|
||||
- [x] Template gallery (init, save, clone, list)
|
||||
- [x] Archetype effectiveness scoring
|
||||
- [x] Git-per-phase commit strategy with rollback
|
||||
- [x] Multi-project orchestration with dependency DAG and shared budget
|
||||
- [x] Act phase skill and artifact routing skill
|
||||
- [x] 8 library scripts (event, dag, report, progress, score, memory, git, init)
|
||||
- [x] Short fiction workflow example with custom archetypes
|
||||
|
||||
### v0.2.0 (2026-04-03)
|
||||
- [x] Plugin consolidation into single shareable directory
|
||||
- [x] Workflow intelligence (conditional escalation, fast-path, confidence triggers)
|
||||
- [x] Quality loop (self-review, convergence detection, dedup, completion promises)
|
||||
- [x] Parallel teams, auto-resume, budget scheduling
|
||||
- [x] Extensibility (archetype composition, team presets, hook points, workflow templates)
|
||||
- [x] Mini-reflect fallback (Ralph Loop integration)
|
||||
- [x] DX improvements and comprehensive README
|
||||
|
||||
### v0.1.0 (2026-04-02)
|
||||
- [x] Core archetypes (7) with shadow detection
|
||||
- [x] PDCA cycle engine with fast/standard/thorough workflows
|
||||
- [x] Cross-cycle structured feedback with routing and resolution tracking
|
||||
@@ -9,12 +37,8 @@
|
||||
- [x] Shadow detection with quantitative checklists
|
||||
- [x] Orchestration metrics (timing, agent count, findings)
|
||||
- [x] Autonomous mode integrated into orchestration flow
|
||||
- [x] Plugin consolidation (single `archeflow/` directory)
|
||||
- [x] Workflow intelligence (conditional escalation, fast-path, confidence triggers)
|
||||
- [x] Quality loop (self-review, convergence detection, dedup, completion promises)
|
||||
- [x] Parallel teams, auto-resume, budget scheduling
|
||||
- [x] Extensibility (archetype composition, team presets, hook points, workflow templates)
|
||||
- [x] Mini-reflect for non-ArcheFlow changes
|
||||
- [x] Custom archetypes and workflow design skills
|
||||
- [x] SessionStart hook for auto-activation
|
||||
|
||||
## Future
|
||||
|
||||
@@ -26,7 +50,8 @@
|
||||
|
||||
## Version History
|
||||
|
||||
| Date | Changes |
|
||||
|------|---------|
|
||||
| 2026-04-03 | v0.2 — Plugin consolidation, shareable structure, examples |
|
||||
| 2026-04-03 | v0.1 — Full feature set: 7 archetypes, 10 skills, PDCA workflows, shadow detection, autonomous mode, extensibility |
|
||||
| Date | Version | Changes |
|
||||
|------|---------|---------|
|
||||
| 2026-04-03 | v0.3.0 | Process infrastructure: run automation, event sourcing, domain adapters, memory, multi-project, 8 lib scripts |
|
||||
| 2026-04-03 | v0.2.0 | Plugin consolidation, workflow intelligence, quality loop, parallel teams, extensibility |
|
||||
| 2026-04-02 | v0.1.0 | Initial release: 7 archetypes, 9 core skills, PDCA workflows, shadow detection, autonomous mode |
|
||||
|
||||
@@ -3,7 +3,7 @@ name: using-archeflow
|
||||
description: Use at session start when implementing features, reviewing code, debugging, or any task that benefits from multiple perspectives. Activates ArcheFlow multi-agent orchestration.
|
||||
---
|
||||
|
||||
# ArcheFlow — Active
|
||||
# ArcheFlow -- Active
|
||||
|
||||
Multi-agent orchestration using archetypal roles and PDCA quality cycles.
|
||||
|
||||
@@ -11,24 +11,24 @@ Multi-agent orchestration using archetypal roles and PDCA quality cycles.
|
||||
|
||||
You MUST use ArcheFlow orchestration (load `archeflow:orchestration` skill and follow its steps) for any task that matches:
|
||||
|
||||
- **New features** — any feature touching 2+ files
|
||||
- **Refactoring** — structural changes across modules
|
||||
- **Security-sensitive changes** — auth, encryption, input handling, API keys
|
||||
- **Bug fixes with unclear root cause** — use Explorer to investigate first
|
||||
- **Code review requests** — spawn Guardian + relevant reviewers
|
||||
- **Multi-file changes** — anything beyond a single-file edit
|
||||
- **New features** -- any feature touching 2+ files
|
||||
- **Refactoring** -- structural changes across modules
|
||||
- **Security-sensitive changes** -- auth, encryption, input handling, API keys
|
||||
- **Bug fixes with unclear root cause** -- use Explorer to investigate first
|
||||
- **Code review requests** -- spawn Guardian + relevant reviewers
|
||||
- **Multi-file changes** -- anything beyond a single-file edit
|
||||
|
||||
Choose the workflow based on risk:
|
||||
|
||||
| Signal | Workflow | Command |
|
||||
|--------|----------|---------|
|
||||
| Small fix, low risk, single concern | `fast` | Creator → Maker → Guardian |
|
||||
| Feature, multiple files, moderate risk | `standard` | Explorer + Creator → Maker → Guardian + Skeptic + Sage |
|
||||
| Security-sensitive, breaking changes, public API | `thorough` | Explorer + Creator → Maker → All 4 reviewers |
|
||||
| Small fix, low risk, single concern | `fast` | Creator --> Maker --> Guardian |
|
||||
| Feature, multiple files, moderate risk | `standard` | Explorer + Creator --> Maker --> Guardian + Skeptic + Sage |
|
||||
| Security-sensitive, breaking changes, public API | `thorough` | Explorer + Creator --> Maker --> All 4 reviewers |
|
||||
|
||||
## When to Skip ArcheFlow
|
||||
|
||||
Do NOT use ArcheFlow for these — just do them directly:
|
||||
Do NOT use ArcheFlow for these -- just do them directly:
|
||||
|
||||
- Single-line fixes, typos, formatting
|
||||
- Answering questions (no code changes)
|
||||
@@ -53,10 +53,10 @@ Do NOT use ArcheFlow for these — just do them directly:
|
||||
## PDCA Cycle
|
||||
|
||||
```
|
||||
Plan → Explorer researches, Creator proposes
|
||||
Do → Maker implements in isolated worktree
|
||||
Check → Reviewers assess in parallel (approve/reject)
|
||||
Act → All approved? Merge. Issues? Cycle back to Plan.
|
||||
Plan --> Explorer researches, Creator proposes
|
||||
Do --> Maker implements in isolated worktree
|
||||
Check --> Reviewers assess in parallel (approve/reject)
|
||||
Act --> All approved? Merge. Issues? Cycle back to Plan.
|
||||
```
|
||||
|
||||
## Progress Indicators
|
||||
@@ -64,18 +64,18 @@ Act → All approved? Merge. Issues? Cycle back to Plan.
|
||||
During orchestration, emit phase markers so the user can track progress:
|
||||
|
||||
```
|
||||
━━━ ArcheFlow: <task> ━━━━━━━━━━━━━━━━━━━
|
||||
📋 Workflow: standard (2 cycles max)
|
||||
--- ArcheFlow: <task> -------------------------
|
||||
Workflow: standard (2 cycles max)
|
||||
|
||||
🔍 [Plan] Explorer researching... ✓ done (35s)
|
||||
🏗️ [Plan] Creator designing proposal... ✓ done (25s, confidence: 0.8)
|
||||
⚒️ [Do] Maker implementing... ✓ done (90s, 4 files, 8 tests)
|
||||
🛡️ [Check] Guardian reviewing... ✓ APPROVED
|
||||
🤔 [Check] Skeptic challenging... ✓ APPROVED (1 INFO)
|
||||
📚 [Check] Sage reviewing... ✓ APPROVED
|
||||
✅ [Act] All approved — merging... ✓ merged to main
|
||||
🔍 [Plan] Explorer researching... done (35s)
|
||||
🏗️ [Plan] Creator designing proposal... done (25s, confidence: 0.8)
|
||||
⚒️ [Do] Maker implementing... done (90s, 4 files, 8 tests)
|
||||
🛡️ [Check] Guardian reviewing... APPROVED
|
||||
🤔 [Check] Skeptic challenging... APPROVED (1 INFO)
|
||||
📚 [Check] Sage reviewing... APPROVED
|
||||
[Act] All approved -- merging... merged to main
|
||||
|
||||
━━━ Complete: 3m 10s, 1 cycle ━━━━━━━━━━━
|
||||
--- Complete: 3m 10s, 1 cycle -----------------
|
||||
```
|
||||
|
||||
Update each line as agents complete. This gives the user real-time visibility without interrupting the flow.
|
||||
@@ -87,7 +87,7 @@ When the user asks "what would ArcheFlow do?" or uses `--dry-run`, show the plan
|
||||
```
|
||||
Dry run for: "Add JWT authentication"
|
||||
Workflow: standard (2 cycles)
|
||||
Agents: 🔍 Explorer → 🏗️ Creator → ⚒️ Maker → 🛡️ Guardian + 🤔 Skeptic + 📚 Sage
|
||||
Agents: 🔍 Explorer --> 🏗️ Creator --> ⚒️ Maker --> 🛡️ Guardian + 🤔 Skeptic + 📚 Sage
|
||||
Est. agents: 6 per cycle, 12 max
|
||||
Worktree: yes (isolated branch)
|
||||
Proceed? [y/n]
|
||||
@@ -103,31 +103,61 @@ When the user gives an implementation task:
|
||||
4. Execute the PDCA steps from the orchestration skill
|
||||
5. Emit progress indicators throughout (see above)
|
||||
|
||||
## Commands
|
||||
## Available Commands
|
||||
|
||||
| Command | What it does |
|
||||
|---------|-------------|
|
||||
| `/archeflow:orchestration` | Load and run a full PDCA orchestration |
|
||||
| `/archeflow:status` | Show current orchestration state (phase, cycle, active agents) |
|
||||
| `/archeflow:history` | Show past orchestration summaries from `.archeflow/session-log.md` |
|
||||
| `/archeflow:shadow-detection` | Load shadow monitoring rules |
|
||||
| `/archeflow:autonomous-mode` | Load autonomous/overnight session protocol |
|
||||
| `archeflow:run` | Automated PDCA loop -- single command to orchestrate a full run |
|
||||
| `archeflow:orchestration` | Load manual PDCA execution guide |
|
||||
| `archeflow:shadow-detection` | Load shadow monitoring rules |
|
||||
| `archeflow:autonomous-mode` | Load autonomous/overnight session protocol |
|
||||
| `archeflow:status` | Show current orchestration state (phase, cycle, active agents) |
|
||||
| `archeflow:history` | Show past orchestration summaries from `.archeflow/session-log.md` |
|
||||
|
||||
### `/archeflow:status`
|
||||
### `archeflow:status`
|
||||
Read `.archeflow/state.json` (if exists) and report:
|
||||
- Current task, phase, and cycle
|
||||
- Active agents and their status
|
||||
- Findings so far (by severity)
|
||||
- Time elapsed
|
||||
|
||||
### `/archeflow:history`
|
||||
### `archeflow:history`
|
||||
Read `.archeflow/session-log.md` and show the last 5 orchestration summaries in compact format.
|
||||
|
||||
## Skills Reference
|
||||
## Skills Reference (All 24)
|
||||
|
||||
- **archeflow:orchestration** — Step-by-step execution guide (load this to run)
|
||||
- **archeflow:plan-phase** / **do-phase** / **check-phase** — Phase protocols
|
||||
- **archeflow:shadow-detection** — Recognizing and correcting dysfunction
|
||||
- **archeflow:attention-filters** — What context each archetype receives
|
||||
- **archeflow:autonomous-mode** — Unattended sessions
|
||||
- **archeflow:custom-archetypes** / **workflow-design** — Extending ArcheFlow
|
||||
### Core Orchestration
|
||||
- **archeflow:run** -- Automated PDCA execution loop with `--start-from` and `--dry-run`
|
||||
- **archeflow:orchestration** -- Step-by-step manual execution guide
|
||||
- **archeflow:plan-phase** -- Explorer and Creator output formats and protocols
|
||||
- **archeflow:do-phase** -- Maker implementation rules and worktree commit strategy
|
||||
- **archeflow:check-phase** -- Shared reviewer protocols and output format
|
||||
- **archeflow:act-phase** -- Post-Check decision logic: collect findings, route fixes, exit or cycle
|
||||
|
||||
### Quality and Safety
|
||||
- **archeflow:shadow-detection** -- Quantitative dysfunction detection and correction
|
||||
- **archeflow:attention-filters** -- Context optimization per archetype
|
||||
- **archeflow:convergence** -- Detects convergence, stalling, and oscillation in multi-cycle runs
|
||||
- **archeflow:artifact-routing** -- Inter-phase artifact protocol for naming, storage, and routing
|
||||
|
||||
### Process Intelligence
|
||||
- **archeflow:process-log** -- Event-sourced JSONL logging with DAG parent relationships
|
||||
- **archeflow:memory** -- Cross-run learning from recurring findings
|
||||
- **archeflow:effectiveness** -- Archetype scoring on signal-to-noise, fix rate, cost efficiency
|
||||
- **archeflow:progress** -- Live progress file watchable from a second terminal
|
||||
|
||||
### Integration
|
||||
- **archeflow:colette-bridge** -- Bridges ArcheFlow with the Colette writing platform
|
||||
- **archeflow:git-integration** -- Git-per-phase commits, branch-per-run, rollback
|
||||
- **archeflow:multi-project** -- Cross-repo orchestration with dependency DAG and shared budget
|
||||
|
||||
### Configuration
|
||||
- **archeflow:custom-archetypes** -- Create domain-specific roles
|
||||
- **archeflow:workflow-design** -- Design custom workflows with per-phase archetype assignment
|
||||
- **archeflow:domains** -- Domain adapters for writing, research, and non-code workflows
|
||||
- **archeflow:cost-tracking** -- Budget enforcement and model tier recommendations
|
||||
- **archeflow:templates** -- Template gallery for sharing workflows, teams, and setup bundles
|
||||
- **archeflow:autonomous-mode** -- Unattended overnight sessions
|
||||
|
||||
### Meta
|
||||
- **archeflow:using-archeflow** -- This skill: session-start activation and quick reference
|
||||
|
||||
Reference in New Issue
Block a user