Skip to content

IDE_INTEGRATION.md

Latest commit

 

History

History
85 lines (62 loc) · 3.6 KB

IDE_INTEGRATION.md

File metadata and controls

85 lines (62 loc) · 3.6 KB

IDE Integration

Three integration paths cover every modern dev environment:

1. VS Code extension (most direct)

Adds a status bar showing live certify score + wire violation count, two activity-bar tree views (violations + certify axes), and 10 commands mapped to forge CLI verbs. Click any violation to jump to the file.

cd vscode-extension
npm install && npm run compile && npm run package
code --install-extension atomadic-forge-0.18.0.vsix

See vscode-extension/README.md for settings + usage.

2. MCP server (works with any MCP-aware assistant)

Forge ships a fully-typed MCP server whose current counts are recorded in ../forge_metrics.json and whose canonical tool map lives in ../surface.json. Any of these clients can attach:

  • Claude Code (Anthropic CLI) — claude mcp add atomadic-forge -- forge mcp serve --project ${workspaceFolder}
  • Cursor — Settings → MCP Servers → add the same command above
  • Cowork (Anthropic) — same pattern; the assistant gets the full toolkit
  • Windsurf — Add Server → command forge, args ["mcp", "serve"]
  • Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json: 
    {
  "mcpServers": {
    "atomadic-forge": {
      "command": "forge",
      "args": ["mcp", "serve"]
    }
  }
}

Once connected, every recon / wire / certify call your assistant makes goes through Forge's typed dispatch and the lazy a3-bootstrap fix in v0.17.0+ ensures handlers register on the first call (no manual setup).

3. Claude Code skills bundle (workflow templates)

The skills/ directory ships four ready-to-use skill bundles:

Skill Trigger What it does
forge-onboard "onboard me to this repo" runs welcome + context_pack + explain_repo
forge-fix "fix the wire violations" wire --suggest-repairs → enforce --apply → verify loop
forge-guardian "review my changes" preflight_change + wire + score_patch + select_tests
forge-optimize "improve the score" certify → auto_plan → cherry-picked enforce + materialize

Install:

forge mcp serve &     # background MCP attach (or add to assistant config)
# In your Claude Code session, the skills are auto-discovered from skills/.

Recommended VS Code settings

skills/vscode-settings-recommended.json is auto-applied if you install the extension. Highlights:

  • python.analysis.extraPaths: ["src"] — picks up the src/ layout Forge scaffolds
  • python.testing.pytestEnabled: true with pytestArgs: ["tests"]
  • editor.rulers: [100] — Forge generates code at 100 chars
  • git.preCommitHook: true — wires pre-commit if you've copied hooks/pre-commit

Hooks

Three git hooks ship in hooks/:

  • post-clone — runs forge welcome after a fresh clone so new contributors see the architecture immediately.
  • pre-commit — blocks commits that introduce wire violations OR drop the certify score below the configured floor.
  • pre-push — runs full forge wire + forge verify before any push.

Install:

cp hooks/pre-commit hooks/pre-push .git/hooks/
chmod +x .git/hooks/pre-commit .git/hooks/pre-push

All three were updated in v0.18.0 to use the current CLI argument shape (positional path args, kebab-case flags) — earlier versions had a flag mismatch that caused the hooks to silently no-op.

Agent instructions

The full tool catalog with use-case guidance lives in skills/FORGE-AGENT-INSTRUCTIONS.md. Point any AI assistant at it (or include it as a system prompt) for tier-aware behaviour out of the gate.