cntx-ui 2.0.13 → 3.0.0

package/templates/activities/lib/create-activity.mdc

@@ -0,0 +1,63 @@
+---
+description: 
+globs: 
+alwaysApply: false
+---
+# Rule: Generating an Activity Definition
+
+## Goal
+
+To guide an AI assistant in creating a detailed Activity Definition in Markdown format, based on an initial user prompt. The Activity should be clear, actionable, and suitable for a junior developer to understand and implement the feature or improvement for the cntx-ui project.
+
+## Process
+
+1.  **Receive Initial Prompt:** The user provides a brief description or request for a new feature, improvement, or functionality for cntx-ui.
+2.  **Ask Clarifying Questions:** Before writing the Activity, the AI *must* ask clarifying questions to gather sufficient detail. The goal is to understand the "what" and "why" of the activity, not necessarily the "how" (which the developer will figure out). Make sure to provide options in letter/number lists so I can respond easily with my selections.
+3.  **Generate Activity:** Based on the initial prompt and the user's answers to the clarifying questions, generate an Activity using the structure outlined below.
+4.  **Save Activity:** Save the generated document as `activity-[feature-name].md` inside the `.cntx/activities/[activity-name]/` directory.
+
+## Clarifying Questions (Examples)
+
+The AI should adapt its questions based on the prompt, but here are some common areas to explore:
+
+*   **Problem/Goal:** "What problem does this activity solve for cntx-ui users?" or "What is the main goal we want to achieve with this activity?"
+*   **Target User:** "Who is the primary user of this feature? (e.g., developers using cntx-ui, AI assistants, end users of bundled applications)"
+*   **Core Functionality:** "Can you describe the key actions a user should be able to perform with this feature?"
+*   **User Stories:** "Could you provide a few user stories? (e.g., As a [type of user], I want to [perform an action] so that [benefit].)"
+*   **Acceptance Criteria:** "How will we know when this activity is successfully implemented? What are the key success criteria?"
+*   **Scope/Boundaries:** "Are there any specific things this activity *should not* do (non-goals)?"
+*   **Data Requirements:** "What kind of data does this feature need to display or manipulate? (e.g., bundle configurations, file metadata, semantic chunks)"
+*   **Design/UI:** "Are there any existing design patterns in cntx-ui to follow?" or "Can you describe the desired look and feel?"
+*   **Edge Cases:** "Are there any potential edge cases or error conditions we should consider?"
+
+## Activity Structure
+
+The generated Activity should include the following sections:
+
+1.  **Introduction/Overview:** Briefly describe the activity and the problem it solves for cntx-ui. State the goal.
+2.  **Goals:** List the specific, measurable objectives for this activity.
+3.  **User Stories:** Detail the user narratives describing activity usage and benefits.
+4.  **Functional Requirements:** List the specific functionalities the activity must have. Use clear, concise language (e.g., "The system must allow users to configure bundle rules."). Number these requirements.
+5.  **Non-Goals (Out of Scope):** Clearly state what this activity will *not* include to manage scope.
+6.  **Design Considerations (Optional):** Link to existing UI components, describe UI/UX requirements, or mention relevant cntx-ui components/styles if applicable.
+7.  **Technical Considerations (Optional):** Mention any known technical constraints, dependencies, or suggestions (e.g., "Should integrate with the existing bundle management system").
+8.  **Success Metrics:** How will the success of this activity be measured? (e.g., "Improve bundle generation speed by 20%", "Reduce configuration errors by 50%").
+9.  **Open Questions:** List any remaining questions or areas needing further clarification.
+
+## Target Audience
+
+Assume the primary reader of the Activity is a **junior developer** working on cntx-ui. Therefore, requirements should be explicit, unambiguous, and avoid jargon where possible. Provide enough detail for them to understand the activity's purpose and core logic.
+
+## Output
+
+*   **Format:** Markdown (`.md`)
+*   **Location:** `.cntx/activities/activities/[activity-name]/`
+*   **Filename:** `README.md`
+
+## Final instructions
+
+1. Do NOT start implementing the Activity
+2. Make sure to ask the user clarifying questions
+3. Take the user's answers to the clarifying questions and improve the Activity
+4. Consider how this activity fits into the broader cntx-ui ecosystem of file bundling and AI development tools
+5. **REQUIRED**: After creating the activity README.md, update `.cntx/activities/activities.json` to register the new activity with proper title, description, desired_outcome, references, status, and tasks

package/templates/activities/lib/generate-tasks.mdc

@@ -0,0 +1,64 @@
+---
+description: 
+globs: 
+alwaysApply: false
+---
+# Rule: Generating a Task List from a PRD
+
+## Goal
+
+To guide an AI assistant in creating a detailed, step-by-step task list in Markdown format based on an existing Product Requirements Document (PRD). The task list should guide a developer through implementation.
+
+## Output
+
+- **Format:** Markdown (`.md`)
+- **Location:** `/tasks/`
+- **Filename:** `tasks-[prd-file-name].md` (e.g., `tasks-prd-user-profile-editing.md`)
+
+## Process
+
+1.  **Receive PRD Reference:** The user points the AI to a specific PRD file
+2.  **Analyze PRD:** The AI reads and analyzes the functional requirements, user stories, and other sections of the specified PRD.
+3.  **Phase 1: Generate Parent Tasks:** Based on the PRD analysis, create the file and generate the main, high-level tasks required to implement the feature. Use your judgement on how many high-level tasks to use. It's likely to be about 5. Present these tasks to the user in the specified format (without sub-tasks yet). Inform the user: "I have generated the high-level tasks based on the PRD. Ready to generate the sub-tasks? Respond with 'Go' to proceed."
+4.  **Wait for Confirmation:** Pause and wait for the user to respond with "Go".
+5.  **Phase 2: Generate Sub-Tasks:** Once the user confirms, break down each parent task into smaller, actionable sub-tasks necessary to complete the parent task. Ensure sub-tasks logically follow from the parent task and cover the implementation details implied by the PRD.
+6.  **Identify Relevant Files:** Based on the tasks and PRD, identify potential files that will need to be created or modified. List these under the `Relevant Files` section, including corresponding test files if applicable.
+7.  **Generate Final Output:** Combine the parent tasks, sub-tasks, relevant files, and notes into the final Markdown structure.
+8.  **Save Task List:** Save the generated document in the `/tasks/` directory with the filename `tasks-[prd-file-name].md`, where `[prd-file-name]` matches the base name of the input PRD file (e.g., if the input was `prd-user-profile-editing.md`, the output is `tasks-prd-user-profile-editing.md`).
+
+## Output Format
+
+The generated task list _must_ follow this structure:
+
+```markdown
+## Relevant Files
+
+- `path/to/potential/file1.ts` - Brief description of why this file is relevant (e.g., Contains the main component for this feature).
+- `path/to/file1.test.ts` - Unit tests for `file1.ts`.
+- `path/to/another/file.tsx` - Brief description (e.g., API route handler for data submission).
+- `path/to/another/file.test.tsx` - Unit tests for `another/file.tsx`.
+- `lib/utils/helpers.ts` - Brief description (e.g., Utility functions needed for calculations).
+- `lib/utils/helpers.test.ts` - Unit tests for `helpers.ts`.
+
+### Notes
+
+- Unit tests should typically be placed alongside the code files they are testing (e.g., `MyComponent.tsx` and `MyComponent.test.tsx` in the same directory).
+- Use `npx jest [optional/path/to/test/file]` to run tests. Running without a path executes all tests found by the Jest configuration.
+
+## Tasks
+
+- [ ] 1.0 Parent Task Title
+  - [ ] 1.1 [Sub-task description 1.1]
+  - [ ] 1.2 [Sub-task description 1.2]
+- [ ] 2.0 Parent Task Title
+  - [ ] 2.1 [Sub-task description 2.1]
+- [ ] 3.0 Parent Task Title (may not require sub-tasks if purely structural or configuration)
+```
+
+## Interaction Model
+
+The process explicitly requires a pause after generating parent tasks to get user confirmation ("Go") before proceeding to generate the detailed sub-tasks. This ensures the high-level plan aligns with user expectations before diving into details.
+
+## Target Audience
+
+Assume the primary reader of the task list is a **junior developer** who will implement the feature.

package/templates/activities/lib/process-task-list.mdc

@@ -0,0 +1,52 @@
+---
+description: 
+globs: 
+alwaysApply: false
+---
+# Task List Management
+
+Guidelines for managing task lists in markdown files to track progress on completing a PRD
+
+## Task Implementation
+- **One sub-task at a time:** Do **NOT** start the next sub‑task until you ask the user for permission and they say "yes" or "y"
+- **Completion protocol:**  
+  1. When you finish a **sub‑task**, immediately mark it as completed by changing `[ ]` to `[x]`.
+  2. If **all** subtasks underneath a parent task are now `[x]`, follow this sequence:
+    - **First**: Run the full test suite (`pytest`, `npm test`, `bin/rails test`, etc.)
+    - **Only if all tests pass**: Stage changes (`git add .`)
+    - **Clean up**: Remove any temporary files and temporary code before committing
+    - **Commit**: Use a descriptive commit message that:
+      - Uses conventional commit format (`feat:`, `fix:`, `refactor:`, etc.)
+      - Summarizes what was accomplished in the parent task
+      - Lists key changes and additions
+      - References the task number and PRD context
+      - **Formats the message as a single-line command using `-m` flags**, e.g.:
+
+        ```
+        git commit -m "feat: add payment validation logic" -m "- Validates card type and expiry" -m "- Adds unit tests for edge cases" -m "Related to T123 in PRD"
+        ```
+  3. Once all the subtasks are marked completed and changes have been committed, mark the **parent task** as completed.
+- Stop after each sub‑task and wait for the user's go‑ahead.
+
+## Task List Maintenance
+
+1. **Update the task list as you work:**
+   - Mark tasks and subtasks as completed (`[x]`) per the protocol above.
+   - Add new tasks as they emerge.
+
+2. **Maintain the "Relevant Files" section:**
+   - List every file created or modified.
+   - Give each file a one‑line description of its purpose.
+
+## AI Instructions
+
+When working with task lists, the AI must:
+
+1. Regularly update the task list file after finishing any significant work.
+2. Follow the completion protocol:
+   - Mark each finished **sub‑task** `[x]`.
+   - Mark the **parent task** `[x]` once **all** its subtasks are `[x]`.
+3. Add newly discovered tasks.
+4. Keep "Relevant Files" accurate and up to date.
+5. Before starting work, check which sub‑task is next.
+6. After implementing a sub‑task, update the file and then pause for user approval.

package/templates/agent-config.yaml

@@ -0,0 +1,65 @@
+# Agent Rules Configuration - cntx-ui
+# Modular agent instruction system for composable rule sets
+
+version: "1.0.0"
+project: "cntx-ui"
+description: "Semantic code analysis and bundle management system"
+
+# Core rule sets (universal across all agents)
+core_rules:
+  - "core/performance-hierarchy.md"
+  - "core/codebase-navigation.md" 
+  - "core/response-formatting.md"
+
+# Capability modules (include if available in project)
+capabilities:
+  vector_search:
+    file: "capabilities/vector-search.md"
+    required: true
+    endpoint_check: "/api/vector-db/status"
+    
+  bundle_system:
+    file: "capabilities/bundle-system.md" 
+    required: true
+    endpoint_check: "/api/bundles"
+    
+  activities_system:
+    file: "capabilities/activities-system.md"
+    required: false
+    endpoint_check: "/api/activities"
+
+# Project-specific context
+project_context:
+  - "project-specific/architecture.md"
+
+# Tool-specific optimizations
+tools:
+  cursor:
+    include: ["core_rules", "capabilities", "project_context"]
+    output_file: ".cursorrules"
+    format: "markdown"
+      
+  claude_code:
+    include: ["core_rules", "capabilities", "project_context"]
+    output_file: ".cntx/agent-instructions.md"
+    format: "markdown"
+
+# Performance metrics and validation
+validation:
+  vector_db_chunks: ">= 300"
+  response_time_target: "< 50ms"
+  token_efficiency_target: "> 80% vs traditional search"
+
+# Rule precedence (later rules override earlier ones)
+precedence:
+  1. "core_rules"      # Universal principles
+  2. "capabilities"    # Available system features  
+  3. "project_context" # Project-specific patterns
+  4. "tool_specific"   # Tool optimizations
+
+# Composition metadata
+metadata:
+  generated_by: "cntx-ui modular agent rules system"
+  last_updated: "2025-01-28"
+  schema_version: "1.0.0"
+  total_modules: 7

package/templates/agent-instructions.md

@@ -0,0 +1,234 @@
+# Agent Instructions for Codebase Exploration
+
+## Project Overview
+
+This repository has been analyzed by cntx-ui and is ready for intelligent agent exploration.
+
+## Quick Start for External Agents
+
+If you're an agent without MCP server access, use this prompt to get up to speed:
+
+```
+I'm working in a project that uses cntx-ui for file organization and AI collaboration. Please read these files to understand the project structure and help me with activities:
+
+@.cntx/agent-instructions.md
+@.cntx/activities/README.md
+@.cntx/activities/activities.json
+
+After reading those, please also examine:
+@.cntx/activities/lib/create-activity.mdc
+@.cntx/activities/lib/generate-tasks.mdc
+@.cntx/activities/lib/process-task-list.mdc
+
+These files contain the complete workflow for creating and managing activities with agent assistance.
+```
+
+## Your Role
+
+You are an AI agent with access to a specialized "Repository Intelligence" engine. Your goal is to help humans understand and work with this codebase efficiently.
+
+## Available Capabilities
+
+### 1. Model Context Protocol (MCP) - PRIMARY
+You have direct access to surgical intelligence tools. Refer to the **Intelligence Interface** section in `.cntx/AGENT.md` for full parameter schemas.
+
+### 2. HTTP API - FALLBACK
+If MCP is unavailable, use the HTTP endpoints documented in `.cntx/AGENT.md`.
+
+## Performance Hierarchy (Use in this order):
+
+1. **Semantic Search** (20ms, 90% token savings) - `agent/query` (MCP) or `POST /api/semantic-search` (HTTP)
+   - Use for: code discovery, pattern matching, "find functions that..."
+
+2. **Bundle System** (50ms) - `list_bundles` (MCP) or `GET /api/bundles` (HTTP)
+   - Use for: project structure, file organization, high-level overview
+
+3. **Discovery Mode** - `agent/discover` (MCP) or `GET /api/status` (HTTP)
+   - Use for: architectural overview and health check.
+
+4. **Traditional Search** (100ms+, high token cost) - `grep/rg/Read`
+   - Use ONLY when: exact string matching needed, semantic search fails.
+
+---
+
+## Operating Modes
+
+### Discovery Mode
+
+_"Tell me about this codebase"_
+
+- Start with bundle overview and purposes
+- Identify architectural patterns and frameworks
+- Report on code organization and key components
+- Provide file counts, complexity metrics, and structure insights
+
+### Query Mode
+
+_"Where is the user authentication handled?"_
+
+- **ALWAYS use vector database first** for semantic discovery (`POST /api/vector-db/search`)
+- Use precise queries like "user authentication login session" 
+- Fallback to traditional search only if vector DB fails
+- Always provide specific file paths and line numbers from results
+- Explain relationships between components
+
+### Feature Investigation Mode
+
+_"I want to add dark mode—what already exists?"_
+
+- **Vector search for related patterns** first: "theme dark mode styling colors"
+- Use the format: ✅ Existing, ⚠️ Partial, ❌ Missing
+- Cross-reference vector results with bundle organization
+- Identify integration points and patterns to follow
+- Recommend extend vs. create approaches
+
+### Passive Mode
+
+_"Let's discuss the architecture before I make changes"_
+
+- Engage in thoughtful conversation about design decisions
+- Ask clarifying questions about requirements and constraints
+- Suggest alternatives and trade-offs
+- Plan implementation approaches collaboratively
+
+### Project Organizer Mode
+
+_"Help me set up this project" or "Optimize my bundle organization"_
+
+- **Fresh Projects**: Detect project state → Generate semantic analysis → Plan bundles → Create bundles
+- **Established Projects**: Audit organization → Optimize bundles → Suggest improvements
+- **Maintenance**: Cleanup stale patterns → Validate health → Recommend optimizations
+- **Activities**: detect, analyze, bundle (plan), create (execute), optimize, audit, cleanup, validate
+
+## Response Guidelines
+
+### Always Include:
+
+- **Specific file references**: `path/to/file.js:23-67`
+- **Evidence level**: Based on semantic analysis, AST parsing, or heuristics
+- **Confidence indicators**: "I found 3 definitive matches" vs "This appears to be related"
+- **Next steps**: "Would you like me to dive deeper into X or explore Y?"
+
+### Response Structure:
+
+```
+Based on semantic analysis of your codebase:
+
+[Direct answer to the question]
+
+Key locations:
+1. Primary implementation in `file.js:lines`
+2. Related functionality in `other.js:lines`
+3. Configuration in `config.js:lines`
+
+[Brief explanation of how they work together]
+
+Would you like me to [specific follow-up options]?
+```
+
+## Bundle-Aware Navigation
+
+- Start exploration with bundle boundaries
+- Respect existing organization patterns
+- Use bundles to scope queries appropriately
+- Reference bundle relationships in explanations
+
+## Efficiency Principles
+
+### Performance Hierarchy (Use in this order):
+
+1. **Vector Database** (20ms, 90% token savings) - `POST /api/vector-db/search`
+   - Use for: code discovery, pattern matching, "find functions that..."
+   - Query format: `{"query": "semantic description", "limit": 5, "minSimilarity": 0.2}`
+
+2. **Bundle System** (50ms) - `GET /api/bundles`
+   - Use for: project structure, file organization, high-level overview
+
+3. **Activities System** (30ms) - `GET /api/activities` 
+   - Use for: agent task tracking, progress monitoring
+
+4. **Traditional Search** (100ms+, high token cost) - `grep/rg/Read`
+   - Use ONLY when: exact string matching needed, vector search fails
+   - Examples: specific error messages, exact function names
+
+### Token Optimization:
+- **Vector search**: ~5k tokens per query vs 50k+ for file reading
+- **Real-time updates**: Vector DB stays current with code changes
+- **Comprehensive coverage**: 315+ indexed code chunks across entire codebase
+
+## Vector Search Examples
+
+### Good Query Patterns:
+```bash
+# ✅ Semantic discovery
+curl -X POST /api/vector-db/search -d '{"query": "React component state management", "limit": 3}'
+
+# ✅ Pattern matching  
+curl -X POST /api/vector-db/search -d '{"query": "API endpoint request handling", "limit": 5}'
+
+# ✅ Feature investigation
+curl -X POST /api/vector-db/search -d '{"query": "configuration file loading parsing", "limit": 3}'
+```
+
+### Query by Type:
+```bash
+# Find specific code types
+curl -X POST /api/vector-db/search-by-type -d '{"type": "react_component", "limit": 5}'
+curl -X POST /api/vector-db/search-by-type -d '{"type": "api_integration", "limit": 3}'
+```
+
+### Query by Domain:
+```bash
+# Find by business domain
+curl -X POST /api/vector-db/search-by-domain -d '{"domain": "authentication", "limit": 5}'
+curl -X POST /api/vector-db/search-by-domain -d '{"domain": "user-interface", "limit": 3}'
+```
+
+## Common Patterns to Look For
+
+- **React Components**: Vector search "React component JSX hooks"
+- **API Endpoints**: Vector search "API endpoint route handler" 
+- **Configuration**: Vector search "configuration environment setup"
+- **State Management**: Vector search "state management context hooks"
+- **Testing**: Vector search "test suite jest unit testing"
+- **Styling**: Vector search "styling CSS theme colors"
+
+## Project-Specific Guidance
+
+_This section will be populated based on the specific codebase you're exploring_
+
+## Error Handling
+
+### Vector Database Fallback Strategy:
+
+1. **If vector search fails** (empty results, 500 error):
+   - Try broader/simpler query terms
+   - Use search-by-type or search-by-domain endpoints
+   - Fall back to bundle-based exploration
+   - Last resort: traditional grep/rg search
+
+2. **If vector DB is offline** (404, connection error):
+   - Acknowledge limitation: "Vector search unavailable, using traditional methods"
+   - Use bundle system for structure discovery
+   - Suggest rebuilding vector DB: `POST /api/vector-db/rebuild`
+
+3. **Query Optimization Tips**:
+   - Use 3-5 descriptive words for best results
+   - Lower minSimilarity (0.1-0.2) for broader results  
+   - Increase limit (5-10) for more comprehensive search
+   - Try different semantic phrasings if first query fails
+
+## Conversation Flow
+
+1. **Listen carefully** to the human's question or request
+2. **Classify the mode** (Discovery, Query, Investigation, Passive)  
+3. **Start with vector search** for semantic discovery (unless exact string matching needed)
+4. **Provide structured response** with evidence and confidence
+5. **Offer specific next steps** or follow-up options
+
+### Optimal Tool Usage Order:
+```
+Human Query → Vector Search → [Optional: Bundle Context] → [Fallback: Traditional Search] → Response
+```
+
+Remember: **Vector-first approach saves 90% token cost** while providing superior semantic understanding. You're here to make the codebase understandable and navigable efficiently, not to overwhelm with information.

package/templates/agent-rules/capabilities/activities-system.md

@@ -0,0 +1,147 @@
+# Activities System Capabilities
+
+## Overview
+The activities system provides structured task management for agents, tracking progress on complex development activities through defined workflows and documentation.
+
+## When Available
+- Check for activities endpoint: `GET /api/activities`
+- Look for activities directory: `.cntx/activities/activities/`
+- Verify activity definitions and progress tracking
+
+## Core Capabilities
+
+### Activity Discovery
+**Endpoint**: `GET /api/activities`
+
+**Provides**:
+- List of all available activities
+- Activity status and progress percentages
+- Activity metadata (name, description, category)
+- Complete file contents (README, progress, tasks, notes)
+
+### Activity Execution (Future)
+**Endpoints**: 
+- `POST /api/activities/{id}/execute` (planned)
+- `POST /api/activities/{id}/stop` (planned)
+
+**Will provide**:
+- Programmatic activity execution
+- Progress monitoring and updates
+- Result collection and reporting
+
+## Activity Structure
+
+### Standard Activity Format
+Each activity contains:
+- **README.md**: Activity definition, goals, requirements
+- **progress.md**: Current status, completion tracking
+- **tasks.md**: Detailed task breakdown with priorities
+- **notes.md**: Implementation decisions, technical notes
+
+### Activity Metadata
+- **Status**: pending, in_progress, completed, failed
+- **Progress**: Percentage completion (0-100%)
+- **Category**: Type of activity (refactoring, feature, analysis, etc.)
+- **Priority**: Task importance (high, medium, low)
+
+## Activity Types and Use Cases
+
+### Development Activities
+- **Feature implementation**: Adding new functionality
+- **Refactoring**: Code organization and cleanup
+- **Migration**: Technology or pattern updates
+- **Optimization**: Performance and efficiency improvements
+
+### Analysis Activities
+- **Architecture review**: System design evaluation
+- **Code analysis**: Pattern discovery and documentation
+- **Dependency audit**: Library and framework assessment
+- **Security review**: Vulnerability analysis
+
+### Maintenance Activities
+- **Documentation updates**: Keeping docs current
+- **Test coverage**: Ensuring adequate testing
+- **Cleanup tasks**: Removing deprecated code
+- **Configuration updates**: Settings and environment management
+
+## Progress Tracking
+
+### Status Indicators
+- **✅ Completed**: Task finished successfully
+- **🚧 In Progress**: Currently being worked on
+- **⏳ Pending**: Not yet started
+- **❌ Failed**: Encountered blocking issues
+
+### Progress Calculation
+Based on task completion percentages from tasks.md:
+- Parse task status indicators
+- Calculate completion ratio
+- Update overall activity progress
+- Track progress over time
+
+### Completion Criteria
+Activities are considered complete when:
+- All defined tasks are finished
+- Success criteria are met
+- Documentation is updated
+- Results are validated
+
+## Agent Integration
+
+### Activity-Driven Development
+Agents can use activities to:
+- **Structure complex work**: Break down large tasks into manageable pieces
+- **Track progress**: Monitor completion status and identify blockers
+- **Coordinate effort**: Understand what work is planned vs in progress
+- **Learn from context**: Use existing activities as templates
+
+### Activity Creation Process
+1. **Define goals**: Clear objectives and success criteria
+2. **Break down tasks**: Specific, actionable work items
+3. **Estimate effort**: Time and complexity assessments
+4. **Track progress**: Regular status updates and milestone tracking
+5. **Document results**: Lessons learned and outcomes
+
+### Progress Monitoring
+- **Real-time updates**: Activity status reflects current work
+- **Milestone tracking**: Key progress points and deliverables
+- **Blocker identification**: Issues preventing progress
+- **Completion validation**: Ensuring work meets requirements
+
+## Integration with Other Systems
+
+### Vector Search + Activities
+- Use vector search to find activity-related code
+- Reference activities in code discovery and explanation
+- Connect implementation work to activity goals
+
+### Bundle System + Activities
+- Scope activities by bundle boundaries
+- Use bundle organization to plan activity tasks
+- Track activity impact across bundle boundaries
+
+## Performance Characteristics
+
+### Speed
+- **Activity listing**: ~30ms
+- **Activity details**: ~50ms (includes file contents)
+- **Token efficiency**: High (structured, relevant content)
+
+### Use Cases
+- **Project planning**: Understanding planned and ongoing work
+- **Context switching**: Quickly understanding current development state
+- **Progress reporting**: Communicating status to stakeholders
+- **Knowledge transfer**: Sharing implementation context and decisions
+
+## Best Practices
+
+### Activity-Aware Assistance
+- **Check activity context** when helping with development tasks
+- **Reference related activities** when explaining code or suggesting changes
+- **Respect activity boundaries** and existing work in progress
+- **Contribute to activity documentation** when making related changes
+
+### Integration Patterns
+- **Planning**: Activities → Bundle scope → Vector search → Implementation
+- **Execution**: Activity tasks → Code discovery → Implementation → Progress update
+- **Review**: Activity completion → Validation → Documentation → Lessons learned