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).
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).
skill-type
PROTOCOL
shannon-version
>=5.0.0
complexity-triggers
["0.00-1.00"]
invoked-by-commands
["/shannon:do"]
related-commands
[{"/shannon:exec":"Structured execution with library discovery + validation"},{"/shannon:task":"Meta-command that orchestrates prime→spec→wave"},{"/shannon:wave":"Direct wave execution for parallel work"}]
command-orchestration
This skill is invoked by /shannon:do, which is the RECOMMENDED default for general task execution.
WHEN TO USE /shannon:do (this skill):
- General task execution in any project
- Auto-detection of complexity, research needs, context
- Both new and existing projects
- Simple to complex tasks
WHEN TO USE ALTERNATIVES:
- /shannon:exec: When you want explicit library discovery + 3-tier validation + git commits
- /shannon:task: When you want full automation (prime→spec→wave) from specification
- /shannon:wave: When you already have spec analysis and just need parallel execution
See docs/COMMAND_ORCHESTRATION.md for complete decision trees.
mcp-requirements
{"required":[{"name":"serena","version":">=2.0.0","purpose":"Persistent context backend for project memory","fallback":"ERROR - Cannot operate without Serena","degradation":"critical"}],"recommended":[{"name":"sequential","purpose":"Deep analysis for complex decisions"},{"name":"context7","purpose":"Framework documentation lookup"},{"name":"tavily","purpose":"Library and best practice research"}]}
Comprehensive intelligent task execution that automatically handles all scenarios: new projects, existing codebases, simple tasks, complex requirements, first-time work, and returning workflows - all with Serena MCP as the persistent context backend.
Core Innovation: One command that adapts to any scenario without configuration, learns from every execution, and gets faster on return visits.
Workflow
Step 1: Context Detection Using Serena
Check if project exists in Serena memory:
Determine project ID from current working directory:
Get current path: Use Bash tool to run pwd
Extract project name: Last component of path
Sanitize for memory key: Replace special characters with underscores
Check Serena for existing project memory:
Use Serena tool: list_memories()
Search for key: "shannon_project_{project_id}"
If key found → RETURNING_WORKFLOW
If key not found → FIRST_TIME_WORKFLOW
Duration: < 1 second
Step 2a: FIRST_TIME_WORKFLOW
For projects not yet in Serena:
Sub-Step 1: Determine Project Type
Count files in current directory to determine if new or existing project:
Invoke sub-skill:
@skill wave-orchestration
Task: {task_description}
Spec: {spec_analysis_results if complex}
Save Project to Serena:
Use Serena tool:
write_memory("shannon_project_{project_id}", {
project_path: "{full_path}",
created: "{ISO_timestamp}",
type: "NEW_PROJECT",
initial_task: "{task_description}",
complexity: "{simple|complex}",
spec_id: "{spec_analysis_id if complex}"
})
Save Execution Results:
Use Serena tool:
write_memory("shannon_execution_{timestamp}", {
project_id: "{project_id}",
task: "{task_description}",
files_created: [list of files from wave results],
duration_seconds: {duration},
success: true,
timestamp: "{ISO_timestamp}"
})
Sub-Step 3: EXISTING_PROJECT Path
For projects with existing codebase:
Explore Project Structure:
Use Read tool to read: README.md, package.json, pyproject.toml, requirements.txt
Use Bash tool to find: find . -name "*.py" | head -20 (sample files)
Use Grep tool to search: Look for main entry points, app initialization
Detect Tech Stack:
From files found:
If package.json exists → Node.js/JavaScript
If pyproject.toml or requirements.txt → Python
If pom.xml → Java
If go.mod → Go
If Podfile → iOS/Swift
Extract specific frameworks from file contents:
package.json dependencies → React, Express, Next.js, etc.
requirements.txt → Flask, Django, FastAPI, etc.
Detect Validation Gates:
From package.json:
Look for "scripts" section
Extract "test", "build", "lint" commands
From pyproject.toml:
Look for [tool.pytest], [tool.ruff] sections
Default gates: pytest, ruff check
Research Decision:
Check if task mentions libraries NOT in current dependencies:
Parse task for library names (common libraries list)
Compare against detected dependencies
If new library found → Need research
If Research Needed:
For each new library:
- Use Tavily tool: Search "{library_name} best practices guide"
- Use Context7 tool: Get library documentation if available
- Save research to Serena:
write_memory("shannon_research_{library}_{timestamp}", {
library: "{library_name}",
project_id: "{project_id}",
best_practices: "{tavily_results}",
documentation: "{context7_results}",
timestamp: "{ISO_timestamp}"
})
Complexity Assessment:
Simple task (< 12 words, starts with "create" or "add") → Skip spec
Complex task (multiple requirements, "system", "integrate") → Run spec
