feat: ArcheFlow — multi-agent orchestration plugin for Claude Code
Zero-dependency Claude Code plugin using Jungian archetypes as behavioral protocols for multi-agent orchestration. - 7 archetypes (Explorer, Creator, Maker, Guardian, Skeptic, Trickster, Sage) - ArcheHelix: rising PDCA quality spiral with feedback loops - Shadow detection: automatic dysfunction recognition and correction - 3 built-in workflows (fast, standard, thorough) - Autonomous mode: unattended overnight sessions with full visibility - Custom archetypes and workflows via markdown/YAML - SessionStart hook for automatic bootstrap - Examples for feature implementation and security review
This commit is contained in:
186
skills/orchestration/SKILL.md
Normal file
186
skills/orchestration/SKILL.md
Normal file
@@ -0,0 +1,186 @@
|
||||
---
|
||||
name: orchestration
|
||||
description: Use when executing a multi-agent orchestration — spawning archetype agents, managing PDCA cycles, coordinating worktrees, and merging results. This is the step-by-step execution guide.
|
||||
---
|
||||
|
||||
# Orchestration Execution
|
||||
|
||||
This skill guides you through running a full ArcheFlow orchestration using Claude Code's native Agent tool and git worktrees.
|
||||
|
||||
## Step 0: Choose a Workflow
|
||||
|
||||
Assess the task and pick:
|
||||
|
||||
| Signal | Workflow |
|
||||
|--------|----------|
|
||||
| Small fix, low risk, single concern | `fast` (1 cycle) |
|
||||
| Feature, multiple files, moderate risk | `standard` (2 cycles) |
|
||||
| Security-sensitive, breaking changes, public API | `thorough` (3 cycles) |
|
||||
|
||||
## Step 1: Plan Phase
|
||||
|
||||
Spawn agents sequentially — Creator needs Explorer's findings.
|
||||
|
||||
### Explorer (if standard or thorough)
|
||||
```
|
||||
Agent(
|
||||
description: "Explorer: research context",
|
||||
prompt: "<task description>
|
||||
You are the EXPLORER archetype.
|
||||
Research the codebase to understand:
|
||||
1. What files and functions are involved
|
||||
2. What dependencies exist
|
||||
3. What tests currently cover this area
|
||||
4. What patterns the codebase uses
|
||||
Write your findings as a structured research report.
|
||||
Be thorough but focused — no rabbit holes.",
|
||||
subagent_type: "Explore"
|
||||
)
|
||||
```
|
||||
|
||||
### Creator
|
||||
```
|
||||
Agent(
|
||||
description: "Creator: design proposal",
|
||||
prompt: "<task description>
|
||||
You are the CREATOR archetype.
|
||||
Based on the research findings: <Explorer's output>
|
||||
Design a solution proposal including:
|
||||
1. Architecture decisions (with rationale)
|
||||
2. Files to create/modify (with specific changes)
|
||||
3. Test strategy
|
||||
4. Confidence score (0.0 to 1.0)
|
||||
5. Risks you foresee
|
||||
Be decisive. Ship a clear plan, not a menu of options.",
|
||||
subagent_type: "Plan"
|
||||
)
|
||||
```
|
||||
|
||||
## Step 2: Do Phase
|
||||
|
||||
Spawn Maker in an **isolated worktree** so changes don't affect main.
|
||||
|
||||
```
|
||||
Agent(
|
||||
description: "Maker: implement proposal",
|
||||
prompt: "<task description>
|
||||
You are the MAKER archetype.
|
||||
Implement this proposal: <Creator's output>
|
||||
Rules:
|
||||
1. Follow the proposal exactly — don't redesign
|
||||
2. Write tests for every behavioral change
|
||||
3. Commit with descriptive messages
|
||||
4. Run existing tests — nothing may break
|
||||
5. If the proposal is unclear, implement your best interpretation and note it
|
||||
Do NOT skip tests. Do NOT refactor unrelated code.",
|
||||
isolation: "worktree",
|
||||
mode: "bypassPermissions"
|
||||
)
|
||||
```
|
||||
|
||||
**Critical:** The Maker MUST commit its changes before finishing. Uncommitted changes in a worktree are lost.
|
||||
|
||||
## Step 3: Check Phase
|
||||
|
||||
Spawn reviewers **in parallel** — they read the Maker's changes independently.
|
||||
|
||||
### Guardian
|
||||
```
|
||||
Agent(
|
||||
description: "Guardian: security and risk review",
|
||||
prompt: "You are the GUARDIAN archetype.
|
||||
Review the changes in branch: <maker's branch>
|
||||
Assess:
|
||||
1. Security vulnerabilities (injection, auth bypass, data exposure)
|
||||
2. Reliability risks (error handling, edge cases, race conditions)
|
||||
3. Breaking changes (API compatibility, schema migrations)
|
||||
4. Dependency risks (new deps, version conflicts)
|
||||
Output: APPROVED or REJECTED with specific findings.
|
||||
Each finding needs: location, severity (critical/warning/info), description, fix suggestion.
|
||||
Be rigorous but practical — flag real risks, not theoretical ones."
|
||||
)
|
||||
```
|
||||
|
||||
### Skeptic (if standard or thorough)
|
||||
```
|
||||
Agent(
|
||||
description: "Skeptic: challenge assumptions",
|
||||
prompt: "You are the SKEPTIC archetype.
|
||||
Review the changes in branch: <maker's branch>
|
||||
Challenge:
|
||||
1. Assumptions in the design — what if they're wrong?
|
||||
2. Alternative approaches not considered
|
||||
3. Edge cases not tested
|
||||
4. Scalability concerns
|
||||
Output: APPROVED or REJECTED with counterarguments.
|
||||
Be constructive — every challenge must include a suggested alternative."
|
||||
)
|
||||
```
|
||||
|
||||
### Sage (if standard or thorough)
|
||||
```
|
||||
Agent(
|
||||
description: "Sage: holistic quality review",
|
||||
prompt: "You are the SAGE archetype.
|
||||
Review the changes in branch: <maker's branch>
|
||||
Evaluate holistically:
|
||||
1. Code quality (readability, maintainability, simplicity)
|
||||
2. Test coverage (are the tests meaningful, not just present?)
|
||||
3. Documentation (does the change need docs?)
|
||||
4. Consistency with codebase patterns
|
||||
Output: APPROVED or REJECTED with quality findings.
|
||||
Judge like a senior engineer doing a PR review."
|
||||
)
|
||||
```
|
||||
|
||||
### Trickster (if thorough only)
|
||||
```
|
||||
Agent(
|
||||
description: "Trickster: adversarial testing",
|
||||
prompt: "You are the TRICKSTER archetype.
|
||||
Try to break the changes in branch: <maker's branch>
|
||||
Attack vectors:
|
||||
1. Malformed input, boundary values, empty/null/huge data
|
||||
2. Concurrency and race conditions
|
||||
3. Error path exploitation
|
||||
4. Dependency failure scenarios
|
||||
Output: APPROVED or REJECTED with edge cases found.
|
||||
Think like a QA engineer who gets paid per bug found."
|
||||
)
|
||||
```
|
||||
|
||||
## Step 4: Act Phase
|
||||
|
||||
Collect all reviewer outputs and decide:
|
||||
|
||||
### All Approved
|
||||
1. Merge the Maker's worktree branch into the target branch
|
||||
2. Report: what was implemented, what was reviewed, any warnings noted
|
||||
3. Clean up the worktree
|
||||
|
||||
### Issues Found (and cycles remaining)
|
||||
1. Collect all findings into a feedback summary
|
||||
2. Go back to Step 1 (Plan) with the feedback
|
||||
3. Creator revises the proposal based on reviewer findings
|
||||
4. Maker re-implements in a fresh worktree
|
||||
5. Reviewers check again
|
||||
|
||||
### Max Cycles Reached with Unresolved Issues
|
||||
1. Report all unresolved findings to the user
|
||||
2. Present the best implementation so far (on its branch)
|
||||
3. Let the user decide: merge as-is, fix manually, or abandon
|
||||
|
||||
## Orchestration Report
|
||||
|
||||
After completion, summarize:
|
||||
|
||||
```
|
||||
## ArcheFlow Orchestration Report
|
||||
- **Task:** <description>
|
||||
- **Workflow:** standard (2 cycles)
|
||||
- **Cycle 1:** Guardian rejected (SQL injection in user input handler)
|
||||
- **Cycle 2:** All approved after input sanitization added
|
||||
- **Files changed:** 4 files, +120 -30 lines
|
||||
- **Tests added:** 8 new tests
|
||||
- **Branch:** archeflow/maker-<id> → merged to main
|
||||
```
|
||||
Reference in New Issue
Block a user