serena-usage

What this skill does

# Serena Usage

Effective usage of the Serena MCP Server for project memory management, code intelligence, and maintaining continuity across AI agent sessions.

- Leverage native parallel subagent dispatch and 200k+ context windows where available.



## Activation Conditions

Use symptom -> action triggers: when one matches, apply this skill and verify with the protocol below.

**MUST activate when:**
- Serena is available for the project
- Task requires project memory continuity
- Task requires symbol navigation or Serena refactoring workflow
- Managing project memories for AI session continuity
- Navigating codebases using symbol-based tools
- Performing code refactoring with Serena's symbol management
- Setting up Serena onboarding for new projects
- Using Serena's memory system for project context preservation

**Critical: Always verify project activation FIRST with `get_current_config` before any Serena operations**

## Prerequisites

- Serena MCP Server configured and running
- Project activated (use `get_current_config` to verify, or `activate_project` if not activated)
- Onboarding completed for the target project (use `check_onboarding_performed` first)
- If not activated, run `activate_project` with project name or path
- If not onboarded, run `onboarding` tool after activation

---

## Onboarding Workflow

### First-Time Project Setup
1. **Check activation**: Call `get_current_config` to verify if project is activated
2. **Activate if needed**: If not activated, call `activate_project` with project name or path
3. **Check onboarding**: Call `check_onboarding_performed` to verify onboarding status
4. **Read manual**: If not onboarded, call `initial_instructions` to read the Serena Instructions Manual
5. **Initialize**: Call `onboarding` to complete project setup
6. Serena analyzes the project structure and creates initial context

### What Onboarding Captures
- Project language and framework detection
- Directory structure analysis
- Key file identification
- Symbol index creation
- Initial memory scaffolding

### Activation Check Pattern
```bash
# Always verify activation first
get_current_config
# If no active project, activate it
activate_project project="path/to/project"
# Then proceed with onboarding check
check_onboarding_performed
```

## Project Activation

### Why Activation Matters
Project activation is the first step when working with Serena. It tells Serena which project to work with and initializes the workspace context.

### Activation Workflow
1. **Check current status**: Call `get_current_config` to see if a project is already activated
2. **Activate if needed**: If no active project, call:
   ```
   activate_project project="project-name"
   # OR with path:
   activate_project project="path/to/project/directory"
   ```
3. **Verify activation**: Call `get_current_config` again to confirm activation succeeded
4. **Proceed with onboarding**: Once activated, check if onboarding is needed

### Activation Best Practices
- Always check `get_current_config` before attempting any Serena operations
- Use the workspace root path when activating
- Activation is session-specific — you may need to reactivate in new sessions
- After activation, the project context is available for all subsequent Serena operations

---

## Memory Management

### Core Concepts
Serena memories persist between sessions, providing continuity for AI agents across work sessions.

### Memory Operations

| Operation | Tool | Purpose |
|-----------|------|---------|
| List all | `list_memories` | See available memories |
| Read one | `read_memory` | Access specific memory content |
| Create | `write_memory` | Store new information |
| Update | `edit_memory` | Modify existing memory |
| Remove | `delete_memory` | Clean up obsolete information |

### Memory Structure

Serena memories use the Memory Bank naming convention for consistency and clarity. This structure organizes project intelligence into core files and tasks.

#### Core Files

| Memory Name | Purpose |
|-------------|---------|
| `project-brief` | Foundation document defining core requirements and goals. Shapes all other memories. Created at project start. |
| `product-context` | Why this project exists, problems it solves, how it should work, and user experience goals |
| `active-context` | Current work focus, recent changes, and next steps with active decisions and considerations |
| `system-patterns` | System architecture, key technical decisions, design patterns in use, and component relationships |
| `tech-context` | Technologies used, development setup, technical constraints, and dependencies |
| `progress` | What works, what's left to build, current status, and known issues |

#### Task Management Memories

Tasks are managed with dedicated memory files for tracking progress and history.

| Memory Name | Purpose |
|-------------|---------|
| `task-{id}` | Individual task tracking (e.g., TASK001-implement-login.md) with original request, thought process, implementation plan, and progress logs |
| `task-index` | Master list of all tasks with IDs, names, statuses (Pending/In Progress/Completed/Abandoned), and last updated dates |

#### Task Memory Structure

Each task memory follows this format:

```markdown
# [Task ID] - [Task Name]

**Status:** [Pending/In Progress/Completed/Abandoned]
**Added:** [Date Added]
**Updated:** [Date Last Updated]

## Original Request
[The original task description as provided by the user]

## Thought Process
[Documentation of the discussion and reasoning that shaped the approach]

## Implementation Plan
- [Step 1]
- [Step 2]
- [Step 3]

## Progress Tracking

**Overall Status:** [Not Started/In Progress/Blocked/Completed] - [Completion Percentage]

### Subtasks
| ID | Description | Status | Updated | Notes |
|----|-------------|--------|---------|-------|
| 1.1 | [Subtask description] | [Complete/In Progress/Not Started/Blocked] | [Date] | [Relevant notes] |

## Progress Log
### [Date]
- Updated subtask 1.1 status to Complete
- Started work on subtask 1.2
- Encountered issue with [specific problem]
- Made decision to [approach/solution]
```

#### Task Index Structure

The task-index memory maintains a structured record:

```markdown
# Tasks Index

## In Progress
- [TASK003] Implement user authentication -Working on OAuth integration
- [TASK005] Create dashboard UI -Building main components

## Pending
- [TASK006] Add export functionality -Planned for next sprint

## Completed
- [TASK001] Project setup -Completed on 2025-03-15
- [TASK002] Create database schema -Completed on 2025-03-17
```

#### Commands

When you request **add task** or **create task**, the agent will:
1. Create a new task memory with a unique Task ID
2. Document the thought process about the approach
3. Develop an implementation plan
4. Set an initial status
5. Update the task-index memory

To view tasks, the command **show tasks [filter]** will display filtered lists with valid filters:
- **all** - Show all tasks regardless of status
- **active** - Show only "In Progress" tasks
- **pending** - Show only "Pending" tasks
- **completed** - Show only "Completed" tasks
- **blocked** - Show only "Blocked" tasks
- **recent** - Show tasks updated in the last week

### When to Update Memories

**Update core memories when:**
- After completing significant features or functionality
- When making architectural decisions
- Discovering new project patterns or conventions
- Changing technical stack or dependencies
- Modifying data models or schemas
- At the start and end of each work session

**Update task memories when:**
- Creating new tasks via "create task" command
- Making progress on existing tasks
- Completing subtasks or entire tasks
- Encountering blockers or issues
- Changing task status (Pending → In Progress → Completed/Abandoned)

### Memory Creation Workflow

**CRITICAL: ALWAYS check for relevant existing memories before creating new ones**

#### Step-by-Step Process

1. **List available memories**: U