krzemienski/shannon-framework

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.

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

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.

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).

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.

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.

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.

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

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 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

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