musubix 1.0.1 → 1.0.3

package/.github/skills/musubix-sdd-workflow/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: musubix-sdd-workflow
+description: Guide for MUSUBIX SDD (Specification-Driven Development) workflow. Use this when asked to develop features using MUSUBIX methodology, create requirements, designs, or implement code following the 9 constitutional articles.
+license: MIT
+---
+
+# MUSUBIX SDD Workflow Skill
+
+This skill guides you through the complete SDD workflow for MUSUBIX projects.
+
+## Prerequisites
+
+Before starting any development task:
+
+1. Read `steering/` directory for project context
+2. Check `steering/rules/constitution.md` for the 9 constitutional articles
+3. Review existing specs in `storage/specs/`
+
+## Workflow Steps
+
+### Step 1: Requirements Phase (Article IV - EARS Format)
+
+Create requirements using EARS patterns:
+
+```markdown
+# REQ-[CATEGORY]-[NUMBER]
+
+**種別**: [UBIQUITOUS|EVENT-DRIVEN|STATE-DRIVEN|UNWANTED|OPTIONAL]
+**優先度**: [P0|P1|P2]
+
+**要件**:
+[EARS形式の要件文]
+
+**トレーサビリティ**: DES-XXX, TEST-XXX
+```
+
+EARS Patterns:
+- **Ubiquitous**: `THE [system] SHALL [requirement]`
+- **Event-driven**: `WHEN [event], THE [system] SHALL [response]`
+- **State-driven**: `WHILE [state], THE [system] SHALL [response]`
+- **Unwanted**: `THE [system] SHALL NOT [behavior]`
+- **Optional**: `IF [condition], THEN THE [system] SHALL [response]`
+
+### Step 2: Design Phase (Article VII - Design Patterns)
+
+Create C4 model design documents:
+
+1. **Context Level**: System boundaries and external actors
+2. **Container Level**: Technology choices and container composition
+3. **Component Level**: Internal structure of containers
+4. **Code Level**: Implementation details
+
+Design document template:
+```markdown
+# DES-[CATEGORY]-[NUMBER]
+
+## トレーサビリティ
+- 要件: REQ-XXX
+
+## C4モデル
+### Level 2: Container
+[PlantUML diagram]
+
+## コンポーネント設計
+[Component details]
+```
+
+### Step 3: Task Generation
+
+Generate implementation tasks from design:
+
+```markdown
+# TSK-[CATEGORY]-[NUMBER]
+
+## 関連設計: DES-XXX
+## 関連要件: REQ-XXX
+
+## タスク内容
+[Implementation task description]
+
+## 受入基準
+- [ ] Criterion 1
+- [ ] Criterion 2
+```
+
+### Step 4: Implementation (Article III - Test-First)
+
+Follow Red-Green-Blue cycle:
+
+1. **Red**: Write failing test first
+2. **Green**: Write minimal code to pass
+3. **Blue**: Refactor while keeping tests green
+
+### Step 5: Traceability Validation (Article V)
+
+Ensure 100% traceability:
+```
+REQ-* → DES-* → TSK-* → Code → Test
+```
+
+Add requirement IDs in code comments:
+```typescript
+/**
+ * @see REQ-INT-001 - Neuro-Symbolic Integration
+ */
+```
+
+## CLI Commands
+
+```bash
+# Requirements
+npx musubix requirements analyze <file>
+npx musubix requirements validate <file>
+
+# Design
+npx musubix design generate <file>
+npx musubix design patterns <context>
+
+# Code Generation
+npx musubix codegen generate <file>
+
+# Traceability
+npx musubix trace matrix
+npx musubix trace validate
+```
+
+## Constitutional Articles Checklist
+
+- [ ] **Article I**: Library-First - Is this a standalone library?
+- [ ] **Article II**: CLI Interface - Does it expose CLI?
+- [ ] **Article III**: Test-First - Are tests written first?
+- [ ] **Article IV**: EARS Format - Are requirements in EARS?
+- [ ] **Article V**: Traceability - Is everything traceable?
+- [ ] **Article VI**: Project Memory - Did you check steering/?
+- [ ] **Article VII**: Design Patterns - Are patterns documented?
+- [ ] **Article VIII**: Decision Records - Is ADR created?
+- [ ] **Article IX**: Quality Gates - Are quality checks passed?

package/AGENTS.md

@@ -0,0 +1,286 @@
+# MUSUBIX - Neuro-Symbolic AI Integration System
+
+> **AI Coding Agent向け**: このファイルはAIエージェント（GitHub Copilot、Claude等）がMUSUBIXプロジェクトを理解するためのガイドです。
+
+## 🎯 プロジェクト概要
+
+**MUSUBIX**は、**Neural（LLM）** と **Symbolic（Knowledge Graph）** 推論を統合した次世代AIコーディングシステムです。MUSUBI SDD方法論とYATA知識グラフ推論を組み合わせ、高品質なソフトウェア開発を支援します。
+
+| 項目 | 詳細 |
+|------|------|
+| **バージョン** | 1.0.0 |
+| **言語** | TypeScript |
+| **ランタイム** | Node.js >= 20.0.0 |
+| **パッケージマネージャ** | npm >= 10.0.0 |
+| **ビルドシステム** | モノレポ（npm workspaces） |
+| **テストフレームワーク** | Vitest |
+
+---
+
+## 📦 アーキテクチャ
+
+### パッケージ構成
+
+```
+packages/
+├── core/           # @nahisaho/musubix-core
+├── mcp-server/     # @nahisaho/musubix-mcp-server  
+└── yata-client/    # @nahisaho/musubix-yata-client
+```
+
+| パッケージ | npm | 役割 |
+|-----------|-----|------|
+| `packages/core/` | `@nahisaho/musubix-core` | コアライブラリ - CLI、EARS検証、コード生成、設計パターン |
+| `packages/mcp-server/` | `@nahisaho/musubix-mcp-server` | MCPサーバー - 9ツール、3プロンプト |
+| `packages/yata-client/` | `@nahisaho/musubix-yata-client` | YATAクライアント - 知識グラフ連携 |
+
+### Core パッケージモジュール
+
+```
+packages/core/src/
+├── auth/           # 認証・認可
+├── cli/            # CLIインターフェース
+├── codegen/        # コード生成・解析
+├── design/         # 設計パターン・C4モデル
+├── error/          # エラーハンドリング
+├── explanation/    # 説明生成・可視化
+├── requirements/   # 要件分析・分解
+├── traceability/   # トレーサビリティ
+├── types/          # 型定義
+├── utils/          # ユーティリティ
+└── validators/     # EARS検証
+```
+
+---
+
+## 🛠️ CLI コマンド
+
+```bash
+# プロジェクト初期化
+npx musubix init [path] [--name <name>] [--force]
+
+# 要件分析（EARS形式）
+npx musubix requirements analyze <file>    # 自然言語 → EARS変換
+npx musubix requirements validate <file>   # EARS構文検証
+npx musubix requirements map <file>        # オントロジーマッピング
+npx musubix requirements search <query>    # 関連要件検索
+
+# 設計生成
+npx musubix design generate <file>         # 要件から設計生成
+npx musubix design patterns <context>      # パターン検出
+npx musubix design validate <file>         # SOLID準拠検証
+npx musubix design c4 <file>               # C4ダイアグラム生成
+npx musubix design adr <decision>          # ADR生成
+
+# コード生成
+npx musubix codegen generate <file>        # 設計からコード生成
+npx musubix codegen analyze <file>         # 静的解析
+npx musubix codegen security <path>        # セキュリティスキャン
+
+# テスト
+npx musubix test generate <file>           # テスト生成
+npx musubix test coverage <dir>            # カバレッジ測定
+
+# トレーサビリティ
+npx musubix trace matrix                   # トレーサビリティマトリクス
+npx musubix trace impact <id>              # 影響分析
+npx musubix trace validate                 # リンク検証
+
+# 説明生成
+npx musubix explain why <id>               # 決定理由の説明
+npx musubix explain graph <id>             # 推論グラフ生成
+
+# ヘルプ
+npx musubix --help
+npx musubix help <command>
+```
+
+---
+
+## 🔌 MCP Server
+
+### 起動方法
+
+```bash
+npx @nahisaho/musubix-mcp-server
+npx musubix-mcp --transport stdio
+```
+
+### ツール一覧（9ツール）
+
+| ツール名 | 説明 |
+|---------|------|
+| `sdd_create_requirements` | EARS形式の要件ドキュメント作成 |
+| `sdd_validate_requirements` | 要件のEARS検証・憲法準拠チェック |
+| `sdd_create_design` | C4モデル設計ドキュメント作成 |
+| `sdd_validate_design` | 設計の要件トレーサビリティ検証 |
+| `sdd_create_tasks` | 設計から実装タスク生成 |
+| `sdd_query_knowledge` | YATA知識グラフへのクエリ |
+| `sdd_update_knowledge` | 知識グラフの更新 |
+| `sdd_validate_constitution` | 9憲法条項への準拠検証 |
+| `sdd_validate_traceability` | 要件↔設計↔タスクのトレーサビリティ検証 |
+
+### プロンプト一覧（3プロンプト）
+
+| プロンプト名 | 説明 |
+|-------------|------|
+| `sdd_requirements_analysis` | 機能説明からEARS形式要件を生成 |
+| `sdd_requirements_review` | 要件の完全性・憲法準拠レビュー |
+| `sdd_design_generation` | 要件からC4モデル設計を生成 |
+
+---
+
+## 📋 9憲法条項（Constitutional Articles）
+
+すべての開発活動を統治する不変のルールです。
+
+| 条項 | 名称 | 概要 |
+|-----|------|------|
+| **I** | Library-First | 機能は独立ライブラリとして開始 |
+| **II** | CLI Interface | すべてのライブラリはCLI公開必須 |
+| **III** | Test-First | Red-Green-Blueサイクルでテスト先行 |
+| **IV** | EARS Format | 要件はEARS形式で記述 |
+| **V** | Traceability | 要件↔設計↔コード↔テストの100%追跡 |
+| **VI** | Project Memory | steering/を参照してから決定 |
+| **VII** | Design Patterns | 設計パターン適用の文書化 |
+| **VIII** | Decision Records | すべての決定をADRで記録 |
+| **IX** | Quality Gates | フェーズ移行前の品質検証 |
+
+**詳細**: [steering/rules/constitution.md](steering/rules/constitution.md)
+
+---
+
+## 📁 プロジェクトメモリ（Steering）
+
+AIエージェントは決定前に必ずこれらのファイルを参照してください。
+
+| ファイル | 内容 |
+|---------|------|
+| `steering/structure.ja.md` | アーキテクチャパターン、レイヤー構造 |
+| `steering/tech.ja.md` | 技術スタック（TypeScript, Node.js 20+） |
+| `steering/product.ja.md` | プロダクトコンテキスト |
+| `steering/rules/constitution.md` | 9憲法条項 |
+| `steering/project.yml` | プロジェクト設定 |
+
+---
+
+## 📂 ストレージ構造
+
+| パス | 内容 |
+|-----|------|
+| `storage/specs/` | 要件(REQ-*)、設計(DES-*)、タスク(TSK-*) |
+| `storage/design/` | 設計ドキュメント、C4ダイアグラム |
+| `storage/traceability/` | トレーサビリティマトリクス |
+| `storage/reviews/` | コードレビュー、検証結果 |
+| `storage/changes/` | 変更履歴 |
+| `storage/archive/` | アーカイブ |
+
+---
+
+## 🧪 開発コマンド
+
+```bash
+# 依存関係インストール
+npm install
+
+# 全パッケージビルド
+npm run build
+
+# テスト実行
+npm run test              # 全テスト
+npm run test:unit         # ユニットテスト
+npm run test:integration  # 統合テスト
+npm run test:coverage     # カバレッジ計測
+
+# コード品質
+npm run lint              # ESLint
+npm run lint:fix          # ESLint 自動修正
+npm run typecheck         # TypeScript型チェック
+
+# クリーンアップ
+npm run clean
+```
+
+---
+
+## 🔑 主要機能
+
+### 1. Neuro-Symbolic統合（REQ-INT-001〜003準拠）
+- **Neural（LLM）**: 創造的なコード生成、自然言語理解
+- **Symbolic（YATA）**: 知識グラフによる精密な推論、一貫性検証
+- **信頼度評価ルール** (REQ-INT-002):
+  | シンボリック結果 | ニューラル信頼度 | 最終決定 |
+  |-----------------|-----------------|---------|
+  | invalid | - | ニューラル結果を棄却 |
+  | valid | ≥0.8 | ニューラル結果を採用 |
+  | valid | <0.8 | シンボリック結果を優先 |
+
+### 2. EARS要件分析
+5つのEARSパターンで要件を形式化（REQ-RA-001準拠）：
+
+| パターン | 構文 | 用途 |
+|---------|------|------|
+| Ubiquitous | `THE [system] SHALL [requirement]` | システムが常に満たすべき要件 |
+| Event-driven | `WHEN [event], THE [system] SHALL [response]` | 特定イベント発生時の要件 |
+| State-driven | `WHILE [state], THE [system] SHALL [response]` | 特定状態における要件 |
+| Unwanted | `THE [system] SHALL NOT [behavior]` | 回避すべき動作の要件 |
+| Optional | `IF [condition], THEN THE [system] SHALL [response]` | 条件付き要件 |
+
+**要件総数**: 41要件（REQ-MUSUBIX-001定義）  
+**優先度**: P0（必須）、P1（重要）、P2（任意）
+
+### 3. C4モデル設計
+4つのレベルで設計を構造化：
+- **Context**: システム境界と外部アクター
+- **Container**: 技術選択とコンテナ構成
+- **Component**: コンテナ内部構造
+- **Code**: 実装詳細
+
+### 4. 完全なトレーサビリティ
+```
+要件(REQ-*) → 設計(DES-*) → タスク(TSK-*) → コード → テスト
+```
+
+---
+
+## 📚 ドキュメント
+
+| ドキュメント | 説明 |
+|-------------|------|
+| [docs/INSTALL-GUIDE.md](docs/INSTALL-GUIDE.md) | インストールガイド |
+| [docs/USER-GUIDE.md](docs/USER-GUIDE.md) | ユーザーガイド |
+| [docs/API-REFERENCE.md](docs/API-REFERENCE.md) | APIリファレンス |
+| [README.md](README.md) | 英語版README |
+| [README.ja.md](README.ja.md) | 日本語版README |
+
+---
+
+## 🤝 AI Agent向けガイドライン
+
+### コード生成時の注意点
+
+1. **憲法条項の遵守**: 9条項を必ず確認
+2. **steering/参照**: 決定前にproject memoryを確認
+3. **EARS形式**: 要件は必ずEARS形式で記述
+4. **トレーサビリティ**: コードコメントに要件IDを記載
+5. **テスト先行**: Red-Green-Blueサイクルを遵守
+6. **モノレポ構造**: パッケージ間の依存関係に注意
+
+### 推奨ワークフロー
+
+```
+1. steering/ を読む
+2. 要件をEARS形式で定義
+3. C4モデルで設計
+4. テストを先に書く（Red）
+5. 最小限のコードで実装（Green）
+6. リファクタリング（Blue）
+7. トレーサビリティを検証
+```
+
+---
+
+**Agent**: GitHub Copilot / Claude
+**Last Updated**: 2026-01-02
+**Version**: 1.0.0
+**Repository**: https://github.com/nahisaho/MUSUBIX