feat: Enhance MCP-first agent experience and improve dependency validation in AGENTS.md

Author: tikazyq

AGENTS.md

@@ -4,260 +4,123 @@
 
 Lightweight spec methodology for AI-powered development.
 
-## First Principles (Decision Framework)
+## 🚨 CRITICAL: Before ANY Task
 
-When making spec decisions, apply these principles in priority order:
+1. **Discover** → `board` or `lean-spec board` to see project state
+2. **Search** → `search` or `lean-spec search` before creating new specs  
+3. **Never create files manually** → Always use `create` tool or `lean-spec create`
 
-### 1. Context Economy - Fit in working memory
-**Specs must fit in working memory—both human and AI.**
+## 🔧 Managing Specs
 
-- **Target**: <2,000 tokens per spec file
-- **Warning**: 2,000-3,500 tokens (acceptable but watch complexity)
-- **Problem**: >3,500 tokens (consider splitting)
-- **Question**: "Can this be read in 5-10 minutes? Can you hold the entire structure in your head?"
-- **Why**: Attention and cognitive capacity are scarce resources. AI performance degrades with longer context (quality drops beyond 50K tokens despite 200K limits). Humans can't hold >7 concepts in working memory. **Use `lean-spec tokens <spec>` to check.**
+### MCP Tools (Preferred) with CLI Fallback
 
-### 2. Signal-to-Noise Maximization - Every word informs decisions
-**Every word must inform decisions or be cut.**
+| Action | MCP Tool | CLI Fallback |
+|--------|----------|--------------|
+| Project status | `board` | `lean-spec board` |
+| List specs | `list` | `lean-spec list` |
+| Search specs | `search` | `lean-spec search "query"` |
+| View spec | `view` | `lean-spec view <spec>` |
+| Create spec | `create` | `lean-spec create <name>` |
+| Update spec | `update` | `lean-spec update <spec> --status <status>` |
+| Dependencies | `deps` | `lean-spec deps <spec>` |
+| Token count | `tokens` | `lean-spec tokens <spec>` |
 
-- **Test**: "What decision does this sentence inform?"
-- **Cut**: Obvious, inferable, or "maybe future" content
-- **Keep**: Decision rationale, constraints, success criteria
-- **Action**: Remove anything that doesn't answer the test question
-- **Why**: While Context Economy asks "Can you hold it all?", Signal-to-Noise asks "Is each piece worth holding?" Cognitive load, token costs, and maintenance burden all penalize low-value content.
+**Local Development:** Use `node bin/lean-spec.js <command>` instead of `npx lean-spec`. Build first with `pnpm build`.
 
-### 3. Intent Over Implementation - Capture why, not just how
-**Capture "why" and "what," let "how" emerge.**
+## ⚠️ Core Rules
 
-- **Must have**: Problem, intent, success criteria
-- **Should have**: Design rationale, trade-offs
-- **Could have**: Implementation details, examples
-- **Question**: "Is the rationale clear?"
-- **Action**: Explain trade-offs, constraints, success criteria
-- **Why**: Intent is stable, implementation changes, AI needs why
+| Rule | Details |
+|------|---------|
+| **NEVER edit frontmatter manually** | Use `update`, `link`, `unlink` for: `status`, `priority`, `tags`, `assignee`, `transitions`, timestamps, `depends_on`, `related` |
+| **ALWAYS link spec references** | Content mentions another spec → `lean-spec link <spec> --related <other>` or `--depends-on <other>` |
+| **Track status transitions** | `planned` → `in-progress` (before coding) → `complete` (after done) |
+| **No nested code blocks** | Use indentation instead |
 
-### 4. Bridge the Gap - Both human and AI must understand
-**Specs exist to align human intent with machine execution.**
+### 🚫 Common Mistakes
 
-- **For humans**: Overview, context, rationale
-- **For AI**: Unambiguous requirements, clear structure, examples
-- **Both must understand**: Use clear structure + natural language
-- **Question**: "Can both parse and reason about this?"
-- **Action**: Clear structure + natural language explanation
-- **Why**: Gap between human goals and machine execution must be bridged
+| ❌ Don't | ✅ Do Instead |
+|----------|---------------|
+| Create spec files manually | Use `create` tool |
+| Skip discovery | Run `board` and `search` first |
+| Leave status as "planned" | Update to `in-progress` before coding |
+| Edit frontmatter manually | Use `update` tool |
 
-### 5. Progressive Disclosure - Add complexity when pain is felt
-**Start simple, add structure only when pain is felt.**
+## 📋 SDD Workflow
 
-- **Solo dev**: Just status + created
-- **Feel pain?**: Add tags, priority, custom fields
-- **Never add**: "Just in case" features
-- **Question**: "Do we need this now?"
-- **Action**: Start minimal, add fields when required
-- **Why**: Teams evolve, requirements emerge, premature abstraction is waste
-
-### Conflict Resolution Examples
-
-When practices conflict, apply principles in priority order:
-
-**"Should I split this 4,000-token spec?"**
-→ **Yes** (Context Economy: >3,500 tokens needs splitting)
-
-**"Should I document every edge case?"**
-→ **Only if it informs current decisions** (Signal-to-Noise test)
-
-**"Should I add custom fields upfront?"**
-→ **Only if you feel pain without them** (Progressive Disclosure)
-
-**"This spec is complex but only 2,500 tokens, split it?"**
-→ **No** (Under Context Economy warning threshold)
-
-## Core Rules
-
-1. **Read README.md first** - Understand project context
-2. **Check specs/** - Review existing specs before starting
-3. **Use `lean-spec --help`** - When unsure about commands, check the built-in help
-4. **Follow LeanSpec principles** - Clarity over documentation
-5. **Keep it minimal** - If it doesn't add clarity, cut it
-6. **NEVER manually edit system-managed frontmatter** - Fields like `status`, `priority`, `tags`, `assignee`, `transitions`, `created_at`, `updated_at`, `completed_at`, `depends_on`, `related` are system-managed. Always use `lean-spec update`, `lean-spec link`, `lean-spec unlink`, or `lean-spec create` commands. Manual edits will cause metadata corruption and tracking issues.
-7. **Never use nested code blocks** - Markdown doesn't support code blocks within code blocks. If you need to show code examples in documentation, use indentation or describe the structure instead of nesting backticks.
-8. **ALWAYS link spec dependencies** - When a spec mentions or references another spec in its content, you MUST add it to frontmatter using `lean-spec link <spec> --related <other>` or `lean-spec link <spec> --depends-on <other>`. Content and frontmatter must stay aligned.
-
-## When to Use Specs
-
-Write a spec for:
-- Features affecting multiple parts of the system
-- Breaking changes or significant refactors
-- Design decisions needing team alignment
-
-Skip specs for:
-- Bug fixes
-- Trivial changes
-- Self-explanatory refactors
-
-## Essential Commands
-
-**Quick Reference** (for full details, see [docs/agents/COMMANDS.md](docs/agents/COMMANDS.md)):
-
-**Discovery:**
-- `lean-spec list` - See all specs
-- `lean-spec search "<query>"` - Find relevant specs
-
-**Working with specs:**
-- `lean-spec create <name>` - Create new spec
-- `lean-spec update <spec> --status <status>` - Update status (REQUIRED - never edit frontmatter manually)
-- `lean-spec update <spec> --priority <priority>` - Update priority
-- `lean-spec deps <spec>` - Show dependency graph
-- `lean-spec tokens <spec>` - Count tokens for context management
-
-**Project overview:**
-- `lean-spec board` - Kanban view with project health
-- `lean-spec stats` - Quick project metrics
+```
+BEFORE: board → search → check existing specs
+DURING: update status to in-progress → code → document decisions → link related specs
+AFTER:  update status to complete → document learnings
+```
 
-**When in doubt:** Run `lean-spec --help` or `lean-spec <command> --help` to discover commands.
+**Status tracks implementation, NOT spec writing.**
 
 ## Spec Relationships
 
-LeanSpec has two types of relationships (for detailed examples, see [docs/agents/WORKFLOWS.md](docs/agents/WORKFLOWS.md)):
-
-### `related` - Bidirectional Soft Reference
-Informational relationship between specs. Automatically shown from both sides.
-
-**Use when:** Specs cover related topics, work is coordinated but not blocking.
+| Type | Direction | Use When |
+|------|-----------|----------|
+| `related` | Bidirectional | Related topics, coordinated work |
+| `depends_on` | Directional | True blocker, work order matters |
 
-### `depends_on` - Directional Blocking Dependency
-Hard dependency - spec cannot start until dependencies complete.
+**Default to `related`**. Reserve `depends_on` for true blockers.
 
-**Use when:** Spec truly cannot start until another completes, work order matters.
-
-**Best Practice:** Use `related` by default. Reserve `depends_on` for true blocking dependencies.
-
-### ⚠️ CRITICAL: Link Dependencies When Creating/Editing Specs
-
-**After creating or editing any spec, you MUST:**
-
-1. **Scan the content** for references to other specs (e.g., "spec 045", "related to 072", "depends on", "see also", "builds on", "requires")
-2. **Link each reference** using the CLI:
-   ```bash
-   # For informational references
-   lean-spec link <spec> --related <other-spec>
-   
-   # For blocking dependencies
-   lean-spec link <spec> --depends-on <other-spec>
-   ```
-3. **Verify with:** `lean-spec deps <spec>`
-
-**Examples of content that MUST be linked:**
-- "This builds on spec 045" → `lean-spec link <this-spec> --depends-on 045`
-- "Related to spec 072" → `lean-spec link <this-spec> --related 072`
-- "See spec 110 for details" → `lean-spec link <this-spec> --related 110`
-- "Blocked by spec 086" → `lean-spec link <this-spec> --depends-on 086`
-- "## Related Specs" section listing specs → Link each one
-
-## SDD Workflow
-
-**Full workflow details:** See [docs/agents/WORKFLOWS.md](docs/agents/WORKFLOWS.md)
+## When to Use Specs
 
-1. **Discover** - Check existing specs with `lean-spec list`
-2. **Plan** - Create spec with `lean-spec create <name>` (status: `planned`)
-3. **Start Work** - Run `lean-spec update <spec> --status in-progress` before implementing
-4. **Implement** - Write code/docs, keep spec in sync as you learn
-5. **Complete** - Run `lean-spec update <spec> --status complete` after implementation done
-6. **Document** - Report progress and document changes into the spec
+| ✅ Write spec | ❌ Skip spec |
+|---------------|--------------|
+| Multi-part features | Bug fixes |
+| Breaking changes | Trivial changes |
+| Design decisions | Self-explanatory refactors |
 
-**CRITICAL - What "Work" Means:**
-- ❌ **NOT**: Creating/writing the spec document itself
-- ✅ **YES**: Implementing what the spec describes (code, docs, features, etc.)
+## Token Thresholds
 
-**Frontmatter Editing Rules:**
-- **NEVER manually edit**: `status`, `priority`, `tags`, `assignee`, `transitions`, timestamps, `depends_on`, `related`
-- **Use CLI commands**: `lean-spec update`, `lean-spec link`, `lean-spec unlink`
+| Tokens | Status |
+|--------|--------|
+| <2,000 | ✅ Optimal |
+| 2,000-3,500 | ✅ Good |
+| 3,500-5,000 | ⚠️ Consider splitting |
+| >5,000 | 🔴 Must split |
 
-**Note on Archiving**: Archive specs when they're no longer actively referenced (weeks/months after completion), not immediately. Use `lean-spec archive <spec>` to move old/stale specs to `archived/` directory.
+## First Principles (Priority Order)
 
-## Quality Standards
+1. **Context Economy** - <2,000 tokens optimal, >3,500 needs splitting
+2. **Signal-to-Noise** - Every word must inform a decision
+3. **Intent Over Implementation** - Capture why, let how emerge
+4. **Bridge the Gap** - Both human and AI must understand
+5. **Progressive Disclosure** - Add complexity only when pain is felt
 
-- Code is clear and maintainable
-- Tests cover critical paths
-- Specs stay in sync with implementation
-- **Status tracking is mandatory:**
-  - Specs start as `planned` after creation
-  - Mark `in-progress` BEFORE starting implementation work
-  - Mark `complete` AFTER implementation is finished
-  - **Remember**: Status tracks implementation, not spec document completion
-  - Never leave specs with stale status
-- **Always validate before completing work:**
-  - Run `node bin/lean-spec.js validate` to check spec structure and frontmatter (use local build, not `npx`)
-  - Run `node bin/lean-spec.js validate --check-deps` to verify content/frontmatter dependency alignment
-  - Run `cd docs-site && npm run build` to ensure documentation site builds successfully
-  - Update spec status to `complete` with `lean-spec update <spec> --status complete`
-  - Fix any validation errors or build failures before marking work complete
+## Quality Validation
 
-**Note on Local Development:**
-When working on the LeanSpec codebase itself, always use the local build (`node bin/lean-spec.js <command>`) instead of `npx lean-spec`, which runs the published npm package. Build changes with `pnpm build` before testing.
+Before completing work:
+```bash
+node bin/lean-spec.js validate              # Check structure
+node bin/lean-spec.js validate --check-deps # Verify dependencies
+cd docs-site && npm run build               # Test docs build
+```
 
 ## Publishing Releases
 
-⚠️ **CRITICAL**: When publishing a release, you MUST create a GitHub release. This is not optional.
-
-See [docs/agents/PUBLISHING.md](docs/agents/PUBLISHING.md) for the complete release process.
+See [docs/agents/PUBLISHING.md](docs/agents/PUBLISHING.md).
 
-**Quick reminder of mandatory steps:**
+**Mandatory steps:**
 1. Update versions & CHANGELOG
-2. Run pre-release checks (`pnpm pre-release`)
-3. Commit, tag, and push
-4. Prepare packages (`pnpm prepare-publish`)
+2. `pnpm pre-release`
+3. Commit, tag, push
+4. `pnpm prepare-publish`
 5. Publish to npm (all packages)
-6. Restore packages (`pnpm restore-packages`)
-7. **CREATE GITHUB RELEASE** (`gh release create vX.Y.Z --title "..." --notes-file ...`) ← DO NOT SKIP THIS
-8. Verify everything is published correctly
+6. `pnpm restore-packages`
+7. **CREATE GITHUB RELEASE** ← DO NOT SKIP
+8. Verify
 
-## Spec Complexity Guidelines
-
-**Token Thresholds:**
-- **<2,000 tokens**: ✅ Optimal
-- **2,000-3,500 tokens**: ✅ Good
-- **3,500-5,000 tokens**: ⚠️ Warning - Consider splitting
-- **>5,000 tokens**: 🔴 Should split
-
-**Check with:** `lean-spec tokens <spec>`
-
-**When to split:** >3,500 tokens, multiple concerns, takes >10 min to read
-
-**How to split:** Use `lean-spec analyze <spec>`, `lean-spec split`, and `lean-spec compact` commands. See [docs/agents/WORKFLOWS.md](docs/agents/WORKFLOWS.md) for detailed examples.
-
-## Parallel Development
-
-Need to work on multiple specs at once? Use Git worktrees for complete code isolation:
+## Advanced: Parallel Development
 
+Use Git worktrees for multiple specs:
 ```bash
-# Create worktree for spec 045
-lean-spec update 045 --status in-progress
-git worktree add .worktrees/spec-045-dashboard -b feature/045-dashboard
-cd .worktrees/spec-045-dashboard
-# Implement spec 045...
-
-# Meanwhile, start spec 047 in a separate worktree
-cd ~/project  # Back to main
-lean-spec update 047 --status in-progress
-git worktree add .worktrees/spec-047-timestamps -b feature/047-timestamps
+git worktree add .worktrees/spec-045-feature -b feature/045-feature
 ```
 
-**Best Practices:**
-- **Naming**: Use `spec-<number>-<short-name>` for worktrees
-- **Branches**: Feature branch per spec (`feature/045-dashboard`)
-- **Cleanup**: `git worktree remove <path>` after merge
-- **Status**: Update spec status from main worktree
-- **Ignore**: Add `.worktrees/` to `.gitignore`
-
-**Full guide:** See [docs/agents/WORKFLOWS.md](docs/agents/WORKFLOWS.md) for complete patterns.
-
-## FAQ
-
-**Q: How do I work on multiple specs at once?**
-
-Use Git worktrees. Each worktree gives you an isolated working directory with its own branch while sharing the same Git history. See [Parallel Development](#parallel-development) above and [docs/agents/WORKFLOWS.md](docs/agents/WORKFLOWS.md) for detailed patterns.
+See [docs/agents/WORKFLOWS.md](docs/agents/WORKFLOWS.md) for patterns.
 
 ---
 
-**Remember**: LeanSpec is a mindset, not a rulebook. When in doubt, apply the first principles in order: Context Economy → Signal-to-Noise → Intent Over Implementation → Bridge the Gap → Progressive Disclosure. Use `lean-spec --help` to discover features as needed.
+**Remember**: Context Economy → Signal-to-Noise → Intent → Bridge Gap → Progressive Disclosure

CHANGELOG.md

@@ -7,6 +7,44 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- **MCP-first agent experience** (spec 121) - Enhanced AI agent workflow with better SDD compliance
+  - Multi-tool symlink support: `lean-spec init` now creates tool-specific symlinks (CLAUDE.md, GEMINI.md → AGENTS.md)
+  - New `--agent-tools` flag for non-interactive mode (`--agent-tools all`, `--agent-tools claude,gemini`, `--agent-tools none`)
+  - MCP-first AGENTS.md rewrite emphasizing MCP tools as primary method over CLI
+  - New MCP prompt: `checkpoint` - Periodic SDD compliance reminder for long sessions
+  - New MCP prompt: `create-spec` - Guided spec creation workflow with dependency linking
+  - Stale spec warnings in board output
+  - SDD Workflow Checkpoints section in AGENTS.md
+- **Dependency alignment validation** (spec 122) - Automated detection of content/frontmatter misalignment
+  - New `--check-deps` flag for `lean-spec validate` command
+  - `DependencyAlignmentValidator` scans spec content for references to other specs
+  - Detects patterns like "spec 045", "depends on", "related to", "builds on", etc.
+  - Outputs actionable fix commands (e.g., `lean-spec link <spec> --related 045`)
+  - MCP `validate` tool now supports `checkDeps` option
+  - Added Core Rule #8 in AGENTS.md: "ALWAYS link spec dependencies"
+- **Native diagram rendering in Web UI** (spec 119) - Mermaid diagram support in spec detail view
+  - Client-side Mermaid rendering for flowcharts, sequence diagrams, class diagrams, etc.
+  - Dark mode theme support with automatic theme switching
+  - Error handling with fallback to code block display
+  - Lazy loading for optimal bundle size (only loads when diagrams present)
+- **Parallel spec implementation workflow** (spec 118) - Documentation for concurrent spec development
+  - Git worktrees pattern for working on multiple specs simultaneously
+  - Patterns for solo developers, teams, and experimental work
+  - Best practices for worktree naming, branch strategy, and cleanup
+  - Added to AGENTS.md FAQ section
+
+### Changed
+- **AGENTS.md restructured for MCP-first approach**
+  - MCP tools listed before CLI commands
+  - Added "How to Manage Specs" section with MCP vs CLI comparison table
+  - Added "SDD Workflow Checkpoints" with before/during/after task reminders
+  - Added "Common Mistakes to Avoid" section with clear ❌/✅ examples
+- **Quality Standards updated** - Added `--check-deps` validation to required checks before completing work
+
+### Fixed
+- All existing specs now have aligned dependencies (19+ specs fixed after running `validate --check-deps`)
+
 ## [0.2.6] - 2025-11-25
 
 ### Added