GTPlanner turns a task description into an agent SOP, split across design, prefab, and starter-kit documents

The output is three documents, not one PRD file

The argument behind the tool is given in three steps, and it starts with a definition rather than a feature.

First, define the task: the inputs, the specific steps, the outputs, and how success is defined. These are typically called SOPs, and the claim attached to them is blunt: work that can be SOPed can be automated by AI.

Second, give the agent the tools a human would use, since people work with office suites, a browser, and files.

Third, specify how the agent should organise its outputs.

Translated into what a code agent reads before starting, those three steps become three files. `design.md` defines what the work is. `prefab.md` defines the available tools and how to use them, and those tools are called Prefabs. A starter-kit defines the development frameworks and available environments, with the note that this part is largely the same across projects.

So the deliverable is documentation aimed at an agent rather than at a stakeholder, and the file split is chosen by what an agent needs to read at a particular moment.

Determinism, composability, and freedom are the three claims

Three principles are stated, and each one excludes a common design choice.

Determinism is the goal of eliminating AI ambiguity through clear SOPs, with the stated result being controllable and predictable execution paths and results. That is a claim about variance rather than about capability: the tool is not promising better plans, it is promising the same plan twice.

Composability means breaking SOPs into reusable Prefabs and task modules and combining them the way you would combine building blocks. This is what makes a second workflow cheaper than the first, provided the pieces are genuinely reusable.

Freedom is the interesting one because it is a refusal. The project says it does not lock you into execution platforms such as n8n, and instead uses minimal AI frameworks and native Python code for flexibility.

That refusal has a visible consequence in the packaging. The workflow engine is PocketFlow, pinned to a specific version, and the runtime is described as native Python rather than as a hosted orchestrator, so the generated SOP stays executable in a process you control rather than inside someone else's canvas.

The Claude Code skill exposes four tools in a fixed order

As a Claude Code plugin skill, GTPlanner installs into the plugins directory, copies its environment template, and is initialised from inside Claude Code with a slash command.

cd ~/.claude/plugins
git clone https://github.com/OpenSQZ/GTPlanner.git

It is then initialised by running `/gtplanner-init` in Claude Code, and afterwards you invoke it by mentioning a trigger word. The triggers are `PRD`, `项目规划`, `架构设计`, `技术方案`, and `设计文档`, which is a bilingual set covering both an English acronym and four Chinese phrases.

Four tools are exposed. `short_planning` does requirement analysis and scope definition. `tool_recommend` gives technology stack recommendations. `research` does deep technical research and requires a Jina API key. `design` generates design documents in quick or deep mode.

The order they are meant to be used in is fixed:

short_planning (initial) → tool_recommend → short_planning (technical) → design

Note that planning runs twice, once at the requirement stage and once at the technical stage. The design step is last and has a mode switch, which is the difference between a first draft and a considered one.

Three entry points share one Python entry script

Beyond the web interface there are three ways to run it locally, and they are documented separately rather than as modes of one command.

The interactive CLI is `python gtplanner.py`, which starts a session and takes your requirement as input. The same script takes the requirement as an argument for direct execution, so a one-shot generation is a single command with a quoted string.

The API is a FastAPI service started with `uv run fastapi_main.py`, and it runs on `http://0.0.0.0:11211` by default, with interactive documentation at the `/docs` path. The container image exposes the same port and health checks the same one.

The MCP server is a separate small project in its own directory, installed with `uv sync` and run with `uv run python mcp_service.py`, so an agent can call GTPlanner as a tool rather than a person invoking it.

Two separate model configurations are worth noting: the interactive and API paths read the same `.env`, while the MCP service is installed from its own lockfile in the `mcp` directory, so the two can drift apart if you upgrade only one.

There is also a hosted option, with the web UI at `the-agent-builder.com`, described as a live demo and an online quick experience requiring no installation.

The default package index is a Tsinghua mirror

The packaging configuration sets a package index, and it is not the default public one.

[[tool.uv.index]]
url = "https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple"
default = true

That makes the Tsinghua University PyPI mirror the default index for `uv sync`, which is a deliberate choice for an audience in China and a poor default for everyone else: installs will be slower outside that region, and anyone behind a network policy that blocks or distrusts that host will hit an unrelated failure while installing dependencies.

The fix is a project level configuration change rather than a code change, and it is worth making before you diagnose anything else about the install.

The same reasoning applies to the rest of the configuration. The project ships both a `.env.example` and a `settings.toml` at the top level, and the documentation lists several configuration methods, so the precedence between file, environment, and defaults is something to check before assuming a value was ignored.

For a tool aimed at an international audience, the mirror is the single most likely thing to surprise a new user, and the documentation does not call it out as a regional default.

Four dependencies are pinned to exact versions while the rest float

The dependency list mixes styles, and the pattern is informative.

Four packages use exact pins with `==`: PocketFlow at 0.0.3, its AG-UI component at 0.1.0, FastAPI at 0.115.9, and uvicorn at 0.23.1. The uvicorn entry appears twice, once plain and once with the standard extras, both at the same version.

Everything else uses a lower bound or a caret: `openai>=1.0.0`, `pyyaml>=6.0`, `aiohttp`, `json-repair`, `python-dotenv`, `dynaconf>=3.1.12`, `rich>=13.0.0`, and `pydantic>=2.5.0`. Dev dependencies are pytest and pytest-asyncio.

The exact pins are on the two things the tool's own claims depend on. PocketFlow is the workflow engine, and pinning a 0.0.3 release says the agent graph format is not yet stable enough to move. Pinning FastAPI and uvicorn together suggests the request and response shapes the web UI depends on are held fixed.

One more detail: the setuptools package discovery includes `agent*` and `utils*` while excluding `mcp*`, `static*`, and `assets*`, so the MCP server is not part of the published distribution even though it lives in the same repository.

Prefab search needs a vector service whose index is built by CI

Prefabs are the reusable tool definitions, and searching them runs against a separate vector service rather than against files in the repository.

The configuration block lists `VECTOR_SERVICE_BASE_URL` and a timeout, marked as required for prefab search, plus the index name, whose default is `document_gtplanner_prefabs`, and the field used for the search, `combined_text`, described as holding the summary, the description, and the examples together.

The comments in the environment template add two operational facts. The index is built by the CI/CD pipeline, and at runtime it is read-only. So a local checkout has no prefab index at all until the service is available and populated, which means prefab search degrades in a way that looks like an empty result set rather than an error.

The other optional key follows the same pattern. The Jina API key is documented as not required, with the note that without it the search tool is not enabled, so the `research` capability disappears entirely rather than degrading.

Tracing is configured in the same file, with Langfuse keys marked as required for tracing, and a block of PocketFlow tracing booleans that decide whether inputs, outputs, preparation, execution, post-processing, and errors are recorded, plus an optional session id and user id.

The metadata version is 0.7.0 while the newest release tag is v0.3.4

The version numbers in this repository live in three places and they do not agree.

The project metadata declares version 0.7.0. The newest release in the history is v0.3.4, with v0.3.0 and v0.2.0 behind it. The repository description calls it an AI-powered PRD generation tool, and the metadata description calls it a PRD generation tool for Vibe Coding.

So installing from the repository and installing the newest release give you different code, and the higher number is on the branch, not on a tag.

The Python floor disagrees as well. The documentation lists Python 3.10 or newer with 3.11 or newer recommended, while the metadata declares `requires-python` as 3.11 or newer, so an installation on 3.10 satisfies the documentation and fails the metadata check.

The container settles it in practice: the Dockerfile is built on `python:3.11-slim`, installs uv with pip, installs dependencies from the lockfile into the system environment, exposes 11211, and starts the FastAPI entry point with a health check that requests the health endpoint every 30 seconds.

If you are pinning anything, pin the container image rather than the branch.

Editorial conclusion

GTPlanner fits someone preparing to hand work to Claude Code, Cursor, or a similar coding agent and wants the task written down before the first prompt, since the three-document output maps directly onto what those tools read. It does not fit a team that wants one PRD file for human review. Before installing, note two things that will otherwise surprise you: the package metadata points uv at a Tsinghua package mirror by default, and the declared Python floor in the metadata is 3.11 while the documentation says 3.10 or newer.

Frequently asked questions

Official sources

1. License: MIT
2. OpenSQZ/GTPlanner on GitHub
3. Project website
4. README
5. Releases