Specforge

specforge

specforge is a local tool for spec-driven development. It keeps a specs/ tree in a workspace: every feature gets a numbered directory holding its spec, constitution, plan, task list, research notes, clarifications and contracts, and specforge creates and maintains those files. It can also create a git branch and run format, lint, test and security-audit checks. One binary serves a command-line interface and a stdio MCP server; nothing here talks to a network service.

The workspace root is taken from the SPECFORGE_ROOT environment variable, defaulting to the current working directory. The "current feature" that most tools operate on is the highest-numbered directory under specs/; tools that need one fail with an error when no feature exists yet.

Install

npx @reneturcios/specforge specify_start --project-name "My Feature"

Or run the container image:

docker run -i ghcr.io/cloudcorprecords/specforge

The container defaults to the MCP server (see below). Pass CLI arguments to use it as a CLI instead.

CLI

The subcommands mirror the MCP tool names:

export SPECFORGE_ROOT=/path/to/workspace

specforge specify_start --project-name "Widget API" --agent claude specforge specify_describe --description "As a user I can create widgets." specforge constitution_create --principles "Ship small,Test first" --constraints "Node 20" specforge clarify_add --question "Which database?" --context storage specforge clarify_resolve --clarification-id CLARIFY-001 --resolution Postgres specforge spec_validate specforge research_append --content "Evaluated two libraries; picked the smaller one." specforge plan_create --constraints-text "Must ship by Friday." specforge spec_refine --section Requirements --changes "- Must be fast" specforge artifacts_analyze --artifacts spec,plan,tasks,contracts specforge tasks_generate --scope backend specforge tasks_tick --task-id T-001 specforge tasks_tick_range --task-ids T-002,T-003 specforge tasks_filter --preset actionable --limit 5 specforge tasks_search --query widget --fuzzy true specforge tasks_visualize --format mermaid specforge tasks_stats --include-charts true specforge git_create_branch --branch-name feature/widgets specforge quality_format specforge quality_lint --fix true specforge quality_test --coverage true specforge quality_security_audit

specforge --version

Results print as JSON. Exit codes: 0 on success, 1 when a tool fails (for example there is no current feature, or the underlying git/quality command exits non-zero), 2 for usage errors.

MCP server

One bin serves both faces. The mcp subcommand starts a stdio MCP server:

npx -y @reneturcios/specforge mcp

MCP client configuration:

{

"mcpServers": { "specforge": { "command": "npx", "args": ["-y", "@reneturcios/specforge", "mcp"], "env": { "SPECFORGE_ROOT": "/path/to/workspace" } } } }

Tools

The git and quality tools report an error result when the underlying command is unavailable or exits non-zero; they never report success for a command that did not run cleanly.

Note: the original project's prose also mentions clarify_list and artifacts_read, but they do not appear in its documented tools table, so they are not part of this rebuild.

Development

npm install

npm run build # tsc -> dist/ npm test # node test runner over test/*.test.ts, temp dirs and a fake executor, no network npm run dev # run the CLI from source via tsx

License

MIT — see LICENSE.