architect-mcp

architect-mcp keeps coding agents honest. It is a local-first agent work gate that clarifies intent before edits, constrains the plan, reviews implementation drift, and requires verification evidence before completion.

The MCP tools return structured reviews and blockers; they do not sandbox a model, shell, or filesystem by themselves. Use the TUI, host approvals, CI, and human review when you need an enforced workflow boundary.

Full docs: tonycdr-prog.github.io/architect-mcp

Launch Snapshot

| Surface | What It Gates | | --- | --- | | Core work gate | grill_me, pre-edit contracts, plan review, drift review, final/session honesty checks | | Advanced maturity | Stack packs, standards intelligence, governance evals, operating-model evals | | Rust TUI | Ratatui client for live work-gate checks, adapter readiness, guarded headless JSONL, approval/promotion commands, arena ranking, repo-foundry staging, and provisional ACP | | Hosted mode | Stateless /mcp, explicit file summaries, no local workspace scanning | | Release gate | npm run release:check |

Quick Start

The npm registry name architect-mcp is owned by a different package, so this project publishes as @tonycdr-prog/architect-mcp while keeping the architect-mcp command name.

npm install -g @tonycdr-prog/architect-mcp
architect-mcp

For a source checkout:

npm install
npm run build
node dist/index.js

For local MCP clients:

{
  "mcpServers": {
    "architect-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "--package",
        "@tonycdr-prog/architect-mcp@latest",
        "architect-mcp"
      ]
    }
  }
}

Core Flow

1. Run grill_me until blockers are gone.
2. Create a pre-edit contract with create_pre_edit_contract.
3. Review the build plan with review_build_plan.
4. Review proposed files with review_proposed_file_plan.
5. Review implementation with review_repo_structure and review_implementation_against_contract.
6. Review final output with review_agent_final_response or review_agent_session.

The default MCP surface exposes exactly these eight work-gate tools:

• grill_me
• create_pre_edit_contract
• review_build_plan
• review_proposed_file_plan
• review_repo_structure
• review_implementation_against_contract
• review_agent_final_response
• review_agent_session

Use the advanced surface for stack packs, standards intelligence, governance evals, operating-model evals, productization boundary evals, repo-quality gates, and local workspace utilities:

ARCHITECT_MCP_TOOL_SURFACE=advanced architect-mcp

Historical V3-V10 labels remain in tool names, scripts, tests, and document filenames for compatibility. Public documentation frames them as advanced maturity criteria rather than public product versions.

Rust TUI

The package also exposes architect-mcp-tui, a Ratatui client for local work-gate sessions, adapter readiness, safe headless automation, approval/promotion commands, arena ranking, private-by-default repo-foundry staging/smoke checks, read-only governance audits, and provisional ACP:

architect-mcp-tui
architect-mcp-tui smoke --json
architect-mcp-tui governance-audit --json
architect-mcp-tui foundry-smoke --owner <github-owner> --json
architect-mcp-tui run --prompt "Build an offline recipe planner" --adapter codex --jsonl
architect-mcp-tui run --prompt "Build an offline recipe planner" --adapter codex --jsonl --execute
architect-mcp-tui acp --stdio

See Rust TUI for config, adapters, release binaries, and workflow details. Use Terminal QA for real Windows and Linux smoke checks.

Docs

• Getting Started
• MCP Client Setup
• Core Work Gate
• New App Work Gate
• Prompt Injection And Gate Bypass Threat Model
• AI Software Foundry Goal
• Tool Reference
• Hosted Mode
• MCP Integrations
• Rust TUI
• Terminal QA
• Governance Audit
• Stack Packs
• Release Readiness
• Read-Only Smoke Matrix
• Compatibility And Advanced Maturity Criteria

Release Readiness

Use the clean-checkout release gate before release-sensitive changes:

npm run release:check

This gate runs the Rust TUI checks and then the existing advanced maturity release check.

Local docs build:

npm run docs:build

After merge, repository Pages settings should use "GitHub Actions" as the Pages source.

Star History

Security

Security reports should follow SECURITY.md. Do not put vulnerabilities, secrets, exploit details, or private repository data in public issues.