@masinc/qtk

v0.1.6

Published

21 days ago

Local issue / ADR / spec / plan management CLI tool (Bun required)

0High
0Medium
0Low

masinc

issue adr spec plan ticket cli markdown bun

qtk

ローカル issue / ADR / spec / plan / log / doc 統合管理 CLI ツール。

Markdown ファイル (YAML frontmatter 付き) をストアとして、チケット・アーキテクチャ決定記録・仕様・計画・作業履歴・ドキュメントを単一ツールで管理します。git でバージョン管理可能です。config.yaml の types: でカスタム種別を定義できます。

注意: qtk は Bun ランタイム必須 です（npx では動作しません）。bunx は過去のバージョンをキャッシュするため、最新版を使う場合は bunx @masinc/qtk@latest を実行してください。

インストール

# bun が必要です (https://bun.sh)
bunx @masinc/qtk --help

クイックスタート

# ストア初期化 (.qtk/ ディレクトリと config.yaml を作成)
bunx @masinc/qtk init

# チケット作成
bunx @masinc/qtk issue new "認証機能を追加" -d "ユーザー認証を実装" --tag backend --ac "ログイン画面がある"

# チケット一覧
bunx @masinc/qtk issue list

# チケット詳細
bunx @masinc/qtk issue show 1

# チケット編集 (ステータス・タグ・コメント)
bunx @masinc/qtk issue edit 1 --status in-progress --add-tag auth --comment "実装開始"

# ADR 作成
bunx @masinc/qtk adr new "データベース選定" -d "DB を選定する" --tag architecture

# 計画作成 (AI Agent の plan 履歴管理)
bunx @masinc/qtk plan new "qtk ツール構築" --generated-by claude

# 作業履歴作成
bunx @masinc/qtk log new "認証APIの実装" -d "JWT 認証エンドポイントを実装した" --ref 1

# ドキュメント作成
bunx @masinc/qtk doc new "API 設計ドキュメント" -d "API の全体設計"

# 横断検索
bunx @masinc/qtk search "認証"

# 全種別バリデーション
bunx @masinc/qtk validate

ヒント: コマンドには短縮エイリアスがあります。issue→is、spec→sp、plan→pl、list→ls、search→find/fd など。例: bunx @masinc/qtk is ls は issue list と同じです。new と create は全種別でどちらも使えます。

コマンド一覧

エイリアス: issue→is / spec→sp / plan→pl / tags→tg / search→find,fd / graph→gr / list→ls / new↔create（全種別で両対応）

種別コマンド (issue / adr / spec / plan / log / doc / ユーザー定義種別) は config.yaml の types: から動的生成されます。全種別で共通のサブコマンドを持ちます:

| サブコマンド | 説明 | |---|---| | new (alias: create) | レコード作成 | | list (alias: ls) | 一覧表示 | | show | 詳細表示 | | edit | 編集 | | archive / unarchive | アーカイブ・復元 (archived フラグ) | | validate | 種別のバリデーション | | claim | クレーム (claim feature を持つ種別のみ) |

| コマンド | 説明 | |---|---| | qtk init | ストアを初期化 (.qtk/ ディレクトリ + config.yaml + テンプレート + .gitignore) | | qtk <type> new "タイトル" [-d 説明] [--tag タグ] [--assignee 名前] [--dep 依存ID] [--ref 参照ID] [--ac 基準] [--supersedes 旧ID] | レコード作成 (create も可) | | qtk <type> list [-s ステータス] [-a 担当者] [--tag タグ] [--ready] [--blocked] [--search キーワード] [--limit n] [--archived] [--all] [--json] | 一覧表示 (ls も可) | | qtk <type> show <ID> [--json] | 詳細表示 | | qtk <type> edit <ID> [--title タイトル] [-d 説明] [--status ステータス] [--tag タグ] [--add-tag タグ] [--remove-tag タグ] [--clear-tags] [--assignee 名前] [--comment 本文] [--dep 依存ID] [--ref 参照ID] [--ac 基準] [--final-summary サマリー] [--supersedes 旧ID] | 編集 | | qtk <type> archive <ID> / qtk <type> unarchive <ID> | アーカイブ・復元 | | qtk <type> validate | 種別のバリデーション | | qtk tags [--json] | 全種別のタグ一覧 | | qtk search "キーワード" [--type 種別] [--status ステータス] [--tag タグ] [--limit n] [--json] | 横断検索 (find/fd も可) | | qtk graph [--plan ID] [--cycles] [--format text\|dot\|json] | 依存グラフ表示・循環依存検出 | | qtk validate | 全種別のバリデーション | | qtk web [--port ポート] [--no-open] | Web UI / Kanban を起動 (http://127.0.0.1:port) |

配列系オプション: --tag、--dep、--ref、--ac、--assignee、--add-tag、--remove-tag はカンマ区切りで複数指定可能です (例: --tag backend,auth)。

ステータス

| 種別 | ステータス | |---|---| | issue | new → in-progress → paused → done | | adr | proposed → accepted / deprecated / superseded | | spec | new (固定) | | plan | drafting → ready → in-progress → completed / superseded / abandoned | | log | new → in-progress → done | | doc | なし (ステータスを持たない) |

ストア構成

<repo-root>/.qtk/
├── config.yaml             # 設定ファイル (types 定義付き)
├── templates/              # 本文テンプレート (issue.md, adr.md, spec.md, plan.md, log.md, doc.md)
├── issues/                 # チケット (0001-slug.md)
├── adrs/                   # ADR (0002-slug.md)
├── specs/                  # 仕様 (0003-slug.md)
├── plans/                  # 計画 (0004-slug.md)
├── logs/                   # 作業履歴
├── docs/                   # ドキュメント
├── .meta/                  # 内部管理 (counter.json, *.lock)
└── .gitignore              # *.lock を除外 (init 時に自動生成)

全種別で共通採番 (#0001 形式、デフォルト4桁)
ファイル名は <NNNN>-<slug>.md
採番はファイルロックで原子的 (並列セッションでも ID 衝突なし)
counter.json はバージョン管理対象、*.lock は gitignore 対象
アーカイブは archived: boolean フラグで管理 (ファイル移動なし)

設定 (config.yaml)

version: "1.0"
idDigits: 4
claimLeaseMinutes: 30

types:
  issue:
    dir: issues
    statuses: [new, in-progress, paused, done]
    defaultStatus: new
    doneStatus: done
    features: [dependencies, claim, acceptance_criteria, final_summary]
    template: issue.md
  adr:
    dir: adrs
    statuses: [proposed, accepted, deprecated, superseded]
    defaultStatus: proposed
    doneStatus: accepted
    features: [supersedes, deciders]
    template: adr.md
  spec:
    dir: specs
    statuses: [new]
    defaultStatus: new
    doneStatus: null
    features: []
    template: spec.md
  plan:
    dir: plans
    statuses: [drafting, ready, in-progress, completed, superseded, abandoned]
    defaultStatus: drafting
    doneStatus: completed
    features: [supersedes]
    template: plan.md
  log:
    dir: logs
    statuses: [new, in-progress, done]
    defaultStatus: new
    doneStatus: done
    features: []
    template: log.md
  doc:
    dir: docs
    statuses: []
    defaultStatus: null
    doneStatus: null
    features: []
    template: doc.md

カスタム種別の追加

config.yaml の types: にエントリを追加するだけで、qtk <typename> new/list/show/edit が動作します:

types:
  meeting:
    dir: meetings
    statuses: [scheduled, held]
    defaultStatus: scheduled
    doneStatus: held
    features: []
    template: meeting.md

テンプレートファイルは .qtk/templates/meeting.md に配置します。

Windows / PowerShell での注意

PowerShell で日本語が文字化けする場合は、以下を実行してください:

$OutputEncoding = [Console]::OutputEncoding = [System.Text.Encoding]::UTF8

開発

bun install        # 依存インストール
bun test           # テスト実行 (backend + frontend)
bun run typecheck  # 型チェック (tsc + svelte-check)
bun run lint       # lint (Biome)
bun run cli.ts     # 開発実行

Web UI の開発フロー

Web UI は Bun workspaces モノレポ構成です。バックエンド (Hono) は src/web/、フロントエンド (Svelte 5 + Vite + Tailwind v4 + daisyUI 5) は web/ にあります。

フロントエンドを編集する場合 — 1コマンドで API サーバー (port 3000) と Vite dev サーバー (port 5173, HMR) を同時起動:

bun run dev:web

ブラウザで http://localhost:5173/ を開きます。Vite が /api を localhost:3000 へプロキシするため、フロントエンドの変更は HMR で即時反映されます。Ctrl+C で両方停止します。

個別に起動する場合:

bun run dev:cli   # CLI のみ (bun run cli.ts と同じ)
bun run cli.ts web --no-open --port 3000   # API サーバーのみ
bun run --filter @masinc/qtk-web dev       # Vite dev サーバーのみ

バックエンドのみ編集する場合 — フロントエンドの dev サーバーは不要です。bun run cli.ts web が配信するのは web/dist (Vite ビルド済みの静的ファイル) なので、フロントエンドの変更を反映するには bun run build:web が必要です。

テスト:

bun test                              # 既存テスト (API/CLI/store、Bun) + フロントエンド (Vitest)
bun run test:web                      # フロントエンドコンポーネントテストのみ (Vitest)
bun run --filter @masinc/qtk-web test:watch  # フロントエンドテストを watch モードで実行

型チェック:

bun run typecheck       # tsc (backend) + svelte-check (frontend)
bun run typecheck:web   # フロントエンドのみ (svelte-check)

lint / format (Biome):

bun run lint        # lint チェック
bun run lint:fix    # lint 自動修正
bun run format      # フォーマット適用

ビルド:

bun run build        # フルビルド (web → cli)
bun run build:web    # フロントエンドのみ (vite build + web/dist を dist/web/static/ へコピー)
bun run build:cli    # CLI のみ (bun build cli.ts)

リリース手順は RELEASE.md
変更履歴は CHANGELOG.md

スキル統合

qtk CLI は masinc/skills リポジトリで配布されているスキル群と統合されています。以下のスキルが qtk CLI を選択肢としてサポートしています:

| スキル | 説明 | |---|---| | setup-matt-pocock-skills | リポジトリのセットアップ (イシュートラッカー・トリアージラベル・ドメイン文書)。qtk CLI を選択肢に追加 | | to-tickets | 計画・仕様をトレーサーバレットチケットに分解。qtk issue new + --dep で構造化依存 | | to-spec | 会話を仕様に変換。qtk spec new + qtk spec update で管理 | | triage | イシューをトリアージロールで状態管理。qtk issue edit --add-tag / --comment / --status で操作 | | wayfinder | 大規模作業を共有マップとして計画。qtk plan new (マップ) + qtk issue list --ready (フロンティア) + qtk issue claim (クレーム) | | implement | 仕様・チケットに基づいて実装。qtk issue list --ready → show --json → claim → edit --status done のワークフロー | | qtk | qtk CLI の包括的ガイド。issue / ADR / spec / plan / log / doc の全コマンド・ワークフロー・データモデルを詳細に扱う |

スキルのインストール:

npx skills add https://github.com/masinc/skills.git -g

ライセンス

MIT — 詳細は LICENSE を参照。