feat(mcp-tools): add link and unlink commands to MCP tools and update AGENTS.md

Author: Marvin Zhang

AGENTS.md

@@ -32,9 +32,13 @@ Lightweight spec methodology for AI-powered development.
 | View spec | `view` | `lean-spec view <spec>` |
 | Create spec | `create` | `lean-spec create <name>` |
 | Update spec | `update` | `lean-spec update <spec> --status <status>` |
+| Link specs | `create --related` | `lean-spec link <spec> --related <other>` |
+| Unlink specs | ❌ CLI only | `lean-spec unlink <spec> --related <other>` |
 | Dependencies | `deps` | `lean-spec deps <spec>` |
 | Token count | `tokens` | `lean-spec tokens <spec>` |
 
+**⚠️ Link/Unlink**: Use `--related` or `--depends-on` params in `create` tool. For existing specs, use CLI fallback. (See spec 129 for MCP tool tracking)
+
 **Local Development:** Use `node bin/lean-spec.js <command>` instead of `npx lean-spec`. Build first with `pnpm build`.
 
 ## ⚠️ Core Rules

docs-site

@@ -12,10 +12,11 @@ related:
   - 046-stats-dashboard-refactor
   - 014-complete-custom-frontmatter
   - 118-parallel-spec-implementation
+  - 128-constant-time-migration
 created_at: '2025-11-04T22:58:23+08:00'
-updated_at: '2025-11-26T06:04:17.915Z'
+updated_at: '2025-11-28T01:24:56.696Z'
 assignee: Marvin Zhang
-updated: '2025-11-26'
+updated: '2025-11-28'
 completed_at: '2025-11-04T15:08:31.110Z'
 completed: '2025-11-04'
 transitions:

specs/047-git-backfill-timestamps/README.md

@@ -10,7 +10,7 @@ priority: medium
 created_at: '2025-11-16T13:33:40.858Z'
 depends_on:
   - 035-live-specs-showcase
-updated_at: '2025-11-26T06:03:58.540Z'
+updated_at: '2025-11-28T01:27:53.930Z'
 related:
   - 076-programmatic-spec-relationships
   - 081-web-app-ux-redesign
@@ -19,6 +19,7 @@ related:
   - 080-mcp-server-modular-architecture
   - 059-programmatic-spec-management
   - 086-template-component-deduplication
+  - 129-mcp-link-tool
 completed_at: '2025-11-16T14:08:51.283Z'
 completed: '2025-11-16'
 transitions:

specs/085-cli-relationship-commands/README.md

@@ -0,0 +1,113 @@
+---
+status: planned
+created: '2025-11-28'
+tags:
+  - cli
+  - migration
+  - dx
+  - performance
+priority: high
+created_at: '2025-11-28T01:21:44.679Z'
+updated_at: '2025-11-28T01:24:56.701Z'
+related:
+  - 047-git-backfill-timestamps
+---
+
+# Constant-Time Migration (O(1) UX)
+
+> **Status**: 🗓️ Planned · **Priority**: High · **Created**: 2025-11-28 · **Tags**: cli, migration, dx, performance
+
+**Project**: lean-spec  
+**Team**: Core Development
+
+## Overview
+
+Migration time should NOT scale with the number of existing specs. Whether you have 10 or 1000 specs, the migration experience should feel instant.
+
+**Problem**: Current migration process is O(n) where n = number of specs. The time estimates table shows linear scaling (100 specs = 3x time of 20 specs). This is unacceptable for larger projects.
+
+**Goal**: Achieve O(1) *perceived* migration time regardless of spec count.
+
+## Problem Analysis
+
+### Current Pain Points
+
+1. **Manual folder restructuring** - Each spec requires individual attention
+2. **Sequential renaming** - `spec.md → README.md` one by one  
+3. **Backfill is already fast** - This scales well via git operations
+4. **Validation per-spec** - Must check each spec individually
+
+### Why O(n) Is Bad for AI Era
+
+- AI agents work in parallel, shouldn't wait for migrations
+- Large projects shouldn't be punished
+- Migration should be "invisible" - just works
+
+## Design
+
+### Strategy: Batch Everything, Parallelize, Cache
+
+**Phase 1: One-Shot Folder Transform**
+```bash
+lean-spec migrate ./source --auto
+```
+
+This single command should:
+1. Auto-detect source format (spec-kit, OpenSpec, generic markdown)
+2. Bulk rename/restructure in one pass (using filesystem batch ops)
+3. Run backfill in parallel across all specs
+4. Validate all at once (not per-spec)
+
+**Phase 2: AI-Assisted Instant Migration**
+
+For any source format, generate a single AI prompt that handles ALL specs at once:
+```bash
+lean-spec migrate ./source --ai
+```
+
+Outputs a comprehensive migration script that the AI executes in one shot.
+
+**Phase 3: Zero-Touch Migration**
+
+Ideal future state:
+```bash
+lean-spec init  # Detects existing specs anywhere, migrates automatically
+```
+
+### Key Insight
+
+**Don't process specs one-by-one. Process the entire specs directory as a single unit.**
+
+- Batch `mv` operations via shell
+- Parallel `git log` queries (already supported)
+- Single-pass validation with aggregated results
+
+## Plan
+
+- [ ] Audit current migration bottlenecks (profile with 100+ specs)
+- [ ] Implement batch folder restructure (`migrate --auto`)
+- [ ] Add auto-detection for source formats
+- [ ] Parallelize backfill across specs
+- [ ] Update `validate` to batch mode
+- [ ] Update docs to show single-command migration
+- [ ] Remove per-spec time estimates (irrelevant if instant)
+
+## Test
+
+- [ ] Migration of 100 specs completes in < 30 seconds
+- [ ] Migration of 500 specs completes in < 60 seconds  
+- [ ] Time increase from 100 → 500 specs is < 2x (not 5x)
+- [ ] Single command handles entire migration
+
+## Success Metrics
+
+| Spec Count | Current Time | Target Time |
+|------------|--------------|-------------|
+| 20 | 5-30 min | < 30 sec |
+| 100 | 15-60 min | < 30 sec |
+| 500 | hours | < 60 sec |
+
+## Notes
+
+Related: [063-migration-from-existing-tools](../063-migration-from-existing-tools) - original migration design
+Related: [047-git-backfill-timestamps](../047-git-backfill-timestamps) - backfill command (already performant)

specs/128-constant-time-migration/README.md

@@ -0,0 +1,113 @@
+---
+status: planned
+created: '2025-11-28'
+tags:
+  - mcp
+  - tooling
+  - dx
+  - ai-agents
+priority: high
+created_at: '2025-11-28T01:27:53.890Z'
+related:
+  - 085-cli-relationship-commands
+updated_at: '2025-11-28T01:27:53.931Z'
+---
+
+# Add `link` and `unlink` MCP Tools
+
+> **Status**: 🗓️ Planned · **Priority**: High · **Created**: 2025-11-28 · **Tags**: mcp, tooling, dx, ai-agents
+
+**Project**: lean-spec  
+**Team**: Core Development
+
+## Overview
+
+The `link` and `unlink` commands exist in CLI but are not exposed as MCP tools. This creates a gap where AGENTS.md tells AI agents to use tools that don't exist in MCP context.
+
+### Problem
+
+1. **AGENTS.md says**: "ALWAYS link spec references → use `link` tool"
+2. **MCP Tools table** lists `link` as available
+3. **Reality**: No `link.ts` in `packages/cli/src/mcp/tools/`
+
+This causes AI agents to:
+- Try to use a non-existent MCP tool
+- Fall back to CLI (extra step, breaks flow)
+- Sometimes forget to link at all (spec 128 incident)
+
+### Workarounds (Current)
+
+1. Use `--related` / `--depends-on` at `create` time (works but easy to forget)
+2. Fall back to CLI: `lean-spec link <spec> --related <other>`
+
+## Design
+
+### Tooling Fix: Add MCP Tools
+
+Create two new MCP tools following existing patterns:
+
+**`packages/cli/src/mcp/tools/link.ts`**
+```typescript
+// Expose linkSpec() from commands/link.js
+inputSchema: {
+  specPath: z.string().describe('Spec to add relationships to'),
+  dependsOn: z.string().optional().describe('Comma-separated specs this depends on'),
+  related: z.string().optional().describe('Comma-separated related specs'),
+}
+```
+
+**`packages/cli/src/mcp/tools/unlink.ts`**
+```typescript
+// Expose unlinkSpec() from commands/unlink.js
+inputSchema: {
+  specPath: z.string().describe('Spec to remove relationships from'),
+  dependsOn: z.string().optional().describe('Comma-separated dependencies to remove'),
+  related: z.string().optional().describe('Comma-separated related specs to remove'),
+}
+```
+
+### Process Fix: Update AGENTS.md
+
+Until tools are added, clarify the workaround:
+
+```markdown
+| Action | MCP Tool | CLI Fallback |
+|--------|----------|--------------|
+| Link specs | `create --related` | `lean-spec link <spec> --related <other>` |
+| Unlink specs | ❌ CLI only | `lean-spec unlink <spec> --related <other>` |
+```
+
+### Best Practice: Include relationships at creation
+
+When creating a spec that references others, always include `related` or `dependsOn`:
+
+```
+mcp_lean-spec_create(
+  name: "my-feature",
+  related: ["063", "047"]  // ← Don't forget!
+)
+```
+
+## Plan
+
+- [ ] Create `packages/cli/src/mcp/tools/link.ts`
+- [ ] Create `packages/cli/src/mcp/tools/unlink.ts`
+- [ ] Register tools in `packages/cli/src/mcp/tools/registry.ts`
+- [ ] Add tests for new MCP tools
+- [ ] Update AGENTS.md MCP Tools table (remove "CLI only" note after impl)
+- [ ] Rebuild and test with MCP client
+
+## Test
+
+- [ ] `mcp_lean-spec_link` successfully adds relationships
+- [ ] `mcp_lean-spec_unlink` successfully removes relationships
+- [ ] Bidirectional links work correctly via MCP
+- [ ] Error handling for invalid spec paths
+
+## Notes
+
+Related: [085-cli-relationship-commands](../085-cli-relationship-commands) - original `link`/`unlink` CLI implementation
+
+### Interim AGENTS.md Update
+
+Until this is implemented, update AGENTS.md to note `link` requires CLI fallback.