musubix 1.0.1 → 1.0.2

package/.github/AGENTS.md

@@ -0,0 +1,242 @@
+# MUSUBIX - AI Coding Agents
+
+This file defines AI agent configurations for MUSUBIX - Neuro-Symbolic AI Integration System.
+
+**Platform Support**: GitHub Copilot, Claude, Cursor, Gemini CLI, Codex CLI, Windsurf
+
+---
+
+## MCP Server Integration
+
+MUSUBIX provides an MCP Server (`@nahisaho/musubix-mcp-server`) with 9 tools and 3 prompts.
+
+### Starting MCP Server
+
+```bash
+npx @nahisaho/musubix-mcp-server
+npx musubix-mcp --transport stdio
+```
+
+### MCP Tools (9 Tools)
+
+| Tool Name | Description | Usage |
+|-----------|-------------|-------|
+| `sdd_create_requirements` | Create EARS-format requirements document | Requirements phase |
+| `sdd_validate_requirements` | Validate requirements against EARS patterns | Requirements validation |
+| `sdd_create_design` | Create C4 model design document | Design phase |
+| `sdd_validate_design` | Validate design traceability | Design validation |
+| `sdd_create_tasks` | Generate implementation tasks | Task breakdown |
+| `sdd_query_knowledge` | Query YATA knowledge graph | Knowledge retrieval |
+| `sdd_update_knowledge` | Update knowledge graph | Knowledge management |
+| `sdd_validate_constitution` | Validate against 9 Constitutional Articles | Compliance check |
+| `sdd_validate_traceability` | Validate requirement-design-task traceability | Traceability audit |
+
+### MCP Prompts (3 Prompts)
+
+| Prompt Name | Description |
+|-------------|-------------|
+| `sdd_requirements_analysis` | Analyze feature and generate EARS requirements |
+| `sdd_requirements_review` | Review requirements for completeness |
+| `sdd_design_generation` | Generate C4 model design from requirements |
+
+**Setup**: See `steering/tech.ja.md` for configuration.
+
+---
+
+## Project Structure
+
+MUSUBIX is a monorepo with 3 packages:
+
+```
+packages/
+├── core/           # @nahisaho/musubix-core - CLI, validation, code generation
+├── mcp-server/     # @nahisaho/musubix-mcp-server - MCP Server
+└── yata-client/    # @nahisaho/musubix-yata-client - Knowledge graph client
+```
+
+---
+
+## CLI Commands
+
+```bash
+# Project initialization
+npx musubix init [path] [--name <name>] [--force]
+
+# Requirements analysis (EARS format)
+npx musubix requirements analyze <file>
+npx musubix requirements validate <file>
+npx musubix requirements map <file>
+npx musubix requirements search <query>
+
+# Design generation
+npx musubix design generate <file>
+npx musubix design patterns <context>
+npx musubix design validate <file>
+npx musubix design c4 <file>
+npx musubix design adr <decision>
+
+# Code generation
+npx musubix codegen generate <file>
+npx musubix codegen analyze <file>
+npx musubix codegen security <path>
+
+# Test generation
+npx musubix test generate <file>
+npx musubix test coverage <dir>
+
+# Traceability
+npx musubix trace matrix
+npx musubix trace impact <id>
+npx musubix trace validate
+
+# Explanation
+npx musubix explain why <id>
+npx musubix explain graph <id>
+```
+
+---
+
+## 9 Constitutional Articles
+
+All development activities are governed by these immutable rules:
+
+| Article | Name | Summary |
+|---------|------|---------|
+| **I** | Library-First | Features start as independent libraries in packages/ |
+| **II** | CLI Interface | All libraries expose CLI |
+| **III** | Test-First | Red-Green-Blue cycle |
+| **IV** | EARS Format | Requirements in EARS syntax |
+| **V** | Traceability | 100% Requirements↔Design↔Code↔Tests tracking |
+| **VI** | Project Memory | Consult steering/ before decisions |
+| **VII** | Design Patterns | Document pattern applications |
+| **VIII** | Decision Records | All decisions as ADRs |
+| **IX** | Quality Gates | Validate before phase transitions |
+
+---
+
+## Prompt Files
+
+GitHub Copilot prompts are located in `.github/prompts/`:
+
+| Prompt | Command | Description |
+|--------|---------|-------------|
+| `sdd-requirements.prompt.md` | `musubix requirements` | Create EARS requirements |
+| `sdd-design.prompt.md` | `musubix design` | Generate C4 design |
+| `sdd-tasks.prompt.md` | `musubix tasks` | Break down into tasks |
+| `sdd-implement.prompt.md` | `musubix implement` | Execute implementation |
+| `sdd-validate.prompt.md` | `musubix validate` | Validate compliance |
+| `sdd-steering.prompt.md` | `musubix steering` | Manage project memory |
+| `sdd-change-init.prompt.md` | `musubix change init` | Initialize change proposal |
+| `sdd-change-apply.prompt.md` | `musubix change apply` | Apply change proposal |
+| `sdd-change-archive.prompt.md` | `musubix change archive` | Archive completed change |
+
+---
+
+## Project Memory (Steering)
+
+AI agents MUST consult these files before making decisions:
+
+| File | Content |
+|------|---------|
+| `steering/structure.ja.md` | Architecture patterns, layer structure |
+| `steering/tech.ja.md` | Technology stack (TypeScript, Node.js 20+) |
+| `steering/product.ja.md` | Product context |
+| `steering/rules/constitution.md` | 9 Constitutional Articles |
+| `steering/project.yml` | Project configuration |
+
+---
+
+## Storage Structure
+
+| Path | Content |
+|------|---------|
+| `storage/specs/` | Requirements (REQ-*), Design (DES-*), Tasks (TSK-*) |
+| `storage/design/` | Design documents, C4 diagrams |
+| `storage/traceability/` | Traceability matrices |
+| `storage/reviews/` | Code reviews, validations |
+| `storage/changes/` | Change proposals and implementations |
+| `storage/archive/` | Archived documents |
+
+---
+
+## EARS Patterns
+
+All requirements MUST use one of 5 EARS patterns:
+
+| Pattern | Syntax | Example |
+|---------|--------|---------|
+| **Event-driven** | `WHEN [event], the [system] SHALL [response]` | WHEN user clicks Submit, the system SHALL validate input |
+| **State-driven** | `WHILE [state], the [system] SHALL [response]` | WHILE loading, the UI SHALL show spinner |
+| **Unwanted** | `IF [error], THEN the [system] SHALL [response]` | IF timeout occurs, THEN the system SHALL retry |
+| **Optional** | `WHERE [feature enabled], the [system] SHALL [response]` | WHERE 2FA enabled, the system SHALL require OTP |
+| **Ubiquitous** | `The [system] SHALL [requirement]` | The API SHALL authenticate all requests |
+
+---
+
+## C4 Model Levels
+
+Design documents use 4 C4 levels:
+
+| Level | Name | Content |
+|-------|------|---------|
+| **1** | Context | System boundary, external actors |
+| **2** | Container | Deployable units, databases, APIs |
+| **3** | Component | Internal structure, services, repositories |
+| **4** | Code | Implementation details |
+
+---
+
+## Development Workflow
+
+```
+1. Read steering/ (Article VI)
+2. Define requirements in EARS format (Article IV)
+3. Design with C4 model
+4. Write tests first - RED (Article III)
+5. Implement minimum code - GREEN
+6. Refactor - BLUE
+7. Validate traceability (Article V)
+8. Pass quality gates (Article IX)
+```
+
+---
+
+## Technology Stack
+
+- **Language**: TypeScript
+- **Runtime**: Node.js >= 20.0.0
+- **Package Manager**: npm >= 10.0.0
+- **Build**: npm workspaces (monorepo)
+- **Test**: Vitest
+- **Lint**: ESLint
+
+---
+
+## Quick Start
+
+```bash
+# Initialize project
+npx musubix init my-project
+
+# Create requirements
+npx musubix requirements analyze feature.md
+
+# Generate design
+npx musubix design generate requirements.md
+
+# Break down tasks
+npx musubix tasks generate design.md
+
+# Implement with Test-First
+npx musubix implement feature-name
+
+# Validate
+npx musubix validate feature-name
+```
+
+---
+
+**Agent**: GitHub Copilot / Claude
+**Last Updated**: 2026-01-02
+**Version**: 1.0.0
+**Repository**: https://github.com/nahisaho/MUSUBIX

package/.github/prompts/sdd-change-apply.prompt.md

@@ -0,0 +1,283 @@
+# MUSUBIX Change Apply Command
+
+Apply a change proposal to the codebase.
+
+---
+
+## Instructions for AI Agent
+
+You are executing the `musubix change apply [change-name]` command to implement an approved change proposal.
+
+### Command Format
+
+```bash
+npx musubix change apply add-2fa
+npx musubix change apply migrate-to-graphql
+```
+
+### Your Task
+
+Implement the changes defined in the change proposal, following constitutional governance.
+
+---
+
+## Process
+
+### 1. Read Change Proposal
+
+**IMPORTANT**: Read the approved change proposal first:
+
+```bash
+storage/changes/{{CHANGE_NAME}}-proposal.md
+```
+
+**Extract**:
+
+- ADDED requirements
+- MODIFIED requirements
+- REMOVED requirements
+- Implementation plan
+
+**Verify Approval**:
+
+- Status must be "Approved" (not "Proposed")
+- If not approved, abort and notify user
+
+---
+
+### 2. Read Steering Context (Article VI)
+
+```bash
+steering/product.ja.md
+steering/structure.ja.md
+steering/tech.ja.md
+```
+
+---
+
+### 3. Execute Implementation Plan
+
+Follow the phases defined in the change proposal:
+
+#### Phase 1: Preparation
+
+```bash
+# Create feature branch
+git checkout -b feature/{{CHANGE_NAME}}
+
+# Create implementation tracking document
+touch storage/changes/{{CHANGE_NAME}}-implementation.md
+```
+
+#### Phase 2: Update Requirements
+
+For ADDED requirements:
+- Create new requirement files in `storage/specs/`
+
+For MODIFIED requirements:
+- Update existing requirement files
+- Mark version change
+
+For REMOVED requirements:
+- Archive to `storage/archive/`
+- Update traceability
+
+#### Phase 3: Update Design
+
+- Update `storage/specs/DES-*.md` files
+- Add new ADRs for significant changes
+
+#### Phase 4: Implement Code
+
+Follow Test-First (Article III):
+
+1. **Write Tests (RED)**
+   ```typescript
+   // packages/core/__tests__/unit/{{feature}}.test.ts
+   describe('REQ-{{COMPONENT}}-NEW-001: [New Feature]', () => {
+     it('should [new behavior]', () => {
+       // Test new functionality
+     });
+   });
+   ```
+
+2. **Implement (GREEN)**
+   ```typescript
+   // packages/core/src/{{feature}}/service.ts
+   // Minimal implementation to pass tests
+   ```
+
+3. **Refactor (BLUE)**
+   - Improve design
+   - Ensure tests still pass
+
+---
+
+### 4. Feature Flag (Optional)
+
+For gradual rollout:
+
+```typescript
+// packages/core/src/config/feature-flags.ts
+
+export const FEATURE_FLAGS = {
+  enable_{{feature}}: {
+    enabled: false,  // Start disabled
+    description: '{{CHANGE_DESCRIPTION}}',
+  },
+} as const;
+```
+
+```typescript
+// Usage in code
+import { FEATURE_FLAGS } from '../config/feature-flags.js';
+
+if (FEATURE_FLAGS.enable_{{feature}}.enabled) {
+  // New implementation
+} else {
+  // Old implementation
+}
+```
+
+---
+
+### 5. Update CLI (Article II)
+
+If CLI changes:
+
+```typescript
+// packages/core/src/cli/commands/{{feature}}.ts
+
+export function register{{Feature}}Command(program: Command): void {
+  program
+    .command('{{feature}}')
+    .description('{{New/Updated description}}')
+    .option('--new-option', 'New option from change')
+    .action(async (options) => {
+      // Updated implementation
+    });
+}
+```
+
+---
+
+### 6. Update MCP Tools
+
+If MCP tools change:
+
+```typescript
+// packages/mcp-server/src/tools/{{feature}}-tools.ts
+
+export const {{feature}}Tool: ToolDefinition = {
+  name: 'sdd_{{feature}}',
+  description: '{{Updated description}}',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      // Updated schema
+      newProperty: {
+        type: 'string',
+        description: 'New property from change',
+      },
+    },
+  },
+  handler: async (args) => {
+    // Updated implementation
+  },
+};
+```
+
+---
+
+### 7. Generate Implementation Report
+
+**Output**: `storage/changes/{{CHANGE_NAME}}-implementation.md`
+
+```markdown
+# Implementation Report: {{CHANGE_NAME}}
+
+**Date**: {{DATE}}
+**Status**: In Progress / Completed
+
+## Summary
+
+| Item | Status |
+|------|--------|
+| Requirements Updated | ✅ |
+| Design Updated | ✅ |
+| Tests Written | ✅ |
+| Code Implemented | ✅ |
+| Documentation Updated | ⏳ |
+
+## Changes Made
+
+### Files Created
+
+- `packages/core/src/{{feature}}/new-module.ts`
+- `packages/core/__tests__/unit/new-module.test.ts`
+
+### Files Modified
+
+- `packages/core/src/{{feature}}/service.ts`
+- `packages/mcp-server/src/tools/{{feature}}-tools.ts`
+
+### Files Deleted
+
+- `packages/core/src/{{feature}}/deprecated.ts`
+
+## Test Results
+
+\`\`\`
+npm test
+
+✓ packages/core/__tests__/unit/{{feature}}.test.ts (10 tests)
+✓ packages/core/__tests__/integration/{{feature}}.integration.test.ts (5 tests)
+
+Test Suites: 2 passed
+Tests: 15 passed
+Coverage: 87%
+\`\`\`
+
+## Traceability Verification
+
+| Requirement | Design | Code | Test |
+|-------------|--------|------|------|
+| REQ-XXX-NEW-001 | DES-XXX-001 | ✅ | ✅ |
+| REQ-XXX-001 (mod) | DES-XXX-001 | ✅ | ✅ |
+
+## Deployment Notes
+
+1. Run migrations (if any)
+2. Enable feature flag
+3. Monitor metrics
+
+## Rollback Instructions
+
+1. Disable feature flag
+2. Revert to previous release
+```
+
+---
+
+### 8. Validation
+
+Run all validations:
+
+```bash
+# Tests
+npm test
+
+# Type check
+npm run typecheck
+
+# Lint
+npm run lint
+
+# Traceability
+npx musubix trace validate
+```
+
+---
+
+**MUSUBIX**: https://github.com/nahisaho/MUSUBIX
+**Version**: 1.0.0