legion-cc 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vladyslav Blackmoore
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,269 @@
+# Legion
+
+Multi-agent orchestration framework for Claude Code. Legion organizes specialized agents into domain-specific pipelines — architect, plan, execute, review — with state tracking, context monitoring, and session continuity across conversations.
+
+The first domain ships with Legion: **devops** — infrastructure design, planning, execution, and review.
+
+---
+
+## Features
+
+**Domain-based agent pipelines**
+Each domain defines a sequential pipeline of specialized agents. The devops domain runs: `architect → plan → execute → review`. Every stage produces a numbered artifact that feeds the next.
+
+**Fast context-aware execution**
+`/legion:devops:quick` reads `.codebase/` and `.planning/codebase/` before dispatching to classify and route the task to the correct agent automatically.
+
+**State tracking across sessions**
+All pipeline state is written to `.planning/legion/STATE.md` — current domain, stage, task history, and artifact chain. State persists between Claude Code sessions.
+
+**Context window monitoring**
+A `PostToolUse` hook reads context metrics after each tool call. When remaining context drops below 35%, the agent receives an in-context warning to wrap up. At 25%, it receives a critical stop directive. Warnings are debounced across tool calls and coexist safely with GSD.
+
+**Approval checkpoints in the pipeline**
+`/legion:devops:cycle` pauses after the architect and plan stages to show the output and ask for approval before continuing. The user can approve, request a revision, or stop and save state for later.
+
+**Sequential artifact management**
+Each pipeline stage writes a numbered artifact to `.planning/legion/devops/`:
+```
+001-architect-eks-migration.md
+002-plan-eks-migration.md
+003-execution-eks-migration.md
+004-review-eks-migration.md
+```
+
+**Session continuity**
+`/legion:resume` reads `STATE.md` and the latest session record, restores context, identifies where the pipeline stopped, and routes to the correct next command.
+
+---
+
+## Quick Start
+
+```bash
+git clone git@github.com:vladyslavblackmoore/legion.git
+cd legion
+chmod +x install.sh
+./install.sh
+```
+
+The installer copies commands, workflows, templates, references, and hooks into `~/.claude/`, registers the `PostToolUse` context monitor in Claude Code settings, and writes a file manifest for clean uninstalls.
+
+**Options**
+
+```bash
+./install.sh --dry-run   # preview what would be installed
+./install.sh --force     # overwrite existing agent files
+```
+
+**Uninstall**
+
+```bash
+./uninstall.sh
+```
+
+---
+
+## Commands
+
+### DevOps domain
+
+| Command | Description |
+|---------|-------------|
+| `/legion:devops:quick <task>` | Classify the task and dispatch to the right agent. Reads `.codebase/` first. |
+| `/legion:devops:architect <task>` | Design infrastructure architecture with the `devops-architect` agent (opus). |
+| `/legion:devops:plan [path]` | Decompose architecture into an implementation plan with `delivery-planner` (sonnet). Uses latest architect artifact if no path given. |
+| `/legion:devops:execute [path]` | Implement the plan with `infra-executor` (opus). Supports `--task T1` to run a single task. |
+| `/legion:devops:build [path]` | Scaffold project structure and create `.codebase/` documentation with `codebase-builder` (opus). |
+| `/legion:devops:review [path]` | Review changes against architectural intent with `devops-architect` in review mode (sonnet). |
+| `/legion:devops:cycle <task>` | Run the full pipeline (architect → plan → execute → review) with checkpoints after architect and plan. |
+
+### Session management
+
+| Command | Description |
+|---------|-------------|
+| `/legion:status` | Show active domain, pipeline stage, task history, and last session info. |
+| `/legion:resume` | Restore context from the previous session and route to the next pipeline stage. |
+
+---
+
+## Architecture
+
+```
+legion/
+├── agents/          # Agent definitions installed to ~/.claude/agents/
+├── bin/             # Node.js CLI (legion-tools.cjs) — init, state, session management
+│   └── lib/         # Modules: config, core, domain, init, session, state
+├── commands/        # Claude Code slash commands (.md frontmatter + execution prompt)
+│   └── legion/
+│       ├── devops/  # /legion:devops:* commands
+│       ├── resume.md
+│       └── status.md
+├── hooks/           # Claude Code hooks (Node.js)
+│   ├── legion-context-monitor.js   # PostToolUse: injects context warnings
+│   └── legion-statusline.js        # StatusLine: shows domain:stage + context bar
+├── references/      # Reference documents read during workflow execution
+│   ├── agent-routing.md
+│   ├── domain-registry.md
+│   ├── ui-brand.md
+│   └── devops/
+│       ├── agent-map.md
+│       └── pipeline-patterns.md
+├── templates/       # State, session, artifact, and config templates
+│   └── devops/      # Artifact templates (architect, plan, execution, review)
+├── workflows/       # Step-by-step execution logic referenced by commands
+│   ├── core/        # init, context-load, completion (shared across domains)
+│   └── devops/      # One workflow per command
+├── install.sh
+├── uninstall.sh
+├── package.json
+└── VERSION
+```
+
+---
+
+## DevOps Agents
+
+| Agent | Role | Model | Used By |
+|-------|------|-------|---------|
+| `devops-architect` | Senior/Lead DevOps Architect — infrastructure design, security assessment, migration planning, HA/DR | opus (architect) / sonnet (review) | `architect`, `review`, `cycle` |
+| `delivery-planner` | Senior Delivery Planner — work decomposition, phased planning, dependency mapping, risk assessment | sonnet | `plan`, `cycle` |
+| `infra-executor` | Elite Infrastructure Execution Specialist — Terraform, CI/CD, Kubernetes, AWS resource management | opus | `execute`, `cycle` |
+| `codebase-builder` | Elite Codebase Builder — project scaffolding, `.codebase/` documentation creation, existing project analysis | opus | `build` |
+
+The `devops-architect` agent doubles as reviewer: the same agent definition is invoked with a review prompt at sonnet model for the review stage.
+
+---
+
+## Pipeline
+
+```
+/legion:devops:cycle "Add ElastiCache Redis for session management"
+
+  [devops-architect]              opus
+        |
+        | 001-architect-*.md
+        v
+  [checkpoint] -- revise? ------> re-run architect
+        |
+        | approve
+        v
+  [delivery-planner]              sonnet
+        |
+        | 002-plan-*.md
+        v
+  [checkpoint] -- revise? ------> re-run planner
+        |
+        | approve
+        v
+  [infra-executor]                opus
+        |
+        | 003-execution-*.md
+        v
+  [devops-architect (review)]     sonnet
+        |
+        | 004-review-*.md
+        v
+  done
+```
+
+Checkpoints default to ON after architect and plan, OFF after execute and review. This is configurable per project in `.planning/legion/config.json`.
+
+---
+
+## Pipeline Patterns
+
+**Full cycle** — new, complex infrastructure work:
+```
+/legion:devops:cycle "Add ElastiCache Redis for session management"
+```
+
+**Enter at any stage** — architecture exists, start from plan:
+```
+/legion:devops:plan
+```
+
+**Quick fix** — small, well-understood change:
+```
+/legion:devops:quick "Add ingress rule for port 8443 to eks-node SG"
+```
+
+**Documentation first** — existing project without `.codebase/` docs:
+```
+/legion:devops:build
+/legion:devops:architect "migration plan"
+```
+
+**Review only** — audit a path:
+```
+/legion:devops:review ./aws/modules/rds/
+```
+
+---
+
+## Adding Domains
+
+Legion is designed to host multiple domains. To add a new domain (e.g., `backend`):
+
+1. Create commands at `commands/legion/{domain}/` — one `.md` file per pipeline stage
+2. Create workflows at `workflows/{domain}/` — one `.md` file per command
+3. Create templates at `templates/{domain}/` — artifact output templates
+4. Create references at `references/{domain}/` — `agent-map.md` and `pipeline-patterns.md`
+5. Define agents in `agents/` and register them in `references/{domain}/agent-map.md`
+6. Add the domain entry to `references/domain-registry.md`
+7. Run `./install.sh` to deploy
+
+Each domain must define: pipeline stages (ordered), agent mapping (stage to agent), model assignment, and classification rules for its `/quick` command.
+
+---
+
+## Project Structure (installed)
+
+After installation, Legion lives inside `~/.claude/`:
+
+```
+~/.claude/
+├── commands/legion/       # Slash commands
+│   ├── resume.md
+│   ├── status.md
+│   └── devops/
+├── hooks/
+│   ├── legion-context-monitor.js
+│   └── legion-statusline.js
+├── agents/
+│   ├── devops-architect.md
+│   ├── delivery-planner.md
+│   ├── infra-executor.md
+│   ├── codebase-builder.md
+│   └── legion-orchestrator.md
+└── legion/
+    ├── bin/
+    ├── workflows/
+    ├── templates/
+    ├── references/
+    └── VERSION
+```
+
+Per-project state is written alongside your code:
+
+```
+{project}/
+└── .planning/
+    └── legion/
+        ├── STATE.md
+        ├── config.json
+        ├── sessions/
+        └── devops/          # Numbered artifacts
+```
+
+---
+
+## Requirements
+
+- [Claude Code](https://claude.ai/download) installed and configured (`~/.claude/` must exist)
+- Node.js >= 18
+
+---
+
+## License
+
+MIT

package/VERSION

@@ -0,0 +1 @@
+0.1.0

package/agents/legion-orchestrator.md

@@ -0,0 +1,95 @@
+---
+name: legion-orchestrator
+description: "Legion meta-agent for task classification and agent routing. Used by /legion:devops:quick to analyze tasks and dispatch to the right specialized agent."
+model: sonnet
+color: blue
+memory: user
+---
+
+# Legion Orchestrator
+
+You are the Legion Orchestrator — a lightweight routing agent that analyzes incoming tasks and determines which specialized agent should handle them.
+
+## Core Role
+
+You do NOT execute tasks yourself. You:
+1. Analyze the task description
+2. Load project context (.codebase/, .planning/)
+3. Classify the task type
+4. Recommend the appropriate agent and provide context for spawning
+
+## Classification Rules
+
+Analyze the task and classify into one of these categories:
+
+### architecture
+**Agent**: devops-architect (opus)
+**Triggers**: Design decisions, technology evaluation, migration strategy, HA/DR planning, security architecture, infrastructure design, capacity planning, comparing options
+**Keywords**: design, architect, propose, evaluate, strategy, migration, HA, DR, compare options, should we use, how to design
+
+### planning
+**Agent**: delivery-planner (sonnet)
+**Triggers**: Breaking down work, creating implementation plans, task decomposition, phased rollout planning, dependency analysis
+**Keywords**: plan, decompose, break down, create tasks, implementation plan, phases, rollout, what steps, how to implement
+
+### execution
+**Agent**: infra-executor (opus)
+**Triggers**: Writing Terraform code, modifying infrastructure, fixing configs, updating pipelines, creating AWS resources, changing security groups
+**Keywords**: implement, create, add, write, fix, update, change, terraform, pipeline, module, resource, deploy, configure
+
+### build
+**Agent**: codebase-builder (opus)
+**Triggers**: New project setup, scaffolding, creating .codebase/ documentation, initializing project structure
+**Keywords**: scaffold, init, setup, create project, new project, .codebase/, document structure, bootstrap
+
+### review
+**Agent**: devops-architect (sonnet, review mode)
+**Triggers**: Code review, security audit, architecture validation, compliance check, best practices review
+**Keywords**: review, audit, check, validate, security review, compliance, best practices
+
+## Classification Process
+
+1. Read the task description carefully
+2. Identify primary intent (what does the user want to ACHIEVE?)
+3. Match against classification rules above
+4. If ambiguous between two categories:
+   - Prefer the more specific one
+   - If still unclear, state both options and ask the user
+5. NEVER guess — if truly unclear, ask
+
+## Output Format
+
+```json
+{
+  "classification": "execution",
+  "confidence": "high",
+  "agent": "infra-executor",
+  "model": "opus",
+  "reasoning": "Task asks to add a security group rule — this is a direct infrastructure change",
+  "context_needed": ["current security group config", "VPC CIDR ranges"],
+  "task_summary": "Add ingress rule for port 8443 to eks-node security group"
+}
+```
+
+## Rules
+
+- You are a ROUTER, not an executor
+- Classify quickly — don't over-analyze
+- If the task is simple and clear, route immediately
+- If the task is complex, it might need the full cycle (/legion:devops:cycle)
+- Always consider project context when classifying
+- MCP tools are mandatory for context gathering
+- If unsure, say "я не знаю" and ask the user
+
+## Agent Memory
+
+You have persistent memory at `/Users/explorer/.claude/agent-memory/legion-orchestrator/`.
+
+### What to Remember
+- Common task patterns and their correct classifications
+- Project-specific routing preferences
+- Classification mistakes and corrections
+
+### What NOT to Remember
+- Individual task details
+- Session-specific context