specforge

specforge

specforge は、仕様駆動開発のためのローカルツールです。ワークスペース内に specs/ ツリーを保持します。各機能には、仕様書、憲章、計画、タスクリスト、 調査メモ、明確化事項、コントラクトを格納する番号付きディレクトリが割り当てられ、 specforge がこれらのファイルを作成・管理します。Git ブランチを作成し、フォーマット、Lint、テスト、セキュリティ監査のチェックを実行することもできます。 1 つのバイナリでコマンドラインインターフェースと stdio MCP サーバーを提供します。このツールがネットワークサービスと通信することはありません。

ワークスペースのルートは SPECFORGE_ROOT 環境変数で指定し、設定されていない場合は現在の作業ディレクトリが使用されます。ほとんどのツールが操作する「現在の機能」は、 specs/ 配下にあるディレクトリのうち番号が最も大きいものです。現在の機能を必要とするツールは、 機能がまだ存在しない場合、エラーになります。

インストール

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

または、コンテナイメージを実行します。

docker run -i ghcr.io/cloudcorprecords/specforge

コンテナはデフォルトで MCP サーバーを起動します（下記参照）。CLI として使用するには、CLI の引数を渡します。

CLI

サブコマンド名は MCP ツール名と同じです。

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

結果は JSON として出力されます。終了コード：成功時は 0、ツールが失敗した場合（たとえば、現在の機能が存在しない場合や、基盤となる git／品質チェックコマンドが 0 以外で終了した場合）は 1、使用方法に誤りがある場合は 2 です。

MCP サーバー

1 つのバイナリで両方のインターフェースを提供します。mcp サブコマンドを実行すると、stdio MCP サーバーが起動します。

npx -y @reneturcios/specforge mcp

MCP クライアントの設定：

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

ツール

ツール	入力	機能
specify_start	projectName（必須）、agent	仕様テンプレート、contracts/、research.md を含む、次の番号付き機能ディレクトリを作成します。
specify_describe	description（必須）	説明を現在の機能の仕様にあるユーザーストーリーのセクションに記述します。
constitution_create	principles（必須）、constraints、preferences	現在の機能の constitution.md を記述します。
clarify_add	question（必須）、context	確認事項（CLARIFY-NNN、解決内容は null）を clarifications.json に追加します。
clarify_resolve	clarificationId、resolution（両方必須）	確認事項の解決内容を設定します。
spec_validate	checks（任意のオブジェクト）	仕様の有無と完全性を確認し、各チェックの結果を返します。
research_append	content（必須）	research.md に追記します。
plan_create	constraintsText（必須）	制約に基づいて plan.md を作成します。
spec_refine	section、changes（両方必須）	spec.md の指定セクションを置き換えるか、追加します。
artifacts_analyze	artifacts（必須の配列）	指定した成果物の有無とサイズを報告します。
tasks_generate	scope（任意）	仕様から生成した番号付きチェックボックスリストである tasks.md を作成します。
tasks_tick	taskId（必須）	タスク T-NNN を完了としてマークします。
tasks_tick_range	taskIds（必須の配列）	複数のタスクを完了としてマークします。不足している ID は報告されます。
tasks_filter	preset、limit（任意）	タスクを一覧表示します。デフォルトのプリセットでは、実行可能（未チェック）のタスクが表示されます。
tasks_search	query（必須）、fuzzy	タスクのテキストを検索します。あいまい検索では、部分列による一致も受け付けます。
tasks_visualize	format（任意）	タスクリストを text（デフォルト）または mermaid 形式で描画します。
tasks_stats	groupBy、includeCharts（任意）	完了および保留中のタスクを集計し、オプションでテキストチャートを表示します。
git_create_branch	branchName（必須）	ワークスペースで git checkout -b <branchName> を実行します。
quality_format	fix（任意）	Prettier のチェックを実行するか、fix を指定して --write を実行します。
quality_lint	fix（任意）	ESLint を実行するか、--fix を指定して実行します。
quality_test	coverage（任意）	npm test を実行します。オプションでカバレッジも確認できます。
quality_security_audit	fix（任意）	npm audit を実行するか、fix を指定して npm audit fix を実行します。

git ツールと quality ツールは、基盤となるコマンドが利用できない場合、またはゼロ以外の終了コードで終了した場合にエラー結果を報告します。正常に実行されなかったコマンドを成功として報告することはありません。

注：元のプロジェクトの説明文には clarify_list と artifacts_read も記載されていますが、ドキュメント化されたツールの表には載っていないため、この再構築には含まれません。

開発

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

ライセンス

MIT — LICENSE を参照してください。