PM Server — Workflow Guide

1. Workflow とは — pm-server の「思考の段取り」を構造化する

pm-server の workflow は 「ステップ列の状態マシン」。 ある作業 (機能開発・調査・リサーチ) を「順を追って進めるべき step の列」として YAML テンプレートで定義し、各 step では Claude に対して 「ここでは pm_add_decision を使え」「ここでは sub-agent を起動しろ」 といったヒントを構造的に提供する。

1.1 「workflow が嬉しい」3 つの理由

1.2 アーキテクチャ上の役割分担

pm-server 自身は 何もしない。step の hint と progress を返すだけ。 実際の作業 (sub-agent 起動・ADR 作成等) は全部 Claude が行う。 この「engine と executor の分離」が workflow を 柔軟かつ強力にする鍵。

2. メンタルモデル — workflow は「現在地」を返す map

Claude にとって workflow は GPS のような存在。pm_workflow_status を呼ぶと、現在の step が何か、 次にすべきことが何か、artifact (ADR/task/KR) として何を残すべきかが返ってくる。

このループが完了するまで回る。各 advance で artifacts (ADR/task/KR の ID) を渡せば、 後で pm_workflow_status から「この workflow が生んだ artifact 一覧」が取り出せる。

3. Step Lifecycle — 4 つの status

3.1 Workflow 全体の status (instance レベル)

4. Special Features — gate / loop / chain / optional

4 つの構造を組み合わせて「ただの線形列」から「人間と LLM の協働 protocol」に昇華させる。

4.1 gate: user_approval

このフィールドが立った step では、pm_workflow_advance を Claude が 無断で呼ばないことが期待される。user の明示承認を待つ。

engine 側で「自動 advance を block する」コードがあるわけではない (= 紳士協定)。 CLAUDE.md auto-action rule の「gate のあるステップでは、ユーザーの承認を待ってから進む」が enforcement。

4.2 loop / loop_group

同じ loop_group の step は「セット」として扱われ、ループバック可能になる。 pm_workflow_advance(proceed=false) でループバックすると、group 内の全 step が pending にリセット + iteration +1 され、最初の step から再開する。

典型例: super-research の parallel_research ↔ depth_check。Depth Check のスコアが 3.0 未満なら戻ってリサーチを深堀り。

4.3 chain_to

workflow 完了時に「次に起動を推奨する template 名」を返す。 例: discovery 完了 → development の起動を提案。

4.4 optional: true

「条件次第で skip 可能」を明示するフラグ。development workflow の issues step が好例。 skip された場合 status=skipped として記録される。

4.5 required_artifacts warning

step に required_artifacts: [ADR] 等を書くと、advance 時に artifacts が空だと warning を返す (block ではなく soft warn)。

5. Builtin Templates 詳解

v0.9.0 に組み込まれる 4 つのテンプレート。 pm_workflow_templates で一覧、pm_workflow_start(template="...") で起動。

5.1 development (9 steps) — 機能開発の正攻法

ADR → Task → Spec → Plan → Cross-check (gate) → Implement → Test → Quality (gate) → Issues (optional)。 phase-8 / phase-9 の本番タスクはほぼ全てこの workflow で進められた。

5.2 discovery (5 steps, loop あり, chain → development)

調査・ブレストの workflow。research / fact_check / proposal の 3 step が loop_group: brainstorm でループ可。proposal で user 承認後、cross_check → confirm (ADR 起票) → chain_to: development。

5.3 super-research (6 steps, depth_check ループ)

3 並列エージェント (Domain Expert / Critical Analyst / Lateral Thinker) を起動して 6 dimension で depth scoring。スコア < 3.0 で parallel_research へループバック。 完了時は pm_record で Knowledge Record (KR-NNN) として保存。

5.4 brainstorming (8 steps, diverge↔evaluate ループ, chain → development)

アイデアの発散から要件・仕様化までを一貫して扱う workflow。Double Diamond パターンで、 diverge (3 並列エージェント: Idea Generator / Devil's Advocate / Synthesizer) と evaluate (6 dimension scoring: Impact/Feasibility/Effort/Risk/Novelty/Strategic fit) が loop_group: diverge_evaluate でループ可。Top 案の平均スコア < 3.5 なら pm_workflow_advance(proceed=False) で diverge に戻り再発散。

収束後は converge (user 承認) → requirements (KR/category=requirement) → spec (KR/category=spec) → cross_check → record (ADR 起票, user 承認, 必須 artifacts=KR+ADR) → chain_to: development。super-research の 3 agents パターンを発散思考に応用した位置付け (research 用の Domain Expert/Critical Analyst/Lateral Thinker を ideation 用に再キャスト)。

使い分けの指針:

• discovery: 既存解の調査と方向性承認 (research-leaning)。
• super-research: 知識構築としての多角的深掘り (KR を生成)。
• brainstorming: アイデアの創発と要件・仕様への結晶化 (KR + ADR を生成)。

6. YAML Schema 完全リファレンス

Template YAML は WorkflowTemplate と WorkflowStep (Pydantic v2) でバリデートされる。 未知フィールドは error にせず無視 (forward compat)。

6.1 トップレベル (WorkflowTemplate)

6.2 step レベル (WorkflowStep)

6.3 runtime state (template には書かないが instance に残る)

7. カスタム Template の作り方 — Step by Step

7.1 配置場所

<project>/.pm/workflow_templates/
├── code-review.yaml         # 自作テンプレ
└── release.yaml             # 自作テンプレ

builtin と同名のファイルを置けば 上書きされる (storage.py:567)。 組織独自の development.yaml を書いて builtin を rewrite するパターンも可能。

7.2 最小テンプレ — 3 step の release workflow を作る

仮に「version bump → tag → CHANGELOG 更新」の 3 step を回したい場合:

# .pm/workflow_templates/release.yaml
name: Release
description: |
  Atomic release workflow:
  pyproject version bump → git tag → CHANGELOG.

steps:
  - id: bump
    name: Version Bump
    description: >
      pyproject.toml と manifest.json を新 version へ更新。
      ruff format で正規化、test 通過確認。
    tool_hint: pm_log
    produces:
      - version_bump

  - id: tag
    name: Git Tag
    description: >
      git tag -a v<version> -m "<message>" + push tag。
      tag の整合性 (HEAD と tag が一致) を確認。
    consumes:
      - version_bump
    gate: user_approval     # tag は不可逆なので承認待ち

  - id: changelog
    name: CHANGELOG Update
    description: |
      CHANGELOG.md にバージョン entry を追記。
      breaking changes を明示。
    tool_hint: pm_log
    optional: true             # patch release では skip 可

7.3 起動 → 進行 → 完了

> release workflow を起動して、feature は "v0.8.1 patch release"
# → pm_workflow_start(template="release", feature="v0.8.1 patch release")
# → WF-029 として instance 化、current_step = "bump"

> bump 完了。pyproject 0.8.0 → 0.8.1 へ。
# → pm_workflow_advance(artifacts=["pyproject:0.8.1"], notes="ruff clean, tests passed")
# → 次 step "tag" が ACTIVE になる

> (tag step は gate あり) tag 内容を確認してください
# Claude は user 承認を待つ
> OK、進めて
# → pm_workflow_advance(artifacts=["v0.8.1"], notes="git tag -a v0.8.1")

> changelog は patch なので skip
# → pm_workflow_advance(skip=true)
# → workflow_completed: true

7.4 super-research のような loop を持つ template を作る

name: Iterative Debug
description: バグ調査 → 仮説 → 検証 を回す debug ループ

steps:
  - id: reproduce
    name: Reproduce
    description: バグを再現する最小ケースを作る
    loop: true
    loop_group: debug_cycle

  - id: hypothesize
    name: Hypothesize
    description: 原因仮説を立てる (1-3 個)
    loop: true
    loop_group: debug_cycle

  - id: verify
    name: Verify
    description: 仮説を検証 — 当たれば advance、外れたら loop back
    loop: true
    loop_group: debug_cycle
    gate: user_approval

  - id: fix
    name: Fix
    description: 原因を修正 + regression test

使い方:

> reproduce, hypothesize 完了。verify したが外れ → loop back
# → pm_workflow_advance(proceed=false)
# → debug_cycle 内の 3 step が pending にリセット、iteration +1
# → reproduce step が再び ACTIVE

8. Task / ADR / KR との連動

workflow と他の artifact は artifacts 列で疎結合に紐付く。

8.1 advance 時に artifacts を渡す

# workflow の各 step で生まれる artifact ID を渡す
> tasks step 完了、生成タスク 11 件
# → pm_workflow_advance(artifacts=["PMSERV-094", "PMSERV-095", ..., "PMSERV-104"])

> spec step 完了、memory に保存した
# → pm_workflow_advance(artifacts=["memory:153"], notes="spec stored")

8.2 後から逆引き

> WF-028 が生んだ artifact 全部出して
# → pm_workflow_status(workflow_id="WF-028")
# → steps[*].artifacts に履歴が残っている

> KR-005 はどの workflow で生まれた？
# → load_knowledge() の workflow_id field を見る
# → pm_workflow_status はそれを knowledge.count / by_category で返す

8.3 Knowledge Record (KR) 自動紐付け

pm_record で KR を作るとき workflow_id を指定すると、 pm_workflow_status の knowledge field に集計される (super-research の synthesis 用)。

8.4 artifact 型の使い分け (慣例)

9. いつ workflow を使うか — 判断基準

9.1 使うべき場合

9.2 使わない方がいい場合

10. 実用例 (recipe 集)

name: PR Review
steps:
  - id: scope
    name: Scope & Risk
    description: 変更行数・影響範囲・risk profile を把握
  - id: correctness
    name: Correctness
    description: ロジック妥当性 (sub-agent で independent check)
    agent_hint: code-reviewer
  - id: security
    name: Security
    description: 脆弱性チェック
    skill_hint: security-audit
  - id: approval
    name: Approval
    gate: user_approval

11. トラブルシューティング

11.1 builtin template の探索パス確認

> pm_status の diagnostics を見せて
# → diagnostics.builtin_templates_dir.path に builtin の絶対 path
#   diagnostics.builtin_templates_dir.template_count で件数 (現在 3)

11.2 関連リンク

• 架構の workflow 図 → Architecture Section 5
• workflow と日常運用 → User Guide Section 4
• workflow テンプレ source → src/pm_server/templates/workflows/*.yaml
• engine source → src/pm_server/workflow.py
• model schema → src/pm_server/models.py (WorkflowStep / WorkflowTemplate)