musubix 3.3.3 → 3.3.5

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

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

@@ -0,0 +1,237 @@
+---
+name: musubix-code-generation
+description: Guide for generating code from design specifications using MUSUBIX. Use this when asked to generate code, implement features, or create components following design documents.
+license: MIT
+---
+
+# MUSUBIX Code Generation Skill
+
+This skill guides you through generating code from design specifications following MUSUBIX methodology.
+
+## Prerequisites
+
+Before generating code:
+
+1. Verify design document exists (`DES-*`)
+2. Verify requirements are traceable (`REQ-*`)
+3. Check `steering/tech.ja.md` for technology stack
+
+## Supported Languages
+
+| Language | Extension | Features |
+|----------|-----------|----------|
+| TypeScript | `.ts` | Full support with types |
+| JavaScript | `.js` | ES6+ modules |
+| Python | `.py` | Type hints support |
+| Java | `.java` | Interface/Class generation |
+| Go | `.go` | Struct/Interface generation |
+| Rust | `.rs` | Trait/Struct generation |
+| C# | `.cs` | Interface/Class generation |
+
+## Code Generation Workflow
+
+### Step 1: Read Design Document
+
+```bash
+# Generate code from design
+npx musubix codegen generate <design-file>
+```
+
+### Step 2: Generate with Traceability
+
+Always include requirement references:
+
+```typescript
+/**
+ * UserService - Handles user operations
+ * 
+ * @see REQ-INT-001 - Neuro-Symbolic Integration
+ * @see DES-INT-001 - Integration Layer Design
+ */
+export class UserService {
+  // Implementation
+}
+```
+
+### Step 3: Follow Test-First (Article III)
+
+1. **Write test first**:
+```typescript
+describe('UserService', () => {
+  it('should create user', async () => {
+    const service = new UserService();
+    const user = await service.create({ name: 'Test' });
+    expect(user.id).toBeDefined();
+  });
+});
+```
+
+2. **Implement minimal code**:
+```typescript
+export class UserService {
+  async create(data: CreateUserDto): Promise<User> {
+    return { id: generateId(), ...data };
+  }
+}
+```
+
+3. **Refactor**
+
+## Design Pattern Templates
+
+### Singleton Pattern
+```typescript
+/**
+ * @see REQ-DES-001 - Pattern Detection
+ * @pattern Singleton
+ */
+export class ConfigManager {
+  private static instance: ConfigManager;
+  
+  private constructor() {}
+  
+  static getInstance(): ConfigManager {
+    if (!ConfigManager.instance) {
+      ConfigManager.instance = new ConfigManager();
+    }
+    return ConfigManager.instance;
+  }
+}
+```
+
+### Factory Pattern
+```typescript
+/**
+ * @see REQ-DES-001 - Pattern Detection
+ * @pattern Factory
+ */
+export interface ServiceFactory {
+  create(type: string): Service;
+}
+
+export class DefaultServiceFactory implements ServiceFactory {
+  create(type: string): Service {
+    switch (type) {
+      case 'auth': return new AuthService();
+      case 'user': return new UserService();
+      default: throw new Error(`Unknown service: ${type}`);
+    }
+  }
+}
+```
+
+### Repository Pattern
+```typescript
+/**
+ * @see REQ-COD-001 - Code Generation
+ * @pattern Repository
+ */
+export interface Repository<T> {
+  findById(id: string): Promise<T | null>;
+  findAll(): Promise<T[]>;
+  save(entity: T): Promise<T>;
+  delete(id: string): Promise<void>;
+}
+
+export class UserRepository implements Repository<User> {
+  async findById(id: string): Promise<User | null> {
+    // Implementation
+  }
+  // ... other methods
+}
+```
+
+## CLI Commands
+
+```bash
+# Generate code from design
+npx musubix codegen generate <design-file>
+
+# Generate status transition code (v3.1.0)
+npx musubix codegen status <spec>
+npx musubix codegen status <spec> --enum   # Use enum type
+
+# Analyze existing code
+npx musubix codegen analyze <file>
+
+# Security scan
+npx musubix codegen security <path>
+
+# Scaffold with Value Objects and Status machines (v3.1.0)
+npx musubix scaffold domain-model <name> -v "Price,Email"
+npx musubix scaffold domain-model <name> -s "Order,Task"
+```
+
+## Quality Checks (Article IX)
+
+Before committing code:
+
+- [ ] **Type Safety**: No `any` types (TypeScript)
+- [ ] **Traceability**: All classes/functions have `@see` references
+- [ ] **Tests**: Test coverage ≥ 80%
+- [ ] **Linting**: `npm run lint` passes
+- [ ] **Build**: `npm run build` succeeds
+
+## Neuro-Symbolic Integration (REQ-INT-002)
+
+When generating code that involves decision-making:
+
+```typescript
+/**
+ * @see REQ-INT-002 - Confidence Evaluation
+ */
+async function integrateResults(
+  neuralResult: NeuralResult,
+  symbolicResult: SymbolicResult
+): Promise<FinalResult> {
+  // Decision rules from REQ-INT-002
+  if (symbolicResult.status === 'invalid') {
+    return rejectNeural(neuralResult);
+  }
+  
+  if (neuralResult.confidence >= 0.8) {
+    return adoptNeural(neuralResult);
+  }
+  
+  return prioritizeSymbolic(symbolicResult);
+}
+```
+
+## File Structure Convention
+
+```
+packages/
+├── core/
+│   └── src/
+│       ├── [feature]/
+│       │   ├── index.ts        # Public exports
+│       │   ├── [feature].ts    # Main implementation
+│       │   ├── types.ts        # Type definitions
+│       │   └── __tests__/      # Tests
+│       └── index.ts            # Package exports
+```
+
+## Error Handling Pattern
+
+```typescript
+/**
+ * @see REQ-ERR-001 - Graceful Degradation
+ */
+export class MuSubixError extends Error {
+  constructor(
+    message: string,
+    public code: string,
+    public recoverable: boolean = true
+  ) {
+    super(message);
+    this.name = 'MuSubixError';
+  }
+}
+
+// Usage
+throw new MuSubixError(
+  'Failed to connect to YATA',
+  'YATA_CONNECTION_ERROR',
+  true // Can retry
+);
+```