feat: DX, extensibility, and adaptive intelligence — completes 25-feature backlog
Sprint 5 — Developer Experience (D1-D5): - Progress indicators with emoji phase markers during orchestration - Dry-run mode: preview workflow without executing - /archeflow:status and /archeflow:history commands - Onboarding skill for first-time users Sprint 6 — Extensibility (E1-E4, A4-A6): - Archetype composition: combine 2 archetypes into super-reviewer - Team presets: save common team configs in .archeflow/teams/ - Hook points: pre-plan, post-check, pre-merge, post-merge custom validation - Workflow template library: api-design, migration, dep-upgrade, docs, hotfix - Reviewer profiles: per-project config of which reviewers run - Explorer cache: skip redundant research on recently-explored code - Learning from history: track archetype usefulness, recommend profile changes
This commit is contained in:
@@ -138,9 +138,68 @@ Agent(
|
||||
|
||||
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)
|
||||
- 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/`:
|
||||
|
||||
```yaml
|
||||
# .archeflow/teams/backend.yaml
|
||||
name: backend
|
||||
description: Standard backend development team
|
||||
plan: [explorer, creator]
|
||||
do: [maker]
|
||||
check: [guardian, sage]
|
||||
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
|
||||
```
|
||||
|
||||
Use in orchestration: `"Use the backend team preset"` or `"Run security-audit workflow on this change"`
|
||||
|
||||
## 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.
|
||||
|
||||
46
skills/onboarding/SKILL.md
Normal file
46
skills/onboarding/SKILL.md
Normal file
@@ -0,0 +1,46 @@
|
||||
---
|
||||
name: onboarding
|
||||
description: Use when a user is new to ArcheFlow or asks "what is this?" / "how does this work?". Explains the plugin in 60 seconds.
|
||||
---
|
||||
|
||||
# Welcome to ArcheFlow
|
||||
|
||||
ArcheFlow is a Claude Code plugin that automatically coordinates multiple AI agents when you give implementation tasks. Instead of one agent doing everything, specialized agents with different perspectives collaborate through quality cycles.
|
||||
|
||||
## What Just Happened
|
||||
|
||||
When you installed ArcheFlow, it activated automatically. From now on:
|
||||
|
||||
- **Give an implementation task** (feature, refactor, bug fix) → ArcheFlow kicks in
|
||||
- **Give a quick task** (typo fix, question, config edit) → Claude handles it normally
|
||||
|
||||
You don't need to do anything different. Just describe your task.
|
||||
|
||||
## The 30-Second Version
|
||||
|
||||
```
|
||||
You: "Add user authentication with JWT"
|
||||
|
||||
ArcheFlow:
|
||||
🔍 Explorer researches your codebase (what files, what patterns, what tests)
|
||||
<20><>️ Creator designs a proposal (architecture, file changes, test strategy)
|
||||
⚒️ Maker implements it in a safe branch (isolated, nothing breaks)
|
||||
🛡️ Guardian reviews for security (injection, auth bypass, data exposure)
|
||||
🤔 Skeptic challenges assumptions (what if JWT isn't the right choice?)
|
||||
📚 Sage checks quality (readable? tested? consistent with codebase?)
|
||||
✅ All approve → merged. Issues? → automatic revision cycle.
|
||||
```
|
||||
|
||||
## Key Concepts
|
||||
|
||||
- **Archetypes:** 7 specialized agent roles, each with a unique perspective
|
||||
- **PDCA Cycles:** Plan → Do → Check → Act. If reviewers reject, it cycles back and improves
|
||||
- **Worktrees:** Code changes happen on isolated branches. Nothing touches main until approved.
|
||||
- **Shadow Detection:** If an agent gets stuck or dysfunctional, ArcheFlow detects and corrects it
|
||||
- **Workflows:** `fast` (1 cycle, quick fixes), `standard` (2 cycles, features), `thorough` (3 cycles, security)
|
||||
|
||||
## Want to Learn More?
|
||||
|
||||
- `/archeflow:orchestration` — See the full step-by-step execution guide
|
||||
- `/archeflow:shadow-detection` — How dysfunction is detected and corrected
|
||||
- `/archeflow:autonomous-mode` — Run tasks overnight unattended
|
||||
@@ -460,6 +460,51 @@ Each team follows the full PDCA steps independently. The orchestrator monitors a
|
||||
|
||||
---
|
||||
|
||||
## Reviewer Profiles
|
||||
|
||||
Projects can configure which reviewers matter in `.archeflow/config.yaml`:
|
||||
|
||||
```yaml
|
||||
reviewers:
|
||||
always: [guardian] # Always runs
|
||||
default: [sage] # Runs in standard+thorough
|
||||
thorough_only: [trickster] # Only in thorough
|
||||
skip: [skeptic] # Never runs for this project
|
||||
```
|
||||
|
||||
If no config exists, use the built-in workflow defaults. Profiles save tokens by not spawning reviewers that add little value for the specific project.
|
||||
|
||||
## Explorer Cache
|
||||
|
||||
If the same code area was explored recently, skip Explorer and reuse prior research:
|
||||
|
||||
**Cache hit criteria:** Same files affected (>70% overlap by path) AND prior research is <24 hours old AND no commits to those files since the research.
|
||||
|
||||
**On cache hit:** Show the prior research to Creator with a note: "Using cached Explorer research from [timestamp]. If the codebase changed significantly, re-run Explorer."
|
||||
|
||||
**On cache miss:** Run Explorer normally.
|
||||
|
||||
Cache is stored in `.archeflow/explorer-cache/` as timestamped markdown files. The orchestrator checks for matches before spawning Explorer.
|
||||
|
||||
## Learning from History
|
||||
|
||||
Track which archetypes catch real issues per project over time. After each orchestration, append to `.archeflow/metrics.jsonl`:
|
||||
|
||||
```json
|
||||
{"task": "...", "archetype": "guardian", "findings": 2, "critical": 1, "resolved": 2, "useful": true}
|
||||
{"task": "...", "archetype": "skeptic", "findings": 3, "critical": 0, "resolved": 0, "useful": false}
|
||||
```
|
||||
|
||||
A finding is **useful** if it was resolved (led to a code change) rather than dismissed.
|
||||
|
||||
After 10+ orchestrations, the orchestrator can recommend reviewer profile changes:
|
||||
- "Skeptic has found 0 useful issues in 8 runs — consider moving to `skip` or `thorough_only`"
|
||||
- "Guardian catches critical issues in 80% of runs — confirmed as essential"
|
||||
|
||||
This is advisory, not automatic. The user decides based on the data.
|
||||
|
||||
---
|
||||
|
||||
## Orchestration Report
|
||||
|
||||
After completion, summarize:
|
||||
|
||||
@@ -59,6 +59,40 @@ Check → Reviewers assess in parallel (approve/reject)
|
||||
Act → All approved? Merge. Issues? Cycle back to Plan.
|
||||
```
|
||||
|
||||
## Progress Indicators
|
||||
|
||||
During orchestration, emit phase markers so the user can track progress:
|
||||
|
||||
```
|
||||
━━━ 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
|
||||
|
||||
━━━ Complete: 3m 10s, 1 cycle ━━━━━━━━━━━
|
||||
```
|
||||
|
||||
Update each line as agents complete. This gives the user real-time visibility without interrupting the flow.
|
||||
|
||||
## Dry-Run Mode
|
||||
|
||||
When the user asks "what would ArcheFlow do?" or uses `--dry-run`, show the plan without executing:
|
||||
|
||||
```
|
||||
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]
|
||||
```
|
||||
|
||||
## Quick Start
|
||||
|
||||
When the user gives an implementation task:
|
||||
@@ -67,6 +101,27 @@ When the user gives an implementation task:
|
||||
2. If yes: load `archeflow:orchestration` skill
|
||||
3. Pick workflow (fast/standard/thorough)
|
||||
4. Execute the PDCA steps from the orchestration skill
|
||||
5. Emit progress indicators throughout (see above)
|
||||
|
||||
## 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: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`
|
||||
Read `.archeflow/session-log.md` and show the last 5 orchestration summaries in compact format.
|
||||
|
||||
## Skills Reference
|
||||
|
||||
|
||||
@@ -129,6 +129,112 @@ Check: Guardian
|
||||
Exit: no_critical, max 1 cycle
|
||||
```
|
||||
|
||||
## Hook Points
|
||||
|
||||
Add project-specific validation at key moments in the PDCA cycle. Define hooks 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 |
|
||||
|------|------|-------------|
|
||||
| `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 |
|
||||
|
||||
## 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"
|
||||
```
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
- **Kitchen sink:** Putting all 7 archetypes in Check. Most can't add value simultaneously.
|
||||
|
||||
Reference in New Issue
Block a user