---
description: System Overview for Lamplighter-MCP
globs: **
alwaysApply: false
---
# Lamplighter-MCP System Overview

Lamplighter-MCP is an intelligent context engine for software development teams. It serves as a bridge between AI coding assistants (like you) and the complex context of software projects.

## System Architecture

Lamplighter-MCP follows a modular architecture with these key components:

1. **CodebaseAnalyzer**: Scans project files and directories to create a structured representation of the codebase.
2. **HistoryLogger**: Maintains a chronological record of actions taken during development.
3. **FeatureSpecProcessor**: Processes feature specifications from Confluence into actionable tasks.
4. **TaskManager**: Tracks the status of tasks and suggests prioritization.
5. **AIService**: Provides specialized AI functionality for tasks like summarization and contextual understanding.
6. **ConfluenceReader**: Interfaces with Confluence to retrieve and parse documentation.

## Context Files (Source of Truth)

Lamplighter-MCP maintains these essential context files:

- **codebase_summary.md**: Contains a structured overview of the project architecture.
- **feature_tasks/feature_[ID]_tasks.md**: Contains the task breakdown for each feature specification.
- **history_log.md**: Contains a chronological log of all system events and actions.

## Key Workflows

### 1. Codebase Analysis Workflow

When a user requests codebase analysis:
- The `CodebaseAnalyzer` module scans the project structure
- Creates a comprehensive representation in `codebase_summary.md`
- AI assistants use this to provide more contextually relevant code suggestions

### 2. Feature Specification Processing

When a user provides a Confluence spec:
- The `ConfluenceReader` retrieves the document
- The `FeatureSpecProcessor` analyzes the content
- Breaks it down into discrete tasks in a `feature_[ID]_tasks.md` file
- Tasks are tagged with status (ToDo, InProgress, Done)

### 3. Task Management

When discussing development work:
- The `TaskManager` tracks task status
- Recommends task prioritization based on dependencies
- Updates task status as work progresses

### 4. History Logging

All significant actions and decisions are logged:
- The `HistoryLogger` records timestamps and action details
- Maintains a chronological development narrative
- Helps with continuity between development sessions

## API Tools for AI Assistants

Use these tools to interact with Lamplighter-MCP:

- `analyze_codebase()`: Analyzes project structure and creates/updates the codebase summary
- `process_confluence_spec(url)`: Processes a Confluence specification and creates tasks
- `update_task_status(task_id, status)`: Updates the status of a specific task
- `suggest_next_task(feature_id)`: Identifies the next task to work on
- `get_codebase_summary()`: Retrieves the latest codebase summary
- `get_history_log(limit)`: Retrieves recent history entries
- `get_feature_tasks(feature_id)`: Retrieves tasks for a specific feature

## Best Practices for AI Assistants

1. **Suggest context-gathering first**: When working in a new area of the codebase, suggest analyzing it before major changes.
2. **Use the two-step protocol**: For actions that modify project state, first suggest the action, then wait for user confirmation.
3. **Reference context files**: Use information from context files to provide more informed suggestions.
4. **Keep track of task status**: Be aware of which tasks are in progress and completed.
5. **Use the history log**: Reference past actions to maintain continuity between sessions.

## Example Interactions

### Example 1: Breaking Down a Feature
User: "I need to implement this feature from Confluence: [URL]"
AI: "I'll help you break down that feature. Let me process the specification."
[AI uses process_confluence_spec tool]
AI: "I've broken the feature into 5 tasks. Here they are: [list of tasks]"

### Example 2: Suggesting the Next Task
User: "What should I work on next for feature X?"
AI: "Let me check the current task status."
[AI uses get_feature_tasks and suggest_next_task tools]
AI: "Based on the current status, I recommend working on 'Implement user authentication flow' next."

### Example 3: Understanding Codebase Context
User: "I need to modify the authentication system."
AI: "Let me check what we know about the authentication system."
[AI uses get_codebase_summary tool]
AI: "The authentication system is implemented in the 'auth' module. It uses JWT for token management and connects to Firebase for user storage."