feat: Add advanced search capabilities and improve search query guidance in documentation

tikazyq · tikazyq · commit 7cf0a8b55da7 · 2025-11-26T14:32:29.000+08:00
diff --git a/AGENTS.md b/AGENTS.md
@@ -10,6 +10,16 @@ Lightweight spec methodology for AI-powered development.
 2. **Search** → `search` or `lean-spec search` before creating new specs  
 3. **Never create files manually** → Always use `create` tool or `lean-spec create`
 
+### 🔍 Search Query Best Practices
+
+| ✅ Good Query | ❌ Poor Query |
+|---------------|---------------|
+| `"search ranking"` | `"AI agent integration coding agent orchestration"` |
+| `"token validation"` | `"how to validate tokens in specs"` |
+| `"api"` + tags filter `["integration"]` | `"api integration feature"` |
+
+**Why?** All search terms must appear in the SAME field/line to match. Use 2-4 specific terms + filters instead of long queries.
+
 ## 🔧 Managing Specs
 
 ### MCP Tools (Preferred) with CLI Fallback
diff --git a/packages/cli/src/commands/create.ts b/packages/cli/src/commands/create.ts
@@ -12,6 +12,7 @@ import { normalizeDateFields } from '../frontmatter.js';
 import { autoCheckIfEnabled } from './check.js';
 import { sanitizeUserInput } from '../utils/ui.js';
 import { parseCustomFieldOptions } from '../utils/cli-helpers.js';
+import { linkSpec } from './link.js';
 
 /**
  * Create command - create new spec
@@ -28,6 +29,8 @@ export function createCommand(): Command {
     .option('--template <template>', 'Use a specific template')
     .option('--field <name=value...>', 'Set custom field (can specify multiple)')
     .option('--no-prefix', 'Skip date prefix even if configured')
+    .option('--depends-on <specs>', 'Add dependencies (comma-separated spec numbers or names)')
+    .option('--related <specs>', 'Add related specs (comma-separated spec numbers or names)')
     .action(async (name: string, options: {
       title?: string;
       description?: string;
@@ -37,6 +40,8 @@ export function createCommand(): Command {
       template?: string;
       field?: string[];
       prefix?: boolean;
+      dependsOn?: string;
+      related?: string;
     }) => {
       const customFields = parseCustomFieldOptions(options.field);
       const createOptions: {
@@ -48,6 +53,8 @@ export function createCommand(): Command {
         template?: string;
         customFields?: Record<string, unknown>;
         noPrefix?: boolean;
+        dependsOn?: string[];
+        related?: string[];
       } = {
         title: options.title,
         description: options.description,
@@ -57,6 +64,8 @@ export function createCommand(): Command {
         template: options.template,
         customFields: Object.keys(customFields).length > 0 ? customFields : undefined,
         noPrefix: options.prefix === false,
+        dependsOn: options.dependsOn ? options.dependsOn.split(',').map(s => s.trim()) : undefined,
+        related: options.related ? options.related.split(',').map(s => s.trim()) : undefined,
       };
       await createSpec(name, createOptions);
     });
@@ -71,6 +80,8 @@ export async function createSpec(name: string, options: {
   template?: string;
   customFields?: Record<string, unknown>;
   noPrefix?: boolean;
+  dependsOn?: string[];
+  related?: string[];
 } = {}): Promise<void> {
   const config = await loadConfig();
   const cwd = process.cwd();
@@ -286,6 +297,21 @@ export async function createSpec(name: string, options: {
     console.log(chalk.gray(`  Edit: ${sanitizeUserInput(specFile)}`));
   }
   
+  // Add dependencies and related specs if specified
+  const hasRelationships = (options.dependsOn && options.dependsOn.length > 0) || 
+                           (options.related && options.related.length > 0);
+  if (hasRelationships) {
+    const newSpecName = path.basename(specDir);
+    try {
+      await linkSpec(newSpecName, {
+        dependsOn: options.dependsOn?.join(','),
+        related: options.related?.join(','),
+      });
+    } catch (error: any) {
+      console.log(chalk.yellow(`⚠️  Warning: Failed to add relationships: ${error.message}`));
+    }
+  }
+  
   // Auto-check for conflicts after creation
   await autoCheckIfEnabled();
 }
diff --git a/packages/cli/src/mcp/tools/create.ts b/packages/cli/src/mcp/tools/create.ts
@@ -25,6 +25,8 @@ export function createTool(): ToolDefinition {
         priority: z.enum(['low', 'medium', 'high', 'critical']).optional().describe('Priority level for the spec. Defaults to "medium" if not specified.'),
         assignee: z.string().optional().describe('Person responsible for this spec.'),
         template: z.string().optional().describe('Template name to use (e.g., "minimal", "enterprise"). Uses default template if omitted.'),
+        dependsOn: z.array(z.string()).optional().describe('Specs this depends on (e.g., ["045-api-design", "046-database"]). Creates upstream dependencies.'),
+        related: z.array(z.string()).optional().describe('Related specs (e.g., ["047-frontend"]). Creates bidirectional relationships.'),
       },
       outputSchema: {
         success: z.boolean(),
@@ -49,6 +51,8 @@ export function createTool(): ToolDefinition {
           priority: input.priority as SpecPriority | undefined,
           assignee: input.assignee,
           template: input.template,
+          dependsOn: input.dependsOn,
+          related: input.related,
         });
 
         const output = {
diff --git a/packages/cli/src/mcp/tools/search.ts b/packages/cli/src/mcp/tools/search.ts
@@ -124,11 +124,24 @@ export function searchTool(): ToolDefinition {
     'search',
     {
       title: 'Search Specs',
-      description: 'Intelligent relevance-ranked search across all specification content. Uses field-weighted scoring (title > tags > description > content) to return the most relevant specs. Returns matching specs with relevance scores, highlighted excerpts, and metadata.',
+      description: `Intelligent relevance-ranked search across all specification content. Uses field-weighted scoring (title > tags > description > content) to return the most relevant specs.
+
+**Query Formulation Tips:**
+- Use 2-4 specific terms for best results (e.g., "search ranking" not "AI agent integration coding agent orchestration")
+- All terms must appear in the SAME field/line to match - keep queries focused
+- Prefer nouns and technical terms over common words
+- Use filters (status, tags, priority) to narrow scope instead of adding more search terms
+
+**Examples:**
+- Good: "search ranking" or "token validation"
+- Good: "api" with tags filter ["integration"]  
+- Poor: "AI agent integration coding agent orchestration" (too many terms, unlikely all in one line)
+
+Returns matching specs with relevance scores, highlighted excerpts, and metadata.`,
       inputSchema: {
-        query: z.string().describe('Search term or phrase to find in spec content. Multiple terms are combined with AND logic. Searches across titles, tags, descriptions, and body text with intelligent relevance ranking.'),
+        query: z.string().describe('Search term or phrase. Use 2-4 specific terms. All terms must appear in the same field/line to match. For broad concepts, use fewer terms + filters instead of long queries.'),
         status: z.enum(['planned', 'in-progress', 'complete', 'archived']).optional().describe('Limit search to specs with this status.'),
-        tags: z.array(z.string()).optional().describe('Limit search to specs with these tags.'),
+        tags: z.array(z.string()).optional().describe('Limit search to specs with these tags. Use this to narrow scope instead of adding more search terms.'),
         priority: z.enum(['low', 'medium', 'high', 'critical']).optional().describe('Limit search to specs with this priority.'),
       },
       outputSchema: {
diff --git a/specs/123-ai-coding-agent-integration/README.md b/specs/123-ai-coding-agent-integration/README.md
@@ -0,0 +1,221 @@
+---
+status: planned
+created: '2025-11-26'
+tags:
+  - ai-agents
+  - workflow
+  - automation
+  - cli
+  - integration
+  - parallel-development
+priority: high
+created_at: '2025-11-26T06:25:37.182Z'
+related:
+  - 118-parallel-spec-implementation
+  - 072-ai-agent-first-use-workflow
+  - 110-project-aware-agents-generation
+---
+
+# AI Coding Agent Integration for Automated Spec Orchestration
+
+> **Status**: 📅 Planned · **Priority**: High · **Created**: 2025-11-26
+
+**Project**: lean-spec  
+**Team**: Core Development
+
+## Overview
+
+Integrate AI coding agents (GitHub Copilot CLI, Claude Code, Gemini CLI, OpenChat, GitHub Coding Agent, etc.) directly into LeanSpec to automate spec implementation orchestration. Currently users manually manage agent sessions, branch creation, and spec status updates. This spec extends the parallel spec implementation work (spec 118) to enable seamless agent-driven development without manual coordination.
+
+**Problem**:
+- Users manually orchestrate AI agents to implement specs (copy context, manage branches, update status)
+- No unified interface across different agent types (CLI-based vs cloud-based)
+- Parallel spec implementation (spec 118) requires manual worktree management
+- Agent sessions are disconnected from spec lifecycle (status, dependencies, completion)
+
+**Goals**:
+1. Unified interface to dispatch specs to various AI coding agents
+2. Automatic environment setup (branches, worktrees) based on spec requirements
+3. Bi-directional sync between agent progress and spec status
+4. Support both CLI agents (local) and cloud agents (GitHub Coding Agent)
+5. Enable parallel spec implementation with minimal manual coordination
+
+## Design
+
+### Supported Agent Types
+
+**CLI-Based Agents (Local)**:
+- GitHub Copilot CLI (`gh copilot`)
+- Claude Code (Anthropic)
+- Gemini CLI (Google)
+- Aider
+- Continue.dev
+
+**Cloud-Based Agents**:
+- GitHub Coding Agent (creates PRs automatically)
+- Future: Other cloud coding services
+
+### Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    LeanSpec CLI / MCP                        │
+├─────────────────────────────────────────────────────────────┤
+│                   Agent Orchestrator                         │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
+│  │ CLI Adapter  │  │Cloud Adapter │  │ Status Sync  │      │
+│  │ (local exec) │  │  (API/GH)    │  │  (webhooks)  │      │
+│  └──────────────┘  └──────────────┘  └──────────────┘      │
+├─────────────────────────────────────────────────────────────┤
+│              Environment Manager                             │
+│  • Git worktree creation (parallel specs)                   │
+│  • Branch strategy enforcement                              │
+│  • Context injection (spec content → agent prompt)          │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Proposed Commands
+
+```bash
+# Dispatch a spec to an AI agent
+lean-spec agent run <spec> [--agent <type>] [--parallel]
+
+# Examples:
+lean-spec agent run 045 --agent claude      # Use Claude Code locally
+lean-spec agent run 045 --agent gh-coding   # Use GitHub Coding Agent (cloud)
+lean-spec agent run 045 --agent copilot     # Use GitHub Copilot CLI
+lean-spec agent run 045                     # Use default agent from config
+
+# Run multiple specs in parallel (extends spec 118)
+lean-spec agent run 045 047 048 --parallel  # Creates worktrees, dispatches agents
+
+# Check agent status
+lean-spec agent status [<spec>]
+
+# Configure default agent
+lean-spec config set default-agent claude
+```
+
+### MCP Tool Extensions
+
+```typescript
+// New MCP tools for agent orchestration
+mcp_lean-spec_agent_run     // Dispatch spec to agent
+mcp_lean-spec_agent_status  // Check agent progress
+mcp_lean-spec_agent_list    // List available agents
+```
+
+### Workflow Integration
+
+**Single Spec → Agent**:
+```bash
+lean-spec agent run 045 --agent claude
+# 1. Updates spec status to in-progress
+# 2. Creates feature branch (feature/045-dashboard)
+# 3. Injects spec content as agent context
+# 4. Launches agent with appropriate prompt
+# 5. Monitors for completion (optional webhook/polling)
+# 6. Updates spec status on completion
+```
+
+**Parallel Specs → Agents (extends spec 118)**:
+```bash
+lean-spec agent run 045 047 048 --parallel --agent claude
+# 1. Creates .worktrees/ for each spec
+# 2. Updates all specs to in-progress
+# 3. Dispatches agent to each worktree (separate sessions)
+# 4. Monitors all sessions
+# 5. Reports completion status
+```
+
+**Cloud Agent (GitHub Coding Agent)**:
+```bash
+lean-spec agent run 045 --agent gh-coding
+# 1. Creates GitHub issue from spec (if not exists)
+# 2. Triggers GitHub Coding Agent via API
+# 3. Agent creates branch + PR automatically
+# 4. LeanSpec monitors PR status via webhooks
+# 5. Updates spec status when PR merged
+```
+
+### Configuration
+
+```yaml
+# .leanspec/config.yaml
+agents:
+  default: claude
+  
+  claude:
+    type: cli
+    command: claude
+    context-template: |
+      Implement the following spec:
+      ---
+      {spec_content}
+      ---
+      Create the implementation in this worktree.
+  
+  gh-coding:
+    type: cloud
+    provider: github
+    # Uses GitHub App or PAT for API access
+  
+  copilot:
+    type: cli
+    command: gh copilot suggest
+```
+
+## Plan
+
+- [ ] Research agent APIs and CLI interfaces (Claude Code, Copilot CLI, Gemini CLI)
+- [ ] Design agent adapter interface (abstract common operations)
+- [ ] Implement CLI agent adapter (exec-based, stdin/stdout)
+- [ ] Implement GitHub Coding Agent adapter (API-based)
+- [ ] Create `lean-spec agent run` command
+- [ ] Integrate with worktree creation (spec 118)
+- [ ] Add spec status auto-update on agent events
+- [ ] Implement `lean-spec agent status` for monitoring
+- [ ] Add MCP tools for agent orchestration
+- [ ] Document agent setup for each supported provider
+- [ ] Create example workflows in docs
+
+## Test
+
+**Verification Criteria**:
+
+- [ ] Can dispatch a spec to Claude Code and have it start implementation
+- [ ] Can dispatch a spec to GitHub Coding Agent and receive PR
+- [ ] Parallel dispatch creates proper worktrees and isolated sessions
+- [ ] Spec status updates automatically on agent completion
+- [ ] Agent configuration is flexible and extensible
+- [ ] MCP tools work for AI-to-AI orchestration
+
+**Integration Tests**:
+
+- [ ] End-to-end: spec → agent → implementation → PR → status update
+- [ ] Parallel: 3 specs → 3 agents → 3 worktrees → all complete
+- [ ] Failure handling: agent error → spec status reflects failure
+
+## Notes
+
+**Open Questions**:
+- How to handle agent authentication (API keys, OAuth)?
+- Should we support custom agent prompts per spec/project?
+- How to handle long-running agents (timeout, checkpoints)?
+- Priority: CLI agents first (simpler) or cloud agents first (more powerful)?
+
+**Research Needed**:
+- Claude Code CLI interface and automation options
+- GitHub Coding Agent API (triggering, status checking)
+- Gemini CLI capabilities
+- Aider integration patterns
+
+**Related Work**:
+- Spec 118: Git worktrees for parallel development (foundation)
+- Spec 072: AI agent first-use workflow (onboarding)
+- Spec 110: Project-aware AGENTS.md generation (context)
+
+**Alternatives Considered**:
+- IDE-only integration (VS Code tasks) - too narrow
+- Shell scripts only - not portable, hard to maintain
+- Full orchestration platform - too complex for LeanSpec's lean philosophy
diff --git a/specs/124-advanced-search-capabilities/README.md b/specs/124-advanced-search-capabilities/README.md
