Skip to content

Releases: johnson-xue/summoner

Summoner v0.1.0 — AI Agent Orchestration Framework

09 Jun 09:24
@johnson-xue johnson-xue
v0.1.0
d486a90

Choose a tag to compare

View all tags
Summoner v0.1.0 — AI Agent Orchestration Framework Latest
Latest

🎯 The Problem Summoner Solves

AI coding agents are powerful but undisciplined. Without a process layer:

Pain Point Summoner Answer
AI skips diagnosis, jumps to code Phase 1 Iron Law — hook-enforced, never skipped
Can't correct direction mid-flight Checkpoint Protocol — pause at any phase, recall anytime
Past fixes forgotten next session Memory Chain — SQLite auto-recalls past bug patterns before diagnosis
Reviews only when you remember Post-Game Review — Stop hook reminds if you forget

🚀 Quick Start

# ① Install
git clone https://github.com/johnson-xue/summoner.git ~/.claude/plugins/summoner/
cd ~/.claude/plugins/summoner/hooks && make build

# ② Add summoner.yaml to your project
cd your-project
~/.claude/plugins/summoner/scripts/summoner-init.sh

# ③ Initialize memory (optional, recommended)
~/.claude/plugins/summoner/scripts/init-memory-db.sh your-project-name

# ④ Validate
~/.claude/plugins/summoner/scripts/validate-manifest.sh summoner.yaml

# ⑤ Restart Claude Code — SessionStart hook auto-injects Summoner context

💰 Token Cost (Honest)

Scenario Tokens Overhead
/summoner:fix (memory matched) ~9,300 +86%
/summoner:fix (simple, no match) ~8,300 +66%
/summoner:debug (diagnose only) ~4,300 +35%
Direct skill (baseline) ~5,000 —

Rule of thumb: Multi-step workflows → Summoner. Single-step tasks → direct skill.

📋 Commands

Command Pipeline Use When
/summoner:fix diagnosis → reproduce → fix → verify → review Bug fixing
/summoner:new define → plan → implement → test → review New features
/summoner:ship fan-out(1-3 reviewers) → merge → go/no-go Pre-launch review
/summoner:debug diagnosis only Quick investigation
/summoner:ops ops skill (delegated) Server operations
/summoner:review code review only Standalone review

💻 Platform Support

Platform Slash Commands Memory Chain State Tracking Setup
Claude Code ✅ ✅ SQLite ✅ Go hooks plugin.json
Gemini CLI ✅ TOML ✅ bash — .gemini/commands/
OpenCode ✅ routing ✅ bash — skills/
Cursor ✅ rules ✅ bash — .cursor/rules/
Windsurf ✅ rules ✅ bash — .windsurfrules
Copilot ✅ instructions ✅ bash — .github/
Aider ✅ conventions ✅ bash — CONVENTIONS.md
Codex ⚠️ manual ⚠️ bash — prompt

✅ = works natively · ✅ bash = works via shell commands · — = not available (platform limitation)

✨ Features

  • 6 Workflow Commands — fix, new, ship, debug, ops, review — each with Phase 0→1→...→checkpoint→review pipeline
  • Checkpoint Protocol — every phase pauses for user input: continue, skip, recall (redo), or stop
  • Memory Chain — SQLite database auto-recalls past bug patterns before diagnosis starts. Smart token budgeting: loads Top-5 patterns by default, drops to Top-3 or Top-1 if context budget exceeded
  • Post-Game Review — 5 review types auto-selected by how the session ended: direction correction, phase skipped, knowledge injected, full completion, or verbosity complaint
  • Go Lifecycle Hooks — 3 hooks (SessionStart context injection, PreToolUse state tracking, Stop review reminder). 100% hook-driven — AI writes zero state files
  • 3 Reusable Personas — code-reviewer (5-axis), security-auditor (OWASP), test-engineer (coverage gaps)
  • Adaptive Fan-Out — /summoner:ship scales reviews by diff size: <200 lines = 1 reviewer, <500 = 2 reviewers, ≥500 or sensitive = all 3 (code + security + test)
  • Project-Agnostic — summoner.yaml manifest maps framework verbs to project skills. Like a Makefile: verbs fixed, implementations replaceable
  • 8-Platform Support — Claude Code (full), Gemini CLI, OpenCode, Cursor, Windsurf, Copilot, Aider, Codex

⚠️ Known Issues

  • Go hooks require Go 1.16+ — make build will fail on older Go versions. Install Go from https://go.dev/dl/
  • SQLite3 must be in PATH — Memory Chain uses sqlite3 CLI. macOS ships it by default; Linux: apt install sqlite3 or equivalent
  • Windows requires WSL — Shell scripts and Go hooks need WSL/Git Bash. Native PowerShell not yet supported
  • Non-Claude-Code platforms get markdown-driven Memory Chain (no Go hooks, no auto state tracking). See Platform Support table for details
  • Star-history chart may show flat line until the repo accumulates stars (just went public)

📦 Install Size

63 files (19 core framework + 12 platform adapters + 14 docs + 12 community + 6 config). Compiled Go hooks: ~7.5 MB. No external dependencies beyond Go + SQLite3.

Assets 2
Loading