Workfile

リポジトリがデータベースです。

@illodev/workfile は、人間とソフトウェアエージェントの間で 作業、ドキュメント、履歴、永続的なプロジェクトメモリ を調整する、リポジトリネイティブなプロトコルです。

リポジトリ内の Markdown ファイルが正規の情報源です。CLI、HTTP API、ローカル UI は、同じコアサービス、コレクションレジストリ、インデックス、検証ルールを使用します。ブラウザーやデータベースに専用の状態を保持することはありません。

作業、ドキュメント、履歴、メモリは、共通の ProjectRecord インデックスを使用します。コア、CLI、HTTP サーバー、MCP ランタイムは TypeScript で作成され、パブリック宣言を含むコンパイル済み ESM として配布されます。ローカル UI は事前にコンパイルされてパッケージに含まれており、セマンティック検索はオプションの @illodev/workfile-search-local ワークスペースパッケージを通じてデバイス上で実行されます。

ライブデモを試す — この リポジトリ自体のワークスペースを再生します。Workfile の開発における実際のカード、リリース、インシデント、学びを確認できます。変更はブラウザーのセッションごとに適用され、再読み込みするとリセットされます。

https://github.com/user-attachments/assets/c9cd3035-6729-4cda-9172-984829ab5dbc

利用例

本番環境で使用中

Workfile — 自己利用：すべてのリリースは、このリポジトリ自身の .project/ で計画・記録されています

## 境界

Workfileは作業の記録を管理します。エージェントの設定は行いません。

どちらも同じリポジトリのそばにあるため、混同されがちです。gentle-aiは、エコシステム設定ツールの好例です。エージェントを複数まとめて、すでに使っているエージェントにペルソナ、厳選されたスキル、モデルルーティング、MCP サーバー、レビューゲートをインストールします。その問いは「エージェントをどのように動かすか」です。Workfileの問いは「何が行われ、誰が保持し、どのような証拠があるか」であり、その答えは、エージェント、セッション、このパッケージがなくなった後も残るMarkdownファイルです。

両者は連携できます。適切に設定されたエージェントにも、実行した作業を永続的に書き残す場所が必要です。

ここに含まれるものと、設定ツールの役割ではないもの：

• リポジトリが正本です。 カードはプルリクエスト内のファイルであり、差分でレビューされ、形式が不正な場合はworkfile doctorで報告されます。ブラウザー、データベース、~/.configに専用の状態を持ちません。パッケージを削除しても、記録は読み取り可能なままです。
• 主張は合意ではなく、強制されます。 所有権は変更時に確認されるため、別のアクターが保持するカードに対して操作しようとすると、黙って受け入れられるのではなくCARD_CLAIM_OWNER_MISMATCHが返されます。これは、プロンプト内のどんな文言でも保証できないことです。
• reviewはdoneではありません。 doneには、実際にコードを実行した場所からの証拠が必要です。マージは証拠ではありません。
• 人間も同じ記録を読みます。 UI、生成された変更履歴、リリースは、エージェントが書き込んだ内容だけから生成されます。同期を保つ必要のある機械向け表示と人間向け表示はありません。

意図的に含めていないもの：Workfileはエージェントをインストールまたは更新せず、ペルソナの提供、モデルのルーティング、スキルカタログの厳選も行いません。エージェントがすでに読み込む指示ファイルに、独自のプロトコルを同期し（workfile agents sync）、MCP経由ですべての操作を公開します。ベンダーに依存しませんが、エコシステムではなくサーバーです。

要件

• Node.js 22以降。
• npm、pnpm、yarn、またはBunからパッケージを実行できます。

インストール

このREADMEにあるすべてのworkfile …コマンドでは、パッケージをインストールしておく必要があります。pnpm dlx／npxでの一時実行では、コマンドを実行した後にバイナリが破棄されます：

pnpm add -D @illodev/workfile     # per repository (recommended)
pnpm workfile doctor              # dependency bins run through pnpm / npx

pnpm add -g @illodev/workfile     # or globally: `workfile` lands on your PATH
workfile doctor
wf doctor                         # `wf` is the same binary, for typing by hand

wfは別名であり、改名ではありません。どちらの名前でも同じエントリーポイントに到達し、ヘルプやエラーのヒントは入力した名前に合わせて表示されます。生成または共有するものには、正式名称を使用してください。wfが解決されるのはパッケージのインストール後のみです。また、レジストリには無関係なwfも存在するため、npx workfileがそのまま失敗する場面でnpx wfを実行すると、別のツールが取得されてしまいます。

一度だけ初期化する場合はpnpm dlx @illodev/workfile initで問題ありませんが、その後もパッケージをdevDependencyとして残してください。これにより、initがpackage.jsonに追加するproject*スクリプトを解決できます。この接頭辞はnpmスクリプトの名前空間です。pnpm projectでUIを開き、pnpm project:doctorでチェックを実行します。古いバイナリ名とは関係ありません。

TypeScript API

公開APIでは、条件付きパッケージエクスポートを通じてJavaScriptと型宣言を提供します。TypeScriptの利用者は、ルートパッケージとドキュメントに記載されたすべてのサブパスから、型付きの設定、ワークスペース、レコード、検索、統合の各コントラクトを利用できます：

import {
    defineProject,
    type CardStatus,
    type ProjectConfig,
    type ProjectRecord
} from "@illodev/workfile";
import { createSemanticSearchProvider } from "@illodev/workfile/search";

const config: ProjectConfig = defineProject({
    schemaVersion: 2,
    name: "Billing",
    cards: {
        areas: ["api", "web"]
    }
});

const status: CardStatus = "doing";

CLIとUIを利用するプロジェクトにTypeScriptは必要ありません。React、Primer、Vite、UIの型パッケージはビルド専用の依存関係です。インストールされたパッケージは、バンドル済みのブラウザーアセットをdist/uiから提供します。

ワークスペース

プロジェクトは project.config.mjs を通じて検出され、通常、プロトコルが管理する ファイルは .project/ の下に保存されます。

project.config.mjs
.project/
├── VERSION
├── cards/
│   └── archive/
├── assets/
├── docs/
├── changelog/
│   ├── unreleased/
│   └── releases/
├── memory/
│   ├── learnings/
│   ├── decisions/
│   ├── incidents/
│   ├── conventions/
│   └── context/
├── agents/
└── .cache/

最小限の設定です。defineProject(...) ではなく、プレーンなオブジェクトを使用します。ローダーが defineProject を適用します。また、ここでのインポートはベアスペシファイアであり、 node_modules が存在する場合にしかファイルから解決できません。そのため、 node_modules なしで実行される2つのコンシューマーで問題が発生します。パッケージの インストール前に pnpm dlx で初期化されたワークスペースと、クリーンなクローンで 生成された CI ジョブが実行する npx です。JSDoc アノテーションを使うことで、ランタイムで インポートせずにエディターの型情報を維持できます。

/** @type {import("@illodev/workfile").ProjectConfigInput} */
export default {
    schemaVersion: 2,
    name: "My project",
    cards: {
        areas: ["api", "web", "infra", "docs"]
    },
    docs: {
        sources: [
            "README.md",
            "docs/**/*.md",
            "apps/*/README.md",
            ".project/specs/**/*.md"
        ]
    },
    changelog: {
        releaseStrategy: "semver",
        defaultVisibility: "public"
    },
    memory: {
        collections: [
            "learnings",
            "decisions",
            "incidents",
            "conventions",
            "context"
        ]
    },
    agents: {
        targets: ["agents-md", "cursor"]
    },
    ci: {
        targets: ["github"]
    },
    mcp: {
        allowMutations: true
    },
    search: {
        semanticWeight: 0.35,
        maxProviderRecords: 500
    }
};

プロジェクト固有の領域、パス、語彙は実行時に解決され、有効なスキーマを通じて公開されます。 Work の8つのステータスと、スキーマ v2 のメモリーコレクションのセマンティクスは、 引き続きプロトコルの契約です。

Work

カードは .project/cards/ の下に Markdown レコードとして管理されます。Work モジュールは、 階層、依存関係、割り当て、スコープ、ステータス遷移、アーカイブ、アセット、 競合を考慮した書き込みを提供します。

workfile card list --json
workfile card show T-0042 --json
workfile card create --title "Implement runtime schema" --area infra
workfile card create --json-input card.json   # body, parent, source and tags in one call
workfile card claim T-0042 --scope apps/api,packages/sdk   # actor resolves itself
workfile card transition T-0042 review
workfile card patch T-0042 --json-input changes.json --expected-revision sha256:...
workfile card archive T-0042
workfile card reopen T-0042 --status backlog

Docs

Docs は、既存のドキュメントをコピーすることなく、次の2つのソースを組み合わせます。

• インデックス化されたドキュメント：設定された glob から検出されます。決定論的な PATH-* ID が割り当てられ、プロトコル経由では読み取り専用です。
• 管理対象ドキュメント：.project/docs/ に保存され、安定した DOC-NNNN ID、 型付きフロントマター、リビジョンを考慮した変更を備えています。

管理対象ドキュメントは再帰的に読み込まれるため、手動で作成したフォルダーも含め、 フォルダーごとに整理できます。ID はグローバルで連番のままです。フォルダーは整理のためのものであり、 識別子ではありません。新しいドキュメントは docs.layout に従います（デフォルトの kind はドキュメントの種類ごとに分類し、flat は管理対象ルートに書き込みます）。 --folder を指定すると、この設定を上書きできます。

workfile doc list --query billing
workfile doc show DOC-0012 --json
workfile doc create --title "Deployment runbook" --kind runbook --status current
workfile doc create --title "Rate limiting" --folder architecture/billing
workfile doc move DOC-0012 --folder architecture
workfile doc patch DOC-0012 --json-input changes.json --expected-revision sha256:...

doctor は、壊れたローカルリンク、解決されていない関連レコードや置き換え済みレコード、 存在しないスコープパス、古くなったレビューとソースの関連を検出します。

History

History は、複数のブランチやエージェントに共有の CHANGELOG.md を編集させるのではなく、 アトミックな変更フラグメントを使用します。

未リリースのフラグメント：

---
id: CHG-0042
title: Add portable history workspace
type: added
area: infra
visibility: public
cards: [T-0042]
created: 2026-07-28
updated: 2026-07-28
---

リリースでは、選択したフラグメントを取り込み、リリースディレクトリの下に移動して、 正規の REL-NNNN レコードを作成します。公開用または内部用の変更履歴は、派生出力です。

workfile changelog list --unreleased
workfile changelog add --title "Add portable history" --type added --area infra
workfile changelog preview
workfile changelog release 0.4.0 --title "History and Memory"
workfile changelog render --visibility public
workfile changelog render --visibility public --write
workfile changelog verify

リリースバージョンは、設定に応じて semver、calendar、freeform の検証を使用できます。 フラグメントとリリースは、カード、ドキュメント、メモリーと同じワークファイル検索および バックリンクグラフに含まれます。

Memory

Memory は、増え続ける単一の会話記録ではなく、型付きでアトミックな、 ライフサイクルを考慮したレコードの集合です。

コレクション	プレフィックス	目的
学び	LRN	確信度と発生シグナルを持つ、再利用可能な観察事項
決定事項	ADR	提案、承認、却下、または置き換えられた決定事項
インシデント	INC	運用上のイベント、重大度、タイミング、是正措置
規約	CONV	人間とエージェントが従う永続的なルール
コンテキスト	CTX	有用ですが、期限切れになる可能性のあるプロジェクトの状態

workfile memory list --collection learnings --status active
workfile memory add learning --title "Atomic fragments avoid merge conflicts" \
  --confidence high
workfile memory add decision --title "Keep Markdown canonical" --status accepted
workfile memory add incident --title "Release pipeline stalled" --severity high
workfile memory graduate LRN-0004 --to CONV-0002,DOC-0012
workfile memory supersede ADR-0003 --by ADR-0009
workfile memory patch CTX-0002 --json-input changes.json --expected-revision sha256:...
workfile memory verify

doctor は、無効なライフサイクル状態、存在しない昇格先や置き換え先、期限切れの コンテキスト、不完全なインシデント解決メタデータを確認します。

統合インデックス

すべてのモジュールは、共通のコレクションレジストリを通じて、ファイルを ProjectRecord エントリーとして正規化します。派生したプロセス内インデックスは、次を提供します。

• プロジェクト全体を対象とする重み付きテキスト検索；
• 安定したレコード ID による検索；
• 4つすべてのドメインにわたる外向き参照と受信バックリンク；
• カードの source: リンクとローカルの Markdown リンク；
• モジュール固有の健全性、ライフサイクル、新しさのシグナル；
• モジュールおよびコレクションの件数。

正規の状態は常にディスク上に保持されます。サーバーキャッシュの有効期間は短く、 無効化でき、完全に再構築可能です。

workfile search "billing architecture"
workfile search release --kind change,release,memory --limit 25 --json

初期化

初期化ツールは、対話形式でも自動化向けの決定的な方法でも実行できます。パッケージマネージャー、モノレポのフォルダー、カードが配置されていそうな領域、ドキュメントのソース、既存のエージェント環境、CI プロバイダーを検出します。ドライランでは、ファイルシステムに対する正確な変更計画を確認できます。

pnpm dlx @illodev/workfile init
pnpm dlx @illodev/workfile init --yes \
  --agents agents-md,claude,cursor,copilot --ci github
workfile init --dry-run --json

生成される project.config.mjs はプレーンなオブジェクトをエクスポートするため、pnpm dlx で初期化したワークスペースも、パッケージをローカルにインストールする前から読み込み可能です。--force を明示しない限り、既存のファイルは上書きされません。.project/.cache/ は .gitignore に追加され、すべての標準プロトコルファイルは引き続き追跡対象になります。

ホスト型デモ

UI には、静的ホスティング（Vercel、GitHub Pages、任意のファイルサーバー）向けのデモモードが用意されています。npm run build:demo を実行すると、シード済みワークスペースのスナップショットを再生する、メモリ内 API を備えた UI がビルドされます。すべてのビューが動作し、セッション中は通常どおり変更できますが、再読み込みするとリセットされます。リポジトリには vercel.json が含まれているため、Vercel にインポートすれば、設定なしでデモをデプロイできます。

pnpm run demo:data   # reseed and resnapshot packages/workfile/ui/src/demo-data.json
pnpm run build:demo  # static demo build into packages/workfile/dist/demo

通常のビルドでは、ツリーシェイキングによってデモレイヤーとスナップショットがバンドルから除外されます。

リリース

リリースは CI から npm の信頼された公開（OIDC）を通じて公開されます。リポジトリに npm トークンは保存されません。リリースを作成する前に、前回のタグ以降に UI の変更が含まれている場合は、pnpm run screenshots を実行してください。すべてのビューを再撮影し、README とランディングページの静止画を自動で公開します。これらはバージョンを更新するコミットではなく、シェルを変更したコミットに含めます。リリースの流れは次のとおりです。

1. 変更履歴を作成します。workfile changelog release <version> と workfile changelog render --write を実行します。
2. バージョンを更新してタグを付けます。npm version <version> を実行し、続けて git push && git push --tags を実行します。 バージョンフックにより、すべての packages/* パッケージも同時に更新されます。ワークスペースパッケージは常にコアと同じバージョンでリリースされます。
3. Release ワークフローで、タグが package.json と一致すること（およびワークスペースのバージョンにずれがないこと）を検証し、pnpm で check:release（ビルド、型チェック、テスト、監査、パッケージ化した tarball のスモークテスト）を実行してから、npm CLI を使ってコアとすべてのワークスペースパッケージを latest で公開します。

プレリリース用のチャンネルはありません。公開されたすべてのバージョンは npm install ですぐに利用でき、v*-rc.* タグは公開されずにリリースに失敗します。これは好みではなく、信頼された公開の仕組みによるものです。OIDC が許可するのは npm publish のみで、それ以外のレジストリへの書き込みは許可されないため、いったん設定されたリリース候補の dist-tag を CI が移動することはできません。

エージェントプロトコル

標準の指示とワークフローは .project/agents/ にあります。簡潔な管理対象ブロックは、ユーザーの無関係なコンテンツを置き換えずに、サポート対象の環境へ同期されます。

AGENTS.md
CLAUDE.md
.cursor/rules/workfile.mdc
.github/copilot-instructions.md

workfile agents sync
workfile agents sync --targets agents-md,claude,cursor,copilot
workfile agents check
workfile agents context --card T-0042

管理対象ブロックには、パッケージのバージョンと SHA-256 ダイジェストが含まれます。agents check と workfile doctor は、生成された指示の欠落、未管理、古さを報告します。エージェントのコンテキストは上限が設けられており、workfile のメモリーをすべて読み込むのではなく、選択したカード、直接の関連項目、有効な規約、未解決のインシデント、有効期限切れでないコンテキストを優先します。

Model Context Protocol

Workfile には、UTF-8 の改行区切り JSON-RPC を stdio 経由で使用する、依存関係のないローカル MCP サーバーが含まれています。CLI および HTTP API と同じコアサービスにすべての操作を委譲し、新旧のプロトコルリビジョン（2026-07-28 と 2025-11-25）の両方に対応し、32 個のツール、4 個のリソース、3 個のプロンプトを公開します。--read-only モードでは、変更ツールはすべて利用できなくなります。

何もインストールせずに、クライアントから接続できます。これは、公式レジストリが io.github.illodev/workfile 用に公開している呼び出し方法です。多くのクライアントでは、この一覧から自動的に設定が作成されます。

{
  "mcpServers": {
    "workfile": {
      "command": "npx",
      "args": ["-y", "@illodev/workfile", "mcp"]
    }
  }
}

ここでの mcp はバイナリではなくサブコマンドです。npx はパッケージ名と一致する名前の実行ファイルを解決し、その後に続くすべての引数を渡します。クライアントの起動場所がワークスペース以外の場合は --root PATH を追加してください。指定がない場合は .project/ を上位ディレクトリへ向かって検索します。また、読み取りツールのみを提供し、変更をすべて拒否するには --read-only を追加します。

パッケージがインストール済みなら、同じサーバーをサブコマンドから起動できます。

workfile mcp
workfile mcp inspect --json
workfile mcp config --read-only --json

Claude Code では、同じ機能をプラグインとして利用できます。MCP サーバーに加え、/claim、/card-context、/next、/done コマンド、スキル、そしてカードの取得を実行可能なガードレールにするフックが含まれています。リポジトリに生成ファイルをコミットする必要はありません。

/plugin marketplace add illodev/workfile
/plugin install workfile@illodev

ツール一覧、リソース、プロンプト、プロセスの衛生管理、プラグインの機能範囲を含む完全な仕様は、docs/mcp.md に記載されています。

このサーバーは Glama に掲載されており、コンテナ内でビルドされ、報告される機能が検査されます。

検索連携

字句検索は、引き続き決定論的かつローカルで実行されます。ホストはプログラムから任意のセマンティック検索プロバイダーを注入できます。Workfile がベンダーを選択したり、リポジトリのコンテンツを独自にネットワーク経由で送信したりすることはありません。

ファーストパーティ：ローカル埋め込み

@illodev/workfile-search-local はデバイス上で埋め込みを実行します（onnxruntime-web、CPU 上の ONNX、量子化された Xenova/multilingual-e5-small）。リポジトリのコンテンツがマシンの外に出ることはありません。project.config.mjs では ガード付きインポート を使って宣言してください。設定はパッケージを解決できない環境でも読み込める必要があるためです（生成される CI ジョブは、クリーンなクローンで npx を実行します）。

export const integrations = await (async () => {
    try {
        const { localSearchIntegration } = await import(
            "@illodev/workfile-search-local"
        );
        return [localSearchIntegration()];
    } catch {
        return []; // package absent: search stays lexical
    }
})();

export default {
    // …
    search: { provider: "local-embeddings" }
};

組み込む前に、コストモデルを把握してください。初回のハイブリッド検索では、キャッシュされていない候補レコードすべての埋め込みが作成されます。数千件のレコードがあるワークスペースでは、数分にわたって CPU を継続使用します。エージェントが読み込んだ CLI、ボード UI、MCP サーバーのいずれが最初に検索を実行するかによって、この処理が開始されます。プロバイダーは、デフォルトで ONNX が使用するコア数を全体の半分に制限し、中断された処理を再開できるようにバッチごとに保存します。また、標準エラー出力に進捗を表示します。search.maxProviderRecords をコーパスに合わせて設定すると、すべてのレコードが検索対象になります。詳細とオプションについては、packages/search-local/README.md を参照してください。

独自のプロバイダーを使用する

import {
    createSemanticSearchProvider,
    searchProjectRecordsHybrid
} from "@illodev/workfile/search";

const provider = createSemanticSearchProvider({
    id: "company-embeddings",
    async search({ query, records }) {
        // Return [{ id, score }] with scores between 0 and 1.
        return rankWithYourApprovedProvider(query, records);
    }
});

const result = await searchProjectRecordsHybrid(index.records, query, {
    provider,
    semanticWeight: 0.35
});

アダプター境界により、外部データの開示はホストが明示的に判断でき、正規の Markdown／インデックス実装はプロバイダーに依存しません。

実験的な連携レジストリ

プログラムから利用するホストは、承認済みのセマンティック検索アダプターとヘルスアダプターを、小規模なベンダー中立のレジストリにまとめることができます。

import {
    createIntegrationRegistry,
    defineProjectIntegration
} from "@illodev/workfile/integrations";

const integrations = createIntegrationRegistry([
    defineProjectIntegration({
        id: "company.platform",
        semanticSearchProvider: provider,
        async healthCheck({ workspace, index }) {
            return [];
        }
    })
]);

このレジストリは MCP サーバーと doctor API で使用できます。現在の RC では意図的に範囲を限定しています。ベンダー固有のイシュートラッカー、デプロイシステム、認証情報は正規のパッケージに含まれません。この境界は、スキーマを GitHub、GitLab、Jira、またはデプロイプロバイダーに固定することなく、実際の連携を通じて成熟させることができます。

CI テンプレート

CI ファイルには同じ管理対象ファイルの契約が適用され、GitHub Actions、 GitLab CI、または汎用のシェルランナー向けに生成できます。

workfile ci sync --targets github,gitlab,generic
workfile ci check

テンプレートは、固定された Workfile バージョンに対して、Workfile の doctor とエージェントの同期チェックの両方を実行します。

レガシーの移行

v1 の .planning システムは、決定論的な競合チェックを行いながら計画・適用できます。

workfile migrate plan --source .planning
workfile migrate apply --source .planning --mode copy
workfile migrate apply --source .planning --mode move

有効なレガシーカードとアセットは、正規の v2 Work レコードになります。古い提案、変更履歴、学習記録、形式が正しくないレコードは、互換性のないスキーマで暗黙に再解釈されるのではなく、.project/sources/legacy-planning/ に保持されます。適用された移行はすべて、ソース、移行先、ダイジェスト、結果のメタデータを含む .project/migrations/legacy-planning.json を書き込みます。

一般的な CLI

workfile init
workfile schema --json
workfile doctor --json
workfile ui
workfile ui --read-only --host 0.0.0.0 --allowed-host board.example.com

コマンドは --json を指定すると、安定した機械可読エラーを返します。リビジョンが古い場合は終了コード 3、設定エラーの場合は終了コード 2、検証エラーおよび見つからない場合のエラーは終了コード 1 で終了します。コマンドの全容は docs/cli.md に記載されています。

HTTP API

workfile ui --read-only --host 0.0.0.0 --allowed-host board.example.com は、閲覧用のボードと同じものを提供します。変更を行うすべてのルートは 409 WORKSPACE_READ_ONLY を返し、UI の編集機能は表示されなくなります。ただし、独自の認証機能はないため、この方法で公開する場合は、認証を行うリバースプロキシを前段に配置してください。詳細は docs/security.md を参照してください。

workfile ui はローカルサーバーを起動し、通常は http://127.0.0.1:4747 で利用できます。バージョン管理された /api/v2/* インターフェースでは、ワークスペース、統合検索、すべてのコレクション（カード、ドキュメント、変更履歴（リリースのプレビュー／組み立て／レンダリングを含む）、メモリーのライフサイクル、エージェント、CI 同期）を扱います。管理対象レコードの読み取りでは ETag が公開され、書き込みでは If-Match を受け付け、エラーには安定したコードが使われます。エンドポイントのリファレンスは docs/http-api.md にあります。

ローカル UI

ナビゲーションは、ドメインごとにグループ化された折りたたみ式のサイドバーです。

• 作業： エクスプローラー、トリアージ、フロー、エピック、ガントタイムライン（ステータスごとに色分けされたバー、月単位の目盛り、今日のマーカー）。
• ナレッジ： ドキュメント（検索、Markdown、メタデータ、鮮度、スコープ、バックリンク）とメモリー（型付きコレクション、ライフサイクルの警告、昇格、置き換え）。
• プロジェクト： ワークフロー（プロビナンスグラフ — すべてのレコードがノード、型付きリレーションがエッジ）、履歴（フラグメント、リリース、リリース準備、レンダリングされた変更履歴のプレビュー）、ヘルス。

ヘルスの問題から、どのドメインのレコードにも移動できます。ランタイム構成によってカードの領域、変更の語彙、メモリーコレクションのステータスが決まり、これらの値はビューにコンパイルされません。ファイルへのリンクを開くとローカルエディターが開きます。サーバーが repoUrl を提供している場合（ホストされたデモなど）は、リポジトリの Web UI が開きます。

概要では、「調子はどうか」という問いに、最も深刻なものから順に選ばれた一文で答えます。医師のエラー、停滞したクレーム、衝突するスコープ、ブロックされたカード、進行中の作業を示し、その上に、離席中にエージェントが記録したすべての変更の履歴を表示します。

インスペクターを開いたエクスプローラー	ガントタイムライン

リリースを表示した履歴	メモリー（ダークテーマ）

ワークフローでは、コレクションを4つのリストに分けず、1つのグラフとして読み込みます。1段目の切り替えでコレクションを選択し、2段目でリレーションの種類を選択します。フロントマターで宣言されたリレーションは実線で、文中に記述されたIDは破線で描画されます。文章中のリンクはフィールドよりも根拠として弱く、同じように確かなものに見えてはならないためです。文章のスキャンはデフォルトでオフです。これは、このワークスペースの742個のエッジのうち294個にあたります。上の図は、リレーションが宣言された精選コーパスを示しています。カードを追跡する related なドキュメント、教訓となったインシデントに結び付く学習内容、解決の根拠となったカードに結び付く決定などを通じて、カード、その背景にある決定、それを説明するドキュメントが、1つのオブジェクトとして読み取れます。

開発

このリポジトリは pnpm ワークスペースです。ルートはバージョンと委譲スクリプトを保持するプライベートなシェルであり、公開されるものはすべて packages/ 以下にあります。コアは packages/workfile にあり、packages/search-local のようなプロバイダーがその隣に配置され、すべて同じバージョンでリリースされます。pnpm のバージョンは packageManager フィールドで固定されており、corepack enable で自動的に適用されます。

pnpm install
pnpm run check
pnpm run smoke:package
node ./packages/workfile/dist/bin/workfile.js mcp inspect --root ./packages/workfile/test/fixtures/workspace --json
node ./packages/workfile/dist/bin/workfile.js schema --root ./packages/workfile/test/fixtures/workspace --json
node ./packages/workfile/dist/bin/workfile.js doctor --root ./packages/workfile/test/fixtures/workspace --json
node ./packages/workfile/dist/bin/workfile.js ui --root ./packages/workfile/test/fixtures/workspace

pnpm run check は TypeScript のランタイムと宣言ファイルをコンパイルし、公開コンシューマーとの厳格な互換性を確認し、React UI の型チェックとバンドルを行い、完全なテストスイートを実行します。 pnpm run smoke:package は一時的なプロジェクトに実際の tarball をパッケージ化してインストールしてから、初期化、4 つすべてのドメイン、MCP、パッケージ化された UI を検証します。npm のコンシューマーパスを検証するため、スモークテストのインストールには意図的に npm を使用します。

prepack はランタイムの宣言ファイルと UI を再ビルドします。これにより、今後公開されるパッケージには dist/ 以下のコンパイル済みランタイムアーティファクトのみが含まれ、開発用 TypeScript やコピーされた UI ソースツリーは含まれません。

現在保証されていること

• バイト単位で安定したスカラー／リストのラウンドトリップに対応する、制限付き frontmatter コーデック。
• 未知の frontmatter フィールドと本文のバイト列を保持します。
• ファイルのアトミックな置き換え、レコード単位のロック、衝突に安全な ID の予約。
• SHA-256 リビジョントークンと古い書き込みの拒否。
• Work のアトミックな取得、状態遷移、アーカイブ、再オープン操作。
• 管理対象の Docs、History のフラグメント、型付き Memory の変更。
• 正規フラグメントの消費と派生レンダリングによるリリースの組み立て。
• 設定可能な、リポジトリ内で安全なパスとランタイム語彙。
• すべてのドメインで共通の正規化、検索、参照、バックリンク。
• Work、Docs、History、Memory のヘルス診断。
• 公開パッケージおよびサブパスエクスポート用の、コンパイル済み ESM と .d.ts 宣言ファイル。
• クリーンな tarball インストールから検証された、実行可能なパッケージ化済み CLI/MCP バイナリ。
• バージョン管理された API と、元のボード向け互換アダプター。

ドキュメント

• docs/getting-started.md — インストール、初期化、日々の作業サイクル。
• docs/cli.md — すべてのモジュールを網羅した CLI リファレンス。
• docs/http-api.md — エンドポイントのリファレンス、規約、エラー。
• docs/mcp.md — MCP サーバーの仕様：ツール、リソース、プロンプト。
• docs/security.md — ローカルサーバー、リクエストガード、アセット処理の脅威モデルと、意図的に対象外としている事項。
• docs/ui.md — インターフェイス：ビルド、依存関係ゼロの保証、shadcn の移行とデザインシステムの共存方法。
• docs/SPEC.md — 規範となるプロトコル仕様：データモデル、レコードの仕様、リビジョンのセマンティクス、MCP 統合の仕様。