musubix 3.4.3 → 3.4.7

package/.github/skills/musubix-technical-writing/SKILL.md

@@ -0,0 +1,444 @@
+---
+name: musubix-technical-writing
+description: Guide for creating technical documentation including README, user guides, API references, and changelogs. Use this when asked to write documentation, create user manuals, or generate API docs.
+license: MIT
+---
+
+# MUSUBIX Technical Writing Skill
+
+This skill guides you through creating high-quality technical documentation for software projects.
+
+## Overview
+
+Technical documentation bridges the gap between code and users. MUSUBIX supports generating various document types with consistent structure and traceability.
+
+## Document Types
+
+### 1. README.md (Project Overview)
+
+**Purpose**: First impression of your project.
+
+**Template**:
+```markdown
+# Project Name
+
+> One-line description of what the project does.
+
+[![npm version](https://badge.fury.io/js/package-name.svg)](https://badge.fury.io/js/package-name)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## 🎯 Features
+
+- Feature 1: Brief description
+- Feature 2: Brief description
+- Feature 3: Brief description
+
+## 📦 Installation
+
+\`\`\`bash
+npm install package-name
+\`\`\`
+
+## 🚀 Quick Start
+
+\`\`\`typescript
+import { MainClass } from 'package-name';
+
+const instance = new MainClass();
+instance.doSomething();
+\`\`\`
+
+## 📖 Documentation
+
+- [Installation Guide](docs/INSTALL-GUIDE.md)
+- [User Guide](docs/USER-GUIDE.md)
+- [API Reference](docs/API-REFERENCE.md)
+
+## 🤝 Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## 📄 License
+
+MIT License - see [LICENSE](LICENSE) for details.
+```
+
+### 2. INSTALL-GUIDE.md (Installation Guide)
+
+**Purpose**: Step-by-step setup instructions.
+
+**Structure**:
+```markdown
+# Installation Guide
+
+## Prerequisites
+
+| Requirement | Version | Check Command |
+|-------------|---------|---------------|
+| Node.js | >= 20.0.0 | `node --version` |
+| npm | >= 10.0.0 | `npm --version` |
+
+## Installation Methods
+
+### Method 1: npm (Recommended)
+
+\`\`\`bash
+npm install package-name
+\`\`\`
+
+### Method 2: From Source
+
+\`\`\`bash
+git clone https://github.com/user/repo.git
+cd repo
+npm install
+npm run build
+\`\`\`
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `API_KEY` | API authentication key | - |
+| `LOG_LEVEL` | Logging verbosity | `info` |
+
+### Configuration File
+
+Create `config.json`:
+\`\`\`json
+{
+  "setting1": "value1",
+  "setting2": true
+}
+\`\`\`
+
+## Verification
+
+\`\`\`bash
+npx package-name --version
+\`\`\`
+
+## Troubleshooting
+
+### Common Issues
+
+#### Issue: Module not found
+**Solution**: Run `npm install` again.
+
+#### Issue: Permission denied
+**Solution**: Use `sudo` or fix npm permissions.
+```
+
+### 3. USER-GUIDE.md (User Guide)
+
+**Purpose**: Comprehensive usage instructions.
+
+**Structure**:
+```markdown
+# User Guide
+
+## Table of Contents
+
+1. [Getting Started](#getting-started)
+2. [Basic Usage](#basic-usage)
+3. [Advanced Features](#advanced-features)
+4. [Best Practices](#best-practices)
+
+## Getting Started
+
+### Your First Project
+
+1. Create a new directory
+2. Initialize the project
+3. Run your first command
+
+## Basic Usage
+
+### Command: `command-name`
+
+**Syntax**:
+\`\`\`bash
+npx tool command [options] <arguments>
+\`\`\`
+
+**Options**:
+| Option | Short | Description |
+|--------|-------|-------------|
+| `--output` | `-o` | Output directory |
+| `--verbose` | `-v` | Enable verbose logging |
+
+**Examples**:
+\`\`\`bash
+# Basic usage
+npx tool command input.txt
+
+# With options
+npx tool command -o output/ -v input.txt
+\`\`\`
+
+## Advanced Features
+
+### Feature: Custom Configuration
+
+[Detailed explanation with examples]
+
+## Best Practices
+
+1. **Do**: Recommended approach
+2. **Don't**: Anti-pattern to avoid
+```
+
+### 4. API-REFERENCE.md (API Reference)
+
+**Purpose**: Complete API documentation.
+
+**Structure**:
+```markdown
+# API Reference
+
+## Classes
+
+### `ClassName`
+
+Description of the class.
+
+#### Constructor
+
+\`\`\`typescript
+new ClassName(options?: ClassOptions)
+\`\`\`
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `options` | `ClassOptions` | Configuration options |
+
+#### Methods
+
+##### `methodName(param1, param2)`
+
+Description of what the method does.
+
+**Parameters**:
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `param1` | `string` | Yes | First parameter |
+| `param2` | `number` | No | Optional second parameter |
+
+**Returns**: `Promise<Result>`
+
+**Example**:
+\`\`\`typescript
+const result = await instance.methodName('value', 42);
+\`\`\`
+
+**Throws**:
+- `ValidationError`: When param1 is empty
+
+## Interfaces
+
+### `InterfaceName`
+
+\`\`\`typescript
+interface InterfaceName {
+  property1: string;
+  property2?: number;
+  method(arg: string): void;
+}
+\`\`\`
+
+## Types
+
+### `TypeName`
+
+\`\`\`typescript
+type TypeName = 'option1' | 'option2' | 'option3';
+\`\`\`
+```
+
+### 5. CHANGELOG.md (Change Log)
+
+**Purpose**: Track version history.
+
+**Format**: Follow [Keep a Changelog](https://keepachangelog.com/)
+
+```markdown
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- New feature description
+
+### Changed
+- Modified behavior description
+
+### Deprecated
+- Feature to be removed in future
+
+### Removed
+- Deleted feature description
+
+### Fixed
+- Bug fix description
+
+### Security
+- Security fix description
+
+## [1.0.0] - 2026-01-10
+
+### Added
+- Initial release
+- Core functionality
+- CLI interface
+```
+
+### 6. CONTRIBUTING.md (Contributing Guide)
+
+**Purpose**: Guide for contributors.
+
+```markdown
+# Contributing Guide
+
+Thank you for your interest in contributing!
+
+## Development Setup
+
+1. Fork the repository
+2. Clone your fork
+3. Install dependencies: `npm install`
+4. Create a branch: `git checkout -b feature/your-feature`
+
+## Code Standards
+
+- Use TypeScript
+- Follow ESLint rules
+- Write tests for new features
+- Maintain 80%+ code coverage
+
+## Pull Request Process
+
+1. Update documentation
+2. Add tests
+3. Run `npm test`
+4. Submit PR with clear description
+
+## Commit Message Format
+
+\`\`\`
+type(scope): description
+
+[optional body]
+
+[optional footer]
+\`\`\`
+
+Types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`
+
+## Code of Conduct
+
+Be respectful and inclusive.
+```
+
+## Writing Guidelines
+
+### 1. Audience-Aware Writing
+
+| Document | Audience | Tone | Technical Level |
+|----------|----------|------|-----------------|
+| README | Everyone | Welcoming | Low-Medium |
+| INSTALL-GUIDE | Users | Instructive | Medium |
+| USER-GUIDE | Users | Explanatory | Medium |
+| API-REFERENCE | Developers | Technical | High |
+| CONTRIBUTING | Contributors | Collaborative | High |
+
+### 2. Formatting Best Practices
+
+```markdown
+# ✅ Good Practices
+
+## Use Clear Headings
+Structure content hierarchically.
+
+## Include Code Examples
+\`\`\`typescript
+// Always show working examples
+const example = 'value';
+\`\`\`
+
+## Use Tables for Structured Data
+| Column 1 | Column 2 |
+|----------|----------|
+| Data | Data |
+
+## Add Visual Cues
+> 💡 **Tip**: Helpful advice
+> ⚠️ **Warning**: Important caution
+> ❌ **Error**: Common mistake
+```
+
+### 3. Multilingual Support
+
+For projects requiring Japanese and English:
+
+```
+docs/
+├── README.md          # English (default)
+├── README.ja.md       # Japanese
+├── USER-GUIDE.md      # English
+├── USER-GUIDE.ja.md   # Japanese
+└── ...
+```
+
+## CLI Integration
+
+```bash
+# Generate README from project analysis
+npx musubix docs readme
+
+# Generate API reference from TypeScript
+npx musubix docs api --source src/
+
+# Update CHANGELOG from git commits
+npx musubix docs changelog --from v1.0.0
+
+# Generate all documentation
+npx musubix docs generate --all
+```
+
+## Traceability
+
+Link documentation to requirements and design:
+
+```markdown
+<!-- @requirement REQ-DOC-001 -->
+<!-- @design DES-DOC-001 -->
+
+# User Guide
+
+This guide covers the usage of...
+```
+
+## Document Quality Checklist
+
+- [ ] Clear purpose statement
+- [ ] Logical structure with headings
+- [ ] Working code examples
+- [ ] Complete parameter documentation
+- [ ] Error handling examples
+- [ ] Up-to-date with current version
+- [ ] Spell-checked and grammar-checked
+- [ ] Links verified
+- [ ] Screenshots/diagrams where helpful
+
+## Related Skills
+
+- [musubix-sdd-workflow](../musubix-sdd-workflow/SKILL.md) - Overall development workflow
+- [musubix-adr-generation](../musubix-adr-generation/SKILL.md) - Decision documentation
+- [musubix-code-generation](../musubix-code-generation/SKILL.md) - Code with doc comments

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

@@ -0,0 +1,212 @@
+---
+name: musubix-test-generation
+description: Guide for generating test code from designs and requirements. Use this when asked to create unit tests, integration tests, or test coverage analysis following TDD/BDD practices.
+license: MIT
+---
+
+# MUSUBIX Test Generation Skill
+
+This skill guides you through generating comprehensive test suites that maintain traceability.
+
+## Overview
+
+MUSUBIX follows **Article III - Test-First**: Red-Green-Blue TDD cycle.
+
+```mermaid
+flowchart LR
+    RED[🔴 Red<br/>Failing Test] --> GREEN[🟢 Green<br/>Minimal Code]
+    GREEN --> BLUE[🔵 Blue<br/>Refactor]
+    BLUE --> RED
+```
+
+## Test Structure
+
+### Unit Test Template
+
+```typescript
+/**
+ * @requirement REQ-XXX-NNN
+ * @design DES-XXX-NNN
+ */
+import { describe, it, expect, beforeEach } from 'vitest';
+import { XxxService } from './xxx-service.js';
+import { resetXxxCounter } from './xxx-entity.js';
+
+describe('XxxService', () => {
+  let service: XxxService;
+  let repository: MockXxxRepository;
+
+  beforeEach(() => {
+    // BP-TEST-001: Reset counters before each test
+    resetXxxCounter();
+    repository = new MockXxxRepository();
+    service = new XxxService(repository);
+  });
+
+  describe('create', () => {
+    it('should create entity with valid input', async () => {
+      // Arrange
+      const input = { name: 'Test', value: 100 };
+      
+      // Act
+      const result = await service.create(input);
+      
+      // Assert
+      expect(result.isOk()).toBe(true);
+      if (result.isOk()) {
+        expect(result.value.name).toBe('Test');
+      }
+    });
+
+    it('should return error for invalid input', async () => {
+      // Arrange
+      const input = { name: '', value: -1 };
+      
+      // Act
+      const result = await service.create(input);
+      
+      // Assert
+      expect(result.isErr()).toBe(true);
+    });
+  });
+});
+```
+
+### Integration Test Template
+
+```typescript
+/**
+ * @requirement REQ-XXX-NNN
+ * @design DES-XXX-NNN
+ */
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+
+describe('XxxService Integration', () => {
+  beforeAll(async () => {
+    // Setup test environment
+  });
+
+  afterAll(async () => {
+    // Cleanup
+  });
+
+  it('should complete full workflow', async () => {
+    // Test full user journey
+  });
+});
+```
+
+## Best Practices for Testing
+
+### BP-TEST-001: Test Counter Reset
+
+```typescript
+beforeEach(() => {
+  resetPetCounter();  // Reset ID counters
+  resetReservationCounter();
+});
+```
+
+### BP-TEST-002: Verify API Before Test
+
+```typescript
+// ✅ Check actual API signature first
+const service = new PetService(repository);
+// Verify method exists and parameters match
+```
+
+### BP-TEST-004: Result Type Test Pattern
+
+```typescript
+// ✅ Test both success and failure cases
+it('should handle success', async () => {
+  const result = await service.create(validInput);
+  expect(result.isOk()).toBe(true);
+  if (result.isOk()) {
+    expect(result.value.id).toBeDefined();
+  }
+});
+
+it('should handle failure', async () => {
+  const result = await service.create(invalidInput);
+  expect(result.isErr()).toBe(true);
+  if (result.isErr()) {
+    expect(result.error.message).toContain('validation');
+  }
+});
+```
+
+### BP-TEST-005: Status Transition Testing
+
+```typescript
+describe('status transitions', () => {
+  // Valid transitions
+  it('should allow draft -> active', () => {
+    const result = workflow.transition('draft', 'activate');
+    expect(result).toBe('active');
+  });
+
+  // Invalid transitions
+  it('should reject completed -> draft', () => {
+    expect(() => workflow.transition('completed', 'revert'))
+      .toThrow('Invalid transition');
+  });
+});
+```
+
+## Test Categories
+
+| Category | Purpose | Location |
+|----------|---------|----------|
+| Unit | Single component | `__tests__/unit/` |
+| Integration | Multiple components | `__tests__/integration/` |
+| E2E | Full user flows | `__tests__/e2e/` |
+
+## CLI Commands
+
+```bash
+# Generate tests from design
+npx musubix test generate storage/design/DES-XXX.md
+
+# Run all tests
+npm test
+
+# Coverage report
+npx musubix test coverage src/
+
+# Run specific test file
+npm test -- xxx.test.ts
+```
+
+## Vitest Configuration
+
+```typescript
+// vitest.config.ts
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    include: ['**/*.test.ts'],
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'json', 'html'],
+    },
+  },
+});
+```
+
+## Coverage Targets
+
+| Metric | Target |
+|--------|--------|
+| Line Coverage | ≥80% |
+| Branch Coverage | ≥75% |
+| Function Coverage | ≥90% |
+
+## Related Skills
+
+- `musubix-sdd-workflow` - Full SDD workflow with TDD
+- `musubix-code-generation` - Generate code to test
+- `musubix-traceability` - Link tests to requirements