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 claudespecforge 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 storagespecforge clarify_resolve --clarification-id CLARIFY-001 --resolution Postgresspecforge spec_validatespecforge 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,contractsspecforge tasks_generate --scope backendspecforge tasks_tick --task-id T-001specforge tasks_tick_range --task-ids T-002,T-003specforge tasks_filter --preset actionable --limit 5specforge tasks_search --query widget --fuzzy truespecforge tasks_visualize --format mermaidspecforge tasks_stats --include-charts truespecforge git_create_branch --branch-name feature/widgetsspecforge quality_formatspecforge quality_lint --fix truespecforge quality_test --coverage truespecforge 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 installnpm run build   # tsc -> dist/npm test        # node test runner over test/*.test.ts, temp dirs and a fake executor, no networknpm run dev     # run the CLI from source via tsx

License

MIT — see LICENSE.