MCP-First Agent Experience: Multi-Tool Support & SDD Compliance

Status: ✅ Complete · Priority: High · Created: 2025-11-26 · Tags: mcp, ai-agents, ux, init, dx

Project: lean-spec
Team: Core Development

Overview

Problem: AI Agents Don't Follow MCP-Based SDD Workflow

Real user feedback indicates significant friction with current AGENTS.md approach:

Issue 1: Tool-Specific File Names

Claude Code doesn't read AGENTS.md by default - requires CLAUDE.md
Gemini CLI looks for GEMINI.md
Other tools have their own conventions
Users must manually create symlinks, breaking quick-start experience

Issue 2: AGENTS.md Not MCP-Focused

Current template mentions CLI commands as primary method
MCP tools appear as "alternative" rather than preferred approach
AI agents default to CLI or manual file operations instead of MCP tools
User quote: "效果不是很好" (not working well)

Issue 3: SDD Compliance Degrades Over Time

AI agents create specs correctly initially
After 2-3 conversations, agents forget to update specs with progress
No clear reminder about ongoing SDD obligations
Specs become stale/disconnected from actual work

Root Causes

File naming: AGENTS.md is a convention, not universal standard
MCP buried in docs: CLI commands listed first, MCP mentioned later
One-time instructions: AGENTS.md read once at session start, not reinforced
No session reminders: Agents have no "checkpoint" to re-read SDD rules

Success Criteria

After implementation:

✅ lean-spec init creates tool-specific symlinks (CLAUDE.md → AGENTS.md, etc.)
✅ AGENTS.md emphasizes MCP tools as PRIMARY method
✅ AI agents use MCP tools (not CLI) for spec operations
✅ AI agents maintain SDD compliance across multi-turn conversations
✅ Specs stay in sync with implementation progress

Design

Part 1: Multi-Tool Symlink Support

During lean-spec init:

? Which AI tools do you use? (Select all that apply)
  ◉ Claude Code / Claude Desktop (CLAUDE.md)
  ◉ GitHub Copilot (AGENTS.md - default)
  ◯ Gemini CLI (GEMINI.md)
  ◯ Cursor / Windsurf (uses AGENTS.md)
  ◯ Other (AGENTS.md)

Creating agent instruction files...
  ✓ AGENTS.md (primary)
  ✓ CLAUDE.md → AGENTS.md (symlink)

File Structure After Init:

project/
├── AGENTS.md           # Primary file (always created)
├── CLAUDE.md → AGENTS.md   # Symlink for Claude Code
├── GEMINI.md → AGENTS.md   # Symlink for Gemini CLI (if selected)
└── .lean-spec/

Why Symlinks?

Single source of truth (edit AGENTS.md, all tools see updates)
No duplication or sync issues
Git-friendly (symlinks track correctly)
Easy to add more tools later

Non-Interactive Mode:

# Create all common symlinks
lean-spec init -y --agent-tools all

# Create specific symlinks
lean-spec init -y --agent-tools claude,gemini

# Skip symlinks (legacy behavior)
lean-spec init -y --agent-tools none

Part 2: MCP-First AGENTS.md Rewrite

Current Structure (Problems):

## Essential Commands
**Discovery:**
- `lean-spec list` - See all specs
- `lean-spec search "<query>"` - Find relevant specs
...

New Structure (MCP-First):

## 🔧 How to Manage Specs

### Primary Method: MCP Tools (Recommended)

If you have LeanSpec MCP server configured, **ALWAYS use MCP tools**:

| Action | MCP Tool | Why MCP is Better |
|--------|----------|-------------------|
| See project status | `board` | Kanban view + health metrics |
| List all specs | `list` | Filterable, structured data |
| Search specs | `search` | Semantic search across content |
| View a spec | `view` | Formatted output with metadata |
| Create spec | `create` | Auto-sequences, proper structure |
| Update status | `update` | Validates transitions, timestamps |
| Check dependencies | `deps` | Visual dependency graph |

**Why MCP over CLI?**
- ✅ Direct tool integration (no shell execution)
- ✅ Structured responses (better for AI reasoning)
- ✅ Real-time validation (immediate feedback)
- ✅ Context-aware (knows your project state)

### Fallback: CLI Commands

If MCP is not available, use CLI:
- `lean-spec board` - Project overview
- `lean-spec list` - See all specs
- `lean-spec create <name>` - Create new spec
- `lean-spec update <spec> --status <status>` - Update status

**Check MCP availability first**: If you see LeanSpec tools in your available tools, use them!

Part 3: SDD Compliance Reinforcement

Problem: AI agents read AGENTS.md once, then forget SDD rules.

Solution 1: Persistent Reminders in AGENTS.md

Add a new section that's impossible to miss:

## ⚠️ CRITICAL: SDD Workflow Checkpoints

**Before EVERY task**, check:
1. 📋 Run `board` tool - What's the current project state?
2. 🔍 Run `search` tool - Are there related specs?
3. 📝 Is there an existing spec for this work?

**During implementation**, remember:
4. 📊 Update spec status to `in-progress` BEFORE coding
5. 📝 Document decisions/changes in the spec as you work
6. ✅ Update spec status to `complete` AFTER finishing

**After EVERY task**, ask yourself:
- Did I update the spec with what I learned?
- Did I change the status appropriately?
- Are there new specs needed for follow-up work?

### 🚨 Common Mistakes to Avoid

❌ Creating files without checking existing specs first
❌ Implementing features without updating spec status
❌ Finishing work without documenting decisions in spec
❌ Leaving spec status as "planned" after starting work
❌ Using manual file creation instead of MCP tools

Solution 2: Session Checkpoint Prompt (New MCP Tool)

Add a new MCP prompt checkpoint:

// New MCP prompt: checkpoint
{
  name: "checkpoint",
  description: "SDD compliance reminder - call this periodically during long sessions",
  template: `
## SDD Checkpoint ✅

Before continuing, verify:

1. **Current Specs**: {{board_summary}}
2. **Active Work**: {{in_progress_specs}}
3. **Your Task**: Does it relate to an existing spec?

### Action Required:
- If working on existing spec: Is status `in-progress`?
- If new work: Create spec with \`create\` tool first
- If finished: Update status to \`complete\`

Remember: **Specs are the source of truth. Keep them in sync!**
  `
}

Solution 3: Reminder in MCP Tool Responses

Add gentle reminders to MCP tool outputs:

// After create_spec
return {
  result: "Spec 121-my-feature created",
  reminder: "💡 Remember to update status to 'in-progress' when you start implementing!"
}

// After list/board showing stale specs
return {
  result: [...],
  warning: "⚠️ Spec 045 has been 'in-progress' for 7 days. Consider updating status."
}

Part 4: Enhanced Init Flow

New Interactive Init:

$ lean-spec init

Welcome to LeanSpec! 🚀

? Choose your setup:
  ❯ Quick Start (recommended for most projects)
    Full Setup (customize everything)
    Example Project (learn with a tutorial)

? Which AI tools do you use? (affects agent instruction files)
  ◉ Claude Code / Claude Desktop
  ◉ GitHub Copilot  
  ◯ Gemini CLI
  ◯ Cursor / Windsurf
  ◯ Warp Terminal
  ◯ Other

? Enable MCP integration guidance? (recommended)
  ❯ Yes - Include MCP setup instructions in AGENTS.md
    No - CLI-only instructions

Creating LeanSpec project...
  ✓ .lean-spec/config.json
  ✓ .lean-spec/templates/
  ✓ specs/
  ✓ AGENTS.md (with MCP-first instructions)
  ✓ CLAUDE.md → AGENTS.md

🎉 LeanSpec initialized!

Next steps:
  1. Configure MCP server (see AGENTS.md for instructions)
  2. Start your AI tool and ask: "Show me the project board"
  3. Create your first spec: "Create a spec for [feature]"

Plan

Phase 1: Multi-Tool Symlink Support

Add AI tool selection to init prompts
Create symlink generation logic (CLAUDE.md, GEMINI.md, etc.)
Add --agent-tools CLI flag for non-interactive mode
Handle Windows (use file copy instead of symlink if needed)
Update init success message with created files
Test symlinks work with actual AI tools

Phase 2: MCP-First AGENTS.md

Rewrite packages/cli/templates/standard/AGENTS.md
Rewrite packages/cli/templates/detailed/AGENTS.md
Add "How to Manage Specs" section with MCP-first approach
Add MCP vs CLI comparison table
Add tool availability check guidance
Update SDD Workflow with MCP tools

Phase 3: SDD Compliance Reinforcement

Add "SDD Workflow Checkpoints" section to AGENTS.md
Add "Common Mistakes" section with clear ❌/✅ examples
Create checkpoint MCP prompt for periodic reminders
Add gentle reminders to MCP tool responses
Add stale spec warnings to board/list outputs

Phase 4: Documentation & Testing

Update docs-site MCP integration guide
Update agent-configuration.mdx with new structure
Add Chinese translations for new content
Test with GitHub Copilot MCP (this session validates workflow)
Test with Claude Code (real user flow)
Test with Gemini CLI
Collect user feedback

Test

Multi-Tool Symlinks

lean-spec init shows AI tool selection prompt
Selecting "Claude Code" creates CLAUDE.md symlink
Selecting "Gemini CLI" creates GEMINI.md symlink
Symlinks point to AGENTS.md correctly
Editing AGENTS.md reflects in symlinked files
--agent-tools all creates all symlinks non-interactively
--agent-tools none skips symlink creation
Windows handles lack of symlink support gracefully

MCP-First Content

AGENTS.md lists MCP tools before CLI commands
MCP vs CLI comparison table is clear
"Check MCP availability" guidance is prominent
SDD Workflow uses MCP tool names (not CLI)

SDD Compliance

"SDD Workflow Checkpoints" section exists in AGENTS.md
"Common Mistakes" section lists anti-patterns clearly
checkpoint MCP prompt returns useful reminder
Stale spec warnings appear in board output
AI agents (Claude Code) follow MCP-first approach
AI agents update specs after completing work

Real-World Validation

User with Claude Code reports improved experience
AI agent uses MCP tools (verified via MCP logs)
Specs stay in sync over multi-turn conversations
No manual CLAUDE.md creation needed

Notes

Why Not Just Rename AGENTS.md?

Considered renaming AGENTS.md to tool-specific names:

❌ Breaks existing projects
❌ No single source of truth
❌ Must maintain multiple files
✅ Symlinks: Best of both worlds

Tool-Specific Conventions Research

Tool	Expected File	Source
Claude Code	CLAUDE.md	Anthropic Docs
Claude Desktop	Uses MCP directly	N/A
GitHub Copilot	AGENTS.md	GitHub Docs
Gemini CLI	GEMINI.md	Google Docs
Cursor	.cursorrules, AGENTS.md	Cursor docs
Windsurf	.windsurfrules, AGENTS.md	Codeium docs
Cline	AGENTS.md	Cline docs

MCP Tool Priority Order

For AGENTS.md, recommend tools in this order:

board - Best first-run experience (visual, comprehensive)
list - Alternative overview
search - Finding specific specs
view - Reading spec details
create - Creating new specs
update - Modifying specs

Session Persistence Challenge

Core Problem: LLMs have no memory between sessions. AGENTS.md is read once.

Mitigations:

Make critical info unmissable (top of file, emojis, formatting)
Add checkpoints (periodic reminders via MCP prompt)
Tool-level reminders (in MCP responses)
User training (documentation on how to prompt effectively)

Not Solvable:

Can't force agents to re-read AGENTS.md mid-session
Can't inject reminders into arbitrary conversations
Can't modify agent system prompts directly

Best Approach: Front-load critical info + periodic MCP checkpoints

072-ai-agent-first-use-workflow - First interaction protocol (complementary)
110-project-aware-agents-generation - Context-aware AGENTS.md (future enhancement)
073-template-engine-agents-md - Template system (dependency)

Open Questions

Should symlinks be the default?
- Pro: Better UX for Claude Code users (majority?)
- Con: Adds complexity, may confuse some users
- Tentative: Yes for Quick Start, optional for Full Setup
How to detect which AI tool is running?
- Could add environment variable detection
- Could check for MCP connection type
- Decision: Start with user selection, consider auto-detect later
Should we add tool-specific sections to AGENTS.md?
- E.g., "If you're Claude Code, do X; if Copilot, do Y"
- Decision: Avoid - keep instructions universal, use MCP as common interface
How often should checkpoint be called?
- Every N messages? Every task? User-triggered?
- Decision: Document as "call periodically", let users decide

Bug Fixes (Post-Completion)

2025-11-26: Quick Start mode wasn't showing AI tool selection

Issue: The AI tool selection prompt was only shown in "Choose template" mode, not "Quick start" mode
Root cause: Condition setupMode !== 'quick' incorrectly skipped the prompt
Fix: Removed the setupMode !== 'quick' condition; now AI tools prompt shows for all interactive modes
Impact: Users selecting Quick Start now see the AI tools prompt as designed

MCP-First Agent Experience: Multi-Tool Support & SDD Compliance

Overview

Problem: AI Agents Don't Follow MCP-Based SDD Workflow

Root Causes

Success Criteria

Design

Part 1: Multi-Tool Symlink Support

Part 2: MCP-First AGENTS.md Rewrite

Part 3: SDD Compliance Reinforcement

Part 4: Enhanced Init Flow

Plan

Phase 1: Multi-Tool Symlink Support

Phase 2: MCP-First AGENTS.md

Phase 3: SDD Compliance Reinforcement

Phase 4: Documentation & Testing

Test

Multi-Tool Symlinks

MCP-First Content

SDD Compliance

Real-World Validation

Notes

Why Not Just Rename AGENTS.md?

Tool-Specific Conventions Research

MCP Tool Priority Order

Session Persistence Challenge

Related Specs

Open Questions

Bug Fixes (Post-Completion)