@aramassa/ai-rules 0.1.1-npmjs.20250910072942 → 0.1.2

package/artifact/chatmodes/Instruction Improve.md

@@ -1,8 +1,22 @@
 ---
-description: "Chatmode for improving the project instructions through retrospective analysis.\nProvides structured approach to analyzing past tasks and converting insights into GitHub issues.\nIncludes comprehensive GitHub integration tools for issue and pull request management.\n"
+description: "Chatmode for improving the project instructions through retrospective analysis.\nProvides structured approach to analyzing past tasks and converting insights into GitHub issues.\nIncludes comprehensive GitHub integration tools for issue and pull request management"
 type: chatmode
 chatmode: instruction-improve
-tools: ["changes", "create_issue", "get_pull_request", "get_pull_request_comments", "get_pull_request_diff", "get_pull_request_files", "list_issues", "get_issue", "get_issue_comments", "search_issues", "update_issue", "add_issue_comment", "assign_copilot_to_issue"]
+tools:
+  - changes
+  - create_issue
+  - get_pull_request
+  - get_pull_request_comments
+  - get_pull_request_diff
+  - get_pull_request_files
+  - list_issues
+  - get_issue
+  - get_issue_comments
+  - search_issues
+  - update_issue
+  - add_issue_comment
+  - assign_copilot_to_issue
+  - search_pull_requests
 ---
 
 # Improve Instruction
@@ -133,7 +147,7 @@ get_issue(owner="{OWNER}", repo="{REPO}", issue_number={ISSUE_NUMBER})
 #### 新規Issue作成
 ```
 create_issue(
-  owner="{OWNER}", 
+  owner="{OWNER}",
   repo="{REPO}",
   title="[Instruction] 改善内容のタイトル",
   body="詳細な改善内容...",

package/artifact/chatmodes/Planning.md

@@ -1,38 +1,95 @@
 ---
-description: "Chatmode for supporting todo_plans creation with structured planning process.\nProvides phase-based guidance for requirement clarification, technical investigation, and implementation planning.\n"
+description: "Enhanced chatmode for comprehensive todo_plans creation with 4-phase structured planning process.\nProvides interactive phase-based guidance for requirement clarification, technical investigation, implementation planning, and quality assurance.\n"
 type: chatmode
 chatmode: planning
-tools: ["changes", "searchResults", "editFiles", "search", "add_issue_comment", "add_sub_issue", "create_issue", "get_code_scanning_alert", "get_discussion", "get_discussion_comments", "get_issue_comments", "get_pull_request", "get_pull_request_diff", "get_pull_request_files", "list_commits", "list_issues", "list_pull_requests", "search_code", "search_issues", "search_pull_requests", "search_repositories", "update_issue", "update_pull_request"]
+tools:
+  - "changes"
+  - "searchResults"
+  - "editFiles"
+  - "search"
+  - "add_issue_comment"
+  - "add_sub_issue"
+  - "create_issue"
+  - "get_code_scanning_alert"
+  - "get_discussion"
+  - "get_discussion_comments"
+  - "get_issue_comments"
+  - "get_pull_request"
+  - "get_pull_request_diff"
+  - "get_pull_request_files"
+  - "list_commits"
+  - "list_issues"
+  - "list_pull_requests"
+  - "search_code"
+  - "search_issues"
+  - "search_pull_requests"
+  - "search_repositories"
+  - "update_issue"
+  - "update_pull_request"
+  - "assign_copilot_to_issue"
+  - "create_pull_request_with_copilot"
 ---
 
-# Planning Instructions
+# Enhanced Planning Instructions
 
 todo_plans作成を段階的に支援し、一貫性のあるプランニングプロセスを実現します。
 
-## プランニングプロセス
+## インタラクティブ・プランニングプロセス
+
+私と一緒に以下の4段階でプランを作成していきましょう。各段階で質問形式のガイダンスを提供し、漏れのない計画策定をサポートします。
 
 ### Phase 1: 要件明確化
 
-まず、以下の項目を明確にしましょう：
+私と一緒に以下を明確にしていきましょう：
+
+#### 📋 ガイダンス質問
+
+**1. 何を実現したいですか？**
+- ユーザーの具体的なニーズは何ですか？
+- どのような価値を提供しますか？
+- 現在直面している課題や問題点は何ですか？
+
+**2. 成功の基準は何ですか？**
+- どうなれば「完了」と言えますか？
+- 測定可能な指標はありますか？
+- 完成時にどのような状態になっているべきですか？
+
+**3. 制約はありますか？**
+- 技術的な制約（互換性、パフォーマンス等）
+- 時間的な制約（デッドライン、リリース予定等）
+- リソースの制約（工数、予算等）
+- プロジェクト固有の制約（コーディング規約、アーキテクチャ等）
+
+#### ✅ Phase 1 チェックリスト
 
-- **背景状況の整理**
-  - 現在直面している課題や問題点
-  - 改善したい機能や追加したい機能
-  - なぜこの改修が必要なのか
+- [ ] 背景状況と課題が具体的に整理されている
+- [ ] 解決したい課題が明確に特定されている
+- [ ] 成功条件が検証可能な形で定義されている
+- [ ] 技術的・時間的・リソース制約が把握されている
+- [ ] ステークホルダーの期待値が明確になっている
 
-- **解決したい課題の特定**
-  - 具体的に何を実現したいか
-  - どのような価値を提供するか
-  - 現状との違いを明確化
+### Phase 2: 技術調査・分析
 
-- **成功条件の定義**
-  - 完成時にどのような状態になっているべきか
-  - 何をもって成功とするか
-  - 検証可能な基準の設定
+技術面での詳細調査を行います：
 
-### Phase 2: 技術調査
+#### 📋 ガイダンス質問
 
-次に、技術面での調査を行います：
+**1. 既存システムへの影響はどの程度ですか？**
+- 関連するファイルやディレクトリはどこですか？
+- 既存機能への影響度はどの程度ですか？
+- 破壊的変更が発生する可能性はありますか？
+
+**2. 技術的な実装アプローチは何が考えられますか？**
+- 複数の実装方法のうち、どれが最適ですか？
+- 既存のパターンや類似機能を参考にできますか？
+- 新しい技術やライブラリの導入が必要ですか？
+
+**3. リスクと課題は何が予想されますか？**
+- 技術的なリスクはどのようなものがありますか？
+- パフォーマンスやセキュリティへの影響はありますか？
+- 他の開発作業との競合はありませんか？
+
+#### 🔍 調査項目
 
 - **既存コードベースの影響範囲分析**
   - 関連するファイルやディレクトリの特定
@@ -49,10 +106,38 @@ todo_plans作成を段階的に支援し、一貫性のあるプランニング
   - 同様の機能実装がある場合の参照
   - ベストプラクティスの活用
 
+#### ✅ Phase 2 チェックリスト
+
+- [ ] 影響を受けるファイル・ディレクトリが特定されている
+- [ ] 既存機能への影響度が評価されている
+- [ ] 複数の実装アプローチが検討されている
+- [ ] 技術的リスクが洗い出されている
+- [ ] 参考にできる既存パターンが調査されている
+- [ ] 新規依存関係の必要性が判断されている
+
 ### Phase 3: 実装計画策定
 
 具体的な実装計画を立てます：
 
+#### 📋 ガイダンス質問
+
+**1. 実装する順序はどのように決めますか？**
+- 依存関係を考慮した最適な順序は何ですか？
+- 段階的リリース（フェーズ分け）は可能ですか？
+- リスクを最小化する実装順序は何ですか？
+
+**2. どのファイルを修正・新規作成しますか？**
+- 新規作成が必要なファイルは何ですか？
+- 修正が必要な既存ファイルは何ですか？
+- 影響を受ける可能性があるファイルは何ですか？
+
+**3. テスト戦略はどのように設計しますか？**
+- どのような種類のテストが必要ですか？
+- テストデータやフィクスチャは何が必要ですか？
+- 既存テストへの影響はありますか？
+
+#### 🎯 計画項目
+
 - **改修対象ファイルの特定**
   - 新規作成が必要なファイル
   - 修正が必要な既存ファイル
@@ -68,8 +153,80 @@ todo_plans作成を段階的に支援し、一貫性のあるプランニング
   - 対策・回避策の検討
   - ロールバック計画の準備
 
+#### ✅ Phase 3 チェックリスト
+
+- [ ] 実装対象ファイルが具体的にリストアップされている
+- [ ] 実装順序が論理的に決定されている
+- [ ] テスト戦略が明確に定義されている
+- [ ] 潜在的リスクと対策が検討されている
+- [ ] 工数見積もりが妥当である
+- [ ] ロールバック計画が準備されている
+
+### Phase 4: 品質保証・レビュー
+
+プランの妥当性と品質を確保します：
+
+#### 📋 ガイダンス質問
+
+**1. プランの完全性は確保されていますか？**
+- すべての要件がカバーされていますか？
+- 見落としている重要な観点はありませんか？
+- 実装手順に漏れはありませんか？
+
+**2. 実現可能性は検証されていますか？**
+- 技術的に実装可能ですか？
+- 必要なリソースは現実的ですか？
+- タイムラインは妥当ですか？
+
+**3. レビュー観点は明確ですか？**
+- どの観点でレビューを受けるべきですか？
+- 誰にレビューを依頼すべきですか？
+- レビューのタイミングはいつが適切ですか？
+
+#### 🔍 品質チェック項目
+
+**完全性チェック**
+- [ ] 要件が具体的に定義されている
+- [ ] 実装手順が詳細に記載されている
+- [ ] テスト計画が含まれている
+- [ ] リスクが特定されている
+- [ ] 成功基準が明確である
+
+**実現可能性チェック**
+- [ ] 技術的に実装可能である
+- [ ] 必要なリソースが明確である
+- [ ] 依存関係が整理されている
+- [ ] タイムラインが現実的である
+- [ ] 制約条件が考慮されている
+
+**品質保証チェック**
+- [ ] コーディング規約への準拠計画がある
+- [ ] テストカバレッジ基準が設定されている
+- [ ] ドキュメント更新計画がある
+- [ ] レビュープロセスが定義されている
+
+#### ✅ Phase 4 チェックリスト
+
+- [ ] プラン全体の完全性が確認されている
+- [ ] 実現可能性が技術的に検証されている
+- [ ] 品質基準が明確に定義されている
+- [ ] レビュー観点と方法が決定されている
+- [ ] リリース準備とデプロイ計画がある
+
 ## プロジェクト固有ガイドライン
 
+### ai-rules プロジェクト固有の考慮事項
+
+#### アーキテクチャ原則
+- **モノレポ構造**: packages/core, packages/extract の責務分離
+- **CLIインターフェースの一貫性**: コマンドオプションの統一
+- **後方互換性の維持**: 既存ユーザーへの影響最小化
+
+#### 開発プロセス
+- **skel/ ディレクトリとの整合性**: 構造変更時の同期必須
+- **テストファーストアプローチ**: TDDによる品質確保
+- **ドキュメントの自動生成対応**: docs-ai/ での記録
+
 ### monorepoワークスペース考慮事項
 
 - **core/commonパッケージの依存ルール**
@@ -94,6 +251,8 @@ todo_plans作成を段階的に支援し、一貫性のあるプランニング
 
 todo_plans作成時に必ず確認する項目：
 
+### 📋 必須確認項目
+
 - [ ] **skel/構造との整合性確認**
   - スケルトンファイルの更新が必要か
   - 構造変更がskel/と一致しているか
@@ -117,11 +276,45 @@ todo_plans作成時に必ず確認する項目：
   - package.jsonの更新内容
   - .npmignoreの確認
 
-## テンプレート活用ガイド
+## プランニングパターン・テンプレート
+
+用途に応じて以下のテンプレートを活用してください：
+
+### 🎯 機能実装パターン
+新機能追加時のプランニングアプローチ
+- Phase 1: ユーザーストーリーと受け入れ基準
+- Phase 2: システムアーキテクチャ設計
+- Phase 3: インクリメンタル実装計画
+- Phase 4: 統合テストと品質保証
+
+### 🔧 リファクタリングパターン
+既存コードの改善・整理時のアプローチ
+- Phase 1: 改善目標と品質基準
+- Phase 2: 影響範囲とリスク分析
+- Phase 3: 段階的リファクタリング計画
+- Phase 4: 回帰テストと検証
+
+### 🐛 バグ修正パターン
+問題解決時のプランニングアプローチ
+- Phase 1: 問題の根本原因特定
+- Phase 2: 修正方法の検討と影響分析
+- Phase 3: 修正実装と検証計画
+- Phase 4: 再発防止策の検討
+
+### 🏗️ アーキテクチャ変更パターン
+大規模な構造変更時のアプローチ
+- Phase 1: 変更の必要性と目標設定
+- Phase 2: 移行戦略とリスク評価
+- Phase 3: 段階的移行計画
+- Phase 4: 安定性確認と運用計画
+
+## 標準テンプレート構造
 
 todo_plans作成時は以下のテンプレート構造を使用してください：
 
 ```markdown
+# [機能名] 実装計画
+
 ## 背景
 
 [現状の課題・改善したい点を具体的に記載]
@@ -130,20 +323,40 @@ todo_plans作成時は以下のテンプレート構造を使用してくださ
 
 [実現したい機能・改善内容を段階的に列挙]
 
+## 要件分析
+- [ ] ユーザーストーリー明確化
+- [ ] 受け入れ基準定義
+- [ ] 技術的制約確認
+
 ## 実装後の挙動に関する説明
 
 出力があるのであれば、それがどのような出力になるか、具体例を表示する。
 
+## アーキテクチャ設計
+- [ ] システム影響範囲特定
+- [ ] インターフェース設計
+- [ ] データモデル設計
+
 ## 改修内容
 
 ### 改修対象ファイル一覧
 
 [影響を受けるファイルを漏れなくリストアップ]
 
+### 実装計画
+- [ ] タスク分解
+- [ ] 依存関係整理
+- [ ] 実装順序決定
+
 ### ファイルごと改修内容
 
 [各ファイルの具体的な変更内容。具体的なコードは書かない。どう修正するかを説明する]
 
+### 品質保証
+- [ ] テスト戦略
+- [ ] レビュー計画
+- [ ] デプロイメント計画
+
 ### テスト時の確認事項
 
 [品質確保のためのチェック項目]

package/artifact/instructions/planning.md

@@ -1,19 +1,200 @@
 ---
 type: planning
+category: methodology
+focus: structured-process
 ---
 
-## コミュニケーションのルール
+# プランニング手法とベストプラクティス
 
-### パスの指定について
+## 段階的プランニング手法
 
+### 4段階プランニングプロセス
+
+効果的なプランニングのために、以下の4段階のプロセスを順次実行します：
+
+#### Phase 1: 要件明確化
+**目的**: プロジェクトの目標と制約を明確化
+**手法**: 
+- 5W1H分析（Why, What, Who, When, Where, How）
+- ステークホルダー分析
+- 制約条件の洗い出し
+- 成功基準の定義
+
+**品質チェック**:
+- [ ] 背景と課題が具体的に説明されている
+- [ ] 成功基準が測定可能である
+- [ ] 制約条件が網羅されている
+
+#### Phase 2: 技術調査・分析  
+**目的**: 実装可能性と技術的リスクの評価
+**手法**:
+- システム影響分析（Impact Analysis）
+- 技術スタック調査
+- アーキテクチャ分析
+- 既存パターンの調査
+
+**品質チェック**:
+- [ ] 影響範囲が特定されている
+- [ ] 技術的選択肢が比較検討されている
+- [ ] リスクが定量的に評価されている
+
+#### Phase 3: 実装計画策定
+**目的**: 具体的で実行可能な計画の作成
+**手法**:
+- WBS（Work Breakdown Structure）
+- 依存関係分析
+- リソース見積もり
+- マイルストーン設定
+
+**品質チェック**:
+- [ ] タスクが適切に分解されている
+- [ ] 実装順序が論理的である
+- [ ] 工数見積もりが現実的である
+
+#### Phase 4: 品質保証・レビュー
+**目的**: プランの妥当性と品質の確保
+**手法**:
+- レビューチェックリスト
+- リスクアセスメント
+- 品質ゲート設定
+- 承認プロセス
+
+**品質チェック**:
+- [ ] プラン全体の一貫性が確保されている
+- [ ] リスクが適切に管理されている
+- [ ] レビュー観点が明確である
+
+## プランニング品質チェック項目
+
+### 完全性チェックリスト
+- [ ] **要件定義の完全性**
+  - すべてのステークホルダーが特定されている
+  - 機能要件・非機能要件が明確である
+  - 制約条件が網羅されている
+  - 前提条件が明記されている
+
+- [ ] **実装計画の詳細度**
+  - タスクが実行可能なレベルまで分解されている
+  - 各タスクの成果物が明確である
+  - 依存関係が正確に把握されている
+  - 工数見積もりが根拠とともに示されている
+
+- [ ] **テスト戦略の包括性**
+  - テストケースの方針が明確である
+  - テストデータの準備方法が決まっている
+  - テスト環境の準備が考慮されている
+  - 受け入れ基準が検証可能である
+
+### 実現可能性チェックリスト
+- [ ] **技術的実現可能性**
+  - 選択技術の成熟度と安定性
+  - チームの技術スキルとの適合性
+  - 既存システムとの整合性
+  - パフォーマンス・スケーラビリティ要件への対応
+
+- [ ] **リソース実現可能性**
+  - 必要な人的リソースの確保可能性
+  - 予算・コスト制約への適合
+  - 時間制約との整合性
+  - 外部依存の調整可能性
+
+- [ ] **運用実現可能性**
+  - 運用・保守体制での対応可能性
+  - 既存運用プロセスとの整合性
+  - 監視・アラート体制の確立可能性
+  - 障害対応・復旧手順の明確性
+
+### リスク評価・管理チェックリスト
+- [ ] **リスク特定の網羅性**
+  - 技術リスク（性能、互換性、セキュリティ等）
+  - プロジェクトリスク（スケジュール、リソース、スコープ等）
+  - ビジネスリスク（市場、法規制、競合等）
+  - 運用リスク（障害、保守、スケーラビリティ等）
+
+- [ ] **リスク対策の具体性**
+  - 各リスクの発生確率と影響度の評価
+  - 具体的な予防策・軽減策
+  - 事象発生時の対応策・復旧策
+  - リスク監視の方法・頻度
+
+## プロジェクトパターン別ベストプラクティス
+
+### CLI機能拡張パターン
+**特徴**: コマンドライン引数、オプション、出力フォーマットの拡張
+**重点確認項目**:
+- [ ] 既存オプションとの互換性維持
+- [ ] ヘルプメッセージの一貫性
+- [ ] エラーメッセージの適切性
+- [ ] 出力フォーマットの統一性
+
+### ライブラリ機能追加パターン  
+**特徴**: APIの拡張、新規モジュールの追加
+**重点確認項目**:
+- [ ] API設計の一貫性
+- [ ] 後方互換性の保証
+- [ ] TypeScript型定義の整合性
+- [ ] パッケージ依存関係の管理
+
+### リファクタリングパターン
+**特徴**: コード品質改善、構造最適化
+**重点確認項目**:
+- [ ] 外部インターフェースの不変性
+- [ ] 既存テストの継続実行可能性
+- [ ] パフォーマンスへの影響評価
+- [ ] 段階的移行の安全性
+
+### バグ修正パターン
+**特徴**: 問題解決、品質向上
+**重点確認項目**:
+- [ ] 根本原因の特定と対策
+- [ ] 再現手順と修正検証
+- [ ] 再発防止策の確立
+- [ ] 関連する潜在問題の調査
+
+## ドキュメント作成計画ガイドライン
+
+### 事前に計画すべきドキュメント
+- [ ] **技術仕様書**: システムの設計・アーキテクチャを記録
+- [ ] **ユーザーマニュアル**: エンドユーザー向けの操作ガイド
+- [ ] **API ドキュメント**: 開発者向けのAPIリファレンス  
+- [ ] **運用ドキュメント**: 保守・運用担当者向けの手順書
+- [ ] **テストドキュメント**: テスト仕様・結果・レポート
+
+### ドキュメント更新計画
+- **作成タイミング**: いつ作成・更新するか
+- **責任者**: 誰が作成・レビューするか
+- **フォーマット**: どの形式で作成するか
+- **配布・共有**: どこに配置・共有するか
+- **メンテナンス**: どのように最新性を保つか
+
+## プランニングワークフロー管理
+
+### todo_plans → change_plans → GitHub Issues の流れ
+
+#### 1. todo_plans段階
+- **目的**: アイデアの整理と初期プランニング
+- **期間**: プロジェクト開始前の計画策定期間
+- **成果物**: 詳細な実装計画書
+- **品質基準**: 4段階プランニングプロセスの完了
+
+#### 2. change_plans段階  
+- **目的**: 実装中の進捗管理と計画調整
+- **期間**: 実装開始から完了まで
+- **成果物**: 実装実績と学習内容の記録
+- **品質基準**: 計画の実行状況と乖離の記録
+
+#### 3. GitHub Issues段階
+- **目的**: チーム内での課題管理と進捗共有
+- **期間**: 公式な課題管理が必要な期間
+- **成果物**: Issue、Pull Request、レビュー記録
+- **品質基準**: ステークホルダーとの情報共有
+
+### コミュニケーションのルール
+
+#### パスの指定について
 相対パスはプロジェクトのルートディレクトリを基準に考えること。
 絶対パスはシステムのルートディレクトリを基準に考えること。
 
-例:
-- `docs/README.md` は、プロジェクトのルートディレクトリからの相対パス指定
-- `./docs/README.md` は、プロジェクトのルートディレクトリからの相対パス指定
-- `/docs/README.md` は、システムのルートディレクトリからのパス指定
-
 ### 根源的なルール
 
 - 機能追加のために不明な点があれば、追加で確認する

package/artifact/instructions/rules/test/environment-independent-paths.md

@@ -0,0 +1,206 @@
+---
+type: test
+category: best-practices
+focus: environment-independence
+---
+
+# 環境非依存テスト実行のためのパス指定ルール
+
+## 概要
+
+テスト実行は、ローカル環境でもCI環境でもどちらでもパスするように気をつける必要があります。パス指定などは絶対パス指定にせず、環境に依存しない書き方をすることが重要です。
+
+## 背景・理由
+
+コーディングするのはAIだけではありません。手動で修正した内容が問題ないかの確認を実施する際に、ローカル環境でテストがこけてしまうと困ります。CI環境とローカル環境の差異によるテスト失敗を防ぐため、環境に依存しないテストコードの作成が必要です。
+
+## 基本原則
+
+### 1. 絶対パスの使用を避ける
+
+- **禁止**: `/home/user/project/test-data/sample.txt` のような絶対パス指定
+- **推奨**: 相対パス や Node.js の `path` モジュールを使った動的パス生成
+
+### 2. 一時ディレクトリの適切な使用
+
+- **推奨**: `os.tmpdir()` と `mkdtemp()` の組み合わせを使用
+- **理由**: OS固有の一時ディレクトリ場所を自動で取得し、ユニークなディレクトリを作成
+
+### 3. プラットフォーム依存機能の適切な処理
+
+- **推奨**: テスト前後で環境変数やプラットフォーム情報を保存・復元
+- **推奨**: プラットフォーム固有の機能は条件分岐で対応
+
+## 実装パターン
+
+### パターン 1: 一時ディレクトリの使用
+
+```typescript
+import { mkdtemp, rm } from "fs/promises";
+import path from "path";
+import os from "os";
+
+describe("Example Test", () => {
+  let testTempDir: string;
+
+  beforeEach(async () => {
+    // 環境に依存しない一時ディレクトリの作成
+    testTempDir = await mkdtemp(path.join(os.tmpdir(), "test-prefix-"));
+  });
+
+  afterEach(async () => {
+    // テスト後のクリーンアップ
+    try {
+      await rm(testTempDir, { recursive: true, force: true });
+    } catch {
+      // エラーは無視（クリーンアップエラーは致命的ではない）
+    }
+  });
+
+  it("should work with temporary files", async () => {
+    const testFile = path.join(testTempDir, "test.txt");
+    // テスト実装...
+  });
+});
+```
+
+### パターン 2: 環境変数の保存・復元
+
+```typescript
+describe("Environment Test", () => {
+  let originalEnv: NodeJS.ProcessEnv;
+  let originalPlatform: string;
+
+  beforeEach(() => {
+    // 元の環境を保存
+    originalEnv = { ...process.env };
+    originalPlatform = process.platform;
+  });
+
+  afterEach(() => {
+    // 環境を復元
+    process.env = originalEnv;
+    Object.defineProperty(process, 'platform', {
+      value: originalPlatform
+    });
+  });
+
+  it("should handle platform differences", () => {
+    // プラットフォーム固有のテスト...
+  });
+});
+```
+
+### パターン 3: 相対パスの適切な解決
+
+```typescript
+import path from "path";
+
+describe("Path Resolution Test", () => {
+  it("should resolve paths correctly", () => {
+    // ❌ 絶対パス（環境依存）
+    // const filePath = "/home/user/project/src/cli.ts";
+    
+    // ✅ 相対パス（環境非依存）
+    const filePath = path.resolve("src/cli.ts");
+    
+    // ✅ パッケージルートからの相対パス
+    const packageRoot = findPackageRoot();
+    const configPath = path.join(packageRoot, "config/settings.json");
+  });
+});
+```
+
+### パターン 4: CLI実行時のパス指定
+
+```typescript
+import { execSync } from "child_process";
+import path from "path";
+
+describe("CLI Test", () => {
+  it("should execute CLI with proper paths", () => {
+    const testSrcDir = path.join(testTempDir, "test-src");
+    
+    // ❌ 絶対パスでCLIファイル指定
+    // execSync(`/home/user/project/dist/cli.js extract --src ${testSrcDir}`);
+    
+    // ✅ 相対パスでCLIファイル指定
+    execSync(`npx tsx src/cli.ts extract --src ${testSrcDir}`, {
+      cwd: process.cwd(), // 現在の作業ディレクトリを明示
+      stdio: "pipe"
+    });
+  });
+});
+```
+
+## 避けるべきパターン
+
+### ❌ 絶対パスの直接指定
+
+```typescript
+// 悪い例: ユーザーディレクトリやシステムパスの直接指定
+const testFile = "/home/runner/project/test/data.txt";
+const configPath = "C:\\Users\\user\\project\\config.json";
+```
+
+### ❌ プラットフォーム固有パスの固定
+
+```typescript
+// 悪い例: パス区切り文字の直接使用
+const filePath = "src/utils/helper.js"; // Windowsでは問題になる可能性
+// 良い例: path.join() の使用
+const filePath = path.join("src", "utils", "helper.js");
+```
+
+### ❌ 環境変数の復元なし
+
+```typescript
+// 悪い例: テスト後に環境を復元しない
+it("should test with modified env", () => {
+  process.env.TEST_VAR = "test-value";
+  // テスト後も環境変数が残り、他のテストに影響する
+});
+```
+
+## クリーンアップのベストプラクティス
+
+### 確実なリソース解放
+
+```typescript
+afterEach(async () => {
+  // ファイルシステムリソースの解放
+  try {
+    await rm(testTempDir, { recursive: true, force: true });
+  } catch {
+    // クリーンアップエラーは無視（テストの失敗より重要ではない）
+  }
+});
+```
+
+### プロセス状態の復元
+
+```typescript
+afterEach(() => {
+  // プロセス状態を確実に復元
+  process.env = originalEnv;
+  process.chdir(originalCwd);
+});
+```
+
+## CI/ローカル共通の注意点
+
+1. **タイムアウト設定**: CI環境では処理が遅い場合があるため、適切なタイムアウト値を設定
+2. **並列実行対応**: 複数のテストが同時実行されても競合しないよう、ユニークな識別子を使用
+3. **権限問題の回避**: 読み取り専用ファイルや権限制限のあるディレクトリを避ける
+4. **パスの長さ制限**: Windows環境での長いパス名制限を考慮
+
+## 検証方法
+
+テストが環境非依存であることを確認する方法：
+
+1. **ローカルでの実行**: `npm test`
+2. **異なるワーキングディレクトリからの実行**: 別のディレクトリからテストを実行
+3. **CI環境での実行**: GitHub Actions や他のCI環境での動作確認
+4. **異なるOS環境**: 可能であれば Windows/Linux/macOS での動作確認
+
+このルールに従うことで、テストはどの環境でも一貫して動作し、開発者の生産性向上とCI/CDパイプラインの安定性を実現できます。

package/dist/cli.js

@@ -10,6 +10,7 @@ import require$$3 from 'node:fs';
 import require$$4 from 'node:process';
 import { fileURLToPath } from 'url';
 import { createHash } from 'crypto';
+import { homedir } from 'os';
 
 /******************************************************************************
 Copyright (c) Microsoft Corporation.
@@ -10042,6 +10043,53 @@ class VariableResolver {
     }
 }
 
+/**
+ * Path expansion utility that supports tilde (~) and environment variable expansion
+ *
+ * Features:
+ * - Tilde expansion: ~/path -> /Users/username/path (Unix-like systems only)
+ * - Environment variable expansion: $HOME/path -> /Users/username/path
+ * - Environment variable expansion: ${VAR}/path -> /value/path
+ * - Complex combinations: ~/projects/${PROJECT_NAME}/file.md
+ *
+ * @param inputPath - Path to expand and resolve
+ * @returns Expanded and resolved absolute path
+ * @throws Error if required environment variables are missing
+ */
+function resolvePath(inputPath) {
+    if (!inputPath || typeof inputPath !== 'string') {
+        throw new Error('Path must be a non-empty string');
+    }
+    let expandedPath = inputPath;
+    // 1. Handle tilde expansion first (Unix-like systems only)
+    if (expandedPath.startsWith('~/')) {
+        // Check if we're on Windows
+        if (process.platform === 'win32') {
+            throw new Error('Tilde (~) expansion is not supported on Windows. Use %USERPROFILE% or environment variables instead.');
+        }
+        const homeDir = homedir();
+        expandedPath = path.join(homeDir, expandedPath.slice(2));
+    }
+    else if (expandedPath === '~') {
+        if (process.platform === 'win32') {
+            throw new Error('Tilde (~) expansion is not supported on Windows. Use %USERPROFILE% or environment variables instead.');
+        }
+        expandedPath = homedir();
+    }
+    // 2. Handle environment variable expansion
+    // Support both $VAR and ${VAR} syntax
+    expandedPath = expandedPath.replace(/\$\{([^}]+)\}|\$([A-Za-z_][A-Za-z0-9_]*)/g, (match, bracedVar, simpleVar) => {
+        const varName = bracedVar || simpleVar;
+        const envValue = process.env[varName];
+        if (envValue === undefined) {
+            throw new Error(`Environment variable '${varName}' is not defined`);
+        }
+        return envValue;
+    });
+    // 3. Resolve to absolute path
+    return path.resolve(expandedPath);
+}
+
 const EXCLUDED_STATS_ATTRS = new Set(["human-instruction", "title"]);
 const MAX_IMPORT_DEPTH = 10;
 /**
@@ -10094,7 +10142,7 @@ class ContentTracker {
      * Checks if the same content has already been written to the file
      */
     hasContent(outputFile, content) {
-        const resolvedFile = path.resolve(outputFile);
+        const resolvedFile = resolvePath(outputFile);
         const contentHash = this.generateContentHash(content);
         const fileHashes = this.fileContentHashes.get(resolvedFile);
         return fileHashes ? fileHashes.has(contentHash) : false;
@@ -10103,7 +10151,7 @@ class ContentTracker {
      * Records that content has been written to a file
      */
     addContent(outputFile, content) {
-        const resolvedFile = path.resolve(outputFile);
+        const resolvedFile = resolvePath(outputFile);
         const contentHash = this.generateContentHash(content);
         if (!this.fileContentHashes.has(resolvedFile)) {
             this.fileContentHashes.set(resolvedFile, new Set());
@@ -10114,7 +10162,7 @@ class ContentTracker {
      * Checks if a file has been written to (for auto-append logic)
      */
     hasFile(outputFile) {
-        const resolvedFile = path.resolve(outputFile);
+        const resolvedFile = resolvePath(outputFile);
         return this.fileContentHashes.has(resolvedFile);
     }
     /**
@@ -10160,8 +10208,56 @@ function resolveDefaultSrcDir(providedSrc) {
     return path.join(packageRoot, 'artifact');
 }
 /**
- * Resolves recipe path, supporting package presets with colon syntax
+ * Resolves output path with baseDir support following priority order:
+ * 1. CLI baseDir option (highest priority)
+ * 2. Import-level baseDir (new priority level)
+ * 3. Recipe config.baseDir
+ * 4. Existing behavior (relative to recipe file or current directory)
  */
+function resolveOutputPath(itemOut, cliBaseDir, importBaseDir, recipeBaseDir, recipePath) {
+    // Check if the itemOut contains environment variables or tilde - if so, try to expand
+    let processedItemOut = itemOut;
+    if (itemOut.includes('$') || itemOut.startsWith('~')) {
+        try {
+            processedItemOut = resolvePath(itemOut);
+            // If expansion resulted in an absolute path, use it as-is (ignore baseDir)
+            if (path.isAbsolute(processedItemOut)) {
+                return processedItemOut;
+            }
+        }
+        catch (error) {
+            // If expansion fails, continue with original itemOut
+            processedItemOut = itemOut;
+        }
+    }
+    // If output path is already absolute, use it as-is (ignore baseDir)
+    if (path.isAbsolute(processedItemOut)) {
+        return processedItemOut;
+    }
+    // Determine effective baseDir with priority: CLI > Import > Recipe > undefined
+    const effectiveBaseDir = cliBaseDir || importBaseDir || recipeBaseDir;
+    if (effectiveBaseDir) {
+        // Use baseDir + relative path
+        const expandedBaseDir = resolvePath(effectiveBaseDir);
+        return path.resolve(expandedBaseDir, processedItemOut);
+    }
+    // Existing behavior: resolve relative to recipe file directory or current directory
+    // For preset files (located in presets/ directory), resolve relative to project root instead
+    let baseDirectory = '.';
+    if (recipePath) {
+        const packageRoot = findPackageRoot();
+        const presetsDir = path.join(packageRoot, 'presets');
+        // If the recipe is in the presets directory, use project root as base
+        if (path.dirname(recipePath) === presetsDir) {
+            baseDirectory = process.cwd();
+        }
+        else {
+            // For regular recipe files, use recipe file directory as base
+            baseDirectory = path.dirname(recipePath);
+        }
+    }
+    return path.resolve(baseDirectory, processedItemOut);
+}
 function resolveRecipePath(recipePath) {
     // If recipe starts with ':', resolve to package preset
     if (recipePath.startsWith(':')) {
@@ -10260,11 +10356,26 @@ async function expandRecipeImports(items, currentPath, debugLogger, visited = ne
                     throw new Error(`Invalid imported recipe file '${importPath}': 'recipe' array not found`);
                 }
                 debugLogger?.log(`Import contains ${importData.recipe.length} items`);
+                // Check if this import item has an import-level baseDir
+                const importLevelBaseDir = item.baseDir;
+                if (importLevelBaseDir) {
+                    debugLogger?.log(`Import has baseDir: ${importLevelBaseDir}`);
+                }
                 // Recursively expand imports in the imported recipe
                 debugLogger?.time(`Expanding nested imports in: ${resolvedImportPath}`);
                 const expandedImported = await expandRecipeImports(importData.recipe, resolvedImportPath, debugLogger, newVisited, imported, depth + 1);
                 debugLogger?.timeEnd(`Expanding nested imports in: ${resolvedImportPath}`);
                 debugLogger?.log(`Nested expansion yielded ${expandedImported.length} items`);
+                // If import has baseDir, tag all expanded items with it
+                if (importLevelBaseDir) {
+                    expandedImported.forEach(expandedItem => {
+                        // Only set _importBaseDir if not already set (to preserve nested import baseDir priority)
+                        if (!expandedItem._importBaseDir) {
+                            expandedItem._importBaseDir = importLevelBaseDir;
+                            debugLogger?.log(`Tagged item '${expandedItem.title || expandedItem.out || 'untitled'}' with import baseDir: ${importLevelBaseDir}`);
+                        }
+                    });
+                }
                 // Add all expanded items from the import
                 expanded.push(...expandedImported);
             }
@@ -10320,6 +10431,7 @@ function setupProgram() {
         .option('--title <title>', 'Title for the output')
         .option('--mode <mode>', 'Write mode: append, prepend, overwrite', 'overwrite')
         .option('--recipe <path>', 'Recipe file path or package preset (e.g., :typescript). Can be specified multiple times or comma-separated.', collectRecipeOptions, [])
+        .option('--base-dir <path>', 'Base directory for output files (supports ~ and environment variable expansion)')
         .option('--vars <variables>', 'Template variables in key=value format (comma-separated)')
         .option('--env-file <path>', 'Path to .env file for template variables')
         .option('--debug', 'Enable debug logging')
@@ -10458,7 +10570,7 @@ async function processContentWithMode(outFile, newContent, mode, debugLogger) {
         return newContent;
     }
     try {
-        const existing = await fs.readFile(path.resolve(outFile), "utf-8");
+        const existing = await fs.readFile(resolvePath(outFile), "utf-8");
         debugLogger?.log(`Existing file found with ${existing.length} characters`);
         if (mode === WriteMode.APPEND) {
             debugLogger?.log('Appending new content to existing content');
@@ -10577,7 +10689,7 @@ async function processSingle(options, debugLogger) {
     debugLogger.time('Content mode processing');
     const finalContent = await processContentWithMode(outFile, contentWithTitle, mode, debugLogger);
     debugLogger.timeEnd('Content mode processing');
-    const resolved = path.resolve(outFile);
+    const resolved = resolvePath(outFile);
     const writer = new MarkdownWriter();
     debugLogger.log(`Writing to output file: ${resolved}`);
     // Build front matter
@@ -10740,15 +10852,20 @@ async function handleExtractCommand(options) {
         await validateRecipeFilesExist(options.recipe);
         if (options.recipe.length === 1) {
             // Single recipe - maintain backward compatibility
-            await processRecipe(options.recipe[0], extractOptions, new ContentTracker(), debugLogger);
+            await processRecipe(options.recipe[0], extractOptions, new ContentTracker(), debugLogger, options.baseDir);
         }
         else {
             // Multiple recipes - process in order with auto-append
-            await processMultipleRecipes(options.recipe, extractOptions, debugLogger);
+            await processMultipleRecipes(options.recipe, extractOptions, debugLogger, options.baseDir);
         }
     }
     else {
         debugLogger.log('Processing single extraction without recipe');
+        // For single extraction, apply baseDir to outFile if provided
+        if (options.baseDir) {
+            extractOptions.outFile = resolveOutputPath(extractOptions.outFile, options.baseDir, undefined, undefined, undefined);
+            debugLogger.log(`Applied CLI baseDir to output file: ${extractOptions.outFile}`);
+        }
         await processSingle(extractOptions, debugLogger);
     }
 }
@@ -10765,13 +10882,13 @@ async function handleStatsCommand(options) {
 /**
  * Processes multiple recipe files in the specified order
  */
-async function processMultipleRecipes(recipePaths, baseOptions, debugLogger) {
+async function processMultipleRecipes(recipePaths, baseOptions, debugLogger, cliBaseDir) {
     const contentTracker = new ContentTracker();
     debugLogger.log(`Processing ${recipePaths.length} recipes in order`);
     for (const recipePath of recipePaths) {
         try {
             debugLogger.log(`Starting processing of recipe: ${recipePath}`);
-            await processRecipe(recipePath, baseOptions, contentTracker, debugLogger);
+            await processRecipe(recipePath, baseOptions, contentTracker, debugLogger, cliBaseDir);
             debugLogger.log(`Completed processing of recipe: ${recipePath}`);
         }
         catch (error) {
@@ -10784,10 +10901,91 @@ async function processMultipleRecipes(recipePaths, baseOptions, debugLogger) {
         }
     }
 }
+/**
+ * Reads template files and extracts frontmatter for inheritance
+ */
+async function loadTemplateFrontmatter(srcDir, types, languages, attrFilters, debugLogger) {
+    debugLogger?.log('Loading template frontmatter for inheritance');
+    const templateFiles = await loadAndFilterFiles(srcDir, types, languages, attrFilters, debugLogger);
+    debugLogger?.log(`Found ${templateFiles.length} template files for frontmatter inheritance`);
+    return templateFiles.map(file => file.attrs);
+}
+/**
+ * Merges frontmatter values from multiple templates according to merge rules:
+ * - Strings: concatenate with newlines
+ * - Arrays: combine all elements
+ * - Objects: later values overwrite
+ */
+function mergeTemplateFrontmatterValues(templateFrontmatters, fieldName) {
+    const values = templateFrontmatters
+        .map(fm => fm[fieldName])
+        .filter(val => val !== undefined && val !== null);
+    if (values.length === 0) {
+        return undefined;
+    }
+    if (values.length === 1) {
+        return values[0];
+    }
+    // Check if all values are strings
+    if (values.every(val => typeof val === 'string')) {
+        return values.join('\n');
+    }
+    // Check if all values are arrays
+    if (values.every(val => Array.isArray(val))) {
+        return values.flat();
+    }
+    // For objects and mixed types, use the last value
+    return values[values.length - 1];
+}
+/**
+ * Processes @ syntax in frontmatter to inherit from template files
+ */
+async function processFrontmatterInheritance(frontmatter, srcDir, types, languages, attrFilters, debugLogger) {
+    if (!frontmatter || typeof frontmatter !== 'object') {
+        return {};
+    }
+    const result = {};
+    const inheritanceFields = [];
+    // Separate inheritance fields (@ syntax) from regular fields
+    for (const [key, value] of Object.entries(frontmatter)) {
+        if (key.startsWith('@') && value === true) {
+            inheritanceFields.push(key.slice(1)); // Remove @ prefix
+            debugLogger?.log(`Found inheritance field: ${key} -> ${key.slice(1)}`);
+        }
+        else {
+            result[key] = value;
+        }
+    }
+    // If no inheritance fields, return as-is
+    if (inheritanceFields.length === 0) {
+        debugLogger?.log('No frontmatter inheritance fields found');
+        return result;
+    }
+    debugLogger?.log(`Processing ${inheritanceFields.length} inheritance fields:`, inheritanceFields);
+    // Load template frontmatters
+    const templateFrontmatters = await loadTemplateFrontmatter(srcDir, types, languages, attrFilters, debugLogger);
+    if (templateFrontmatters.length === 0) {
+        debugLogger?.log('No template files found for inheritance');
+        return result;
+    }
+    // Process each inheritance field
+    for (const fieldName of inheritanceFields) {
+        const mergedValue = mergeTemplateFrontmatterValues(templateFrontmatters, fieldName);
+        if (mergedValue !== undefined) {
+            result[fieldName] = mergedValue;
+            debugLogger?.log(`Inherited field ${fieldName}:`, mergedValue);
+        }
+        else {
+            debugLogger?.log(`No value found for inherited field ${fieldName} in templates`);
+        }
+    }
+    debugLogger?.log('Frontmatter after inheritance processing:', Object.keys(result));
+    return result;
+}
 /**
  * Processes a recipe file with multiple extract operations
  */
-async function processRecipe(recipePath, baseOptions, contentTracker, debugLogger) {
+async function processRecipe(recipePath, baseOptions, contentTracker, debugLogger, cliBaseDir) {
     const resolvedPath = resolveRecipePath(recipePath);
     debugLogger?.log(`Processing recipe at path: ${resolvedPath}`);
     try {
@@ -10799,6 +10997,9 @@ async function processRecipe(recipePath, baseOptions, contentTracker, debugLogge
             throw new Error("Invalid recipe file: 'recipe' array not found");
         }
         debugLogger?.log(`Recipe contains ${data.recipe.length} items`);
+        // Read recipe config for baseDir
+        const recipeBaseDir = data.config?.baseDir;
+        debugLogger?.log('Recipe config:', { baseDir: recipeBaseDir });
         // Expand any imports in the recipe
         debugLogger?.time('Recipe import expansion');
         const expandedRecipe = await expandRecipeImports(data.recipe, resolvedPath, debugLogger);
@@ -10814,8 +11015,13 @@ async function processRecipe(recipePath, baseOptions, contentTracker, debugLogge
                 language: item.language,
                 mode: item.mode
             });
-            const outputFile = item.out || baseOptions.outFile;
-            const resolvedOutputFile = path.resolve(outputFile);
+            const itemOut = item.out || baseOptions.outFile;
+            const outputFile = resolveOutputPath(itemOut, cliBaseDir, item._importBaseDir, recipeBaseDir, resolvedPath);
+            debugLogger?.log(`Resolved output path: ${itemOut} -> ${outputFile}`, {
+                cliBaseDir,
+                importBaseDir: item._importBaseDir,
+                recipeBaseDir
+            });
             // Generate the content that would be written to check for duplicates
             const { srcDir, types, languages, attrFilters, title, attr, vars, envFile } = baseOptions;
             const itemTypes = item.type ? parseCommaSeparated(item.type) : types;
@@ -10867,7 +11073,7 @@ async function processRecipe(recipePath, baseOptions, contentTracker, debugLogge
                 effectiveMode = parseWriteMode(item.mode);
                 debugLogger?.log(`Using explicit mode from recipe item: ${effectiveMode}`);
             }
-            else if (localTracker.hasFile(resolvedOutputFile)) {
+            else if (localTracker.hasFile(outputFile)) {
                 // Auto-append for duplicate output files when no explicit mode
                 effectiveMode = WriteMode.APPEND;
                 debugLogger?.log(`Auto-appending due to existing output file: ${effectiveMode}`);
@@ -10875,6 +11081,10 @@ async function processRecipe(recipePath, baseOptions, contentTracker, debugLogge
             else {
                 debugLogger?.log(`Using base mode: ${effectiveMode}`);
             }
+            // Process frontmatter inheritance (@ syntax)
+            debugLogger?.time(`Frontmatter inheritance processing for item ${index + 1}`);
+            const processedFrontmatter = await processFrontmatterInheritance(item.frontmatter, baseOptions.srcDir, itemTypes, itemLanguages, combinedAttrFilters, debugLogger);
+            debugLogger?.timeEnd(`Frontmatter inheritance processing for item ${index + 1}`);
             const options = {
                 srcDir: baseOptions.srcDir,
                 outFile: outputFile,
@@ -10883,7 +11093,7 @@ async function processRecipe(recipePath, baseOptions, contentTracker, debugLogge
                 attrFilters: combinedAttrFilters,
                 title: itemTitle,
                 mode: effectiveMode,
-                attr: item.frontmatter,
+                attr: processedFrontmatter,
                 debug: baseOptions.debug,
                 vars: itemVars,
                 envFile: envFile,

package/dist/utils/pathExpansion.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Path expansion utility that supports tilde (~) and environment variable expansion
+ *
+ * Features:
+ * - Tilde expansion: ~/path -> /Users/username/path (Unix-like systems only)
+ * - Environment variable expansion: $HOME/path -> /Users/username/path
+ * - Environment variable expansion: ${VAR}/path -> /value/path
+ * - Complex combinations: ~/projects/${PROJECT_NAME}/file.md
+ *
+ * @param inputPath - Path to expand and resolve
+ * @returns Expanded and resolved absolute path
+ * @throws Error if required environment variables are missing
+ */
+export declare function resolvePath(inputPath: string): string;
+/**
+ * Safely resolve a path with environment variable expansion, returning the original path
+ * if expansion fails (useful for optional environment variables)
+ *
+ * @param inputPath - Path to expand and resolve
+ * @param fallbackToOriginal - If true, return path.resolve(inputPath) when expansion fails
+ * @returns Expanded and resolved absolute path, or resolved original path on failure
+ */
+export declare function resolvePathSafe(inputPath: string, fallbackToOriginal?: boolean): string;
+//# sourceMappingURL=pathExpansion.d.ts.map

package/dist/utils/pathExpansion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pathExpansion.d.ts","sourceRoot":"","sources":["../../src/utils/pathExpansion.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAuCrD;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,kBAAkB,GAAE,OAAc,GAAG,MAAM,CAS7F"}

package/dist/utils/pathExpansion.js

@@ -0,0 +1,67 @@
+import { homedir } from "os";
+import path from "path";
+/**
+ * Path expansion utility that supports tilde (~) and environment variable expansion
+ *
+ * Features:
+ * - Tilde expansion: ~/path -> /Users/username/path (Unix-like systems only)
+ * - Environment variable expansion: $HOME/path -> /Users/username/path
+ * - Environment variable expansion: ${VAR}/path -> /value/path
+ * - Complex combinations: ~/projects/${PROJECT_NAME}/file.md
+ *
+ * @param inputPath - Path to expand and resolve
+ * @returns Expanded and resolved absolute path
+ * @throws Error if required environment variables are missing
+ */
+export function resolvePath(inputPath) {
+    if (!inputPath || typeof inputPath !== 'string') {
+        throw new Error('Path must be a non-empty string');
+    }
+    let expandedPath = inputPath;
+    // 1. Handle tilde expansion first (Unix-like systems only)
+    if (expandedPath.startsWith('~/')) {
+        // Check if we're on Windows
+        if (process.platform === 'win32') {
+            throw new Error('Tilde (~) expansion is not supported on Windows. Use %USERPROFILE% or environment variables instead.');
+        }
+        const homeDir = homedir();
+        expandedPath = path.join(homeDir, expandedPath.slice(2));
+    }
+    else if (expandedPath === '~') {
+        if (process.platform === 'win32') {
+            throw new Error('Tilde (~) expansion is not supported on Windows. Use %USERPROFILE% or environment variables instead.');
+        }
+        expandedPath = homedir();
+    }
+    // 2. Handle environment variable expansion
+    // Support both $VAR and ${VAR} syntax
+    expandedPath = expandedPath.replace(/\$\{([^}]+)\}|\$([A-Za-z_][A-Za-z0-9_]*)/g, (match, bracedVar, simpleVar) => {
+        const varName = bracedVar || simpleVar;
+        const envValue = process.env[varName];
+        if (envValue === undefined) {
+            throw new Error(`Environment variable '${varName}' is not defined`);
+        }
+        return envValue;
+    });
+    // 3. Resolve to absolute path
+    return path.resolve(expandedPath);
+}
+/**
+ * Safely resolve a path with environment variable expansion, returning the original path
+ * if expansion fails (useful for optional environment variables)
+ *
+ * @param inputPath - Path to expand and resolve
+ * @param fallbackToOriginal - If true, return path.resolve(inputPath) when expansion fails
+ * @returns Expanded and resolved absolute path, or resolved original path on failure
+ */
+export function resolvePathSafe(inputPath, fallbackToOriginal = true) {
+    try {
+        return resolvePath(inputPath);
+    }
+    catch (error) {
+        if (fallbackToOriginal) {
+            return path.resolve(inputPath);
+        }
+        throw error;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aramassa/ai-rules",
-  "version": "0.1.1-npmjs.20250910072942",
+  "version": "0.1.2",
   "description": "This repository collects guidelines and instructions for developing AI agents. It contains documents covering communication rules, coding standards, testing strategies, and general operational practices.",
   "workspaces": [
     "packages/extract",

package/presets/chatmodes.yaml

@@ -1,25 +1,11 @@
+config:
+  baseDir: .github/chatmodes
 recipe:
   - title: Instruction Improve Chatmode
     frontmatter:
-      description: |
-        Chatmode for improving the project instructions through retrospective analysis.
-        Provides structured approach to analyzing past tasks and converting insights into GitHub issues.
-        Includes comprehensive GitHub integration tools for issue and pull request management.
-      tools:
-        [
-          "changes",
-          "create_issue",
-          "list_issues",
-          "get_issue",
-          "get_pull_request",
-          "create_pull_request",
-          "list_pull_requests",
-          "get_pull_request_comments",
-          "get_pull_request_reviews",
-          "search_issues",
-          "search_pull_requests",
-        ]
-    out: ./.github/chatmodes/Instruction Improve.chatmode.md
+      "@description": true
+      "@tools": true
+    out: Instruction Improve.chatmode.md
     type: chatmode
     filters:
       chatmode: instruction-improve
@@ -27,38 +13,9 @@ recipe:
       INSTRUCTION_GITHUB_REPO: https://github.com/Aramassa/ai-rules
   - title: Planning Chatmode
     frontmatter:
-      description: |
-        Chatmode for supporting todo_plans creation with structured planning process.
-        Provides phase-based guidance for requirement clarification, technical investigation, and implementation planning.
-      tools:
-        [
-          "changes",
-          "searchResults",
-          "editFiles",
-          "search",
-          "add_issue_comment",
-          "add_sub_issue",
-          "assign_copilot_to_issue",
-          "create_issue",
-          "create_pull_request_with_copilot",
-          "get_code_scanning_alert",
-          "get_discussion",
-          "get_discussion_comments",
-          "get_issue_comments",
-          "get_pull_request",
-          "get_pull_request_diff",
-          "get_pull_request_files",
-          "list_commits",
-          "list_issues",
-          "list_pull_requests",
-          "search_code",
-          "search_issues",
-          "search_pull_requests",
-          "search_repositories",
-          "update_issue",
-          "update_pull_request",
-        ]
-    out: ./.github/chatmodes/Planning.chatmode.md
+      "@description": true
+      "@tools": true
+    out: Planning.chatmode.md
     type: chatmode
     filters:
       chatmode: planning