shannon

Shannon-aware project analysis with complexity assessment and confidence validation

Verify MCP configuration and provide setup guidance

Create, load, or manage execution checkpoints for recovery

Discover and catalog all available skills on system

Intelligent task execution with auto-context and research. One catch-all command: First time explores and caches, returning uses cache for speed, auto-detects when to research and when to spec. Handles any scenario intelligently.

Autonomous task execution with library discovery and validation

Execute implementation plan in batches with Shannon validation gates and review checkpoints. Loads plan with quantitative analysis, calculates complexity-based batch sizing, executes tasks with 3-tier validation, tracks metrics in Serena, reports progress quantitatively.

Generate project-specific custom instructions from project structure

Display comprehensive Shannon health dashboard with quantitative metrics across test quality, code quality, development velocity, skill effectiveness, and security. Real-time project health visualization with trend analysis and actionable recommendations.

Comprehensive project onboarding with deep codebase analysis and Shannon infrastructure setup

Track and analyze memory coordination patterns and evolution

Set and manage North Star goals with progress tracking

Unified session priming command - one command for complete context restoration

Honest gap analysis before claiming work complete - prevents premature completion

Restore project state from Serena MCP checkpoint

Generate Shannon-optimized project structure with functional test scaffolding

Analyze specification using Shannon 8D complexity framework

Display Shannon Framework status, version, MCP servers, and configuration

Automated prime → spec → wave workflow for complete task execution

NO MOCKS functional testing orchestration with platform detection

Deep debugging with sequential thinking, systematic debugging, and forced reading

Execute wave-based planning and execution with skill orchestration

Create detailed implementation plan with Shannon quantitative analysis. Generates comprehensive plans with complexity scoring, validation gates, MCP requirements, and bite-sized tasks. Plans saved to docs/plans/ with full quantitative metadata for systematic execution.

Enhanced code analysis and debugging specialist with structured evidence tracking

API architecture and interface design specialist with Shannon V4 wave coordination

System architecture specialist with phase planning integration and long-term maintainability focus

**Name**: BACKEND

Code quality and review specialist with Shannon V4 wave coordination

Checkpoint/restore specialist preventing context loss through intelligent memory management

Database architecture and schema design specialist with Shannon V4 wave coordination and NO MOCKS testing

**Name**: DATA_ENGINEER

Enhanced infrastructure and deployment specialist with real deployment testing

Frontend development specialist with shadcn MCP UI generation, Puppeteer accessibility testing, and Shannon V4 wave coordination

Production code implementation specialist with wave awareness and functional testing

Educational facilitator with structured teaching and progressive learning paths

iOS development specialist with Simulator testing and SwiftLens integration

**Name**: PERFORMANCE (Performance Engineer)

5-phase planning specialist with validation gates, resource allocation, and timeline management

Product strategy and requirements specialist with Shannon V4 wave coordination

Quality assurance specialist enforcing Shannon's NO MOCKS philosophy with comprehensive testing strategy

Code quality specialist with wave-based refactoring and test validation

Professional technical writer and documentation specialist with localization expertise

Security validation agent with threat modeling and compliance enforcement

8-dimensional complexity scoring specialist for specification analysis

Technical documentation specialist with Shannon V4 wave coordination

NO MOCKS enforcement specialist ensuring functional testing with real systems

Orchestrates parallel sub-agent execution across multiple waves with complete context preservation

Systematic gap analysis for claimed vs actual work completion. Uses 100+ sequential thoughts to identify assumptions, partial completions, missing components, and rationalization patterns. Validates completion claims against original plans, detects scope deviations, reveals quality gaps. Essential for self-assessment before declaring work complete. Use when: claiming completion, final reviews, quality audits, detecting rationalization patterns in own work.

Context-aware task execution with Serena MCP backend. First time: Explores project, saves to Serena, runs spec if complex, executes waves. Returning: Loads from Serena (<1s), detects changes, executes with cached context. Intelligently decides when to research, when to spec, when to prime. One catch-all intelligent execution command. Use when: User wants task executed in any project (new or existing).

**Purpose**: Deep codebase analysis and Shannon infrastructure setup for projects that weren't built with Shannon from the start.

Use when errors occur deep in execution and you need to trace back to find the original trigger - systematically traces bugs backward through call stack with quantitative tracking, adding instrumentation when needed, to identify source of invalid data or incorrect behavior

Detect OWASP Top 10 vulnerabilities via static analysis. Calculate security score (0.00-1.00) for code quality. Auto-generate remediation suggestions with implementation examples. Integrate with Serena for vulnerability tracking and SLA compliance. Use when: securing code, detecting vulnerabilities, improving security posture, validating fixes, enforcing security standards.

FLEXIBLE skill orchestrating comprehensive analysis workflows. Adapts to analysis type (codebase, architecture, technical debt, complexity) and automatically invokes appropriate sub-skills (spec-analysis, project-indexing, confidence-check). Applies Shannon patterns (8D framework, waves, NO MOCKS) with Serena historical context. Produces quantitative, actionable results with structured outputs and MCP recommendations.

Military-style SITuation REPort protocol for multi-agent coordination. Enforces structured status reporting with 🟢🟡🔴 codes, quantitative progress (0-100%), blockers, dependencies, ETAs, and authorization codes for secure handoffs. Prevents communication failures, lost context, and delayed blocker reporting. Use when: coordinating multiple agents, wave execution, reporting progress, requesting status updates, handing off deliverables.

Use when needing to discover available skills across project/user directories - automatically scans for SKILL.md files, parses YAML frontmatter, extracts metadata (name, description, type, MCP requirements), and builds comprehensive skill catalog. Enables intelligent skill selection and auto-invocation. NO competitor has automated skill discovery system.

Track architectural decisions and detect drift from ADRs (Architecture Decision Records). Calculate alignment score (0.00-1.00) showing code-to-design conformance. Auto-detect architectural violations and suggest refactoring. Integrate with Serena for architectural health monitoring. Use when: maintaining architectural integrity, reviewing large changes, documenting decisions, detecting drift, enforcing standards.

Use when creating or developing ideas before writing code or implementation plans - refines rough ideas into fully-formed designs through collaborative questioning with Shannon quantitative validation, alternative exploration, and incremental validation. Don't use during clear mechanical processes

Use when tests have race conditions, timing dependencies, or inconsistent pass/fail behavior - replaces arbitrary timeouts with condition polling to wait for actual state changes, eliminating flaky tests with quantitative reliability tracking

5-check quantitative validation ensuring 90% confidence before implementation. Prevents wrong-direction work through systematic verification: duplicate check (25%), architecture compliance (25%), official docs (20%), working OSS (15%), root cause (15%). Thresholds: ≥90% proceed, ≥70% clarify, <70% STOP. Proven 25-250x token ROI from SuperClaude.

PROTOCOL skill for checkpoint-based context preservation using Serena MCP. Automatically creates checkpoints at wave boundaries and before PreCompact. Enables zero-context-loss multi-session work with structured metadata collection. Use this skill for ALL Shannon projects - checkpoints are mandatory, not optional.

Restore previous session state from Serena MCP checkpoints. Retrieves checkpoint by ID or auto-selects most recent, deserializes context, restores command/skill/phase/wave state. Use when: resuming after context loss, continuing previous session, recovering from interruption.

Use when invalid data causes failures deep in execution, requiring validation at multiple system layers - validates at every layer data passes through using Shannon validation gates to make bugs structurally impossible with quantitative coverage tracking

Use for 3+ independent failures - dispatches parallel subagents with Shannon wave coordination, success scoring (0.00-1.00) per domain, and MCP result aggregation

Autonomous task execution with library discovery, 3-tier validation, and atomic git commits. Integrates with Shannon CLI Python modules for platform-specific execution. Invokes /shannon:wave for code generation, validates outputs functionally, commits only validated changes. Use when: user requests autonomous execution, wants library-first development, needs validated commits.

Use when partner provides a complete implementation plan to execute in controlled batches with review checkpoints - loads plan, reviews critically with Shannon quantitative analysis, executes tasks in complexity-based batches, runs validation gates, reports for review between batches

Use at development completion - guides branch integration with Shannon 3-tier validation (0.00-1.00 readiness score), MCP merge pattern analysis, and Serena risk assessment

Use automatically when prompts exceed 3000 characters, files exceed 500 lines, or large files are referenced - enforces complete line-by-line reading protocol with quantitative comprehension verification before processing, preventing partial comprehension and ensuring thorough understanding

Use when analyzing critical documents, specifications, or large files (>3000 lines), before any synthesis or conclusions - enforces complete line-by-line reading with quantitative verification to prevent skimming that leads to incomplete understanding

Enforce NO MOCKS testing philosophy with real systems. Iron Law: no mock objects, no unit tests, no stubs. Test with real browsers (Puppeteer MCP), real databases, real APIs. Enforced via post_tool_use.py hook. Use when: writing any tests, tempted to use mocks, need testing guidance.

QUANTITATIVE skill for validating wave deliverables against goal milestones using 0-100% alignment scoring. Prevents scope drift, detects misalignment, enforces goal-wave consistency. Requires goal-management for milestone data. Essential for multi-wave projects to maintain North Star alignment throughout execution.

FLEXIBLE skill for North Star goal tracking with Serena MCP persistence. Parses vague goals into measurable criteria, tracks progress percentages, maintains goal history, integrates with wave execution. Prevents goal drift and context loss through structured storage. Essential for multi-session projects.

Intelligent MCP server recommendation engine based on quantitative domain analysis. Maps project domains (Frontend %, Backend %, Database %, etc.) to appropriate MCP servers using tier-based priority system (Mandatory > Primary > Secondary > Optional). Performs health checking, generates setup instructions, provides fallback chains. Use when: analyzing project needs, configuring MCPs, checking MCP health, recommending alternatives.

Coordinates Serena MCP knowledge graph operations for Shannon Framework. Enforces standardized entity naming (shannon/* namespace), relation creation patterns, search protocols, and observation management. Prevents orphaned entities, naming chaos, and broken context lineage. Use when: storing specs/waves/goals/checkpoints, querying Shannon history, managing knowledge graph structure, ensuring cross-wave context preservation.

Verify test quality by injecting mutations into code and measuring catch rate. Calculate mutation score (0.00-1.00) showing test effectiveness. Auto-generate missing tests to improve coverage. Integrate with Serena for continuous mutation tracking. Use when: improving test quality, validating test effectiveness, generating missing test cases, measuring code coverage gaps.

Track performance benchmarks and detect regressions exceeding 10% threshold. Analyze historical trends and alert on degradation. Calculate regression score (0.00-1.00) for performance health. Integrate with Serena for continuous monitoring. Use when: monitoring performance, detecting regressions, analyzing performance trends, optimizing slow components, validating performance fixes.

Generate 5-phase implementation plan with validation gates and resource allocation. Adapts phase count and timeline based on complexity score. Includes validation gates between phases. Use when: planning implementation, need structured timeline, want validation checkpoints.

Generates SHANNON_INDEX for 94% token reduction (58K → 3K tokens). Compresses large codebases into structured summaries with Quick Stats, Tech Stack, Core Modules, Dependencies, Recent Changes, and Key Patterns. Enables fast agent onboarding, efficient multi-agent coordination, and instant context switching. Use when: starting project analysis, onboarding new agents, coordinating waves, switching between codebases, or when context window efficiency is critical.

8-dimensional quantitative complexity analysis with domain detection. Analyzes specifications across structural, cognitive, coordination, temporal, technical, scale, uncertainty, dependency dimensions producing 0.0-1.0 scores. Detects domains (Frontend, Backend, Database, etc.) with percentages. Use when: analyzing specifications, starting projects, planning implementations, assessing complexity quantitatively.

Use for implementation plans - dispatches fresh subagent per task with quality scoring (0.00-1.00), code review gates, Serena pattern learning, and MCP tracking

Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes - four-phase framework (root cause investigation with quantitative tracking, pattern analysis, hypothesis testing, implementation) that ensures understanding before attempting solutions

Orchestrates Shannon's complete workflow: prime → spec → wave. Automates session preparation, specification analysis, and wave execution in one command. Interactive by default with validation gates, --auto for full automation, --plan-only for estimation. Use when: user provides complete task specification and wants end-to-end Shannon workflow.

Use when implementing any feature or bugfix, before writing implementation code - write the test first using REAL systems (NO MOCKS), watch it fail, write minimal code to pass; ensures tests actually verify behavior by requiring failure first and real system integration

Use when writing or changing tests, adding mocks, or tempted to add test-only methods to production code - prevents testing mock behavior, production pollution with test-only methods, and mocking without understanding dependencies, with quantitative anti-pattern detection scoring

Use before skill deployment to verify pressure resistance via TDD RED-GREEN-REFACTOR cycle with Serena metrics tracking - measures compliance score (0.00-1.00) across pressure scenarios

Use at session start - establishes Shannon Framework workflows including mandatory 8D analysis before implementation, NO MOCKS testing enforcement, wave-based execution for complexity >=0.50, and automatic Serena MCP checkpointing. Prevents under-estimation and ensures quantitative rigor. Trigger keywords: shannon, specification, complexity, wave, checkpoint, functional testing.

Use when about to claim work is complete, fixed, passing, or successful, before committing or creating PRs - requires running verification commands and confirming output before making ANY success claims; evidence before assertions always, no exceptions

True parallel sub-agent coordination with wave-based execution. Analyzes phase dependencies, groups independent phases into waves for parallel execution, allocates agents based on complexity score. Proven 3.5x speedup for complexity >=0.50. Use when: executing complex projects, need parallel coordination, want to achieve 2-4x speedup.

Use when design is complete and you need detailed implementation tasks for engineers with zero codebase context - creates comprehensive implementation plans with Shannon quantitative analysis, exact file paths, complete code examples, validation gates, and MCP requirements assuming engineer has minimal domain knowledge

Use when creating new skills, editing existing skills, or verifying skills work before deployment - applies TDD to process documentation with Shannon quantitative validation by testing with subagents before writing, iterating until bulletproof against rationalization

5 hooks across 5 events