forge-think

English | 中文

Structured multi-step orchestration for MCP agents: adversarial lenses, reusable SOP workflows, and persistent traces.

Force complex tasks through a rigorous, multi-step refinement process instead of letting a single, one-shot LLM response decide the outcome. forge-think provides three primary orchestration modes for MCP agents: Open Exploration, Business SOPs, and Roundtable Review.

Why forge-think?

Strong models don't lack the ability to "think one step further". What they lack when facing complex problems is the correct reasoning path, adversarial reviews from different standpoints, and the ability to persist proven decision trees for reuse. When relying on single-shot prompts, a model's entire reasoning process naturally regresses to the mean, generating generic paradigms.

forge-think acts as a lightweight, external orchestration layer to fix this:

• Open Exploration (seq): When the root cause is unknown, step-by-step debugging allows the agent to gather evidence and pivot its hypotheses on the fly.
• Business SOPs (chain): Encode your team's verified decision trees into Standard Operating Procedures. Prevent the LLM from falling back on generic paradigms by forcing it to respect specific architectural constraints.
• Roundtable Review (deliberate): Apply adversarial lenses (e.g., Security, Performance, Minimalist) to successively critique and rewrite the proposed solution until it reaches a solid consensus.
• Persistent Traces: Every step leaves a trace. You can resume the process even if the connection drops or the server restarts.

Note: The forge-think server strictly follows the MCP pattern and does not use external LLM APIs; it solely manages orchestration, state, and persistence.

Getting Started

git clone https://github.com/halflifezyf2680/forge-think.git
cd forge-think
pip install -r requirements.txt

Requires Python 3.10+. Configure the local stdio server in your MCP host. Example configurations are in examples/:

• Claude Desktop: claude_desktop_config.json
• OpenCode: opencode_config.json

Once configured, simply prompt your host: "Use forge-think" or "Start forge-think". For complex tasks, ask the host to call forge_help first to get the operational manual.

Out-of-the-Box SOPs

On first launch, forge-think installs three editable default SOPs in ~/.forge-mcp/sops/.

| SOP | Scenario | Hardcoded Reasoning Path | |---|---|---| | evidence-first-triage | Incidents, exceptions | Establish a factual baseline first, form falsifiable hypotheses, then choose the lowest-risk action. | | decision-under-constraints | Architecture, tech trade-offs | Explicitly list constraints, attack the candidate solution, and converge to a decision. | | agent-first-application-design | LLM app design | Full methodology from input contracts to eval loops. |

Core Philosophy: Forced Multi-Step Iteration

Why use an MCP server requiring configuration when you could just write a long Prompt or a static "Skill"?

The core reason is engineering the control of reasoning depth.

In practice, feeding an LLM a massive prompt and expecting a single-shot perfect output yields vastly different (and often shallower) results compared to forcing an interruption in its output flow, compelling it to iterate in multiple turns.

1. "Static Suggestions" vs. "Forced State Machine": A static Skill or long prompt is merely a "suggestion" to the LLM. When faced with complex tasks, models naturally take shortcuts, skipping detailed intermediate analysis to jump to a final conclusion. forge-think is a forced state machine. The model must interact with tools like forge_step to be authorized for the next step, physically cutting off the "jump to conclusion" shortcut.
2. Shattering the "Pseudo-Reflection" Illusion: If you ask a model in a single prompt to "Provide a solution, then objectively critique it," the model is just playing an auto-regressive text continuation game. Its "critique" is heavily influenced by the preceding instructions and has nothing to do with genuinely reviewing a completed output. It often devolves into superficial fluff. By forcing an interruption (like in deliberate mode), forge-think ensures the previous output is generated and "committed" to the context. Only then can the next reviewing persona physically "see" that text as context, producing a profound and genuine evaluation.
3. Depth through Concentrated Attention: Breaking a large task into a forced multi-turn interaction ensures the model's Attention mechanism is highly concentrated at each step, rather than being diluted across dozens of concurrent rules. This is the engineering method to raise the ceiling of a model's reasoning capabilities.
4. State Persistence & Preventing Context Bloat: Keeping a massive SOP on the server and dispatching it step-by-step prevents unnecessary pollution of the Context Window. Furthermore, persisting every step allows for resuming interrupted tasks and precise post-mortem analysis.

How is this different from sequentialthinking?

Tools like the official sequentialthinking MCP simply allow the model to break down its own thoughts step-by-step. However, if the model lacks your specific business context, thinking longer just produces "logically rigorous generic nonsense."

forge-think doesn't just ask the model to think more; it forces the model onto the rails of your actual business logic by injecting strict external constraints (adversarial personas and team-verified SOPs).

(For full documentation on Lenses, Rules vs SOPs, and Dev instructions, please refer to the Chinese documentation README_zh-CN.md)

License

MIT