Consolidate agent docs and add LeanSpec MCP server configuration#22
Merged
Consolidate agent docs and add LeanSpec MCP server configuration#22
Conversation
Agents were creating/modifying specs via direct file writes, bypassing the validation rules defined in .lean-spec/config.json (400-line max, 5000-token max, required frontmatter, dependency integrity). The MCP server makes these rules structural — agents must use create/update tools which validate before writing to disk. - Add .mcp.json registering @leanspec/mcp server - Update CLAUDE.md with MCP tool reference and enforcement rule - Update AGENTS.md with spec-writes-via-MCP convention - Update Factory/Fractal skills to reference MCP tools https://claude.ai/code/session_01Y967chCVSr6E7ao8oDKJi2
Fractal's internal sub-specs (.fractal/{work-id}/tree/**/spec.md) are
ephemeral decomposition nodes — gitignored, structurally different from
project specs, discarded after each run. LeanSpec MCP enforcement only
applies to project-level specs in specs/.
https://claude.ai/code/session_01Y967chCVSr6E7ao8oDKJi2
LeanSpec is for Synodic feature development, not for the execution skills (Factory, Fractal, etc.) which are pattern-agnostic. https://claude.ai/code/session_01Y967chCVSr6E7ao8oDKJi2
Single source of truth — no more drift between the two files. https://claude.ai/code/session_01Y967chCVSr6E7ao8oDKJi2
Tested against live server output. link/unlink don't exist — it's `relationships` with action param. Added `children` tool. Updated descriptions to match actual tool schemas. https://claude.ai/code/session_01Y967chCVSr6E7ao8oDKJi2
There was a problem hiding this comment.
Pull request overview
Consolidates agent-facing documentation into CLAUDE.md and adds an MCP configuration to route specs/ creation/mutation through the LeanSpec MCP server for consistent validation.
Changes:
- Added “Spec Management via MCP” guidance to
CLAUDE.md, including tool references and an explicit “spec writes via MCP” convention. - Replaced
AGENTS.mdwith a backward-compatibility pointer toCLAUDE.md. - Added root
.mcp.jsonto register the@leanspec/mcpserver for Claude Code integration.
Reviewed changes
Copilot reviewed 3 out of 4 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| CLAUDE.md | Documents MCP-based spec management rules and updates conventions. |
| AGENTS.md | Redirect/pointer to CLAUDE.md for compatibility. |
| .mcp.json | Registers the LeanSpec MCP server via npx. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
You can also share your feedback on Copilot code review. Take the survey.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR consolidates agent documentation and establishes MCP (Model Context Protocol) integration for spec management. The changes enforce spec creation/mutation through the LeanSpec MCP server rather than direct file writes, ensuring validation rules are applied consistently.
Key Changes
AGENTS.md— Consolidated agent instructions intoCLAUDE.mdas the single source of truthAGENTS.md— Now a redirect file pointing toCLAUDE.mdfor backward compatibility.mcp.json— Registers the LeanSpec MCP server (@leanspec/mcp) for Claude Code integrationCLAUDE.md— Added comprehensive "Spec Management via MCP" section documenting:specs/.mcp.jsonat repo root, no manual setup needed)create,update) — never write spec files directly"Implementation Details
The MCP server acts as a validation gatekeeper, enforcing rules defined in
.lean-spec/config.json(400-line max, 5000-token max, required frontmatter) that cannot be bypassed with direct file writes. This ensures all project-level specs maintain structural integrity and dependency consistency.https://claude.ai/code/session_01Y967chCVSr6E7ao8oDKJi2