musubix 2.3.6 → 2.4.1

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

@@ -0,0 +1,210 @@
+---
+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/`
+
+## Complete Workflow
+
+### Phase 1: Requirements Definition
+
+#### Step 1: Create Requirements Document (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-3: Requirements Review Loop
+
+Review requirements for:
+- EARS format compliance
+- Completeness and clarity
+- Testability
+- Traceability readiness
+
+**Repeat until no issues remain.**
+
+### Phase 2: Design
+
+#### Step 4: Create Design Document (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 5-6: Design Review Loop
+
+Review design for:
+- Requirement coverage
+- SOLID principles compliance
+- Design pattern appropriateness
+- Traceability to requirements
+
+**Repeat until no issues remain.**
+
+### Phase 3: Task Decomposition
+
+#### Step 7: Generate Tasks
+
+Generate implementation tasks from design:
+
+```markdown
+# TSK-[CATEGORY]-[NUMBER]
+
+## 関連設計: DES-XXX
+## 関連要件: REQ-XXX
+
+## タスク内容
+[Implementation task description]
+
+## 受入基準
+- [ ] Criterion 1
+- [ ] Criterion 2
+
+## 見積もり
+[4時間以内を推奨]
+```
+
+#### Step 8-9: Task Review Loop
+
+Review tasks for:
+- Appropriate granularity (≤4 hours)
+- Clear acceptance criteria
+- Complete traceability chain
+
+**Repeat until no issues remain.**
+
+### Phase 4: Implementation
+
+#### Step 10: Coding & Unit Testing (Article III - Test-First)
+
+For each task, 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
+
+Add requirement IDs in code comments:
+```typescript
+/**
+ * @see REQ-INT-001 - Neuro-Symbolic Integration
+ */
+```
+
+#### Step 11: Integration Testing
+
+When required by the task:
+- Run integration tests
+- Verify component interactions
+- Ensure end-to-end flows work correctly
+
+### Phase 5: Documentation & Completion
+
+#### Step 12: Update CHANGELOG.md
+
+Document all changes:
+- New features
+- Bug fixes
+- Breaking changes
+- Migration notes
+
+#### Step 13: Update Other Documentation
+
+If necessary, update:
+- README.md
+- USER-GUIDE.md
+- API-REFERENCE.md
+- AGENTS.md
+
+#### Step 14: Git Commit & Push
+
+```bash
+git add .
+git commit -m "feat/fix/chore: description"
+git push
+```
+
+## Traceability Validation (Article V)
+
+Ensure 100% traceability throughout:
+```
+REQ-* → DES-* → TSK-* → Code → Test
+```
+
+## 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/.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