Agent-Skills.md

Agent Skills: ADR Session

Start or resume an ADR session. Without number: show status overview and recommend next actionable ADR. With number: provide phase-specific guidance. Trigger: /adr-session, /adr-session NNN, /adr-session new

UncategorizedID: berlysia/dotfiles/adr-session

Repository

berlysia/dotfiles
berlysia
9

Install this agent skill to your local

pnpm dlx add-skill https://github.com/berlysia/dotfiles/tree/HEAD/.skills/adr-session

Skill Files

Browse the full folder contents for adr-session.

Download Skill

Loading file tree…

.skills/adr-session/SKILL.md

Skill Metadata

Name
adr-session
Description
"Start or resume an ADR session. Without number: show status overview and recommend next actionable ADR. With number: provide phase-specific guidance. Trigger: /adr-session, /adr-session NNN, /adr-session new"

ADR Session

ADR（Architecture Decision Record）の状態管理とセッションガイダンスを提供する。

Argument Parsing

引数に応じてモードを分岐:

  • 引数なし → Status Overview Mode
  • NNN (number) → Session Mode for ADR-NNN
  • new → New ADR Creation Mode

Mode 1: Status Overview (no arguments)

Step 1: Scan ADR files

Glob: docs/decisions/adr-*.md

If no files found AND docs/decisions/ does not exist:

  • Report: "ADR ディレクトリが見つかりません"
  • Suggest: "docs/decisions/ と docs/plans/ を作成しますか？"
  • If user agrees, create both directories
  • Then suggest: "/adr-session new で最初の ADR を作成できます"
  • Stop here

If directory exists but no ADR files:

  • Report: "ADR ファイルがまだありません"
  • Suggest: "/adr-session new で最初の ADR を作成できます"
  • Stop here

Step 2: Parse frontmatter

For each adr-*.md file, read the file and extract YAML frontmatter (content between --- delimiters at the start).

Refer to adr-schema.md for valid field definitions.

Error handling:

  • YAML parse error → warn with filename and error, skip file
  • Invalid status value (not in Proposed/Accepted/InProgress/Complete) → warn and skip
  • No frontmatter → report as "frontmatter なし" in the table

Step 3: Determine phase for each ADR

Apply phase logic from adr-schema.md:

Complete           → done
Proposed           → investigation
Accepted + no plan → planning
Accepted + plan without <!-- validated --> → validation
Accepted + plan with <!-- validated -->    → implementation
InProgress         → implementation

For ADRs with a plan field, check if docs/plans/{plan} exists and contains <!-- validated -->.

Step 4: Display status table

Format:

## ADR Status Overview

| # | Title | Status | Plan | Phase |
|---|-------|--------|------|-------|
| 001 | Auth System | Accepted | plan-auth.md | planning |
| 002 | API Design | Proposed | - | investigation |
| 003 | DB Migration | Complete | plan-db.md | done |

Step 5: Find actionable ADRs

An ADR is actionable when (see adr-schema.md):

  1. Status is NOT Complete
  2. All deps reference ADRs with status: Complete (or no deps)
  3. Not involved in a circular dependency

Circular dependency detection: Build a directed graph from all deps fields. If a cycle is found:

  • Warn: "循環依存を検出: ADR-X → ADR-Y → ADR-X"
  • List all ADR numbers involved
  • Exclude them from actionable list

Step 6: Recommend next ADR

From the actionable list, recommend the ADR with the earliest phase in priority order: investigation > planning > validation > implementation.

If multiple ADRs are in the same phase, recommend the one with the lowest number.

### 推奨: 次に着手すべき ADR

**ADR-002: API Design** (phase: investigation)
→ `/adr-session 2` で調査セッションを開始できます

Mode 2: Session Mode (NNN specified)

Step 1: Load target ADR

Read docs/decisions/adr-NNN-*.md (glob to find the file matching the number).

If not found: "ADR-NNN が見つかりません。/adr-session でステータス概要を確認してください。"

Step 2: Display ADR summary

Show:

  • Title, status, phase
  • deps status (each dep's current status)
  • Plan link if exists

Step 3: Check dependencies

If ADR has deps, check each referenced ADR's status:

  • All Complete → proceed normally
  • Some not Complete → warn: "依存 ADR-X がまだ Complete ではありません（現在: {status}）。先にそちらを完了することを推奨します。"

Step 4: Phase-specific guidance

investigation (status: Proposed)

### Investigation Session

このADRはまだ調査段階です。以下のアクションを推奨します:

1. ADR の「コンテキスト」「決定」「影響」セクションを充実させる
2. 必要な調査・PoC を実施
3. 完了したら logic-validator で ADR の論理的整合性を検証:
   - Task(subagent_type: "logic-validator") で ADR 内容を検証
4. 検証後、status を `Accepted` に更新

planning (status: Accepted, no plan)

### Planning Session

ADR は承認済みです。実装計画を作成しましょう。

**Plan Mode の使用が必須です。** EnterPlanMode を実行してください。

1. Plan Mode で実装計画を作成
2. テンプレート: この skill の [plan-template.md](references/plan-template.md) を参照
3. 計画ファイルを `docs/plans/plan-{slug}.md` に保存
4. ADR の frontmatter に `plan: plan-{slug}.md` を追加
5. plan-review-automation が自動レビューを実行
6. 人間が `Approval Status: approved` を設定

implementation (plan approved or status: InProgress)

### Implementation Session

計画は検証済みです。実装を進めましょう。

1. 計画ファイル `docs/plans/{plan}` に従って実装
2. 便利なスキル:
   - `/decompose` — タスクを細分化
   - `/execute-plan` — 計画に沿って順次実行
   - `/scope-guard` — スコープが大きすぎる場合
3. テストが通ることを確認
4. 完了したら ADR の status を `Complete` に更新

done (status: Complete)

### Complete

この ADR は完了済みです。変更や再検討が必要な場合は status を更新してください。

Step 5: Check for session memos

Search for related memos:

Glob: .tmp/session-memos/*.md

Read each file and check if it contains ADR-{NNN} (the target ADR number). If found, list them:

### 関連セッションメモ
- `.tmp/session-memos/abc12345.md` — [問題意識の冒頭]

Step 6: Session closing reminder

At the end of the guidance, remind:

セッション終了時には `/session-memo` で作業内容を記録することを推奨します。

Mode 3: New ADR Creation (argument: new)

Step 1: Determine next number

Scan existing docs/decisions/adr-*.md files, extract numbers, and compute max + 1. If no files exist, start from 001. Zero-pad to 3 digits.

Step 2: Ask for title

Use AskUserQuestion to ask: "新しい ADR のタイトルを入力してください"

Provide no predefined options (user will select "Other" and type the title).

Step 3: Create directories if needed

If docs/decisions/ or docs/plans/ don't exist, create them.

Step 4: Create ADR file

Read adr-template.md for the template structure.

Generate the slug from the title (lowercase, spaces to hyphens, remove special chars).

Write the file to docs/decisions/adr-{NNN}-{slug}.md with:

  • status: Proposed in frontmatter
  • NNN and title filled in

Step 5: Guide next steps

ADR-{NNN} を作成しました: `docs/decisions/adr-{NNN}-{slug}.md`

### 次のステップ
1. 「コンテキスト」「決定」「影響」セクションを記入してください
2. 調査が完了したら logic-validator で検証:
   Task(subagent_type: "logic-validator") で ADR の論理的整合性を検証
3. 検証後、status を `Accepted` に更新
4. `/adr-session {NNN}` でセッションガイダンスを確認できます

Related Skills

| Skill | When to Use | | ------------------------------- | -------------------------------------------------------- | | logic-validator (Task subagent) | ADR 作成・更新後の論理検証（investigation phase 完了時） | | /session-memo | セッション終了時の記録 | | /decompose | 実装タスクの細分化（implementation phase） | | /execute-plan | 計画に沿った順次実行（implementation phase） | | /scope-guard | ADR のスコープが大きすぎる場合 |