musubix 2.3.7 → 2.4.1

package/.github/skills/musubix-adr-generation/SKILL.md

@@ -0,0 +1,209 @@
+---
+name: musubix-adr-generation
+description: Guide for creating Architecture Decision Records (ADRs). Use this when asked to document architecture decisions, technology choices, or design trade-offs.
+license: MIT
+---
+
+# MUSUBIX ADR Generation Skill
+
+This skill guides you through creating Architecture Decision Records following **Article VIII - Decision Records**.
+
+## Overview
+
+An **ADR (Architecture Decision Record)** documents significant architectural decisions with their context and consequences.
+
+## ADR Template
+
+```markdown
+# ADR-[NUMBER]: [Decision Title]
+
+## ステータス
+[Proposed | Accepted | Deprecated | Superseded by ADR-XXX]
+
+## コンテキスト
+[What is the issue that we're seeing that is motivating this decision?]
+
+## 決定
+[What is the change that we're proposing and/or doing?]
+
+## 選択肢
+
+### Option 1: [Name]
+**メリット:**
+- [Advantage 1]
+- [Advantage 2]
+
+**デメリット:**
+- [Disadvantage 1]
+- [Disadvantage 2]
+
+### Option 2: [Name]
+**メリット:**
+- [Advantage 1]
+
+**デメリット:**
+- [Disadvantage 1]
+
+## 結果
+[What becomes easier or more difficult to do because of this change?]
+
+## トレーサビリティ
+- 関連要件: REQ-XXX-NNN
+- 関連設計: DES-XXX-NNN
+```
+
+## Common ADR Topics
+
+### 1. Technology Selection
+
+```markdown
+# ADR-001: Use TypeScript for Backend
+
+## コンテキスト
+We need to choose a programming language for the backend API.
+
+## 決定
+We will use TypeScript with Node.js.
+
+## 選択肢
+
+### Option 1: TypeScript + Node.js
+**メリット:**
+- Type safety reduces runtime errors
+- Same language as frontend (code sharing)
+- Large ecosystem (npm)
+- Strong async/await support
+
+**デメリット:**
+- Slower than compiled languages
+- Type definitions not always available
+
+### Option 2: Go
+**メリット:**
+- High performance
+- Strong concurrency support
+
+**デメリット:**
+- Different language from frontend
+- Smaller ecosystem for web
+
+## 結果
+- Frontend/backend code sharing enabled
+- Need to maintain TypeScript configuration
+- Team can use consistent tooling
+```
+
+### 2. Architecture Pattern
+
+```markdown
+# ADR-002: Layered Architecture with DDD
+
+## コンテキスト
+We need to define the overall architecture pattern.
+
+## 決定
+We will use Layered Architecture with Domain-Driven Design principles.
+
+## 選択肢
+
+### Option 1: Layered Architecture
+- Presentation → Application → Domain → Infrastructure
+
+### Option 2: Hexagonal Architecture
+- Ports and Adapters pattern
+
+## 結果
+- Clear separation of concerns
+- Domain logic isolated from infrastructure
+- Easier testing with dependency injection
+```
+
+### 3. Database Selection
+
+```markdown
+# ADR-003: Use PostgreSQL for Primary Database
+
+## コンテキスト
+We need a primary data store for the application.
+
+## 決定
+PostgreSQL will be our primary database.
+
+## 選択肢
+
+### Option 1: PostgreSQL
+**メリット:**
+- ACID compliance
+- JSON support
+- Strong ecosystem
+- Free and open source
+
+### Option 2: MongoDB
+**メリット:**
+- Schema flexibility
+- Horizontal scaling
+
+**デメリット:**
+- Eventual consistency concerns
+- Complex transactions
+
+## 結果
+- Reliable transactional data storage
+- Need to manage schema migrations
+- Can use JSON columns for flexibility
+```
+
+## CLI Commands
+
+```bash
+# Generate ADR from decision description
+npx musubix design adr "Use React for frontend"
+
+# List all ADRs
+ls storage/design/adr/
+
+# Generate ADR interactively
+npx musubix design adr --interactive
+```
+
+## ADR Numbering
+
+ADRs are numbered sequentially:
+- ADR-001, ADR-002, ADR-003...
+
+Never renumber existing ADRs. If an ADR is superseded, mark it as such and reference the new ADR.
+
+## Storage Location
+
+```
+storage/design/adr/
+├── ADR-001-typescript-backend.md
+├── ADR-002-layered-architecture.md
+├── ADR-003-postgresql-database.md
+└── index.md  # ADR index
+```
+
+## ADR Index Template
+
+```markdown
+# Architecture Decision Records
+
+| ADR | Title | Status | Date |
+|-----|-------|--------|------|
+| [ADR-001](./ADR-001-typescript-backend.md) | Use TypeScript for Backend | Accepted | 2026-01-04 |
+| [ADR-002](./ADR-002-layered-architecture.md) | Layered Architecture | Accepted | 2026-01-04 |
+```
+
+## When to Write an ADR
+
+- Technology selection (language, framework, database)
+- Architecture patterns (layered, hexagonal, microservices)
+- External integrations (APIs, services)
+- Security decisions (authentication, authorization)
+- Performance trade-offs (caching, scaling)
+
+## Related Skills
+
+- `musubix-c4-design` - Architecture diagrams
+- `musubix-sdd-workflow` - Full development workflow
+- `musubix-traceability` - Link ADRs to requirements

package/.github/skills/musubix-best-practices/SKILL.md

@@ -0,0 +1,315 @@
+---
+name: musubix-best-practices
+description: Guide for applying MUSUBIX's 17 learned best practices. Use this when asked about coding patterns, design patterns, or testing patterns that MUSUBIX recommends.
+license: MIT
+---
+
+# MUSUBIX Best Practices Skill
+
+This skill guides you through applying the 17 best practices learned from MUSUBIX virtual projects.
+
+## Overview
+
+MUSUBIX has learned these best practices from implementing 14+ virtual projects. Apply them consistently for high-quality code.
+
+## Code Patterns (5)
+
+### BP-CODE-001: Entity Input DTO
+
+Use Input DTO objects for entity creation instead of multiple parameters.
+
+```typescript
+// ✅ Recommended: Input DTO
+interface CreatePetInput {
+  name: string;
+  species: string;
+  ownerId: string;
+}
+
+function createPet(input: CreatePetInput): Pet {
+  return new Pet(input);
+}
+
+// ❌ Avoid: Multiple parameters
+function createPet(name: string, species: string, ownerId: string): Pet {
+  // Hard to extend, easy to mix up parameter order
+}
+```
+
+### BP-CODE-002: Date-based ID Format
+
+Generate IDs with PREFIX-YYYYMMDD-NNN format for sortability.
+
+```typescript
+// ✅ Recommended: Date-based ID
+const id = `PET-20260104-001`;  // Sortable, traceable
+
+// ❌ Avoid: UUID only
+const id = crypto.randomUUID();  // Not human-readable
+```
+
+### BP-CODE-003: Value Objects
+
+Use Value Objects for domain concepts.
+
+```typescript
+// ✅ Recommended: Value Object
+interface Price {
+  readonly amount: number;
+  readonly currency: 'JPY';
+}
+
+// ❌ Avoid: Primitive types
+const price: number = 1000;  // No currency context
+```
+
+### BP-CODE-004: Function-based Value Objects
+
+Use interface + factory function instead of classes for Value Objects.
+
+```typescript
+// ✅ Recommended: Interface + Factory Function
+interface Price {
+  readonly amount: number;
+  readonly currency: 'JPY';
+}
+
+function createPrice(amount: number): Result<Price, ValidationError> {
+  if (amount < 100 || amount > 1_000_000) {
+    return err(new ValidationError('Price must be between 100 and 1,000,000 JPY'));
+  }
+  return ok({ amount, currency: 'JPY' });
+}
+
+// ❌ Avoid: Class-based (doesn't work well with TypeScript structural typing)
+class Price {
+  private constructor(readonly amount: number) {}
+  static create(amount: number): Price { ... }
+}
+```
+
+### BP-CODE-005: Result Type
+
+Use Result<T, E> for operations that can fail.
+
+```typescript
+// ✅ Recommended: Result type
+type Result<T, E> = { ok: true; value: T } | { ok: false; error: E };
+
+function divide(a: number, b: number): Result<number, Error> {
+  if (b === 0) return { ok: false, error: new Error('Division by zero') };
+  return { ok: true, value: a / b };
+}
+
+// ❌ Avoid: Throwing exceptions for expected errors
+function divide(a: number, b: number): number {
+  if (b === 0) throw new Error('Division by zero');
+  return a / b;
+}
+```
+
+## Design Patterns (7)
+
+### BP-DESIGN-001: Status Transition Map
+
+Define valid status transitions in a Map.
+
+```typescript
+// ✅ Recommended: Transition map
+const validTransitions: Record<Status, Status[]> = {
+  draft: ['active', 'cancelled'],
+  active: ['completed', 'cancelled'],
+  completed: [],
+  cancelled: [],
+};
+
+function canTransition(from: Status, to: Status): boolean {
+  return validTransitions[from].includes(to);
+}
+```
+
+### BP-DESIGN-002: Repository Async Pattern
+
+Make repositories async for future DB migration.
+
+```typescript
+// ✅ Recommended: Async repository
+interface PetRepository {
+  findById(id: PetId): Promise<Pet | null>;
+  save(pet: Pet): Promise<void>;
+}
+
+// ❌ Avoid: Sync repository (hard to migrate later)
+interface PetRepository {
+  findById(id: PetId): Pet | null;
+}
+```
+
+### BP-DESIGN-003: Service Layer with DI
+
+Use dependency injection for services.
+
+```typescript
+// ✅ Recommended: Constructor DI
+class PetService {
+  constructor(
+    private readonly petRepository: PetRepository,
+    private readonly auditService: AuditService
+  ) {}
+}
+```
+
+### BP-DESIGN-004: Optimistic Locking
+
+Use version field for concurrent edit detection.
+
+```typescript
+// ✅ Recommended: Version field
+interface Entity {
+  id: string;
+  version: number;
+  updatedAt: Date;
+}
+
+function update(entity: Entity, currentVersion: number): Result<Entity, ConcurrencyError> {
+  if (entity.version !== currentVersion) {
+    return err(new ConcurrencyError('Entity was modified'));
+  }
+  return ok({ ...entity, version: entity.version + 1 });
+}
+```
+
+### BP-DESIGN-005: AuditService
+
+Record data changes in audit logs.
+
+```typescript
+// ✅ Recommended: Audit logging
+interface AuditEntry {
+  id: string;
+  entityType: string;
+  entityId: string;
+  action: 'CREATE' | 'UPDATE' | 'DELETE';
+  changes: object;
+  userId: string;
+  timestamp: Date;
+}
+```
+
+### BP-DESIGN-006: Entity Counter Reset
+
+Provide reset functions for test isolation.
+
+```typescript
+// ✅ Recommended: Resettable counter
+let petCounter = 0;
+
+export function generatePetId(): string {
+  return `PET-${Date.now()}-${++petCounter}`;
+}
+
+export function resetPetCounter(): void {
+  petCounter = 0;  // For tests
+}
+```
+
+### BP-DESIGN-007: Expiry Time Logic
+
+Use expiresAt field for time-limited entities.
+
+```typescript
+// ✅ Recommended: Explicit expiry
+interface Reservation {
+  id: string;
+  createdAt: Date;
+  expiresAt: Date;  // Explicit expiry time
+}
+
+function isExpired(reservation: Reservation): boolean {
+  return new Date() > reservation.expiresAt;
+}
+```
+
+## Test Patterns (5)
+
+### BP-TEST-001: Test Counter Reset
+
+Reset ID counters in beforeEach.
+
+```typescript
+beforeEach(() => {
+  resetPetCounter();
+  resetReservationCounter();
+});
+```
+
+### BP-TEST-002: Verify API Before Test
+
+Check method signatures before writing tests.
+
+### BP-TEST-003: Vitest ESM Configuration
+
+Use proper ESM setup for Vitest.
+
+```typescript
+// vitest.config.ts
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+  },
+});
+```
+
+### BP-TEST-004: Result Type Test Pattern
+
+Test both success and error cases.
+
+```typescript
+it('should succeed with valid input', () => {
+  const result = createPrice(1000);
+  expect(result.isOk()).toBe(true);
+});
+
+it('should fail with invalid input', () => {
+  const result = createPrice(-1);
+  expect(result.isErr()).toBe(true);
+});
+```
+
+### BP-TEST-005: Status Transition Testing
+
+Test all valid and invalid transitions.
+
+```typescript
+describe('status transitions', () => {
+  it.each([
+    ['draft', 'active', true],
+    ['draft', 'completed', false],
+    ['active', 'completed', true],
+  ])('%s -> %s should be %s', (from, to, valid) => {
+    expect(canTransition(from, to)).toBe(valid);
+  });
+});
+```
+
+## CLI Commands
+
+```bash
+# Show all best practices
+npx musubix learn best-practices
+
+# Filter by category
+npx musubix learn best-practices --category code
+npx musubix learn best-practices --category design
+npx musubix learn best-practices --category test
+
+# High confidence only
+npx musubix learn best-practices --high-confidence
+```
+
+## Related Skills
+
+- `musubix-code-generation` - Apply patterns in code
+- `musubix-test-generation` - Apply test patterns
+- `musubix-sdd-workflow` - Full workflow with patterns

package/.github/skills/musubix-c4-design/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: musubix-c4-design
+description: Guide for creating C4 model design documents. Use this when asked to create architecture designs, system context diagrams, container diagrams, or component diagrams following the C4 model methodology.
+license: MIT
+---
+
+# MUSUBIX C4 Design Skill
+
+This skill guides you through creating C4 model architecture designs for MUSUBIX projects.
+
+## Overview
+
+The C4 model provides four levels of abstraction for describing software architecture:
+
+1. **Context** - System boundaries and external actors
+2. **Container** - Technology choices and deployable units
+3. **Component** - Internal structure of containers
+4. **Code** - Implementation details (optional)
+
+## Prerequisites
+
+Before creating designs:
+
+1. Read requirements from `storage/specs/` (REQ-* files)
+2. Check `steering/structure.ja.md` for architecture guidelines
+3. Review `steering/tech.ja.md` for technology constraints
+
+## Design Document Template
+
+```markdown
+# DES-[CATEGORY]-[NUMBER]: [Design Title]
+
+## メタデータ
+- **作成日**: YYYY-MM-DD
+- **トレーサビリティ**: REQ-XXX-NNN
+
+## 1. Context Level
+
+### システムコンテキスト図
+[External actors and systems that interact with our system]
+
+### 外部アクター
+| アクター | 説明 | インタラクション |
+|---------|------|-----------------|
+| User | システム利用者 | Web UI経由でアクセス |
+
+## 2. Container Level
+
+### コンテナ構成
+| コンテナ | 技術 | 責務 |
+|---------|------|------|
+| Web App | React/Next.js | UI提供 |
+| API Server | Node.js/Express | ビジネスロジック |
+| Database | PostgreSQL | データ永続化 |
+
+### コンテナ間通信
+[Describe how containers communicate]
+
+## 3. Component Level
+
+### [Container Name] コンポーネント
+
+| コンポーネント | 種別 | 責務 | 依存先 |
+|---------------|------|------|--------|
+| XxxService | Service | ビジネスロジック | XxxRepository |
+| XxxRepository | Repository | データアクセス | Database |
+| XxxController | Controller | リクエスト処理 | XxxService |
+
+## 4. 設計パターン
+
+### 適用パターン
+| パターン | 適用箇所 | 理由 |
+|---------|---------|------|
+| Repository | データアクセス層 | 永続化の抽象化 |
+| Service | ビジネス層 | ロジックの集約 |
+| Factory | オブジェクト生成 | 生成ロジックの分離 |
+
+## 5. 非機能要件への対応
+
+### セキュリティ
+- 認証: [方式]
+- 認可: [方式]
+- データ保護: [方式]
+
+### スケーラビリティ
+- [スケーリング戦略]
+
+### 可用性
+- [可用性設計]
+```
+
+## C4 Diagram Syntax (Mermaid)
+
+### Context Diagram
+```mermaid
+flowchart TB
+    subgraph External["外部システム"]
+        User[ユーザー]
+        ExtAPI[外部API]
+    end
+    
+    subgraph System["対象システム"]
+        App[アプリケーション]
+    end
+    
+    User --> App
+    App --> ExtAPI
+```
+
+### Container Diagram
+```mermaid
+flowchart TB
+    subgraph Containers["コンテナ構成"]
+        Web[Web App<br/>React]
+        API[API Server<br/>Node.js]
+        DB[(Database<br/>PostgreSQL)]
+    end
+    
+    Web --> API
+    API --> DB
+```
+
+### Component Diagram
+```mermaid
+flowchart TB
+    subgraph APIServer["API Server"]
+        Controller[Controller]
+        Service[Service]
+        Repository[Repository]
+    end
+    
+    Controller --> Service
+    Service --> Repository
+```
+
+## Design Patterns Reference
+
+| パターン | 用途 | 適用場面 |
+|---------|------|---------|
+| **Repository** | データアクセス抽象化 | DB操作 |
+| **Service** | ビジネスロジック集約 | ユースケース実装 |
+| **Factory** | オブジェクト生成 | 複雑な生成ロジック |
+| **Strategy** | アルゴリズム切替 | 認証方式、計算方式 |
+| **Observer** | イベント通知 | 状態変更の伝播 |
+| **Decorator** | 機能追加 | ログ、キャッシュ |
+
+## Domain-Specific Components
+
+Use `npx musubix design generate` to get domain-specific component recommendations for 62 domains.
+
+## Output Location
+
+Save design documents to:
+```
+storage/design/DES-[CATEGORY]-[NUMBER].md
+```
+
+## Related Skills
+
+- `musubix-ears-validation` - Requirements validation
+- `musubix-code-generation` - Generate code from design
+- `musubix-adr-generation` - Document architecture decisions