diff --git a/.cursor/rules/concept-rag-guidance.mdc b/.cursor/rules/concept-rag-guidance.mdc index 5b3350f..5b36e9f 100644 --- a/.cursor/rules/concept-rag-guidance.mdc +++ b/.cursor/rules/concept-rag-guidance.mdc @@ -3,4 +3,4 @@ alwaysApply: true --- # Overview -Before using concept-rag MCP tools, fetch the `concept-rag://intents` resource. \ No newline at end of file +Before using concept-rag MCP tools, fetch the `concept-rag://activities` resource. \ No newline at end of file diff --git a/README.md b/README.md index 51f3d85..6911f93 100644 --- a/README.md +++ b/README.md @@ -14,14 +14,10 @@ A RAG MCP server that enables LLMs to interact with a vector database chunked li --- ## 🎯 Overview -Concept-RAG uses an **Intent β†’ Skill β†’ Tool** architecture to help AI agents to efficiently acquire knowledge. - -``` -User Goal β†’ Intent (problem domain) β†’ Skill (solution domain) β†’ Tools -``` +Concept-RAG uses an **Goal β†’ Activity β†’ Skill β†’ Tool** architecture to help AI agents to efficiently acquire knowledge. After initial setup of an always-applied [rule](prompts/ide-setup.md), agents are able to use an exposed [guidance](prompts/guidance.md) resource to: -1. **Match the user's goal** to an [intent](prompts/intents/index.md) (e.g., "understand a topic", "explore a concept") +1. **Match the user's goal** to an [activity](prompts/activities/index.md) (e.g., "understand a topic", "explore a concept") 2. **Follow the [skill](prompts/skills/index.md) workflow** which orchestrates the right [tool](docs/api-reference.md) sequence 3. **Synthesize the answer** with citations diff --git a/docs/architecture/skills-interface.md b/docs/architecture/skills-interface.md index 2a30b4c..6316077 100644 --- a/docs/architecture/skills-interface.md +++ b/docs/architecture/skills-interface.md @@ -9,19 +9,19 @@ The skills interface provides a three-tier abstraction layer over MCP tools: ``` -Intent (Problem Domain) β†’ Skill (Solution Domain) β†’ Tool (Atomic Operation) +Activity (Problem Domain) β†’ Skill (Solution Domain) β†’ Tool (Atomic Operation) ``` -This reduces tool selection errors and enables successful multi-step workflows by providing intent-based abstractions with context preservation. +This reduces tool selection errors and enables successful multi-step workflows by providing activity-based abstractions with context preservation. ## Architecture ``` Cursor Rule (prompts/agent-quick-rules.md) ↓ instructs agent to read -Intent Index (concept-rag://intents) +Activity Index (concept-rag://activities) ↓ agent matches user goal -Intent Description (concept-rag://intents/{id}) +Activity Description (concept-rag://activities/{id}) ↓ maps to skill Skill Description (concept-rag://skills/{id}) ↓ guides tool workflow @@ -32,13 +32,13 @@ MCP Tools (existing 11 tools) | Layer | Domain | Focus | Example | |-------|--------|-------|---------| -| **Intent** | Problem | User goals, needs | "I want to understand X" | +| **Activity** | Problem | User goals, needs | "I want to understand X" | | **Skill** | Solution | Multi-tool workflows | `catalog_search` β†’ `chunks_search` β†’ synthesize | | **Tool** | Solution | Atomic operations | `catalog_search`, `chunks_search` | -## Available Intents +## Available Activities -| Intent | User Goal | Skill | +| Activity | User Goal | Skill | |--------|-----------|-------| | `understand-topic` | Learn about a topic from the library | deep-research | | `know-my-library` | Discover available content | library-discovery | @@ -54,9 +54,9 @@ MCP Tools (existing 11 tools) | Resource URI | Description | |--------------|-------------| -| `concept-rag://intents` | Intent index (read first) | -| `concept-rag://intents/understand-topic` | Understand a topic intent | -| `concept-rag://intents/know-my-library` | Know my library intent | +| `concept-rag://activities` | Activity index (read first) | +| `concept-rag://activities/understand-topic` | Understand a topic activity | +| `concept-rag://activities/know-my-library` | Know my library activity | | `concept-rag://skills` | Skill index | | `concept-rag://skills/deep-research` | Deep research skill | | `concept-rag://skills/library-discovery` | Library discovery skill | @@ -65,10 +65,10 @@ MCP Tools (existing 11 tools) ``` prompts/ -β”œβ”€β”€ intents/ -β”‚ β”œβ”€β”€ index.md # Intent index -β”‚ β”œβ”€β”€ understand-topic.md # Intent definition -β”‚ └── know-my-library.md # Intent definition +β”œβ”€β”€ activities/ +β”‚ β”œβ”€β”€ index.md # Activity index +β”‚ β”œβ”€β”€ understand-topic.md # Activity definition +β”‚ └── know-my-library.md # Activity definition β”œβ”€β”€ skills/ β”‚ β”œβ”€β”€ index.md # Skill index β”‚ β”œβ”€β”€ deep-research.md # Skill definition @@ -80,15 +80,15 @@ prompts/ ### For Agents -1. Read the intent index: `concept-rag://intents` -2. Match user's goal to an intent -3. Read the intent's linked skill +1. Read the activity index: `concept-rag://activities` +2. Match user's goal to an activity +3. Read the activity's linked skill 4. Follow the skill's tool workflow 5. Synthesize answer with citations ### For Developers -- Add new intents to `prompts/intents/` +- Add new activities to `prompts/activities/` - Add new skills to `prompts/skills/` - Register resources in `src/conceptual_index.ts` - Update indexes to include new entries @@ -98,7 +98,7 @@ prompts/ - **MCP Resources over Tools**: Reduces tool count, leverages existing infrastructure - **Static .md files**: Editable, version controlled, no runtime logic - **Tiered loading**: Index < 50 lines; verbose loaded on demand -- **Separation of concerns**: Problem domain (intents) vs. solution domain (skills/tools) +- **Separation of concerns**: Problem domain (activities) vs. solution domain (skills/tools) ## References diff --git a/docs/development.md b/docs/development.md index 1901965..c28efec 100644 --- a/docs/development.md +++ b/docs/development.md @@ -90,7 +90,7 @@ All major technical decisions are documented in **[Architecture Decision Records ### Key Documentation - **[API Reference](api-reference.md)** - Complete MCP tool documentation with JSON I/O schemas -- **[Intent/Skill Architecture](architecture/skills-interface.md)** - Intent-based tool selection +- **[Activity/Skill Architecture](architecture/skills-interface.md)** - Activity-based tool selection - **[Database Schema](database-schema.md)** - Four-table normalized schema with derived fields - **[Test Suite](../src/__tests__/README.md)** - Comprehensive test documentation diff --git a/mkdocs.yml b/mkdocs.yml index d3988a6..2409a39 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -73,16 +73,16 @@ nav: - Overview: prompts/guidance.md - IDE Setup: prompts/ide-setup.md - - Intents: - - Overview: prompts/intents/index.md - - Understand Topic: prompts/intents/understand-topic.md - - Explore Concept: prompts/intents/explore-concept.md - - Explore Category: prompts/intents/explore-category.md - - Analyze Document: prompts/intents/analyze-document.md - - Know My Library: prompts/intents/know-my-library.md - - Identify Patterns: prompts/intents/identify-patterns.md - - Identify Best Practices: prompts/intents/identify-best-practices.md - - Curate Lexicon: prompts/intents/curate-lexicon.md + - Activities: + - Overview: prompts/activities/index.md + - Understand Topic: prompts/activities/understand-topic.md + - Explore Concept: prompts/activities/explore-concept.md + - Explore Category: prompts/activities/explore-category.md + - Analyze Document: prompts/activities/analyze-document.md + - Know My Library: prompts/activities/know-my-library.md + - Identify Patterns: prompts/activities/identify-patterns.md + - Identify Best Practices: prompts/activities/identify-best-practices.md + - Curate Lexicon: prompts/activities/curate-lexicon.md - Skills: - Overview: prompts/skills/index.md diff --git a/prompts/intents/analyze-document.md b/prompts/activities/analyze-document.md similarity index 95% rename from prompts/intents/analyze-document.md rename to prompts/activities/analyze-document.md index bc09ba9..18f16eb 100644 --- a/prompts/intents/analyze-document.md +++ b/prompts/activities/analyze-document.md @@ -1,4 +1,4 @@ -# Intent: Analyze a Document +# Activity: Analyze a Document ## Problem Domain diff --git a/prompts/intents/curate-lexicon.md b/prompts/activities/curate-lexicon.md similarity index 98% rename from prompts/intents/curate-lexicon.md rename to prompts/activities/curate-lexicon.md index 18296ae..777f26a 100644 --- a/prompts/intents/curate-lexicon.md +++ b/prompts/activities/curate-lexicon.md @@ -1,4 +1,4 @@ -# Intent: Curate Concept Lexicon +# Activity: Curate Concept Lexicon ## Problem Domain @@ -6,7 +6,7 @@ ## Recognition -Match this intent when the user says: +Match this activity when the user says: - "Create a concept lexicon for [project/domain]" - "What concepts from my library apply to [project]?" - "Build a vocabulary reference for [domain]" diff --git a/prompts/intents/explore-category.md b/prompts/activities/explore-category.md similarity index 96% rename from prompts/intents/explore-category.md rename to prompts/activities/explore-category.md index 5674d3e..dcc540e 100644 --- a/prompts/intents/explore-category.md +++ b/prompts/activities/explore-category.md @@ -1,4 +1,4 @@ -# Intent: Explore a Category +# Activity: Explore a Category ## Problem Domain diff --git a/prompts/intents/explore-concept.md b/prompts/activities/explore-concept.md similarity index 96% rename from prompts/intents/explore-concept.md rename to prompts/activities/explore-concept.md index e7fd81b..e9f58c3 100644 --- a/prompts/intents/explore-concept.md +++ b/prompts/activities/explore-concept.md @@ -1,4 +1,4 @@ -# Intent: Explore a Concept +# Activity: Explore a Concept ## Problem Domain diff --git a/prompts/intents/identify-best-practices.md b/prompts/activities/identify-best-practices.md similarity index 95% rename from prompts/intents/identify-best-practices.md rename to prompts/activities/identify-best-practices.md index f65e197..baaabdf 100644 --- a/prompts/intents/identify-best-practices.md +++ b/prompts/activities/identify-best-practices.md @@ -1,4 +1,4 @@ -# Intent: Identify Best Practices +# Activity: Identify Best Practices ## Problem Domain diff --git a/prompts/intents/identify-patterns.md b/prompts/activities/identify-patterns.md similarity index 96% rename from prompts/intents/identify-patterns.md rename to prompts/activities/identify-patterns.md index 65e0168..fd8d746 100644 --- a/prompts/intents/identify-patterns.md +++ b/prompts/activities/identify-patterns.md @@ -1,4 +1,4 @@ -# Intent: Identify Patterns +# Activity: Identify Patterns ## Problem Domain diff --git a/prompts/intents/index.md b/prompts/activities/index.md similarity index 90% rename from prompts/intents/index.md rename to prompts/activities/index.md index 52820ac..b178c67 100644 --- a/prompts/intents/index.md +++ b/prompts/activities/index.md @@ -1,10 +1,10 @@ -# Intent Index +# Activity Index -Match the user's goal to an intent. Each intent may use multiple skills in sequence. +Match the user's goal to an activity. Each activity may use multiple skills in sequence. -## Available Intents +## Available Activities -| Intent | User Goal | Primary Skill | Supporting Skills | +| Activity | User Goal | Primary Skill | Supporting Skills | |--------|-----------|---------------|-------------------| | [understand-topic](understand-topic.md) | Learn about a topic | `deep-research` | `concept-exploration`, `document-analysis` | | [know-my-library](know-my-library.md) | Discover available content | `library-discovery` | `category-exploration` | diff --git a/prompts/intents/know-my-library.md b/prompts/activities/know-my-library.md similarity index 94% rename from prompts/intents/know-my-library.md rename to prompts/activities/know-my-library.md index 8d24a46..92f586a 100644 --- a/prompts/intents/know-my-library.md +++ b/prompts/activities/know-my-library.md @@ -1,4 +1,4 @@ -# Intent: Know My Library +# Activity: Know My Library ## Problem Domain @@ -6,7 +6,7 @@ ## Recognition -Match this intent when the user says: +Match this activity when the user says: - "What do I have?" - "What's in my library?" - "What documents do I have?" diff --git a/prompts/intents/understand-topic.md b/prompts/activities/understand-topic.md similarity index 94% rename from prompts/intents/understand-topic.md rename to prompts/activities/understand-topic.md index f3c3bbd..8ba94b5 100644 --- a/prompts/intents/understand-topic.md +++ b/prompts/activities/understand-topic.md @@ -1,4 +1,4 @@ -# Intent: Understand a Topic +# Activity: Understand a Topic ## Problem Domain @@ -6,7 +6,7 @@ ## Recognition -Match this intent when the user says: +Match this activity when the user says: - "What does my library say about X?" - "Research topic X" - "I want to understand X" diff --git a/prompts/guidance.md b/prompts/guidance.md index 9ca193d..0c5d3c8 100644 --- a/prompts/guidance.md +++ b/prompts/guidance.md @@ -4,28 +4,28 @@ How to use concept-rag effectively. --- -## The Intent β†’ Skill β†’ Tool Model +## The Activity β†’ Skill β†’ Tool Model ``` -User Goal β†’ Intent (problem domain) β†’ Skill (solution domain) β†’ Tools +User Goal β†’ Activity (problem domain) β†’ Skill (solution domain) β†’ Tools ``` -1. **Identify the intent** β€” What is the user trying to accomplish? -2. **Follow the skill** β€” Each intent maps to a skill with a tool workflow +1. **Identify the activity** β€” What is the user trying to accomplish? +2. **Follow the skill** β€” Each activity maps to a skill with a tool workflow 3. **Execute tools** β€” Follow the skill's tool sequence 4. **Synthesize answer** β€” Combine findings with citations --- -## Step 1: Identify the Intent +## Step 1: Identify the Activity -Fetch `concept-rag://intents` to see available intents and match the user's goal. +Fetch `concept-rag://activities` to see available activities and match the user's goal. --- ## Step 2: Follow the Skill -Each intent links to a skill. The skill describes: +Each activity links to a skill. The skill describes: - Which tools to use and in what order - What context to preserve between calls - Expected output format diff --git a/prompts/ide-setup.md b/prompts/ide-setup.md index f0aad57..a9b49c6 100644 --- a/prompts/ide-setup.md +++ b/prompts/ide-setup.md @@ -1,5 +1,5 @@ Paste the following into your IDE rules location: ``` -Before using concept-rag MCP tools, fetch the `concept-rag://intents` resource. +Before using concept-rag MCP tools, fetch the `concept-rag://activities` resource. ``` \ No newline at end of file diff --git a/prompts/skills/category-exploration.md b/prompts/skills/category-exploration.md index 952ac82..e7cf428 100644 --- a/prompts/skills/category-exploration.md +++ b/prompts/skills/category-exploration.md @@ -4,9 +4,9 @@ Understand what concepts appear in a specific domain/category. -## Fulfills Intent +## Fulfills Activity -[explore-category](../intents/explore-category.md) +[explore-category](../activities/explore-category.md) ## Tool Workflow diff --git a/prompts/skills/concept-exploration.md b/prompts/skills/concept-exploration.md index b61e41c..742b48d 100644 --- a/prompts/skills/concept-exploration.md +++ b/prompts/skills/concept-exploration.md @@ -4,9 +4,9 @@ Track where a concept appears across the library and find source attribution. -## Fulfills Intent +## Fulfills Activity -[explore-concept](../intents/explore-concept.md) +[explore-concept](../activities/explore-concept.md) ## Tool Workflow diff --git a/prompts/skills/deep-research.md b/prompts/skills/deep-research.md index 0f9e803..9cc4536 100644 --- a/prompts/skills/deep-research.md +++ b/prompts/skills/deep-research.md @@ -4,9 +4,9 @@ Synthesize knowledge across multiple documents to answer a user's question. -## Fulfills Intent +## Fulfills Activity -[understand-topic](../intents/understand-topic.md) +[understand-topic](../activities/understand-topic.md) ## Tool Workflow diff --git a/prompts/skills/document-analysis.md b/prompts/skills/document-analysis.md index 2b577dd..af701a3 100644 --- a/prompts/skills/document-analysis.md +++ b/prompts/skills/document-analysis.md @@ -4,9 +4,9 @@ Extract and analyze concepts from a specific document. -## Fulfills Intent +## Fulfills Activity -[analyze-document](../intents/analyze-document.md) +[analyze-document](../activities/analyze-document.md) ## Tool Workflow diff --git a/prompts/skills/index.md b/prompts/skills/index.md index e8c7ce9..1b0ebc3 100644 --- a/prompts/skills/index.md +++ b/prompts/skills/index.md @@ -1,6 +1,6 @@ # Skill Index -Skills define tool workflows to fulfill user intents. Workflows may include **loops** for iterative refinement. +Skills define tool workflows to fulfill user activities. Workflows may include **loops** for iterative refinement. ## Available Skills @@ -17,7 +17,7 @@ Skills define tool workflows to fulfill user intents. Workflows may include **lo ## Execution Model ``` -1. Match intent to skill(s) +1. Match activity to skill(s) β”‚ 2. Execute skill workflow β”œβ”€ Tools may be called multiple times diff --git a/prompts/skills/library-discovery.md b/prompts/skills/library-discovery.md index a8ff421..c527d59 100644 --- a/prompts/skills/library-discovery.md +++ b/prompts/skills/library-discovery.md @@ -4,9 +4,9 @@ Browse and inventory available content to help users understand their library. -## Fulfills Intent +## Fulfills Activity -[know-my-library](../intents/know-my-library.md) +[know-my-library](../activities/know-my-library.md) ## Tool Workflow diff --git a/prompts/skills/pattern-research.md b/prompts/skills/pattern-research.md index e76e5f4..4493d94 100644 --- a/prompts/skills/pattern-research.md +++ b/prompts/skills/pattern-research.md @@ -4,9 +4,9 @@ Find design patterns applicable to a specific problem or domain. -## Fulfills Intent +## Fulfills Activity -[identify-patterns](../intents/identify-patterns.md) +[identify-patterns](../activities/identify-patterns.md) ## Tool Workflow diff --git a/prompts/skills/practice-research.md b/prompts/skills/practice-research.md index 0388962..938bcad 100644 --- a/prompts/skills/practice-research.md +++ b/prompts/skills/practice-research.md @@ -4,9 +4,9 @@ Discover industry best practices and anti-patterns for a domain. -## Fulfills Intent +## Fulfills Activity -[identify-best-practices](../intents/identify-best-practices.md) +[identify-best-practices](../activities/identify-best-practices.md) ## Tool Workflow diff --git a/src/__tests__/ail/agent/llm-agent-runner.ts b/src/__tests__/ail/agent/llm-agent-runner.ts index 09d88a1..8e26cf1 100644 --- a/src/__tests__/ail/agent/llm-agent-runner.ts +++ b/src/__tests__/ail/agent/llm-agent-runner.ts @@ -64,10 +64,10 @@ export class LLMAgentRunner { let totalPromptTokens = 0; let totalCompletionTokens = 0; - // Load skills interface content (intents, skills, guidance) + // Load skills interface content (activities, skills, guidance) const projectRoot = process.cwd(); const skillsFiles = [ - { path: 'prompts/intents/index.md', label: 'Intent Index' }, + { path: 'prompts/activities/index.md', label: 'Activity Index' }, { path: 'prompts/skills/index.md', label: 'Skill Index' }, { path: 'prompts/guidance.md', label: 'Research Guidelines' }, ]; @@ -95,7 +95,7 @@ export class LLMAgentRunner { }); messages.push({ role: 'assistant', - content: `I've reviewed the intentβ†’skillβ†’tool guidance:\n\n${fullContext}\n\nReady for your question.`, + content: `I've reviewed the activityβ†’skillβ†’tool guidance:\n\n${fullContext}\n\nReady for your question.`, }); // Now add the actual user question diff --git a/src/__tests__/ail/skills-interface.ail.test.ts b/src/__tests__/ail/skills-interface.ail.test.ts index d1ca1c2..81e0b01 100644 --- a/src/__tests__/ail/skills-interface.ail.test.ts +++ b/src/__tests__/ail/skills-interface.ail.test.ts @@ -1,9 +1,9 @@ /** * Agent-in-the-Loop E2E Tests - Skills Interface * - * Tests the intentβ†’skillβ†’tool workflow: - * - Agent receives intent/skill guidance as context - * - Agent matches query to appropriate intent + * Tests the activityβ†’skillβ†’tool workflow: + * - Agent receives activity/skill guidance as context + * - Agent matches query to appropriate activity * - Agent follows skill workflow for tool selection * * Success Criteria: @@ -34,7 +34,7 @@ const SKIP_AIL = process.env.AIL_TESTS !== 'true' || !config.apiKey; function loadSkillsContext(): string { const projectRoot = process.cwd(); const files = [ - 'prompts/intents/index.md', + 'prompts/activities/index.md', 'prompts/skills/index.md', 'prompts/guidance.md', ]; @@ -53,13 +53,13 @@ function loadSkillsContext(): string { /** * Skills Interface Test Scenarios * - * Each scenario maps to a specific intent and tests the expected skill workflow. + * Each scenario maps to a specific activity and tests the expected skill workflow. */ const SKILLS_SCENARIOS: TestScenario[] = [ - // Intent: understand-topic β†’ deep-research skill + // Activity: understand-topic β†’ deep-research skill { id: 'skills-understand-topic', - name: 'Intent: Understand Topic β†’ Deep Research Skill', + name: 'Activity: Understand Topic β†’ Deep Research Skill', tier: 2, goal: 'What does my library say about microservices architecture?', groundTruth: { @@ -72,14 +72,14 @@ const SKILLS_SCENARIOS: TestScenario[] = [ }, expectedTools: ['catalog_search', 'broad_chunks_search', 'chunks_search'], maxToolCalls: 12, - description: 'Tests understand-topic intent β†’ deep-research skill workflow', + description: 'Tests understand-topic activity β†’ deep-research skill workflow', tags: ['skills-interface', 'understand-topic', 'deep-research'], }, - // Intent: know-my-library β†’ library-discovery skill + // Activity: know-my-library β†’ library-discovery skill { id: 'skills-know-library', - name: 'Intent: Know My Library β†’ Library Discovery Skill', + name: 'Activity: Know My Library β†’ Library Discovery Skill', tier: 1, goal: 'What categories of documents do I have in my library?', groundTruth: { @@ -91,14 +91,14 @@ const SKILLS_SCENARIOS: TestScenario[] = [ }, expectedTools: ['list_categories', 'category_search'], maxToolCalls: 5, - description: 'Tests know-my-library intent β†’ library-discovery skill workflow', + description: 'Tests know-my-library activity β†’ library-discovery skill workflow', tags: ['skills-interface', 'know-my-library', 'library-discovery'], }, - // Intent: explore-concept β†’ concept-exploration skill + // Activity: explore-concept β†’ concept-exploration skill { id: 'skills-explore-concept', - name: 'Intent: Explore Concept β†’ Concept Exploration Skill', + name: 'Activity: Explore Concept β†’ Concept Exploration Skill', tier: 2, goal: 'Where is the concept of "dependency injection" discussed in my library?', groundTruth: { @@ -110,14 +110,14 @@ const SKILLS_SCENARIOS: TestScenario[] = [ }, expectedTools: ['concept_search', 'source_concepts'], maxToolCalls: 6, - description: 'Tests explore-concept intent β†’ concept-exploration skill workflow', + description: 'Tests explore-concept activity β†’ concept-exploration skill workflow', tags: ['skills-interface', 'explore-concept', 'concept-exploration'], }, - // Intent: analyze-document β†’ document-analysis skill + // Activity: analyze-document β†’ document-analysis skill { id: 'skills-analyze-document', - name: 'Intent: Analyze Document β†’ Document Analysis Skill', + name: 'Activity: Analyze Document β†’ Document Analysis Skill', tier: 2, goal: 'Extract the key concepts from Clean Architecture.', groundTruth: { @@ -129,14 +129,14 @@ const SKILLS_SCENARIOS: TestScenario[] = [ }, expectedTools: ['catalog_search', 'extract_concepts', 'chunks_search'], maxToolCalls: 6, - description: 'Tests analyze-document intent β†’ document-analysis skill workflow', + description: 'Tests analyze-document activity β†’ document-analysis skill workflow', tags: ['skills-interface', 'analyze-document', 'document-analysis'], }, - // Intent: explore-category β†’ category-exploration skill + // Activity: explore-category β†’ category-exploration skill { id: 'skills-explore-category', - name: 'Intent: Explore Category β†’ Category Exploration Skill', + name: 'Activity: Explore Category β†’ Category Exploration Skill', tier: 2, goal: 'What concepts are covered in the software engineering category?', groundTruth: { @@ -148,14 +148,14 @@ const SKILLS_SCENARIOS: TestScenario[] = [ }, expectedTools: ['list_categories', 'category_search', 'list_concepts_in_category'], maxToolCalls: 6, - description: 'Tests explore-category intent β†’ category-exploration skill workflow', + description: 'Tests explore-category activity β†’ category-exploration skill workflow', tags: ['skills-interface', 'explore-category', 'category-exploration'], }, - // Intent: identify-patterns β†’ pattern-research skill + // Activity: identify-patterns β†’ pattern-research skill { id: 'skills-identify-patterns', - name: 'Intent: Identify Patterns β†’ Pattern Research Skill', + name: 'Activity: Identify Patterns β†’ Pattern Research Skill', tier: 2, goal: 'What design patterns are recommended for handling errors in distributed systems?', groundTruth: { @@ -167,14 +167,14 @@ const SKILLS_SCENARIOS: TestScenario[] = [ }, expectedTools: ['broad_chunks_search', 'concept_search', 'chunks_search'], maxToolCalls: 20, - description: 'Tests identify-patterns intent β†’ pattern-research skill workflow', + description: 'Tests identify-patterns activity β†’ pattern-research skill workflow', tags: ['skills-interface', 'identify-patterns', 'pattern-research'], }, - // Intent: identify-best-practices β†’ practice-research skill + // Activity: identify-best-practices β†’ practice-research skill { id: 'skills-identify-practices', - name: 'Intent: Identify Best Practices β†’ Practice Research Skill', + name: 'Activity: Identify Best Practices β†’ Practice Research Skill', tier: 2, goal: 'What are the best practices for API design?', groundTruth: { @@ -186,7 +186,7 @@ const SKILLS_SCENARIOS: TestScenario[] = [ }, expectedTools: ['catalog_search', 'broad_chunks_search', 'chunks_search'], maxToolCalls: 20, - description: 'Tests identify-best-practices intent β†’ practice-research skill workflow', + description: 'Tests identify-best-practices activity β†’ practice-research skill workflow', tags: ['skills-interface', 'identify-best-practices', 'practice-research'], }, ]; @@ -223,14 +223,14 @@ describe('AIL Skills Interface Tests', () => { describe('Skills Context Validation', () => { it('should have skills context available', () => { const context = loadSkillsContext(); - expect(context).toContain('Intent Index'); + expect(context).toContain('Activity Index'); expect(context).toContain('Skill Index'); expect(context).toContain('understand-topic'); expect(context).toContain('deep-research'); }); }); - describe.skipIf(shouldSkip)('Intent β†’ Skill β†’ Tool Workflow', () => { + describe.skipIf(shouldSkip)('Activity β†’ Skill β†’ Tool Workflow', () => { it('should follow understand-topic β†’ deep-research workflow', async () => { const scenario = SKILLS_SCENARIOS.find(s => s.id === 'skills-understand-topic')!; diff --git a/src/__tests__/e2e/mcp-resources.e2e.test.ts b/src/__tests__/e2e/mcp-resources.e2e.test.ts index 09acf82..860991e 100644 --- a/src/__tests__/e2e/mcp-resources.e2e.test.ts +++ b/src/__tests__/e2e/mcp-resources.e2e.test.ts @@ -7,7 +7,7 @@ * Run with: npm test -- src/__tests__/e2e/mcp-resources.e2e.test.ts * * Tests validate: - * - All intent/skill resources are registered + * - All activity/skill resources are registered * - Resources return valid markdown content * - Resource URIs follow naming conventions * - Content contains expected sections @@ -29,16 +29,16 @@ const EXPECTED_RESOURCES = { // Guidance 'concept-rag://guidance': 'prompts/guidance.md', - // Intents - 'concept-rag://intents': 'prompts/intents/index.md', - 'concept-rag://intents/understand-topic': 'prompts/intents/understand-topic.md', - 'concept-rag://intents/know-my-library': 'prompts/intents/know-my-library.md', - 'concept-rag://intents/explore-concept': 'prompts/intents/explore-concept.md', - 'concept-rag://intents/analyze-document': 'prompts/intents/analyze-document.md', - 'concept-rag://intents/explore-category': 'prompts/intents/explore-category.md', - 'concept-rag://intents/identify-patterns': 'prompts/intents/identify-patterns.md', - 'concept-rag://intents/identify-best-practices': 'prompts/intents/identify-best-practices.md', - 'concept-rag://intents/curate-lexicon': 'prompts/intents/curate-lexicon.md', + // Activities + 'concept-rag://activities': 'prompts/activities/index.md', + 'concept-rag://activities/understand-topic': 'prompts/activities/understand-topic.md', + 'concept-rag://activities/know-my-library': 'prompts/activities/know-my-library.md', + 'concept-rag://activities/explore-concept': 'prompts/activities/explore-concept.md', + 'concept-rag://activities/analyze-document': 'prompts/activities/analyze-document.md', + 'concept-rag://activities/explore-category': 'prompts/activities/explore-category.md', + 'concept-rag://activities/identify-patterns': 'prompts/activities/identify-patterns.md', + 'concept-rag://activities/identify-best-practices': 'prompts/activities/identify-best-practices.md', + 'concept-rag://activities/curate-lexicon': 'prompts/activities/curate-lexicon.md', // Skills 'concept-rag://skills': 'prompts/skills/index.md', @@ -77,11 +77,11 @@ describe('MCP Resources E2E Tests', () => { }); }); - it('should have intent index with all intents listed', () => { - const indexPath = path.join(PROJECT_ROOT, 'prompts/intents/index.md'); + it('should have activity index with all activities listed', () => { + const indexPath = path.join(PROJECT_ROOT, 'prompts/activities/index.md'); const content = fs.readFileSync(indexPath, 'utf-8'); - // Should reference all intent files + // Should reference all activity files expect(content).toContain('understand-topic'); expect(content).toContain('know-my-library'); expect(content).toContain('explore-concept'); @@ -106,19 +106,19 @@ describe('MCP Resources E2E Tests', () => { expect(content).toContain('practice-research'); }); - it('should have each intent link to primary and supporting skills', () => { - const intentFiles = [ - 'prompts/intents/understand-topic.md', - 'prompts/intents/know-my-library.md', - 'prompts/intents/explore-concept.md', - 'prompts/intents/analyze-document.md', - 'prompts/intents/explore-category.md', - 'prompts/intents/identify-patterns.md', - 'prompts/intents/identify-best-practices.md', - 'prompts/intents/curate-lexicon.md', + it('should have each activity link to primary and supporting skills', () => { + const activityFiles = [ + 'prompts/activities/understand-topic.md', + 'prompts/activities/know-my-library.md', + 'prompts/activities/explore-concept.md', + 'prompts/activities/analyze-document.md', + 'prompts/activities/explore-category.md', + 'prompts/activities/identify-patterns.md', + 'prompts/activities/identify-best-practices.md', + 'prompts/activities/curate-lexicon.md', ]; - intentFiles.forEach(filePath => { + activityFiles.forEach(filePath => { const fullPath = path.join(PROJECT_ROOT, filePath); const content = fs.readFileSync(fullPath, 'utf-8'); @@ -171,14 +171,14 @@ describe('MCP Resources E2E Tests', () => { it('should have expected number of resources', () => { const resourceCount = Object.keys(EXPECTED_RESOURCES).length; - // 1 guidance + 9 intents (1 index + 8 intents) + 8 skills (1 index + 7 skills) = 18 + // 1 guidance + 9 activities (1 index + 8 activities) + 8 skills (1 index + 7 skills) = 18 expect(resourceCount).toBe(18); }); - it('should have 7 intent files plus index', () => { - const intentDir = path.join(PROJECT_ROOT, 'prompts/intents'); - const files = fs.readdirSync(intentDir).filter(f => f.endsWith('.md')); - expect(files.length).toBe(9); // 8 intents + index + it('should have 8 activity files plus index', () => { + const activityDir = path.join(PROJECT_ROOT, 'prompts/activities'); + const files = fs.readdirSync(activityDir).filter(f => f.endsWith('.md')); + expect(files.length).toBe(9); // 8 activities + index }); it('should have 7 skill files plus index', () => { @@ -194,10 +194,10 @@ describe('MCP Resources E2E Tests', () => { expect(fs.existsSync(ideSetupPath)).toBe(true); }); - it('should reference intents resource in ide-setup', () => { + it('should reference activities resource in ide-setup', () => { const ideSetupPath = path.join(PROJECT_ROOT, 'prompts/ide-setup.md'); const content = fs.readFileSync(ideSetupPath, 'utf-8'); - expect(content).toContain('concept-rag://intents'); + expect(content).toContain('concept-rag://activities'); }); }); }); diff --git a/src/conceptual_index.ts b/src/conceptual_index.ts index 107b3f5..f6c4c5d 100644 --- a/src/conceptual_index.ts +++ b/src/conceptual_index.ts @@ -32,75 +32,75 @@ const RESOURCES = [ mimeType: 'text/markdown', filePath: 'prompts/guidance.md', }, - // Intent resources (problem domain - user goals) + // Activity resources (problem domain - user goals) { - uri: 'concept-rag://intents', - name: 'Intent Index', - description: 'Index of user intents (goals). Read this first to match user goals to appropriate skills.', + uri: 'concept-rag://activities', + name: 'Activity Index', + description: 'Index of user activities (goals). Read this first to match user goals to appropriate skills.', mimeType: 'text/markdown', - filePath: 'prompts/intents/index.md', + filePath: 'prompts/activities/index.md', }, { - uri: 'concept-rag://intents/understand-topic', - name: 'Intent: Understand a Topic', - description: 'Intent for users who want to learn about a topic from their library.', + uri: 'concept-rag://activities/understand-topic', + name: 'Activity: Understand a Topic', + description: 'Activity for users who want to learn about a topic from their library.', mimeType: 'text/markdown', - filePath: 'prompts/intents/understand-topic.md', + filePath: 'prompts/activities/understand-topic.md', }, { - uri: 'concept-rag://intents/know-my-library', - name: 'Intent: Know My Library', - description: 'Intent for users who want to discover what content is available in their library.', + uri: 'concept-rag://activities/know-my-library', + name: 'Activity: Know My Library', + description: 'Activity for users who want to discover what content is available in their library.', mimeType: 'text/markdown', - filePath: 'prompts/intents/know-my-library.md', + filePath: 'prompts/activities/know-my-library.md', }, { - uri: 'concept-rag://intents/explore-concept', - name: 'Intent: Explore a Concept', - description: 'Intent for tracking where a concept appears across the library.', + uri: 'concept-rag://activities/explore-concept', + name: 'Activity: Explore a Concept', + description: 'Activity for tracking where a concept appears across the library.', mimeType: 'text/markdown', - filePath: 'prompts/intents/explore-concept.md', + filePath: 'prompts/activities/explore-concept.md', }, { - uri: 'concept-rag://intents/analyze-document', - name: 'Intent: Analyze a Document', - description: 'Intent for extracting and analyzing concepts from a specific document.', + uri: 'concept-rag://activities/analyze-document', + name: 'Activity: Analyze a Document', + description: 'Activity for extracting and analyzing concepts from a specific document.', mimeType: 'text/markdown', - filePath: 'prompts/intents/analyze-document.md', + filePath: 'prompts/activities/analyze-document.md', }, { - uri: 'concept-rag://intents/explore-category', - name: 'Intent: Explore a Category', - description: 'Intent for understanding what concepts appear in a domain/category.', + uri: 'concept-rag://activities/explore-category', + name: 'Activity: Explore a Category', + description: 'Activity for understanding what concepts appear in a domain/category.', mimeType: 'text/markdown', - filePath: 'prompts/intents/explore-category.md', + filePath: 'prompts/activities/explore-category.md', }, { - uri: 'concept-rag://intents/identify-patterns', - name: 'Intent: Identify Patterns', - description: 'Intent for identifying design patterns applicable to a problem.', + uri: 'concept-rag://activities/identify-patterns', + name: 'Activity: Identify Patterns', + description: 'Activity for identifying design patterns applicable to a problem.', mimeType: 'text/markdown', - filePath: 'prompts/intents/identify-patterns.md', + filePath: 'prompts/activities/identify-patterns.md', }, { - uri: 'concept-rag://intents/identify-best-practices', - name: 'Intent: Identify Best Practices', - description: 'Intent for identifying best practices and anti-patterns.', + uri: 'concept-rag://activities/identify-best-practices', + name: 'Activity: Identify Best Practices', + description: 'Activity for identifying best practices and anti-patterns.', mimeType: 'text/markdown', - filePath: 'prompts/intents/identify-best-practices.md', + filePath: 'prompts/activities/identify-best-practices.md', }, { - uri: 'concept-rag://intents/curate-lexicon', - name: 'Intent: Curate Concept Lexicon', - description: 'Intent for creating a curated vocabulary of concepts applicable to a project.', + uri: 'concept-rag://activities/curate-lexicon', + name: 'Activity: Curate Concept Lexicon', + description: 'Activity for creating a curated vocabulary of concepts applicable to a project.', mimeType: 'text/markdown', - filePath: 'prompts/intents/curate-lexicon.md', + filePath: 'prompts/activities/curate-lexicon.md', }, // Skill resources (solution domain - capabilities) { uri: 'concept-rag://skills', name: 'Skill Index', - description: 'Index of available skills (multi-tool workflows). Skills fulfill user intents.', + description: 'Index of available skills (multi-tool workflows). Skills fulfill user activities.', mimeType: 'text/markdown', filePath: 'prompts/skills/index.md', },