diff --git a/skills/custom-archetypes/SKILL.md b/skills/custom-archetypes/SKILL.md index 18e4cf9..950c31d 100644 --- a/skills/custom-archetypes/SKILL.md +++ b/skills/custom-archetypes/SKILL.md @@ -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. diff --git a/skills/onboarding/SKILL.md b/skills/onboarding/SKILL.md new file mode 100644 index 0000000..19ce6f8 --- /dev/null +++ b/skills/onboarding/SKILL.md @@ -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) + ��️ 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 diff --git a/skills/orchestration/SKILL.md b/skills/orchestration/SKILL.md index d9252e0..f2b5549 100644 --- a/skills/orchestration/SKILL.md +++ b/skills/orchestration/SKILL.md @@ -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: diff --git a/skills/using-archeflow/SKILL.md b/skills/using-archeflow/SKILL.md index bcdbd34..da458a4 100644 --- a/skills/using-archeflow/SKILL.md +++ b/skills/using-archeflow/SKILL.md @@ -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: ━━━━━━━━━━━━━━━━━━━ +📋 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 diff --git a/skills/workflow-design/SKILL.md b/skills/workflow-design/SKILL.md index a277768..0ad148b 100644 --- a/skills/workflow-design/SKILL.md +++ b/skills/workflow-design/SKILL.md @@ -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.