Use architect-mcp On A Repo

The default MCP surface is the agent work gate: grill_me, create_pre_edit_contract, review_build_plan, review_proposed_file_plan, review_repo_structure, review_implementation_against_contract, review_agent_final_response, and review_agent_session. Set ARCHITECT_MCP_TOOL_SURFACE=advanced when you need stack-pack authoring, governance, repo-quality, productization boundary, eval, repo constitution, workspace review, or MCP config review tools. Local-only tools still require an environment that enables trusted workspace access.

Local Flow

1. Run grill_me with the project brief until blockers are gone.
2. Generate a contract with generate_architecture_contract.
3. Generate repo artifacts with generate_repo_artifacts.
4. Derive repo expectations with derive_local_repo_constitution, or use derive_repo_constitution when the client supplies file summaries, artifacts, and recent merged PR bodies.
5. Scan the workspace with review_local_workspace or provide file summaries to review_repo_structure.
6. Normalize review findings, external tool findings, verification summaries, coverage, and repo constitution output with normalize_foundry_evidence before scoring or routing.
7. Score normalized evidence with score_foundry_actionability before generating PR previews, issue previews, exceptions, or human questions.
8. Route scored decisions with route_foundry_decisions so each finding has an explicit public-safe ledger route before any PR, issue, exception, no-op, or human-question workflow.
9. Forge preview-only PR, issue, exception, no-op, or human-question artifacts with forge_foundry_previews; treat the output as a draft artifact, not mutation permission.
10. Run scan_mcp_config_files to check .mcp.json, Cursor, Claude Desktop, and Codex MCP configs.
11. Use review_build_plan before implementation slices.
12. Use review_agent_session before final output when a client has intent, contract, changed files, verification, memory, and response data.
13. Use review_agent_final_response before sending a final reply.

Hosted-Safe Flow

1. Do not use local file paths.
2. Send explicit file summaries to review_repo_structure.
3. Send repo constitution artifacts and recent merged PR summaries to derive_repo_constitution.
4. Send supplied review reports, external finding summaries, verification summaries, and constitution output to normalize_foundry_evidence.
5. Send normalized evidence to score_foundry_actionability; treat the result as advisory until the decision-ledger routing step records an explicit route.
6. Send scored actionability output to route_foundry_decisions; use the emitted ledger routes as public-safe previews, not as mutation permission.
7. Send the public-safe ledger and repo constitution to forge_foundry_previews to generate maintainer-native previews without creating branches, issues, pull requests, comments, or labels.
8. Send parsed MCP config objects to review_mcp_config_security.
9. Use audit_hosted_tool_policy to confirm local-only tools are not exposed.
10. Keep memory tools stateless unless a future adapter is explicitly configured.

Repo Constitution Flow

Use repo constitution output before drafting issues, PR previews, or mutation plans. The output is public-safe by design: it reports paths, counts, headings, package metadata, workflows, release signals, findings, and source provenance, but it does not return raw artifact bodies and it does not mutate files.

PR templates are hard repository signals. Recent merged PR bodies are advisory style evidence only: they can fill gaps when templates are missing, hidden-comment-only, too sparse, or possibly stale because accepted PR headings do not overlap the template. Recent PR style does not override explicit repo instructions, security policy, or template requirements. Bot-only PR bodies are ignored by default so dependency automation does not redefine accepted contribution style for normal PRs.

Foundry Evidence Flow

Use normalize_foundry_evidence after repo constitution derivation and read-only audits, before actionability scoring or decision routing. The inventory assigns stable evidence IDs, source refs, confidence, public-safety class, redaction state, suppression candidates, merged coverage caveats, and finding histograms. It omits raw external payloads and raw repo content, redacts local paths and token-shaped values, and keeps mutation disabled.

Use score_foundry_actionability on that inventory before proposing maintainer work. The score is deterministic and advisory: it labels findings as pr_preview_candidate, ask_human, exception_candidate, or no_op_candidate and explains evidence strength, confidence, blast radius, patch-size confidence, maintainer fit, duplicate risk, release impact, verification path, public-safety risk, and expected maintainer value. The scorer does not mutate repositories and does not create issues or PRs; later routing and forge steps must still record an explicit decision.

Use route_foundry_decisions after scoring to emit the next explicit preview route for each finding: pr_preview, architect_issue, exception, no_op, or ask_human. The ledger reports public-safe, ledger-local evidence aliases, decision reasons, redaction state, verification requirements, approval state, and next action while reporting zero server writes. Direct MCP clients must treat pr_preview, architect_issue, and exception as approval-required previews only; the tool does not write files, create GitHub issues, open pull requests, or persist raw MCP payloads.

Use forge_foundry_previews after decision routing to render public-safe draft artifacts for the chosen routes. Pull request previews use repository PR-template headings as hard signals, recent accepted PR headings only as advisory fallback when templates are missing or sparse, and include verification, release-note impact, ledger-local evidence aliases, maintainer-fit rationale, and an architect-mcp footer. Architect issue previews, exception records, no-op records, and human questions remain preview-only as well. The forge reports zero server writes and never creates branches, issues, pull requests, comments, labels, or raw payload persistence.

Baseline Flow

1. Run review_repo_structure in audit mode for a first pass on an established repo.
2. Create a baseline with create_review_baseline.
3. Store accepted findings with reasons.
4. Run later reviews in ci mode so new findings fail without blocking historical debt.

Use migration mode when adopting architect-mcp in a mature repo that already has known debt and you want lower-value line-count warnings suppressed in the report. Use audit mode when you want source findings without requiring AGENTS.md or docs/architecture-contract.md to exist yet. For large repos, check report.coverage: it includes total finding histograms before detailed-output suppression, scan truncation caveats, and the top scanned directories so capped audits are not mistaken for full-repo coverage.