mirror of
https://github.com/rohitg00/skillkit.git
synced 2026-11-19 02:13:58 +00:00
Compare commits
5
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
6fc62f4e42 | ||
|
|
b3ba8eb59e | ||
|
|
44ed5c2485 | ||
|
|
3d0195f180 | ||
|
|
e74f7d6b57 |
@@ -13,6 +13,14 @@
|
||||
npm install -g skillkit
|
||||
```
|
||||
|
||||
## What's New in v1.5.0
|
||||
|
||||
- **Team Collaboration**: Share skill bundles with your team via Git
|
||||
- **Plugin System**: Extend SkillKit with custom translators, providers, and commands
|
||||
- **Methodologies**: 5 ready-to-use development frameworks (Agile, TDD, DevOps, etc.)
|
||||
- **Agent Orchestration**: Coordinate multiple AI agents working together
|
||||
- **Hooks & Automation**: Auto-trigger skills on git commits, file changes
|
||||
|
||||
## The Problem
|
||||
|
||||
You've built amazing skills for Claude Code. Now you want to try Cursor. Or your team uses different agents. Your options:
|
||||
@@ -44,6 +52,7 @@ skillkit recommend
|
||||
| Feature | Without SkillKit | With SkillKit |
|
||||
|---------|-----------------|---------------|
|
||||
| **Multi-Agent Support** | Manual rewrite for each agent | One command, all agents |
|
||||
| **Team Collaboration** | Email skills back and forth | Git-based bundles, remote sync |
|
||||
| **Skill Discovery** | Search GitHub manually | Smart recommendations for your stack |
|
||||
| **Format Translation** | Learn each agent's format | Automatic conversion (17 formats) |
|
||||
| **Context Sync** | Configure each agent separately | One config, synced everywhere |
|
||||
|
||||
+170
-10
@@ -14,23 +14,183 @@ npm install -g skillkit
|
||||
# Initialize skillkit in your project
|
||||
skillkit init
|
||||
|
||||
# Install a skill
|
||||
skillkit install github.com/anthropics/courses:prompt-eng/interactive-tutorial
|
||||
# Install skills from GitHub
|
||||
skillkit install anthropics/skills
|
||||
|
||||
# List installed skills
|
||||
skillkit list
|
||||
# Get recommendations for your stack
|
||||
skillkit recommend
|
||||
|
||||
# Launch interactive TUI
|
||||
skillkit ui
|
||||
```
|
||||
|
||||
## Features
|
||||
## Core Features
|
||||
|
||||
- **17+ Agent Support**: Claude Code, Cursor, Codex, Gemini CLI, Windsurf, GitHub Copilot, and more
|
||||
- **Universal Skill Translation**: Convert skills between different agent formats
|
||||
- **Smart Recommendations**: Get skill suggestions based on your project stack
|
||||
- **Project Context Sync**: One config, all agents
|
||||
- **Interactive TUI**: Browse, install, and manage skills visually
|
||||
### Cross-Agent Translation
|
||||
|
||||
```bash
|
||||
# Translate a Claude skill to Cursor format
|
||||
skillkit translate react-patterns --to cursor
|
||||
|
||||
# Translate all skills to multiple agents
|
||||
skillkit translate --all --to windsurf,codex
|
||||
|
||||
# Preview translation
|
||||
skillkit translate my-skill --to copilot --dry-run
|
||||
```
|
||||
|
||||
### Smart Recommendations
|
||||
|
||||
```bash
|
||||
# Get project-aware suggestions
|
||||
skillkit recommend
|
||||
|
||||
# Filter by task
|
||||
skillkit recommend --search "authentication"
|
||||
|
||||
# Quality threshold
|
||||
skillkit recommend --min-score 85
|
||||
```
|
||||
|
||||
### Team Collaboration
|
||||
|
||||
```bash
|
||||
# Initialize team
|
||||
skillkit team init --name "Engineering Team"
|
||||
|
||||
# Create skill bundle
|
||||
skillkit team bundle-create
|
||||
|
||||
# Share with team
|
||||
skillkit team share onboarding-bundle
|
||||
|
||||
# Sync with remote registry
|
||||
skillkit team sync
|
||||
```
|
||||
|
||||
### Plugin System
|
||||
|
||||
```bash
|
||||
# List installed plugins
|
||||
skillkit plugin list
|
||||
|
||||
# Install custom plugin
|
||||
skillkit plugin install @company/custom-translator
|
||||
|
||||
# View plugin info
|
||||
skillkit plugin info my-plugin
|
||||
```
|
||||
|
||||
### Development Methodologies
|
||||
|
||||
```bash
|
||||
# List available methodologies
|
||||
skillkit methodology list
|
||||
|
||||
# Load TDD methodology
|
||||
skillkit methodology load tdd
|
||||
|
||||
# Apply to project
|
||||
skillkit methodology apply agile
|
||||
```
|
||||
|
||||
### Plan System
|
||||
|
||||
```bash
|
||||
# Parse and validate plan
|
||||
skillkit plan parse ./implementation-plan.md
|
||||
skillkit plan validate ./plan.md
|
||||
|
||||
# Execute plan
|
||||
skillkit plan execute ./feature-plan.md
|
||||
|
||||
# Check status
|
||||
skillkit plan status
|
||||
```
|
||||
|
||||
### Hooks & Automation
|
||||
|
||||
```bash
|
||||
# List hooks
|
||||
skillkit hook list
|
||||
|
||||
# Register pre-commit hook
|
||||
skillkit hook register pre-commit
|
||||
|
||||
# Trigger manually
|
||||
skillkit hook trigger pre-commit
|
||||
```
|
||||
|
||||
### Workflow Orchestration
|
||||
|
||||
```bash
|
||||
# List workflows
|
||||
skillkit workflow list
|
||||
|
||||
# Run workflow
|
||||
skillkit workflow run feature-development
|
||||
|
||||
# Create new workflow
|
||||
skillkit workflow create deployment-flow
|
||||
```
|
||||
|
||||
### Session Memory
|
||||
|
||||
```bash
|
||||
# View learnings
|
||||
skillkit memory list
|
||||
|
||||
# Search past sessions
|
||||
skillkit memory search "error handling"
|
||||
|
||||
# Compress observations
|
||||
skillkit memory compress
|
||||
|
||||
# Export learning as skill
|
||||
skillkit memory export auth-insight --output auth-skill.md
|
||||
```
|
||||
|
||||
## Supported Agents (17)
|
||||
|
||||
Claude Code, Cursor, Codex, Gemini CLI, Windsurf, GitHub Copilot, OpenCode, Antigravity, Amp, Clawdbot, Droid, Goose, Kilo, Kiro, Roo, Trae, Universal
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Install and Sync
|
||||
|
||||
```bash
|
||||
# Install to multiple agents
|
||||
skillkit install anthropics/skills --agent claude-code,cursor
|
||||
|
||||
# Sync all skills to detected agents
|
||||
skillkit sync --all
|
||||
```
|
||||
|
||||
### Context Management
|
||||
|
||||
```bash
|
||||
# Initialize project context
|
||||
skillkit context init
|
||||
|
||||
# View detected stack
|
||||
skillkit context show
|
||||
|
||||
# Sync to all agents
|
||||
skillkit context sync --all
|
||||
```
|
||||
|
||||
### Testing
|
||||
|
||||
```bash
|
||||
# Run all skill tests
|
||||
skillkit test
|
||||
|
||||
# Test specific skills
|
||||
skillkit test ./my-skill --tags unit
|
||||
|
||||
# CI/CD integration
|
||||
skillkit cicd init
|
||||
```
|
||||
|
||||
## Documentation
|
||||
|
||||
|
||||
@@ -33,6 +33,12 @@ import {
|
||||
CICDCommand,
|
||||
TeamCommand,
|
||||
PluginCommand,
|
||||
MethodologyCommand,
|
||||
HookCommand,
|
||||
PlanCommand,
|
||||
CommandCmd,
|
||||
AICommand,
|
||||
AuditCommand,
|
||||
} from '@skillkit/cli';
|
||||
|
||||
const __filename = fileURLToPath(import.meta.url);
|
||||
@@ -79,5 +85,11 @@ cli.register(SettingsCommand);
|
||||
cli.register(CICDCommand);
|
||||
cli.register(TeamCommand);
|
||||
cli.register(PluginCommand);
|
||||
cli.register(MethodologyCommand);
|
||||
cli.register(HookCommand);
|
||||
cli.register(PlanCommand);
|
||||
cli.register(CommandCmd);
|
||||
cli.register(AICommand);
|
||||
cli.register(AuditCommand);
|
||||
|
||||
cli.runExit(process.argv.slice(2));
|
||||
|
||||
@@ -21,7 +21,8 @@
|
||||
"test": "vitest run"
|
||||
},
|
||||
"dependencies": {
|
||||
"@skillkit/core": "workspace:*"
|
||||
"@skillkit/core": "workspace:*",
|
||||
"minimatch": "^9.0.0"
|
||||
},
|
||||
"devDependencies": {
|
||||
"@types/node": "^22.10.5",
|
||||
|
||||
@@ -0,0 +1,542 @@
|
||||
/**
|
||||
* Agent Features Tests
|
||||
*/
|
||||
|
||||
import { describe, it, expect, beforeEach } from 'vitest';
|
||||
import {
|
||||
PermissionManager,
|
||||
createPermissionManager,
|
||||
isAllowed,
|
||||
isDenied,
|
||||
needsConfirmation,
|
||||
} from '../permissions.js';
|
||||
import {
|
||||
GlobMatcher,
|
||||
createGlobMatcher,
|
||||
matchPattern,
|
||||
parseGlobsFromMDC,
|
||||
fromCommonPatterns,
|
||||
COMMON_PATTERNS,
|
||||
} from '../globs.js';
|
||||
import {
|
||||
BootstrapManager,
|
||||
createBootstrapManager,
|
||||
createBootstrapSet,
|
||||
} from '../bootstrap.js';
|
||||
import {
|
||||
ModeManager,
|
||||
createModeManager,
|
||||
createDefaultModeManager,
|
||||
ALL_MODES,
|
||||
} from '../modes.js';
|
||||
import type { PermissionConfig, GlobConfig, ModeConfig } from '../types.js';
|
||||
|
||||
describe('PermissionManager', () => {
|
||||
let manager: PermissionManager;
|
||||
|
||||
beforeEach(() => {
|
||||
manager = createPermissionManager();
|
||||
});
|
||||
|
||||
describe('checkFileAccess', () => {
|
||||
it('should return default permission for unmatched files', () => {
|
||||
manager.setConfig({ default: 'ask' });
|
||||
expect(manager.checkFileAccess('some/file.ts')).toBe('ask');
|
||||
});
|
||||
|
||||
it('should match file patterns', () => {
|
||||
manager.setConfig({
|
||||
files: [
|
||||
{ pattern: '*.ts', level: 'allow' },
|
||||
{ pattern: 'secret/*', level: 'deny' },
|
||||
],
|
||||
default: 'ask',
|
||||
});
|
||||
|
||||
expect(manager.checkFileAccess('app.ts')).toBe('allow');
|
||||
expect(manager.checkFileAccess('secret/keys.json')).toBe('deny');
|
||||
expect(manager.checkFileAccess('random.json')).toBe('ask');
|
||||
});
|
||||
|
||||
it('should use first matching pattern', () => {
|
||||
manager.setConfig({
|
||||
files: [
|
||||
{ pattern: '*.ts', level: 'deny' },
|
||||
{ pattern: 'src/*.ts', level: 'allow' },
|
||||
],
|
||||
});
|
||||
|
||||
expect(manager.checkFileAccess('app.ts')).toBe('deny');
|
||||
});
|
||||
});
|
||||
|
||||
describe('checkCommandAccess', () => {
|
||||
it('should check command patterns', () => {
|
||||
manager.setConfig({
|
||||
commands: [
|
||||
{ pattern: 'npm *', level: 'allow' },
|
||||
{ pattern: 'rm *', level: 'deny' },
|
||||
],
|
||||
default: 'ask',
|
||||
});
|
||||
|
||||
expect(manager.checkCommandAccess('npm install')).toBe('allow');
|
||||
expect(manager.checkCommandAccess('rm -rf /')).toBe('deny');
|
||||
expect(manager.checkCommandAccess('git status')).toBe('ask');
|
||||
});
|
||||
});
|
||||
|
||||
describe('addFilePattern', () => {
|
||||
it('should add file pattern', () => {
|
||||
manager.addFilePattern({ pattern: '*.js', level: 'allow' });
|
||||
|
||||
expect(manager.checkFileAccess('app.js')).toBe('allow');
|
||||
});
|
||||
});
|
||||
|
||||
describe('generateOpenCodeConfig', () => {
|
||||
it('should generate OpenCode-compatible config', () => {
|
||||
manager.setConfig({
|
||||
files: [{ pattern: 'src/*', level: 'allow' }],
|
||||
commands: [{ pattern: 'npm *', level: 'allow' }],
|
||||
default: 'ask',
|
||||
});
|
||||
|
||||
const config = manager.generateOpenCodeConfig();
|
||||
|
||||
expect(config).toContain('File Access');
|
||||
expect(config).toContain('allow: `src/*`');
|
||||
expect(config).toContain('Command Execution');
|
||||
expect(config).toContain('Default: ask');
|
||||
});
|
||||
});
|
||||
|
||||
describe('generateSkillMetadata', () => {
|
||||
it('should generate skill metadata', () => {
|
||||
manager.setConfig({
|
||||
files: [{ pattern: '*.ts', level: 'allow' }],
|
||||
default: 'deny',
|
||||
});
|
||||
|
||||
const metadata = manager.generateSkillMetadata();
|
||||
|
||||
expect(metadata.filePermissions).toHaveLength(1);
|
||||
expect(metadata.defaultPermission).toBe('deny');
|
||||
});
|
||||
});
|
||||
|
||||
describe('fromMetadata', () => {
|
||||
it('should parse permissions from metadata', () => {
|
||||
const metadata = {
|
||||
filePermissions: [{ pattern: '*.ts', level: 'allow' }],
|
||||
defaultPermission: 'ask',
|
||||
};
|
||||
|
||||
const config = PermissionManager.fromMetadata(metadata);
|
||||
|
||||
expect(config.files).toHaveLength(1);
|
||||
expect(config.default).toBe('ask');
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
describe('Permission helpers', () => {
|
||||
it('isAllowed should work correctly', () => {
|
||||
expect(isAllowed('allow')).toBe(true);
|
||||
expect(isAllowed('deny')).toBe(false);
|
||||
expect(isAllowed('ask')).toBe(false);
|
||||
});
|
||||
|
||||
it('isDenied should work correctly', () => {
|
||||
expect(isDenied('deny')).toBe(true);
|
||||
expect(isDenied('allow')).toBe(false);
|
||||
});
|
||||
|
||||
it('needsConfirmation should work correctly', () => {
|
||||
expect(needsConfirmation('ask')).toBe(true);
|
||||
expect(needsConfirmation('allow')).toBe(false);
|
||||
});
|
||||
});
|
||||
|
||||
describe('GlobMatcher', () => {
|
||||
let matcher: GlobMatcher;
|
||||
|
||||
describe('matches', () => {
|
||||
it('should match simple patterns', () => {
|
||||
matcher = createGlobMatcher({ include: ['*.ts'] });
|
||||
|
||||
expect(matcher.matches('app.ts')).toBe(true);
|
||||
expect(matcher.matches('app.js')).toBe(false);
|
||||
});
|
||||
|
||||
it('should match wildcard patterns', () => {
|
||||
matcher = createGlobMatcher({ include: ['src/**/*.ts'] });
|
||||
|
||||
expect(matcher.matches('src/app.ts')).toBe(true);
|
||||
expect(matcher.matches('src/components/Button.ts')).toBe(true);
|
||||
expect(matcher.matches('lib/app.ts')).toBe(false);
|
||||
});
|
||||
|
||||
it('should respect exclude patterns', () => {
|
||||
matcher = createGlobMatcher({
|
||||
include: ['**/*.ts'],
|
||||
exclude: ['**/*.test.ts'],
|
||||
});
|
||||
|
||||
expect(matcher.matches('app.ts')).toBe(true);
|
||||
expect(matcher.matches('app.test.ts')).toBe(false);
|
||||
});
|
||||
|
||||
it('should skip hidden files by default', () => {
|
||||
matcher = createGlobMatcher({ include: ['**/*'] });
|
||||
|
||||
expect(matcher.matches('.hidden/file.ts')).toBe(false);
|
||||
});
|
||||
|
||||
it('should match hidden files when enabled', () => {
|
||||
matcher = createGlobMatcher({
|
||||
include: ['**/*'],
|
||||
matchHidden: true,
|
||||
});
|
||||
|
||||
expect(matcher.matches('.hidden/file.ts')).toBe(true);
|
||||
});
|
||||
});
|
||||
|
||||
describe('filter', () => {
|
||||
it('should filter file list', () => {
|
||||
matcher = createGlobMatcher({ include: ['*.ts'] });
|
||||
|
||||
const files = ['app.ts', 'app.js', 'index.ts'];
|
||||
const result = matcher.filter(files);
|
||||
|
||||
expect(result).toEqual(['app.ts', 'index.ts']);
|
||||
});
|
||||
});
|
||||
|
||||
describe('addInclude', () => {
|
||||
it('should add include pattern', () => {
|
||||
matcher = createGlobMatcher({ include: ['*.ts'] });
|
||||
matcher.addInclude('*.js');
|
||||
|
||||
expect(matcher.matches('app.js')).toBe(true);
|
||||
});
|
||||
});
|
||||
|
||||
describe('generateCursorGlobs', () => {
|
||||
it('should generate Cursor-compatible globs', () => {
|
||||
matcher = createGlobMatcher({
|
||||
include: ['src/**/*.ts'],
|
||||
exclude: ['**/*.test.ts'],
|
||||
});
|
||||
|
||||
const globs = matcher.generateCursorGlobs();
|
||||
|
||||
expect(globs).toContain('src/**/*.ts');
|
||||
expect(globs).toContain('!**/*.test.ts');
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
describe('matchPattern', () => {
|
||||
it('should create matcher from single pattern', () => {
|
||||
const matcher = matchPattern('*.ts');
|
||||
|
||||
expect(matcher.matches('app.ts')).toBe(true);
|
||||
});
|
||||
});
|
||||
|
||||
describe('parseGlobsFromMDC', () => {
|
||||
it('should parse globs from MDC content', () => {
|
||||
const content = `---
|
||||
globs: ["**/*.ts", "!**/*.test.ts"]
|
||||
---
|
||||
Content here`;
|
||||
|
||||
const config = parseGlobsFromMDC(content);
|
||||
|
||||
expect(config?.include).toContain('**/*.ts');
|
||||
expect(config?.exclude).toContain('**/*.test.ts');
|
||||
});
|
||||
|
||||
it('should return null for invalid content', () => {
|
||||
const result = parseGlobsFromMDC('no globs here');
|
||||
|
||||
expect(result).toBeNull();
|
||||
});
|
||||
});
|
||||
|
||||
describe('fromCommonPatterns', () => {
|
||||
it('should create config from common patterns', () => {
|
||||
const config = fromCommonPatterns(['typescript', 'source'], ['nodeModules']);
|
||||
|
||||
expect(config.include).toContain('**/*.ts');
|
||||
expect(config.include).toContain('src/**/*');
|
||||
expect(config.exclude).toContain('**/node_modules/**');
|
||||
});
|
||||
});
|
||||
|
||||
describe('COMMON_PATTERNS', () => {
|
||||
it('should have expected patterns', () => {
|
||||
expect(COMMON_PATTERNS.typescript).toContain('**/*.ts');
|
||||
expect(COMMON_PATTERNS.tests).toContain('**/*.test.*');
|
||||
expect(COMMON_PATTERNS.nodeModules).toContain('**/node_modules/**');
|
||||
});
|
||||
});
|
||||
|
||||
describe('BootstrapManager', () => {
|
||||
let manager: BootstrapManager;
|
||||
|
||||
beforeEach(() => {
|
||||
manager = createBootstrapManager();
|
||||
});
|
||||
|
||||
describe('addFile/getFile', () => {
|
||||
it('should add and get files', () => {
|
||||
manager.addFile({
|
||||
type: 'agents',
|
||||
name: 'AGENTS.md',
|
||||
content: '# Agents',
|
||||
priority: 100,
|
||||
});
|
||||
|
||||
const file = manager.getFile('agents');
|
||||
|
||||
expect(file).toBeDefined();
|
||||
expect(file?.name).toBe('AGENTS.md');
|
||||
});
|
||||
});
|
||||
|
||||
describe('getFilesByPriority', () => {
|
||||
it('should return files sorted by priority', () => {
|
||||
manager.addFile({ type: 'tools', name: 'TOOLS.md', content: '', priority: 10 });
|
||||
manager.addFile({ type: 'agents', name: 'AGENTS.md', content: '', priority: 100 });
|
||||
manager.addFile({ type: 'soul', name: 'SOUL.md', content: '', priority: 50 });
|
||||
|
||||
const files = manager.getFilesByPriority();
|
||||
|
||||
expect(files[0].type).toBe('agents');
|
||||
expect(files[1].type).toBe('soul');
|
||||
expect(files[2].type).toBe('tools');
|
||||
});
|
||||
});
|
||||
|
||||
describe('createAgentsFile', () => {
|
||||
it('should create AGENTS.md', () => {
|
||||
manager.createAgentsFile([
|
||||
{
|
||||
name: 'Coder',
|
||||
description: 'A coding agent',
|
||||
capabilities: ['Write code', 'Debug'],
|
||||
},
|
||||
]);
|
||||
|
||||
const file = manager.getFile('agents');
|
||||
|
||||
expect(file).toBeDefined();
|
||||
expect(file?.content).toContain('# Agents');
|
||||
expect(file?.content).toContain('## Coder');
|
||||
expect(file?.content).toContain('Write code');
|
||||
});
|
||||
});
|
||||
|
||||
describe('createSoulFile', () => {
|
||||
it('should create SOUL.md', () => {
|
||||
manager.createSoulFile({
|
||||
personality: 'Helpful and precise',
|
||||
values: ['Accuracy', 'Efficiency'],
|
||||
});
|
||||
|
||||
const file = manager.getFile('soul');
|
||||
|
||||
expect(file).toBeDefined();
|
||||
expect(file?.content).toContain('Helpful and precise');
|
||||
expect(file?.content).toContain('Accuracy');
|
||||
});
|
||||
});
|
||||
|
||||
describe('createToolsFile', () => {
|
||||
it('should create TOOLS.md', () => {
|
||||
manager.createToolsFile([
|
||||
{
|
||||
name: 'read_file',
|
||||
description: 'Read a file',
|
||||
usage: 'read_file(path)',
|
||||
},
|
||||
]);
|
||||
|
||||
const file = manager.getFile('tools');
|
||||
|
||||
expect(file).toBeDefined();
|
||||
expect(file?.content).toContain('## read_file');
|
||||
expect(file?.content).toContain('read_file(path)');
|
||||
});
|
||||
});
|
||||
|
||||
describe('generateCombinedContent', () => {
|
||||
it('should generate combined content', () => {
|
||||
manager.addFile({ type: 'agents', name: 'AGENTS.md', content: '# Agents', priority: 100 });
|
||||
manager.addFile({ type: 'soul', name: 'SOUL.md', content: '# Soul', priority: 50 });
|
||||
|
||||
const combined = manager.generateCombinedContent();
|
||||
|
||||
expect(combined).toContain('<!-- AGENTS.md -->');
|
||||
expect(combined).toContain('# Agents');
|
||||
expect(combined).toContain('<!-- SOUL.md -->');
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
describe('createBootstrapSet', () => {
|
||||
it('should create complete bootstrap set', () => {
|
||||
const manager = createBootstrapSet({
|
||||
agents: [{ name: 'Test Agent' }],
|
||||
soul: { personality: 'Friendly' },
|
||||
tools: [{ name: 'tool1' }],
|
||||
});
|
||||
|
||||
expect(manager.hasFile('agents')).toBe(true);
|
||||
expect(manager.hasFile('soul')).toBe(true);
|
||||
expect(manager.hasFile('tools')).toBe(true);
|
||||
});
|
||||
});
|
||||
|
||||
describe('ModeManager', () => {
|
||||
let manager: ModeManager;
|
||||
|
||||
beforeEach(() => {
|
||||
manager = createModeManager([
|
||||
{ mode: 'code', description: 'Coding mode', skills: ['tdd', 'debugging'] },
|
||||
{ mode: 'architect', description: 'Architecture mode', skills: ['planning'] },
|
||||
]);
|
||||
});
|
||||
|
||||
describe('addMode/getMode', () => {
|
||||
it('should add and get modes', () => {
|
||||
const mode = manager.getMode('code');
|
||||
|
||||
expect(mode).toBeDefined();
|
||||
expect(mode?.description).toBe('Coding mode');
|
||||
expect(mode?.skills).toContain('tdd');
|
||||
});
|
||||
});
|
||||
|
||||
describe('getAvailableModes', () => {
|
||||
it('should return available modes', () => {
|
||||
const modes = manager.getAvailableModes();
|
||||
|
||||
expect(modes).toContain('code');
|
||||
expect(modes).toContain('architect');
|
||||
});
|
||||
});
|
||||
|
||||
describe('setMode/getCurrentMode', () => {
|
||||
it('should set and get current mode', () => {
|
||||
manager.setMode('architect');
|
||||
|
||||
expect(manager.getCurrentMode()).toBe('architect');
|
||||
});
|
||||
|
||||
it('should throw for unconfigured mode', () => {
|
||||
expect(() => manager.setMode('debug')).toThrow('Mode not configured');
|
||||
});
|
||||
});
|
||||
|
||||
describe('getCurrentSkills', () => {
|
||||
it('should return skills for current mode', () => {
|
||||
manager.setMode('code');
|
||||
|
||||
const skills = manager.getCurrentSkills();
|
||||
|
||||
expect(skills).toContain('tdd');
|
||||
expect(skills).toContain('debugging');
|
||||
});
|
||||
});
|
||||
|
||||
describe('isSkillAvailable', () => {
|
||||
it('should check if skill is available', () => {
|
||||
manager.setMode('code');
|
||||
|
||||
expect(manager.isSkillAvailable('tdd')).toBe(true);
|
||||
expect(manager.isSkillAvailable('planning')).toBe(false);
|
||||
});
|
||||
});
|
||||
|
||||
describe('isFileAllowed', () => {
|
||||
it('should return true when no patterns defined', () => {
|
||||
expect(manager.isFileAllowed('any/file.ts')).toBe(true);
|
||||
});
|
||||
|
||||
it('should check file patterns when defined', () => {
|
||||
manager.addMode({
|
||||
mode: 'restricted',
|
||||
description: 'Restricted mode',
|
||||
skills: [],
|
||||
allowedFiles: ['src/**/*'],
|
||||
});
|
||||
manager.setMode('restricted');
|
||||
|
||||
expect(manager.isFileAllowed('src/app.ts')).toBe(true);
|
||||
expect(manager.isFileAllowed('lib/util.ts')).toBe(false);
|
||||
});
|
||||
});
|
||||
|
||||
describe('addModeListener', () => {
|
||||
it('should notify listeners on mode change', () => {
|
||||
let notified = false;
|
||||
let newModeValue = '';
|
||||
|
||||
manager.addModeListener((newMode) => {
|
||||
notified = true;
|
||||
newModeValue = newMode;
|
||||
});
|
||||
|
||||
manager.setMode('architect');
|
||||
|
||||
expect(notified).toBe(true);
|
||||
expect(newModeValue).toBe('architect');
|
||||
});
|
||||
});
|
||||
|
||||
describe('generateRooConfig', () => {
|
||||
it('should generate Roo-compatible config', () => {
|
||||
const config = manager.generateRooConfig();
|
||||
|
||||
expect(config.defaultMode).toBe('code');
|
||||
expect(config.modes).toBeDefined();
|
||||
});
|
||||
});
|
||||
|
||||
describe('generateModeDocumentation', () => {
|
||||
it('should generate mode documentation', () => {
|
||||
const docs = manager.generateModeDocumentation();
|
||||
|
||||
expect(docs).toContain('# Available Modes');
|
||||
expect(docs).toContain('## code');
|
||||
expect(docs).toContain('## architect');
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
describe('createDefaultModeManager', () => {
|
||||
it('should create manager with default modes', () => {
|
||||
const manager = createDefaultModeManager({
|
||||
code: ['tdd'],
|
||||
debug: ['debugging'],
|
||||
});
|
||||
|
||||
const modes = manager.getAvailableModes();
|
||||
|
||||
expect(modes.length).toBe(7); // All default modes
|
||||
expect(manager.getMode('code')?.skills).toContain('tdd');
|
||||
});
|
||||
});
|
||||
|
||||
describe('ALL_MODES', () => {
|
||||
it('should contain all mode types', () => {
|
||||
expect(ALL_MODES).toContain('code');
|
||||
expect(ALL_MODES).toContain('architect');
|
||||
expect(ALL_MODES).toContain('debug');
|
||||
expect(ALL_MODES).toContain('test');
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,434 @@
|
||||
/**
|
||||
* Bootstrap Files System
|
||||
*
|
||||
* Implements bootstrap file generation for agents that support them.
|
||||
*/
|
||||
|
||||
import type {
|
||||
BootstrapFile,
|
||||
BootstrapFileType,
|
||||
} from './types.js';
|
||||
|
||||
/**
|
||||
* Default bootstrap file names for each type
|
||||
*/
|
||||
const DEFAULT_FILE_NAMES: Record<BootstrapFileType, string> = {
|
||||
agents: 'AGENTS.md',
|
||||
soul: 'SOUL.md',
|
||||
tools: 'TOOLS.md',
|
||||
identity: 'IDENTITY.md',
|
||||
context: 'CONTEXT.md',
|
||||
brief: 'BRIEF.md',
|
||||
history: 'HISTORY.md',
|
||||
};
|
||||
|
||||
/**
|
||||
* BootstrapManager - Manage bootstrap files for agents
|
||||
*/
|
||||
export class BootstrapManager {
|
||||
private files: Map<BootstrapFileType, BootstrapFile> = new Map();
|
||||
|
||||
/**
|
||||
* Add a bootstrap file
|
||||
*/
|
||||
addFile(file: BootstrapFile): void {
|
||||
this.files.set(file.type, file);
|
||||
}
|
||||
|
||||
/**
|
||||
* Get a bootstrap file by type
|
||||
*/
|
||||
getFile(type: BootstrapFileType): BootstrapFile | undefined {
|
||||
return this.files.get(type);
|
||||
}
|
||||
|
||||
/**
|
||||
* Get all bootstrap files
|
||||
*/
|
||||
getAllFiles(): BootstrapFile[] {
|
||||
return Array.from(this.files.values());
|
||||
}
|
||||
|
||||
/**
|
||||
* Get files sorted by priority
|
||||
*/
|
||||
getFilesByPriority(): BootstrapFile[] {
|
||||
return this.getAllFiles().sort((a, b) => (b.priority || 0) - (a.priority || 0));
|
||||
}
|
||||
|
||||
/**
|
||||
* Remove a bootstrap file
|
||||
*/
|
||||
removeFile(type: BootstrapFileType): boolean {
|
||||
return this.files.delete(type);
|
||||
}
|
||||
|
||||
/**
|
||||
* Check if a file type exists
|
||||
*/
|
||||
hasFile(type: BootstrapFileType): boolean {
|
||||
return this.files.has(type);
|
||||
}
|
||||
|
||||
/**
|
||||
* Create AGENTS.md file
|
||||
*/
|
||||
createAgentsFile(agents: AgentDefinition[]): void {
|
||||
const lines: string[] = [];
|
||||
|
||||
lines.push('# Agents');
|
||||
lines.push('');
|
||||
lines.push('This file defines the available agents and their capabilities.');
|
||||
lines.push('');
|
||||
|
||||
for (const agent of agents) {
|
||||
lines.push(`## ${agent.name}`);
|
||||
lines.push('');
|
||||
if (agent.description) {
|
||||
lines.push(agent.description);
|
||||
lines.push('');
|
||||
}
|
||||
if (agent.capabilities && agent.capabilities.length > 0) {
|
||||
lines.push('### Capabilities');
|
||||
lines.push('');
|
||||
for (const cap of agent.capabilities) {
|
||||
lines.push(`- ${cap}`);
|
||||
}
|
||||
lines.push('');
|
||||
}
|
||||
if (agent.constraints && agent.constraints.length > 0) {
|
||||
lines.push('### Constraints');
|
||||
lines.push('');
|
||||
for (const constraint of agent.constraints) {
|
||||
lines.push(`- ${constraint}`);
|
||||
}
|
||||
lines.push('');
|
||||
}
|
||||
}
|
||||
|
||||
this.addFile({
|
||||
type: 'agents',
|
||||
name: 'AGENTS.md',
|
||||
content: lines.join('\n'),
|
||||
priority: 100,
|
||||
required: true,
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
* Create SOUL.md file
|
||||
*/
|
||||
createSoulFile(soul: SoulDefinition): void {
|
||||
const lines: string[] = [];
|
||||
|
||||
lines.push('# Soul');
|
||||
lines.push('');
|
||||
lines.push('This file defines the personality and behavior of the agent.');
|
||||
lines.push('');
|
||||
|
||||
if (soul.personality) {
|
||||
lines.push('## Personality');
|
||||
lines.push('');
|
||||
lines.push(soul.personality);
|
||||
lines.push('');
|
||||
}
|
||||
|
||||
if (soul.values && soul.values.length > 0) {
|
||||
lines.push('## Values');
|
||||
lines.push('');
|
||||
for (const value of soul.values) {
|
||||
lines.push(`- ${value}`);
|
||||
}
|
||||
lines.push('');
|
||||
}
|
||||
|
||||
if (soul.communication) {
|
||||
lines.push('## Communication Style');
|
||||
lines.push('');
|
||||
lines.push(soul.communication);
|
||||
lines.push('');
|
||||
}
|
||||
|
||||
if (soul.rules && soul.rules.length > 0) {
|
||||
lines.push('## Rules');
|
||||
lines.push('');
|
||||
for (const rule of soul.rules) {
|
||||
lines.push(`- ${rule}`);
|
||||
}
|
||||
lines.push('');
|
||||
}
|
||||
|
||||
this.addFile({
|
||||
type: 'soul',
|
||||
name: 'SOUL.md',
|
||||
content: lines.join('\n'),
|
||||
priority: 90,
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
* Create TOOLS.md file
|
||||
*/
|
||||
createToolsFile(tools: ToolDefinition[]): void {
|
||||
const lines: string[] = [];
|
||||
|
||||
lines.push('# Tools');
|
||||
lines.push('');
|
||||
lines.push('This file defines the available tools and their usage.');
|
||||
lines.push('');
|
||||
|
||||
for (const tool of tools) {
|
||||
lines.push(`## ${tool.name}`);
|
||||
lines.push('');
|
||||
if (tool.description) {
|
||||
lines.push(tool.description);
|
||||
lines.push('');
|
||||
}
|
||||
if (tool.usage) {
|
||||
lines.push('### Usage');
|
||||
lines.push('');
|
||||
lines.push('```');
|
||||
lines.push(tool.usage);
|
||||
lines.push('```');
|
||||
lines.push('');
|
||||
}
|
||||
if (tool.examples && tool.examples.length > 0) {
|
||||
lines.push('### Examples');
|
||||
lines.push('');
|
||||
for (const example of tool.examples) {
|
||||
lines.push(`- ${example}`);
|
||||
}
|
||||
lines.push('');
|
||||
}
|
||||
}
|
||||
|
||||
this.addFile({
|
||||
type: 'tools',
|
||||
name: 'TOOLS.md',
|
||||
content: lines.join('\n'),
|
||||
priority: 80,
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
* Create IDENTITY.md file
|
||||
*/
|
||||
createIdentityFile(identity: IdentityDefinition): void {
|
||||
const lines: string[] = [];
|
||||
|
||||
lines.push('# Identity');
|
||||
lines.push('');
|
||||
|
||||
if (identity.name) {
|
||||
lines.push(`**Name:** ${identity.name}`);
|
||||
lines.push('');
|
||||
}
|
||||
|
||||
if (identity.role) {
|
||||
lines.push(`**Role:** ${identity.role}`);
|
||||
lines.push('');
|
||||
}
|
||||
|
||||
if (identity.description) {
|
||||
lines.push('## Description');
|
||||
lines.push('');
|
||||
lines.push(identity.description);
|
||||
lines.push('');
|
||||
}
|
||||
|
||||
if (identity.expertise && identity.expertise.length > 0) {
|
||||
lines.push('## Expertise');
|
||||
lines.push('');
|
||||
for (const exp of identity.expertise) {
|
||||
lines.push(`- ${exp}`);
|
||||
}
|
||||
lines.push('');
|
||||
}
|
||||
|
||||
this.addFile({
|
||||
type: 'identity',
|
||||
name: 'IDENTITY.md',
|
||||
content: lines.join('\n'),
|
||||
priority: 95,
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
* Create CONTEXT.md file
|
||||
*/
|
||||
createContextFile(context: ContextDefinition): void {
|
||||
const lines: string[] = [];
|
||||
|
||||
lines.push('# Context');
|
||||
lines.push('');
|
||||
|
||||
if (context.project) {
|
||||
lines.push('## Project');
|
||||
lines.push('');
|
||||
lines.push(context.project);
|
||||
lines.push('');
|
||||
}
|
||||
|
||||
if (context.techStack && context.techStack.length > 0) {
|
||||
lines.push('## Tech Stack');
|
||||
lines.push('');
|
||||
for (const tech of context.techStack) {
|
||||
lines.push(`- ${tech}`);
|
||||
}
|
||||
lines.push('');
|
||||
}
|
||||
|
||||
if (context.conventions && context.conventions.length > 0) {
|
||||
lines.push('## Conventions');
|
||||
lines.push('');
|
||||
for (const conv of context.conventions) {
|
||||
lines.push(`- ${conv}`);
|
||||
}
|
||||
lines.push('');
|
||||
}
|
||||
|
||||
if (context.currentTask) {
|
||||
lines.push('## Current Task');
|
||||
lines.push('');
|
||||
lines.push(context.currentTask);
|
||||
lines.push('');
|
||||
}
|
||||
|
||||
this.addFile({
|
||||
type: 'context',
|
||||
name: 'CONTEXT.md',
|
||||
content: lines.join('\n'),
|
||||
priority: 70,
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
* Generate all files as a map
|
||||
*/
|
||||
generateFiles(): Map<string, string> {
|
||||
const files = new Map<string, string>();
|
||||
|
||||
for (const file of this.getFilesByPriority()) {
|
||||
files.set(file.name, file.content);
|
||||
}
|
||||
|
||||
return files;
|
||||
}
|
||||
|
||||
/**
|
||||
* Generate combined content for agents without file support
|
||||
*/
|
||||
generateCombinedContent(): string {
|
||||
const lines: string[] = [];
|
||||
|
||||
for (const file of this.getFilesByPriority()) {
|
||||
lines.push(`<!-- ${file.name} -->`);
|
||||
lines.push('');
|
||||
lines.push(file.content);
|
||||
lines.push('');
|
||||
lines.push('---');
|
||||
lines.push('');
|
||||
}
|
||||
|
||||
return lines.join('\n');
|
||||
}
|
||||
|
||||
/**
|
||||
* Get default file name for a type
|
||||
*/
|
||||
static getDefaultFileName(type: BootstrapFileType): string {
|
||||
return DEFAULT_FILE_NAMES[type];
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Agent definition for AGENTS.md
|
||||
*/
|
||||
export interface AgentDefinition {
|
||||
name: string;
|
||||
description?: string;
|
||||
capabilities?: string[];
|
||||
constraints?: string[];
|
||||
}
|
||||
|
||||
/**
|
||||
* Soul definition for SOUL.md
|
||||
*/
|
||||
export interface SoulDefinition {
|
||||
personality?: string;
|
||||
values?: string[];
|
||||
communication?: string;
|
||||
rules?: string[];
|
||||
}
|
||||
|
||||
/**
|
||||
* Tool definition for TOOLS.md
|
||||
*/
|
||||
export interface ToolDefinition {
|
||||
name: string;
|
||||
description?: string;
|
||||
usage?: string;
|
||||
examples?: string[];
|
||||
}
|
||||
|
||||
/**
|
||||
* Identity definition for IDENTITY.md
|
||||
*/
|
||||
export interface IdentityDefinition {
|
||||
name?: string;
|
||||
role?: string;
|
||||
description?: string;
|
||||
expertise?: string[];
|
||||
}
|
||||
|
||||
/**
|
||||
* Context definition for CONTEXT.md
|
||||
*/
|
||||
export interface ContextDefinition {
|
||||
project?: string;
|
||||
techStack?: string[];
|
||||
conventions?: string[];
|
||||
currentTask?: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* Create a BootstrapManager instance
|
||||
*/
|
||||
export function createBootstrapManager(): BootstrapManager {
|
||||
return new BootstrapManager();
|
||||
}
|
||||
|
||||
/**
|
||||
* Create a complete bootstrap set from definitions
|
||||
*/
|
||||
export function createBootstrapSet(options: {
|
||||
agents?: AgentDefinition[];
|
||||
soul?: SoulDefinition;
|
||||
tools?: ToolDefinition[];
|
||||
identity?: IdentityDefinition;
|
||||
context?: ContextDefinition;
|
||||
}): BootstrapManager {
|
||||
const manager = new BootstrapManager();
|
||||
|
||||
if (options.agents) {
|
||||
manager.createAgentsFile(options.agents);
|
||||
}
|
||||
|
||||
if (options.soul) {
|
||||
manager.createSoulFile(options.soul);
|
||||
}
|
||||
|
||||
if (options.tools) {
|
||||
manager.createToolsFile(options.tools);
|
||||
}
|
||||
|
||||
if (options.identity) {
|
||||
manager.createIdentityFile(options.identity);
|
||||
}
|
||||
|
||||
if (options.context) {
|
||||
manager.createContextFile(options.context);
|
||||
}
|
||||
|
||||
return manager;
|
||||
}
|
||||
@@ -0,0 +1,240 @@
|
||||
/**
|
||||
* Glob Pattern System
|
||||
*
|
||||
* Implements file pattern matching for file-scoped skills.
|
||||
*/
|
||||
|
||||
import { minimatch } from 'minimatch';
|
||||
import type { GlobConfig } from './types.js';
|
||||
|
||||
/**
|
||||
* GlobMatcher - Match files against glob patterns
|
||||
*/
|
||||
export class GlobMatcher {
|
||||
private config: GlobConfig;
|
||||
private includePatterns: RegExp[];
|
||||
private excludePatterns: RegExp[];
|
||||
|
||||
constructor(config: GlobConfig) {
|
||||
this.config = config;
|
||||
this.includePatterns = config.include.map((p) => this.patternToRegex(p));
|
||||
this.excludePatterns = (config.exclude || []).map((p) => this.patternToRegex(p));
|
||||
}
|
||||
|
||||
/**
|
||||
* Check if a file matches the glob patterns
|
||||
*/
|
||||
matches(filePath: string): boolean {
|
||||
// Normalize path separators
|
||||
const normalizedPath = filePath.replace(/\\/g, '/');
|
||||
|
||||
// Check if hidden file and skip if not matching hidden
|
||||
if (!this.config.matchHidden && this.isHiddenFile(normalizedPath)) {
|
||||
return false;
|
||||
}
|
||||
|
||||
// Check exclude patterns first
|
||||
for (const pattern of this.excludePatterns) {
|
||||
if (pattern.test(normalizedPath)) {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
// Check include patterns
|
||||
for (const pattern of this.includePatterns) {
|
||||
if (pattern.test(normalizedPath)) {
|
||||
return true;
|
||||
}
|
||||
}
|
||||
|
||||
return false;
|
||||
}
|
||||
|
||||
/**
|
||||
* Filter a list of files
|
||||
*/
|
||||
filter(filePaths: string[]): string[] {
|
||||
return filePaths.filter((p) => this.matches(p));
|
||||
}
|
||||
|
||||
/**
|
||||
* Get all include patterns
|
||||
*/
|
||||
getIncludePatterns(): string[] {
|
||||
return [...this.config.include];
|
||||
}
|
||||
|
||||
/**
|
||||
* Get all exclude patterns
|
||||
*/
|
||||
getExcludePatterns(): string[] {
|
||||
return [...(this.config.exclude || [])];
|
||||
}
|
||||
|
||||
/**
|
||||
* Add an include pattern
|
||||
*/
|
||||
addInclude(pattern: string): void {
|
||||
this.config.include.push(pattern);
|
||||
this.includePatterns.push(this.patternToRegex(pattern));
|
||||
}
|
||||
|
||||
/**
|
||||
* Add an exclude pattern
|
||||
*/
|
||||
addExclude(pattern: string): void {
|
||||
if (!this.config.exclude) {
|
||||
this.config.exclude = [];
|
||||
}
|
||||
this.config.exclude.push(pattern);
|
||||
this.excludePatterns.push(this.patternToRegex(pattern));
|
||||
}
|
||||
|
||||
/**
|
||||
* Convert glob pattern to regex using minimatch
|
||||
*
|
||||
* Uses the battle-tested minimatch library to avoid ReDoS vulnerabilities
|
||||
* and ensure consistent glob matching behavior.
|
||||
*/
|
||||
private patternToRegex(pattern: string): RegExp {
|
||||
// Handle negation
|
||||
const isNegated = pattern.startsWith('!');
|
||||
const cleanPattern = isNegated ? pattern.slice(1) : pattern;
|
||||
|
||||
// Adjust pattern for directory matching
|
||||
let adjustedPattern = cleanPattern;
|
||||
if (this.config.matchDirectories && !cleanPattern.endsWith('/**')) {
|
||||
// Append /** to match directories and their contents
|
||||
adjustedPattern = cleanPattern.endsWith('/')
|
||||
? `${cleanPattern}**`
|
||||
: `${cleanPattern}/**`;
|
||||
}
|
||||
|
||||
// Use minimatch to create a safe regex
|
||||
// minimatch returns null if pattern is invalid, fallback to match-nothing regex
|
||||
const regex = minimatch.makeRe(adjustedPattern, { dot: this.config.matchHidden });
|
||||
|
||||
return regex || /(?!)/; // /(?!)/ is a regex that never matches anything
|
||||
}
|
||||
|
||||
/**
|
||||
* Check if file is hidden (starts with .)
|
||||
*/
|
||||
private isHiddenFile(path: string): boolean {
|
||||
const parts = path.split('/');
|
||||
return parts.some((part) => part.startsWith('.') && part !== '.' && part !== '..');
|
||||
}
|
||||
|
||||
/**
|
||||
* Generate Cursor-compatible globs field
|
||||
*/
|
||||
generateCursorGlobs(): string[] {
|
||||
const globs: string[] = [...this.config.include];
|
||||
|
||||
// Add negated exclude patterns
|
||||
if (this.config.exclude) {
|
||||
for (const pattern of this.config.exclude) {
|
||||
globs.push(`!${pattern}`);
|
||||
}
|
||||
}
|
||||
|
||||
return globs;
|
||||
}
|
||||
|
||||
/**
|
||||
* Generate MDC frontmatter
|
||||
*/
|
||||
generateMDCFrontmatter(): string {
|
||||
const globs = this.generateCursorGlobs();
|
||||
return `globs: ${JSON.stringify(globs)}`;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Create a GlobMatcher instance
|
||||
*/
|
||||
export function createGlobMatcher(config: GlobConfig): GlobMatcher {
|
||||
return new GlobMatcher(config);
|
||||
}
|
||||
|
||||
/**
|
||||
* Create a GlobMatcher from a single pattern
|
||||
*/
|
||||
export function matchPattern(pattern: string): GlobMatcher {
|
||||
return new GlobMatcher({ include: [pattern] });
|
||||
}
|
||||
|
||||
/**
|
||||
* Parse glob patterns from Cursor MDC format
|
||||
*/
|
||||
export function parseGlobsFromMDC(content: string): GlobConfig | null {
|
||||
const match = content.match(/globs:\s*(\[.*?\])/s);
|
||||
if (!match) {
|
||||
return null;
|
||||
}
|
||||
|
||||
try {
|
||||
const patterns = JSON.parse(match[1]) as string[];
|
||||
const include: string[] = [];
|
||||
const exclude: string[] = [];
|
||||
|
||||
for (const pattern of patterns) {
|
||||
if (pattern.startsWith('!')) {
|
||||
exclude.push(pattern.slice(1));
|
||||
} else {
|
||||
include.push(pattern);
|
||||
}
|
||||
}
|
||||
|
||||
return { include, exclude };
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Common glob patterns for different file types
|
||||
*/
|
||||
export const COMMON_PATTERNS = {
|
||||
/** All TypeScript files */
|
||||
typescript: ['**/*.ts', '**/*.tsx'],
|
||||
/** All JavaScript files */
|
||||
javascript: ['**/*.js', '**/*.jsx', '**/*.mjs', '**/*.cjs'],
|
||||
/** All test files */
|
||||
tests: ['**/*.test.*', '**/*.spec.*', '**/__tests__/**'],
|
||||
/** All config files */
|
||||
configs: ['*.config.*', '*rc', '*rc.*', '*.json', '*.yaml', '*.yml'],
|
||||
/** All source files */
|
||||
source: ['src/**/*'],
|
||||
/** All documentation */
|
||||
docs: ['**/*.md', 'docs/**/*', 'README*'],
|
||||
/** Node modules (usually excluded) */
|
||||
nodeModules: ['**/node_modules/**'],
|
||||
/** Build outputs (usually excluded) */
|
||||
buildOutputs: ['**/dist/**', '**/build/**', '**/.next/**'],
|
||||
/** All files */
|
||||
all: ['**/*'],
|
||||
} as const;
|
||||
|
||||
/**
|
||||
* Create glob config from common pattern names
|
||||
*/
|
||||
export function fromCommonPatterns(
|
||||
includeNames: (keyof typeof COMMON_PATTERNS)[],
|
||||
excludeNames?: (keyof typeof COMMON_PATTERNS)[]
|
||||
): GlobConfig {
|
||||
const include: string[] = [];
|
||||
const exclude: string[] = [];
|
||||
|
||||
for (const name of includeNames) {
|
||||
include.push(...COMMON_PATTERNS[name]);
|
||||
}
|
||||
|
||||
if (excludeNames) {
|
||||
for (const name of excludeNames) {
|
||||
exclude.push(...COMMON_PATTERNS[name]);
|
||||
}
|
||||
}
|
||||
|
||||
return { include, exclude };
|
||||
}
|
||||
@@ -0,0 +1,15 @@
|
||||
/**
|
||||
* Agent Features Module
|
||||
*
|
||||
* Enhanced agent-specific features including:
|
||||
* - Permissions system (OpenCode-style)
|
||||
* - Glob pattern matching (Cursor-style)
|
||||
* - Bootstrap files (Amp-style)
|
||||
* - Multi-mode support (Roo/Kilo-style)
|
||||
*/
|
||||
|
||||
export * from './types.js';
|
||||
export * from './permissions.js';
|
||||
export * from './globs.js';
|
||||
export * from './bootstrap.js';
|
||||
export * from './modes.js';
|
||||
@@ -0,0 +1,301 @@
|
||||
/**
|
||||
* Multi-Mode System
|
||||
*
|
||||
* Implements multi-mode support for agents that support different operating modes.
|
||||
*/
|
||||
|
||||
import type { AgentMode, ModeConfig } from './types.js';
|
||||
import { GlobMatcher } from './globs.js';
|
||||
|
||||
/**
|
||||
* Default mode configurations
|
||||
*/
|
||||
const DEFAULT_MODES: Record<AgentMode, Omit<ModeConfig, 'skills'>> = {
|
||||
code: {
|
||||
mode: 'code',
|
||||
description: 'Code editing and implementation mode',
|
||||
promptPrefix: 'You are in code mode. Focus on writing and editing code.',
|
||||
},
|
||||
architect: {
|
||||
mode: 'architect',
|
||||
description: 'Architecture and planning mode',
|
||||
promptPrefix: 'You are in architect mode. Focus on system design and planning.',
|
||||
},
|
||||
ask: {
|
||||
mode: 'ask',
|
||||
description: 'Question and answer mode',
|
||||
promptPrefix: 'You are in ask mode. Focus on answering questions clearly.',
|
||||
},
|
||||
debug: {
|
||||
mode: 'debug',
|
||||
description: 'Debugging and troubleshooting mode',
|
||||
promptPrefix: 'You are in debug mode. Focus on finding and fixing issues.',
|
||||
},
|
||||
review: {
|
||||
mode: 'review',
|
||||
description: 'Code review mode',
|
||||
promptPrefix: 'You are in review mode. Focus on reviewing code quality.',
|
||||
},
|
||||
test: {
|
||||
mode: 'test',
|
||||
description: 'Testing mode',
|
||||
promptPrefix: 'You are in test mode. Focus on writing and running tests.',
|
||||
},
|
||||
docs: {
|
||||
mode: 'docs',
|
||||
description: 'Documentation mode',
|
||||
promptPrefix: 'You are in docs mode. Focus on writing documentation.',
|
||||
},
|
||||
};
|
||||
|
||||
/**
|
||||
* ModeManager - Manage agent operating modes
|
||||
*/
|
||||
export class ModeManager {
|
||||
private modes: Map<AgentMode, ModeConfig> = new Map();
|
||||
private currentMode: AgentMode = 'code';
|
||||
private modeListeners: Set<ModeChangeListener> = new Set();
|
||||
|
||||
constructor(modes?: ModeConfig[]) {
|
||||
if (modes) {
|
||||
for (const mode of modes) {
|
||||
this.addMode(mode);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Add a mode configuration
|
||||
*/
|
||||
addMode(config: ModeConfig): void {
|
||||
this.modes.set(config.mode, config);
|
||||
}
|
||||
|
||||
/**
|
||||
* Get a mode configuration
|
||||
*/
|
||||
getMode(mode: AgentMode): ModeConfig | undefined {
|
||||
return this.modes.get(mode);
|
||||
}
|
||||
|
||||
/**
|
||||
* Get all mode configurations
|
||||
*/
|
||||
getAllModes(): ModeConfig[] {
|
||||
return Array.from(this.modes.values());
|
||||
}
|
||||
|
||||
/**
|
||||
* Get available mode names
|
||||
*/
|
||||
getAvailableModes(): AgentMode[] {
|
||||
return Array.from(this.modes.keys());
|
||||
}
|
||||
|
||||
/**
|
||||
* Set the current mode
|
||||
*/
|
||||
setMode(mode: AgentMode): void {
|
||||
const config = this.modes.get(mode);
|
||||
if (!config) {
|
||||
throw new Error(`Mode not configured: ${mode}`);
|
||||
}
|
||||
|
||||
const previousMode = this.currentMode;
|
||||
this.currentMode = mode;
|
||||
|
||||
// Notify listeners
|
||||
for (const listener of this.modeListeners) {
|
||||
listener(mode, previousMode, config);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Get the current mode
|
||||
*/
|
||||
getCurrentMode(): AgentMode {
|
||||
return this.currentMode;
|
||||
}
|
||||
|
||||
/**
|
||||
* Get current mode configuration
|
||||
*/
|
||||
getCurrentModeConfig(): ModeConfig | undefined {
|
||||
return this.modes.get(this.currentMode);
|
||||
}
|
||||
|
||||
/**
|
||||
* Get skills for current mode
|
||||
*/
|
||||
getCurrentSkills(): string[] {
|
||||
const config = this.getCurrentModeConfig();
|
||||
return config?.skills || [];
|
||||
}
|
||||
|
||||
/**
|
||||
* Get tools for current mode
|
||||
*/
|
||||
getCurrentTools(): string[] {
|
||||
const config = this.getCurrentModeConfig();
|
||||
return config?.tools || [];
|
||||
}
|
||||
|
||||
/**
|
||||
* Check if a skill is available in current mode
|
||||
*/
|
||||
isSkillAvailable(skillName: string): boolean {
|
||||
const skills = this.getCurrentSkills();
|
||||
return skills.length === 0 || skills.includes(skillName);
|
||||
}
|
||||
|
||||
/**
|
||||
* Check if a file is allowed in current mode
|
||||
*/
|
||||
isFileAllowed(filePath: string): boolean {
|
||||
const config = this.getCurrentModeConfig();
|
||||
if (!config?.allowedFiles || config.allowedFiles.length === 0) {
|
||||
return true;
|
||||
}
|
||||
|
||||
const matcher = new GlobMatcher({ include: config.allowedFiles });
|
||||
return matcher.matches(filePath);
|
||||
}
|
||||
|
||||
/**
|
||||
* Add mode change listener
|
||||
*/
|
||||
addModeListener(listener: ModeChangeListener): void {
|
||||
this.modeListeners.add(listener);
|
||||
}
|
||||
|
||||
/**
|
||||
* Remove mode change listener
|
||||
*/
|
||||
removeModeListener(listener: ModeChangeListener): void {
|
||||
this.modeListeners.delete(listener);
|
||||
}
|
||||
|
||||
/**
|
||||
* Create a mode from default configuration
|
||||
*/
|
||||
addDefaultMode(mode: AgentMode, skills: string[]): void {
|
||||
const defaultConfig = DEFAULT_MODES[mode];
|
||||
this.addMode({
|
||||
...defaultConfig,
|
||||
skills,
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
* Generate mode-specific prompt prefix
|
||||
*/
|
||||
getPromptPrefix(): string {
|
||||
const config = this.getCurrentModeConfig();
|
||||
return config?.promptPrefix || '';
|
||||
}
|
||||
|
||||
/**
|
||||
* Generate Roo-compatible mode configuration
|
||||
*/
|
||||
generateRooConfig(): Record<string, unknown> {
|
||||
const modes: Record<string, unknown> = {};
|
||||
|
||||
for (const config of this.modes.values()) {
|
||||
modes[config.mode] = {
|
||||
description: config.description,
|
||||
skills: config.skills,
|
||||
tools: config.tools,
|
||||
promptPrefix: config.promptPrefix,
|
||||
};
|
||||
}
|
||||
|
||||
return {
|
||||
defaultMode: this.currentMode,
|
||||
modes,
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Generate mode documentation
|
||||
*/
|
||||
generateModeDocumentation(): string {
|
||||
const lines: string[] = [];
|
||||
|
||||
lines.push('# Available Modes');
|
||||
lines.push('');
|
||||
|
||||
for (const config of this.modes.values()) {
|
||||
lines.push(`## ${config.mode}`);
|
||||
lines.push('');
|
||||
lines.push(config.description);
|
||||
lines.push('');
|
||||
|
||||
if (config.skills.length > 0) {
|
||||
lines.push('### Skills');
|
||||
lines.push('');
|
||||
for (const skill of config.skills) {
|
||||
lines.push(`- ${skill}`);
|
||||
}
|
||||
lines.push('');
|
||||
}
|
||||
|
||||
if (config.tools && config.tools.length > 0) {
|
||||
lines.push('### Tools');
|
||||
lines.push('');
|
||||
for (const tool of config.tools) {
|
||||
lines.push(`- ${tool}`);
|
||||
}
|
||||
lines.push('');
|
||||
}
|
||||
}
|
||||
|
||||
return lines.join('\n');
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Mode change listener type
|
||||
*/
|
||||
export type ModeChangeListener = (
|
||||
newMode: AgentMode,
|
||||
previousMode: AgentMode,
|
||||
config: ModeConfig
|
||||
) => void;
|
||||
|
||||
/**
|
||||
* Create a ModeManager instance
|
||||
*/
|
||||
export function createModeManager(modes?: ModeConfig[]): ModeManager {
|
||||
return new ModeManager(modes);
|
||||
}
|
||||
|
||||
/**
|
||||
* Create a ModeManager with all default modes
|
||||
*/
|
||||
export function createDefaultModeManager(
|
||||
skillsPerMode: Partial<Record<AgentMode, string[]>>
|
||||
): ModeManager {
|
||||
const manager = new ModeManager();
|
||||
|
||||
for (const [mode, config] of Object.entries(DEFAULT_MODES)) {
|
||||
const skills = skillsPerMode[mode as AgentMode] || [];
|
||||
manager.addMode({
|
||||
...config,
|
||||
skills,
|
||||
});
|
||||
}
|
||||
|
||||
return manager;
|
||||
}
|
||||
|
||||
/**
|
||||
* Get default configuration for a mode
|
||||
*/
|
||||
export function getDefaultModeConfig(mode: AgentMode): Omit<ModeConfig, 'skills'> {
|
||||
return DEFAULT_MODES[mode];
|
||||
}
|
||||
|
||||
/**
|
||||
* All available agent modes
|
||||
*/
|
||||
export const ALL_MODES: AgentMode[] = ['code', 'architect', 'ask', 'debug', 'review', 'test', 'docs'];
|
||||
@@ -0,0 +1,262 @@
|
||||
/**
|
||||
* Permissions System
|
||||
*
|
||||
* Implements permission patterns for agent skill access control.
|
||||
*/
|
||||
|
||||
import { minimatch } from 'minimatch';
|
||||
import type {
|
||||
PermissionConfig,
|
||||
PermissionPattern,
|
||||
PermissionLevel,
|
||||
} from './types.js';
|
||||
|
||||
/**
|
||||
* PermissionManager - Manage skill permissions
|
||||
*/
|
||||
export class PermissionManager {
|
||||
private config: PermissionConfig;
|
||||
|
||||
constructor(config?: PermissionConfig) {
|
||||
this.config = config || { default: 'ask' };
|
||||
}
|
||||
|
||||
/**
|
||||
* Set permission configuration
|
||||
*/
|
||||
setConfig(config: PermissionConfig): void {
|
||||
this.config = config;
|
||||
}
|
||||
|
||||
/**
|
||||
* Get permission configuration
|
||||
*/
|
||||
getConfig(): PermissionConfig {
|
||||
return this.config;
|
||||
}
|
||||
|
||||
/**
|
||||
* Check file access permission
|
||||
*/
|
||||
checkFileAccess(path: string): PermissionLevel {
|
||||
return this.checkPattern(path, this.config.files);
|
||||
}
|
||||
|
||||
/**
|
||||
* Check command execution permission
|
||||
*/
|
||||
checkCommandAccess(command: string): PermissionLevel {
|
||||
return this.checkPattern(command, this.config.commands);
|
||||
}
|
||||
|
||||
/**
|
||||
* Check network access permission
|
||||
*/
|
||||
checkNetworkAccess(url: string): PermissionLevel {
|
||||
return this.checkPattern(url, this.config.network);
|
||||
}
|
||||
|
||||
/**
|
||||
* Check environment variable access
|
||||
*/
|
||||
checkEnvAccess(varName: string): PermissionLevel {
|
||||
return this.checkPattern(varName, this.config.env);
|
||||
}
|
||||
|
||||
/**
|
||||
* Add file permission pattern
|
||||
*/
|
||||
addFilePattern(pattern: PermissionPattern): void {
|
||||
if (!this.config.files) {
|
||||
this.config.files = [];
|
||||
}
|
||||
this.config.files.push(pattern);
|
||||
}
|
||||
|
||||
/**
|
||||
* Add command permission pattern
|
||||
*/
|
||||
addCommandPattern(pattern: PermissionPattern): void {
|
||||
if (!this.config.commands) {
|
||||
this.config.commands = [];
|
||||
}
|
||||
this.config.commands.push(pattern);
|
||||
}
|
||||
|
||||
/**
|
||||
* Check pattern against permission list
|
||||
*/
|
||||
private checkPattern(
|
||||
value: string,
|
||||
patterns?: PermissionPattern[]
|
||||
): PermissionLevel {
|
||||
if (!patterns || patterns.length === 0) {
|
||||
return this.config.default || 'ask';
|
||||
}
|
||||
|
||||
// Check patterns in order (first match wins)
|
||||
for (const pattern of patterns) {
|
||||
if (this.matchPattern(value, pattern.pattern)) {
|
||||
return pattern.level;
|
||||
}
|
||||
}
|
||||
|
||||
return this.config.default || 'ask';
|
||||
}
|
||||
|
||||
/**
|
||||
* Match value against pattern (glob-style)
|
||||
*
|
||||
* Uses minimatch for safe glob matching, avoiding ReDoS vulnerabilities.
|
||||
*/
|
||||
private matchPattern(value: string, pattern: string): boolean {
|
||||
// Use minimatch for safe, battle-tested glob matching
|
||||
// nocase option ensures case-insensitive matching
|
||||
return minimatch(value, pattern, { nocase: true });
|
||||
}
|
||||
|
||||
/**
|
||||
* Generate OpenCode-compatible permission config
|
||||
*/
|
||||
generateOpenCodeConfig(): string {
|
||||
const lines: string[] = [];
|
||||
|
||||
lines.push('# Permission Configuration');
|
||||
lines.push('');
|
||||
|
||||
if (this.config.files && this.config.files.length > 0) {
|
||||
lines.push('## File Access');
|
||||
lines.push('');
|
||||
for (const pattern of this.config.files) {
|
||||
lines.push(`- ${pattern.level}: \`${pattern.pattern}\``);
|
||||
if (pattern.reason) {
|
||||
lines.push(` - Reason: ${pattern.reason}`);
|
||||
}
|
||||
}
|
||||
lines.push('');
|
||||
}
|
||||
|
||||
if (this.config.commands && this.config.commands.length > 0) {
|
||||
lines.push('## Command Execution');
|
||||
lines.push('');
|
||||
for (const pattern of this.config.commands) {
|
||||
lines.push(`- ${pattern.level}: \`${pattern.pattern}\``);
|
||||
if (pattern.reason) {
|
||||
lines.push(` - Reason: ${pattern.reason}`);
|
||||
}
|
||||
}
|
||||
lines.push('');
|
||||
}
|
||||
|
||||
if (this.config.network && this.config.network.length > 0) {
|
||||
lines.push('## Network Access');
|
||||
lines.push('');
|
||||
for (const pattern of this.config.network) {
|
||||
lines.push(`- ${pattern.level}: \`${pattern.pattern}\``);
|
||||
if (pattern.reason) {
|
||||
lines.push(` - Reason: ${pattern.reason}`);
|
||||
}
|
||||
}
|
||||
lines.push('');
|
||||
}
|
||||
|
||||
lines.push(`Default: ${this.config.default || 'ask'}`);
|
||||
lines.push('');
|
||||
|
||||
return lines.join('\n');
|
||||
}
|
||||
|
||||
/**
|
||||
* Generate SKILL.md metadata for permissions
|
||||
*/
|
||||
generateSkillMetadata(): Record<string, unknown> {
|
||||
const metadata: Record<string, unknown> = {};
|
||||
|
||||
if (this.config.files) {
|
||||
metadata.filePermissions = this.config.files.map((p) => ({
|
||||
pattern: p.pattern,
|
||||
level: p.level,
|
||||
}));
|
||||
}
|
||||
|
||||
if (this.config.commands) {
|
||||
metadata.commandPermissions = this.config.commands.map((p) => ({
|
||||
pattern: p.pattern,
|
||||
level: p.level,
|
||||
}));
|
||||
}
|
||||
|
||||
if (this.config.network) {
|
||||
metadata.networkPermissions = this.config.network.map((p) => ({
|
||||
pattern: p.pattern,
|
||||
level: p.level,
|
||||
}));
|
||||
}
|
||||
|
||||
if (this.config.default) {
|
||||
metadata.defaultPermission = this.config.default;
|
||||
}
|
||||
|
||||
return metadata;
|
||||
}
|
||||
|
||||
/**
|
||||
* Parse permissions from SKILL.md metadata
|
||||
*/
|
||||
static fromMetadata(metadata: Record<string, unknown>): PermissionConfig {
|
||||
const config: PermissionConfig = {};
|
||||
|
||||
if (metadata.filePermissions && Array.isArray(metadata.filePermissions)) {
|
||||
config.files = metadata.filePermissions as PermissionPattern[];
|
||||
}
|
||||
|
||||
if (metadata.commandPermissions && Array.isArray(metadata.commandPermissions)) {
|
||||
config.commands = metadata.commandPermissions as PermissionPattern[];
|
||||
}
|
||||
|
||||
if (metadata.networkPermissions && Array.isArray(metadata.networkPermissions)) {
|
||||
config.network = metadata.networkPermissions as PermissionPattern[];
|
||||
}
|
||||
|
||||
if (metadata.defaultPermission) {
|
||||
config.default = metadata.defaultPermission as PermissionLevel;
|
||||
}
|
||||
|
||||
return config;
|
||||
}
|
||||
|
||||
/**
|
||||
* Merge two permission configs
|
||||
*/
|
||||
static merge(base: PermissionConfig, override: PermissionConfig): PermissionConfig {
|
||||
return {
|
||||
files: [...(base.files || []), ...(override.files || [])],
|
||||
commands: [...(base.commands || []), ...(override.commands || [])],
|
||||
network: [...(base.network || []), ...(override.network || [])],
|
||||
env: [...(base.env || []), ...(override.env || [])],
|
||||
default: override.default || base.default,
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Create a PermissionManager instance
|
||||
*/
|
||||
export function createPermissionManager(config?: PermissionConfig): PermissionManager {
|
||||
return new PermissionManager(config);
|
||||
}
|
||||
|
||||
/**
|
||||
* Quick permission check helpers
|
||||
*/
|
||||
export function isAllowed(level: PermissionLevel): boolean {
|
||||
return level === 'allow';
|
||||
}
|
||||
|
||||
export function isDenied(level: PermissionLevel): boolean {
|
||||
return level === 'deny';
|
||||
}
|
||||
|
||||
export function needsConfirmation(level: PermissionLevel): boolean {
|
||||
return level === 'ask';
|
||||
}
|
||||
@@ -0,0 +1,214 @@
|
||||
/**
|
||||
* Agent Features Types
|
||||
*
|
||||
* Type definitions for enhanced agent-specific features.
|
||||
*/
|
||||
|
||||
import type { AgentType } from '@skillkit/core';
|
||||
|
||||
/**
|
||||
* Permission level for agent actions
|
||||
*/
|
||||
export type PermissionLevel = 'allow' | 'deny' | 'ask';
|
||||
|
||||
/**
|
||||
* Permission pattern for file/resource access
|
||||
*/
|
||||
export interface PermissionPattern {
|
||||
/** Pattern to match (glob or regex) */
|
||||
pattern: string;
|
||||
/** Permission level */
|
||||
level: PermissionLevel;
|
||||
/** Description of why this permission is needed */
|
||||
reason?: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* Permission configuration for skills
|
||||
*/
|
||||
export interface PermissionConfig {
|
||||
/** File access permissions */
|
||||
files?: PermissionPattern[];
|
||||
/** Command execution permissions */
|
||||
commands?: PermissionPattern[];
|
||||
/** Network access permissions */
|
||||
network?: PermissionPattern[];
|
||||
/** Environment variable access */
|
||||
env?: PermissionPattern[];
|
||||
/** Default permission level */
|
||||
default?: PermissionLevel;
|
||||
}
|
||||
|
||||
/**
|
||||
* Glob pattern configuration for file-scoped skills
|
||||
*/
|
||||
export interface GlobConfig {
|
||||
/** Patterns to include */
|
||||
include: string[];
|
||||
/** Patterns to exclude */
|
||||
exclude?: string[];
|
||||
/** Whether to match directories */
|
||||
matchDirectories?: boolean;
|
||||
/** Whether to match hidden files */
|
||||
matchHidden?: boolean;
|
||||
}
|
||||
|
||||
/**
|
||||
* Bootstrap file types
|
||||
*/
|
||||
export type BootstrapFileType =
|
||||
| 'agents' // AGENTS.md - Agent definitions
|
||||
| 'soul' // SOUL.md - Personality and behavior
|
||||
| 'tools' // TOOLS.md - Available tools
|
||||
| 'identity' // IDENTITY.md - Agent identity
|
||||
| 'context' // CONTEXT.md - Context information
|
||||
| 'brief' // BRIEF.md - Project brief
|
||||
| 'history'; // HISTORY.md - Conversation history
|
||||
|
||||
/**
|
||||
* Bootstrap file configuration
|
||||
*/
|
||||
export interface BootstrapFile {
|
||||
/** File type */
|
||||
type: BootstrapFileType;
|
||||
/** File name */
|
||||
name: string;
|
||||
/** File content */
|
||||
content: string;
|
||||
/** Priority (higher = loaded first) */
|
||||
priority?: number;
|
||||
/** Whether file is required */
|
||||
required?: boolean;
|
||||
}
|
||||
|
||||
/**
|
||||
* Agent mode types
|
||||
*/
|
||||
export type AgentMode =
|
||||
| 'code' // Code editing mode
|
||||
| 'architect' // Architecture/planning mode
|
||||
| 'ask' // Question/answer mode
|
||||
| 'debug' // Debugging mode
|
||||
| 'review' // Code review mode
|
||||
| 'test' // Testing mode
|
||||
| 'docs'; // Documentation mode
|
||||
|
||||
/**
|
||||
* Mode configuration
|
||||
*/
|
||||
export interface ModeConfig {
|
||||
/** Mode name */
|
||||
mode: AgentMode;
|
||||
/** Mode description */
|
||||
description: string;
|
||||
/** Skills available in this mode */
|
||||
skills: string[];
|
||||
/** Tools available in this mode */
|
||||
tools?: string[];
|
||||
/** Default prompt prefix for this mode */
|
||||
promptPrefix?: string;
|
||||
/** Allowed file patterns in this mode */
|
||||
allowedFiles?: string[];
|
||||
}
|
||||
|
||||
/**
|
||||
* Tool whitelist configuration
|
||||
*/
|
||||
export interface ToolWhitelistConfig {
|
||||
/** Allowed tools */
|
||||
allowed: string[];
|
||||
/** Denied tools */
|
||||
denied?: string[];
|
||||
/** Mode for handling unlisted tools */
|
||||
unlisted?: 'allow' | 'deny' | 'ask';
|
||||
}
|
||||
|
||||
/**
|
||||
* Skill package configuration (for .skill bundles)
|
||||
*/
|
||||
export interface SkillPackageConfig {
|
||||
/** Package name */
|
||||
name: string;
|
||||
/** Package version */
|
||||
version: string;
|
||||
/** Package description */
|
||||
description?: string;
|
||||
/** Entry point skill */
|
||||
entryPoint: string;
|
||||
/** Included skill files */
|
||||
files: string[];
|
||||
/** Dependencies */
|
||||
dependencies?: string[];
|
||||
/** Metadata */
|
||||
metadata?: Record<string, unknown>;
|
||||
}
|
||||
|
||||
/**
|
||||
* Agent feature capabilities
|
||||
*/
|
||||
export interface AgentCapabilities {
|
||||
/** Supports permission system */
|
||||
permissions: boolean;
|
||||
/** Supports glob patterns */
|
||||
globs: boolean;
|
||||
/** Supports bootstrap files */
|
||||
bootstrapFiles: boolean;
|
||||
/** Supports multi-mode */
|
||||
multiMode: boolean;
|
||||
/** Supports tool whitelisting */
|
||||
toolWhitelist: boolean;
|
||||
/** Supports .skill packages */
|
||||
skillPackages: boolean;
|
||||
/** Supports hooks */
|
||||
hooks: boolean;
|
||||
/** Supports subagents */
|
||||
subagents: boolean;
|
||||
}
|
||||
|
||||
/**
|
||||
* Agent feature set
|
||||
*/
|
||||
export interface AgentFeatures {
|
||||
/** Agent type */
|
||||
agent: AgentType;
|
||||
/** Agent capabilities */
|
||||
capabilities: AgentCapabilities;
|
||||
/** Permission configuration */
|
||||
permissions?: PermissionConfig;
|
||||
/** Glob configuration */
|
||||
globs?: GlobConfig;
|
||||
/** Bootstrap files */
|
||||
bootstrapFiles?: BootstrapFile[];
|
||||
/** Mode configurations */
|
||||
modes?: ModeConfig[];
|
||||
/** Tool whitelist */
|
||||
toolWhitelist?: ToolWhitelistConfig;
|
||||
}
|
||||
|
||||
/**
|
||||
* Feature generation options
|
||||
*/
|
||||
export interface FeatureGenerationOptions {
|
||||
/** Target agent */
|
||||
agent: AgentType;
|
||||
/** Output directory */
|
||||
outputDir?: string;
|
||||
/** Include optional files */
|
||||
includeOptional?: boolean;
|
||||
/** Dry run (don't write files) */
|
||||
dryRun?: boolean;
|
||||
}
|
||||
|
||||
/**
|
||||
* Feature validation result
|
||||
*/
|
||||
export interface FeatureValidationResult {
|
||||
/** Whether features are valid */
|
||||
valid: boolean;
|
||||
/** Validation errors */
|
||||
errors: string[];
|
||||
/** Validation warnings */
|
||||
warnings: string[];
|
||||
/** Agent capabilities used */
|
||||
usedCapabilities: (keyof AgentCapabilities)[];
|
||||
}
|
||||
@@ -37,6 +37,9 @@ export * from './trae.js';
|
||||
export * from './windsurf.js';
|
||||
export * from './universal.js';
|
||||
|
||||
// Agent features
|
||||
export * from './features/index.js';
|
||||
|
||||
const adapters: Record<AgentType, AgentAdapter> = {
|
||||
'claude-code': new ClaudeCodeAdapter(),
|
||||
cursor: new CursorAdapter(),
|
||||
|
||||
@@ -101,6 +101,62 @@ skillkit workflow create # Create new workflow
|
||||
skillkit cicd github-action # Generate GitHub Actions
|
||||
skillkit cicd gitlab-ci # Generate GitLab CI
|
||||
skillkit cicd pre-commit # Generate pre-commit hook
|
||||
skillkit cicd init # Initialize CI/CD templates
|
||||
```
|
||||
|
||||
### Team Collaboration
|
||||
|
||||
```bash
|
||||
skillkit team init --name "Team" # Initialize team
|
||||
skillkit team share <bundle> # Share skill bundle
|
||||
skillkit team import <path> # Import bundle
|
||||
skillkit team list # List team bundles
|
||||
skillkit team sync # Sync with remote
|
||||
skillkit team remove <bundle> # Remove bundle
|
||||
skillkit team bundle-create # Create new bundle
|
||||
skillkit team bundle-export <id> # Export bundle
|
||||
skillkit team bundle-list # List all bundles
|
||||
```
|
||||
|
||||
### Plugin System
|
||||
|
||||
```bash
|
||||
skillkit plugin list # List installed plugins
|
||||
skillkit plugin install <name> # Install plugin
|
||||
skillkit plugin uninstall <name> # Uninstall plugin
|
||||
skillkit plugin enable <name> # Enable plugin
|
||||
skillkit plugin disable <name> # Disable plugin
|
||||
skillkit plugin info <name> # Plugin details
|
||||
```
|
||||
|
||||
### Methodologies & Plans
|
||||
|
||||
```bash
|
||||
skillkit methodology list # List methodologies
|
||||
skillkit methodology load <name> # Load methodology
|
||||
skillkit methodology apply <name> # Apply to project
|
||||
|
||||
skillkit plan parse <file> # Parse plan file
|
||||
skillkit plan validate <file> # Validate plan
|
||||
skillkit plan execute <file> # Execute plan
|
||||
skillkit plan status # Plan execution status
|
||||
```
|
||||
|
||||
### Hooks & Automation
|
||||
|
||||
```bash
|
||||
skillkit hook list # List registered hooks
|
||||
skillkit hook register <event> # Register new hook
|
||||
skillkit hook trigger <event> # Trigger hook manually
|
||||
skillkit hook enable <id> # Enable hook
|
||||
skillkit hook disable <id> # Disable hook
|
||||
```
|
||||
|
||||
### Agent Commands
|
||||
|
||||
```bash
|
||||
skillkit command generate <agent> # Generate agent-native commands
|
||||
skillkit command list <agent> # List available commands
|
||||
```
|
||||
|
||||
### Utilities
|
||||
@@ -110,6 +166,8 @@ skillkit init # Initialize in project
|
||||
skillkit init --agent cursor # Initialize for specific agent
|
||||
skillkit validate ./skill # Validate skill format
|
||||
skillkit create my-skill # Create new skill
|
||||
skillkit settings # View all settings
|
||||
skillkit settings --set key=value # Update setting
|
||||
```
|
||||
|
||||
## Install Options
|
||||
|
||||
@@ -0,0 +1,390 @@
|
||||
import { Command, Option } from 'clipanion';
|
||||
import { resolve } from 'node:path';
|
||||
import { promises as fs } from 'fs';
|
||||
import chalk from 'chalk';
|
||||
import ora from 'ora';
|
||||
import {
|
||||
type SearchableSkill,
|
||||
type SkillExample,
|
||||
AIManager,
|
||||
loadIndex as loadIndexFromCache,
|
||||
} from '@skillkit/core';
|
||||
|
||||
export class AICommand extends Command {
|
||||
static override paths = [['ai']];
|
||||
|
||||
static override usage = Command.Usage({
|
||||
description: 'AI-powered skill search and generation',
|
||||
details: `
|
||||
The ai command provides AI-powered features for skills:
|
||||
|
||||
- Natural language search: Find skills using conversational queries
|
||||
- Skill generation: Automatically generate skills from examples
|
||||
- Similar skills: Find skills similar to a given skill
|
||||
|
||||
Note: Without an API key, the command uses a basic mock AI provider.
|
||||
Set ANTHROPIC_API_KEY or OPENAI_API_KEY to use real AI features.
|
||||
`,
|
||||
examples: [
|
||||
['Search skills naturally', '$0 ai search "help me write better tests"'],
|
||||
['Generate skill from description', '$0 ai generate --description "skill for code review"'],
|
||||
['Generate from code example', '$0 ai generate --from-code example.ts --description "..."'],
|
||||
['Find similar skills', '$0 ai similar my-skill-name'],
|
||||
],
|
||||
});
|
||||
|
||||
// Subcommand
|
||||
subcommand = Option.String({ required: true });
|
||||
|
||||
// Search options
|
||||
query = Option.String('--query,-q', {
|
||||
description: 'Search query for natural language search',
|
||||
});
|
||||
|
||||
// Generation options
|
||||
description = Option.String('--description,-d', {
|
||||
description: 'Description of the skill to generate',
|
||||
});
|
||||
|
||||
fromCode = Option.String('--from-code', {
|
||||
description: 'Generate skill from code example file',
|
||||
});
|
||||
|
||||
additionalContext = Option.String('--context', {
|
||||
description: 'Additional context for generation',
|
||||
});
|
||||
|
||||
targetAgent = Option.String('--agent,-a', {
|
||||
description: 'Target agent for generated skill',
|
||||
});
|
||||
|
||||
// Similar skills option
|
||||
skillName = Option.String({ required: false });
|
||||
|
||||
// Common options
|
||||
limit = Option.String('--limit,-l', {
|
||||
description: 'Maximum number of results',
|
||||
});
|
||||
|
||||
minRelevance = Option.String('--min-relevance', {
|
||||
description: 'Minimum relevance score (0-1)',
|
||||
});
|
||||
|
||||
json = Option.Boolean('--json,-j', false, {
|
||||
description: 'Output in JSON format',
|
||||
});
|
||||
|
||||
output = Option.String('--output,-o', {
|
||||
description: 'Output file for generated skill',
|
||||
});
|
||||
|
||||
async execute(): Promise<number> {
|
||||
const aiConfig = this.getAIConfig();
|
||||
const manager = new AIManager(aiConfig);
|
||||
|
||||
if (!this.json) {
|
||||
const providerName = manager.getProviderName();
|
||||
if (providerName === 'mock') {
|
||||
console.log(
|
||||
chalk.yellow(
|
||||
'⚠ Using mock AI provider (limited functionality)\n' +
|
||||
' Set ANTHROPIC_API_KEY or OPENAI_API_KEY for real AI features\n'
|
||||
)
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
switch (this.subcommand) {
|
||||
case 'search':
|
||||
return await this.handleSearch(manager);
|
||||
case 'generate':
|
||||
case 'gen':
|
||||
return await this.handleGenerate(manager);
|
||||
case 'similar':
|
||||
return await this.handleSimilar(manager);
|
||||
default:
|
||||
console.error(
|
||||
chalk.red(`Unknown subcommand: ${this.subcommand}\n`)
|
||||
);
|
||||
console.log('Valid subcommands: search, generate, similar');
|
||||
return 1;
|
||||
}
|
||||
}
|
||||
|
||||
private async handleSearch(manager: AIManager): Promise<number> {
|
||||
const query = this.query || this.skillName;
|
||||
if (!query) {
|
||||
console.error(chalk.red('Search query required (--query or positional argument)'));
|
||||
return 1;
|
||||
}
|
||||
|
||||
const skills = await this.loadSkills();
|
||||
if (skills.length === 0) {
|
||||
console.log(
|
||||
chalk.yellow('No skills found. Run "skillkit recommend --update" first.')
|
||||
);
|
||||
return 0;
|
||||
}
|
||||
|
||||
const spinner = ora('Searching with AI...').start();
|
||||
|
||||
try {
|
||||
const results = await manager.searchSkills(query, skills, {
|
||||
limit: this.limit ? parseInt(this.limit, 10) : 10,
|
||||
minRelevance: this.minRelevance
|
||||
? parseFloat(this.minRelevance)
|
||||
: 0.5,
|
||||
includeReasoning: !this.json,
|
||||
});
|
||||
|
||||
spinner.stop();
|
||||
|
||||
if (this.json) {
|
||||
console.log(JSON.stringify(results, null, 2));
|
||||
return 0;
|
||||
}
|
||||
|
||||
if (results.length === 0) {
|
||||
console.log(chalk.yellow(`No skills found matching "${query}"`));
|
||||
return 0;
|
||||
}
|
||||
|
||||
console.log(chalk.cyan(`\nAI Search Results (${results.length} found):\n`));
|
||||
|
||||
for (const result of results) {
|
||||
const score = Math.round(result.relevance * 100);
|
||||
const scoreColor =
|
||||
score >= 70 ? chalk.green : score >= 50 ? chalk.yellow : chalk.dim;
|
||||
|
||||
console.log(
|
||||
` ${scoreColor(`${score}%`)} ${chalk.bold(result.skill.name)}`
|
||||
);
|
||||
|
||||
if (result.skill.description) {
|
||||
console.log(` ${chalk.dim(result.skill.description)}`);
|
||||
}
|
||||
|
||||
if (result.reasoning) {
|
||||
console.log(` ${chalk.dim('→ ' + result.reasoning)}`);
|
||||
}
|
||||
|
||||
console.log();
|
||||
}
|
||||
|
||||
return 0;
|
||||
} catch (error) {
|
||||
spinner.fail('Search failed');
|
||||
console.error(
|
||||
chalk.red(error instanceof Error ? error.message : String(error))
|
||||
);
|
||||
return 1;
|
||||
}
|
||||
}
|
||||
|
||||
private async handleGenerate(manager: AIManager): Promise<number> {
|
||||
const description = this.description;
|
||||
if (!description) {
|
||||
console.error(chalk.red('Description required (--description)'));
|
||||
return 1;
|
||||
}
|
||||
|
||||
let codeExamples: string[] = [];
|
||||
if (this.fromCode) {
|
||||
const codePath = resolve(this.fromCode);
|
||||
try {
|
||||
const code = await fs.readFile(codePath, 'utf-8');
|
||||
codeExamples = [code];
|
||||
} catch {
|
||||
console.error(chalk.red(`Failed to read code file: ${codePath}`));
|
||||
return 1;
|
||||
}
|
||||
}
|
||||
|
||||
const example: SkillExample = {
|
||||
description,
|
||||
context: this.additionalContext,
|
||||
codeExamples,
|
||||
targetAgent: this.targetAgent,
|
||||
};
|
||||
|
||||
const spinner = ora('Generating skill with AI...').start();
|
||||
|
||||
try {
|
||||
const generated = await manager.generateSkill(example, {
|
||||
targetAgent: this.targetAgent,
|
||||
includeTests: true,
|
||||
includeDocumentation: true,
|
||||
});
|
||||
|
||||
spinner.stop();
|
||||
|
||||
const validation = manager.validateGenerated(generated);
|
||||
if (!validation.valid) {
|
||||
console.log(chalk.yellow('\n⚠ Generated skill has validation warnings:'));
|
||||
for (const error of validation.errors) {
|
||||
console.log(chalk.dim(` • ${error}`));
|
||||
}
|
||||
console.log();
|
||||
}
|
||||
|
||||
if (this.json) {
|
||||
console.log(JSON.stringify(generated, null, 2));
|
||||
return 0;
|
||||
}
|
||||
|
||||
console.log(chalk.green('\n✓ Generated skill successfully\n'));
|
||||
console.log(chalk.cyan('Name:') + ` ${generated.name}`);
|
||||
console.log(chalk.cyan('Description:') + ` ${generated.description}`);
|
||||
console.log(
|
||||
chalk.cyan('Tags:') + ` ${generated.tags.join(', ')}`
|
||||
);
|
||||
console.log(
|
||||
chalk.cyan('Confidence:') +
|
||||
` ${Math.round(generated.confidence * 100)}%`
|
||||
);
|
||||
|
||||
if (generated.reasoning) {
|
||||
console.log(chalk.cyan('Reasoning:') + ` ${generated.reasoning}`);
|
||||
}
|
||||
|
||||
console.log('\n' + chalk.dim('Content:'));
|
||||
console.log(chalk.dim('─'.repeat(60)));
|
||||
console.log(generated.content);
|
||||
console.log(chalk.dim('─'.repeat(60)));
|
||||
|
||||
if (this.output) {
|
||||
const outputPath = resolve(this.output);
|
||||
await fs.writeFile(outputPath, generated.content, 'utf-8');
|
||||
console.log(chalk.green(`\n✓ Saved to: ${outputPath}`));
|
||||
} else {
|
||||
console.log(
|
||||
chalk.dim('\nSave with: --output <filename>')
|
||||
);
|
||||
}
|
||||
|
||||
return 0;
|
||||
} catch (error) {
|
||||
spinner.fail('Generation failed');
|
||||
console.error(
|
||||
chalk.red(error instanceof Error ? error.message : String(error))
|
||||
);
|
||||
return 1;
|
||||
}
|
||||
}
|
||||
|
||||
private async handleSimilar(manager: AIManager): Promise<number> {
|
||||
const skillName = this.skillName;
|
||||
if (!skillName) {
|
||||
console.error(chalk.red('Skill name required'));
|
||||
return 1;
|
||||
}
|
||||
|
||||
const skills = await this.loadSkills();
|
||||
if (skills.length === 0) {
|
||||
console.log(
|
||||
chalk.yellow('No skills found. Run "skillkit recommend --update" first.')
|
||||
);
|
||||
return 0;
|
||||
}
|
||||
|
||||
const targetSkill = skills.find(
|
||||
(s) => s.name.toLowerCase() === skillName.toLowerCase()
|
||||
);
|
||||
|
||||
if (!targetSkill) {
|
||||
console.error(chalk.red(`Skill not found: ${skillName}`));
|
||||
return 1;
|
||||
}
|
||||
|
||||
const spinner = ora('Finding similar skills...').start();
|
||||
|
||||
try {
|
||||
const results = await manager.findSimilar(targetSkill, skills, {
|
||||
limit: this.limit ? parseInt(this.limit, 10) : 10,
|
||||
minRelevance: this.minRelevance
|
||||
? parseFloat(this.minRelevance)
|
||||
: 0.5,
|
||||
includeReasoning: !this.json,
|
||||
});
|
||||
|
||||
spinner.stop();
|
||||
|
||||
if (this.json) {
|
||||
console.log(JSON.stringify(results, null, 2));
|
||||
return 0;
|
||||
}
|
||||
|
||||
if (results.length === 0) {
|
||||
console.log(
|
||||
chalk.yellow(`No similar skills found for "${skillName}"`)
|
||||
);
|
||||
return 0;
|
||||
}
|
||||
|
||||
console.log(
|
||||
chalk.cyan(`\nSkills similar to "${skillName}" (${results.length} found):\n`)
|
||||
);
|
||||
|
||||
for (const result of results) {
|
||||
const score = Math.round(result.relevance * 100);
|
||||
const scoreColor =
|
||||
score >= 70 ? chalk.green : score >= 50 ? chalk.yellow : chalk.dim;
|
||||
|
||||
console.log(
|
||||
` ${scoreColor(`${score}%`)} ${chalk.bold(result.skill.name)}`
|
||||
);
|
||||
|
||||
if (result.skill.description) {
|
||||
console.log(` ${chalk.dim(result.skill.description)}`);
|
||||
}
|
||||
|
||||
if (result.reasoning) {
|
||||
console.log(` ${chalk.dim('→ ' + result.reasoning)}`);
|
||||
}
|
||||
|
||||
console.log();
|
||||
}
|
||||
|
||||
return 0;
|
||||
} catch (error) {
|
||||
spinner.fail('Search failed');
|
||||
console.error(
|
||||
chalk.red(error instanceof Error ? error.message : String(error))
|
||||
);
|
||||
return 1;
|
||||
}
|
||||
}
|
||||
|
||||
private async loadSkills(): Promise<SearchableSkill[]> {
|
||||
const index = loadIndexFromCache();
|
||||
if (!index) {
|
||||
return [];
|
||||
}
|
||||
|
||||
return index.skills.map((s) => ({
|
||||
name: s.name,
|
||||
description: s.description,
|
||||
content: '',
|
||||
tags: s.tags,
|
||||
source: s.source,
|
||||
}));
|
||||
}
|
||||
|
||||
private getAIConfig() {
|
||||
const apiKey =
|
||||
process.env.ANTHROPIC_API_KEY || process.env.OPENAI_API_KEY;
|
||||
|
||||
return {
|
||||
provider:
|
||||
process.env.ANTHROPIC_API_KEY
|
||||
? ('anthropic' as const)
|
||||
: process.env.OPENAI_API_KEY
|
||||
? ('openai' as const)
|
||||
: ('none' as const),
|
||||
apiKey,
|
||||
model: process.env.ANTHROPIC_API_KEY ? 'claude-3-sonnet-20240229' : undefined,
|
||||
maxTokens: 4096,
|
||||
temperature: 0.7,
|
||||
};
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,288 @@
|
||||
import { Command, Option } from 'clipanion';
|
||||
import { resolve } from 'node:path';
|
||||
import { promises as fs } from 'fs';
|
||||
import path from 'path';
|
||||
import chalk from 'chalk';
|
||||
import { AuditLogger, type AuditQuery, type AuditEventType } from '@skillkit/core';
|
||||
|
||||
export class AuditCommand extends Command {
|
||||
static override paths = [['audit']];
|
||||
|
||||
static override usage = Command.Usage({
|
||||
description: 'View and manage audit logs',
|
||||
details: `
|
||||
The audit command provides access to the audit log system.
|
||||
All skill operations, team activities, and plugin actions are logged.
|
||||
|
||||
Subcommands:
|
||||
log View recent audit log entries
|
||||
export Export audit logs to file
|
||||
stats Show audit statistics
|
||||
clear Clear old audit entries
|
||||
`,
|
||||
examples: [
|
||||
['View recent logs', '$0 audit log'],
|
||||
['View logs with filters', '$0 audit log --type skill.install --limit 20'],
|
||||
['Export logs to JSON', '$0 audit export --format json --output audit.json'],
|
||||
['Show statistics', '$0 audit stats'],
|
||||
['Clear logs older than 30 days', '$0 audit clear --days 30'],
|
||||
],
|
||||
});
|
||||
|
||||
subcommand = Option.String({ required: true });
|
||||
|
||||
// Query options
|
||||
type = Option.Array('--type,-t', {
|
||||
description: 'Filter by event type',
|
||||
});
|
||||
|
||||
user = Option.String('--user,-u', {
|
||||
description: 'Filter by user',
|
||||
});
|
||||
|
||||
resource = Option.String('--resource,-r', {
|
||||
description: 'Filter by resource',
|
||||
});
|
||||
|
||||
success = Option.Boolean('--success', {
|
||||
description: 'Show only successful operations',
|
||||
});
|
||||
|
||||
failed = Option.Boolean('--failed', {
|
||||
description: 'Show only failed operations',
|
||||
});
|
||||
|
||||
since = Option.String('--since', {
|
||||
description: 'Show events since date (ISO 8601)',
|
||||
});
|
||||
|
||||
until = Option.String('--until', {
|
||||
description: 'Show events until date (ISO 8601)',
|
||||
});
|
||||
|
||||
limit = Option.String('--limit,-l', {
|
||||
description: 'Maximum number of entries',
|
||||
});
|
||||
|
||||
// Export options
|
||||
format = Option.String('--format,-f', {
|
||||
description: 'Export format (json, csv, text)',
|
||||
});
|
||||
|
||||
output = Option.String('--output,-o', {
|
||||
description: 'Output file path',
|
||||
});
|
||||
|
||||
// Clear options
|
||||
days = Option.String('--days', {
|
||||
description: 'Clear entries older than N days',
|
||||
});
|
||||
|
||||
// Common options
|
||||
json = Option.Boolean('--json,-j', false, {
|
||||
description: 'Output in JSON format',
|
||||
});
|
||||
|
||||
projectPath = Option.String('--path,-p', {
|
||||
description: 'Project path (default: current directory)',
|
||||
});
|
||||
|
||||
async execute(): Promise<number> {
|
||||
const targetPath = resolve(this.projectPath || process.cwd());
|
||||
const logDir = path.join(targetPath, '.skillkit');
|
||||
const logger = new AuditLogger(logDir);
|
||||
|
||||
try {
|
||||
switch (this.subcommand) {
|
||||
case 'log':
|
||||
case 'list':
|
||||
return await this.handleLog(logger);
|
||||
case 'export':
|
||||
return await this.handleExport(logger);
|
||||
case 'stats':
|
||||
return await this.handleStats(logger);
|
||||
case 'clear':
|
||||
return await this.handleClear(logger);
|
||||
default:
|
||||
console.error(chalk.red(`Unknown subcommand: ${this.subcommand}\n`));
|
||||
console.log('Valid subcommands: log, export, stats, clear');
|
||||
return 1;
|
||||
}
|
||||
} finally {
|
||||
await logger.destroy();
|
||||
}
|
||||
}
|
||||
|
||||
private async handleLog(logger: AuditLogger): Promise<number> {
|
||||
const query = this.buildQuery();
|
||||
const events = await logger.query(query);
|
||||
|
||||
if (this.json) {
|
||||
console.log(JSON.stringify(events, null, 2));
|
||||
return 0;
|
||||
}
|
||||
|
||||
if (events.length === 0) {
|
||||
console.log(chalk.yellow('No audit events found'));
|
||||
return 0;
|
||||
}
|
||||
|
||||
console.log(chalk.cyan(`\nAudit Log (${events.length} entries):\n`));
|
||||
|
||||
for (const event of events) {
|
||||
const statusIcon = event.success ? chalk.green('✓') : chalk.red('✗');
|
||||
const timestamp = event.timestamp.toLocaleString();
|
||||
|
||||
console.log(
|
||||
`${statusIcon} ${chalk.dim(timestamp)} ${chalk.bold(event.type)}`
|
||||
);
|
||||
console.log(
|
||||
` ${event.action} on ${chalk.cyan(event.resource)}`
|
||||
);
|
||||
|
||||
if (event.user) {
|
||||
console.log(` ${chalk.dim('User:')} ${event.user}`);
|
||||
}
|
||||
|
||||
if (event.duration) {
|
||||
console.log(` ${chalk.dim('Duration:')} ${event.duration}ms`);
|
||||
}
|
||||
|
||||
if (event.error) {
|
||||
console.log(` ${chalk.red('Error:')} ${event.error}`);
|
||||
}
|
||||
|
||||
if (event.details && Object.keys(event.details).length > 0) {
|
||||
console.log(` ${chalk.dim('Details:')} ${JSON.stringify(event.details)}`);
|
||||
}
|
||||
|
||||
console.log();
|
||||
}
|
||||
|
||||
return 0;
|
||||
}
|
||||
|
||||
private async handleExport(logger: AuditLogger): Promise<number> {
|
||||
const format = (this.format as 'json' | 'csv' | 'text') || 'json';
|
||||
const query = this.buildQuery();
|
||||
|
||||
const content = await logger.export({ format, query });
|
||||
|
||||
if (this.output) {
|
||||
const outputPath = resolve(this.output);
|
||||
await fs.writeFile(outputPath, content, 'utf-8');
|
||||
console.log(chalk.green(`✓ Exported audit log to: ${outputPath}`));
|
||||
} else {
|
||||
console.log(content);
|
||||
}
|
||||
|
||||
return 0;
|
||||
}
|
||||
|
||||
private async handleStats(logger: AuditLogger): Promise<number> {
|
||||
const stats = await logger.stats();
|
||||
|
||||
if (this.json) {
|
||||
console.log(JSON.stringify(stats, null, 2));
|
||||
return 0;
|
||||
}
|
||||
|
||||
console.log(chalk.cyan('\nAudit Statistics:\n'));
|
||||
console.log(`Total Events: ${chalk.bold(stats.totalEvents.toString())}`);
|
||||
console.log(
|
||||
`Success Rate: ${chalk.bold(`${(stats.successRate * 100).toFixed(1)}%`)}`
|
||||
);
|
||||
|
||||
if (Object.keys(stats.eventsByType).length > 0) {
|
||||
console.log(chalk.cyan('\nEvents by Type:'));
|
||||
const sorted = Object.entries(stats.eventsByType).sort(
|
||||
([, a], [, b]) => b - a
|
||||
);
|
||||
for (const [type, count] of sorted) {
|
||||
console.log(` ${type.padEnd(30)} ${count}`);
|
||||
}
|
||||
}
|
||||
|
||||
if (stats.topResources.length > 0) {
|
||||
console.log(chalk.cyan('\nTop Resources:'));
|
||||
for (const { resource, count } of stats.topResources) {
|
||||
console.log(` ${resource.padEnd(40)} ${count}`);
|
||||
}
|
||||
}
|
||||
|
||||
if (stats.recentErrors.length > 0) {
|
||||
console.log(chalk.cyan(`\nRecent Errors (${stats.recentErrors.length}):`));
|
||||
for (const error of stats.recentErrors.slice(0, 5)) {
|
||||
const timestamp = error.timestamp.toLocaleString();
|
||||
console.log(
|
||||
` ${chalk.red('✗')} ${chalk.dim(timestamp)} ${error.type}`
|
||||
);
|
||||
if (error.error) {
|
||||
console.log(` ${chalk.dim(error.error)}`);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
console.log();
|
||||
return 0;
|
||||
}
|
||||
|
||||
private async handleClear(logger: AuditLogger): Promise<number> {
|
||||
if (!this.days) {
|
||||
console.error(chalk.red('--days option required'));
|
||||
return 1;
|
||||
}
|
||||
|
||||
const daysAgo = parseInt(this.days, 10);
|
||||
const cutoffDate = new Date();
|
||||
cutoffDate.setDate(cutoffDate.getDate() - daysAgo);
|
||||
|
||||
const cleared = await logger.clear(cutoffDate);
|
||||
|
||||
console.log(
|
||||
chalk.green(
|
||||
`✓ Cleared ${cleared} audit entries older than ${daysAgo} days`
|
||||
)
|
||||
);
|
||||
|
||||
return 0;
|
||||
}
|
||||
|
||||
private buildQuery(): AuditQuery {
|
||||
const query: AuditQuery = {};
|
||||
|
||||
if (this.type && this.type.length > 0) {
|
||||
query.types = this.type as AuditEventType[];
|
||||
}
|
||||
|
||||
if (this.user) {
|
||||
query.user = this.user;
|
||||
}
|
||||
|
||||
if (this.resource) {
|
||||
query.resource = this.resource;
|
||||
}
|
||||
|
||||
if (this.success) {
|
||||
query.success = true;
|
||||
} else if (this.failed) {
|
||||
query.success = false;
|
||||
}
|
||||
|
||||
if (this.since) {
|
||||
query.startDate = new Date(this.since);
|
||||
}
|
||||
|
||||
if (this.until) {
|
||||
query.endDate = new Date(this.until);
|
||||
}
|
||||
|
||||
if (this.limit) {
|
||||
query.limit = parseInt(this.limit, 10);
|
||||
} else {
|
||||
query.limit = 50;
|
||||
}
|
||||
|
||||
return query;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,501 @@
|
||||
/**
|
||||
* Command CLI
|
||||
*
|
||||
* Manage slash commands and agent integration.
|
||||
*/
|
||||
|
||||
import { Command, Option } from 'clipanion';
|
||||
import { readFile, writeFile, mkdir } from 'node:fs/promises';
|
||||
import { resolve, join, dirname, extname } from 'node:path';
|
||||
import * as path from 'node:path';
|
||||
import * as fs from 'node:fs/promises';
|
||||
import { existsSync } from 'node:fs';
|
||||
import {
|
||||
createCommandRegistry,
|
||||
createCommandGenerator,
|
||||
getAgentFormat,
|
||||
supportsSlashCommands,
|
||||
} from '@skillkit/core';
|
||||
import type { SlashCommand, AgentType } from '@skillkit/core';
|
||||
|
||||
export class CommandCmd extends Command {
|
||||
static paths = [['command']];
|
||||
|
||||
static usage = Command.Usage({
|
||||
category: 'Commands',
|
||||
description: 'Manage slash commands and agent integration',
|
||||
details: `
|
||||
This command provides tools for working with slash commands.
|
||||
|
||||
Actions:
|
||||
- list: List registered commands
|
||||
- create: Create a new command from a skill
|
||||
- generate: Generate agent-specific command files
|
||||
- validate: Validate command definitions
|
||||
- export: Export commands to a bundle
|
||||
- import: Import commands from a bundle
|
||||
|
||||
Examples:
|
||||
$ skillkit command list
|
||||
$ skillkit command create my-skill --name my-command
|
||||
$ skillkit command generate --agent claude-code
|
||||
$ skillkit command validate ./commands.json
|
||||
`,
|
||||
examples: [
|
||||
['List all commands', '$0 command list'],
|
||||
['Create command from skill', '$0 command create tdd --name run-tdd'],
|
||||
['Generate for Claude Code', '$0 command generate --agent claude-code'],
|
||||
['Export commands', '$0 command export --output commands.json'],
|
||||
],
|
||||
});
|
||||
|
||||
action = Option.String({ required: true });
|
||||
|
||||
skill = Option.String('--skill,-s', {
|
||||
description: 'Skill to create command from',
|
||||
});
|
||||
|
||||
name = Option.String('--name,-n', {
|
||||
description: 'Command name',
|
||||
});
|
||||
|
||||
description = Option.String('--description,-d', {
|
||||
description: 'Command description',
|
||||
});
|
||||
|
||||
agent = Option.String('--agent,-a', {
|
||||
description: 'Target agent for generation',
|
||||
});
|
||||
|
||||
output = Option.String('--output,-o', {
|
||||
description: 'Output file or directory',
|
||||
});
|
||||
|
||||
input = Option.String('--input,-i', {
|
||||
description: 'Input file',
|
||||
});
|
||||
|
||||
category = Option.String('--category,-c', {
|
||||
description: 'Command category',
|
||||
});
|
||||
|
||||
all = Option.Boolean('--all', false, {
|
||||
description: 'Include all commands (hidden and disabled)',
|
||||
});
|
||||
|
||||
json = Option.Boolean('--json', false, {
|
||||
description: 'Output as JSON',
|
||||
});
|
||||
|
||||
dryRun = Option.Boolean('--dry-run', false, {
|
||||
description: 'Show what would be generated without writing files',
|
||||
});
|
||||
|
||||
async execute(): Promise<number> {
|
||||
try {
|
||||
switch (this.action) {
|
||||
case 'list':
|
||||
return await this.listCommands();
|
||||
case 'create':
|
||||
return await this.createCommand();
|
||||
case 'generate':
|
||||
return await this.generateCommands();
|
||||
case 'validate':
|
||||
return await this.validateCommands();
|
||||
case 'export':
|
||||
return await this.exportCommands();
|
||||
case 'import':
|
||||
return await this.importCommands();
|
||||
case 'info':
|
||||
return await this.showInfo();
|
||||
default:
|
||||
this.context.stderr.write(
|
||||
`Unknown action: ${this.action}\n` +
|
||||
`Available actions: list, create, generate, validate, export, import, info\n`
|
||||
);
|
||||
return 1;
|
||||
}
|
||||
} catch (error) {
|
||||
this.context.stderr.write(`Error: ${(error as Error).message}\n`);
|
||||
return 1;
|
||||
}
|
||||
}
|
||||
|
||||
private async listCommands(): Promise<number> {
|
||||
const registry = createCommandRegistry();
|
||||
|
||||
// Load commands from local config
|
||||
await this.loadCommandsFromConfig(registry);
|
||||
|
||||
const commands = registry.search({
|
||||
category: this.category,
|
||||
includeHidden: this.all,
|
||||
includeDisabled: this.all,
|
||||
});
|
||||
|
||||
if (this.json) {
|
||||
this.context.stdout.write(JSON.stringify(commands, null, 2) + '\n');
|
||||
} else {
|
||||
if (commands.length === 0) {
|
||||
this.context.stdout.write('No commands registered.\n');
|
||||
this.context.stdout.write('Use "skillkit command create" to create commands from skills.\n');
|
||||
return 0;
|
||||
}
|
||||
|
||||
this.context.stdout.write(`Registered Commands (${commands.length}):\n\n`);
|
||||
|
||||
// Group by category
|
||||
const categories = new Map<string, typeof commands>();
|
||||
for (const cmd of commands) {
|
||||
const cat = cmd.category || 'uncategorized';
|
||||
if (!categories.has(cat)) {
|
||||
categories.set(cat, []);
|
||||
}
|
||||
categories.get(cat)!.push(cmd);
|
||||
}
|
||||
|
||||
for (const [category, cmds] of categories) {
|
||||
this.context.stdout.write(` ${category.toUpperCase()}\n`);
|
||||
for (const cmd of cmds) {
|
||||
const status = cmd.enabled ? '' : ' (disabled)';
|
||||
const hidden = cmd.hidden ? ' (hidden)' : '';
|
||||
this.context.stdout.write(` /${cmd.name}${status}${hidden}\n`);
|
||||
this.context.stdout.write(` ${cmd.description}\n`);
|
||||
if (cmd.aliases && cmd.aliases.length > 0) {
|
||||
this.context.stdout.write(` Aliases: ${cmd.aliases.join(', ')}\n`);
|
||||
}
|
||||
}
|
||||
this.context.stdout.write('\n');
|
||||
}
|
||||
}
|
||||
|
||||
return 0;
|
||||
}
|
||||
|
||||
private async createCommand(): Promise<number> {
|
||||
if (!this.skill) {
|
||||
this.context.stderr.write('Error: --skill is required for create action\n');
|
||||
return 1;
|
||||
}
|
||||
|
||||
const commandName = this.name || this.skill.toLowerCase().replace(/[^a-z0-9]+/g, '-');
|
||||
|
||||
const command: SlashCommand = {
|
||||
name: commandName,
|
||||
description: this.description || `Execute ${this.skill} skill`,
|
||||
skill: this.skill,
|
||||
category: this.category,
|
||||
examples: [`/${commandName}`],
|
||||
};
|
||||
|
||||
// Save to commands config
|
||||
const configPath = resolve(process.cwd(), '.skillkit', 'commands.json');
|
||||
let commands: SlashCommand[] = [];
|
||||
|
||||
if (existsSync(configPath)) {
|
||||
const content = await readFile(configPath, 'utf-8');
|
||||
const config = JSON.parse(content);
|
||||
commands = config.commands || [];
|
||||
}
|
||||
|
||||
// Check if command already exists
|
||||
const existing = commands.findIndex((c) => c.name === commandName);
|
||||
if (existing >= 0) {
|
||||
// Merge new properties with existing command to preserve metadata
|
||||
const previous = commands[existing];
|
||||
commands[existing] = {
|
||||
...previous,
|
||||
name: commandName,
|
||||
skill: this.skill,
|
||||
description: this.description ?? previous.description ?? command.description,
|
||||
category: this.category ?? previous.category,
|
||||
examples: command.examples?.length ? command.examples : previous.examples,
|
||||
// Preserve existing metadata if not provided
|
||||
aliases: previous.aliases,
|
||||
args: previous.args,
|
||||
tags: previous.tags,
|
||||
hidden: previous.hidden,
|
||||
metadata: previous.metadata,
|
||||
};
|
||||
this.context.stdout.write(`Updated command: /${commandName}\n`);
|
||||
} else {
|
||||
commands.push(command);
|
||||
this.context.stdout.write(`Created command: /${commandName}\n`);
|
||||
}
|
||||
|
||||
// Ensure directory exists
|
||||
await mkdir(dirname(configPath), { recursive: true });
|
||||
|
||||
// Save config
|
||||
await writeFile(
|
||||
configPath,
|
||||
JSON.stringify({ version: '1.0.0', commands }, null, 2)
|
||||
);
|
||||
|
||||
this.context.stdout.write(`Saved to: ${configPath}\n`);
|
||||
|
||||
return 0;
|
||||
}
|
||||
|
||||
private async generateCommands(): Promise<number> {
|
||||
const agent = (this.agent || 'claude-code') as AgentType;
|
||||
|
||||
if (!supportsSlashCommands(agent)) {
|
||||
this.context.stdout.write(`Note: ${agent} has limited slash command support.\n`);
|
||||
}
|
||||
|
||||
const registry = createCommandRegistry();
|
||||
await this.loadCommandsFromConfig(registry);
|
||||
|
||||
const commands = registry.getAll(this.all);
|
||||
|
||||
if (commands.length === 0) {
|
||||
this.context.stderr.write('No commands to generate. Create commands first.\n');
|
||||
return 1;
|
||||
}
|
||||
|
||||
const generator = createCommandGenerator({
|
||||
includeHidden: this.all,
|
||||
includeDisabled: this.all,
|
||||
});
|
||||
|
||||
const format = getAgentFormat(agent);
|
||||
const outputTarget = this.output
|
||||
? resolve(this.output)
|
||||
: resolve(process.cwd(), format.directory);
|
||||
const outputDir = extname(outputTarget) ? dirname(outputTarget) : outputTarget;
|
||||
|
||||
const result = generator.generate(commands, agent);
|
||||
|
||||
if (typeof result === 'string') {
|
||||
// Single file output (e.g., Cursor rules)
|
||||
const extension = format.extension
|
||||
? format.extension.startsWith('.') ? format.extension : `.${format.extension}`
|
||||
: '.mdc';
|
||||
const filePath = extname(outputTarget)
|
||||
? outputTarget
|
||||
: join(outputTarget, `commands${extension}`);
|
||||
|
||||
if (this.dryRun) {
|
||||
this.context.stdout.write('Would write to: ' + filePath + '\n\n');
|
||||
this.context.stdout.write(result);
|
||||
} else {
|
||||
await mkdir(dirname(filePath), { recursive: true });
|
||||
await writeFile(filePath, result);
|
||||
this.context.stdout.write(`Generated: ${filePath}\n`);
|
||||
}
|
||||
} else {
|
||||
// Multiple file output
|
||||
if (extname(outputTarget)) {
|
||||
this.context.stderr.write(
|
||||
'Error: --output must be a directory for multi-file formats\n'
|
||||
);
|
||||
return 1;
|
||||
}
|
||||
|
||||
if (this.dryRun) {
|
||||
this.context.stdout.write('Would write to: ' + outputDir + '\n\n');
|
||||
for (const [filename, content] of result) {
|
||||
this.context.stdout.write(`--- ${filename} ---\n`);
|
||||
this.context.stdout.write(content.substring(0, 500));
|
||||
if (content.length > 500) {
|
||||
this.context.stdout.write('\n... (truncated)\n');
|
||||
}
|
||||
this.context.stdout.write('\n');
|
||||
}
|
||||
} else {
|
||||
await mkdir(outputDir, { recursive: true });
|
||||
for (const [filename, content] of result) {
|
||||
const filePath = join(outputDir, filename);
|
||||
await writeFile(filePath, content);
|
||||
this.context.stdout.write(`Generated: ${filePath}\n`);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Generate manifest
|
||||
const manifestPath = join(outputDir, 'manifest.json');
|
||||
const manifest = generator.generateManifest(commands);
|
||||
|
||||
if (!this.dryRun) {
|
||||
await writeFile(manifestPath, manifest);
|
||||
this.context.stdout.write(`Generated: ${manifestPath}\n`);
|
||||
}
|
||||
|
||||
this.context.stdout.write(`\nGenerated ${commands.length} commands for ${agent}\n`);
|
||||
|
||||
return 0;
|
||||
}
|
||||
|
||||
private async validateCommands(): Promise<number> {
|
||||
const inputPath = this.input || resolve(process.cwd(), '.skillkit', 'commands.json');
|
||||
|
||||
if (!existsSync(inputPath)) {
|
||||
this.context.stderr.write(`File not found: ${inputPath}\n`);
|
||||
return 1;
|
||||
}
|
||||
|
||||
const content = await readFile(inputPath, 'utf-8');
|
||||
const config = JSON.parse(content);
|
||||
const commands: SlashCommand[] = config.commands || [];
|
||||
|
||||
const registry = createCommandRegistry({ validateOnRegister: false });
|
||||
let valid = 0;
|
||||
let invalid = 0;
|
||||
|
||||
this.context.stdout.write(`Validating ${commands.length} commands...\n\n`);
|
||||
|
||||
for (const command of commands) {
|
||||
const result = registry.validate(command);
|
||||
|
||||
if (result.valid) {
|
||||
valid++;
|
||||
if (!this.json) {
|
||||
this.context.stdout.write(`\u2713 /${command.name}\n`);
|
||||
}
|
||||
} else {
|
||||
invalid++;
|
||||
if (!this.json) {
|
||||
this.context.stdout.write(`\u2717 /${command.name}\n`);
|
||||
for (const error of result.errors) {
|
||||
this.context.stdout.write(` Error: ${error}\n`);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
if (!this.json && result.warnings.length > 0) {
|
||||
for (const warning of result.warnings) {
|
||||
this.context.stdout.write(` Warning: ${warning}\n`);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
if (this.json) {
|
||||
this.context.stdout.write(
|
||||
JSON.stringify({
|
||||
total: commands.length,
|
||||
valid,
|
||||
invalid,
|
||||
}) + '\n'
|
||||
);
|
||||
} else {
|
||||
this.context.stdout.write(`\nValidation complete: ${valid} valid, ${invalid} invalid\n`);
|
||||
}
|
||||
|
||||
return invalid > 0 ? 1 : 0;
|
||||
}
|
||||
|
||||
private async exportCommands(): Promise<number> {
|
||||
const registry = createCommandRegistry();
|
||||
await this.loadCommandsFromConfig(registry);
|
||||
|
||||
const bundle = registry.export(this.all);
|
||||
|
||||
if (this.output) {
|
||||
let outputPath = resolve(this.output);
|
||||
|
||||
// Check if output is a directory or ends with path separator
|
||||
const stat = await fs.stat(outputPath).catch(() => null);
|
||||
if ((stat && stat.isDirectory()) || this.output.endsWith(path.sep)) {
|
||||
outputPath = path.join(outputPath, 'commands.json');
|
||||
}
|
||||
|
||||
// Ensure parent directory exists
|
||||
await fs.mkdir(path.dirname(outputPath), { recursive: true });
|
||||
await writeFile(outputPath, JSON.stringify(bundle, null, 2));
|
||||
this.context.stdout.write(`Exported ${bundle.commands.length} commands to: ${outputPath}\n`);
|
||||
} else {
|
||||
this.context.stdout.write(JSON.stringify(bundle, null, 2) + '\n');
|
||||
}
|
||||
|
||||
return 0;
|
||||
}
|
||||
|
||||
private async importCommands(): Promise<number> {
|
||||
if (!this.input) {
|
||||
this.context.stderr.write('Error: --input is required for import action\n');
|
||||
return 1;
|
||||
}
|
||||
|
||||
const inputPath = resolve(this.input);
|
||||
if (!existsSync(inputPath)) {
|
||||
this.context.stderr.write(`File not found: ${inputPath}\n`);
|
||||
return 1;
|
||||
}
|
||||
|
||||
const content = await readFile(inputPath, 'utf-8');
|
||||
const bundle = JSON.parse(content);
|
||||
|
||||
// Load existing commands
|
||||
const configPath = resolve(process.cwd(), '.skillkit', 'commands.json');
|
||||
let existingCommands: SlashCommand[] = [];
|
||||
|
||||
if (existsSync(configPath)) {
|
||||
const existingContent = await readFile(configPath, 'utf-8');
|
||||
const config = JSON.parse(existingContent);
|
||||
existingCommands = config.commands || [];
|
||||
}
|
||||
|
||||
// Merge commands
|
||||
const commandMap = new Map<string, SlashCommand>();
|
||||
for (const cmd of existingCommands) {
|
||||
commandMap.set(cmd.name, cmd);
|
||||
}
|
||||
for (const cmd of bundle.commands) {
|
||||
commandMap.set(cmd.name, cmd);
|
||||
}
|
||||
|
||||
const mergedCommands = Array.from(commandMap.values());
|
||||
|
||||
// Save
|
||||
await mkdir(dirname(configPath), { recursive: true });
|
||||
await writeFile(
|
||||
configPath,
|
||||
JSON.stringify({ version: '1.0.0', commands: mergedCommands }, null, 2)
|
||||
);
|
||||
|
||||
const imported = bundle.commands.length;
|
||||
this.context.stdout.write(`Imported ${imported} commands\n`);
|
||||
this.context.stdout.write(`Total commands: ${mergedCommands.length}\n`);
|
||||
this.context.stdout.write(`Saved to: ${configPath}\n`);
|
||||
|
||||
return 0;
|
||||
}
|
||||
|
||||
private async showInfo(): Promise<number> {
|
||||
const agent = (this.agent || 'claude-code') as AgentType;
|
||||
const format = getAgentFormat(agent);
|
||||
|
||||
if (this.json) {
|
||||
this.context.stdout.write(JSON.stringify(format, null, 2) + '\n');
|
||||
} else {
|
||||
this.context.stdout.write(`Agent: ${agent}\n`);
|
||||
this.context.stdout.write(`Directory: ${format.directory}\n`);
|
||||
this.context.stdout.write(`Extension: ${format.extension}\n`);
|
||||
this.context.stdout.write(`Supports Slash Commands: ${format.supportsSlashCommands}\n`);
|
||||
this.context.stdout.write(`Supports Command Files: ${format.supportsCommandFiles}\n`);
|
||||
}
|
||||
|
||||
return 0;
|
||||
}
|
||||
|
||||
private async loadCommandsFromConfig(
|
||||
registry: ReturnType<typeof createCommandRegistry>
|
||||
): Promise<void> {
|
||||
const configPath = resolve(process.cwd(), '.skillkit', 'commands.json');
|
||||
|
||||
if (existsSync(configPath)) {
|
||||
const content = await readFile(configPath, 'utf-8');
|
||||
const config = JSON.parse(content);
|
||||
const commands: SlashCommand[] = config.commands || [];
|
||||
|
||||
for (const command of commands) {
|
||||
try {
|
||||
registry.register(command);
|
||||
} catch {
|
||||
// Skip invalid commands
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,282 @@
|
||||
/**
|
||||
* Hook Command
|
||||
*
|
||||
* Manage skill hooks for automatic triggering
|
||||
*/
|
||||
|
||||
import { Command, Option } from 'clipanion';
|
||||
import chalk from 'chalk';
|
||||
import { createHookManager, type HookEvent, type InjectionMode } from '@skillkit/core';
|
||||
|
||||
export class HookCommand extends Command {
|
||||
static override paths = [['hook']];
|
||||
|
||||
static override usage = Command.Usage({
|
||||
description: 'Manage skill hooks for automatic triggering',
|
||||
examples: [
|
||||
['List all hooks', '$0 hook list'],
|
||||
['Add a session start hook', '$0 hook add session:start tdd-workflow'],
|
||||
['Add a file save hook with pattern', '$0 hook add file:save code-review --pattern "*.ts"'],
|
||||
['Remove a hook', '$0 hook remove <hook-id>'],
|
||||
['Enable a hook', '$0 hook enable <hook-id>'],
|
||||
['Disable a hook', '$0 hook disable <hook-id>'],
|
||||
['Generate agent hooks', '$0 hook generate --agent claude-code'],
|
||||
],
|
||||
});
|
||||
|
||||
action = Option.String({ required: true });
|
||||
target = Option.String({ required: false });
|
||||
skill = Option.String({ required: false });
|
||||
pattern = Option.String('--pattern,-p', { description: 'File pattern matcher' });
|
||||
agent = Option.String('--agent,-a', { description: 'Target agent for generation' });
|
||||
inject = Option.String('--inject,-i', { description: 'Injection mode: content, reference, prompt' });
|
||||
priority = Option.String('--priority', { description: 'Hook priority (higher = earlier)' });
|
||||
verbose = Option.Boolean('--verbose,-v', { description: 'Show detailed output' });
|
||||
|
||||
async execute(): Promise<number> {
|
||||
const projectPath = process.cwd();
|
||||
|
||||
try {
|
||||
switch (this.action) {
|
||||
case 'list':
|
||||
return await this.listHooks(projectPath);
|
||||
case 'add':
|
||||
return await this.addHook(projectPath);
|
||||
case 'remove':
|
||||
return await this.removeHook(projectPath);
|
||||
case 'enable':
|
||||
return await this.enableHook(projectPath);
|
||||
case 'disable':
|
||||
return await this.disableHook(projectPath);
|
||||
case 'generate':
|
||||
return await this.generateHooks(projectPath);
|
||||
case 'info':
|
||||
return await this.showHookInfo(projectPath);
|
||||
default:
|
||||
this.context.stderr.write(chalk.red(`Unknown action: ${this.action}\n`));
|
||||
this.context.stderr.write('Available actions: list, add, remove, enable, disable, generate, info\n');
|
||||
return 1;
|
||||
}
|
||||
} catch (err) {
|
||||
this.context.stderr.write(chalk.red(`✗ ${err instanceof Error ? err.message : 'Unknown error'}\n`));
|
||||
return 1;
|
||||
}
|
||||
}
|
||||
|
||||
private async listHooks(projectPath: string): Promise<number> {
|
||||
const manager = createHookManager({ projectPath });
|
||||
const hooks = manager.getAllHooks();
|
||||
|
||||
if (hooks.length === 0) {
|
||||
this.context.stdout.write('No hooks configured.\n');
|
||||
this.context.stdout.write(chalk.gray('Run `skillkit hook add <event> <skill>` to add a hook.\n'));
|
||||
return 0;
|
||||
}
|
||||
|
||||
this.context.stdout.write(chalk.cyan('Configured Hooks:\n\n'));
|
||||
|
||||
// Group by event
|
||||
const eventGroups = new Map<string, typeof hooks>();
|
||||
for (const hook of hooks) {
|
||||
const group = eventGroups.get(hook.event) || [];
|
||||
group.push(hook);
|
||||
eventGroups.set(hook.event, group);
|
||||
}
|
||||
|
||||
for (const [event, eventHooks] of eventGroups) {
|
||||
this.context.stdout.write(chalk.yellow(`${event}:\n`));
|
||||
for (const hook of eventHooks) {
|
||||
const status = hook.enabled ? chalk.green('●') : chalk.gray('○');
|
||||
this.context.stdout.write(` ${status} ${chalk.white(hook.id.slice(0, 8))} → ${hook.skills.join(', ')}\n`);
|
||||
if (hook.matcher) {
|
||||
this.context.stdout.write(chalk.gray(` Pattern: ${hook.matcher}\n`));
|
||||
}
|
||||
if (this.verbose) {
|
||||
this.context.stdout.write(chalk.gray(` Inject: ${hook.inject}, Priority: ${hook.priority || 0}\n`));
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
this.context.stdout.write(`\nTotal: ${hooks.length} hooks\n`);
|
||||
return 0;
|
||||
}
|
||||
|
||||
private async addHook(projectPath: string): Promise<number> {
|
||||
if (!this.target) {
|
||||
this.context.stderr.write(chalk.red('Event type required.\n'));
|
||||
this.context.stderr.write('Usage: skillkit hook add <event> <skill>\n');
|
||||
this.context.stderr.write('Events: session:start, session:end, file:save, file:open, task:start, commit:pre, commit:post, error:occur, test:fail, build:fail\n');
|
||||
return 1;
|
||||
}
|
||||
|
||||
if (!this.skill) {
|
||||
this.context.stderr.write(chalk.red('Skill name required.\n'));
|
||||
this.context.stderr.write('Usage: skillkit hook add <event> <skill>\n');
|
||||
return 1;
|
||||
}
|
||||
|
||||
const event = this.target as HookEvent;
|
||||
const validEvents: HookEvent[] = [
|
||||
'session:start', 'session:resume', 'session:end',
|
||||
'file:open', 'file:save', 'file:create', 'file:delete',
|
||||
'task:start', 'task:complete',
|
||||
'commit:pre', 'commit:post',
|
||||
'error:occur', 'test:fail', 'test:pass',
|
||||
'build:start', 'build:fail', 'build:success',
|
||||
];
|
||||
|
||||
if (!validEvents.includes(event)) {
|
||||
this.context.stderr.write(chalk.red(`Invalid event: ${this.target}\n`));
|
||||
this.context.stderr.write(`Valid events: ${validEvents.join(', ')}\n`);
|
||||
return 1;
|
||||
}
|
||||
|
||||
const manager = createHookManager({ projectPath });
|
||||
|
||||
const hook = manager.registerHook({
|
||||
event,
|
||||
skills: [this.skill],
|
||||
inject: (this.inject as InjectionMode) || 'reference',
|
||||
matcher: this.pattern,
|
||||
priority: this.priority ? parseInt(this.priority, 10) : 0,
|
||||
enabled: true,
|
||||
});
|
||||
|
||||
manager.save();
|
||||
|
||||
this.context.stdout.write(chalk.green(`✓ Hook added: ${hook.id.slice(0, 8)}\n`));
|
||||
this.context.stdout.write(` Event: ${event}\n`);
|
||||
this.context.stdout.write(` Skill: ${this.skill}\n`);
|
||||
if (this.pattern) {
|
||||
this.context.stdout.write(` Pattern: ${this.pattern}\n`);
|
||||
}
|
||||
|
||||
return 0;
|
||||
}
|
||||
|
||||
private async removeHook(projectPath: string): Promise<number> {
|
||||
if (!this.target) {
|
||||
this.context.stderr.write(chalk.red('Hook ID required.\n'));
|
||||
this.context.stderr.write('Usage: skillkit hook remove <hook-id>\n');
|
||||
return 1;
|
||||
}
|
||||
|
||||
const manager = createHookManager({ projectPath });
|
||||
const hooks = manager.getAllHooks();
|
||||
|
||||
// Find hook by ID prefix
|
||||
const hook = hooks.find((h) => h.id.startsWith(this.target!));
|
||||
if (!hook) {
|
||||
this.context.stderr.write(chalk.red(`Hook not found: ${this.target}\n`));
|
||||
return 1;
|
||||
}
|
||||
|
||||
manager.unregisterHook(hook.id);
|
||||
manager.save();
|
||||
|
||||
this.context.stdout.write(chalk.green(`✓ Hook removed: ${hook.id.slice(0, 8)}\n`));
|
||||
return 0;
|
||||
}
|
||||
|
||||
private async enableHook(projectPath: string): Promise<number> {
|
||||
if (!this.target) {
|
||||
this.context.stderr.write(chalk.red('Hook ID required.\n'));
|
||||
return 1;
|
||||
}
|
||||
|
||||
const manager = createHookManager({ projectPath });
|
||||
const hooks = manager.getAllHooks();
|
||||
const hook = hooks.find((h) => h.id.startsWith(this.target!));
|
||||
|
||||
if (!hook) {
|
||||
this.context.stderr.write(chalk.red(`Hook not found: ${this.target}\n`));
|
||||
return 1;
|
||||
}
|
||||
|
||||
manager.enableHook(hook.id);
|
||||
manager.save();
|
||||
|
||||
this.context.stdout.write(chalk.green(`✓ Hook enabled: ${hook.id.slice(0, 8)}\n`));
|
||||
return 0;
|
||||
}
|
||||
|
||||
private async disableHook(projectPath: string): Promise<number> {
|
||||
if (!this.target) {
|
||||
this.context.stderr.write(chalk.red('Hook ID required.\n'));
|
||||
return 1;
|
||||
}
|
||||
|
||||
const manager = createHookManager({ projectPath });
|
||||
const hooks = manager.getAllHooks();
|
||||
const hook = hooks.find((h) => h.id.startsWith(this.target!));
|
||||
|
||||
if (!hook) {
|
||||
this.context.stderr.write(chalk.red(`Hook not found: ${this.target}\n`));
|
||||
return 1;
|
||||
}
|
||||
|
||||
manager.disableHook(hook.id);
|
||||
manager.save();
|
||||
|
||||
this.context.stdout.write(chalk.yellow(`○ Hook disabled: ${hook.id.slice(0, 8)}\n`));
|
||||
return 0;
|
||||
}
|
||||
|
||||
private async generateHooks(projectPath: string): Promise<number> {
|
||||
const manager = createHookManager({ projectPath });
|
||||
const hooks = manager.getAllHooks();
|
||||
|
||||
if (hooks.length === 0) {
|
||||
this.context.stdout.write('No hooks configured to generate.\n');
|
||||
return 0;
|
||||
}
|
||||
|
||||
const agent = this.agent || 'claude-code';
|
||||
const generated = manager.generateAgentHooks(agent as any);
|
||||
|
||||
this.context.stdout.write(chalk.cyan(`Generated hooks for ${agent}:\n\n`));
|
||||
|
||||
if (typeof generated === 'string') {
|
||||
this.context.stdout.write(generated);
|
||||
} else {
|
||||
this.context.stdout.write(JSON.stringify(generated, null, 2));
|
||||
}
|
||||
|
||||
this.context.stdout.write('\n');
|
||||
return 0;
|
||||
}
|
||||
|
||||
private async showHookInfo(projectPath: string): Promise<number> {
|
||||
if (!this.target) {
|
||||
this.context.stderr.write(chalk.red('Hook ID required.\n'));
|
||||
return 1;
|
||||
}
|
||||
|
||||
const manager = createHookManager({ projectPath });
|
||||
const hooks = manager.getAllHooks();
|
||||
const hook = hooks.find((h) => h.id.startsWith(this.target!));
|
||||
|
||||
if (!hook) {
|
||||
this.context.stderr.write(chalk.red(`Hook not found: ${this.target}\n`));
|
||||
return 1;
|
||||
}
|
||||
|
||||
this.context.stdout.write(chalk.cyan(`\nHook: ${hook.id}\n`));
|
||||
this.context.stdout.write(`Event: ${hook.event}\n`);
|
||||
this.context.stdout.write(`Skills: ${hook.skills.join(', ')}\n`);
|
||||
this.context.stdout.write(`Enabled: ${hook.enabled ? 'Yes' : 'No'}\n`);
|
||||
this.context.stdout.write(`Inject: ${hook.inject}\n`);
|
||||
this.context.stdout.write(`Priority: ${hook.priority || 0}\n`);
|
||||
if (hook.matcher) {
|
||||
this.context.stdout.write(`Pattern: ${hook.matcher}\n`);
|
||||
}
|
||||
if (hook.condition) {
|
||||
this.context.stdout.write(`Condition: ${hook.condition}\n`);
|
||||
}
|
||||
if (hook.agentOverrides) {
|
||||
this.context.stdout.write(`Agent Overrides: ${Object.keys(hook.agentOverrides).join(', ')}\n`);
|
||||
}
|
||||
|
||||
return 0;
|
||||
}
|
||||
}
|
||||
@@ -25,3 +25,9 @@ export { SettingsCommand } from './settings.js';
|
||||
export { CICDCommand } from './cicd.js';
|
||||
export { TeamCommand } from './team.js';
|
||||
export { PluginCommand } from './plugin.js';
|
||||
export { MethodologyCommand } from './methodology.js';
|
||||
export { HookCommand } from './hook.js';
|
||||
export { PlanCommand } from './plan.js';
|
||||
export { CommandCmd } from './command.js';
|
||||
export { AICommand } from './ai.js';
|
||||
export { AuditCommand } from './audit.js';
|
||||
|
||||
@@ -0,0 +1,343 @@
|
||||
/**
|
||||
* Methodology Command
|
||||
*
|
||||
* Manage methodology packs for AI coding agents
|
||||
*/
|
||||
|
||||
import { Command, Option } from 'clipanion';
|
||||
import chalk from 'chalk';
|
||||
import { createMethodologyManager, createMethodologyLoader } from '@skillkit/core';
|
||||
|
||||
export class MethodologyCommand extends Command {
|
||||
static override paths = [['methodology']];
|
||||
|
||||
static override usage = Command.Usage({
|
||||
description: 'Manage methodology packs for AI coding agents',
|
||||
examples: [
|
||||
['List available packs', '$0 methodology list'],
|
||||
['Install all methodology packs', '$0 methodology install'],
|
||||
['Install specific pack', '$0 methodology install testing'],
|
||||
['Install specific skill', '$0 methodology install testing/red-green-refactor'],
|
||||
['Sync methodology skills to agents', '$0 methodology sync'],
|
||||
['Search methodology skills', '$0 methodology search tdd'],
|
||||
['Show pack details', '$0 methodology info testing'],
|
||||
],
|
||||
});
|
||||
|
||||
action = Option.String({ required: true });
|
||||
target = Option.String({ required: false });
|
||||
agent = Option.String('--agent,-a', { description: 'Target agent for sync' });
|
||||
dryRun = Option.Boolean('--dry-run', { description: 'Preview without making changes' });
|
||||
verbose = Option.Boolean('--verbose,-v', { description: 'Show detailed output' });
|
||||
|
||||
async execute(): Promise<number> {
|
||||
const projectPath = process.cwd();
|
||||
|
||||
try {
|
||||
switch (this.action) {
|
||||
case 'list':
|
||||
return await this.listPacks();
|
||||
case 'install':
|
||||
return await this.installPacks(projectPath);
|
||||
case 'uninstall':
|
||||
return await this.uninstallPack(projectPath);
|
||||
case 'sync':
|
||||
return await this.syncSkills(projectPath);
|
||||
case 'search':
|
||||
return await this.searchSkills();
|
||||
case 'info':
|
||||
return await this.showPackInfo();
|
||||
case 'installed':
|
||||
return await this.listInstalled(projectPath);
|
||||
default:
|
||||
this.context.stderr.write(chalk.red(`Unknown action: ${this.action}\n`));
|
||||
this.context.stderr.write('Available actions: list, install, uninstall, sync, search, info, installed\n');
|
||||
return 1;
|
||||
}
|
||||
} catch (err) {
|
||||
this.context.stderr.write(chalk.red(`✗ ${err instanceof Error ? err.message : 'Unknown error'}\n`));
|
||||
return 1;
|
||||
}
|
||||
}
|
||||
|
||||
private async listPacks(): Promise<number> {
|
||||
const loader = createMethodologyLoader();
|
||||
const packs = await loader.loadAllPacks();
|
||||
|
||||
if (packs.length === 0) {
|
||||
this.context.stdout.write('No methodology packs available.\n');
|
||||
return 0;
|
||||
}
|
||||
|
||||
this.context.stdout.write(chalk.cyan('Available Methodology Packs:\n\n'));
|
||||
|
||||
for (const pack of packs) {
|
||||
this.context.stdout.write(chalk.green(` ${pack.name}`) + ` v${pack.version}\n`);
|
||||
this.context.stdout.write(chalk.gray(` ${pack.description}\n`));
|
||||
this.context.stdout.write(` Skills: ${pack.skills.join(', ')}\n`);
|
||||
this.context.stdout.write(` Tags: ${pack.tags.join(', ')}\n`);
|
||||
this.context.stdout.write('\n');
|
||||
}
|
||||
|
||||
this.context.stdout.write(`Total: ${packs.length} packs\n`);
|
||||
this.context.stdout.write(chalk.gray('\nRun `skillkit methodology install` to install all packs.\n'));
|
||||
return 0;
|
||||
}
|
||||
|
||||
private async installPacks(projectPath: string): Promise<number> {
|
||||
const manager = createMethodologyManager({ projectPath });
|
||||
const loader = manager.getLoader();
|
||||
|
||||
if (this.target) {
|
||||
// Check if it's a skill ID (pack/skill) or pack name
|
||||
if (this.target.includes('/')) {
|
||||
// Install single skill
|
||||
this.context.stdout.write(`Installing skill: ${chalk.cyan(this.target)}...\n`);
|
||||
|
||||
if (this.dryRun) {
|
||||
this.context.stdout.write(chalk.yellow('[dry-run] Would install skill.\n'));
|
||||
return 0;
|
||||
}
|
||||
|
||||
const result = await manager.installSkill(this.target);
|
||||
|
||||
if (result.success) {
|
||||
this.context.stdout.write(chalk.green(`✓ Skill installed: ${this.target}\n`));
|
||||
} else {
|
||||
for (const failed of result.failed) {
|
||||
this.context.stderr.write(chalk.red(`✗ ${failed.name}: ${failed.error}\n`));
|
||||
}
|
||||
return 1;
|
||||
}
|
||||
} else {
|
||||
// Install single pack
|
||||
this.context.stdout.write(`Installing pack: ${chalk.cyan(this.target)}...\n`);
|
||||
|
||||
if (this.dryRun) {
|
||||
const pack = await loader.loadPack(this.target);
|
||||
if (pack) {
|
||||
this.context.stdout.write(chalk.yellow(`[dry-run] Would install ${pack.skills.length} skills.\n`));
|
||||
}
|
||||
return 0;
|
||||
}
|
||||
|
||||
const result = await manager.installPack(this.target);
|
||||
|
||||
if (result.success) {
|
||||
this.context.stdout.write(chalk.green(`✓ Pack "${this.target}" installed!\n`));
|
||||
this.context.stdout.write(` Installed: ${result.installed.length} skills\n`);
|
||||
if (result.skipped.length > 0) {
|
||||
this.context.stdout.write(` Skipped (already installed): ${result.skipped.length}\n`);
|
||||
}
|
||||
} else {
|
||||
this.context.stderr.write(chalk.red(`✗ Failed to install pack\n`));
|
||||
for (const failed of result.failed) {
|
||||
this.context.stderr.write(chalk.red(` - ${failed.name}: ${failed.error}\n`));
|
||||
}
|
||||
return 1;
|
||||
}
|
||||
}
|
||||
} else {
|
||||
// Install all packs
|
||||
this.context.stdout.write('Installing all methodology packs...\n\n');
|
||||
|
||||
if (this.dryRun) {
|
||||
const packs = await loader.loadAllPacks();
|
||||
let totalSkills = 0;
|
||||
for (const pack of packs) {
|
||||
this.context.stdout.write(chalk.yellow(`[dry-run] Would install ${pack.name} (${pack.skills.length} skills)\n`));
|
||||
totalSkills += pack.skills.length;
|
||||
}
|
||||
this.context.stdout.write(chalk.yellow(`\n[dry-run] Would install ${totalSkills} skills total.\n`));
|
||||
return 0;
|
||||
}
|
||||
|
||||
const result = await manager.installAllPacks();
|
||||
|
||||
if (result.success) {
|
||||
this.context.stdout.write(chalk.green('\n✓ All methodology packs installed!\n'));
|
||||
this.context.stdout.write(` Installed: ${result.installed.length} skills\n`);
|
||||
if (result.skipped.length > 0) {
|
||||
this.context.stdout.write(` Skipped (already installed): ${result.skipped.length}\n`);
|
||||
}
|
||||
} else {
|
||||
this.context.stdout.write(chalk.yellow('\n⚠ Some skills failed to install:\n'));
|
||||
for (const failed of result.failed) {
|
||||
this.context.stderr.write(chalk.red(` - ${failed.name}: ${failed.error}\n`));
|
||||
}
|
||||
this.context.stdout.write(`\n Installed: ${result.installed.length} skills\n`);
|
||||
}
|
||||
}
|
||||
|
||||
this.context.stdout.write(chalk.gray('\nRun `skillkit methodology sync` to sync to detected agents.\n'));
|
||||
return 0;
|
||||
}
|
||||
|
||||
private async uninstallPack(projectPath: string): Promise<number> {
|
||||
const manager = createMethodologyManager({ projectPath });
|
||||
|
||||
if (!this.target) {
|
||||
this.context.stderr.write(chalk.red('Pack name required for uninstall.\n'));
|
||||
this.context.stderr.write('Usage: skillkit methodology uninstall <pack-name>\n');
|
||||
return 1;
|
||||
}
|
||||
|
||||
if (this.dryRun) {
|
||||
this.context.stdout.write(chalk.yellow(`[dry-run] Would uninstall pack: ${this.target}\n`));
|
||||
return 0;
|
||||
}
|
||||
|
||||
await manager.uninstallPack(this.target);
|
||||
this.context.stdout.write(chalk.green(`✓ Pack "${this.target}" uninstalled.\n`));
|
||||
return 0;
|
||||
}
|
||||
|
||||
private async syncSkills(projectPath: string): Promise<number> {
|
||||
const manager = createMethodologyManager({ projectPath, autoSync: false });
|
||||
|
||||
this.context.stdout.write('Syncing methodology skills to detected agents...\n\n');
|
||||
|
||||
if (this.dryRun) {
|
||||
const installed = manager.listInstalledSkills();
|
||||
this.context.stdout.write(chalk.yellow(`[dry-run] Would sync ${installed.length} skills.\n`));
|
||||
return 0;
|
||||
}
|
||||
|
||||
const result = await manager.syncAll();
|
||||
|
||||
if (result.synced.length > 0) {
|
||||
this.context.stdout.write(chalk.green('✓ Sync complete!\n'));
|
||||
for (const sync of result.synced) {
|
||||
this.context.stdout.write(` ${sync.skill} → ${sync.agents.join(', ')}\n`);
|
||||
}
|
||||
}
|
||||
|
||||
if (result.failed.length > 0) {
|
||||
this.context.stdout.write(chalk.yellow('\n⚠ Some syncs failed:\n'));
|
||||
for (const fail of result.failed) {
|
||||
this.context.stderr.write(chalk.red(` ${fail.skill} (${fail.agent}): ${fail.error}\n`));
|
||||
}
|
||||
}
|
||||
|
||||
if (result.synced.length === 0 && result.failed.length === 0) {
|
||||
this.context.stdout.write('No installed skills to sync. Run `skillkit methodology install` first.\n');
|
||||
}
|
||||
|
||||
return result.success ? 0 : 1;
|
||||
}
|
||||
|
||||
private async searchSkills(): Promise<number> {
|
||||
const loader = createMethodologyLoader();
|
||||
|
||||
if (!this.target) {
|
||||
this.context.stderr.write(chalk.red('Search query required.\n'));
|
||||
this.context.stderr.write('Usage: skillkit methodology search <query>\n');
|
||||
return 1;
|
||||
}
|
||||
|
||||
const skills = await loader.searchSkills(this.target);
|
||||
|
||||
if (skills.length === 0) {
|
||||
this.context.stdout.write(`No skills found matching "${this.target}".\n`);
|
||||
return 0;
|
||||
}
|
||||
|
||||
this.context.stdout.write(chalk.cyan(`Found ${skills.length} skills matching "${this.target}":\n\n`));
|
||||
|
||||
for (const skill of skills) {
|
||||
this.context.stdout.write(chalk.green(` ${skill.id}`) + ` v${skill.version}\n`);
|
||||
this.context.stdout.write(chalk.gray(` ${skill.description || 'No description'}\n`));
|
||||
if (skill.tags.length > 0) {
|
||||
this.context.stdout.write(` Tags: ${skill.tags.join(', ')}\n`);
|
||||
}
|
||||
if (this.verbose && skill.metadata.triggers) {
|
||||
this.context.stdout.write(` Triggers: ${skill.metadata.triggers.join(', ')}\n`);
|
||||
}
|
||||
this.context.stdout.write('\n');
|
||||
}
|
||||
|
||||
return 0;
|
||||
}
|
||||
|
||||
private async showPackInfo(): Promise<number> {
|
||||
const loader = createMethodologyLoader();
|
||||
|
||||
if (!this.target) {
|
||||
this.context.stderr.write(chalk.red('Pack name required.\n'));
|
||||
this.context.stderr.write('Usage: skillkit methodology info <pack-name>\n');
|
||||
return 1;
|
||||
}
|
||||
|
||||
const pack = await loader.loadPack(this.target);
|
||||
|
||||
if (!pack) {
|
||||
this.context.stderr.write(chalk.red(`Pack not found: ${this.target}\n`));
|
||||
return 1;
|
||||
}
|
||||
|
||||
this.context.stdout.write(chalk.cyan(`\nPack: ${pack.name}\n`));
|
||||
this.context.stdout.write(`Version: ${pack.version}\n`);
|
||||
this.context.stdout.write(`Description: ${pack.description}\n`);
|
||||
this.context.stdout.write(`Tags: ${pack.tags.join(', ')}\n`);
|
||||
this.context.stdout.write(`Author: ${pack.author || 'Unknown'}\n`);
|
||||
this.context.stdout.write(`License: ${pack.license || 'Unknown'}\n`);
|
||||
this.context.stdout.write(`Compatibility: ${pack.compatibility.join(', ')}\n`);
|
||||
|
||||
this.context.stdout.write(chalk.cyan(`\nSkills (${pack.skills.length}):\n`));
|
||||
|
||||
const skills = await loader.loadPackSkills(this.target);
|
||||
for (const skill of skills) {
|
||||
this.context.stdout.write(chalk.green(` ${skill.id.split('/')[1]}\n`));
|
||||
this.context.stdout.write(chalk.gray(` ${skill.description || 'No description'}\n`));
|
||||
if (this.verbose) {
|
||||
if (skill.metadata.triggers) {
|
||||
this.context.stdout.write(` Triggers: ${skill.metadata.triggers.join(', ')}\n`);
|
||||
}
|
||||
if (skill.metadata.difficulty) {
|
||||
this.context.stdout.write(` Difficulty: ${skill.metadata.difficulty}\n`);
|
||||
}
|
||||
if (skill.metadata.estimatedTime) {
|
||||
this.context.stdout.write(` Est. Time: ${skill.metadata.estimatedTime} min\n`);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
this.context.stdout.write(chalk.gray(`\nRun \`skillkit methodology install ${this.target}\` to install this pack.\n`));
|
||||
return 0;
|
||||
}
|
||||
|
||||
private async listInstalled(projectPath: string): Promise<number> {
|
||||
const manager = createMethodologyManager({ projectPath });
|
||||
|
||||
const installedPacks = manager.listInstalledPacks();
|
||||
const installedSkills = manager.listInstalledSkills();
|
||||
|
||||
if (installedPacks.length === 0 && installedSkills.length === 0) {
|
||||
this.context.stdout.write('No methodology skills installed.\n');
|
||||
this.context.stdout.write(chalk.gray('Run `skillkit methodology install` to install methodology packs.\n'));
|
||||
return 0;
|
||||
}
|
||||
|
||||
if (installedPacks.length > 0) {
|
||||
this.context.stdout.write(chalk.cyan('Installed Packs:\n'));
|
||||
for (const pack of installedPacks) {
|
||||
this.context.stdout.write(chalk.green(` ${pack.name}`) + ` v${pack.version}\n`);
|
||||
this.context.stdout.write(` Skills: ${pack.skills.length}\n`);
|
||||
}
|
||||
this.context.stdout.write('\n');
|
||||
}
|
||||
|
||||
if (installedSkills.length > 0) {
|
||||
this.context.stdout.write(chalk.cyan('Installed Skills:\n'));
|
||||
for (const skill of installedSkills) {
|
||||
const syncStatus = skill.syncedAgents.length > 0
|
||||
? chalk.green(`synced to ${skill.syncedAgents.length} agents`)
|
||||
: chalk.yellow('not synced');
|
||||
this.context.stdout.write(` ${chalk.green(skill.id)} v${skill.version} [${syncStatus}]\n`);
|
||||
}
|
||||
}
|
||||
|
||||
this.context.stdout.write(chalk.gray(`\nTotal: ${installedSkills.length} skills installed.\n`));
|
||||
return 0;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,388 @@
|
||||
/**
|
||||
* Plan Command
|
||||
*
|
||||
* Manage structured development plans.
|
||||
* Parse, validate, execute, and generate plans.
|
||||
*/
|
||||
|
||||
import { Command, Option } from 'clipanion';
|
||||
import { readFile, writeFile } from 'node:fs/promises';
|
||||
import { resolve } from 'node:path';
|
||||
import {
|
||||
createPlanParser,
|
||||
createPlanValidator,
|
||||
createPlanGenerator,
|
||||
createPlanExecutor,
|
||||
dryRunExecutor,
|
||||
shellExecutor,
|
||||
TASK_TEMPLATES,
|
||||
} from '@skillkit/core';
|
||||
|
||||
export class PlanCommand extends Command {
|
||||
static paths = [['plan']];
|
||||
|
||||
static usage = Command.Usage({
|
||||
category: 'Development',
|
||||
description: 'Manage structured development plans',
|
||||
details: `
|
||||
This command provides tools for working with structured development plans.
|
||||
|
||||
Actions:
|
||||
- parse: Parse a markdown plan to structured format
|
||||
- validate: Validate a plan for completeness
|
||||
- execute: Execute a plan (with optional dry-run)
|
||||
- generate: Generate a plan from task list
|
||||
- templates: List available task templates
|
||||
- create: Create a new empty plan
|
||||
|
||||
Examples:
|
||||
$ skillkit plan parse ./plan.md
|
||||
$ skillkit plan validate ./plan.md
|
||||
$ skillkit plan execute ./plan.md --dry-run
|
||||
$ skillkit plan generate "Add auth" --tasks "Setup,Login,Logout"
|
||||
$ skillkit plan templates
|
||||
`,
|
||||
examples: [
|
||||
['Parse a markdown plan', '$0 plan parse ./development-plan.md'],
|
||||
['Validate a plan', '$0 plan validate ./plan.md --strict'],
|
||||
['Dry-run execute a plan', '$0 plan execute ./plan.md --dry-run'],
|
||||
['List task templates', '$0 plan templates'],
|
||||
],
|
||||
});
|
||||
|
||||
action = Option.String({ required: true });
|
||||
|
||||
file = Option.String('--file,-f', {
|
||||
description: 'Plan file path',
|
||||
});
|
||||
|
||||
output = Option.String('--output,-o', {
|
||||
description: 'Output file path',
|
||||
});
|
||||
|
||||
name = Option.String('--name,-n', {
|
||||
description: 'Plan name',
|
||||
});
|
||||
|
||||
goal = Option.String('--goal,-g', {
|
||||
description: 'Plan goal',
|
||||
});
|
||||
|
||||
tasks = Option.String('--tasks,-t', {
|
||||
description: 'Comma-separated list of task names',
|
||||
});
|
||||
|
||||
template = Option.String('--template', {
|
||||
description: 'Task template to use',
|
||||
});
|
||||
|
||||
techStack = Option.String('--tech-stack', {
|
||||
description: 'Comma-separated tech stack',
|
||||
});
|
||||
|
||||
dryRun = Option.Boolean('--dry-run', false, {
|
||||
description: 'Dry run execution (no actual changes)',
|
||||
});
|
||||
|
||||
strict = Option.Boolean('--strict', false, {
|
||||
description: 'Strict validation (treat warnings as errors)',
|
||||
});
|
||||
|
||||
stopOnError = Option.Boolean('--stop-on-error', true, {
|
||||
description: 'Stop execution on first error',
|
||||
});
|
||||
|
||||
verbose = Option.Boolean('--verbose,-v', false, {
|
||||
description: 'Verbose output',
|
||||
});
|
||||
|
||||
json = Option.Boolean('--json', false, {
|
||||
description: 'Output as JSON',
|
||||
});
|
||||
|
||||
async execute(): Promise<number> {
|
||||
try {
|
||||
switch (this.action) {
|
||||
case 'parse':
|
||||
return await this.parsePlan();
|
||||
case 'validate':
|
||||
return await this.validatePlan();
|
||||
case 'execute':
|
||||
return await this.executePlan();
|
||||
case 'generate':
|
||||
return await this.generatePlan();
|
||||
case 'templates':
|
||||
return await this.listTemplates();
|
||||
case 'create':
|
||||
return await this.createPlan();
|
||||
default:
|
||||
this.context.stderr.write(
|
||||
`Unknown action: ${this.action}\n` +
|
||||
`Available actions: parse, validate, execute, generate, templates, create\n`
|
||||
);
|
||||
return 1;
|
||||
}
|
||||
} catch (error) {
|
||||
this.context.stderr.write(`Error: ${(error as Error).message}\n`);
|
||||
return 1;
|
||||
}
|
||||
}
|
||||
|
||||
private async parsePlan(): Promise<number> {
|
||||
if (!this.file) {
|
||||
this.context.stderr.write('Error: --file is required for parse action\n');
|
||||
return 1;
|
||||
}
|
||||
|
||||
const filePath = resolve(this.file);
|
||||
const content = await readFile(filePath, 'utf-8');
|
||||
|
||||
const parser = createPlanParser();
|
||||
const plan = parser.parse(content);
|
||||
|
||||
if (this.json) {
|
||||
this.context.stdout.write(JSON.stringify(plan, null, 2) + '\n');
|
||||
} else {
|
||||
this.context.stdout.write(`Plan: ${plan.name}\n`);
|
||||
this.context.stdout.write(`Goal: ${plan.goal}\n`);
|
||||
this.context.stdout.write(`Status: ${plan.status}\n`);
|
||||
this.context.stdout.write(`Tasks: ${plan.tasks.length}\n\n`);
|
||||
|
||||
for (const task of plan.tasks) {
|
||||
this.context.stdout.write(` Task ${task.id}: ${task.name}\n`);
|
||||
this.context.stdout.write(` Steps: ${task.steps.length}\n`);
|
||||
if (task.estimatedMinutes) {
|
||||
this.context.stdout.write(` Estimated: ${task.estimatedMinutes} min\n`);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
if (this.output) {
|
||||
const outputPath = resolve(this.output);
|
||||
await writeFile(outputPath, JSON.stringify(plan, null, 2));
|
||||
this.context.stdout.write(`\nSaved to: ${outputPath}\n`);
|
||||
}
|
||||
|
||||
return 0;
|
||||
}
|
||||
|
||||
private async validatePlan(): Promise<number> {
|
||||
if (!this.file) {
|
||||
this.context.stderr.write('Error: --file is required for validate action\n');
|
||||
return 1;
|
||||
}
|
||||
|
||||
const filePath = resolve(this.file);
|
||||
const content = await readFile(filePath, 'utf-8');
|
||||
|
||||
const parser = createPlanParser();
|
||||
const plan = parser.parse(content);
|
||||
|
||||
const validator = createPlanValidator({ strict: this.strict });
|
||||
const result = validator.validate(plan);
|
||||
|
||||
if (this.json) {
|
||||
this.context.stdout.write(JSON.stringify(result, null, 2) + '\n');
|
||||
} else {
|
||||
this.context.stdout.write(`Validation: ${result.valid ? 'PASSED' : 'FAILED'}\n\n`);
|
||||
|
||||
this.context.stdout.write(`Statistics:\n`);
|
||||
this.context.stdout.write(` Total tasks: ${result.stats.totalTasks}\n`);
|
||||
this.context.stdout.write(` Total steps: ${result.stats.totalSteps}\n`);
|
||||
this.context.stdout.write(` Estimated time: ${result.stats.estimatedMinutes} minutes\n`);
|
||||
this.context.stdout.write(` Tasks with tests: ${result.stats.tasksWithTests}\n`);
|
||||
this.context.stdout.write(` Avg steps/task: ${result.stats.avgStepsPerTask}\n\n`);
|
||||
|
||||
if (result.issues.length > 0) {
|
||||
this.context.stdout.write(`Issues:\n`);
|
||||
for (const issue of result.issues) {
|
||||
const icon =
|
||||
issue.type === 'error' ? '\u274C' : issue.type === 'warning' ? '\u26A0\uFE0F' : '\u2139\uFE0F';
|
||||
const location = issue.taskId ? `Task ${issue.taskId}` : 'Plan';
|
||||
this.context.stdout.write(` ${icon} [${location}] ${issue.message}\n`);
|
||||
if (issue.suggestion && this.verbose) {
|
||||
this.context.stdout.write(` Suggestion: ${issue.suggestion}\n`);
|
||||
}
|
||||
}
|
||||
} else {
|
||||
this.context.stdout.write('No issues found.\n');
|
||||
}
|
||||
}
|
||||
|
||||
return result.valid ? 0 : 1;
|
||||
}
|
||||
|
||||
private async executePlan(): Promise<number> {
|
||||
if (!this.file) {
|
||||
this.context.stderr.write('Error: --file is required for execute action\n');
|
||||
return 1;
|
||||
}
|
||||
|
||||
const filePath = resolve(this.file);
|
||||
const content = await readFile(filePath, 'utf-8');
|
||||
|
||||
const parser = createPlanParser();
|
||||
const plan = parser.parse(content);
|
||||
|
||||
// Validate first
|
||||
const validator = createPlanValidator({ strict: this.strict });
|
||||
const validation = validator.validate(plan);
|
||||
|
||||
if (!validation.valid) {
|
||||
this.context.stderr.write('Plan validation failed. Fix errors before executing.\n');
|
||||
for (const issue of validation.issues.filter((i) => i.type === 'error')) {
|
||||
this.context.stderr.write(` \u274C ${issue.message}\n`);
|
||||
}
|
||||
return 1;
|
||||
}
|
||||
|
||||
// Create executor
|
||||
const executor = createPlanExecutor({
|
||||
stepExecutor: this.dryRun ? dryRunExecutor : shellExecutor,
|
||||
});
|
||||
|
||||
// Add progress listener
|
||||
executor.addListener((event, _plan, task) => {
|
||||
if (this.verbose) {
|
||||
if (event === 'plan:task_started' && task) {
|
||||
this.context.stdout.write(`Starting task ${task.id}: ${task.name}\n`);
|
||||
} else if (event === 'plan:task_completed' && task) {
|
||||
this.context.stdout.write(`Completed task ${task.id}: ${task.name}\n`);
|
||||
} else if (event === 'plan:task_failed' && task) {
|
||||
this.context.stderr.write(`Failed task ${task.id}: ${task.name}\n`);
|
||||
}
|
||||
}
|
||||
});
|
||||
|
||||
this.context.stdout.write(`Executing plan: ${plan.name}\n`);
|
||||
if (this.dryRun) {
|
||||
this.context.stdout.write('(Dry run mode - no actual changes)\n');
|
||||
}
|
||||
this.context.stdout.write('\n');
|
||||
|
||||
const result = await executor.execute(plan, {
|
||||
dryRun: this.dryRun,
|
||||
stopOnError: this.stopOnError,
|
||||
onProgress: (taskId, step, status) => {
|
||||
if (this.verbose) {
|
||||
this.context.stdout.write(` Task ${taskId}, Step ${step}: ${status}\n`);
|
||||
}
|
||||
},
|
||||
});
|
||||
|
||||
this.context.stdout.write('\n');
|
||||
|
||||
if (this.json) {
|
||||
this.context.stdout.write(
|
||||
JSON.stringify(
|
||||
{
|
||||
...result,
|
||||
taskResults: Object.fromEntries(result.taskResults),
|
||||
},
|
||||
null,
|
||||
2
|
||||
) + '\n'
|
||||
);
|
||||
} else {
|
||||
this.context.stdout.write(`Execution: ${result.success ? 'SUCCESS' : 'FAILED'}\n`);
|
||||
this.context.stdout.write(`Duration: ${result.durationMs}ms\n`);
|
||||
this.context.stdout.write(`Completed: ${result.completedTasks.length} tasks\n`);
|
||||
this.context.stdout.write(`Failed: ${result.failedTasks.length} tasks\n`);
|
||||
this.context.stdout.write(`Skipped: ${result.skippedTasks.length} tasks\n`);
|
||||
|
||||
if (result.errors && result.errors.length > 0) {
|
||||
this.context.stdout.write('\nErrors:\n');
|
||||
for (const error of result.errors) {
|
||||
this.context.stderr.write(` - ${error}\n`);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return result.success ? 0 : 1;
|
||||
}
|
||||
|
||||
private async generatePlan(): Promise<number> {
|
||||
if (!this.name) {
|
||||
this.context.stderr.write('Error: --name is required for generate action\n');
|
||||
return 1;
|
||||
}
|
||||
|
||||
const generator = createPlanGenerator({
|
||||
includeTests: true,
|
||||
includeCommits: true,
|
||||
techStack: this.techStack?.split(',').map((s) => s.trim()).filter((s) => s !== ''),
|
||||
});
|
||||
|
||||
let plan;
|
||||
|
||||
if (this.tasks) {
|
||||
const taskNames = this.tasks.split(',').map((s) => s.trim()).filter((s) => s !== '');
|
||||
plan = generator.fromTaskList(this.name, this.goal || 'Complete the tasks', taskNames, {
|
||||
template: this.template as keyof typeof TASK_TEMPLATES,
|
||||
techStack: this.techStack?.split(',').map((s) => s.trim()).filter((s) => s !== ''),
|
||||
});
|
||||
} else {
|
||||
plan = generator.createPlan(this.name, this.goal || 'Complete the project');
|
||||
if (this.techStack) {
|
||||
plan.techStack = this.techStack.split(',').map((s) => s.trim()).filter((s) => s !== '');
|
||||
}
|
||||
}
|
||||
|
||||
const markdown = generator.toMarkdown(plan);
|
||||
|
||||
if (this.output) {
|
||||
const outputPath = resolve(this.output);
|
||||
await writeFile(outputPath, markdown);
|
||||
this.context.stdout.write(`Plan saved to: ${outputPath}\n`);
|
||||
} else if (this.json) {
|
||||
this.context.stdout.write(JSON.stringify(plan, null, 2) + '\n');
|
||||
} else {
|
||||
this.context.stdout.write(markdown);
|
||||
}
|
||||
|
||||
return 0;
|
||||
}
|
||||
|
||||
private async listTemplates(): Promise<number> {
|
||||
if (this.json) {
|
||||
this.context.stdout.write(JSON.stringify(TASK_TEMPLATES, null, 2) + '\n');
|
||||
} else {
|
||||
this.context.stdout.write('Available Task Templates:\n\n');
|
||||
|
||||
for (const [name, template] of Object.entries(TASK_TEMPLATES)) {
|
||||
this.context.stdout.write(` ${name}\n`);
|
||||
this.context.stdout.write(` ${template.description}\n`);
|
||||
this.context.stdout.write(` Steps: ${template.steps.length}\n`);
|
||||
this.context.stdout.write(` Estimated: ${template.estimatedMinutes} min\n\n`);
|
||||
}
|
||||
}
|
||||
|
||||
return 0;
|
||||
}
|
||||
|
||||
private async createPlan(): Promise<number> {
|
||||
if (!this.name) {
|
||||
this.context.stderr.write('Error: --name is required for create action\n');
|
||||
return 1;
|
||||
}
|
||||
|
||||
const generator = createPlanGenerator({
|
||||
includeTests: true,
|
||||
includeCommits: true,
|
||||
});
|
||||
|
||||
const plan = generator.createPlan(this.name, this.goal || 'Complete the project');
|
||||
|
||||
if (this.techStack) {
|
||||
plan.techStack = this.techStack.split(',').map((s) => s.trim()).filter((s) => s !== '');
|
||||
}
|
||||
|
||||
const markdown = generator.toMarkdown(plan);
|
||||
|
||||
const outputPath = this.output || resolve(`${this.name.toLowerCase().replace(/\s+/g, '-')}-plan.md`);
|
||||
await writeFile(outputPath, markdown);
|
||||
this.context.stdout.write(`Plan created: ${outputPath}\n`);
|
||||
|
||||
return 0;
|
||||
}
|
||||
}
|
||||
@@ -21,6 +21,12 @@ npm install @skillkit/core
|
||||
- **Skill Testing**: Test framework with assertions for skill validation
|
||||
- **Workflow Orchestration**: Compose skills into multi-step workflows
|
||||
- **Marketplace Aggregation**: Browse and search curated skill repositories
|
||||
- **Team Collaboration**: Share skill bundles with Git-based remote sync
|
||||
- **Plugin System**: Extend with custom translators, providers, and commands
|
||||
- **Methodologies**: 5 development frameworks (Agile, TDD, DevOps, Design Thinking, Feature Flags)
|
||||
- **Multi-Agent Orchestration**: Coordinate teams of AI agents with task assignment
|
||||
- **Plan System**: Parse, validate, and execute structured development plans
|
||||
- **Hooks & Automation**: Auto-trigger skills on file changes, git events
|
||||
|
||||
## Usage
|
||||
|
||||
@@ -155,6 +161,121 @@ const filtered = await marketplace.search({
|
||||
});
|
||||
```
|
||||
|
||||
### Team Collaboration
|
||||
|
||||
```typescript
|
||||
import { TeamManager, SkillBundle } from '@skillkit/core';
|
||||
|
||||
// Initialize team
|
||||
const teamManager = new TeamManager('./my-project');
|
||||
await teamManager.init('Engineering Team');
|
||||
|
||||
// Create skill bundle
|
||||
const bundle = await teamManager.createBundle('onboarding', {
|
||||
skills: ['git-workflow', 'code-review'],
|
||||
description: 'New developer onboarding',
|
||||
});
|
||||
|
||||
// Share bundle
|
||||
await teamManager.shareBundle(bundle);
|
||||
|
||||
// Sync with remote registry
|
||||
await teamManager.syncWithRemote('https://github.com/myorg/skills');
|
||||
```
|
||||
|
||||
### Plugin System
|
||||
|
||||
```typescript
|
||||
import { PluginManager, TranslatorPlugin } from '@skillkit/core';
|
||||
|
||||
// Load plugins
|
||||
const pluginManager = new PluginManager('./my-project');
|
||||
await pluginManager.loadAll();
|
||||
|
||||
// Install plugin
|
||||
await pluginManager.install('custom-translator');
|
||||
|
||||
// Create custom plugin
|
||||
const myPlugin: TranslatorPlugin = {
|
||||
name: 'my-agent',
|
||||
parse: async (content) => ({ /* canonical skill */ }),
|
||||
generate: async (skill) => '/* custom format */',
|
||||
};
|
||||
```
|
||||
|
||||
### Methodologies
|
||||
|
||||
```typescript
|
||||
import { MethodologyManager } from '@skillkit/core';
|
||||
|
||||
// List available methodologies
|
||||
const methodologies = await MethodologyManager.list();
|
||||
|
||||
// Load methodology
|
||||
const tdd = await MethodologyManager.load('tdd');
|
||||
// Returns: { name: 'TDD', skills: ['red-green-refactor', 'test-first'], ... }
|
||||
```
|
||||
|
||||
### Multi-Agent Orchestration
|
||||
|
||||
```typescript
|
||||
import { TeamOrchestrator, TaskManager } from '@skillkit/core';
|
||||
|
||||
// Create agent team
|
||||
const orchestrator = new TeamOrchestrator();
|
||||
const team = await orchestrator.createTeam({
|
||||
name: 'feature-dev',
|
||||
leader: { id: 'architect', name: 'System Architect' },
|
||||
teammates: [
|
||||
{ id: 'frontend', name: 'Frontend Dev', capabilities: ['react'] },
|
||||
{ id: 'backend', name: 'Backend Dev', capabilities: ['api'] },
|
||||
],
|
||||
});
|
||||
|
||||
// Manage tasks
|
||||
const taskManager = new TaskManager();
|
||||
const task = taskManager.createTask('Build login', 'Create login endpoint', spec);
|
||||
await taskManager.assignTask(task.id, 'backend');
|
||||
|
||||
// Get stats
|
||||
const stats = taskManager.getStats();
|
||||
```
|
||||
|
||||
### Plan System
|
||||
|
||||
```typescript
|
||||
import { PlanParser, PlanValidator, PlanExecutor } from '@skillkit/core';
|
||||
|
||||
// Parse plan from markdown
|
||||
const parser = new PlanParser();
|
||||
const plan = await parser.parseFile('./plan.md');
|
||||
|
||||
// Validate plan
|
||||
const validator = new PlanValidator();
|
||||
const validation = validator.validate(plan);
|
||||
|
||||
// Execute plan
|
||||
const executor = new PlanExecutor();
|
||||
const result = await executor.execute(plan, { dryRun: false });
|
||||
```
|
||||
|
||||
### Hooks & Automation
|
||||
|
||||
```typescript
|
||||
import { HookRegistry } from '@skillkit/core';
|
||||
|
||||
// Register hooks
|
||||
const hooks = new HookRegistry('./my-project');
|
||||
await hooks.register('pre-commit', {
|
||||
event: 'pre-commit',
|
||||
skill: 'code-review',
|
||||
enabled: true,
|
||||
});
|
||||
|
||||
// Trigger hook
|
||||
await hooks.trigger('pre-commit', { files: ['src/index.ts'] });
|
||||
```
|
||||
|
||||
## Supported Agents
|
||||
|
||||
The translator supports all 17 SkillKit-compatible agents:
|
||||
|
||||
@@ -45,6 +45,8 @@
|
||||
"test": "vitest run"
|
||||
},
|
||||
"dependencies": {
|
||||
"@types/minimatch": "^6.0.0",
|
||||
"minimatch": "^10.1.1",
|
||||
"yaml": "^2.6.1",
|
||||
"zod": "^3.24.1"
|
||||
},
|
||||
|
||||
@@ -0,0 +1,238 @@
|
||||
import { describe, it, expect, beforeEach } from 'vitest';
|
||||
import { AIManager } from '../manager.js';
|
||||
import type { SearchableSkill, SkillExample } from '../types.js';
|
||||
|
||||
describe('AIManager', () => {
|
||||
let manager: AIManager;
|
||||
let testSkills: SearchableSkill[];
|
||||
|
||||
beforeEach(() => {
|
||||
manager = new AIManager({
|
||||
provider: 'mock',
|
||||
});
|
||||
|
||||
testSkills = [
|
||||
{
|
||||
name: 'test-driven-development',
|
||||
description: 'Write tests before code using TDD methodology',
|
||||
content: 'TDD skill content',
|
||||
tags: ['testing', 'tdd', 'quality'],
|
||||
source: 'test-repo',
|
||||
},
|
||||
{
|
||||
name: 'code-review',
|
||||
description: 'Perform thorough code reviews',
|
||||
content: 'Code review skill content',
|
||||
tags: ['review', 'quality', 'collaboration'],
|
||||
source: 'test-repo',
|
||||
},
|
||||
{
|
||||
name: 'debugging-guide',
|
||||
description: 'Systematic approach to debugging issues',
|
||||
content: 'Debugging skill content',
|
||||
tags: ['debugging', 'troubleshooting'],
|
||||
source: 'test-repo',
|
||||
},
|
||||
];
|
||||
});
|
||||
|
||||
describe('searchSkills', () => {
|
||||
it('should search skills by query', async () => {
|
||||
const results = await manager.searchSkills('testing', testSkills, {
|
||||
minRelevance: 0,
|
||||
});
|
||||
|
||||
expect(results.length).toBeGreaterThan(0);
|
||||
expect(results[0].skill.name).toBe('test-driven-development');
|
||||
expect(results[0].relevance).toBeGreaterThan(0);
|
||||
});
|
||||
|
||||
it('should respect limit option', async () => {
|
||||
const results = await manager.searchSkills('code', testSkills, {
|
||||
limit: 1,
|
||||
});
|
||||
|
||||
expect(results.length).toBeLessThanOrEqual(1);
|
||||
});
|
||||
|
||||
it('should filter by min relevance', async () => {
|
||||
const results = await manager.searchSkills('testing', testSkills, {
|
||||
minRelevance: 0.8,
|
||||
});
|
||||
|
||||
for (const result of results) {
|
||||
expect(result.relevance).toBeGreaterThanOrEqual(0.8);
|
||||
}
|
||||
});
|
||||
|
||||
it('should include reasoning when requested', async () => {
|
||||
const results = await manager.searchSkills('testing', testSkills, {
|
||||
includeReasoning: true,
|
||||
});
|
||||
|
||||
if (results.length > 0) {
|
||||
expect(results[0].reasoning).toBeDefined();
|
||||
expect(results[0].reasoning.length).toBeGreaterThan(0);
|
||||
}
|
||||
});
|
||||
});
|
||||
|
||||
describe('searchByIntent', () => {
|
||||
it('should search by user intent', async () => {
|
||||
const results = await manager.searchByIntent(
|
||||
'I want to improve my testing workflow',
|
||||
testSkills,
|
||||
{ minRelevance: 0 }
|
||||
);
|
||||
|
||||
expect(results.length).toBeGreaterThan(0);
|
||||
const names = results.map((r) => r.skill.name);
|
||||
expect(names).toContain('test-driven-development');
|
||||
});
|
||||
});
|
||||
|
||||
describe('findSimilar', () => {
|
||||
it('should find similar skills', async () => {
|
||||
const targetSkill = testSkills[0];
|
||||
const results = await manager.findSimilar(targetSkill, testSkills, {
|
||||
minRelevance: 0,
|
||||
});
|
||||
|
||||
expect(results.length).toBeGreaterThan(0);
|
||||
results.forEach((r) => {
|
||||
expect(r.skill.name).not.toBe(targetSkill.name);
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
describe('generateSkill', () => {
|
||||
it('should generate skill from example', async () => {
|
||||
const example: SkillExample = {
|
||||
description: 'Help with API testing',
|
||||
context: 'REST APIs using Jest',
|
||||
};
|
||||
|
||||
const generated = await manager.generateSkill(example);
|
||||
|
||||
expect(generated.name).toBeDefined();
|
||||
expect(generated.name.length).toBeGreaterThan(0);
|
||||
expect(generated.description).toBe(example.description);
|
||||
expect(generated.content).toBeDefined();
|
||||
expect(generated.tags).toBeDefined();
|
||||
expect(generated.confidence).toBeGreaterThan(0);
|
||||
});
|
||||
|
||||
it('should include target agent metadata', async () => {
|
||||
const example: SkillExample = {
|
||||
description: 'Test skill',
|
||||
};
|
||||
|
||||
const generated = await manager.generateSkill(example, {
|
||||
targetAgent: 'claude-code',
|
||||
});
|
||||
|
||||
expect(generated.content).toContain('agent: claude-code');
|
||||
});
|
||||
});
|
||||
|
||||
describe('generateFromCode', () => {
|
||||
it('should generate skill from code example', async () => {
|
||||
const code = `
|
||||
function add(a: number, b: number): number {
|
||||
return a + b;
|
||||
}
|
||||
`;
|
||||
const description = 'Simple addition function';
|
||||
|
||||
const generated = await manager.generateFromCode(code, description);
|
||||
|
||||
expect(generated.name).toBeDefined();
|
||||
expect(generated.description).toBe(description);
|
||||
expect(generated.content).toContain('Example');
|
||||
});
|
||||
});
|
||||
|
||||
describe('generateFromTemplate', () => {
|
||||
it('should generate skill from template', async () => {
|
||||
const generated = await manager.generateFromTemplate(
|
||||
'api-testing',
|
||||
{ framework: 'Jest', type: 'REST' }
|
||||
);
|
||||
|
||||
expect(generated.name).toBeDefined();
|
||||
expect(generated.content).toBeDefined();
|
||||
});
|
||||
});
|
||||
|
||||
describe('validateGenerated', () => {
|
||||
it('should validate valid generated skill', () => {
|
||||
const skill = {
|
||||
name: 'valid-skill-name',
|
||||
description: 'This is a valid description with enough length',
|
||||
content: 'This is valid content with enough length to pass validation checks',
|
||||
tags: ['test', 'valid'],
|
||||
confidence: 0.8,
|
||||
reasoning: 'Valid reasoning',
|
||||
};
|
||||
|
||||
const result = manager.validateGenerated(skill);
|
||||
|
||||
expect(result.valid).toBe(true);
|
||||
expect(result.errors).toHaveLength(0);
|
||||
});
|
||||
|
||||
it('should reject skill with short name', () => {
|
||||
const skill = {
|
||||
name: 'ab',
|
||||
description: 'Valid description',
|
||||
content: 'Valid content with enough length',
|
||||
tags: [],
|
||||
confidence: 0.8,
|
||||
reasoning: '',
|
||||
};
|
||||
|
||||
const result = manager.validateGenerated(skill);
|
||||
|
||||
expect(result.valid).toBe(false);
|
||||
expect(result.errors).toContain(
|
||||
'Skill name must be at least 3 characters'
|
||||
);
|
||||
});
|
||||
|
||||
it('should reject skill with low confidence', () => {
|
||||
const skill = {
|
||||
name: 'valid-name',
|
||||
description: 'Valid description',
|
||||
content: 'Valid content with enough length',
|
||||
tags: [],
|
||||
confidence: 0.4,
|
||||
reasoning: '',
|
||||
};
|
||||
|
||||
const result = manager.validateGenerated(skill);
|
||||
|
||||
expect(result.valid).toBe(false);
|
||||
expect(result.errors).toContain(
|
||||
'Skill confidence is too low (< 0.6)'
|
||||
);
|
||||
});
|
||||
});
|
||||
|
||||
describe('getProviderName', () => {
|
||||
it('should return provider name', () => {
|
||||
const name = manager.getProviderName();
|
||||
expect(name).toBe('mock');
|
||||
});
|
||||
});
|
||||
|
||||
describe('updateConfig', () => {
|
||||
it('should update configuration', () => {
|
||||
manager.updateConfig({
|
||||
temperature: 0.5,
|
||||
});
|
||||
|
||||
// Provider should be recreated
|
||||
expect(manager.getProviderName()).toBe('mock');
|
||||
});
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,89 @@
|
||||
import type {
|
||||
AIProvider,
|
||||
AIGenerateOptions,
|
||||
GeneratedSkill,
|
||||
SkillExample,
|
||||
} from './types.js';
|
||||
|
||||
export class AISkillGenerator {
|
||||
constructor(private provider: AIProvider) {}
|
||||
|
||||
async generate(
|
||||
example: SkillExample,
|
||||
options: AIGenerateOptions = {}
|
||||
): Promise<GeneratedSkill> {
|
||||
const skill = await this.provider.generateSkill(example);
|
||||
|
||||
if (options.targetAgent && skill.content) {
|
||||
skill.content = this.addAgentMetadata(skill.content, options.targetAgent);
|
||||
}
|
||||
|
||||
return skill;
|
||||
}
|
||||
|
||||
async generateFromCode(
|
||||
code: string,
|
||||
description: string,
|
||||
options: AIGenerateOptions = {}
|
||||
): Promise<GeneratedSkill> {
|
||||
return this.generate(
|
||||
{
|
||||
description,
|
||||
codeExamples: [code],
|
||||
},
|
||||
options
|
||||
);
|
||||
}
|
||||
|
||||
async generateFromTemplate(
|
||||
templateName: string,
|
||||
variables: Record<string, string>,
|
||||
options: AIGenerateOptions = {}
|
||||
): Promise<GeneratedSkill> {
|
||||
return this.generate(
|
||||
{
|
||||
description: `Create a skill based on the ${templateName} template with the following customization: ${JSON.stringify(variables)}`,
|
||||
context: `Template: ${templateName}`,
|
||||
},
|
||||
options
|
||||
);
|
||||
}
|
||||
|
||||
private addAgentMetadata(content: string, agent: string): string {
|
||||
const metadata = `---
|
||||
agent: ${agent}
|
||||
generated: ${new Date().toISOString()}
|
||||
---
|
||||
|
||||
${content}`;
|
||||
return metadata;
|
||||
}
|
||||
|
||||
validateGenerated(skill: GeneratedSkill): {
|
||||
valid: boolean;
|
||||
errors: string[];
|
||||
} {
|
||||
const errors: string[] = [];
|
||||
|
||||
if (!skill.name || skill.name.length < 3) {
|
||||
errors.push('Skill name must be at least 3 characters');
|
||||
}
|
||||
|
||||
if (!skill.description || skill.description.length < 10) {
|
||||
errors.push('Skill description must be at least 10 characters');
|
||||
}
|
||||
|
||||
if (!skill.content || skill.content.length < 50) {
|
||||
errors.push('Skill content must be at least 50 characters');
|
||||
}
|
||||
|
||||
if (skill.confidence < 0.6) {
|
||||
errors.push('Skill confidence is too low (< 0.6)');
|
||||
}
|
||||
|
||||
return {
|
||||
valid: errors.length === 0,
|
||||
errors,
|
||||
};
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,5 @@
|
||||
export * from './types.js';
|
||||
export * from './search.js';
|
||||
export * from './generator.js';
|
||||
export * from './manager.js';
|
||||
export * from './providers/index.js';
|
||||
@@ -0,0 +1,104 @@
|
||||
import type {
|
||||
AIConfig,
|
||||
AIProvider,
|
||||
AISearchOptions,
|
||||
AISearchResult,
|
||||
AIGenerateOptions,
|
||||
GeneratedSkill,
|
||||
SearchableSkill,
|
||||
SkillExample,
|
||||
} from './types.js';
|
||||
import { AISearch } from './search.js';
|
||||
import { AISkillGenerator } from './generator.js';
|
||||
import { MockAIProvider } from './providers/mock.js';
|
||||
|
||||
export class AIManager {
|
||||
private provider: AIProvider;
|
||||
private search: AISearch;
|
||||
private generator: AISkillGenerator;
|
||||
|
||||
constructor(private config: AIConfig) {
|
||||
this.provider = this.createProvider();
|
||||
this.search = new AISearch(this.provider);
|
||||
this.generator = new AISkillGenerator(this.provider);
|
||||
}
|
||||
|
||||
async searchSkills(
|
||||
query: string,
|
||||
skills: SearchableSkill[],
|
||||
options?: AISearchOptions
|
||||
): Promise<AISearchResult[]> {
|
||||
return this.search.search(query, skills, options);
|
||||
}
|
||||
|
||||
async searchByIntent(
|
||||
intent: string,
|
||||
skills: SearchableSkill[],
|
||||
options?: AISearchOptions
|
||||
): Promise<AISearchResult[]> {
|
||||
return this.search.searchByIntent(intent, skills, options);
|
||||
}
|
||||
|
||||
async findSimilar(
|
||||
skill: SearchableSkill,
|
||||
allSkills: SearchableSkill[],
|
||||
options?: AISearchOptions
|
||||
): Promise<AISearchResult[]> {
|
||||
return this.search.findSimilar(skill, allSkills, options);
|
||||
}
|
||||
|
||||
async generateSkill(
|
||||
example: SkillExample,
|
||||
options?: AIGenerateOptions
|
||||
): Promise<GeneratedSkill> {
|
||||
return this.generator.generate(example, options);
|
||||
}
|
||||
|
||||
async generateFromCode(
|
||||
code: string,
|
||||
description: string,
|
||||
options?: AIGenerateOptions
|
||||
): Promise<GeneratedSkill> {
|
||||
return this.generator.generateFromCode(code, description, options);
|
||||
}
|
||||
|
||||
async generateFromTemplate(
|
||||
templateName: string,
|
||||
variables: Record<string, string>,
|
||||
options?: AIGenerateOptions
|
||||
): Promise<GeneratedSkill> {
|
||||
return this.generator.generateFromTemplate(templateName, variables, options);
|
||||
}
|
||||
|
||||
validateGenerated(skill: GeneratedSkill): {
|
||||
valid: boolean;
|
||||
errors: string[];
|
||||
} {
|
||||
return this.generator.validateGenerated(skill);
|
||||
}
|
||||
|
||||
private createProvider(): AIProvider {
|
||||
if (this.config.provider === 'none' || !this.config.apiKey) {
|
||||
return new MockAIProvider();
|
||||
}
|
||||
|
||||
switch (this.config.provider) {
|
||||
case 'anthropic':
|
||||
case 'openai':
|
||||
return new MockAIProvider();
|
||||
default:
|
||||
return new MockAIProvider();
|
||||
}
|
||||
}
|
||||
|
||||
getProviderName(): string {
|
||||
return this.provider.name;
|
||||
}
|
||||
|
||||
updateConfig(config: Partial<AIConfig>): void {
|
||||
this.config = { ...this.config, ...config };
|
||||
this.provider = this.createProvider();
|
||||
this.search = new AISearch(this.provider);
|
||||
this.generator = new AISkillGenerator(this.provider);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,119 @@
|
||||
import type {
|
||||
AIProvider,
|
||||
AISearchResult,
|
||||
GeneratedSkill,
|
||||
SearchableSkill,
|
||||
SkillExample,
|
||||
} from '../types.js';
|
||||
|
||||
export abstract class BaseAIProvider implements AIProvider {
|
||||
abstract name: string;
|
||||
|
||||
abstract search(
|
||||
query: string,
|
||||
skills: SearchableSkill[]
|
||||
): Promise<AISearchResult[]>;
|
||||
|
||||
abstract generateSkill(example: SkillExample): Promise<GeneratedSkill>;
|
||||
|
||||
protected buildSearchPrompt(query: string, skills: SearchableSkill[]): string {
|
||||
const skillsList = skills
|
||||
.map(
|
||||
(s, i) =>
|
||||
`${i + 1}. ${s.name}${s.description ? ` - ${s.description}` : ''}${s.tags ? ` [${s.tags.join(', ')}]` : ''}`
|
||||
)
|
||||
.join('\n');
|
||||
|
||||
return `You are a skill search assistant. Given a user query and a list of available skills, identify the most relevant skills.
|
||||
|
||||
User Query: "${query}"
|
||||
|
||||
Available Skills:
|
||||
${skillsList}
|
||||
|
||||
For each relevant skill (up to 10), provide:
|
||||
1. Skill index number
|
||||
2. Relevance score (0-1)
|
||||
3. Brief reasoning
|
||||
|
||||
Format your response as JSON:
|
||||
[
|
||||
{
|
||||
"index": <number>,
|
||||
"relevance": <0-1>,
|
||||
"reasoning": "<explanation>"
|
||||
}
|
||||
]`;
|
||||
}
|
||||
|
||||
protected buildGeneratePrompt(example: SkillExample): string {
|
||||
let prompt = `You are a skill generation assistant. Generate a complete skill based on the following specification:
|
||||
|
||||
Description: ${example.description}`;
|
||||
|
||||
if (example.context) {
|
||||
prompt += `\n\nContext: ${example.context}`;
|
||||
}
|
||||
|
||||
if (example.codeExamples && example.codeExamples.length > 0) {
|
||||
prompt += `\n\nCode Examples:\n${example.codeExamples.map((code, i) => `Example ${i + 1}:\n\`\`\`\n${code}\n\`\`\``).join('\n\n')}`;
|
||||
}
|
||||
|
||||
if (example.expectedBehavior) {
|
||||
prompt += `\n\nExpected Behavior: ${example.expectedBehavior}`;
|
||||
}
|
||||
|
||||
prompt += `
|
||||
|
||||
Generate a skill in SKILL.md format with:
|
||||
1. Clear name (kebab-case)
|
||||
2. Comprehensive description
|
||||
3. Detailed instructions
|
||||
4. Relevant tags
|
||||
5. Usage examples if applicable
|
||||
|
||||
Format your response as JSON:
|
||||
{
|
||||
"name": "<skill-name>",
|
||||
"description": "<description>",
|
||||
"content": "<full SKILL.md content>",
|
||||
"tags": ["<tag1>", "<tag2>"],
|
||||
"confidence": <0-1>,
|
||||
"reasoning": "<why this skill design>"
|
||||
}`;
|
||||
|
||||
return prompt;
|
||||
}
|
||||
|
||||
protected parseSearchResponse(
|
||||
response: string,
|
||||
skills: SearchableSkill[]
|
||||
): AISearchResult[] {
|
||||
try {
|
||||
const parsed = JSON.parse(response);
|
||||
return parsed.map((item: any) => ({
|
||||
skill: skills[item.index - 1],
|
||||
relevance: item.relevance,
|
||||
reasoning: item.reasoning,
|
||||
}));
|
||||
} catch {
|
||||
return [];
|
||||
}
|
||||
}
|
||||
|
||||
protected parseGenerateResponse(response: string): GeneratedSkill {
|
||||
try {
|
||||
const parsed = JSON.parse(response);
|
||||
return {
|
||||
name: parsed.name,
|
||||
description: parsed.description,
|
||||
content: parsed.content,
|
||||
tags: parsed.tags || [],
|
||||
confidence: parsed.confidence || 0.7,
|
||||
reasoning: parsed.reasoning || '',
|
||||
};
|
||||
} catch {
|
||||
throw new Error('Failed to parse skill generation response');
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,2 @@
|
||||
export { BaseAIProvider } from './base.js';
|
||||
export { MockAIProvider } from './mock.js';
|
||||
@@ -0,0 +1,144 @@
|
||||
import { BaseAIProvider } from './base.js';
|
||||
import type {
|
||||
AISearchResult,
|
||||
GeneratedSkill,
|
||||
SearchableSkill,
|
||||
SkillExample,
|
||||
} from '../types.js';
|
||||
|
||||
export class MockAIProvider extends BaseAIProvider {
|
||||
name = 'mock';
|
||||
|
||||
async search(
|
||||
query: string,
|
||||
skills: SearchableSkill[]
|
||||
): Promise<AISearchResult[]> {
|
||||
const lowerQuery = query.toLowerCase();
|
||||
const queryTerms = lowerQuery.split(/\s+/).filter((t) => t.length > 2);
|
||||
|
||||
return skills
|
||||
.map((skill) => {
|
||||
let relevance = 0;
|
||||
|
||||
const nameMatch = skill.name.toLowerCase().includes(lowerQuery);
|
||||
const descMatch = skill.description?.toLowerCase().includes(lowerQuery);
|
||||
const tagMatch = skill.tags?.some((t) =>
|
||||
t.toLowerCase().includes(lowerQuery)
|
||||
);
|
||||
const contentMatch = skill.content.toLowerCase().includes(lowerQuery);
|
||||
|
||||
// Also check individual terms
|
||||
const nameTermMatch = queryTerms.some((term) =>
|
||||
skill.name.toLowerCase().includes(term)
|
||||
);
|
||||
const descTermMatch = queryTerms.some(
|
||||
(term) => skill.description?.toLowerCase().includes(term)
|
||||
);
|
||||
const tagTermMatch = queryTerms.some((term) =>
|
||||
skill.tags?.some((t) => t.toLowerCase().includes(term))
|
||||
);
|
||||
|
||||
if (nameMatch) relevance += 0.5;
|
||||
if (descMatch) relevance += 0.3;
|
||||
if (tagMatch) relevance += 0.2;
|
||||
if (contentMatch) relevance += 0.1;
|
||||
|
||||
// Partial term matches
|
||||
if (!nameMatch && nameTermMatch) relevance += 0.3;
|
||||
if (!descMatch && descTermMatch) relevance += 0.2;
|
||||
if (!tagMatch && tagTermMatch) relevance += 0.15;
|
||||
|
||||
relevance = Math.min(1, relevance);
|
||||
|
||||
return {
|
||||
skill,
|
||||
relevance,
|
||||
reasoning: this.buildReasoning(
|
||||
nameMatch || nameTermMatch,
|
||||
descMatch || descTermMatch,
|
||||
tagMatch || tagTermMatch,
|
||||
contentMatch
|
||||
),
|
||||
};
|
||||
})
|
||||
.filter((r) => r.relevance > 0)
|
||||
.sort((a, b) => b.relevance - a.relevance)
|
||||
.slice(0, 10);
|
||||
}
|
||||
|
||||
async generateSkill(example: SkillExample): Promise<GeneratedSkill> {
|
||||
const name = this.generateName(example.description);
|
||||
const tags = this.generateTags(example.description);
|
||||
|
||||
return {
|
||||
name,
|
||||
description: example.description,
|
||||
content: this.generateContent(name, example),
|
||||
tags,
|
||||
confidence: 0.75,
|
||||
reasoning: 'Mock generated skill based on description and examples',
|
||||
};
|
||||
}
|
||||
|
||||
private buildReasoning(
|
||||
nameMatch: boolean,
|
||||
descMatch: boolean | undefined,
|
||||
tagMatch: boolean | undefined,
|
||||
contentMatch: boolean
|
||||
): string {
|
||||
const matches: string[] = [];
|
||||
if (nameMatch) matches.push('name');
|
||||
if (descMatch === true) matches.push('description');
|
||||
if (tagMatch === true) matches.push('tags');
|
||||
if (contentMatch) matches.push('content');
|
||||
|
||||
return matches.length > 0
|
||||
? `Matched in: ${matches.join(', ')}`
|
||||
: 'No significant matches';
|
||||
}
|
||||
|
||||
private generateName(description: string): string {
|
||||
return description
|
||||
.toLowerCase()
|
||||
.replace(/[^a-z0-9\s]/g, '')
|
||||
.split(/\s+/)
|
||||
.slice(0, 3)
|
||||
.join('-');
|
||||
}
|
||||
|
||||
private generateTags(description: string): string[] {
|
||||
const commonTags = ['productivity', 'automation', 'development'];
|
||||
if (description.toLowerCase().includes('test')) commonTags.push('testing');
|
||||
if (description.toLowerCase().includes('debug'))
|
||||
commonTags.push('debugging');
|
||||
if (description.toLowerCase().includes('code')) commonTags.push('coding');
|
||||
return commonTags.slice(0, 5);
|
||||
}
|
||||
|
||||
private generateContent(name: string, example: SkillExample): string {
|
||||
let content = `# ${name}\n\n${example.description}\n\n`;
|
||||
|
||||
if (example.context) {
|
||||
content += `## Context\n\n${example.context}\n\n`;
|
||||
}
|
||||
|
||||
content += `## Instructions\n\n`;
|
||||
content += `1. Review the task requirements\n`;
|
||||
content += `2. Implement the solution\n`;
|
||||
content += `3. Test the implementation\n`;
|
||||
content += `4. Document the changes\n\n`;
|
||||
|
||||
if (example.codeExamples && example.codeExamples.length > 0) {
|
||||
content += `## Examples\n\n`;
|
||||
example.codeExamples.forEach((code, i) => {
|
||||
content += `### Example ${i + 1}\n\n\`\`\`\n${code}\n\`\`\`\n\n`;
|
||||
});
|
||||
}
|
||||
|
||||
if (example.expectedBehavior) {
|
||||
content += `## Expected Behavior\n\n${example.expectedBehavior}\n`;
|
||||
}
|
||||
|
||||
return content;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,55 @@
|
||||
import type {
|
||||
AIProvider,
|
||||
AISearchOptions,
|
||||
AISearchResult,
|
||||
SearchableSkill,
|
||||
} from './types.js';
|
||||
|
||||
export class AISearch {
|
||||
constructor(private provider: AIProvider) {}
|
||||
|
||||
async search(
|
||||
query: string,
|
||||
skills: SearchableSkill[],
|
||||
options: AISearchOptions = {}
|
||||
): Promise<AISearchResult[]> {
|
||||
const {
|
||||
limit = 10,
|
||||
minRelevance = 0.5,
|
||||
includeReasoning = true,
|
||||
} = options;
|
||||
|
||||
const results = await this.provider.search(query, skills);
|
||||
|
||||
const filtered = results
|
||||
.filter((r) => r.relevance >= minRelevance)
|
||||
.slice(0, limit);
|
||||
|
||||
if (!includeReasoning) {
|
||||
filtered.forEach((r) => {
|
||||
r.reasoning = '';
|
||||
});
|
||||
}
|
||||
|
||||
return filtered;
|
||||
}
|
||||
|
||||
async searchByIntent(
|
||||
intent: string,
|
||||
skills: SearchableSkill[],
|
||||
options: AISearchOptions = {}
|
||||
): Promise<AISearchResult[]> {
|
||||
const enhancedQuery = `Find skills that help with: ${intent}. Consider the skill's purpose, capabilities, and use cases.`;
|
||||
return this.search(enhancedQuery, skills, options);
|
||||
}
|
||||
|
||||
async findSimilar(
|
||||
skill: SearchableSkill,
|
||||
allSkills: SearchableSkill[],
|
||||
options: AISearchOptions = {}
|
||||
): Promise<AISearchResult[]> {
|
||||
const query = `Find skills similar to "${skill.name}". ${skill.description ? `This skill: ${skill.description}` : ''}`;
|
||||
const filtered = allSkills.filter((s) => s.name !== skill.name);
|
||||
return this.search(query, filtered, options);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,56 @@
|
||||
export interface AIProvider {
|
||||
name: string;
|
||||
search(query: string, skills: SearchableSkill[]): Promise<AISearchResult[]>;
|
||||
generateSkill(example: SkillExample): Promise<GeneratedSkill>;
|
||||
}
|
||||
|
||||
export interface SearchableSkill {
|
||||
name: string;
|
||||
description?: string;
|
||||
content: string;
|
||||
tags?: string[];
|
||||
source?: string;
|
||||
}
|
||||
|
||||
export interface AISearchResult {
|
||||
skill: SearchableSkill;
|
||||
relevance: number;
|
||||
reasoning: string;
|
||||
}
|
||||
|
||||
export interface SkillExample {
|
||||
description: string;
|
||||
context?: string;
|
||||
codeExamples?: string[];
|
||||
expectedBehavior?: string;
|
||||
targetAgent?: string;
|
||||
}
|
||||
|
||||
export interface GeneratedSkill {
|
||||
name: string;
|
||||
description: string;
|
||||
content: string;
|
||||
tags: string[];
|
||||
confidence: number;
|
||||
reasoning: string;
|
||||
}
|
||||
|
||||
export interface AIConfig {
|
||||
provider: 'anthropic' | 'openai' | 'none';
|
||||
apiKey?: string;
|
||||
model?: string;
|
||||
maxTokens?: number;
|
||||
temperature?: number;
|
||||
}
|
||||
|
||||
export interface AISearchOptions {
|
||||
limit?: number;
|
||||
minRelevance?: number;
|
||||
includeReasoning?: boolean;
|
||||
}
|
||||
|
||||
export interface AIGenerateOptions {
|
||||
targetAgent?: string;
|
||||
includeTests?: boolean;
|
||||
includeDocumentation?: boolean;
|
||||
}
|
||||
@@ -0,0 +1,309 @@
|
||||
import { describe, it, expect, beforeEach, afterEach } from 'vitest';
|
||||
import { promises as fs } from 'fs';
|
||||
import { tmpdir } from 'os';
|
||||
import { join } from 'path';
|
||||
import { AuditLogger } from '../logger.js';
|
||||
|
||||
describe('AuditLogger', () => {
|
||||
let logger: AuditLogger;
|
||||
let tempDir: string;
|
||||
|
||||
beforeEach(async () => {
|
||||
tempDir = join(tmpdir(), `skillkit-audit-test-${Date.now()}`);
|
||||
await fs.mkdir(tempDir, { recursive: true });
|
||||
logger = new AuditLogger(tempDir);
|
||||
});
|
||||
|
||||
afterEach(async () => {
|
||||
await logger.destroy();
|
||||
try {
|
||||
await fs.rm(tempDir, { recursive: true, force: true });
|
||||
} catch {
|
||||
// Ignore cleanup errors
|
||||
}
|
||||
});
|
||||
|
||||
describe('log', () => {
|
||||
it('should log an event', async () => {
|
||||
await logger.log(
|
||||
'skill.install',
|
||||
'install',
|
||||
'test-skill',
|
||||
{ source: 'github' },
|
||||
true
|
||||
);
|
||||
|
||||
await logger.flush();
|
||||
|
||||
const events = await logger.query();
|
||||
expect(events.length).toBe(1);
|
||||
expect(events[0].type).toBe('skill.install');
|
||||
expect(events[0].action).toBe('install');
|
||||
expect(events[0].resource).toBe('test-skill');
|
||||
expect(events[0].success).toBe(true);
|
||||
});
|
||||
|
||||
it('should log failure event', async () => {
|
||||
await logger.log(
|
||||
'skill.install',
|
||||
'install',
|
||||
'test-skill',
|
||||
{},
|
||||
false,
|
||||
'Network error'
|
||||
);
|
||||
|
||||
await logger.flush();
|
||||
|
||||
const events = await logger.query();
|
||||
expect(events[0].success).toBe(false);
|
||||
expect(events[0].error).toBe('Network error');
|
||||
});
|
||||
|
||||
it('should log event with duration', async () => {
|
||||
await logger.log(
|
||||
'skill.execute',
|
||||
'execute',
|
||||
'test-skill',
|
||||
{},
|
||||
true,
|
||||
undefined,
|
||||
1234
|
||||
);
|
||||
|
||||
await logger.flush();
|
||||
|
||||
const events = await logger.query();
|
||||
expect(events[0].duration).toBe(1234);
|
||||
});
|
||||
|
||||
it('should auto-flush when buffer reaches limit', async () => {
|
||||
for (let i = 0; i < 15; i++) {
|
||||
await logger.log(
|
||||
'skill.sync',
|
||||
'sync',
|
||||
`skill-${i}`,
|
||||
{},
|
||||
true
|
||||
);
|
||||
}
|
||||
|
||||
const events = await logger.query();
|
||||
expect(events.length).toBeGreaterThan(0);
|
||||
});
|
||||
});
|
||||
|
||||
describe('query', () => {
|
||||
beforeEach(async () => {
|
||||
await logger.log('skill.install', 'install', 'skill-1', {}, true);
|
||||
await logger.log('skill.uninstall', 'uninstall', 'skill-2', {}, true);
|
||||
await logger.log('team.create', 'create', 'team-1', {}, true);
|
||||
await logger.log('skill.install', 'install', 'skill-3', {}, false, 'Error');
|
||||
await logger.flush();
|
||||
});
|
||||
|
||||
it('should query all events', async () => {
|
||||
const events = await logger.query();
|
||||
expect(events.length).toBe(4);
|
||||
});
|
||||
|
||||
it('should filter by type', async () => {
|
||||
const events = await logger.query({
|
||||
types: ['skill.install'],
|
||||
});
|
||||
|
||||
expect(events.length).toBe(2);
|
||||
events.forEach((e) => {
|
||||
expect(e.type).toBe('skill.install');
|
||||
});
|
||||
});
|
||||
|
||||
it('should filter by success', async () => {
|
||||
const events = await logger.query({
|
||||
success: true,
|
||||
});
|
||||
|
||||
expect(events.length).toBe(3);
|
||||
events.forEach((e) => {
|
||||
expect(e.success).toBe(true);
|
||||
});
|
||||
});
|
||||
|
||||
it('should filter by resource', async () => {
|
||||
const events = await logger.query({
|
||||
resource: 'skill-1',
|
||||
});
|
||||
|
||||
expect(events.length).toBe(1);
|
||||
expect(events[0].resource).toBe('skill-1');
|
||||
});
|
||||
|
||||
it('should filter by date range', async () => {
|
||||
const startDate = new Date(Date.now() - 1000);
|
||||
const endDate = new Date(Date.now() + 1000);
|
||||
|
||||
const events = await logger.query({
|
||||
startDate,
|
||||
endDate,
|
||||
});
|
||||
|
||||
expect(events.length).toBe(4);
|
||||
});
|
||||
|
||||
it('should respect limit', async () => {
|
||||
const events = await logger.query({
|
||||
limit: 2,
|
||||
});
|
||||
|
||||
expect(events.length).toBe(2);
|
||||
});
|
||||
|
||||
it('should respect offset', async () => {
|
||||
const events = await logger.query({
|
||||
offset: 2,
|
||||
});
|
||||
|
||||
expect(events.length).toBe(2);
|
||||
});
|
||||
});
|
||||
|
||||
describe('stats', () => {
|
||||
beforeEach(async () => {
|
||||
await logger.log('skill.install', 'install', 'skill-1', {}, true);
|
||||
await logger.log('skill.install', 'install', 'skill-2', {}, true);
|
||||
await logger.log('skill.install', 'install', 'skill-3', {}, false, 'Error');
|
||||
await logger.log('team.create', 'create', 'team-1', {}, true);
|
||||
await logger.flush();
|
||||
});
|
||||
|
||||
it('should calculate stats', async () => {
|
||||
const stats = await logger.stats();
|
||||
|
||||
expect(stats.totalEvents).toBe(4);
|
||||
expect(stats.successRate).toBe(0.75); // 3 out of 4
|
||||
expect(stats.eventsByType['skill.install']).toBe(3);
|
||||
expect(stats.eventsByType['team.create']).toBe(1);
|
||||
});
|
||||
|
||||
it('should include recent errors', async () => {
|
||||
const stats = await logger.stats();
|
||||
|
||||
expect(stats.recentErrors.length).toBe(1);
|
||||
expect(stats.recentErrors[0].error).toBe('Error');
|
||||
});
|
||||
|
||||
it('should include top resources', async () => {
|
||||
const stats = await logger.stats();
|
||||
|
||||
expect(stats.topResources.length).toBeGreaterThan(0);
|
||||
expect(stats.topResources[0].count).toBeGreaterThan(0);
|
||||
});
|
||||
});
|
||||
|
||||
describe('export', () => {
|
||||
beforeEach(async () => {
|
||||
await logger.log('skill.install', 'install', 'skill-1', {}, true);
|
||||
await logger.log('team.create', 'create', 'team-1', {}, true);
|
||||
await logger.flush();
|
||||
});
|
||||
|
||||
it('should export to JSON', async () => {
|
||||
const content = await logger.export({ format: 'json' });
|
||||
|
||||
const parsed = JSON.parse(content);
|
||||
expect(Array.isArray(parsed)).toBe(true);
|
||||
expect(parsed.length).toBe(2);
|
||||
});
|
||||
|
||||
it('should export to CSV', async () => {
|
||||
const content = await logger.export({ format: 'csv' });
|
||||
|
||||
expect(content).toContain('ID,Timestamp,Type');
|
||||
expect(content).toContain('skill.install');
|
||||
expect(content).toContain('team.create');
|
||||
});
|
||||
|
||||
it('should export to text', async () => {
|
||||
const content = await logger.export({ format: 'text' });
|
||||
|
||||
expect(content).toContain('skill.install');
|
||||
expect(content).toContain('SUCCESS');
|
||||
});
|
||||
|
||||
it('should export with query filter', async () => {
|
||||
const content = await logger.export({
|
||||
format: 'json',
|
||||
query: { types: ['skill.install'] },
|
||||
});
|
||||
|
||||
const parsed = JSON.parse(content);
|
||||
expect(parsed.length).toBe(1);
|
||||
expect(parsed[0].type).toBe('skill.install');
|
||||
});
|
||||
});
|
||||
|
||||
describe('clear', () => {
|
||||
beforeEach(async () => {
|
||||
const oldDate = new Date(Date.now() - 1000 * 60 * 60 * 24 * 40);
|
||||
const recentDate = new Date();
|
||||
|
||||
await logger.log('skill.install', 'install', 'old-skill', {}, true);
|
||||
await logger.flush();
|
||||
|
||||
const events = await logger.query();
|
||||
events[0].timestamp = oldDate;
|
||||
|
||||
const logFile = join(tempDir, 'audit.log');
|
||||
const content = events.map((e) => JSON.stringify(e)).join('\n');
|
||||
await fs.writeFile(logFile, content, 'utf-8');
|
||||
|
||||
await logger.log('skill.install', 'install', 'new-skill', {}, true);
|
||||
await logger.flush();
|
||||
});
|
||||
|
||||
it('should clear old entries', async () => {
|
||||
const cutoffDate = new Date(Date.now() - 1000 * 60 * 60 * 24 * 30);
|
||||
const cleared = await logger.clear(cutoffDate);
|
||||
|
||||
expect(cleared).toBeGreaterThan(0);
|
||||
|
||||
const events = await logger.query();
|
||||
events.forEach((e) => {
|
||||
expect(e.timestamp.getTime()).toBeGreaterThanOrEqual(
|
||||
cutoffDate.getTime()
|
||||
);
|
||||
});
|
||||
});
|
||||
|
||||
it('should clear all entries when no date provided', async () => {
|
||||
const cleared = await logger.clear();
|
||||
|
||||
expect(cleared).toBeGreaterThan(0);
|
||||
|
||||
const events = await logger.query();
|
||||
expect(events.length).toBe(0);
|
||||
});
|
||||
});
|
||||
|
||||
describe('flush', () => {
|
||||
it('should persist buffered events', async () => {
|
||||
await logger.log('skill.install', 'install', 'skill-1', {}, true);
|
||||
|
||||
// Don't auto-flush
|
||||
let events = await logger.query();
|
||||
expect(events.length).toBe(0);
|
||||
|
||||
await logger.flush();
|
||||
|
||||
events = await logger.query();
|
||||
expect(events.length).toBe(1);
|
||||
});
|
||||
|
||||
it('should handle empty buffer', async () => {
|
||||
await logger.flush();
|
||||
|
||||
const events = await logger.query();
|
||||
expect(events.length).toBe(0);
|
||||
});
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,2 @@
|
||||
export * from './types.js';
|
||||
export * from './logger.js';
|
||||
@@ -0,0 +1,293 @@
|
||||
import { promises as fs } from 'fs';
|
||||
import path from 'path';
|
||||
import type {
|
||||
AuditEvent,
|
||||
AuditEventType,
|
||||
AuditQuery,
|
||||
AuditStats,
|
||||
AuditExportOptions,
|
||||
} from './types.js';
|
||||
|
||||
export class AuditLogger {
|
||||
private logFile: string;
|
||||
private buffer: AuditEvent[] = [];
|
||||
private flushInterval: NodeJS.Timeout | null = null;
|
||||
private flushing: Promise<void> | null = null;
|
||||
|
||||
constructor(logDir: string) {
|
||||
this.logFile = path.join(logDir, 'audit.log');
|
||||
this.startAutoFlush();
|
||||
}
|
||||
|
||||
async log(
|
||||
type: AuditEventType,
|
||||
action: string,
|
||||
resource: string,
|
||||
details?: Record<string, unknown>,
|
||||
success: boolean = true,
|
||||
error?: string,
|
||||
duration?: number
|
||||
): Promise<void> {
|
||||
const event: AuditEvent = {
|
||||
id: this.generateId(),
|
||||
timestamp: new Date(),
|
||||
type,
|
||||
user: process.env.USER || 'unknown',
|
||||
action,
|
||||
resource,
|
||||
details,
|
||||
success,
|
||||
error,
|
||||
duration,
|
||||
};
|
||||
|
||||
this.buffer.push(event);
|
||||
|
||||
if (this.buffer.length >= 10) {
|
||||
await this.flush();
|
||||
}
|
||||
}
|
||||
|
||||
async query(query: AuditQuery = {}): Promise<AuditEvent[]> {
|
||||
const events = await this.loadEvents();
|
||||
return this.filterEvents(events, query);
|
||||
}
|
||||
|
||||
async stats(): Promise<AuditStats> {
|
||||
const events = await this.loadEvents();
|
||||
|
||||
const totalEvents = events.length;
|
||||
const successEvents = events.filter((e) => e.success).length;
|
||||
const successRate = totalEvents > 0 ? successEvents / totalEvents : 0;
|
||||
|
||||
const eventsByType: Record<AuditEventType, number> = {} as any;
|
||||
events.forEach((e) => {
|
||||
eventsByType[e.type] = (eventsByType[e.type] || 0) + 1;
|
||||
});
|
||||
|
||||
const recentErrors = events
|
||||
.filter((e) => !e.success)
|
||||
.sort((a, b) => b.timestamp.getTime() - a.timestamp.getTime())
|
||||
.slice(0, 10);
|
||||
|
||||
const resourceCounts = new Map<string, number>();
|
||||
events.forEach((e) => {
|
||||
resourceCounts.set(e.resource, (resourceCounts.get(e.resource) || 0) + 1);
|
||||
});
|
||||
|
||||
const topResources = Array.from(resourceCounts.entries())
|
||||
.map(([resource, count]) => ({ resource, count }))
|
||||
.sort((a, b) => b.count - a.count)
|
||||
.slice(0, 10);
|
||||
|
||||
return {
|
||||
totalEvents,
|
||||
successRate,
|
||||
eventsByType,
|
||||
recentErrors,
|
||||
topResources,
|
||||
};
|
||||
}
|
||||
|
||||
async export(options: AuditExportOptions): Promise<string> {
|
||||
const events = await this.query(options.query);
|
||||
|
||||
switch (options.format) {
|
||||
case 'json':
|
||||
return JSON.stringify(events, null, 2);
|
||||
case 'csv':
|
||||
return this.toCsv(events);
|
||||
case 'text':
|
||||
return this.toText(events);
|
||||
default:
|
||||
return JSON.stringify(events, null, 2);
|
||||
}
|
||||
}
|
||||
|
||||
async clear(olderThan?: Date): Promise<number> {
|
||||
const events = await this.loadEvents();
|
||||
|
||||
const filtered = olderThan
|
||||
? events.filter((e) => e.timestamp >= olderThan)
|
||||
: [];
|
||||
|
||||
await this.saveEvents(filtered);
|
||||
|
||||
return events.length - filtered.length;
|
||||
}
|
||||
|
||||
async flush(): Promise<void> {
|
||||
// If already flushing, wait for it to complete
|
||||
if (this.flushing) {
|
||||
return this.flushing;
|
||||
}
|
||||
|
||||
if (this.buffer.length === 0) {
|
||||
return;
|
||||
}
|
||||
|
||||
// Start flush with mutex
|
||||
this.flushing = this.doFlush();
|
||||
try {
|
||||
await this.flushing;
|
||||
} finally {
|
||||
this.flushing = null;
|
||||
}
|
||||
}
|
||||
|
||||
private async doFlush(): Promise<void> {
|
||||
// Snapshot buffer and clear it before async operations
|
||||
const toFlush = this.buffer;
|
||||
this.buffer = [];
|
||||
|
||||
try {
|
||||
const events = await this.loadEvents();
|
||||
events.push(...toFlush);
|
||||
await this.saveEvents(events);
|
||||
} catch (error) {
|
||||
// Restore events on failure
|
||||
this.buffer = [...toFlush, ...this.buffer];
|
||||
console.error('Failed to flush audit log:', error);
|
||||
}
|
||||
}
|
||||
|
||||
async destroy(): Promise<void> {
|
||||
if (this.flushInterval) {
|
||||
clearInterval(this.flushInterval);
|
||||
this.flushInterval = null;
|
||||
}
|
||||
await this.flush();
|
||||
}
|
||||
|
||||
private startAutoFlush(): void {
|
||||
this.flushInterval = setInterval(
|
||||
() => {
|
||||
this.flush().catch(console.error);
|
||||
},
|
||||
30000
|
||||
);
|
||||
}
|
||||
|
||||
private async loadEvents(): Promise<AuditEvent[]> {
|
||||
try {
|
||||
const content = await fs.readFile(this.logFile, 'utf-8');
|
||||
const events: AuditEvent[] = [];
|
||||
|
||||
for (const line of content.split('\n')) {
|
||||
if (!line.trim()) continue;
|
||||
|
||||
try {
|
||||
const event = JSON.parse(line);
|
||||
event.timestamp = new Date(event.timestamp);
|
||||
events.push(event);
|
||||
} catch (error) {
|
||||
// Skip malformed lines silently to prevent data loss
|
||||
// Malformed lines are ignored, valid events are preserved
|
||||
continue;
|
||||
}
|
||||
}
|
||||
|
||||
return events;
|
||||
} catch (error) {
|
||||
// Only propagate genuine filesystem errors
|
||||
if ((error as NodeJS.ErrnoException).code !== 'ENOENT') {
|
||||
throw error;
|
||||
}
|
||||
return [];
|
||||
}
|
||||
}
|
||||
|
||||
private async saveEvents(events: AuditEvent[]): Promise<void> {
|
||||
const dir = path.dirname(this.logFile);
|
||||
await fs.mkdir(dir, { recursive: true });
|
||||
const content = events.map((e) => JSON.stringify(e)).join('\n');
|
||||
await fs.writeFile(this.logFile, content, 'utf-8');
|
||||
}
|
||||
|
||||
private filterEvents(events: AuditEvent[], query: AuditQuery): AuditEvent[] {
|
||||
let filtered = events;
|
||||
|
||||
if (query.types && query.types.length > 0) {
|
||||
filtered = filtered.filter((e) => query.types!.includes(e.type));
|
||||
}
|
||||
|
||||
if (query.user) {
|
||||
filtered = filtered.filter((e) => e.user === query.user);
|
||||
}
|
||||
|
||||
if (query.resource) {
|
||||
filtered = filtered.filter((e) =>
|
||||
e.resource.toLowerCase().includes(query.resource!.toLowerCase())
|
||||
);
|
||||
}
|
||||
|
||||
if (query.startDate) {
|
||||
filtered = filtered.filter((e) => e.timestamp >= query.startDate!);
|
||||
}
|
||||
|
||||
if (query.endDate) {
|
||||
filtered = filtered.filter((e) => e.timestamp <= query.endDate!);
|
||||
}
|
||||
|
||||
if (query.success !== undefined) {
|
||||
filtered = filtered.filter((e) => e.success === query.success);
|
||||
}
|
||||
|
||||
filtered.sort((a, b) => b.timestamp.getTime() - a.timestamp.getTime());
|
||||
|
||||
if (query.offset !== undefined && query.offset !== null) {
|
||||
filtered = filtered.slice(query.offset);
|
||||
}
|
||||
|
||||
if (query.limit !== undefined && query.limit !== null) {
|
||||
filtered = filtered.slice(0, query.limit);
|
||||
}
|
||||
|
||||
return filtered;
|
||||
}
|
||||
|
||||
private generateId(): string {
|
||||
return `${Date.now()}-${Math.random().toString(36).substring(2, 9)}`;
|
||||
}
|
||||
|
||||
private toCsv(events: AuditEvent[]): string {
|
||||
const headers = [
|
||||
'ID',
|
||||
'Timestamp',
|
||||
'Type',
|
||||
'User',
|
||||
'Action',
|
||||
'Resource',
|
||||
'Success',
|
||||
'Error',
|
||||
'Duration',
|
||||
];
|
||||
|
||||
const rows = events.map((e) => [
|
||||
e.id,
|
||||
e.timestamp.toISOString(),
|
||||
e.type,
|
||||
e.user || '',
|
||||
e.action,
|
||||
e.resource,
|
||||
e.success ? 'true' : 'false',
|
||||
e.error || '',
|
||||
e.duration?.toString() || '',
|
||||
]);
|
||||
|
||||
return [headers.join(','), ...rows.map((r) => r.join(','))].join('\n');
|
||||
}
|
||||
|
||||
private toText(events: AuditEvent[]): string {
|
||||
return events
|
||||
.map((e) => {
|
||||
let text = `[${e.timestamp.toISOString()}] ${e.type} - ${e.action} on ${e.resource}`;
|
||||
if (e.user) text += ` by ${e.user}`;
|
||||
text += ` (${e.success ? 'SUCCESS' : 'FAILED'})`;
|
||||
if (e.error) text += `\n Error: ${e.error}`;
|
||||
if (e.duration) text += `\n Duration: ${e.duration}ms`;
|
||||
return text;
|
||||
})
|
||||
.join('\n\n');
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,57 @@
|
||||
export type AuditEventType =
|
||||
| 'skill.install'
|
||||
| 'skill.uninstall'
|
||||
| 'skill.sync'
|
||||
| 'skill.translate'
|
||||
| 'skill.execute'
|
||||
| 'team.create'
|
||||
| 'team.share'
|
||||
| 'team.import'
|
||||
| 'team.sync'
|
||||
| 'bundle.create'
|
||||
| 'bundle.export'
|
||||
| 'bundle.import'
|
||||
| 'plugin.install'
|
||||
| 'plugin.uninstall'
|
||||
| 'plugin.enable'
|
||||
| 'plugin.disable'
|
||||
| 'workflow.execute'
|
||||
| 'ai.search'
|
||||
| 'ai.generate';
|
||||
|
||||
export interface AuditEvent {
|
||||
id: string;
|
||||
timestamp: Date;
|
||||
type: AuditEventType;
|
||||
user?: string;
|
||||
action: string;
|
||||
resource: string;
|
||||
details?: Record<string, unknown>;
|
||||
success: boolean;
|
||||
error?: string;
|
||||
duration?: number;
|
||||
}
|
||||
|
||||
export interface AuditQuery {
|
||||
types?: AuditEventType[];
|
||||
user?: string;
|
||||
resource?: string;
|
||||
startDate?: Date;
|
||||
endDate?: Date;
|
||||
success?: boolean;
|
||||
limit?: number;
|
||||
offset?: number;
|
||||
}
|
||||
|
||||
export interface AuditStats {
|
||||
totalEvents: number;
|
||||
successRate: number;
|
||||
eventsByType: Record<AuditEventType, number>;
|
||||
recentErrors: AuditEvent[];
|
||||
topResources: Array<{ resource: string; count: number }>;
|
||||
}
|
||||
|
||||
export interface AuditExportOptions {
|
||||
format: 'json' | 'csv' | 'text';
|
||||
query?: AuditQuery;
|
||||
}
|
||||
@@ -0,0 +1,589 @@
|
||||
/**
|
||||
* Commands Module Tests
|
||||
*/
|
||||
|
||||
import { describe, it, expect, beforeEach } from 'vitest';
|
||||
import {
|
||||
CommandRegistry,
|
||||
createCommandRegistry,
|
||||
CommandGenerator,
|
||||
createCommandGenerator,
|
||||
getAgentFormat,
|
||||
supportsSlashCommands,
|
||||
} from '../index.js';
|
||||
import type { SlashCommand, CommandContext, AgentType } from '../types.js';
|
||||
|
||||
describe('CommandRegistry', () => {
|
||||
let registry: CommandRegistry;
|
||||
|
||||
beforeEach(() => {
|
||||
registry = createCommandRegistry({ allowOverrides: true });
|
||||
});
|
||||
|
||||
describe('register', () => {
|
||||
it('should register a valid command', () => {
|
||||
const command: SlashCommand = {
|
||||
name: 'test-cmd',
|
||||
description: 'Test command',
|
||||
skill: 'test-skill',
|
||||
};
|
||||
|
||||
registry.register(command);
|
||||
|
||||
expect(registry.has('test-cmd')).toBe(true);
|
||||
expect(registry.size).toBe(1);
|
||||
});
|
||||
|
||||
it('should register command with aliases', () => {
|
||||
const command: SlashCommand = {
|
||||
name: 'test-cmd',
|
||||
description: 'Test command',
|
||||
skill: 'test-skill',
|
||||
aliases: ['tc', 'test'],
|
||||
};
|
||||
|
||||
registry.register(command);
|
||||
|
||||
expect(registry.has('test-cmd')).toBe(true);
|
||||
expect(registry.has('tc')).toBe(true);
|
||||
expect(registry.has('test')).toBe(true);
|
||||
});
|
||||
|
||||
it('should throw on duplicate command without override', () => {
|
||||
const strictRegistry = createCommandRegistry({ allowOverrides: false });
|
||||
|
||||
const command: SlashCommand = {
|
||||
name: 'test-cmd',
|
||||
description: 'Test command',
|
||||
skill: 'test-skill',
|
||||
};
|
||||
|
||||
strictRegistry.register(command);
|
||||
|
||||
expect(() => strictRegistry.register(command)).toThrow('Command already registered');
|
||||
});
|
||||
|
||||
it('should allow override when enabled', () => {
|
||||
const command1: SlashCommand = {
|
||||
name: 'test-cmd',
|
||||
description: 'First version',
|
||||
skill: 'test-skill',
|
||||
};
|
||||
|
||||
const command2: SlashCommand = {
|
||||
name: 'test-cmd',
|
||||
description: 'Second version',
|
||||
skill: 'test-skill-2',
|
||||
};
|
||||
|
||||
registry.register(command1);
|
||||
registry.register(command2);
|
||||
|
||||
expect(registry.get('test-cmd')?.description).toBe('Second version');
|
||||
});
|
||||
|
||||
it('should validate command on register', () => {
|
||||
const invalidCommand: SlashCommand = {
|
||||
name: '', // Invalid: empty name
|
||||
description: 'Test',
|
||||
skill: 'test',
|
||||
};
|
||||
|
||||
expect(() => registry.register(invalidCommand)).toThrow('Invalid command');
|
||||
});
|
||||
});
|
||||
|
||||
describe('unregister', () => {
|
||||
it('should unregister a command', () => {
|
||||
const command: SlashCommand = {
|
||||
name: 'test-cmd',
|
||||
description: 'Test command',
|
||||
skill: 'test-skill',
|
||||
aliases: ['tc'],
|
||||
};
|
||||
|
||||
registry.register(command);
|
||||
expect(registry.has('test-cmd')).toBe(true);
|
||||
|
||||
const result = registry.unregister('test-cmd');
|
||||
|
||||
expect(result).toBe(true);
|
||||
expect(registry.has('test-cmd')).toBe(false);
|
||||
expect(registry.has('tc')).toBe(false);
|
||||
});
|
||||
|
||||
it('should return false for non-existent command', () => {
|
||||
const result = registry.unregister('non-existent');
|
||||
expect(result).toBe(false);
|
||||
});
|
||||
});
|
||||
|
||||
describe('get', () => {
|
||||
it('should get command by name', () => {
|
||||
const command: SlashCommand = {
|
||||
name: 'test-cmd',
|
||||
description: 'Test command',
|
||||
skill: 'test-skill',
|
||||
};
|
||||
|
||||
registry.register(command);
|
||||
|
||||
const result = registry.get('test-cmd');
|
||||
expect(result?.name).toBe('test-cmd');
|
||||
});
|
||||
|
||||
it('should get command by alias', () => {
|
||||
const command: SlashCommand = {
|
||||
name: 'test-cmd',
|
||||
description: 'Test command',
|
||||
skill: 'test-skill',
|
||||
aliases: ['tc'],
|
||||
};
|
||||
|
||||
registry.register(command);
|
||||
|
||||
const result = registry.get('tc');
|
||||
expect(result?.name).toBe('test-cmd');
|
||||
});
|
||||
|
||||
it('should return undefined for non-existent command', () => {
|
||||
const result = registry.get('non-existent');
|
||||
expect(result).toBeUndefined();
|
||||
});
|
||||
});
|
||||
|
||||
describe('search', () => {
|
||||
beforeEach(() => {
|
||||
registry.register({
|
||||
name: 'test-one',
|
||||
description: 'First test command',
|
||||
skill: 'skill-one',
|
||||
category: 'testing',
|
||||
tags: ['test', 'one'],
|
||||
});
|
||||
registry.register({
|
||||
name: 'test-two',
|
||||
description: 'Second test command',
|
||||
skill: 'skill-two',
|
||||
category: 'testing',
|
||||
tags: ['test', 'two'],
|
||||
});
|
||||
registry.register({
|
||||
name: 'deploy',
|
||||
description: 'Deploy command',
|
||||
skill: 'deploy-skill',
|
||||
category: 'deployment',
|
||||
tags: ['deploy'],
|
||||
});
|
||||
});
|
||||
|
||||
it('should search by query', () => {
|
||||
const results = registry.search({ query: 'test' });
|
||||
expect(results).toHaveLength(2);
|
||||
});
|
||||
|
||||
it('should search by category', () => {
|
||||
const results = registry.search({ category: 'testing' });
|
||||
expect(results).toHaveLength(2);
|
||||
});
|
||||
|
||||
it('should search by tags', () => {
|
||||
const results = registry.search({ tags: ['deploy'] });
|
||||
expect(results).toHaveLength(1);
|
||||
expect(results[0].name).toBe('deploy');
|
||||
});
|
||||
|
||||
it('should limit results', () => {
|
||||
const results = registry.search({ limit: 1 });
|
||||
expect(results).toHaveLength(1);
|
||||
});
|
||||
});
|
||||
|
||||
describe('enable/disable', () => {
|
||||
it('should disable a command', () => {
|
||||
registry.register({
|
||||
name: 'test-cmd',
|
||||
description: 'Test command',
|
||||
skill: 'test-skill',
|
||||
});
|
||||
|
||||
registry.disable('test-cmd');
|
||||
|
||||
const cmd = registry.get('test-cmd');
|
||||
expect(cmd?.enabled).toBe(false);
|
||||
});
|
||||
|
||||
it('should enable a command', () => {
|
||||
registry.register({
|
||||
name: 'test-cmd',
|
||||
description: 'Test command',
|
||||
skill: 'test-skill',
|
||||
});
|
||||
|
||||
registry.disable('test-cmd');
|
||||
registry.enable('test-cmd');
|
||||
|
||||
const cmd = registry.get('test-cmd');
|
||||
expect(cmd?.enabled).toBe(true);
|
||||
});
|
||||
});
|
||||
|
||||
describe('execute', () => {
|
||||
it('should execute command with handler', async () => {
|
||||
registry.register(
|
||||
{
|
||||
name: 'test-cmd',
|
||||
description: 'Test command',
|
||||
skill: 'test-skill',
|
||||
},
|
||||
async () => ({
|
||||
success: true,
|
||||
output: 'Executed',
|
||||
})
|
||||
);
|
||||
|
||||
const context: Omit<CommandContext, 'command'> = {
|
||||
args: {},
|
||||
agent: 'claude-code' as AgentType,
|
||||
cwd: '/test',
|
||||
};
|
||||
|
||||
const result = await registry.execute('test-cmd', context);
|
||||
|
||||
expect(result.success).toBe(true);
|
||||
expect(result.output).toBe('Executed');
|
||||
});
|
||||
|
||||
it('should return error for non-existent command', async () => {
|
||||
const result = await registry.execute('non-existent', {
|
||||
args: {},
|
||||
agent: 'claude-code' as AgentType,
|
||||
cwd: '/test',
|
||||
});
|
||||
|
||||
expect(result.success).toBe(false);
|
||||
expect(result.error).toContain('not found');
|
||||
});
|
||||
|
||||
it('should return error for disabled command', async () => {
|
||||
registry.register({
|
||||
name: 'test-cmd',
|
||||
description: 'Test command',
|
||||
skill: 'test-skill',
|
||||
});
|
||||
registry.disable('test-cmd');
|
||||
|
||||
const result = await registry.execute('test-cmd', {
|
||||
args: {},
|
||||
agent: 'claude-code' as AgentType,
|
||||
cwd: '/test',
|
||||
});
|
||||
|
||||
expect(result.success).toBe(false);
|
||||
expect(result.error).toContain('disabled');
|
||||
});
|
||||
});
|
||||
|
||||
describe('validate', () => {
|
||||
it('should validate valid command', () => {
|
||||
const command: SlashCommand = {
|
||||
name: 'test-cmd',
|
||||
description: 'Test command',
|
||||
skill: 'test-skill',
|
||||
examples: ['/test-cmd'],
|
||||
};
|
||||
|
||||
const result = registry.validate(command);
|
||||
|
||||
expect(result.valid).toBe(true);
|
||||
expect(result.errors).toHaveLength(0);
|
||||
});
|
||||
|
||||
it('should reject command without name', () => {
|
||||
const command: SlashCommand = {
|
||||
name: '',
|
||||
description: 'Test command',
|
||||
skill: 'test-skill',
|
||||
};
|
||||
|
||||
const result = registry.validate(command);
|
||||
|
||||
expect(result.valid).toBe(false);
|
||||
expect(result.errors).toContain('Command must have a name');
|
||||
});
|
||||
|
||||
it('should reject command with invalid name format', () => {
|
||||
const command: SlashCommand = {
|
||||
name: 'INVALID_NAME',
|
||||
description: 'Test command',
|
||||
skill: 'test-skill',
|
||||
};
|
||||
|
||||
const result = registry.validate(command);
|
||||
|
||||
expect(result.valid).toBe(false);
|
||||
});
|
||||
|
||||
it('should warn about missing examples', () => {
|
||||
const command: SlashCommand = {
|
||||
name: 'test-cmd',
|
||||
description: 'Test command',
|
||||
skill: 'test-skill',
|
||||
};
|
||||
|
||||
const result = registry.validate(command);
|
||||
|
||||
expect(result.warnings).toContain('Command has no usage examples');
|
||||
});
|
||||
});
|
||||
|
||||
describe('export/import', () => {
|
||||
it('should export commands to bundle', () => {
|
||||
registry.register({
|
||||
name: 'test-cmd',
|
||||
description: 'Test command',
|
||||
skill: 'test-skill',
|
||||
});
|
||||
|
||||
const bundle = registry.export();
|
||||
|
||||
expect(bundle.version).toBe('1.0.0');
|
||||
expect(bundle.commands).toHaveLength(1);
|
||||
expect(bundle.commands[0].name).toBe('test-cmd');
|
||||
});
|
||||
|
||||
it('should import commands from bundle', () => {
|
||||
const bundle = {
|
||||
version: '1.0.0',
|
||||
commands: [
|
||||
{
|
||||
name: 'imported-cmd',
|
||||
description: 'Imported command',
|
||||
skill: 'imported-skill',
|
||||
},
|
||||
],
|
||||
};
|
||||
|
||||
const imported = registry.import(bundle);
|
||||
|
||||
expect(imported).toBe(1);
|
||||
expect(registry.has('imported-cmd')).toBe(true);
|
||||
});
|
||||
});
|
||||
|
||||
describe('getCategories', () => {
|
||||
it('should return unique categories', () => {
|
||||
registry.register({
|
||||
name: 'cmd-one',
|
||||
description: 'Command one',
|
||||
skill: 'skill',
|
||||
category: 'testing',
|
||||
});
|
||||
registry.register({
|
||||
name: 'cmd-two',
|
||||
description: 'Command two',
|
||||
skill: 'skill',
|
||||
category: 'debugging',
|
||||
});
|
||||
registry.register({
|
||||
name: 'cmd-three',
|
||||
description: 'Command three',
|
||||
skill: 'skill',
|
||||
category: 'testing',
|
||||
});
|
||||
|
||||
const categories = registry.getCategories();
|
||||
|
||||
expect(categories).toHaveLength(2);
|
||||
expect(categories).toContain('testing');
|
||||
expect(categories).toContain('debugging');
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
describe('CommandGenerator', () => {
|
||||
let generator: CommandGenerator;
|
||||
|
||||
beforeEach(() => {
|
||||
generator = createCommandGenerator();
|
||||
});
|
||||
|
||||
describe('fromSkill', () => {
|
||||
it('should generate command from skill', () => {
|
||||
const skill = {
|
||||
name: 'Test Skill',
|
||||
description: 'A test skill',
|
||||
content: 'Test content',
|
||||
tags: ['test'],
|
||||
};
|
||||
|
||||
const command = generator.fromSkill(skill);
|
||||
|
||||
expect(command.name).toBe('test-skill');
|
||||
expect(command.description).toBe('A test skill');
|
||||
expect(command.skill).toBe('Test Skill');
|
||||
});
|
||||
|
||||
it('should use custom command name', () => {
|
||||
const skill = {
|
||||
name: 'Test Skill',
|
||||
description: 'A test skill',
|
||||
content: 'Test content',
|
||||
};
|
||||
|
||||
const command = generator.fromSkill(skill, 'custom-name');
|
||||
|
||||
expect(command.name).toBe('custom-name');
|
||||
});
|
||||
});
|
||||
|
||||
describe('generateClaudeCommand', () => {
|
||||
it('should generate Claude Code command file', () => {
|
||||
const command: SlashCommand = {
|
||||
name: 'test-cmd',
|
||||
description: 'Test command',
|
||||
skill: 'test-skill',
|
||||
aliases: ['tc'],
|
||||
examples: ['/test-cmd'],
|
||||
};
|
||||
|
||||
const content = generator.generateClaudeCommand(command);
|
||||
|
||||
expect(content).toContain('name: test-cmd');
|
||||
expect(content).toContain('description: Test command');
|
||||
expect(content).toContain('aliases: [tc]');
|
||||
expect(content).toContain('# /test-cmd');
|
||||
});
|
||||
|
||||
it('should include args in frontmatter', () => {
|
||||
const command: SlashCommand = {
|
||||
name: 'test-cmd',
|
||||
description: 'Test command',
|
||||
skill: 'test-skill',
|
||||
args: [
|
||||
{
|
||||
name: 'file',
|
||||
description: 'File path',
|
||||
required: true,
|
||||
},
|
||||
],
|
||||
};
|
||||
|
||||
const content = generator.generateClaudeCommand(command);
|
||||
|
||||
expect(content).toContain('args:');
|
||||
expect(content).toContain('name: file');
|
||||
expect(content).toContain('required: true');
|
||||
});
|
||||
});
|
||||
|
||||
describe('generateCursorRules', () => {
|
||||
it('should generate Cursor rules with @-mentions', () => {
|
||||
const commands: SlashCommand[] = [
|
||||
{
|
||||
name: 'test-cmd',
|
||||
description: 'Test command',
|
||||
skill: 'test-skill',
|
||||
},
|
||||
];
|
||||
|
||||
const content = generator.generateCursorRules(commands);
|
||||
|
||||
expect(content).toContain('## @test-cmd');
|
||||
expect(content).toContain('Test command');
|
||||
});
|
||||
});
|
||||
|
||||
describe('generate', () => {
|
||||
const commands: SlashCommand[] = [
|
||||
{
|
||||
name: 'test-cmd',
|
||||
description: 'Test command',
|
||||
skill: 'test-skill',
|
||||
},
|
||||
];
|
||||
|
||||
it('should generate for claude-code', () => {
|
||||
const result = generator.generate(commands, 'claude-code');
|
||||
|
||||
expect(result instanceof Map).toBe(true);
|
||||
expect((result as Map<string, string>).has('test-cmd.md')).toBe(true);
|
||||
});
|
||||
|
||||
it('should generate for cursor', () => {
|
||||
const result = generator.generate(commands, 'cursor');
|
||||
|
||||
expect(typeof result).toBe('string');
|
||||
expect((result as string)).toContain('@test-cmd');
|
||||
});
|
||||
|
||||
it('should generate for opencode', () => {
|
||||
const result = generator.generate(commands, 'opencode');
|
||||
|
||||
expect(result instanceof Map).toBe(true);
|
||||
});
|
||||
|
||||
it('should generate for github-copilot', () => {
|
||||
const result = generator.generate(commands, 'github-copilot');
|
||||
|
||||
expect(result instanceof Map).toBe(true);
|
||||
});
|
||||
});
|
||||
|
||||
describe('generateManifest', () => {
|
||||
it('should generate JSON manifest', () => {
|
||||
const commands: SlashCommand[] = [
|
||||
{
|
||||
name: 'test-cmd',
|
||||
description: 'Test command',
|
||||
skill: 'test-skill',
|
||||
},
|
||||
];
|
||||
|
||||
const manifest = generator.generateManifest(commands);
|
||||
const parsed = JSON.parse(manifest);
|
||||
|
||||
expect(parsed.version).toBe('1.0.0');
|
||||
expect(parsed.commands).toHaveLength(1);
|
||||
expect(parsed.generatedAt).toBeDefined();
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
describe('getAgentFormat', () => {
|
||||
it('should return format for claude-code', () => {
|
||||
const format = getAgentFormat('claude-code');
|
||||
|
||||
expect(format.agent).toBe('claude-code');
|
||||
expect(format.directory).toBe('.claude/commands');
|
||||
expect(format.extension).toBe('.md');
|
||||
expect(format.supportsSlashCommands).toBe(true);
|
||||
});
|
||||
|
||||
it('should return format for cursor', () => {
|
||||
const format = getAgentFormat('cursor');
|
||||
|
||||
expect(format.agent).toBe('cursor');
|
||||
expect(format.supportsSlashCommands).toBe(false);
|
||||
});
|
||||
|
||||
it('should return universal format for unknown agent', () => {
|
||||
const format = getAgentFormat('unknown' as AgentType);
|
||||
|
||||
expect(format.agent).toBe('universal');
|
||||
});
|
||||
});
|
||||
|
||||
describe('supportsSlashCommands', () => {
|
||||
it('should return true for claude-code', () => {
|
||||
expect(supportsSlashCommands('claude-code')).toBe(true);
|
||||
});
|
||||
|
||||
it('should return false for cursor', () => {
|
||||
expect(supportsSlashCommands('cursor')).toBe(false);
|
||||
});
|
||||
|
||||
it('should return false for windsurf', () => {
|
||||
expect(supportsSlashCommands('windsurf')).toBe(false);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,532 @@
|
||||
/**
|
||||
* Command Generator
|
||||
*
|
||||
* Generates agent-specific slash commands from skills.
|
||||
*/
|
||||
|
||||
import type { AgentType } from '../types.js';
|
||||
import type { CanonicalSkill } from '../translator/types.js';
|
||||
import type {
|
||||
SlashCommand,
|
||||
CommandGeneratorOptions,
|
||||
AgentCommandFormat,
|
||||
RegisteredCommand,
|
||||
} from './types.js';
|
||||
|
||||
/**
|
||||
* Agent command formats
|
||||
*/
|
||||
const AGENT_FORMATS: Record<AgentType, AgentCommandFormat> = {
|
||||
'claude-code': {
|
||||
agent: 'claude-code',
|
||||
extension: '.md',
|
||||
directory: '.claude/commands',
|
||||
supportsSlashCommands: true,
|
||||
supportsCommandFiles: true,
|
||||
},
|
||||
cursor: {
|
||||
agent: 'cursor',
|
||||
extension: '.mdc',
|
||||
directory: '.cursor/rules',
|
||||
supportsSlashCommands: false,
|
||||
supportsCommandFiles: true,
|
||||
},
|
||||
codex: {
|
||||
agent: 'codex',
|
||||
extension: '.md',
|
||||
directory: '.codex/commands',
|
||||
supportsSlashCommands: true,
|
||||
supportsCommandFiles: true,
|
||||
},
|
||||
'gemini-cli': {
|
||||
agent: 'gemini-cli',
|
||||
extension: '.md',
|
||||
directory: '.gemini/commands',
|
||||
supportsSlashCommands: true,
|
||||
supportsCommandFiles: true,
|
||||
},
|
||||
opencode: {
|
||||
agent: 'opencode',
|
||||
extension: '.md',
|
||||
directory: '.opencode/commands',
|
||||
supportsSlashCommands: true,
|
||||
supportsCommandFiles: true,
|
||||
},
|
||||
antigravity: {
|
||||
agent: 'antigravity',
|
||||
extension: '.md',
|
||||
directory: '.antigravity/commands',
|
||||
supportsSlashCommands: true,
|
||||
supportsCommandFiles: true,
|
||||
},
|
||||
amp: {
|
||||
agent: 'amp',
|
||||
extension: '.md',
|
||||
directory: '.amp/commands',
|
||||
supportsSlashCommands: true,
|
||||
supportsCommandFiles: true,
|
||||
},
|
||||
clawdbot: {
|
||||
agent: 'clawdbot',
|
||||
extension: '.md',
|
||||
directory: '.clawdbot/commands',
|
||||
supportsSlashCommands: true,
|
||||
supportsCommandFiles: true,
|
||||
},
|
||||
droid: {
|
||||
agent: 'droid',
|
||||
extension: '.md',
|
||||
directory: '.factory/commands',
|
||||
supportsSlashCommands: true,
|
||||
supportsCommandFiles: true,
|
||||
},
|
||||
'github-copilot': {
|
||||
agent: 'github-copilot',
|
||||
extension: '.md',
|
||||
directory: '.github/copilot/commands',
|
||||
supportsSlashCommands: true,
|
||||
supportsCommandFiles: true,
|
||||
},
|
||||
goose: {
|
||||
agent: 'goose',
|
||||
extension: '.md',
|
||||
directory: '.goose/commands',
|
||||
supportsSlashCommands: true,
|
||||
supportsCommandFiles: true,
|
||||
},
|
||||
kilo: {
|
||||
agent: 'kilo',
|
||||
extension: '.md',
|
||||
directory: '.kilocode/commands',
|
||||
supportsSlashCommands: true,
|
||||
supportsCommandFiles: true,
|
||||
},
|
||||
'kiro-cli': {
|
||||
agent: 'kiro-cli',
|
||||
extension: '.md',
|
||||
directory: '.kiro/commands',
|
||||
supportsSlashCommands: true,
|
||||
supportsCommandFiles: true,
|
||||
},
|
||||
roo: {
|
||||
agent: 'roo',
|
||||
extension: '.md',
|
||||
directory: '.roo/commands',
|
||||
supportsSlashCommands: true,
|
||||
supportsCommandFiles: true,
|
||||
},
|
||||
trae: {
|
||||
agent: 'trae',
|
||||
extension: '.md',
|
||||
directory: '.trae/commands',
|
||||
supportsSlashCommands: true,
|
||||
supportsCommandFiles: true,
|
||||
},
|
||||
windsurf: {
|
||||
agent: 'windsurf',
|
||||
extension: '.md',
|
||||
directory: '.windsurf/commands',
|
||||
supportsSlashCommands: false,
|
||||
supportsCommandFiles: true,
|
||||
},
|
||||
universal: {
|
||||
agent: 'universal',
|
||||
extension: '.md',
|
||||
directory: 'commands',
|
||||
supportsSlashCommands: true,
|
||||
supportsCommandFiles: true,
|
||||
},
|
||||
};
|
||||
|
||||
/**
|
||||
* CommandGenerator - Generate agent-specific commands
|
||||
*/
|
||||
export class CommandGenerator {
|
||||
private options: Partial<CommandGeneratorOptions>;
|
||||
|
||||
constructor(options?: Partial<CommandGeneratorOptions>) {
|
||||
this.options = options || {};
|
||||
}
|
||||
|
||||
/**
|
||||
* Get agent command format
|
||||
*/
|
||||
getAgentFormat(agent: AgentType): AgentCommandFormat {
|
||||
return AGENT_FORMATS[agent] || AGENT_FORMATS.universal;
|
||||
}
|
||||
|
||||
/**
|
||||
* Generate command from skill
|
||||
*/
|
||||
fromSkill(skill: CanonicalSkill, commandName?: string): SlashCommand {
|
||||
return {
|
||||
name: commandName || this.slugify(skill.name),
|
||||
description: skill.description || `Execute ${skill.name} skill`,
|
||||
skill: skill.name,
|
||||
tags: skill.tags,
|
||||
category: this.inferCategory(skill),
|
||||
examples: this.generateExamples(skill, commandName || this.slugify(skill.name)),
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Generate commands from multiple skills
|
||||
*/
|
||||
fromSkills(skills: CanonicalSkill[]): SlashCommand[] {
|
||||
return skills.map((skill) => this.fromSkill(skill));
|
||||
}
|
||||
|
||||
/**
|
||||
* Generate Claude Code command file
|
||||
*/
|
||||
generateClaudeCommand(command: SlashCommand | RegisteredCommand): string {
|
||||
const lines: string[] = [];
|
||||
|
||||
// Frontmatter
|
||||
lines.push('---');
|
||||
lines.push(`name: ${command.name}`);
|
||||
lines.push(`description: ${command.description}`);
|
||||
if (command.aliases && command.aliases.length > 0) {
|
||||
lines.push(`aliases: [${command.aliases.join(', ')}]`);
|
||||
}
|
||||
if (command.disableModelInvocation) {
|
||||
lines.push('disableModelInvocation: true');
|
||||
}
|
||||
if (command.args && command.args.length > 0) {
|
||||
lines.push('args:');
|
||||
for (const arg of command.args) {
|
||||
lines.push(` - name: ${arg.name}`);
|
||||
lines.push(` description: ${arg.description}`);
|
||||
if (arg.required) lines.push(` required: true`);
|
||||
if (arg.default) lines.push(` default: "${arg.default}"`);
|
||||
}
|
||||
}
|
||||
lines.push('---');
|
||||
lines.push('');
|
||||
|
||||
// Command content
|
||||
lines.push(`# /${command.name}`);
|
||||
lines.push('');
|
||||
lines.push(command.description);
|
||||
lines.push('');
|
||||
|
||||
// Usage examples
|
||||
if (command.examples && command.examples.length > 0) {
|
||||
lines.push('## Usage');
|
||||
lines.push('');
|
||||
for (const example of command.examples) {
|
||||
lines.push(`- ${example}`);
|
||||
}
|
||||
lines.push('');
|
||||
}
|
||||
|
||||
// Skill reference
|
||||
lines.push('## Skill');
|
||||
lines.push('');
|
||||
lines.push(`This command invokes the \`${command.skill}\` skill.`);
|
||||
lines.push('');
|
||||
|
||||
return lines.join('\n');
|
||||
}
|
||||
|
||||
/**
|
||||
* Generate Claude Code commands
|
||||
*/
|
||||
generateClaudeCommands(commands: (SlashCommand | RegisteredCommand)[]): Map<string, string> {
|
||||
const files = new Map<string, string>();
|
||||
for (const command of commands) {
|
||||
if (this.shouldInclude(command)) {
|
||||
const filename = `${command.name}.md`;
|
||||
files.set(filename, this.generateClaudeCommand(command));
|
||||
}
|
||||
}
|
||||
return files;
|
||||
}
|
||||
|
||||
/**
|
||||
* Generate Cursor rules with @-mention syntax
|
||||
*/
|
||||
generateCursorRules(commands: (SlashCommand | RegisteredCommand)[]): string {
|
||||
const lines: string[] = [];
|
||||
|
||||
lines.push('---');
|
||||
lines.push('description: Available commands');
|
||||
lines.push('globs: ["**/*"]');
|
||||
lines.push('---');
|
||||
lines.push('');
|
||||
lines.push('# Available Commands');
|
||||
lines.push('');
|
||||
lines.push('You can invoke the following commands using @-mentions:');
|
||||
lines.push('');
|
||||
|
||||
for (const command of commands) {
|
||||
if (this.shouldInclude(command)) {
|
||||
lines.push(`## @${command.name}`);
|
||||
lines.push('');
|
||||
lines.push(command.description);
|
||||
lines.push('');
|
||||
if (command.examples && command.examples.length > 0) {
|
||||
lines.push('**Usage:**');
|
||||
for (const example of command.examples) {
|
||||
lines.push(`- ${example}`);
|
||||
}
|
||||
lines.push('');
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return lines.join('\n');
|
||||
}
|
||||
|
||||
/**
|
||||
* Generate OpenCode commands
|
||||
*/
|
||||
generateOpenCodeCommands(commands: (SlashCommand | RegisteredCommand)[]): Map<string, string> {
|
||||
const files = new Map<string, string>();
|
||||
|
||||
for (const command of commands) {
|
||||
if (this.shouldInclude(command)) {
|
||||
const lines: string[] = [];
|
||||
|
||||
// SKILL.md format with command metadata
|
||||
lines.push('---');
|
||||
lines.push(`name: ${command.name}`);
|
||||
lines.push(`description: ${command.description}`);
|
||||
lines.push('type: command');
|
||||
if (command.aliases && command.aliases.length > 0) {
|
||||
lines.push(`aliases: [${command.aliases.join(', ')}]`);
|
||||
}
|
||||
lines.push('---');
|
||||
lines.push('');
|
||||
lines.push(`# ${command.name}`);
|
||||
lines.push('');
|
||||
lines.push(command.description);
|
||||
lines.push('');
|
||||
|
||||
if (command.args && command.args.length > 0) {
|
||||
lines.push('## Arguments');
|
||||
lines.push('');
|
||||
for (const arg of command.args) {
|
||||
const required = arg.required ? '(required)' : '(optional)';
|
||||
lines.push(`- \`${arg.name}\` ${required}: ${arg.description}`);
|
||||
}
|
||||
lines.push('');
|
||||
}
|
||||
|
||||
if (command.examples && command.examples.length > 0) {
|
||||
lines.push('## Examples');
|
||||
lines.push('');
|
||||
for (const example of command.examples) {
|
||||
lines.push(`- ${example}`);
|
||||
}
|
||||
lines.push('');
|
||||
}
|
||||
|
||||
lines.push('## Skill Reference');
|
||||
lines.push('');
|
||||
lines.push(`Invokes: \`${command.skill}\``);
|
||||
lines.push('');
|
||||
|
||||
const filename = `${command.name}.md`;
|
||||
files.set(filename, lines.join('\n'));
|
||||
}
|
||||
}
|
||||
|
||||
return files;
|
||||
}
|
||||
|
||||
/**
|
||||
* Generate Copilot commands (agent skills format)
|
||||
*/
|
||||
generateCopilotCommands(commands: (SlashCommand | RegisteredCommand)[]): Map<string, string> {
|
||||
const files = new Map<string, string>();
|
||||
|
||||
for (const command of commands) {
|
||||
if (this.shouldInclude(command)) {
|
||||
const lines: string[] = [];
|
||||
|
||||
lines.push(`# ${command.name}`);
|
||||
lines.push('');
|
||||
lines.push(`> ${command.description}`);
|
||||
lines.push('');
|
||||
|
||||
if (command.args && command.args.length > 0) {
|
||||
lines.push('## Parameters');
|
||||
lines.push('');
|
||||
lines.push('| Name | Required | Description |');
|
||||
lines.push('|------|----------|-------------|');
|
||||
for (const arg of command.args) {
|
||||
lines.push(`| ${arg.name} | ${arg.required ? 'Yes' : 'No'} | ${arg.description} |`);
|
||||
}
|
||||
lines.push('');
|
||||
}
|
||||
|
||||
if (command.examples && command.examples.length > 0) {
|
||||
lines.push('## Examples');
|
||||
lines.push('');
|
||||
for (const example of command.examples) {
|
||||
lines.push(`\`\`\`\n${example}\n\`\`\``);
|
||||
}
|
||||
lines.push('');
|
||||
}
|
||||
|
||||
lines.push('## Implementation');
|
||||
lines.push('');
|
||||
lines.push(`This command is powered by the \`${command.skill}\` skill.`);
|
||||
lines.push('');
|
||||
|
||||
const filename = `${command.name}.md`;
|
||||
files.set(filename, lines.join('\n'));
|
||||
}
|
||||
}
|
||||
|
||||
return files;
|
||||
}
|
||||
|
||||
/**
|
||||
* Generate commands for any agent
|
||||
*/
|
||||
generate(
|
||||
commands: (SlashCommand | RegisteredCommand)[],
|
||||
agent: AgentType
|
||||
): Map<string, string> | string {
|
||||
switch (agent) {
|
||||
case 'claude-code':
|
||||
case 'codex':
|
||||
case 'gemini-cli':
|
||||
case 'amp':
|
||||
case 'roo':
|
||||
case 'kiro-cli':
|
||||
return this.generateClaudeCommands(commands);
|
||||
|
||||
case 'cursor':
|
||||
return this.generateCursorRules(commands);
|
||||
|
||||
case 'opencode':
|
||||
return this.generateOpenCodeCommands(commands);
|
||||
|
||||
case 'github-copilot':
|
||||
return this.generateCopilotCommands(commands);
|
||||
|
||||
default:
|
||||
// Use Claude Code format as default
|
||||
return this.generateClaudeCommands(commands);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Generate JSON manifest of commands
|
||||
*/
|
||||
generateManifest(commands: (SlashCommand | RegisteredCommand)[]): string {
|
||||
const manifest = {
|
||||
version: '1.0.0',
|
||||
commands: commands.filter((c) => this.shouldInclude(c)).map((c) => ({
|
||||
name: c.name,
|
||||
description: c.description,
|
||||
skill: c.skill,
|
||||
aliases: c.aliases,
|
||||
args: c.args,
|
||||
category: c.category,
|
||||
tags: c.tags,
|
||||
})),
|
||||
generatedAt: new Date().toISOString(),
|
||||
};
|
||||
|
||||
return JSON.stringify(manifest, null, 2);
|
||||
}
|
||||
|
||||
/**
|
||||
* Check if command should be included
|
||||
*/
|
||||
private shouldInclude(command: SlashCommand | RegisteredCommand): boolean {
|
||||
// Check hidden
|
||||
if (command.hidden && !this.options.includeHidden) {
|
||||
return false;
|
||||
}
|
||||
|
||||
// Check enabled (for RegisteredCommand)
|
||||
if ('enabled' in command && !command.enabled && !this.options.includeDisabled) {
|
||||
return false;
|
||||
}
|
||||
|
||||
return true;
|
||||
}
|
||||
|
||||
/**
|
||||
* Slugify a string for command name
|
||||
*/
|
||||
private slugify(str: string): string {
|
||||
return str
|
||||
.toLowerCase()
|
||||
.replace(/[^a-z0-9]+/g, '-')
|
||||
.replace(/^-|-$/g, '');
|
||||
}
|
||||
|
||||
/**
|
||||
* Infer category from skill
|
||||
*/
|
||||
private inferCategory(skill: CanonicalSkill): string | undefined {
|
||||
const tags = skill.tags || [];
|
||||
const name = skill.name.toLowerCase();
|
||||
|
||||
if (tags.includes('testing') || name.includes('test')) {
|
||||
return 'testing';
|
||||
}
|
||||
if (tags.includes('debugging') || name.includes('debug')) {
|
||||
return 'debugging';
|
||||
}
|
||||
if (tags.includes('planning') || name.includes('plan')) {
|
||||
return 'planning';
|
||||
}
|
||||
if (tags.includes('collaboration') || name.includes('review')) {
|
||||
return 'collaboration';
|
||||
}
|
||||
if (tags.includes('git') || name.includes('commit') || name.includes('branch')) {
|
||||
return 'git';
|
||||
}
|
||||
|
||||
return undefined;
|
||||
}
|
||||
|
||||
/**
|
||||
* Generate usage examples
|
||||
*/
|
||||
private generateExamples(skill: CanonicalSkill, commandName: string): string[] {
|
||||
const examples: string[] = [];
|
||||
|
||||
examples.push(`/${commandName}`);
|
||||
|
||||
// Add examples based on skill content
|
||||
if (skill.content.toLowerCase().includes('file')) {
|
||||
examples.push(`/${commandName} path/to/file.ts`);
|
||||
}
|
||||
|
||||
if (skill.content.toLowerCase().includes('test')) {
|
||||
examples.push(`/${commandName} --run-tests`);
|
||||
}
|
||||
|
||||
return examples;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Create a CommandGenerator instance
|
||||
*/
|
||||
export function createCommandGenerator(options?: Partial<CommandGeneratorOptions>): CommandGenerator {
|
||||
return new CommandGenerator(options);
|
||||
}
|
||||
|
||||
/**
|
||||
* Get agent format info
|
||||
*/
|
||||
export function getAgentFormat(agent: AgentType): AgentCommandFormat {
|
||||
return AGENT_FORMATS[agent] || AGENT_FORMATS.universal;
|
||||
}
|
||||
|
||||
/**
|
||||
* Check if agent supports slash commands
|
||||
*/
|
||||
export function supportsSlashCommands(agent: AgentType): boolean {
|
||||
const format = AGENT_FORMATS[agent];
|
||||
return format?.supportsSlashCommands ?? true;
|
||||
}
|
||||
@@ -0,0 +1,9 @@
|
||||
/**
|
||||
* Commands Module
|
||||
*
|
||||
* Slash commands and agent integration.
|
||||
*/
|
||||
|
||||
export * from './types.js';
|
||||
export * from './registry.js';
|
||||
export * from './generator.js';
|
||||
@@ -0,0 +1,428 @@
|
||||
/**
|
||||
* Command Registry
|
||||
*
|
||||
* Central registry for managing slash commands.
|
||||
*/
|
||||
|
||||
import type {
|
||||
SlashCommand,
|
||||
RegisteredCommand,
|
||||
CommandRegistryOptions,
|
||||
CommandSearchOptions,
|
||||
CommandValidationResult,
|
||||
CommandHandler,
|
||||
CommandEvent,
|
||||
CommandEventListener,
|
||||
CommandContext,
|
||||
SlashCommandResult,
|
||||
CommandBundle,
|
||||
} from './types.js';
|
||||
|
||||
/**
|
||||
* CommandRegistry - Central registry for slash commands
|
||||
*/
|
||||
export class CommandRegistry {
|
||||
private commands: Map<string, RegisteredCommand> = new Map();
|
||||
private aliases: Map<string, string> = new Map();
|
||||
private listeners: Set<CommandEventListener> = new Set();
|
||||
private options: CommandRegistryOptions;
|
||||
|
||||
constructor(options?: CommandRegistryOptions) {
|
||||
this.options = {
|
||||
allowOverrides: false,
|
||||
validateOnRegister: true,
|
||||
...options,
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Register a command
|
||||
*/
|
||||
register(command: SlashCommand, handler?: CommandHandler, source?: string): void {
|
||||
// Validate if enabled
|
||||
if (this.options.validateOnRegister) {
|
||||
const validation = this.validate(command);
|
||||
if (!validation.valid) {
|
||||
throw new Error(`Invalid command: ${validation.errors.join(', ')}`);
|
||||
}
|
||||
}
|
||||
|
||||
// Check for existing command
|
||||
if (this.commands.has(command.name) && !this.options.allowOverrides) {
|
||||
throw new Error(`Command already registered: ${command.name}`);
|
||||
}
|
||||
|
||||
// Create registered command
|
||||
const registered: RegisteredCommand = {
|
||||
...command,
|
||||
handler: handler || this.options.defaultHandler,
|
||||
enabled: true,
|
||||
source,
|
||||
};
|
||||
|
||||
// Register command
|
||||
this.commands.set(command.name, registered);
|
||||
|
||||
// Register aliases
|
||||
if (command.aliases) {
|
||||
for (const alias of command.aliases) {
|
||||
this.aliases.set(alias, command.name);
|
||||
}
|
||||
}
|
||||
|
||||
this.emit('command:registered', registered);
|
||||
}
|
||||
|
||||
/**
|
||||
* Register multiple commands
|
||||
*/
|
||||
registerAll(commands: SlashCommand[], handler?: CommandHandler, source?: string): void {
|
||||
for (const command of commands) {
|
||||
this.register(command, handler, source);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Unregister a command
|
||||
*/
|
||||
unregister(name: string): boolean {
|
||||
const command = this.commands.get(name);
|
||||
if (!command) {
|
||||
return false;
|
||||
}
|
||||
|
||||
// Remove aliases
|
||||
if (command.aliases) {
|
||||
for (const alias of command.aliases) {
|
||||
this.aliases.delete(alias);
|
||||
}
|
||||
}
|
||||
|
||||
this.commands.delete(name);
|
||||
this.emit('command:unregistered', command);
|
||||
return true;
|
||||
}
|
||||
|
||||
/**
|
||||
* Get a command by name or alias
|
||||
*/
|
||||
get(name: string): RegisteredCommand | undefined {
|
||||
// Check direct name
|
||||
const command = this.commands.get(name);
|
||||
if (command) {
|
||||
return command;
|
||||
}
|
||||
|
||||
// Check aliases
|
||||
const aliasTarget = this.aliases.get(name);
|
||||
if (aliasTarget) {
|
||||
return this.commands.get(aliasTarget);
|
||||
}
|
||||
|
||||
return undefined;
|
||||
}
|
||||
|
||||
/**
|
||||
* Check if a command exists
|
||||
*/
|
||||
has(name: string): boolean {
|
||||
return this.commands.has(name) || this.aliases.has(name);
|
||||
}
|
||||
|
||||
/**
|
||||
* Get all registered commands
|
||||
*/
|
||||
getAll(includeDisabled = false): RegisteredCommand[] {
|
||||
const commands = Array.from(this.commands.values());
|
||||
return includeDisabled ? commands : commands.filter((c) => c.enabled);
|
||||
}
|
||||
|
||||
/**
|
||||
* Search commands
|
||||
*/
|
||||
search(options?: CommandSearchOptions): RegisteredCommand[] {
|
||||
let commands = this.getAll(options?.includeDisabled);
|
||||
|
||||
// Filter hidden
|
||||
if (!options?.includeHidden) {
|
||||
commands = commands.filter((c) => !c.hidden);
|
||||
}
|
||||
|
||||
// Filter by category
|
||||
if (options?.category) {
|
||||
commands = commands.filter((c) => c.category === options.category);
|
||||
}
|
||||
|
||||
// Filter by tags
|
||||
if (options?.tags && options.tags.length > 0) {
|
||||
commands = commands.filter((c) => c.tags && options.tags!.some((t) => c.tags!.includes(t)));
|
||||
}
|
||||
|
||||
// Search by query
|
||||
if (options?.query) {
|
||||
const query = options.query.toLowerCase();
|
||||
commands = commands.filter(
|
||||
(c) =>
|
||||
c.name.toLowerCase().includes(query) ||
|
||||
c.description.toLowerCase().includes(query) ||
|
||||
c.aliases?.some((a) => a.toLowerCase().includes(query))
|
||||
);
|
||||
}
|
||||
|
||||
// Sort by priority
|
||||
commands.sort((a, b) => (b.priority || 0) - (a.priority || 0));
|
||||
|
||||
// Limit results
|
||||
if (options?.limit) {
|
||||
commands = commands.slice(0, options.limit);
|
||||
}
|
||||
|
||||
return commands;
|
||||
}
|
||||
|
||||
/**
|
||||
* Enable a command
|
||||
*/
|
||||
enable(name: string): boolean {
|
||||
const command = this.commands.get(name);
|
||||
if (!command) {
|
||||
return false;
|
||||
}
|
||||
|
||||
command.enabled = true;
|
||||
this.emit('command:enabled', command);
|
||||
return true;
|
||||
}
|
||||
|
||||
/**
|
||||
* Disable a command
|
||||
*/
|
||||
disable(name: string): boolean {
|
||||
const command = this.commands.get(name);
|
||||
if (!command) {
|
||||
return false;
|
||||
}
|
||||
|
||||
command.enabled = false;
|
||||
this.emit('command:disabled', command);
|
||||
return true;
|
||||
}
|
||||
|
||||
/**
|
||||
* Execute a command
|
||||
*/
|
||||
async execute(name: string, context: Omit<CommandContext, 'command'>): Promise<SlashCommandResult> {
|
||||
const command = this.get(name);
|
||||
if (!command) {
|
||||
return {
|
||||
success: false,
|
||||
error: `Command not found: ${name}`,
|
||||
};
|
||||
}
|
||||
|
||||
if (!command.enabled) {
|
||||
return {
|
||||
success: false,
|
||||
error: `Command is disabled: ${name}`,
|
||||
};
|
||||
}
|
||||
|
||||
if (!command.handler) {
|
||||
return {
|
||||
success: false,
|
||||
error: `Command has no handler: ${name}`,
|
||||
};
|
||||
}
|
||||
|
||||
const startTime = Date.now();
|
||||
|
||||
try {
|
||||
const result = await command.handler({
|
||||
...context,
|
||||
command,
|
||||
});
|
||||
|
||||
result.durationMs = Date.now() - startTime;
|
||||
this.emit('command:executed', command, result);
|
||||
return result;
|
||||
} catch (error) {
|
||||
const result: SlashCommandResult = {
|
||||
success: false,
|
||||
error: (error as Error).message,
|
||||
durationMs: Date.now() - startTime,
|
||||
};
|
||||
this.emit('command:failed', command, result);
|
||||
return result;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Validate a command
|
||||
*/
|
||||
validate(command: SlashCommand): CommandValidationResult {
|
||||
const errors: string[] = [];
|
||||
const warnings: string[] = [];
|
||||
|
||||
// Name is required
|
||||
if (!command.name || !command.name.trim()) {
|
||||
errors.push('Command must have a name');
|
||||
} else {
|
||||
// Name format validation
|
||||
if (!/^[a-z][a-z0-9-]*$/.test(command.name)) {
|
||||
errors.push('Command name must start with a letter and contain only lowercase letters, numbers, and hyphens');
|
||||
}
|
||||
}
|
||||
|
||||
// Description is required
|
||||
if (!command.description || !command.description.trim()) {
|
||||
errors.push('Command must have a description');
|
||||
}
|
||||
|
||||
// Skill is required
|
||||
if (!command.skill || !command.skill.trim()) {
|
||||
errors.push('Command must reference a skill');
|
||||
}
|
||||
|
||||
// Validate aliases
|
||||
if (command.aliases) {
|
||||
for (const alias of command.aliases) {
|
||||
if (!/^[a-z][a-z0-9-]*$/.test(alias)) {
|
||||
errors.push(`Invalid alias format: ${alias}`);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Validate args
|
||||
if (command.args) {
|
||||
const argNames = new Set<string>();
|
||||
for (const arg of command.args) {
|
||||
if (!arg.name || !arg.name.trim()) {
|
||||
errors.push('Argument must have a name');
|
||||
} else if (argNames.has(arg.name)) {
|
||||
errors.push(`Duplicate argument name: ${arg.name}`);
|
||||
} else {
|
||||
argNames.add(arg.name);
|
||||
}
|
||||
|
||||
if (!arg.description || !arg.description.trim()) {
|
||||
warnings.push(`Argument ${arg.name} has no description`);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Validate examples
|
||||
if (!command.examples || command.examples.length === 0) {
|
||||
warnings.push('Command has no usage examples');
|
||||
}
|
||||
|
||||
return {
|
||||
valid: errors.length === 0,
|
||||
errors,
|
||||
warnings,
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Get categories
|
||||
*/
|
||||
getCategories(): string[] {
|
||||
const categories = new Set<string>();
|
||||
for (const command of this.commands.values()) {
|
||||
if (command.category) {
|
||||
categories.add(command.category);
|
||||
}
|
||||
}
|
||||
return Array.from(categories).sort();
|
||||
}
|
||||
|
||||
/**
|
||||
* Get commands by category
|
||||
*/
|
||||
getByCategory(category: string): RegisteredCommand[] {
|
||||
return this.getAll().filter((c) => c.category === category);
|
||||
}
|
||||
|
||||
/**
|
||||
* Export commands to bundle
|
||||
*/
|
||||
export(includeDisabled = false): CommandBundle {
|
||||
const commands = this.getAll(includeDisabled).map((c) => {
|
||||
// eslint-disable-next-line @typescript-eslint/no-unused-vars
|
||||
const { handler, enabled, source, ...command } = c;
|
||||
return command;
|
||||
});
|
||||
|
||||
return {
|
||||
version: '1.0.0',
|
||||
commands,
|
||||
metadata: {
|
||||
createdAt: new Date(),
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Import commands from bundle
|
||||
*/
|
||||
import(bundle: CommandBundle, handler?: CommandHandler, source?: string): number {
|
||||
let imported = 0;
|
||||
for (const command of bundle.commands) {
|
||||
try {
|
||||
this.register(command, handler, source);
|
||||
imported++;
|
||||
} catch {
|
||||
// Skip commands that fail to register
|
||||
}
|
||||
}
|
||||
return imported;
|
||||
}
|
||||
|
||||
/**
|
||||
* Clear all commands
|
||||
*/
|
||||
clear(): void {
|
||||
this.commands.clear();
|
||||
this.aliases.clear();
|
||||
}
|
||||
|
||||
/**
|
||||
* Get command count
|
||||
*/
|
||||
get size(): number {
|
||||
return this.commands.size;
|
||||
}
|
||||
|
||||
/**
|
||||
* Add event listener
|
||||
*/
|
||||
addListener(listener: CommandEventListener): void {
|
||||
this.listeners.add(listener);
|
||||
}
|
||||
|
||||
/**
|
||||
* Remove event listener
|
||||
*/
|
||||
removeListener(listener: CommandEventListener): void {
|
||||
this.listeners.delete(listener);
|
||||
}
|
||||
|
||||
/**
|
||||
* Emit event
|
||||
*/
|
||||
private emit(event: CommandEvent, command: RegisteredCommand, result?: SlashCommandResult): void {
|
||||
for (const listener of this.listeners) {
|
||||
try {
|
||||
listener(event, command, result);
|
||||
} catch {
|
||||
// Ignore listener errors
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Create a CommandRegistry instance
|
||||
*/
|
||||
export function createCommandRegistry(options?: CommandRegistryOptions): CommandRegistry {
|
||||
return new CommandRegistry(options);
|
||||
}
|
||||
@@ -0,0 +1,221 @@
|
||||
/**
|
||||
* Command Types
|
||||
*
|
||||
* Type definitions for slash commands and agent integration.
|
||||
*/
|
||||
|
||||
import type { AgentType } from '../types.js';
|
||||
|
||||
/**
|
||||
* Command argument definition
|
||||
*/
|
||||
export interface CommandArg {
|
||||
/** Argument name */
|
||||
name: string;
|
||||
/** Argument description */
|
||||
description: string;
|
||||
/** Whether the argument is required */
|
||||
required?: boolean;
|
||||
/** Default value */
|
||||
default?: string;
|
||||
/** Argument type */
|
||||
type?: 'string' | 'number' | 'boolean' | 'file' | 'choice';
|
||||
/** Valid choices (for type: 'choice') */
|
||||
choices?: string[];
|
||||
/** Validation pattern (regex) */
|
||||
pattern?: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* Slash command definition
|
||||
*/
|
||||
export interface SlashCommand {
|
||||
/** Command name (without slash) */
|
||||
name: string;
|
||||
/** Command description */
|
||||
description: string;
|
||||
/** Skill to invoke when command is executed */
|
||||
skill: string;
|
||||
/** Alternative names for the command */
|
||||
aliases?: string[];
|
||||
/** Whether to disable model invocation (user-only) */
|
||||
disableModelInvocation?: boolean;
|
||||
/** Command arguments */
|
||||
args?: CommandArg[];
|
||||
/** Category for grouping */
|
||||
category?: string;
|
||||
/** Usage examples */
|
||||
examples?: string[];
|
||||
/** Tags for filtering */
|
||||
tags?: string[];
|
||||
/** Priority for ordering */
|
||||
priority?: number;
|
||||
/** Whether the command is hidden from help */
|
||||
hidden?: boolean;
|
||||
/** Metadata */
|
||||
metadata?: Record<string, unknown>;
|
||||
}
|
||||
|
||||
/**
|
||||
* Command execution context
|
||||
*/
|
||||
export interface CommandContext {
|
||||
/** The command being executed */
|
||||
command: SlashCommand;
|
||||
/** Parsed arguments */
|
||||
args: Record<string, unknown>;
|
||||
/** Agent executing the command */
|
||||
agent: AgentType;
|
||||
/** Working directory */
|
||||
cwd: string;
|
||||
/** Environment variables */
|
||||
env?: Record<string, string>;
|
||||
/** Additional context */
|
||||
metadata?: Record<string, unknown>;
|
||||
}
|
||||
|
||||
/**
|
||||
* Command execution result
|
||||
*/
|
||||
export interface SlashCommandResult {
|
||||
/** Whether execution succeeded */
|
||||
success: boolean;
|
||||
/** Output message */
|
||||
output?: string;
|
||||
/** Error message if failed */
|
||||
error?: string;
|
||||
/** Data returned by the command */
|
||||
data?: unknown;
|
||||
/** Duration in milliseconds */
|
||||
durationMs?: number;
|
||||
}
|
||||
|
||||
/**
|
||||
* Command handler function
|
||||
*/
|
||||
export type CommandHandler = (context: CommandContext) => Promise<SlashCommandResult>;
|
||||
|
||||
/**
|
||||
* Registered command with handler
|
||||
*/
|
||||
export interface RegisteredCommand extends SlashCommand {
|
||||
/** Command handler function */
|
||||
handler?: CommandHandler;
|
||||
/** Whether the command is enabled */
|
||||
enabled: boolean;
|
||||
/** Source of the command (plugin, skill, etc.) */
|
||||
source?: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* Command registry options
|
||||
*/
|
||||
export interface CommandRegistryOptions {
|
||||
/** Allow command overrides */
|
||||
allowOverrides?: boolean;
|
||||
/** Validate commands on registration */
|
||||
validateOnRegister?: boolean;
|
||||
/** Default handler for commands without one */
|
||||
defaultHandler?: CommandHandler;
|
||||
}
|
||||
|
||||
/**
|
||||
* Command generator options
|
||||
*/
|
||||
export interface CommandGeneratorOptions {
|
||||
/** Target agent */
|
||||
agent: AgentType;
|
||||
/** Include hidden commands */
|
||||
includeHidden?: boolean;
|
||||
/** Include disabled commands */
|
||||
includeDisabled?: boolean;
|
||||
/** Output format */
|
||||
format?: 'markdown' | 'json' | 'native';
|
||||
/** Custom template */
|
||||
template?: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* Command search options
|
||||
*/
|
||||
export interface CommandSearchOptions {
|
||||
/** Search query */
|
||||
query?: string;
|
||||
/** Filter by category */
|
||||
category?: string;
|
||||
/** Filter by tags */
|
||||
tags?: string[];
|
||||
/** Include hidden commands */
|
||||
includeHidden?: boolean;
|
||||
/** Include disabled commands */
|
||||
includeDisabled?: boolean;
|
||||
/** Maximum results */
|
||||
limit?: number;
|
||||
}
|
||||
|
||||
/**
|
||||
* Command validation result
|
||||
*/
|
||||
export interface CommandValidationResult {
|
||||
/** Whether the command is valid */
|
||||
valid: boolean;
|
||||
/** Validation errors */
|
||||
errors: string[];
|
||||
/** Validation warnings */
|
||||
warnings: string[];
|
||||
}
|
||||
|
||||
/**
|
||||
* Agent command format
|
||||
*/
|
||||
export interface AgentCommandFormat {
|
||||
/** Agent type */
|
||||
agent: AgentType;
|
||||
/** File extension */
|
||||
extension: string;
|
||||
/** Directory for commands */
|
||||
directory: string;
|
||||
/** Whether agent supports slash commands */
|
||||
supportsSlashCommands: boolean;
|
||||
/** Whether agent supports command files */
|
||||
supportsCommandFiles: boolean;
|
||||
/** Template for generating commands */
|
||||
template?: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* Command event types
|
||||
*/
|
||||
export type CommandEvent =
|
||||
| 'command:registered'
|
||||
| 'command:unregistered'
|
||||
| 'command:enabled'
|
||||
| 'command:disabled'
|
||||
| 'command:executed'
|
||||
| 'command:failed';
|
||||
|
||||
/**
|
||||
* Command event listener
|
||||
*/
|
||||
export type CommandEventListener = (
|
||||
event: CommandEvent,
|
||||
command: RegisteredCommand,
|
||||
result?: SlashCommandResult
|
||||
) => void;
|
||||
|
||||
/**
|
||||
* Command import/export format
|
||||
*/
|
||||
export interface CommandBundle {
|
||||
/** Bundle version */
|
||||
version: string;
|
||||
/** Commands in the bundle */
|
||||
commands: SlashCommand[];
|
||||
/** Bundle metadata */
|
||||
metadata?: {
|
||||
name?: string;
|
||||
description?: string;
|
||||
author?: string;
|
||||
createdAt?: Date;
|
||||
};
|
||||
}
|
||||
@@ -0,0 +1,610 @@
|
||||
/**
|
||||
* Hooks System Tests
|
||||
*/
|
||||
|
||||
import { describe, it, expect, beforeEach, afterEach } from 'vitest';
|
||||
import { mkdtempSync, rmSync, writeFileSync, mkdirSync } from 'node:fs';
|
||||
import { join } from 'node:path';
|
||||
import { tmpdir } from 'node:os';
|
||||
import { HookManager, createHookManager } from '../manager.js';
|
||||
import { SkillTriggerEngine, createTriggerEngine } from '../triggers.js';
|
||||
import type { SkillHook, HookEvent, HookContext } from '../types.js';
|
||||
|
||||
describe('HookManager', () => {
|
||||
let tempDir: string;
|
||||
let manager: HookManager;
|
||||
|
||||
beforeEach(() => {
|
||||
tempDir = mkdtempSync(join(tmpdir(), 'skillkit-hooks-test-'));
|
||||
manager = createHookManager({ projectPath: tempDir, autoLoad: false });
|
||||
});
|
||||
|
||||
afterEach(() => {
|
||||
rmSync(tempDir, { recursive: true, force: true });
|
||||
});
|
||||
|
||||
describe('registerHook', () => {
|
||||
it('should register a hook with generated ID', () => {
|
||||
const hook = manager.registerHook({
|
||||
event: 'session:start',
|
||||
skills: ['tdd-workflow'],
|
||||
inject: 'reference',
|
||||
enabled: true,
|
||||
});
|
||||
|
||||
expect(hook.id).toBeDefined();
|
||||
expect(hook.event).toBe('session:start');
|
||||
expect(hook.skills).toEqual(['tdd-workflow']);
|
||||
expect(hook.inject).toBe('reference');
|
||||
expect(hook.enabled).toBe(true);
|
||||
});
|
||||
|
||||
it('should register a hook with custom ID', () => {
|
||||
const hook = manager.registerHook({
|
||||
id: 'my-hook',
|
||||
event: 'file:save',
|
||||
skills: ['code-review'],
|
||||
inject: 'content',
|
||||
enabled: true,
|
||||
});
|
||||
|
||||
expect(hook.id).toBe('my-hook');
|
||||
});
|
||||
|
||||
it('should set default values', () => {
|
||||
const hook = manager.registerHook({
|
||||
event: 'session:start',
|
||||
skills: ['test'],
|
||||
inject: 'reference',
|
||||
enabled: true,
|
||||
});
|
||||
|
||||
expect(hook.priority).toBe(0);
|
||||
});
|
||||
});
|
||||
|
||||
describe('unregisterHook', () => {
|
||||
it('should remove a registered hook', () => {
|
||||
const hook = manager.registerHook({
|
||||
event: 'session:start',
|
||||
skills: ['test'],
|
||||
inject: 'reference',
|
||||
enabled: true,
|
||||
});
|
||||
|
||||
expect(manager.getHook(hook.id)).toBeDefined();
|
||||
expect(manager.unregisterHook(hook.id)).toBe(true);
|
||||
expect(manager.getHook(hook.id)).toBeUndefined();
|
||||
});
|
||||
|
||||
it('should return false for non-existent hook', () => {
|
||||
expect(manager.unregisterHook('non-existent')).toBe(false);
|
||||
});
|
||||
});
|
||||
|
||||
describe('getHooksForEvent', () => {
|
||||
it('should return hooks for a specific event', () => {
|
||||
manager.registerHook({
|
||||
event: 'session:start',
|
||||
skills: ['skill1'],
|
||||
inject: 'reference',
|
||||
enabled: true,
|
||||
});
|
||||
manager.registerHook({
|
||||
event: 'session:start',
|
||||
skills: ['skill2'],
|
||||
inject: 'reference',
|
||||
enabled: true,
|
||||
});
|
||||
manager.registerHook({
|
||||
event: 'file:save',
|
||||
skills: ['skill3'],
|
||||
inject: 'reference',
|
||||
enabled: true,
|
||||
});
|
||||
|
||||
const sessionHooks = manager.getHooksForEvent('session:start');
|
||||
expect(sessionHooks).toHaveLength(2);
|
||||
expect(sessionHooks.every((h) => h.event === 'session:start')).toBe(true);
|
||||
});
|
||||
|
||||
it('should only return enabled hooks', () => {
|
||||
manager.registerHook({
|
||||
event: 'session:start',
|
||||
skills: ['skill1'],
|
||||
inject: 'reference',
|
||||
enabled: true,
|
||||
});
|
||||
manager.registerHook({
|
||||
event: 'session:start',
|
||||
skills: ['skill2'],
|
||||
inject: 'reference',
|
||||
enabled: false,
|
||||
});
|
||||
|
||||
const hooks = manager.getHooksForEvent('session:start');
|
||||
expect(hooks).toHaveLength(1);
|
||||
});
|
||||
|
||||
it('should sort by priority (higher first)', () => {
|
||||
manager.registerHook({
|
||||
event: 'session:start',
|
||||
skills: ['low'],
|
||||
inject: 'reference',
|
||||
enabled: true,
|
||||
priority: 1,
|
||||
});
|
||||
manager.registerHook({
|
||||
event: 'session:start',
|
||||
skills: ['high'],
|
||||
inject: 'reference',
|
||||
enabled: true,
|
||||
priority: 10,
|
||||
});
|
||||
manager.registerHook({
|
||||
event: 'session:start',
|
||||
skills: ['medium'],
|
||||
inject: 'reference',
|
||||
enabled: true,
|
||||
priority: 5,
|
||||
});
|
||||
|
||||
const hooks = manager.getHooksForEvent('session:start');
|
||||
expect(hooks[0].skills).toEqual(['high']);
|
||||
expect(hooks[1].skills).toEqual(['medium']);
|
||||
expect(hooks[2].skills).toEqual(['low']);
|
||||
});
|
||||
});
|
||||
|
||||
describe('enableHook/disableHook', () => {
|
||||
it('should enable a disabled hook', () => {
|
||||
const hook = manager.registerHook({
|
||||
event: 'session:start',
|
||||
skills: ['test'],
|
||||
inject: 'reference',
|
||||
enabled: false,
|
||||
});
|
||||
|
||||
expect(manager.enableHook(hook.id)).toBe(true);
|
||||
expect(manager.getHook(hook.id)?.enabled).toBe(true);
|
||||
});
|
||||
|
||||
it('should disable an enabled hook', () => {
|
||||
const hook = manager.registerHook({
|
||||
event: 'session:start',
|
||||
skills: ['test'],
|
||||
inject: 'reference',
|
||||
enabled: true,
|
||||
});
|
||||
|
||||
expect(manager.disableHook(hook.id)).toBe(true);
|
||||
expect(manager.getHook(hook.id)?.enabled).toBe(false);
|
||||
});
|
||||
});
|
||||
|
||||
describe('trigger', () => {
|
||||
it('should trigger hooks for an event', async () => {
|
||||
manager.registerHook({
|
||||
event: 'session:start',
|
||||
skills: ['skill1', 'skill2'],
|
||||
inject: 'reference',
|
||||
enabled: true,
|
||||
});
|
||||
|
||||
const context: HookContext = {
|
||||
event: 'session:start',
|
||||
trigger: 'test',
|
||||
projectPath: tempDir,
|
||||
agent: 'claude-code',
|
||||
timestamp: new Date(),
|
||||
};
|
||||
|
||||
const result = await manager.trigger('session:start', context);
|
||||
|
||||
expect(result.event).toBe('session:start');
|
||||
expect(result.matchedHooks).toHaveLength(1);
|
||||
expect(result.activatedSkills).toHaveLength(2);
|
||||
expect(result.errors).toHaveLength(0);
|
||||
});
|
||||
|
||||
it('should filter by matcher pattern', async () => {
|
||||
manager.registerHook({
|
||||
event: 'file:save',
|
||||
skills: ['test-skill'],
|
||||
inject: 'reference',
|
||||
matcher: '*.test.ts',
|
||||
enabled: true,
|
||||
});
|
||||
|
||||
const matchContext: HookContext = {
|
||||
event: 'file:save',
|
||||
trigger: 'foo.test.ts',
|
||||
projectPath: tempDir,
|
||||
agent: 'claude-code',
|
||||
timestamp: new Date(),
|
||||
};
|
||||
|
||||
const noMatchContext: HookContext = {
|
||||
event: 'file:save',
|
||||
trigger: 'foo.ts',
|
||||
projectPath: tempDir,
|
||||
agent: 'claude-code',
|
||||
timestamp: new Date(),
|
||||
};
|
||||
|
||||
const matchResult = await manager.trigger('file:save', matchContext);
|
||||
expect(matchResult.matchedHooks).toHaveLength(1);
|
||||
|
||||
const noMatchResult = await manager.trigger('file:save', noMatchContext);
|
||||
expect(noMatchResult.matchedHooks).toHaveLength(0);
|
||||
});
|
||||
|
||||
it('should handle injection modes', async () => {
|
||||
manager.registerHook({
|
||||
event: 'session:start',
|
||||
skills: ['ref-skill'],
|
||||
inject: 'reference',
|
||||
enabled: true,
|
||||
});
|
||||
manager.registerHook({
|
||||
event: 'session:start',
|
||||
skills: ['content-skill'],
|
||||
inject: 'content',
|
||||
enabled: true,
|
||||
});
|
||||
manager.registerHook({
|
||||
event: 'session:start',
|
||||
skills: ['prompt-skill'],
|
||||
inject: 'prompt',
|
||||
enabled: true,
|
||||
});
|
||||
|
||||
const context: HookContext = {
|
||||
event: 'session:start',
|
||||
trigger: 'test',
|
||||
projectPath: tempDir,
|
||||
agent: 'claude-code',
|
||||
timestamp: new Date(),
|
||||
};
|
||||
|
||||
const result = await manager.trigger('session:start', context);
|
||||
|
||||
const refSkill = result.activatedSkills.find((s) => s.skillId === 'ref-skill');
|
||||
expect(refSkill?.reference).toBe('@ref-skill');
|
||||
|
||||
const contentSkill = result.activatedSkills.find((s) => s.skillId === 'content-skill');
|
||||
expect(contentSkill?.content).toBeDefined();
|
||||
|
||||
const promptSkill = result.activatedSkills.find((s) => s.skillId === 'prompt-skill');
|
||||
expect(promptSkill?.content).toContain('prompt-skill');
|
||||
});
|
||||
});
|
||||
|
||||
describe('save/load', () => {
|
||||
it('should save and load hooks', () => {
|
||||
manager.registerHook({
|
||||
event: 'session:start',
|
||||
skills: ['skill1'],
|
||||
inject: 'reference',
|
||||
enabled: true,
|
||||
});
|
||||
manager.registerHook({
|
||||
event: 'file:save',
|
||||
skills: ['skill2'],
|
||||
inject: 'content',
|
||||
enabled: false,
|
||||
matcher: '*.ts',
|
||||
});
|
||||
|
||||
manager.save();
|
||||
|
||||
// Create new manager to load
|
||||
const newManager = createHookManager({ projectPath: tempDir, autoLoad: true });
|
||||
const hooks = newManager.getAllHooks();
|
||||
|
||||
expect(hooks).toHaveLength(2);
|
||||
expect(hooks.find((h) => h.skills[0] === 'skill1')).toBeDefined();
|
||||
expect(hooks.find((h) => h.skills[0] === 'skill2')).toBeDefined();
|
||||
});
|
||||
});
|
||||
|
||||
describe('generateAgentHooks', () => {
|
||||
it('should generate Claude Code hooks format', () => {
|
||||
manager.registerHook({
|
||||
event: 'session:start',
|
||||
skills: ['tdd'],
|
||||
inject: 'reference',
|
||||
enabled: true,
|
||||
});
|
||||
|
||||
const hooks = manager.generateAgentHooks('claude-code');
|
||||
expect(hooks).toHaveProperty('hooks');
|
||||
expect((hooks as any).hooks).toBeInstanceOf(Array);
|
||||
});
|
||||
|
||||
it('should generate Cursor rules format', () => {
|
||||
manager.registerHook({
|
||||
event: 'session:start',
|
||||
skills: ['tdd'],
|
||||
inject: 'reference',
|
||||
enabled: true,
|
||||
});
|
||||
|
||||
const rules = manager.generateAgentHooks('cursor');
|
||||
expect(typeof rules).toBe('string');
|
||||
expect(rules).toContain('session start');
|
||||
});
|
||||
|
||||
it('should generate generic format for other agents', () => {
|
||||
manager.registerHook({
|
||||
event: 'session:start',
|
||||
skills: ['tdd'],
|
||||
inject: 'reference',
|
||||
enabled: true,
|
||||
});
|
||||
|
||||
const content = manager.generateAgentHooks('gemini-cli');
|
||||
expect(typeof content).toBe('string');
|
||||
expect(content).toContain('Skill Activation Triggers');
|
||||
});
|
||||
});
|
||||
|
||||
describe('listeners', () => {
|
||||
it('should notify listeners on trigger', async () => {
|
||||
let notified = false;
|
||||
manager.addListener((event, context, result) => {
|
||||
notified = true;
|
||||
expect(event).toBe('session:start');
|
||||
});
|
||||
|
||||
manager.registerHook({
|
||||
event: 'session:start',
|
||||
skills: ['test'],
|
||||
inject: 'reference',
|
||||
enabled: true,
|
||||
});
|
||||
|
||||
await manager.trigger('session:start', {
|
||||
event: 'session:start',
|
||||
trigger: 'test',
|
||||
projectPath: tempDir,
|
||||
agent: 'claude-code',
|
||||
timestamp: new Date(),
|
||||
});
|
||||
|
||||
expect(notified).toBe(true);
|
||||
});
|
||||
|
||||
it('should remove listeners', async () => {
|
||||
let callCount = 0;
|
||||
const listener = () => {
|
||||
callCount++;
|
||||
};
|
||||
|
||||
manager.addListener(listener);
|
||||
manager.registerHook({
|
||||
event: 'session:start',
|
||||
skills: ['test'],
|
||||
inject: 'reference',
|
||||
enabled: true,
|
||||
});
|
||||
|
||||
const context: HookContext = {
|
||||
event: 'session:start',
|
||||
trigger: 'test',
|
||||
projectPath: tempDir,
|
||||
agent: 'claude-code',
|
||||
timestamp: new Date(),
|
||||
};
|
||||
|
||||
await manager.trigger('session:start', context);
|
||||
expect(callCount).toBe(1);
|
||||
|
||||
manager.removeListener(listener);
|
||||
await manager.trigger('session:start', context);
|
||||
expect(callCount).toBe(1); // Should not increase
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
describe('SkillTriggerEngine', () => {
|
||||
let tempDir: string;
|
||||
let manager: HookManager;
|
||||
let engine: SkillTriggerEngine;
|
||||
|
||||
beforeEach(() => {
|
||||
tempDir = mkdtempSync(join(tmpdir(), 'skillkit-trigger-test-'));
|
||||
manager = createHookManager({ projectPath: tempDir, autoLoad: false });
|
||||
engine = createTriggerEngine(manager, { projectPath: tempDir, watchFiles: false });
|
||||
});
|
||||
|
||||
afterEach(() => {
|
||||
engine.stop();
|
||||
rmSync(tempDir, { recursive: true, force: true });
|
||||
});
|
||||
|
||||
describe('lifecycle', () => {
|
||||
it('should start and stop', async () => {
|
||||
let sessionStartTriggered = false;
|
||||
let sessionEndTriggered = false;
|
||||
|
||||
manager.registerHook({
|
||||
event: 'session:start',
|
||||
skills: ['start-skill'],
|
||||
inject: 'reference',
|
||||
enabled: true,
|
||||
});
|
||||
manager.registerHook({
|
||||
event: 'session:end',
|
||||
skills: ['end-skill'],
|
||||
inject: 'reference',
|
||||
enabled: true,
|
||||
});
|
||||
|
||||
manager.addListener((event) => {
|
||||
if (event === 'session:start') sessionStartTriggered = true;
|
||||
if (event === 'session:end') sessionEndTriggered = true;
|
||||
});
|
||||
|
||||
engine.start('claude-code');
|
||||
// Give it a moment to process
|
||||
await new Promise((r) => setTimeout(r, 10));
|
||||
expect(sessionStartTriggered).toBe(true);
|
||||
expect(engine.isActive()).toBe(true);
|
||||
|
||||
engine.stop();
|
||||
await new Promise((r) => setTimeout(r, 10));
|
||||
expect(sessionEndTriggered).toBe(true);
|
||||
expect(engine.isActive()).toBe(false);
|
||||
});
|
||||
});
|
||||
|
||||
describe('event triggering', () => {
|
||||
beforeEach(() => {
|
||||
manager.registerHook({
|
||||
event: 'file:save',
|
||||
skills: ['save-skill'],
|
||||
inject: 'reference',
|
||||
enabled: true,
|
||||
});
|
||||
manager.registerHook({
|
||||
event: 'task:start',
|
||||
skills: ['task-skill'],
|
||||
inject: 'reference',
|
||||
enabled: true,
|
||||
});
|
||||
manager.registerHook({
|
||||
event: 'commit:pre',
|
||||
skills: ['commit-skill'],
|
||||
inject: 'reference',
|
||||
enabled: true,
|
||||
});
|
||||
manager.registerHook({
|
||||
event: 'error:occur',
|
||||
skills: ['error-skill'],
|
||||
inject: 'reference',
|
||||
enabled: true,
|
||||
});
|
||||
manager.registerHook({
|
||||
event: 'test:fail',
|
||||
skills: ['test-skill'],
|
||||
inject: 'reference',
|
||||
enabled: true,
|
||||
});
|
||||
manager.registerHook({
|
||||
event: 'build:fail',
|
||||
skills: ['build-skill'],
|
||||
inject: 'reference',
|
||||
enabled: true,
|
||||
});
|
||||
});
|
||||
|
||||
it('should trigger file save event', async () => {
|
||||
const result = await engine.triggerFileSave('src/index.ts');
|
||||
expect(result.matchedHooks).toHaveLength(1);
|
||||
expect(result.activatedSkills[0].skillId).toBe('save-skill');
|
||||
});
|
||||
|
||||
it('should trigger task start event', async () => {
|
||||
const result = await engine.triggerTaskStart('implement-feature', 'task-123');
|
||||
expect(result.matchedHooks).toHaveLength(1);
|
||||
expect(result.activatedSkills[0].skillId).toBe('task-skill');
|
||||
});
|
||||
|
||||
it('should trigger pre-commit event', async () => {
|
||||
const result = await engine.triggerPreCommit('feat: add new feature');
|
||||
expect(result.matchedHooks).toHaveLength(1);
|
||||
expect(result.activatedSkills[0].skillId).toBe('commit-skill');
|
||||
});
|
||||
|
||||
it('should trigger error event', async () => {
|
||||
const result = await engine.triggerError(new Error('Something went wrong'), 'test-context');
|
||||
expect(result.matchedHooks).toHaveLength(1);
|
||||
expect(result.activatedSkills[0].skillId).toBe('error-skill');
|
||||
});
|
||||
|
||||
it('should trigger test fail event', async () => {
|
||||
const result = await engine.triggerTestFail('should add numbers', 'Expected 4 but got 5');
|
||||
expect(result.matchedHooks).toHaveLength(1);
|
||||
expect(result.activatedSkills[0].skillId).toBe('test-skill');
|
||||
});
|
||||
|
||||
it('should trigger build fail event', async () => {
|
||||
const result = await engine.triggerBuildFail('TypeScript error');
|
||||
expect(result.matchedHooks).toHaveLength(1);
|
||||
expect(result.activatedSkills[0].skillId).toBe('build-skill');
|
||||
});
|
||||
});
|
||||
|
||||
describe('agent setting', () => {
|
||||
it('should use the set agent in context', async () => {
|
||||
manager.registerHook({
|
||||
event: 'session:start',
|
||||
skills: ['test'],
|
||||
inject: 'reference',
|
||||
enabled: true,
|
||||
});
|
||||
|
||||
let capturedAgent: string | null = null;
|
||||
manager.addListener((event, context) => {
|
||||
capturedAgent = context.agent;
|
||||
});
|
||||
|
||||
engine.setAgent('cursor');
|
||||
await engine.triggerEvent('session:start', 'test');
|
||||
|
||||
expect(capturedAgent).toBe('cursor');
|
||||
});
|
||||
});
|
||||
|
||||
describe('listeners', () => {
|
||||
it('should notify engine listeners', async () => {
|
||||
let notified = false;
|
||||
engine.addListener((event) => {
|
||||
notified = true;
|
||||
expect(event).toBe('task:start');
|
||||
});
|
||||
|
||||
manager.registerHook({
|
||||
event: 'task:start',
|
||||
skills: ['test'],
|
||||
inject: 'reference',
|
||||
enabled: true,
|
||||
});
|
||||
|
||||
await engine.triggerTaskStart('test-task');
|
||||
expect(notified).toBe(true);
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
describe('Hook Event Types', () => {
|
||||
it('should support all documented events', () => {
|
||||
const events: HookEvent[] = [
|
||||
'session:start',
|
||||
'session:resume',
|
||||
'session:end',
|
||||
'file:open',
|
||||
'file:save',
|
||||
'file:create',
|
||||
'file:delete',
|
||||
'task:start',
|
||||
'task:complete',
|
||||
'commit:pre',
|
||||
'commit:post',
|
||||
'error:occur',
|
||||
'test:fail',
|
||||
'test:pass',
|
||||
'build:start',
|
||||
'build:fail',
|
||||
'build:success',
|
||||
];
|
||||
|
||||
// Just verify all events are valid strings
|
||||
expect(events).toHaveLength(17);
|
||||
events.forEach((event) => {
|
||||
expect(typeof event).toBe('string');
|
||||
expect(event).toContain(':');
|
||||
});
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,35 @@
|
||||
/**
|
||||
* Hooks & Automatic Triggering System
|
||||
*
|
||||
* Provides event-driven skill activation across all supported agents.
|
||||
*
|
||||
* Key features:
|
||||
* - 17+ hook events (session, file, task, commit, error, test, build)
|
||||
* - Pattern matching with glob support
|
||||
* - Agent-specific hook generation
|
||||
* - File watching for automatic triggers
|
||||
* - Condition expressions for complex logic
|
||||
*/
|
||||
|
||||
// Manager
|
||||
export { HookManager, createHookManager } from './manager.js';
|
||||
|
||||
// Trigger Engine
|
||||
export { SkillTriggerEngine, createTriggerEngine } from './triggers.js';
|
||||
|
||||
// Types
|
||||
export type {
|
||||
HookEvent,
|
||||
InjectionMode,
|
||||
SkillHook,
|
||||
HookContext,
|
||||
ActivatedSkill,
|
||||
HookTriggerResult,
|
||||
HookError,
|
||||
HookConfig,
|
||||
AgentHookFormat,
|
||||
HookManagerOptions,
|
||||
TriggerEngineOptions,
|
||||
HookEventListener,
|
||||
MatcherFunction,
|
||||
} from './types.js';
|
||||
@@ -0,0 +1,539 @@
|
||||
/**
|
||||
* Hook Manager
|
||||
*
|
||||
* Manages skill hooks for automatic triggering across all supported agents.
|
||||
*/
|
||||
|
||||
import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
|
||||
import { join, dirname } from 'node:path';
|
||||
import { randomUUID } from 'node:crypto';
|
||||
import { minimatch } from 'minimatch';
|
||||
import type { AgentType } from '../types.js';
|
||||
import type {
|
||||
SkillHook,
|
||||
HookEvent,
|
||||
HookContext,
|
||||
HookConfig,
|
||||
HookManagerOptions,
|
||||
ActivatedSkill,
|
||||
HookTriggerResult,
|
||||
HookError,
|
||||
HookEventListener,
|
||||
} from './types.js';
|
||||
|
||||
const DEFAULT_CONFIG_PATH = '.skillkit/hooks.json';
|
||||
|
||||
/**
|
||||
* HookManager - Manages skill hooks for automatic triggering
|
||||
*/
|
||||
export class HookManager {
|
||||
private hooks: Map<string, SkillHook> = new Map();
|
||||
private listeners: Set<HookEventListener> = new Set();
|
||||
private options: Required<HookManagerOptions>;
|
||||
|
||||
constructor(options: HookManagerOptions) {
|
||||
this.options = {
|
||||
projectPath: options.projectPath,
|
||||
configPath: options.configPath || join(options.projectPath, DEFAULT_CONFIG_PATH),
|
||||
autoLoad: options.autoLoad ?? true,
|
||||
defaultInjectionMode: options.defaultInjectionMode || 'reference',
|
||||
};
|
||||
|
||||
if (this.options.autoLoad) {
|
||||
this.load();
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Register a new hook
|
||||
*/
|
||||
registerHook(hook: Omit<SkillHook, 'id'> & { id?: string }): SkillHook {
|
||||
const fullHook: SkillHook = {
|
||||
...hook,
|
||||
id: hook.id || randomUUID(),
|
||||
inject: hook.inject || this.options.defaultInjectionMode,
|
||||
enabled: hook.enabled ?? true,
|
||||
priority: hook.priority ?? 0,
|
||||
};
|
||||
|
||||
this.hooks.set(fullHook.id, fullHook);
|
||||
return fullHook;
|
||||
}
|
||||
|
||||
/**
|
||||
* Unregister a hook by ID
|
||||
*/
|
||||
unregisterHook(id: string): boolean {
|
||||
return this.hooks.delete(id);
|
||||
}
|
||||
|
||||
/**
|
||||
* Get a hook by ID
|
||||
*/
|
||||
getHook(id: string): SkillHook | undefined {
|
||||
return this.hooks.get(id);
|
||||
}
|
||||
|
||||
/**
|
||||
* Get all hooks
|
||||
*/
|
||||
getAllHooks(): SkillHook[] {
|
||||
return Array.from(this.hooks.values());
|
||||
}
|
||||
|
||||
/**
|
||||
* Get hooks for a specific event
|
||||
*/
|
||||
getHooksForEvent(event: HookEvent): SkillHook[] {
|
||||
return this.getAllHooks()
|
||||
.filter((hook) => hook.event === event && hook.enabled)
|
||||
.sort((a, b) => (b.priority || 0) - (a.priority || 0));
|
||||
}
|
||||
|
||||
/**
|
||||
* Update a hook
|
||||
*/
|
||||
updateHook(id: string, updates: Partial<SkillHook>): SkillHook | undefined {
|
||||
const existing = this.hooks.get(id);
|
||||
if (!existing) return undefined;
|
||||
|
||||
const updated = { ...existing, ...updates, id };
|
||||
this.hooks.set(id, updated);
|
||||
return updated;
|
||||
}
|
||||
|
||||
/**
|
||||
* Enable a hook
|
||||
*/
|
||||
enableHook(id: string): boolean {
|
||||
const hook = this.hooks.get(id);
|
||||
if (!hook) return false;
|
||||
hook.enabled = true;
|
||||
return true;
|
||||
}
|
||||
|
||||
/**
|
||||
* Disable a hook
|
||||
*/
|
||||
disableHook(id: string): boolean {
|
||||
const hook = this.hooks.get(id);
|
||||
if (!hook) return false;
|
||||
hook.enabled = false;
|
||||
return true;
|
||||
}
|
||||
|
||||
/**
|
||||
* Trigger hooks for an event
|
||||
*/
|
||||
async trigger(event: HookEvent, context: HookContext): Promise<HookTriggerResult> {
|
||||
const startTime = Date.now();
|
||||
const matchedHooks: SkillHook[] = [];
|
||||
const activatedSkills: ActivatedSkill[] = [];
|
||||
const errors: HookError[] = [];
|
||||
|
||||
const hooks = this.getHooksForEvent(event);
|
||||
|
||||
for (const hook of hooks) {
|
||||
try {
|
||||
// Check if matcher matches
|
||||
if (hook.matcher && !this.matchesTrigger(hook.matcher, context.trigger)) {
|
||||
continue;
|
||||
}
|
||||
|
||||
// Check condition if present
|
||||
if (hook.condition && !this.evaluateCondition(hook.condition, context)) {
|
||||
continue;
|
||||
}
|
||||
|
||||
matchedHooks.push(hook);
|
||||
|
||||
// Apply agent-specific overrides
|
||||
const effectiveHook = this.applyAgentOverrides(hook, context.agent);
|
||||
|
||||
// Activate each skill
|
||||
for (const skillId of effectiveHook.skills) {
|
||||
try {
|
||||
const activated = await this.activateSkill(skillId, effectiveHook, context);
|
||||
activatedSkills.push(activated);
|
||||
} catch (err) {
|
||||
errors.push({
|
||||
hookId: hook.id,
|
||||
skillId,
|
||||
message: err instanceof Error ? err.message : 'Unknown error',
|
||||
stack: err instanceof Error ? err.stack : undefined,
|
||||
});
|
||||
}
|
||||
}
|
||||
} catch (err) {
|
||||
errors.push({
|
||||
hookId: hook.id,
|
||||
message: err instanceof Error ? err.message : 'Unknown error',
|
||||
stack: err instanceof Error ? err.stack : undefined,
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
const result: HookTriggerResult = {
|
||||
event,
|
||||
matchedHooks,
|
||||
activatedSkills,
|
||||
errors,
|
||||
executionTimeMs: Date.now() - startTime,
|
||||
};
|
||||
|
||||
// Notify listeners
|
||||
await this.notifyListeners(event, context, result);
|
||||
|
||||
return result;
|
||||
}
|
||||
|
||||
/**
|
||||
* Add event listener
|
||||
*/
|
||||
addListener(listener: HookEventListener): void {
|
||||
this.listeners.add(listener);
|
||||
}
|
||||
|
||||
/**
|
||||
* Remove event listener
|
||||
*/
|
||||
removeListener(listener: HookEventListener): void {
|
||||
this.listeners.delete(listener);
|
||||
}
|
||||
|
||||
/**
|
||||
* Load hooks from config file
|
||||
*/
|
||||
load(): void {
|
||||
if (!existsSync(this.options.configPath)) {
|
||||
return;
|
||||
}
|
||||
|
||||
try {
|
||||
const content = readFileSync(this.options.configPath, 'utf-8');
|
||||
const config: HookConfig = JSON.parse(content);
|
||||
|
||||
this.hooks.clear();
|
||||
for (const hook of config.hooks) {
|
||||
this.hooks.set(hook.id, {
|
||||
...hook,
|
||||
inject: hook.inject || config.defaults?.inject || this.options.defaultInjectionMode,
|
||||
priority: hook.priority ?? config.defaults?.priority ?? 0,
|
||||
enabled: hook.enabled ?? config.defaults?.enabled ?? true,
|
||||
});
|
||||
}
|
||||
} catch {
|
||||
// Ignore parse errors, start with empty hooks
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Save hooks to config file
|
||||
*/
|
||||
save(): void {
|
||||
const config: HookConfig = {
|
||||
version: 1,
|
||||
hooks: this.getAllHooks(),
|
||||
defaults: {
|
||||
inject: this.options.defaultInjectionMode,
|
||||
priority: 0,
|
||||
enabled: true,
|
||||
},
|
||||
};
|
||||
|
||||
const dir = dirname(this.options.configPath);
|
||||
if (!existsSync(dir)) {
|
||||
mkdirSync(dir, { recursive: true });
|
||||
}
|
||||
|
||||
writeFileSync(this.options.configPath, JSON.stringify(config, null, 2));
|
||||
}
|
||||
|
||||
/**
|
||||
* Generate agent-specific hook configuration
|
||||
*/
|
||||
generateAgentHooks(agent: AgentType): string | Record<string, unknown> {
|
||||
const hooks = this.getAllHooks().filter((h) => h.enabled);
|
||||
|
||||
switch (agent) {
|
||||
case 'claude-code':
|
||||
return this.generateClaudeCodeHooks(hooks);
|
||||
case 'cursor':
|
||||
return this.generateCursorHooks(hooks);
|
||||
case 'opencode':
|
||||
return this.generateOpenCodeHooks(hooks);
|
||||
default:
|
||||
return this.generateGenericHooks(hooks);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Generate Claude Code hooks.json format
|
||||
*/
|
||||
private generateClaudeCodeHooks(hooks: SkillHook[]): Record<string, unknown> {
|
||||
const hookEntries: Record<string, unknown>[] = [];
|
||||
|
||||
for (const hook of hooks) {
|
||||
// Map our events to Claude Code hook events
|
||||
const claudeEvent = this.mapToClaudeCodeEvent(hook.event);
|
||||
if (!claudeEvent) continue;
|
||||
|
||||
hookEntries.push({
|
||||
event: claudeEvent,
|
||||
command: this.generateClaudeCommand(hook),
|
||||
matcher: hook.matcher ? String(hook.matcher) : undefined,
|
||||
});
|
||||
}
|
||||
|
||||
return { hooks: hookEntries };
|
||||
}
|
||||
|
||||
/**
|
||||
* Map SkillKit events to Claude Code events
|
||||
*/
|
||||
private mapToClaudeCodeEvent(event: HookEvent): string | null {
|
||||
const mapping: Record<HookEvent, string | null> = {
|
||||
'session:start': 'SessionStart',
|
||||
'session:resume': 'SessionResume',
|
||||
'session:end': 'SessionEnd',
|
||||
'file:open': null,
|
||||
'file:save': 'PreToolUse',
|
||||
'file:create': 'PostToolUse',
|
||||
'file:delete': 'PostToolUse',
|
||||
'task:start': null,
|
||||
'task:complete': null,
|
||||
'commit:pre': 'PreToolUse',
|
||||
'commit:post': 'PostToolUse',
|
||||
'error:occur': null,
|
||||
'test:fail': 'PostToolUse',
|
||||
'test:pass': 'PostToolUse',
|
||||
'build:start': 'PreToolUse',
|
||||
'build:fail': 'PostToolUse',
|
||||
'build:success': 'PostToolUse',
|
||||
};
|
||||
return mapping[event];
|
||||
}
|
||||
|
||||
/**
|
||||
* Generate Claude Code command for a hook
|
||||
*/
|
||||
private generateClaudeCommand(hook: SkillHook): string {
|
||||
const skillRefs = hook.skills.map((s) => `@${s}`).join(' ');
|
||||
return `echo "Activating skills: ${skillRefs}"`;
|
||||
}
|
||||
|
||||
/**
|
||||
* Generate Cursor rules with hooks
|
||||
*/
|
||||
private generateCursorHooks(hooks: SkillHook[]): string {
|
||||
const lines: string[] = ['# Auto-generated skill activation rules', ''];
|
||||
|
||||
for (const hook of hooks) {
|
||||
lines.push(`## ${hook.event} Hook`);
|
||||
lines.push(`When ${hook.event.replace(':', ' ')} occurs:`);
|
||||
for (const skill of hook.skills) {
|
||||
lines.push(`- Apply skill: ${skill}`);
|
||||
}
|
||||
if (hook.matcher) {
|
||||
lines.push(`- Pattern: ${hook.matcher}`);
|
||||
}
|
||||
lines.push('');
|
||||
}
|
||||
|
||||
return lines.join('\n');
|
||||
}
|
||||
|
||||
/**
|
||||
* Generate OpenCode hooks
|
||||
*/
|
||||
private generateOpenCodeHooks(hooks: SkillHook[]): Record<string, unknown> {
|
||||
return {
|
||||
triggers: hooks.map((hook) => ({
|
||||
event: hook.event,
|
||||
skills: hook.skills,
|
||||
matcher: hook.matcher ? String(hook.matcher) : undefined,
|
||||
enabled: hook.enabled,
|
||||
})),
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Generate generic AGENTS.md injection for unsupported agents
|
||||
*/
|
||||
private generateGenericHooks(hooks: SkillHook[]): string {
|
||||
const lines: string[] = [
|
||||
'# Skill Activation Triggers',
|
||||
'',
|
||||
'The following skills should be activated based on events:',
|
||||
'',
|
||||
];
|
||||
|
||||
const eventGroups = new Map<HookEvent, SkillHook[]>();
|
||||
for (const hook of hooks) {
|
||||
const group = eventGroups.get(hook.event) || [];
|
||||
group.push(hook);
|
||||
eventGroups.set(hook.event, group);
|
||||
}
|
||||
|
||||
for (const [event, eventHooks] of eventGroups) {
|
||||
lines.push(`## On ${event.replace(':', ' ').replace(/\b\w/g, (c) => c.toUpperCase())}`);
|
||||
for (const hook of eventHooks) {
|
||||
lines.push(`- Activate: ${hook.skills.join(', ')}`);
|
||||
if (hook.matcher) {
|
||||
lines.push(` - When matching: ${hook.matcher}`);
|
||||
}
|
||||
}
|
||||
lines.push('');
|
||||
}
|
||||
|
||||
return lines.join('\n');
|
||||
}
|
||||
|
||||
/**
|
||||
* Check if trigger matches the pattern
|
||||
*/
|
||||
private matchesTrigger(matcher: string | RegExp, trigger: string): boolean {
|
||||
if (matcher instanceof RegExp) {
|
||||
return matcher.test(trigger);
|
||||
}
|
||||
// Use minimatch for glob patterns
|
||||
return minimatch(trigger, matcher);
|
||||
}
|
||||
|
||||
/**
|
||||
* Evaluate condition expression
|
||||
*/
|
||||
private evaluateCondition(condition: string, context: HookContext): boolean {
|
||||
// Simple condition evaluation
|
||||
// Supports: event == 'x', trigger.includes('y'), metadata.key == 'value'
|
||||
try {
|
||||
const safeContext = {
|
||||
event: context.event,
|
||||
trigger: context.trigger,
|
||||
agent: context.agent,
|
||||
metadata: context.metadata || {},
|
||||
};
|
||||
|
||||
// Very basic expression evaluation
|
||||
if (condition.includes('==')) {
|
||||
const [left, right] = condition.split('==').map((s) => s.trim());
|
||||
const leftVal = this.resolveValue(left, safeContext);
|
||||
const rightVal = right.replace(/['"]/g, '');
|
||||
return leftVal === rightVal;
|
||||
}
|
||||
|
||||
if (condition.includes('.includes(')) {
|
||||
const match = condition.match(/(\w+)\.includes\(['"](.+)['"]\)/);
|
||||
if (match) {
|
||||
const [, prop, search] = match;
|
||||
const val = this.resolveValue(prop, safeContext);
|
||||
return typeof val === 'string' && val.includes(search);
|
||||
}
|
||||
}
|
||||
|
||||
return true;
|
||||
} catch {
|
||||
return true;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Resolve a value from context
|
||||
*/
|
||||
private resolveValue(path: string, context: Record<string, unknown>): unknown {
|
||||
const parts = path.split('.');
|
||||
let current: unknown = context;
|
||||
|
||||
for (const part of parts) {
|
||||
if (current && typeof current === 'object' && part in current) {
|
||||
current = (current as Record<string, unknown>)[part];
|
||||
} else {
|
||||
return undefined;
|
||||
}
|
||||
}
|
||||
|
||||
return current;
|
||||
}
|
||||
|
||||
/**
|
||||
* Apply agent-specific overrides to a hook
|
||||
*/
|
||||
private applyAgentOverrides(hook: SkillHook, agent: AgentType): SkillHook {
|
||||
if (!hook.agentOverrides || !hook.agentOverrides[agent]) {
|
||||
return hook;
|
||||
}
|
||||
|
||||
return {
|
||||
...hook,
|
||||
...hook.agentOverrides[agent],
|
||||
id: hook.id,
|
||||
event: hook.event,
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Activate a skill from a hook
|
||||
*/
|
||||
private async activateSkill(
|
||||
skillId: string,
|
||||
hook: SkillHook,
|
||||
context: HookContext
|
||||
): Promise<ActivatedSkill> {
|
||||
const activated: ActivatedSkill = {
|
||||
skillId,
|
||||
hookId: hook.id,
|
||||
injectionMode: hook.inject,
|
||||
activatedAt: new Date(),
|
||||
};
|
||||
|
||||
switch (hook.inject) {
|
||||
case 'content':
|
||||
// Load skill content
|
||||
activated.content = await this.loadSkillContent(skillId, context);
|
||||
break;
|
||||
case 'reference':
|
||||
// Create reference
|
||||
activated.reference = `@${skillId}`;
|
||||
break;
|
||||
case 'prompt':
|
||||
// Create prompt injection
|
||||
activated.content = `Please apply the "${skillId}" skill to this task.`;
|
||||
break;
|
||||
}
|
||||
|
||||
return activated;
|
||||
}
|
||||
|
||||
/**
|
||||
* Load skill content (placeholder - integrates with skill loader)
|
||||
*/
|
||||
private async loadSkillContent(skillId: string, _context: HookContext): Promise<string> {
|
||||
// This would integrate with the methodology loader or skill manager
|
||||
// For now, return a placeholder
|
||||
return `# Skill: ${skillId}\n\nThis skill was auto-activated by a hook.`;
|
||||
}
|
||||
|
||||
/**
|
||||
* Notify all listeners of a trigger event
|
||||
*/
|
||||
private async notifyListeners(
|
||||
event: HookEvent,
|
||||
context: HookContext,
|
||||
result: HookTriggerResult
|
||||
): Promise<void> {
|
||||
for (const listener of this.listeners) {
|
||||
try {
|
||||
await listener(event, context, result);
|
||||
} catch {
|
||||
// Ignore listener errors
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Create a HookManager instance
|
||||
*/
|
||||
export function createHookManager(options: HookManagerOptions): HookManager {
|
||||
return new HookManager(options);
|
||||
}
|
||||
@@ -0,0 +1,314 @@
|
||||
/**
|
||||
* Skill Trigger Engine
|
||||
*
|
||||
* Monitors events and triggers skill activation based on configured hooks.
|
||||
*/
|
||||
|
||||
import { watch, type FSWatcher } from 'node:fs';
|
||||
import { join, relative } from 'node:path';
|
||||
import type { AgentType } from '../types.js';
|
||||
import type {
|
||||
HookEvent,
|
||||
HookContext,
|
||||
HookTriggerResult,
|
||||
TriggerEngineOptions,
|
||||
HookEventListener,
|
||||
} from './types.js';
|
||||
import { HookManager } from './manager.js';
|
||||
|
||||
/**
|
||||
* Debounce helper
|
||||
*/
|
||||
function debounce<T extends (...args: string[]) => void>(
|
||||
fn: T,
|
||||
delay: number
|
||||
): (...args: Parameters<T>) => void {
|
||||
let timeoutId: ReturnType<typeof setTimeout> | null = null;
|
||||
return (...args: Parameters<T>) => {
|
||||
if (timeoutId) clearTimeout(timeoutId);
|
||||
timeoutId = setTimeout(() => fn(...args), delay);
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* SkillTriggerEngine - Monitors events and triggers skill activation
|
||||
*/
|
||||
export class SkillTriggerEngine {
|
||||
private hookManager: HookManager;
|
||||
private options: Required<TriggerEngineOptions>;
|
||||
private watchers: Map<string, FSWatcher> = new Map();
|
||||
private listeners: Set<HookEventListener> = new Set();
|
||||
private isRunning = false;
|
||||
private currentAgent: AgentType = 'universal';
|
||||
|
||||
constructor(hookManager: HookManager, options: TriggerEngineOptions) {
|
||||
this.hookManager = hookManager;
|
||||
this.options = {
|
||||
projectPath: options.projectPath,
|
||||
watchFiles: options.watchFiles ?? false,
|
||||
debounceMs: options.debounceMs ?? 100,
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Start the trigger engine
|
||||
*/
|
||||
start(agent?: AgentType): void {
|
||||
if (this.isRunning) return;
|
||||
|
||||
this.isRunning = true;
|
||||
this.currentAgent = agent || 'universal';
|
||||
|
||||
if (this.options.watchFiles) {
|
||||
this.startFileWatcher();
|
||||
}
|
||||
|
||||
// Trigger session:start
|
||||
this.triggerEvent('session:start', 'engine_start');
|
||||
}
|
||||
|
||||
/**
|
||||
* Stop the trigger engine
|
||||
*/
|
||||
stop(): void {
|
||||
if (!this.isRunning) return;
|
||||
|
||||
// Trigger session:end
|
||||
this.triggerEvent('session:end', 'engine_stop');
|
||||
|
||||
this.stopFileWatcher();
|
||||
this.isRunning = false;
|
||||
}
|
||||
|
||||
/**
|
||||
* Set the current agent
|
||||
*/
|
||||
setAgent(agent: AgentType): void {
|
||||
this.currentAgent = agent;
|
||||
}
|
||||
|
||||
/**
|
||||
* Manually trigger an event
|
||||
*/
|
||||
async triggerEvent(
|
||||
event: HookEvent,
|
||||
trigger: string,
|
||||
metadata?: Record<string, unknown>
|
||||
): Promise<HookTriggerResult> {
|
||||
const context: HookContext = {
|
||||
event,
|
||||
trigger,
|
||||
projectPath: this.options.projectPath,
|
||||
agent: this.currentAgent,
|
||||
metadata,
|
||||
timestamp: new Date(),
|
||||
};
|
||||
|
||||
const result = await this.hookManager.trigger(event, context);
|
||||
|
||||
// Notify local listeners
|
||||
for (const listener of this.listeners) {
|
||||
try {
|
||||
await listener(event, context, result);
|
||||
} catch {
|
||||
// Ignore listener errors
|
||||
}
|
||||
}
|
||||
|
||||
return result;
|
||||
}
|
||||
|
||||
/**
|
||||
* Trigger file:open event
|
||||
*/
|
||||
async triggerFileOpen(filePath: string): Promise<HookTriggerResult> {
|
||||
return this.triggerEvent('file:open', filePath, { filePath });
|
||||
}
|
||||
|
||||
/**
|
||||
* Trigger file:save event
|
||||
*/
|
||||
async triggerFileSave(filePath: string): Promise<HookTriggerResult> {
|
||||
return this.triggerEvent('file:save', filePath, { filePath });
|
||||
}
|
||||
|
||||
/**
|
||||
* Trigger file:create event
|
||||
*/
|
||||
async triggerFileCreate(filePath: string): Promise<HookTriggerResult> {
|
||||
return this.triggerEvent('file:create', filePath, { filePath });
|
||||
}
|
||||
|
||||
/**
|
||||
* Trigger file:delete event
|
||||
*/
|
||||
async triggerFileDelete(filePath: string): Promise<HookTriggerResult> {
|
||||
return this.triggerEvent('file:delete', filePath, { filePath });
|
||||
}
|
||||
|
||||
/**
|
||||
* Trigger task:start event
|
||||
*/
|
||||
async triggerTaskStart(taskName: string, taskId?: string): Promise<HookTriggerResult> {
|
||||
return this.triggerEvent('task:start', taskName, { taskName, taskId });
|
||||
}
|
||||
|
||||
/**
|
||||
* Trigger task:complete event
|
||||
*/
|
||||
async triggerTaskComplete(
|
||||
taskName: string,
|
||||
taskId?: string,
|
||||
success?: boolean
|
||||
): Promise<HookTriggerResult> {
|
||||
return this.triggerEvent('task:complete', taskName, { taskName, taskId, success });
|
||||
}
|
||||
|
||||
/**
|
||||
* Trigger commit:pre event
|
||||
*/
|
||||
async triggerPreCommit(message?: string): Promise<HookTriggerResult> {
|
||||
return this.triggerEvent('commit:pre', 'git_commit', { message });
|
||||
}
|
||||
|
||||
/**
|
||||
* Trigger commit:post event
|
||||
*/
|
||||
async triggerPostCommit(commitHash?: string, message?: string): Promise<HookTriggerResult> {
|
||||
return this.triggerEvent('commit:post', 'git_commit', { commitHash, message });
|
||||
}
|
||||
|
||||
/**
|
||||
* Trigger error:occur event
|
||||
*/
|
||||
async triggerError(error: Error | string, context?: string): Promise<HookTriggerResult> {
|
||||
const errorMessage = error instanceof Error ? error.message : error;
|
||||
const errorStack = error instanceof Error ? error.stack : undefined;
|
||||
return this.triggerEvent('error:occur', errorMessage, { error: errorMessage, stack: errorStack, context });
|
||||
}
|
||||
|
||||
/**
|
||||
* Trigger test:fail event
|
||||
*/
|
||||
async triggerTestFail(testName: string, error?: string): Promise<HookTriggerResult> {
|
||||
return this.triggerEvent('test:fail', testName, { testName, error });
|
||||
}
|
||||
|
||||
/**
|
||||
* Trigger test:pass event
|
||||
*/
|
||||
async triggerTestPass(testName: string): Promise<HookTriggerResult> {
|
||||
return this.triggerEvent('test:pass', testName, { testName });
|
||||
}
|
||||
|
||||
/**
|
||||
* Trigger build:start event
|
||||
*/
|
||||
async triggerBuildStart(command?: string): Promise<HookTriggerResult> {
|
||||
return this.triggerEvent('build:start', 'build', { command });
|
||||
}
|
||||
|
||||
/**
|
||||
* Trigger build:fail event
|
||||
*/
|
||||
async triggerBuildFail(error?: string): Promise<HookTriggerResult> {
|
||||
return this.triggerEvent('build:fail', 'build', { error });
|
||||
}
|
||||
|
||||
/**
|
||||
* Trigger build:success event
|
||||
*/
|
||||
async triggerBuildSuccess(): Promise<HookTriggerResult> {
|
||||
return this.triggerEvent('build:success', 'build', {});
|
||||
}
|
||||
|
||||
/**
|
||||
* Add event listener
|
||||
*/
|
||||
addListener(listener: HookEventListener): void {
|
||||
this.listeners.add(listener);
|
||||
}
|
||||
|
||||
/**
|
||||
* Remove event listener
|
||||
*/
|
||||
removeListener(listener: HookEventListener): void {
|
||||
this.listeners.delete(listener);
|
||||
}
|
||||
|
||||
/**
|
||||
* Check if engine is running
|
||||
*/
|
||||
isActive(): boolean {
|
||||
return this.isRunning;
|
||||
}
|
||||
|
||||
/**
|
||||
* Start file watcher
|
||||
*/
|
||||
private startFileWatcher(): void {
|
||||
try {
|
||||
const watcher = watch(
|
||||
this.options.projectPath,
|
||||
{ recursive: true },
|
||||
debounce((eventType: string, filename: string | null) => {
|
||||
if (!filename) return;
|
||||
|
||||
const relativePath = relative(this.options.projectPath, join(this.options.projectPath, filename));
|
||||
|
||||
// Skip node_modules, .git, etc.
|
||||
if (this.shouldIgnore(relativePath)) return;
|
||||
|
||||
if (eventType === 'rename') {
|
||||
// Could be create or delete
|
||||
this.triggerFileCreate(relativePath);
|
||||
} else if (eventType === 'change') {
|
||||
this.triggerFileSave(relativePath);
|
||||
}
|
||||
}, this.options.debounceMs)
|
||||
);
|
||||
|
||||
this.watchers.set('main', watcher);
|
||||
} catch {
|
||||
// File watching not available
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Stop file watcher
|
||||
*/
|
||||
private stopFileWatcher(): void {
|
||||
for (const watcher of this.watchers.values()) {
|
||||
watcher.close();
|
||||
}
|
||||
this.watchers.clear();
|
||||
}
|
||||
|
||||
/**
|
||||
* Check if a path should be ignored
|
||||
*/
|
||||
private shouldIgnore(filePath: string): boolean {
|
||||
const ignorePaths = [
|
||||
'node_modules',
|
||||
'.git',
|
||||
'.skillkit',
|
||||
'dist',
|
||||
'build',
|
||||
'coverage',
|
||||
'.next',
|
||||
'.nuxt',
|
||||
];
|
||||
|
||||
return ignorePaths.some((ignore) => filePath.includes(ignore));
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Create a SkillTriggerEngine instance
|
||||
*/
|
||||
export function createTriggerEngine(
|
||||
hookManager: HookManager,
|
||||
options: TriggerEngineOptions
|
||||
): SkillTriggerEngine {
|
||||
return new SkillTriggerEngine(hookManager, options);
|
||||
}
|
||||
@@ -0,0 +1,189 @@
|
||||
/**
|
||||
* Hooks & Automatic Triggering System Types
|
||||
*
|
||||
* Provides event-driven skill activation across all supported agents.
|
||||
*/
|
||||
|
||||
import type { AgentType } from '../types.js';
|
||||
|
||||
/**
|
||||
* Hook events that can trigger skill activation
|
||||
*/
|
||||
export type HookEvent =
|
||||
| 'session:start'
|
||||
| 'session:resume'
|
||||
| 'session:end'
|
||||
| 'file:open'
|
||||
| 'file:save'
|
||||
| 'file:create'
|
||||
| 'file:delete'
|
||||
| 'task:start'
|
||||
| 'task:complete'
|
||||
| 'commit:pre'
|
||||
| 'commit:post'
|
||||
| 'error:occur'
|
||||
| 'test:fail'
|
||||
| 'test:pass'
|
||||
| 'build:start'
|
||||
| 'build:fail'
|
||||
| 'build:success';
|
||||
|
||||
/**
|
||||
* How to inject the skill when triggered
|
||||
*/
|
||||
export type InjectionMode = 'content' | 'reference' | 'prompt';
|
||||
|
||||
/**
|
||||
* Skill hook configuration
|
||||
*/
|
||||
export interface SkillHook {
|
||||
/** Unique identifier for this hook */
|
||||
id: string;
|
||||
/** Event that triggers this hook */
|
||||
event: HookEvent;
|
||||
/** Pattern to match (e.g., "*.test.ts", "src/**\/*.tsx") */
|
||||
matcher?: string | RegExp;
|
||||
/** Skills to activate when triggered */
|
||||
skills: string[];
|
||||
/** How to inject the skill */
|
||||
inject: InjectionMode;
|
||||
/** Priority (higher = earlier execution) */
|
||||
priority?: number;
|
||||
/** Condition expression (optional) */
|
||||
condition?: string;
|
||||
/** Whether hook is enabled */
|
||||
enabled: boolean;
|
||||
/** Agent-specific overrides */
|
||||
agentOverrides?: Partial<Record<AgentType, Partial<SkillHook>>>;
|
||||
/** Metadata */
|
||||
metadata?: Record<string, unknown>;
|
||||
}
|
||||
|
||||
/**
|
||||
* Context provided when a hook is triggered
|
||||
*/
|
||||
export interface HookContext {
|
||||
/** The event that was triggered */
|
||||
event: HookEvent;
|
||||
/** What triggered the event (filename, command, etc.) */
|
||||
trigger: string;
|
||||
/** Project path */
|
||||
projectPath: string;
|
||||
/** Target agent */
|
||||
agent: AgentType;
|
||||
/** Additional metadata */
|
||||
metadata?: Record<string, unknown>;
|
||||
/** Timestamp */
|
||||
timestamp: Date;
|
||||
}
|
||||
|
||||
/**
|
||||
* Result of activating a skill via hook
|
||||
*/
|
||||
export interface ActivatedSkill {
|
||||
/** Skill ID */
|
||||
skillId: string;
|
||||
/** Hook that activated it */
|
||||
hookId: string;
|
||||
/** Injection mode used */
|
||||
injectionMode: InjectionMode;
|
||||
/** The skill content (if injection mode is 'content') */
|
||||
content?: string;
|
||||
/** The skill reference (if injection mode is 'reference') */
|
||||
reference?: string;
|
||||
/** Activation timestamp */
|
||||
activatedAt: Date;
|
||||
}
|
||||
|
||||
/**
|
||||
* Hook trigger result
|
||||
*/
|
||||
export interface HookTriggerResult {
|
||||
/** Event that was triggered */
|
||||
event: HookEvent;
|
||||
/** Hooks that matched */
|
||||
matchedHooks: SkillHook[];
|
||||
/** Skills that were activated */
|
||||
activatedSkills: ActivatedSkill[];
|
||||
/** Any errors that occurred */
|
||||
errors: HookError[];
|
||||
/** Total execution time in ms */
|
||||
executionTimeMs: number;
|
||||
}
|
||||
|
||||
/**
|
||||
* Hook error
|
||||
*/
|
||||
export interface HookError {
|
||||
hookId: string;
|
||||
skillId?: string;
|
||||
message: string;
|
||||
stack?: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* Hook configuration file format
|
||||
*/
|
||||
export interface HookConfig {
|
||||
version: number;
|
||||
hooks: SkillHook[];
|
||||
defaults?: {
|
||||
inject?: InjectionMode;
|
||||
priority?: number;
|
||||
enabled?: boolean;
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Agent-specific hook format generator
|
||||
*/
|
||||
export interface AgentHookFormat {
|
||||
/** Agent type */
|
||||
agent: AgentType;
|
||||
/** Generate hook configuration for this agent */
|
||||
generate(hooks: SkillHook[]): string | Record<string, unknown>;
|
||||
/** Parse agent-specific hook format */
|
||||
parse(content: string | Record<string, unknown>): SkillHook[];
|
||||
/** File path for hook configuration */
|
||||
configPath: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* Hook manager options
|
||||
*/
|
||||
export interface HookManagerOptions {
|
||||
/** Project path */
|
||||
projectPath: string;
|
||||
/** Path to hooks configuration file */
|
||||
configPath?: string;
|
||||
/** Whether to auto-load hooks on init */
|
||||
autoLoad?: boolean;
|
||||
/** Default injection mode */
|
||||
defaultInjectionMode?: InjectionMode;
|
||||
}
|
||||
|
||||
/**
|
||||
* Trigger engine options
|
||||
*/
|
||||
export interface TriggerEngineOptions {
|
||||
/** Project path */
|
||||
projectPath: string;
|
||||
/** Whether to enable file watching */
|
||||
watchFiles?: boolean;
|
||||
/** Debounce time for file events (ms) */
|
||||
debounceMs?: number;
|
||||
}
|
||||
|
||||
/**
|
||||
* Hook event listener
|
||||
*/
|
||||
export type HookEventListener = (
|
||||
event: HookEvent,
|
||||
context: HookContext,
|
||||
result: HookTriggerResult
|
||||
) => void | Promise<void>;
|
||||
|
||||
/**
|
||||
* Matcher function type
|
||||
*/
|
||||
export type MatcherFunction = (trigger: string, context: HookContext) => boolean;
|
||||
@@ -45,3 +45,24 @@ export * from './team/index.js';
|
||||
|
||||
// Plugin System (Extensibility)
|
||||
export * from './plugins/index.js';
|
||||
|
||||
// Methodology Framework (Phase 12)
|
||||
export * from './methodology/index.js';
|
||||
|
||||
// Hooks & Automatic Triggering System (Phase 13)
|
||||
export * from './hooks/index.js';
|
||||
|
||||
// Team Orchestration System (Phase 14)
|
||||
export * from './orchestrator/index.js';
|
||||
|
||||
// Structured Plan System (Phase 15)
|
||||
export * from './plan/index.js';
|
||||
|
||||
// Slash Commands & Agent Integration (Phase 16)
|
||||
export * from './commands/index.js';
|
||||
|
||||
// AI-Powered Features (Phase 18)
|
||||
export * from './ai/index.js';
|
||||
|
||||
// Audit Logging (Phase 18)
|
||||
export * from './audit/index.js';
|
||||
|
||||
@@ -0,0 +1,275 @@
|
||||
import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
|
||||
import { mkdirSync, writeFileSync, rmSync, existsSync } from 'node:fs';
|
||||
import { join } from 'node:path';
|
||||
import { tmpdir } from 'node:os';
|
||||
import { MethodologyLoader, createMethodologyLoader } from '../loader.js';
|
||||
|
||||
describe('MethodologyLoader', () => {
|
||||
let testDir: string;
|
||||
let packsDir: string;
|
||||
|
||||
beforeEach(() => {
|
||||
// Create temporary directory for tests
|
||||
testDir = join(tmpdir(), `skillkit-test-${Date.now()}`);
|
||||
packsDir = join(testDir, 'packs');
|
||||
mkdirSync(packsDir, { recursive: true });
|
||||
});
|
||||
|
||||
afterEach(() => {
|
||||
// Clean up
|
||||
if (existsSync(testDir)) {
|
||||
rmSync(testDir, { recursive: true, force: true });
|
||||
}
|
||||
});
|
||||
|
||||
function createTestPack(name: string, skills: string[]): void {
|
||||
const packDir = join(packsDir, name);
|
||||
mkdirSync(packDir, { recursive: true });
|
||||
|
||||
// Create pack.json
|
||||
const manifest = {
|
||||
name,
|
||||
version: '1.0.0',
|
||||
description: `Test ${name} pack`,
|
||||
skills,
|
||||
tags: [name],
|
||||
compatibility: ['all'],
|
||||
};
|
||||
writeFileSync(join(packDir, 'pack.json'), JSON.stringify(manifest, null, 2));
|
||||
|
||||
// Create skill directories and SKILL.md files
|
||||
for (const skill of skills) {
|
||||
const skillDir = join(packDir, skill);
|
||||
mkdirSync(skillDir, { recursive: true });
|
||||
|
||||
const skillContent = `---
|
||||
name: ${skill}
|
||||
description: Test skill ${skill}
|
||||
version: 1.0.0
|
||||
triggers:
|
||||
- ${skill}
|
||||
tags:
|
||||
- test
|
||||
---
|
||||
|
||||
# ${skill}
|
||||
|
||||
This is a test skill. You must follow these instructions.
|
||||
|
||||
## Instructions
|
||||
|
||||
Do the thing.
|
||||
`;
|
||||
writeFileSync(join(skillDir, 'SKILL.md'), skillContent);
|
||||
}
|
||||
}
|
||||
|
||||
describe('loadAllPacks', () => {
|
||||
it('should load all available packs', async () => {
|
||||
createTestPack('testing', ['skill1', 'skill2']);
|
||||
createTestPack('debugging', ['skill3']);
|
||||
|
||||
const loader = new MethodologyLoader(packsDir);
|
||||
const packs = await loader.loadAllPacks();
|
||||
|
||||
expect(packs).toHaveLength(2);
|
||||
expect(packs.map(p => p.name).sort()).toEqual(['debugging', 'testing']);
|
||||
});
|
||||
|
||||
it('should return empty array when no packs exist', async () => {
|
||||
const loader = new MethodologyLoader(packsDir);
|
||||
const packs = await loader.loadAllPacks();
|
||||
|
||||
expect(packs).toHaveLength(0);
|
||||
});
|
||||
});
|
||||
|
||||
describe('loadPack', () => {
|
||||
it('should load a specific pack by name', async () => {
|
||||
createTestPack('testing', ['skill1', 'skill2']);
|
||||
|
||||
const loader = new MethodologyLoader(packsDir);
|
||||
const pack = await loader.loadPack('testing');
|
||||
|
||||
expect(pack).not.toBeNull();
|
||||
expect(pack?.name).toBe('testing');
|
||||
expect(pack?.skills).toEqual(['skill1', 'skill2']);
|
||||
});
|
||||
|
||||
it('should return null for non-existent pack', async () => {
|
||||
const loader = new MethodologyLoader(packsDir);
|
||||
const pack = await loader.loadPack('nonexistent');
|
||||
|
||||
expect(pack).toBeNull();
|
||||
});
|
||||
|
||||
it('should cache loaded packs', async () => {
|
||||
createTestPack('testing', ['skill1']);
|
||||
|
||||
const loader = new MethodologyLoader(packsDir);
|
||||
|
||||
const pack1 = await loader.loadPack('testing');
|
||||
const pack2 = await loader.loadPack('testing');
|
||||
|
||||
expect(pack1).toBe(pack2);
|
||||
});
|
||||
});
|
||||
|
||||
describe('loadPackSkills', () => {
|
||||
it('should load all skills from a pack', async () => {
|
||||
createTestPack('testing', ['skill1', 'skill2']);
|
||||
|
||||
const loader = new MethodologyLoader(packsDir);
|
||||
const skills = await loader.loadPackSkills('testing');
|
||||
|
||||
expect(skills).toHaveLength(2);
|
||||
expect(skills.map(s => s.id).sort()).toEqual(['testing/skill1', 'testing/skill2']);
|
||||
});
|
||||
|
||||
it('should throw error for non-existent pack', async () => {
|
||||
const loader = new MethodologyLoader(packsDir);
|
||||
|
||||
await expect(loader.loadPackSkills('nonexistent')).rejects.toThrow();
|
||||
});
|
||||
});
|
||||
|
||||
describe('loadSkill', () => {
|
||||
it('should load a specific skill', async () => {
|
||||
createTestPack('testing', ['skill1']);
|
||||
|
||||
const loader = new MethodologyLoader(packsDir);
|
||||
const skill = await loader.loadSkill('testing', 'skill1');
|
||||
|
||||
expect(skill).not.toBeNull();
|
||||
expect(skill?.id).toBe('testing/skill1');
|
||||
expect(skill?.name).toBe('skill1');
|
||||
expect(skill?.pack).toBe('testing');
|
||||
});
|
||||
|
||||
it('should return null for non-existent skill', async () => {
|
||||
createTestPack('testing', ['skill1']);
|
||||
|
||||
const loader = new MethodologyLoader(packsDir);
|
||||
const skill = await loader.loadSkill('testing', 'nonexistent');
|
||||
|
||||
expect(skill).toBeNull();
|
||||
});
|
||||
|
||||
it('should extract metadata from skill content', async () => {
|
||||
createTestPack('testing', ['skill1']);
|
||||
|
||||
const loader = new MethodologyLoader(packsDir);
|
||||
const skill = await loader.loadSkill('testing', 'skill1');
|
||||
|
||||
expect(skill?.metadata.triggers).toEqual(['skill1']);
|
||||
expect(skill?.tags).toEqual(['test']);
|
||||
});
|
||||
});
|
||||
|
||||
describe('getSkillById', () => {
|
||||
it('should get skill by full ID', async () => {
|
||||
createTestPack('testing', ['skill1']);
|
||||
|
||||
const loader = new MethodologyLoader(packsDir);
|
||||
const skill = await loader.getSkillById('testing/skill1');
|
||||
|
||||
expect(skill).not.toBeNull();
|
||||
expect(skill?.id).toBe('testing/skill1');
|
||||
});
|
||||
|
||||
it('should return null for invalid ID format', async () => {
|
||||
const loader = new MethodologyLoader(packsDir);
|
||||
const skill = await loader.getSkillById('invalid');
|
||||
|
||||
expect(skill).toBeNull();
|
||||
});
|
||||
});
|
||||
|
||||
describe('searchSkills', () => {
|
||||
it('should search skills by name', async () => {
|
||||
createTestPack('testing', ['tdd-skill', 'debug-skill']);
|
||||
|
||||
const loader = new MethodologyLoader(packsDir);
|
||||
const skills = await loader.searchSkills('tdd');
|
||||
|
||||
expect(skills).toHaveLength(1);
|
||||
expect(skills[0].id).toBe('testing/tdd-skill');
|
||||
});
|
||||
|
||||
it('should search skills by tag', async () => {
|
||||
createTestPack('testing', ['skill1']);
|
||||
|
||||
const loader = new MethodologyLoader(packsDir);
|
||||
const skills = await loader.searchSkills('test');
|
||||
|
||||
expect(skills).toHaveLength(1);
|
||||
});
|
||||
|
||||
it('should return all skills when query is empty', async () => {
|
||||
createTestPack('testing', ['skill1', 'skill2']);
|
||||
|
||||
const loader = new MethodologyLoader(packsDir);
|
||||
const skills = await loader.searchSkills('');
|
||||
|
||||
expect(skills).toHaveLength(2);
|
||||
});
|
||||
});
|
||||
|
||||
describe('packExists', () => {
|
||||
it('should return true for existing pack', () => {
|
||||
createTestPack('testing', ['skill1']);
|
||||
|
||||
const loader = new MethodologyLoader(packsDir);
|
||||
expect(loader.packExists('testing')).toBe(true);
|
||||
});
|
||||
|
||||
it('should return false for non-existent pack', () => {
|
||||
const loader = new MethodologyLoader(packsDir);
|
||||
expect(loader.packExists('nonexistent')).toBe(false);
|
||||
});
|
||||
});
|
||||
|
||||
describe('clearCache', () => {
|
||||
it('should clear cached packs and skills', async () => {
|
||||
createTestPack('testing', ['skill1']);
|
||||
|
||||
const loader = new MethodologyLoader(packsDir);
|
||||
|
||||
// Load to populate cache
|
||||
await loader.loadPack('testing');
|
||||
await loader.loadSkill('testing', 'skill1');
|
||||
|
||||
// Clear cache
|
||||
loader.clearCache();
|
||||
|
||||
// Modify pack on disk
|
||||
const packDir = join(packsDir, 'testing');
|
||||
const manifest = {
|
||||
name: 'testing',
|
||||
version: '2.0.0',
|
||||
description: 'Updated pack',
|
||||
skills: ['skill1'],
|
||||
tags: ['testing'],
|
||||
compatibility: ['all'],
|
||||
};
|
||||
writeFileSync(join(packDir, 'pack.json'), JSON.stringify(manifest, null, 2));
|
||||
|
||||
// Reload should get new version
|
||||
const pack = await loader.loadPack('testing');
|
||||
expect(pack?.version).toBe('2.0.0');
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
describe('createMethodologyLoader', () => {
|
||||
it('should create a loader instance', () => {
|
||||
const loader = createMethodologyLoader();
|
||||
expect(loader).toBeInstanceOf(MethodologyLoader);
|
||||
});
|
||||
|
||||
it('should accept custom packs directory', () => {
|
||||
const customDir = '/custom/packs';
|
||||
const loader = createMethodologyLoader(customDir);
|
||||
expect(loader.getPacksDir()).toBe(customDir);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,353 @@
|
||||
import { describe, it, expect, beforeEach, afterEach } from 'vitest';
|
||||
import { mkdirSync, writeFileSync, rmSync, existsSync, readFileSync } from 'node:fs';
|
||||
import { join } from 'node:path';
|
||||
import { tmpdir } from 'node:os';
|
||||
import { MethodologyManager, createMethodologyManager } from '../manager.js';
|
||||
|
||||
describe('MethodologyManager', () => {
|
||||
let testDir: string;
|
||||
let packsDir: string;
|
||||
let projectPath: string;
|
||||
|
||||
beforeEach(() => {
|
||||
// Create temporary directories for tests
|
||||
testDir = join(tmpdir(), `skillkit-manager-test-${Date.now()}`);
|
||||
packsDir = join(testDir, 'packs');
|
||||
projectPath = join(testDir, 'project');
|
||||
mkdirSync(packsDir, { recursive: true });
|
||||
mkdirSync(projectPath, { recursive: true });
|
||||
});
|
||||
|
||||
afterEach(() => {
|
||||
// Clean up
|
||||
if (existsSync(testDir)) {
|
||||
rmSync(testDir, { recursive: true, force: true });
|
||||
}
|
||||
});
|
||||
|
||||
function createTestPack(name: string, skills: string[]): void {
|
||||
const packDir = join(packsDir, name);
|
||||
mkdirSync(packDir, { recursive: true });
|
||||
|
||||
// Create pack.json
|
||||
const manifest = {
|
||||
name,
|
||||
version: '1.0.0',
|
||||
description: `Test ${name} pack`,
|
||||
skills,
|
||||
tags: [name],
|
||||
compatibility: ['all'],
|
||||
};
|
||||
writeFileSync(join(packDir, 'pack.json'), JSON.stringify(manifest, null, 2));
|
||||
|
||||
// Create skill directories and SKILL.md files
|
||||
for (const skill of skills) {
|
||||
const skillDir = join(packDir, skill);
|
||||
mkdirSync(skillDir, { recursive: true });
|
||||
|
||||
const skillContent = `---
|
||||
name: ${skill}
|
||||
description: Test skill ${skill}
|
||||
version: 1.0.0
|
||||
triggers:
|
||||
- ${skill}
|
||||
tags:
|
||||
- test
|
||||
---
|
||||
|
||||
# ${skill}
|
||||
|
||||
This is a test skill. You must follow these instructions.
|
||||
|
||||
## Instructions
|
||||
|
||||
Do the thing.
|
||||
`;
|
||||
writeFileSync(join(skillDir, 'SKILL.md'), skillContent);
|
||||
}
|
||||
}
|
||||
|
||||
describe('installPack', () => {
|
||||
it('should install a pack and its skills', async () => {
|
||||
createTestPack('testing', ['skill1', 'skill2']);
|
||||
|
||||
const manager = createMethodologyManager({
|
||||
projectPath,
|
||||
packsDir,
|
||||
autoSync: false,
|
||||
});
|
||||
|
||||
const result = await manager.installPack('testing');
|
||||
|
||||
expect(result.success).toBe(true);
|
||||
expect(result.installed).toHaveLength(2);
|
||||
expect(result.installed).toContain('testing/skill1');
|
||||
expect(result.installed).toContain('testing/skill2');
|
||||
});
|
||||
|
||||
it('should skip already installed packs', async () => {
|
||||
createTestPack('testing', ['skill1']);
|
||||
|
||||
const manager = createMethodologyManager({
|
||||
projectPath,
|
||||
packsDir,
|
||||
autoSync: false,
|
||||
});
|
||||
|
||||
// Install first time
|
||||
await manager.installPack('testing');
|
||||
|
||||
// Install again
|
||||
const result = await manager.installPack('testing');
|
||||
|
||||
expect(result.success).toBe(true);
|
||||
expect(result.skipped).toContain('testing');
|
||||
});
|
||||
|
||||
it('should fail for non-existent pack', async () => {
|
||||
const manager = createMethodologyManager({
|
||||
projectPath,
|
||||
packsDir,
|
||||
autoSync: false,
|
||||
});
|
||||
|
||||
const result = await manager.installPack('nonexistent');
|
||||
|
||||
expect(result.success).toBe(false);
|
||||
expect(result.failed).toHaveLength(1);
|
||||
});
|
||||
});
|
||||
|
||||
describe('installAllPacks', () => {
|
||||
it('should install all available packs', async () => {
|
||||
createTestPack('testing', ['skill1']);
|
||||
createTestPack('debugging', ['skill2']);
|
||||
|
||||
const manager = createMethodologyManager({
|
||||
projectPath,
|
||||
packsDir,
|
||||
autoSync: false,
|
||||
});
|
||||
|
||||
const result = await manager.installAllPacks();
|
||||
|
||||
expect(result.success).toBe(true);
|
||||
expect(result.installed).toHaveLength(2);
|
||||
});
|
||||
});
|
||||
|
||||
describe('installSkill', () => {
|
||||
it('should install a single skill', async () => {
|
||||
createTestPack('testing', ['skill1', 'skill2']);
|
||||
|
||||
const manager = createMethodologyManager({
|
||||
projectPath,
|
||||
packsDir,
|
||||
autoSync: false,
|
||||
});
|
||||
|
||||
const result = await manager.installSkill('testing/skill1');
|
||||
|
||||
expect(result.success).toBe(true);
|
||||
expect(result.installed).toContain('testing/skill1');
|
||||
});
|
||||
|
||||
it('should fail for non-existent skill', async () => {
|
||||
createTestPack('testing', ['skill1']);
|
||||
|
||||
const manager = createMethodologyManager({
|
||||
projectPath,
|
||||
packsDir,
|
||||
autoSync: false,
|
||||
});
|
||||
|
||||
const result = await manager.installSkill('testing/nonexistent');
|
||||
|
||||
expect(result.success).toBe(false);
|
||||
});
|
||||
});
|
||||
|
||||
describe('uninstallPack', () => {
|
||||
it('should uninstall a pack', async () => {
|
||||
createTestPack('testing', ['skill1']);
|
||||
|
||||
const manager = createMethodologyManager({
|
||||
projectPath,
|
||||
packsDir,
|
||||
autoSync: false,
|
||||
});
|
||||
|
||||
await manager.installPack('testing');
|
||||
await manager.uninstallPack('testing');
|
||||
|
||||
const installed = manager.listInstalledPacks();
|
||||
expect(installed).toHaveLength(0);
|
||||
});
|
||||
|
||||
it('should throw for non-installed pack', async () => {
|
||||
const manager = createMethodologyManager({
|
||||
projectPath,
|
||||
packsDir,
|
||||
autoSync: false,
|
||||
});
|
||||
|
||||
await expect(manager.uninstallPack('testing')).rejects.toThrow();
|
||||
});
|
||||
});
|
||||
|
||||
describe('listInstalledPacks', () => {
|
||||
it('should list installed packs', async () => {
|
||||
createTestPack('testing', ['skill1', 'skill2']);
|
||||
|
||||
const manager = createMethodologyManager({
|
||||
projectPath,
|
||||
packsDir,
|
||||
autoSync: false,
|
||||
});
|
||||
|
||||
await manager.installPack('testing');
|
||||
|
||||
const installed = manager.listInstalledPacks();
|
||||
|
||||
expect(installed).toHaveLength(1);
|
||||
expect(installed[0].name).toBe('testing');
|
||||
expect(installed[0].skills).toHaveLength(2);
|
||||
});
|
||||
|
||||
it('should return empty array when nothing installed', () => {
|
||||
const manager = createMethodologyManager({
|
||||
projectPath,
|
||||
packsDir,
|
||||
autoSync: false,
|
||||
});
|
||||
|
||||
const installed = manager.listInstalledPacks();
|
||||
expect(installed).toHaveLength(0);
|
||||
});
|
||||
});
|
||||
|
||||
describe('listInstalledSkills', () => {
|
||||
it('should list installed skills', async () => {
|
||||
createTestPack('testing', ['skill1', 'skill2']);
|
||||
|
||||
const manager = createMethodologyManager({
|
||||
projectPath,
|
||||
packsDir,
|
||||
autoSync: false,
|
||||
});
|
||||
|
||||
await manager.installPack('testing');
|
||||
|
||||
const installed = manager.listInstalledSkills();
|
||||
|
||||
expect(installed).toHaveLength(2);
|
||||
});
|
||||
});
|
||||
|
||||
describe('listAvailablePacks', () => {
|
||||
it('should list packs not yet installed', async () => {
|
||||
createTestPack('testing', ['skill1']);
|
||||
createTestPack('debugging', ['skill2']);
|
||||
|
||||
const manager = createMethodologyManager({
|
||||
projectPath,
|
||||
packsDir,
|
||||
autoSync: false,
|
||||
});
|
||||
|
||||
await manager.installPack('testing');
|
||||
|
||||
const available = await manager.listAvailablePacks();
|
||||
|
||||
expect(available).toHaveLength(1);
|
||||
expect(available[0].name).toBe('debugging');
|
||||
});
|
||||
});
|
||||
|
||||
describe('search', () => {
|
||||
it('should search by query string', async () => {
|
||||
createTestPack('testing', ['tdd-skill']);
|
||||
createTestPack('debugging', ['debug-skill']);
|
||||
|
||||
const manager = createMethodologyManager({
|
||||
projectPath,
|
||||
packsDir,
|
||||
autoSync: false,
|
||||
});
|
||||
|
||||
const result = await manager.search({ query: 'tdd' });
|
||||
|
||||
expect(result.skills).toHaveLength(1);
|
||||
expect(result.skills[0].id).toBe('testing/tdd-skill');
|
||||
});
|
||||
|
||||
it('should search by tags', async () => {
|
||||
createTestPack('testing', ['skill1']);
|
||||
|
||||
const manager = createMethodologyManager({
|
||||
projectPath,
|
||||
packsDir,
|
||||
autoSync: false,
|
||||
});
|
||||
|
||||
const result = await manager.search({ tags: ['test'] });
|
||||
|
||||
expect(result.skills).toHaveLength(1);
|
||||
});
|
||||
|
||||
it('should search by pack', async () => {
|
||||
createTestPack('testing', ['skill1', 'skill2']);
|
||||
createTestPack('debugging', ['skill3']);
|
||||
|
||||
const manager = createMethodologyManager({
|
||||
projectPath,
|
||||
packsDir,
|
||||
autoSync: false,
|
||||
});
|
||||
|
||||
const result = await manager.search({ pack: 'testing' });
|
||||
|
||||
expect(result.skills).toHaveLength(2);
|
||||
expect(result.packs).toHaveLength(1);
|
||||
});
|
||||
});
|
||||
|
||||
describe('state persistence', () => {
|
||||
it('should persist installed packs across instances', async () => {
|
||||
createTestPack('testing', ['skill1']);
|
||||
|
||||
// Install with first instance
|
||||
const manager1 = createMethodologyManager({
|
||||
projectPath,
|
||||
packsDir,
|
||||
autoSync: false,
|
||||
});
|
||||
await manager1.installPack('testing');
|
||||
|
||||
// Check with second instance
|
||||
const manager2 = createMethodologyManager({
|
||||
projectPath,
|
||||
packsDir,
|
||||
autoSync: false,
|
||||
});
|
||||
const installed = manager2.listInstalledPacks();
|
||||
|
||||
expect(installed).toHaveLength(1);
|
||||
expect(installed[0].name).toBe('testing');
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
describe('createMethodologyManager', () => {
|
||||
it('should create a manager instance', () => {
|
||||
const testDir = join(tmpdir(), `skillkit-test-create-${Date.now()}`);
|
||||
mkdirSync(testDir, { recursive: true });
|
||||
|
||||
try {
|
||||
const manager = createMethodologyManager({ projectPath: testDir });
|
||||
expect(manager).toBeInstanceOf(MethodologyManager);
|
||||
} finally {
|
||||
rmSync(testDir, { recursive: true, force: true });
|
||||
}
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,270 @@
|
||||
import { describe, it, expect } from 'vitest';
|
||||
import {
|
||||
validatePackManifest,
|
||||
validateSkillContent,
|
||||
extractSkillMetadata,
|
||||
} from '../validator.js';
|
||||
|
||||
describe('validatePackManifest', () => {
|
||||
it('should validate a valid pack manifest', () => {
|
||||
const manifest = {
|
||||
name: 'testing',
|
||||
version: '1.0.0',
|
||||
description: 'Test-driven development methodology pack',
|
||||
skills: ['red-green-refactor', 'test-patterns'],
|
||||
tags: ['tdd', 'testing'],
|
||||
compatibility: ['all'],
|
||||
};
|
||||
|
||||
const result = validatePackManifest(manifest);
|
||||
expect(result.valid).toBe(true);
|
||||
expect(result.errors).toHaveLength(0);
|
||||
});
|
||||
|
||||
it('should reject manifest with missing name', () => {
|
||||
const manifest = {
|
||||
version: '1.0.0',
|
||||
description: 'Test pack',
|
||||
skills: ['skill1'],
|
||||
};
|
||||
|
||||
const result = validatePackManifest(manifest);
|
||||
expect(result.valid).toBe(false);
|
||||
expect(result.errors.some(e => e.code === 'MISSING_NAME')).toBe(true);
|
||||
});
|
||||
|
||||
it('should reject manifest with invalid name format', () => {
|
||||
const manifest = {
|
||||
name: 'Invalid Name',
|
||||
version: '1.0.0',
|
||||
description: 'Test pack',
|
||||
skills: ['skill1'],
|
||||
};
|
||||
|
||||
const result = validatePackManifest(manifest);
|
||||
expect(result.valid).toBe(false);
|
||||
expect(result.errors.some(e => e.code === 'INVALID_NAME')).toBe(true);
|
||||
});
|
||||
|
||||
it('should reject manifest with missing version', () => {
|
||||
const manifest = {
|
||||
name: 'testing',
|
||||
description: 'Test pack',
|
||||
skills: ['skill1'],
|
||||
};
|
||||
|
||||
const result = validatePackManifest(manifest);
|
||||
expect(result.valid).toBe(false);
|
||||
expect(result.errors.some(e => e.code === 'MISSING_VERSION')).toBe(true);
|
||||
});
|
||||
|
||||
it('should reject manifest with invalid version format', () => {
|
||||
const manifest = {
|
||||
name: 'testing',
|
||||
version: 'v1',
|
||||
description: 'Test pack',
|
||||
skills: ['skill1'],
|
||||
};
|
||||
|
||||
const result = validatePackManifest(manifest);
|
||||
expect(result.valid).toBe(false);
|
||||
expect(result.errors.some(e => e.code === 'INVALID_VERSION')).toBe(true);
|
||||
});
|
||||
|
||||
it('should reject manifest with empty skills array', () => {
|
||||
const manifest = {
|
||||
name: 'testing',
|
||||
version: '1.0.0',
|
||||
description: 'Test pack',
|
||||
skills: [],
|
||||
};
|
||||
|
||||
const result = validatePackManifest(manifest);
|
||||
expect(result.valid).toBe(false);
|
||||
expect(result.errors.some(e => e.code === 'EMPTY_SKILLS')).toBe(true);
|
||||
});
|
||||
|
||||
it('should warn about short description', () => {
|
||||
const manifest = {
|
||||
name: 'testing',
|
||||
version: '1.0.0',
|
||||
description: 'Short',
|
||||
skills: ['skill1'],
|
||||
};
|
||||
|
||||
const result = validatePackManifest(manifest);
|
||||
expect(result.warnings.some(w => w.code === 'SHORT_DESCRIPTION')).toBe(true);
|
||||
});
|
||||
|
||||
it('should warn about missing tags', () => {
|
||||
const manifest = {
|
||||
name: 'testing',
|
||||
version: '1.0.0',
|
||||
description: 'A longer description for the pack',
|
||||
skills: ['skill1'],
|
||||
};
|
||||
|
||||
const result = validatePackManifest(manifest);
|
||||
expect(result.warnings.some(w => w.code === 'MISSING_TAGS')).toBe(true);
|
||||
});
|
||||
});
|
||||
|
||||
describe('validateSkillContent', () => {
|
||||
it('should validate valid skill content', () => {
|
||||
const content = `---
|
||||
name: Test Skill
|
||||
description: A test skill
|
||||
version: 1.0.0
|
||||
triggers:
|
||||
- test
|
||||
---
|
||||
|
||||
# Test Skill
|
||||
|
||||
## Description
|
||||
|
||||
This skill helps with testing. You should always write tests first.
|
||||
|
||||
## Instructions
|
||||
|
||||
1. Write a failing test
|
||||
2. Make it pass
|
||||
3. Refactor
|
||||
`;
|
||||
|
||||
const result = validateSkillContent(content);
|
||||
expect(result.valid).toBe(true);
|
||||
expect(result.errors).toHaveLength(0);
|
||||
});
|
||||
|
||||
it('should reject empty content', () => {
|
||||
const result = validateSkillContent('');
|
||||
expect(result.valid).toBe(false);
|
||||
expect(result.errors.some(e => e.code === 'EMPTY_CONTENT')).toBe(true);
|
||||
});
|
||||
|
||||
it('should reject unclosed frontmatter', () => {
|
||||
const content = `---
|
||||
name: Test Skill
|
||||
description: A test skill
|
||||
|
||||
# Missing closing frontmatter
|
||||
`;
|
||||
|
||||
const result = validateSkillContent(content);
|
||||
expect(result.valid).toBe(false);
|
||||
expect(result.errors.some(e => e.code === 'UNCLOSED_FRONTMATTER')).toBe(true);
|
||||
});
|
||||
|
||||
it('should warn about missing frontmatter', () => {
|
||||
const content = `# Test Skill
|
||||
|
||||
This is a skill without frontmatter. You should always follow these instructions.
|
||||
`;
|
||||
|
||||
const result = validateSkillContent(content);
|
||||
expect(result.valid).toBe(true); // Still valid, just a warning
|
||||
expect(result.warnings.some(w => w.code === 'NO_FRONTMATTER')).toBe(true);
|
||||
});
|
||||
|
||||
it('should warn about missing structure', () => {
|
||||
const content = `---
|
||||
name: Test
|
||||
---
|
||||
|
||||
Just some random text without proper sections. You must follow this.
|
||||
`;
|
||||
|
||||
const result = validateSkillContent(content);
|
||||
expect(result.warnings.some(w => w.code === 'MISSING_STRUCTURE')).toBe(true);
|
||||
});
|
||||
});
|
||||
|
||||
describe('extractSkillMetadata', () => {
|
||||
it('should extract simple key-value pairs', () => {
|
||||
const content = `---
|
||||
name: Test Skill
|
||||
version: 1.0.0
|
||||
difficulty: intermediate
|
||||
---
|
||||
|
||||
# Content
|
||||
`;
|
||||
|
||||
const metadata = extractSkillMetadata(content);
|
||||
expect(metadata.name).toBe('Test Skill');
|
||||
expect(metadata.version).toBe('1.0.0');
|
||||
expect(metadata.difficulty).toBe('intermediate');
|
||||
});
|
||||
|
||||
it('should extract array values', () => {
|
||||
const content = `---
|
||||
name: Test Skill
|
||||
triggers:
|
||||
- tdd
|
||||
- test driven
|
||||
- write tests
|
||||
tags:
|
||||
- testing
|
||||
- quality
|
||||
---
|
||||
|
||||
# Content
|
||||
`;
|
||||
|
||||
const metadata = extractSkillMetadata(content);
|
||||
expect(metadata.triggers).toEqual(['tdd', 'test driven', 'write tests']);
|
||||
expect(metadata.tags).toEqual(['testing', 'quality']);
|
||||
});
|
||||
|
||||
it('should extract inline arrays', () => {
|
||||
const content = `---
|
||||
name: Test Skill
|
||||
tags: [testing, quality]
|
||||
---
|
||||
|
||||
# Content
|
||||
`;
|
||||
|
||||
const metadata = extractSkillMetadata(content);
|
||||
expect(metadata.tags).toEqual(['testing', 'quality']);
|
||||
});
|
||||
|
||||
it('should extract numeric values', () => {
|
||||
const content = `---
|
||||
name: Test Skill
|
||||
estimatedTime: 15
|
||||
---
|
||||
|
||||
# Content
|
||||
`;
|
||||
|
||||
const metadata = extractSkillMetadata(content);
|
||||
expect(metadata.estimatedTime).toBe(15);
|
||||
});
|
||||
|
||||
it('should extract boolean values', () => {
|
||||
const content = `---
|
||||
name: Test Skill
|
||||
deprecated: true
|
||||
active: false
|
||||
---
|
||||
|
||||
# Content
|
||||
`;
|
||||
|
||||
const metadata = extractSkillMetadata(content);
|
||||
expect(metadata.deprecated).toBe(true);
|
||||
expect(metadata.active).toBe(false);
|
||||
});
|
||||
|
||||
it('should return empty object for content without frontmatter', () => {
|
||||
const content = `# Test Skill
|
||||
|
||||
No frontmatter here.
|
||||
`;
|
||||
|
||||
const metadata = extractSkillMetadata(content);
|
||||
expect(metadata).toEqual({});
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,50 @@
|
||||
/**
|
||||
* Methodology Framework
|
||||
*
|
||||
* Provides a composable, community-driven methodology system for AI coding agents.
|
||||
* Supports multiple approaches (TDD, BDD, DDD, or custom methodologies) through
|
||||
* installable "packs" of related skills.
|
||||
*
|
||||
* Key features:
|
||||
* - Methodology packs: Collections of related skills (testing, debugging, planning)
|
||||
* - Universal translation: Skills work across all 17 supported agents
|
||||
* - Pack management: Install, uninstall, and sync methodology skills
|
||||
* - Community-driven: Open for custom methodology contributions
|
||||
*/
|
||||
|
||||
// Manager
|
||||
export { MethodologyManager, createMethodologyManager } from './manager.js';
|
||||
|
||||
// Loader
|
||||
export {
|
||||
MethodologyLoader,
|
||||
createMethodologyLoader,
|
||||
getBuiltinPacksDir,
|
||||
} from './loader.js';
|
||||
|
||||
// Validator
|
||||
export {
|
||||
validatePackManifest,
|
||||
validateSkillContent,
|
||||
validatePackDirectory,
|
||||
validateBuiltinPacks,
|
||||
extractSkillMetadata,
|
||||
} from './validator.js';
|
||||
|
||||
// Types
|
||||
export type {
|
||||
MethodologyPack,
|
||||
MethodologySkill,
|
||||
MethodologySkillMetadata,
|
||||
MethodologyState,
|
||||
MethodologyManagerOptions,
|
||||
InstallResult,
|
||||
MethodologySyncResult,
|
||||
ValidationResult,
|
||||
ValidationError,
|
||||
ValidationWarning,
|
||||
MethodologySearchQuery,
|
||||
MethodologySearchResult,
|
||||
InstalledPackInfo,
|
||||
InstalledSkillInfo,
|
||||
} from './types.js';
|
||||
@@ -0,0 +1,278 @@
|
||||
/**
|
||||
* Methodology Loader
|
||||
*
|
||||
* Loads methodology packs and skills from the built-in packs directory
|
||||
* and custom locations.
|
||||
*/
|
||||
|
||||
import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
|
||||
import { join, dirname } from 'node:path';
|
||||
import { fileURLToPath } from 'node:url';
|
||||
import type {
|
||||
MethodologyPack,
|
||||
MethodologySkill,
|
||||
MethodologySkillMetadata,
|
||||
} from './types.js';
|
||||
import { validatePackDirectory, extractSkillMetadata } from './validator.js';
|
||||
|
||||
// Get the directory of this module
|
||||
const __filename = fileURLToPath(import.meta.url);
|
||||
const __dirname = dirname(__filename);
|
||||
|
||||
// Built-in packs directory (relative to this file in dist)
|
||||
const BUILTIN_PACKS_DIR = join(__dirname, 'packs');
|
||||
|
||||
/**
|
||||
* Methodology Loader class
|
||||
*/
|
||||
export class MethodologyLoader {
|
||||
private packsDir: string;
|
||||
private loadedPacks: Map<string, MethodologyPack> = new Map();
|
||||
private loadedSkills: Map<string, MethodologySkill> = new Map();
|
||||
|
||||
constructor(customPacksDir?: string) {
|
||||
this.packsDir = customPacksDir || BUILTIN_PACKS_DIR;
|
||||
}
|
||||
|
||||
/**
|
||||
* Load all available packs
|
||||
*/
|
||||
async loadAllPacks(): Promise<MethodologyPack[]> {
|
||||
const packs: MethodologyPack[] = [];
|
||||
|
||||
if (!existsSync(this.packsDir)) {
|
||||
return packs;
|
||||
}
|
||||
|
||||
const packDirs = readdirSync(this.packsDir).filter((name) => {
|
||||
const packPath = join(this.packsDir, name);
|
||||
return statSync(packPath).isDirectory();
|
||||
});
|
||||
|
||||
for (const packName of packDirs) {
|
||||
try {
|
||||
const pack = await this.loadPack(packName);
|
||||
if (pack) {
|
||||
packs.push(pack);
|
||||
}
|
||||
} catch {
|
||||
// Skip invalid packs
|
||||
}
|
||||
}
|
||||
|
||||
return packs;
|
||||
}
|
||||
|
||||
/**
|
||||
* Load a specific pack by name
|
||||
*/
|
||||
async loadPack(packName: string): Promise<MethodologyPack | null> {
|
||||
// Check cache
|
||||
if (this.loadedPacks.has(packName)) {
|
||||
return this.loadedPacks.get(packName)!;
|
||||
}
|
||||
|
||||
const packPath = join(this.packsDir, packName);
|
||||
const manifestPath = join(packPath, 'pack.json');
|
||||
|
||||
if (!existsSync(manifestPath)) {
|
||||
return null;
|
||||
}
|
||||
|
||||
// Validate pack
|
||||
const validation = validatePackDirectory(packPath);
|
||||
if (!validation.valid) {
|
||||
throw new Error(
|
||||
`Invalid pack "${packName}": ${validation.errors.map((e) => e.message).join(', ')}`
|
||||
);
|
||||
}
|
||||
|
||||
// Load manifest
|
||||
const manifest = JSON.parse(
|
||||
readFileSync(manifestPath, 'utf-8')
|
||||
) as MethodologyPack;
|
||||
|
||||
// Cache and return
|
||||
this.loadedPacks.set(packName, manifest);
|
||||
return manifest;
|
||||
}
|
||||
|
||||
/**
|
||||
* Load all skills from a pack
|
||||
*/
|
||||
async loadPackSkills(packName: string): Promise<MethodologySkill[]> {
|
||||
const pack = await this.loadPack(packName);
|
||||
if (!pack) {
|
||||
throw new Error(`Pack not found: ${packName}`);
|
||||
}
|
||||
|
||||
const skills: MethodologySkill[] = [];
|
||||
|
||||
for (const skillName of pack.skills) {
|
||||
const skill = await this.loadSkill(packName, skillName);
|
||||
if (skill) {
|
||||
skills.push(skill);
|
||||
}
|
||||
}
|
||||
|
||||
return skills;
|
||||
}
|
||||
|
||||
/**
|
||||
* Load a specific skill
|
||||
*/
|
||||
async loadSkill(
|
||||
packName: string,
|
||||
skillName: string
|
||||
): Promise<MethodologySkill | null> {
|
||||
const skillId = `${packName}/${skillName}`;
|
||||
|
||||
// Check cache
|
||||
if (this.loadedSkills.has(skillId)) {
|
||||
return this.loadedSkills.get(skillId)!;
|
||||
}
|
||||
|
||||
const skillPath = join(this.packsDir, packName, skillName, 'SKILL.md');
|
||||
|
||||
if (!existsSync(skillPath)) {
|
||||
return null;
|
||||
}
|
||||
|
||||
const content = readFileSync(skillPath, 'utf-8');
|
||||
const rawMetadata = extractSkillMetadata(content);
|
||||
|
||||
// Parse metadata with defaults
|
||||
const metadata: MethodologySkillMetadata = {
|
||||
triggers: rawMetadata.triggers as string[] | undefined,
|
||||
relatedSkills: rawMetadata.relatedSkills as string[] | undefined,
|
||||
difficulty: rawMetadata.difficulty as MethodologySkillMetadata['difficulty'],
|
||||
estimatedTime: rawMetadata.estimatedTime as number | undefined,
|
||||
prerequisites: rawMetadata.prerequisites as string[] | undefined,
|
||||
...rawMetadata,
|
||||
};
|
||||
|
||||
const skill: MethodologySkill = {
|
||||
id: skillId,
|
||||
name: (rawMetadata.name as string) || formatSkillName(skillName),
|
||||
description: (rawMetadata.description as string) || '',
|
||||
version: (rawMetadata.version as string) || '1.0.0',
|
||||
pack: packName,
|
||||
tags: (rawMetadata.tags as string[]) || [],
|
||||
path: skillPath,
|
||||
content,
|
||||
metadata,
|
||||
};
|
||||
|
||||
// Cache and return
|
||||
this.loadedSkills.set(skillId, skill);
|
||||
return skill;
|
||||
}
|
||||
|
||||
/**
|
||||
* Get skill by full ID (pack/skill)
|
||||
*/
|
||||
async getSkillById(skillId: string): Promise<MethodologySkill | null> {
|
||||
const [packName, skillName] = skillId.split('/');
|
||||
if (!packName || !skillName) {
|
||||
return null;
|
||||
}
|
||||
return this.loadSkill(packName, skillName);
|
||||
}
|
||||
|
||||
/**
|
||||
* Search skills by query
|
||||
*/
|
||||
async searchSkills(query: string): Promise<MethodologySkill[]> {
|
||||
const allSkills: MethodologySkill[] = [];
|
||||
const packs = await this.loadAllPacks();
|
||||
|
||||
for (const pack of packs) {
|
||||
const skills = await this.loadPackSkills(pack.name);
|
||||
allSkills.push(...skills);
|
||||
}
|
||||
|
||||
if (!query) {
|
||||
return allSkills;
|
||||
}
|
||||
|
||||
const lowerQuery = query.toLowerCase();
|
||||
return allSkills.filter((skill) => {
|
||||
return (
|
||||
skill.name.toLowerCase().includes(lowerQuery) ||
|
||||
skill.description.toLowerCase().includes(lowerQuery) ||
|
||||
skill.tags.some((tag) => tag.toLowerCase().includes(lowerQuery)) ||
|
||||
skill.metadata.triggers?.some((t) =>
|
||||
t.toLowerCase().includes(lowerQuery)
|
||||
)
|
||||
);
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
* Get skills by tag
|
||||
*/
|
||||
async getSkillsByTag(tag: string): Promise<MethodologySkill[]> {
|
||||
const allSkills: MethodologySkill[] = [];
|
||||
const packs = await this.loadAllPacks();
|
||||
|
||||
for (const pack of packs) {
|
||||
const skills = await this.loadPackSkills(pack.name);
|
||||
allSkills.push(...skills);
|
||||
}
|
||||
|
||||
const lowerTag = tag.toLowerCase();
|
||||
return allSkills.filter((skill) =>
|
||||
skill.tags.some((t) => t.toLowerCase() === lowerTag)
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* Get built-in packs directory path
|
||||
*/
|
||||
getPacksDir(): string {
|
||||
return this.packsDir;
|
||||
}
|
||||
|
||||
/**
|
||||
* Check if a pack exists
|
||||
*/
|
||||
packExists(packName: string): boolean {
|
||||
const packPath = join(this.packsDir, packName);
|
||||
const manifestPath = join(packPath, 'pack.json');
|
||||
return existsSync(manifestPath);
|
||||
}
|
||||
|
||||
/**
|
||||
* Clear cache
|
||||
*/
|
||||
clearCache(): void {
|
||||
this.loadedPacks.clear();
|
||||
this.loadedSkills.clear();
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Format skill directory name to display name
|
||||
*/
|
||||
function formatSkillName(dirName: string): string {
|
||||
return dirName
|
||||
.split('-')
|
||||
.map((word) => word.charAt(0).toUpperCase() + word.slice(1))
|
||||
.join(' ');
|
||||
}
|
||||
|
||||
/**
|
||||
* Create a methodology loader instance
|
||||
*/
|
||||
export function createMethodologyLoader(
|
||||
customPacksDir?: string
|
||||
): MethodologyLoader {
|
||||
return new MethodologyLoader(customPacksDir);
|
||||
}
|
||||
|
||||
/**
|
||||
* Get the built-in packs directory
|
||||
*/
|
||||
export function getBuiltinPacksDir(): string {
|
||||
return BUILTIN_PACKS_DIR;
|
||||
}
|
||||
@@ -0,0 +1,597 @@
|
||||
/**
|
||||
* Methodology Manager
|
||||
*
|
||||
* Manages methodology pack installation, syncing, and lifecycle.
|
||||
*/
|
||||
|
||||
import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
|
||||
import { join, dirname } from 'node:path';
|
||||
import type { AgentType } from '../types.js';
|
||||
import type {
|
||||
MethodologyPack,
|
||||
MethodologySkill,
|
||||
MethodologyState,
|
||||
MethodologyManagerOptions,
|
||||
InstallResult,
|
||||
MethodologySyncResult,
|
||||
MethodologySearchQuery,
|
||||
MethodologySearchResult,
|
||||
} from './types.js';
|
||||
import { MethodologyLoader, createMethodologyLoader } from './loader.js';
|
||||
import { TranslatorRegistry } from '../translator/registry.js';
|
||||
|
||||
const METHODOLOGY_STATE_FILE = '.skillkit/methodology.json';
|
||||
|
||||
/**
|
||||
* Methodology Manager class
|
||||
*/
|
||||
export class MethodologyManager {
|
||||
private projectPath: string;
|
||||
private loader: MethodologyLoader;
|
||||
private state: MethodologyState;
|
||||
private autoSync: boolean;
|
||||
|
||||
constructor(options: MethodologyManagerOptions) {
|
||||
this.projectPath = options.projectPath;
|
||||
this.loader = createMethodologyLoader(options.packsDir);
|
||||
this.autoSync = options.autoSync ?? true;
|
||||
this.state = this.loadState();
|
||||
}
|
||||
|
||||
/**
|
||||
* Install a methodology pack
|
||||
*/
|
||||
async installPack(packName: string): Promise<InstallResult> {
|
||||
const result: InstallResult = {
|
||||
success: true,
|
||||
installed: [],
|
||||
skipped: [],
|
||||
failed: [],
|
||||
};
|
||||
|
||||
// Load pack
|
||||
const pack = await this.loader.loadPack(packName);
|
||||
if (!pack) {
|
||||
result.success = false;
|
||||
result.failed.push({
|
||||
name: packName,
|
||||
error: `Pack not found: ${packName}`,
|
||||
});
|
||||
return result;
|
||||
}
|
||||
|
||||
// Check if already installed
|
||||
if (this.state.installedPacks[packName]) {
|
||||
const installedVersion = this.state.installedPacks[packName].version;
|
||||
if (installedVersion === pack.version) {
|
||||
result.skipped.push(packName);
|
||||
return result;
|
||||
}
|
||||
}
|
||||
|
||||
// Install each skill
|
||||
const skills = await this.loader.loadPackSkills(packName);
|
||||
const installedSkillNames: string[] = [];
|
||||
|
||||
for (const skill of skills) {
|
||||
try {
|
||||
await this.installSkillLocally(skill);
|
||||
installedSkillNames.push(skill.id);
|
||||
result.installed.push(skill.id);
|
||||
} catch (e) {
|
||||
result.failed.push({
|
||||
name: skill.id,
|
||||
error: e instanceof Error ? e.message : 'Unknown error',
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
// Update state
|
||||
this.state.installedPacks[packName] = {
|
||||
version: pack.version,
|
||||
installedAt: new Date().toISOString(),
|
||||
skills: installedSkillNames,
|
||||
autoSync: this.autoSync,
|
||||
};
|
||||
this.saveState();
|
||||
|
||||
// Auto-sync if enabled
|
||||
if (this.autoSync) {
|
||||
await this.syncPack(packName);
|
||||
}
|
||||
|
||||
result.success = result.failed.length === 0;
|
||||
return result;
|
||||
}
|
||||
|
||||
/**
|
||||
* Install all available packs
|
||||
*/
|
||||
async installAllPacks(): Promise<InstallResult> {
|
||||
const result: InstallResult = {
|
||||
success: true,
|
||||
installed: [],
|
||||
skipped: [],
|
||||
failed: [],
|
||||
};
|
||||
|
||||
const packs = await this.loader.loadAllPacks();
|
||||
|
||||
for (const pack of packs) {
|
||||
const packResult = await this.installPack(pack.name);
|
||||
result.installed.push(...packResult.installed);
|
||||
result.skipped.push(...packResult.skipped);
|
||||
result.failed.push(...packResult.failed);
|
||||
}
|
||||
|
||||
result.success = result.failed.length === 0;
|
||||
return result;
|
||||
}
|
||||
|
||||
/**
|
||||
* Install a single skill by ID
|
||||
*/
|
||||
async installSkill(skillId: string): Promise<InstallResult> {
|
||||
const result: InstallResult = {
|
||||
success: true,
|
||||
installed: [],
|
||||
skipped: [],
|
||||
failed: [],
|
||||
};
|
||||
|
||||
const skill = await this.loader.getSkillById(skillId);
|
||||
if (!skill) {
|
||||
result.success = false;
|
||||
result.failed.push({
|
||||
name: skillId,
|
||||
error: `Skill not found: ${skillId}`,
|
||||
});
|
||||
return result;
|
||||
}
|
||||
|
||||
// Check if already installed
|
||||
if (this.state.installedSkills[skillId]) {
|
||||
const installedVersion = this.state.installedSkills[skillId].version;
|
||||
if (installedVersion === skill.version) {
|
||||
result.skipped.push(skillId);
|
||||
return result;
|
||||
}
|
||||
}
|
||||
|
||||
try {
|
||||
await this.installSkillLocally(skill);
|
||||
result.installed.push(skillId);
|
||||
|
||||
// Update state
|
||||
this.state.installedSkills[skillId] = {
|
||||
version: skill.version,
|
||||
pack: skill.pack,
|
||||
installedAt: new Date().toISOString(),
|
||||
syncedAgents: [],
|
||||
};
|
||||
this.saveState();
|
||||
|
||||
// Auto-sync if enabled
|
||||
if (this.autoSync) {
|
||||
await this.syncSkill(skillId);
|
||||
}
|
||||
} catch (e) {
|
||||
result.success = false;
|
||||
result.failed.push({
|
||||
name: skillId,
|
||||
error: e instanceof Error ? e.message : 'Unknown error',
|
||||
});
|
||||
}
|
||||
|
||||
return result;
|
||||
}
|
||||
|
||||
/**
|
||||
* Uninstall a pack
|
||||
*/
|
||||
async uninstallPack(packName: string): Promise<void> {
|
||||
const packInfo = this.state.installedPacks[packName];
|
||||
if (!packInfo) {
|
||||
throw new Error(`Pack not installed: ${packName}`);
|
||||
}
|
||||
|
||||
// Remove all skills from the pack
|
||||
for (const skillId of packInfo.skills) {
|
||||
await this.removeSkillLocally(skillId);
|
||||
delete this.state.installedSkills[skillId];
|
||||
}
|
||||
|
||||
// Remove pack from state
|
||||
delete this.state.installedPacks[packName];
|
||||
this.saveState();
|
||||
}
|
||||
|
||||
/**
|
||||
* Uninstall a skill
|
||||
*/
|
||||
async uninstallSkill(skillId: string): Promise<void> {
|
||||
const skillInfo = this.state.installedSkills[skillId];
|
||||
if (!skillInfo) {
|
||||
throw new Error(`Skill not installed: ${skillId}`);
|
||||
}
|
||||
|
||||
await this.removeSkillLocally(skillId);
|
||||
delete this.state.installedSkills[skillId];
|
||||
this.saveState();
|
||||
}
|
||||
|
||||
/**
|
||||
* Sync a pack to all detected agents
|
||||
*/
|
||||
async syncPack(packName: string, agents?: AgentType[]): Promise<MethodologySyncResult> {
|
||||
const result: MethodologySyncResult = {
|
||||
success: true,
|
||||
synced: [],
|
||||
failed: [],
|
||||
};
|
||||
|
||||
const packInfo = this.state.installedPacks[packName];
|
||||
if (!packInfo) {
|
||||
throw new Error(`Pack not installed: ${packName}`);
|
||||
}
|
||||
|
||||
for (const skillId of packInfo.skills) {
|
||||
const skillResult = await this.syncSkill(skillId, agents);
|
||||
result.synced.push(...skillResult.synced);
|
||||
result.failed.push(...skillResult.failed);
|
||||
}
|
||||
|
||||
result.success = result.failed.length === 0;
|
||||
return result;
|
||||
}
|
||||
|
||||
/**
|
||||
* Sync a skill to all detected agents
|
||||
*/
|
||||
async syncSkill(skillId: string, agents?: AgentType[]): Promise<MethodologySyncResult> {
|
||||
const result: MethodologySyncResult = {
|
||||
success: true,
|
||||
synced: [],
|
||||
failed: [],
|
||||
};
|
||||
|
||||
const skill = await this.loader.getSkillById(skillId);
|
||||
if (!skill) {
|
||||
throw new Error(`Skill not found: ${skillId}`);
|
||||
}
|
||||
|
||||
const targetAgents = agents || this.detectAgents();
|
||||
const registry = new TranslatorRegistry();
|
||||
const syncedAgents: AgentType[] = [];
|
||||
|
||||
for (const agent of targetAgents) {
|
||||
try {
|
||||
// Translate skill to target agent format
|
||||
const translationResult = registry.translateContent(skill.content, agent, {
|
||||
sourceFilename: 'SKILL.md',
|
||||
});
|
||||
|
||||
if (!translationResult.success) {
|
||||
result.failed.push({
|
||||
skill: skillId,
|
||||
agent,
|
||||
error: translationResult.incompatible?.join(', ') || 'Translation failed',
|
||||
});
|
||||
continue;
|
||||
}
|
||||
|
||||
// Write to agent's skills directory
|
||||
await this.writeSkillToAgent(skillId, translationResult.content, agent);
|
||||
|
||||
syncedAgents.push(agent);
|
||||
result.synced.push({ skill: skillId, agents: [agent] });
|
||||
} catch (e) {
|
||||
result.failed.push({
|
||||
skill: skillId,
|
||||
agent,
|
||||
error: e instanceof Error ? e.message : 'Unknown error',
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
// Update synced agents in state
|
||||
if (this.state.installedSkills[skillId]) {
|
||||
this.state.installedSkills[skillId].syncedAgents = syncedAgents;
|
||||
}
|
||||
this.state.lastSync = new Date().toISOString();
|
||||
this.saveState();
|
||||
|
||||
result.success = result.failed.length === 0;
|
||||
return result;
|
||||
}
|
||||
|
||||
/**
|
||||
* Sync all installed skills
|
||||
*/
|
||||
async syncAll(agents?: AgentType[]): Promise<MethodologySyncResult> {
|
||||
const result: MethodologySyncResult = {
|
||||
success: true,
|
||||
synced: [],
|
||||
failed: [],
|
||||
};
|
||||
|
||||
const allSkillIds = [
|
||||
...Object.keys(this.state.installedSkills),
|
||||
...Object.values(this.state.installedPacks).flatMap((p) => p.skills),
|
||||
];
|
||||
|
||||
const uniqueSkillIds = [...new Set(allSkillIds)];
|
||||
|
||||
for (const skillId of uniqueSkillIds) {
|
||||
const skillResult = await this.syncSkill(skillId, agents);
|
||||
result.synced.push(...skillResult.synced);
|
||||
result.failed.push(...skillResult.failed);
|
||||
}
|
||||
|
||||
result.success = result.failed.length === 0;
|
||||
return result;
|
||||
}
|
||||
|
||||
/**
|
||||
* List installed packs
|
||||
*/
|
||||
listInstalledPacks(): Array<{ name: string; version: string; skills: string[] }> {
|
||||
return Object.entries(this.state.installedPacks).map(([name, info]) => ({
|
||||
name,
|
||||
version: info.version,
|
||||
skills: info.skills,
|
||||
}));
|
||||
}
|
||||
|
||||
/**
|
||||
* List installed skills
|
||||
*/
|
||||
listInstalledSkills(): Array<{
|
||||
id: string;
|
||||
version: string;
|
||||
pack?: string;
|
||||
syncedAgents: AgentType[];
|
||||
}> {
|
||||
const skillsFromPacks = Object.values(this.state.installedPacks).flatMap(
|
||||
(pack) =>
|
||||
pack.skills.map((skillId) => ({
|
||||
id: skillId,
|
||||
version: this.state.installedSkills[skillId]?.version || pack.version,
|
||||
pack: skillId.split('/')[0],
|
||||
syncedAgents: this.state.installedSkills[skillId]?.syncedAgents || [],
|
||||
}))
|
||||
);
|
||||
|
||||
const individualSkills = Object.entries(this.state.installedSkills)
|
||||
.filter(([id]) => !skillsFromPacks.some((s) => s.id === id))
|
||||
.map(([id, info]) => ({
|
||||
id,
|
||||
version: info.version,
|
||||
pack: info.pack,
|
||||
syncedAgents: info.syncedAgents,
|
||||
}));
|
||||
|
||||
return [...skillsFromPacks, ...individualSkills];
|
||||
}
|
||||
|
||||
/**
|
||||
* List available packs (not yet installed)
|
||||
*/
|
||||
async listAvailablePacks(): Promise<MethodologyPack[]> {
|
||||
const allPacks = await this.loader.loadAllPacks();
|
||||
return allPacks.filter((pack) => !this.state.installedPacks[pack.name]);
|
||||
}
|
||||
|
||||
/**
|
||||
* Search methodology skills
|
||||
*/
|
||||
async search(query: MethodologySearchQuery): Promise<MethodologySearchResult> {
|
||||
const packs = await this.loader.loadAllPacks();
|
||||
const allSkills: MethodologySkill[] = [];
|
||||
|
||||
for (const pack of packs) {
|
||||
const skills = await this.loader.loadPackSkills(pack.name);
|
||||
allSkills.push(...skills);
|
||||
}
|
||||
|
||||
let matchingSkills = allSkills;
|
||||
let matchingPacks = packs;
|
||||
|
||||
// Filter by query string
|
||||
if (query.query) {
|
||||
const lowerQuery = query.query.toLowerCase();
|
||||
matchingSkills = matchingSkills.filter(
|
||||
(skill) =>
|
||||
skill.name.toLowerCase().includes(lowerQuery) ||
|
||||
skill.description.toLowerCase().includes(lowerQuery) ||
|
||||
skill.tags.some((t) => t.toLowerCase().includes(lowerQuery))
|
||||
);
|
||||
matchingPacks = matchingPacks.filter(
|
||||
(pack) =>
|
||||
pack.name.toLowerCase().includes(lowerQuery) ||
|
||||
pack.description.toLowerCase().includes(lowerQuery) ||
|
||||
pack.tags.some((t) => t.toLowerCase().includes(lowerQuery))
|
||||
);
|
||||
}
|
||||
|
||||
// Filter by tags
|
||||
if (query.tags && query.tags.length > 0) {
|
||||
const lowerTags = query.tags.map((t) => t.toLowerCase());
|
||||
matchingSkills = matchingSkills.filter((skill) =>
|
||||
lowerTags.some((tag) =>
|
||||
skill.tags.some((t) => t.toLowerCase() === tag)
|
||||
)
|
||||
);
|
||||
matchingPacks = matchingPacks.filter((pack) =>
|
||||
lowerTags.some((tag) => pack.tags.some((t) => t.toLowerCase() === tag))
|
||||
);
|
||||
}
|
||||
|
||||
// Filter by pack
|
||||
if (query.pack) {
|
||||
matchingSkills = matchingSkills.filter(
|
||||
(skill) => skill.pack === query.pack
|
||||
);
|
||||
matchingPacks = matchingPacks.filter((pack) => pack.name === query.pack);
|
||||
}
|
||||
|
||||
// Filter by difficulty
|
||||
if (query.difficulty) {
|
||||
matchingSkills = matchingSkills.filter(
|
||||
(skill) => skill.metadata.difficulty === query.difficulty
|
||||
);
|
||||
}
|
||||
|
||||
return {
|
||||
skills: matchingSkills,
|
||||
packs: matchingPacks,
|
||||
total: matchingSkills.length + matchingPacks.length,
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Get the loader instance
|
||||
*/
|
||||
getLoader(): MethodologyLoader {
|
||||
return this.loader;
|
||||
}
|
||||
|
||||
// Private helpers
|
||||
|
||||
private loadState(): MethodologyState {
|
||||
const statePath = join(this.projectPath, METHODOLOGY_STATE_FILE);
|
||||
if (existsSync(statePath)) {
|
||||
try {
|
||||
return JSON.parse(readFileSync(statePath, 'utf-8'));
|
||||
} catch {
|
||||
// Return default state on error
|
||||
}
|
||||
}
|
||||
return {
|
||||
version: 1,
|
||||
installedPacks: {},
|
||||
installedSkills: {},
|
||||
};
|
||||
}
|
||||
|
||||
private saveState(): void {
|
||||
const statePath = join(this.projectPath, METHODOLOGY_STATE_FILE);
|
||||
const dir = dirname(statePath);
|
||||
if (!existsSync(dir)) {
|
||||
mkdirSync(dir, { recursive: true });
|
||||
}
|
||||
writeFileSync(statePath, JSON.stringify(this.state, null, 2), 'utf-8');
|
||||
}
|
||||
|
||||
private async installSkillLocally(skill: MethodologySkill): Promise<void> {
|
||||
// Copy skill to local .skillkit/methodology/skills directory
|
||||
const skillsDir = join(this.projectPath, '.skillkit', 'methodology', 'skills');
|
||||
const skillDir = join(skillsDir, skill.pack, skill.id.split('/')[1]);
|
||||
|
||||
if (!existsSync(skillDir)) {
|
||||
mkdirSync(skillDir, { recursive: true });
|
||||
}
|
||||
|
||||
const targetPath = join(skillDir, 'SKILL.md');
|
||||
writeFileSync(targetPath, skill.content, 'utf-8');
|
||||
}
|
||||
|
||||
private async removeSkillLocally(_skillId: string): Promise<void> {
|
||||
// Note: We don't delete the skill directory to avoid accidental data loss
|
||||
// The skill is just marked as uninstalled in state
|
||||
// Future enhancement: add optional force delete flag
|
||||
}
|
||||
|
||||
private async writeSkillToAgent(
|
||||
skillId: string,
|
||||
content: string,
|
||||
agent: AgentType
|
||||
): Promise<void> {
|
||||
const agentDirs: Record<string, string> = {
|
||||
'claude-code': '.claude/skills',
|
||||
cursor: '.cursor/skills',
|
||||
codex: '.codex/skills',
|
||||
'gemini-cli': '.gemini/skills',
|
||||
opencode: '.opencode/skills',
|
||||
antigravity: '.antigravity/skills',
|
||||
amp: '.amp/skills',
|
||||
clawdbot: '.clawdbot/skills',
|
||||
droid: '.factory/skills',
|
||||
'github-copilot': '.github/skills',
|
||||
goose: '.goose/skills',
|
||||
kilo: '.kilocode/skills',
|
||||
'kiro-cli': '.kiro/skills',
|
||||
roo: '.roo/skills',
|
||||
trae: '.trae/skills',
|
||||
windsurf: '.windsurf/skills',
|
||||
universal: 'skills',
|
||||
};
|
||||
|
||||
const agentDir = agentDirs[agent];
|
||||
if (!agentDir) {
|
||||
throw new Error(`Unknown agent: ${agent}`);
|
||||
}
|
||||
|
||||
const skillsDir = join(this.projectPath, agentDir);
|
||||
if (!existsSync(skillsDir)) {
|
||||
mkdirSync(skillsDir, { recursive: true });
|
||||
}
|
||||
|
||||
// Determine filename based on agent format
|
||||
const skillName = skillId.split('/')[1];
|
||||
let filename: string;
|
||||
|
||||
if (agent === 'cursor') {
|
||||
filename = `${skillName}.mdc`;
|
||||
} else if (agent === 'github-copilot' || agent === 'windsurf') {
|
||||
filename = `${skillName}.md`;
|
||||
} else {
|
||||
filename = `${skillName}.md`;
|
||||
}
|
||||
|
||||
const targetPath = join(skillsDir, filename);
|
||||
writeFileSync(targetPath, content, 'utf-8');
|
||||
}
|
||||
|
||||
private detectAgents(): AgentType[] {
|
||||
const agents: AgentType[] = [];
|
||||
const agentDirs: [AgentType, string][] = [
|
||||
['claude-code', '.claude'],
|
||||
['cursor', '.cursor'],
|
||||
['codex', '.codex'],
|
||||
['gemini-cli', '.gemini'],
|
||||
['opencode', '.opencode'],
|
||||
['antigravity', '.antigravity'],
|
||||
['amp', '.amp'],
|
||||
['clawdbot', '.clawdbot'],
|
||||
['droid', '.factory'],
|
||||
['github-copilot', '.github'],
|
||||
['goose', '.goose'],
|
||||
['kilo', '.kilocode'],
|
||||
['kiro-cli', '.kiro'],
|
||||
['roo', '.roo'],
|
||||
['trae', '.trae'],
|
||||
['windsurf', '.windsurf'],
|
||||
];
|
||||
|
||||
for (const [agent, dir] of agentDirs) {
|
||||
if (existsSync(join(this.projectPath, dir))) {
|
||||
agents.push(agent);
|
||||
}
|
||||
}
|
||||
|
||||
// Always include universal
|
||||
agents.push('universal');
|
||||
|
||||
return agents;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Create a methodology manager instance
|
||||
*/
|
||||
export function createMethodologyManager(
|
||||
options: MethodologyManagerOptions
|
||||
): MethodologyManager {
|
||||
return new MethodologyManager(options);
|
||||
}
|
||||
@@ -0,0 +1,294 @@
|
||||
---
|
||||
name: Handoff Protocols
|
||||
description: Effectively transfer work context between team members or agents
|
||||
version: 1.0.0
|
||||
triggers:
|
||||
- handoff
|
||||
- pass to
|
||||
- transfer work
|
||||
- take over
|
||||
- continue from
|
||||
- pick up where
|
||||
tags:
|
||||
- collaboration
|
||||
- handoff
|
||||
- communication
|
||||
- context
|
||||
difficulty: beginner
|
||||
estimatedTime: 10
|
||||
relatedSkills:
|
||||
- collaboration/structured-review
|
||||
- collaboration/parallel-investigation
|
||||
---
|
||||
|
||||
# Handoff Protocols
|
||||
|
||||
You are executing a work handoff between team members or agents. A good handoff ensures context is preserved and work continues smoothly without loss of information.
|
||||
|
||||
## Core Principle
|
||||
|
||||
**The recipient should be able to continue work immediately without asking "what were you doing?"**
|
||||
|
||||
A complete handoff transfers not just the work, but the context, decisions, and reasoning.
|
||||
|
||||
## Handoff Types
|
||||
|
||||
### Type 1: Planned Handoff
|
||||
|
||||
Scheduled transfer (end of shift, vacation, role change):
|
||||
|
||||
- Time to prepare comprehensive documentation
|
||||
- Opportunity for sync meeting
|
||||
- Can do gradual transition
|
||||
|
||||
### Type 2: Unplanned Handoff
|
||||
|
||||
Unexpected transfer (illness, emergency, priority change):
|
||||
|
||||
- Limited preparation time
|
||||
- Rely on existing documentation
|
||||
- May need to reconstruct context
|
||||
|
||||
### Type 3: Partial Handoff
|
||||
|
||||
Transfer specific piece while retaining some work:
|
||||
|
||||
- Clear boundary definition
|
||||
- Shared ownership considerations
|
||||
- Integration points defined
|
||||
|
||||
## Handoff Document
|
||||
|
||||
### Essential Sections
|
||||
|
||||
```markdown
|
||||
# Handoff: [Task/Project Name]
|
||||
|
||||
## Quick Summary
|
||||
[One paragraph: What is this and current state]
|
||||
|
||||
## Current Status
|
||||
- [ ] Phase: [Design/Implementation/Testing/etc]
|
||||
- [ ] Progress: [X% complete / Y of Z tasks done]
|
||||
- [ ] Blockers: [Current blockers, if any]
|
||||
- [ ] Next Action: [Very next thing to do]
|
||||
|
||||
## Context
|
||||
|
||||
### What We're Building
|
||||
[Brief description of the goal/feature]
|
||||
|
||||
### Why
|
||||
[Business/technical justification]
|
||||
|
||||
### Key Decisions Made
|
||||
| Decision | Options Considered | Choice | Rationale |
|
||||
|----------|-------------------|--------|-----------|
|
||||
| [D1] | A, B, C | B | [Why B was chosen] |
|
||||
|
||||
### Open Questions
|
||||
- [Question 1]
|
||||
- [Question 2]
|
||||
|
||||
## Technical Details
|
||||
|
||||
### Architecture/Design
|
||||
[Relevant diagrams or links]
|
||||
|
||||
### Key Files
|
||||
- `path/to/file1.ts` - [Purpose]
|
||||
- `path/to/file2.ts` - [Purpose]
|
||||
|
||||
### Dependencies
|
||||
- [Dependency 1]: [How it's used]
|
||||
- [Dependency 2]: [How it's used]
|
||||
|
||||
## Current State of Code
|
||||
|
||||
### What's Complete
|
||||
- [x] [Completed item 1]
|
||||
- [x] [Completed item 2]
|
||||
|
||||
### In Progress
|
||||
- [ ] [In progress item] - [Current state]
|
||||
|
||||
### Not Started
|
||||
- [ ] [Pending item 1]
|
||||
- [ ] [Pending item 2]
|
||||
|
||||
## Known Issues
|
||||
|
||||
### Active Issues
|
||||
- [Issue 1]: [Description and current understanding]
|
||||
|
||||
### Workarounds in Place
|
||||
- [Workaround 1]: [Why it exists, how to remove it]
|
||||
|
||||
## How to Continue
|
||||
|
||||
### Immediate Next Steps
|
||||
1. [Step 1]
|
||||
2. [Step 2]
|
||||
3. [Step 3]
|
||||
|
||||
### Things to Watch Out For
|
||||
- [Gotcha 1]
|
||||
- [Gotcha 2]
|
||||
|
||||
### Who to Contact
|
||||
- [Name/Team] for [Topic]
|
||||
- [Name/Team] for [Topic]
|
||||
|
||||
## Resources
|
||||
- [Link to design doc]
|
||||
- [Link to requirements]
|
||||
- [Link to related PRs]
|
||||
```
|
||||
|
||||
## Handoff Meeting Checklist
|
||||
|
||||
If doing a live handoff:
|
||||
|
||||
**Before Meeting:**
|
||||
- [ ] Prepare handoff document
|
||||
- [ ] Ensure code is in clean state
|
||||
- [ ] List questions you anticipate
|
||||
|
||||
**During Meeting:**
|
||||
1. Walk through handoff document
|
||||
2. Show current state of code
|
||||
3. Demo any working functionality
|
||||
4. Explain key decisions and trade-offs
|
||||
5. Highlight risks and unknowns
|
||||
6. Answer questions
|
||||
7. Verify recipient understands
|
||||
|
||||
**After Meeting:**
|
||||
- [ ] Share access to all resources
|
||||
- [ ] Offer availability for follow-up questions
|
||||
- [ ] Confirm handoff complete
|
||||
|
||||
## Code State Preparation
|
||||
|
||||
Before handing off, ensure:
|
||||
|
||||
```bash
|
||||
# Clean working directory
|
||||
git status # Should be clean
|
||||
|
||||
# Latest changes committed
|
||||
git log -1 # Recent meaningful commit
|
||||
|
||||
# Branch is up to date
|
||||
git pull origin main
|
||||
|
||||
# Tests pass
|
||||
npm test # All green
|
||||
|
||||
# Build works
|
||||
npm run build # No errors
|
||||
```
|
||||
|
||||
Leave the code in a state where:
|
||||
- It compiles/runs
|
||||
- Tests pass
|
||||
- No work-in-progress changes uncommitted
|
||||
- Clear commit messages explain recent changes
|
||||
|
||||
## Communication Templates
|
||||
|
||||
### Async Handoff Message
|
||||
|
||||
```
|
||||
Hi [Name],
|
||||
|
||||
I'm handing off [Task/Project] to you. Here's what you need to know:
|
||||
|
||||
**Status:** [Current state in one sentence]
|
||||
|
||||
**What I've Done:**
|
||||
- [Accomplishment 1]
|
||||
- [Accomplishment 2]
|
||||
|
||||
**Next Steps:**
|
||||
1. [Immediate next action]
|
||||
2. [Following action]
|
||||
|
||||
**Watch Out For:**
|
||||
- [Important gotcha]
|
||||
|
||||
**Resources:**
|
||||
- Handoff doc: [link]
|
||||
- Code: [branch name]
|
||||
- Related PR: [link]
|
||||
|
||||
Let me know if you have questions!
|
||||
```
|
||||
|
||||
### Requesting Additional Context
|
||||
|
||||
```
|
||||
Hi [Name],
|
||||
|
||||
I'm picking up [Task] from your handoff. A few clarifications:
|
||||
|
||||
1. [Specific question 1]
|
||||
2. [Specific question 2]
|
||||
|
||||
Also, I noticed [observation]. Was that intentional?
|
||||
|
||||
Thanks!
|
||||
```
|
||||
|
||||
## Handoff Anti-Patterns
|
||||
|
||||
### The Brain Dump
|
||||
- **Problem:** Unstructured info dump
|
||||
- **Fix:** Use structured handoff document
|
||||
|
||||
### The Ghost
|
||||
- **Problem:** Disappear after handoff
|
||||
- **Fix:** Remain available for questions
|
||||
|
||||
### The Incomplete
|
||||
- **Problem:** Missing critical context
|
||||
- **Fix:** Use checklist, get recipient confirmation
|
||||
|
||||
### The Mess
|
||||
- **Problem:** Code in broken state
|
||||
- **Fix:** Clean up before handoff
|
||||
|
||||
## Receiving a Handoff
|
||||
|
||||
When you receive work:
|
||||
|
||||
1. **Read documentation** before asking questions
|
||||
2. **Acknowledge receipt** to confirm handoff
|
||||
3. **Identify gaps** in your understanding
|
||||
4. **Ask focused questions** about specific unclear points
|
||||
5. **Verify you can build/run** the current state
|
||||
6. **Document** any additional context you discover
|
||||
|
||||
## Handoff Quality Checklist
|
||||
|
||||
For the giver:
|
||||
- [ ] Documentation is complete and current
|
||||
- [ ] Code is in clean, working state
|
||||
- [ ] All access/permissions transferred
|
||||
- [ ] Key contacts introduced
|
||||
- [ ] Questions answered or noted
|
||||
- [ ] Availability for follow-up communicated
|
||||
|
||||
For the receiver:
|
||||
- [ ] Documentation reviewed
|
||||
- [ ] Can build and run the code
|
||||
- [ ] Understand current state
|
||||
- [ ] Know next steps
|
||||
- [ ] Know who to contact
|
||||
- [ ] No blocking questions
|
||||
|
||||
## Integration with Other Skills
|
||||
|
||||
- **structured-review**: Get review before handoff if work is complete
|
||||
- **parallel-investigation**: Handoff individual threads
|
||||
- **planning/task-decomposition**: Reference task breakdown in handoff
|
||||
@@ -0,0 +1,11 @@
|
||||
{
|
||||
"name": "collaboration",
|
||||
"version": "1.0.0",
|
||||
"description": "Collaboration methodology pack with skills for structured code reviews, parallel investigation, and handoff protocols",
|
||||
"skills": ["structured-review", "parallel-investigation", "handoff-protocols"],
|
||||
"tags": ["collaboration", "code-review", "teamwork", "handoff", "communication"],
|
||||
"compatibility": ["all"],
|
||||
"author": "SkillKit Team",
|
||||
"repository": "https://github.com/rohitg00/skillkit",
|
||||
"license": "Apache-2.0"
|
||||
}
|
||||
@@ -0,0 +1,283 @@
|
||||
---
|
||||
name: Parallel Investigation
|
||||
description: Coordinate multiple investigation threads for complex problems
|
||||
version: 1.0.0
|
||||
triggers:
|
||||
- investigate in parallel
|
||||
- multiple approaches
|
||||
- divide investigation
|
||||
- complex problem
|
||||
- explore options
|
||||
tags:
|
||||
- collaboration
|
||||
- investigation
|
||||
- parallel
|
||||
- problem-solving
|
||||
difficulty: advanced
|
||||
estimatedTime: 15
|
||||
relatedSkills:
|
||||
- debugging/root-cause-analysis
|
||||
- collaboration/handoff-protocols
|
||||
---
|
||||
|
||||
# Parallel Investigation
|
||||
|
||||
You are coordinating parallel investigation threads to explore multiple hypotheses or approaches simultaneously. This is effective for complex problems where the root cause is unclear.
|
||||
|
||||
## Core Principle
|
||||
|
||||
**When uncertain, explore multiple paths in parallel. Converge when evidence points to an answer.**
|
||||
|
||||
Parallel investigation reduces time-to-solution for complex problems by eliminating serial bottlenecks.
|
||||
|
||||
## When to Use Parallel Investigation
|
||||
|
||||
Use this methodology when:
|
||||
|
||||
- Root cause is unknown with multiple plausible theories
|
||||
- Problem is complex with many interacting components
|
||||
- Time pressure requires faster resolution
|
||||
- Multiple team members are available
|
||||
- Initial investigation hasn't narrowed down the cause
|
||||
|
||||
Don't use when:
|
||||
- Problem is straightforward
|
||||
- Only one likely cause
|
||||
- Resources are constrained
|
||||
|
||||
## Investigation Structure
|
||||
|
||||
### Phase 1: Problem Decomposition
|
||||
|
||||
Break the problem into independent investigation threads:
|
||||
|
||||
```
|
||||
Problem: API responses are slow
|
||||
|
||||
Investigation Threads:
|
||||
├── Thread A: Database performance
|
||||
│ └── Check slow queries, indexes, connection pool
|
||||
├── Thread B: Application code
|
||||
│ └── Profile endpoint handlers, check for N+1
|
||||
├── Thread C: Infrastructure
|
||||
│ └── Check CPU, memory, network latency
|
||||
└── Thread D: External services
|
||||
└── Check third-party API response times
|
||||
```
|
||||
|
||||
Each thread should be:
|
||||
- Independent (can be investigated without blocking others)
|
||||
- Focused (clear scope and success criteria)
|
||||
- Time-boxed (defined duration before sync)
|
||||
|
||||
### Phase 2: Thread Assignment
|
||||
|
||||
Assign threads with clear ownership:
|
||||
|
||||
```markdown
|
||||
## Thread A: Database Performance
|
||||
**Investigator:** [Name/Agent A]
|
||||
**Duration:** 30 minutes
|
||||
**Scope:**
|
||||
- Query execution times
|
||||
- Index utilization
|
||||
- Connection pool metrics
|
||||
**Report Format:** Summary + evidence
|
||||
|
||||
## Thread B: Application Code
|
||||
**Investigator:** [Name/Agent B]
|
||||
...
|
||||
```
|
||||
|
||||
### Phase 3: Parallel Execution
|
||||
|
||||
Each thread follows this pattern:
|
||||
|
||||
```
|
||||
1. Gather evidence specific to thread scope
|
||||
2. Document findings as you go
|
||||
3. Identify if thread is leading to answer or dead end
|
||||
4. Prepare summary for sync point
|
||||
```
|
||||
|
||||
**Thread Log Template:**
|
||||
```markdown
|
||||
## Thread: [Name]
|
||||
**Start:** [Time]
|
||||
|
||||
### Findings
|
||||
- [Timestamp] [Finding 1]
|
||||
- [Timestamp] [Finding 2]
|
||||
|
||||
### Evidence
|
||||
- [Screenshot/Log/Metric]
|
||||
|
||||
### Preliminary Conclusion
|
||||
[What this thread suggests about the problem]
|
||||
```
|
||||
|
||||
### Phase 4: Sync Points
|
||||
|
||||
Regular convergence to share findings:
|
||||
|
||||
```
|
||||
Sync Point Agenda:
|
||||
1. Thread A report (2 min)
|
||||
2. Thread B report (2 min)
|
||||
3. Thread C report (2 min)
|
||||
4. Thread D report (2 min)
|
||||
5. Discussion & correlation (5 min)
|
||||
6. Decision: Continue, pivot, or converge (3 min)
|
||||
```
|
||||
|
||||
**Sync Point Decisions:**
|
||||
- **Continue**: Threads are progressing, continue parallel
|
||||
- **Pivot**: Redirect threads based on new evidence
|
||||
- **Converge**: One thread found the answer, others join
|
||||
|
||||
### Phase 5: Convergence
|
||||
|
||||
When a thread identifies the likely cause:
|
||||
|
||||
1. **Validate** - Other threads verify the finding
|
||||
2. **Deep dive** - Focused investigation on identified cause
|
||||
3. **Document** - Compile findings from all threads
|
||||
|
||||
## Coordination Patterns
|
||||
|
||||
### Hub and Spoke
|
||||
|
||||
One coordinator, multiple investigators:
|
||||
|
||||
```
|
||||
┌─────────┐
|
||||
│ Hub │
|
||||
│(Coord) │
|
||||
└────┬────┘
|
||||
│
|
||||
┌────────┼────────┐
|
||||
▼ ▼ ▼
|
||||
┌───────┐┌───────┐┌───────┐
|
||||
│Thread ││Thread ││Thread │
|
||||
│ A ││ B ││ C │
|
||||
└───────┘└───────┘└───────┘
|
||||
```
|
||||
|
||||
Coordinator responsibilities:
|
||||
- Assigns threads
|
||||
- Tracks progress
|
||||
- Calls sync points
|
||||
- Makes convergence decisions
|
||||
|
||||
### Peer Network
|
||||
|
||||
Equal investigators sharing findings:
|
||||
|
||||
```
|
||||
┌───────┐ ┌───────┐
|
||||
│Thread │◄───▶│Thread │
|
||||
│ A │ │ B │
|
||||
└───┬───┘ └───┬───┘
|
||||
│ │
|
||||
▼ ▼
|
||||
◄─────────────►
|
||||
Shared
|
||||
Channel
|
||||
```
|
||||
|
||||
Each investigator:
|
||||
- Posts findings to shared channel
|
||||
- Reviews others' findings
|
||||
- Volunteers to converge when pattern emerges
|
||||
|
||||
## Communication Protocol
|
||||
|
||||
### During Investigation
|
||||
|
||||
```
|
||||
[Thread A] [Status] Starting query analysis
|
||||
[Thread B] [Finding] No N+1 patterns in user endpoint
|
||||
[Thread A] [Finding] Slow query: SELECT * FROM orders WHERE...
|
||||
[Thread C] [Dead End] CPU and memory within normal
|
||||
[Thread A] [Hot Lead] Missing index on orders.user_id
|
||||
```
|
||||
|
||||
### At Sync Point
|
||||
|
||||
```markdown
|
||||
## Thread A Summary
|
||||
|
||||
**Status:** Hot Lead
|
||||
**Key Finding:** Missing index on orders.user_id
|
||||
**Evidence:** Query taking 3.2s, explain shows table scan
|
||||
**Recommendation:** This is likely the cause, suggest converge
|
||||
```
|
||||
|
||||
## Decision Framework
|
||||
|
||||
At each sync point:
|
||||
|
||||
| Thread Status | Action |
|
||||
|---------------|--------|
|
||||
| All exploring | Continue parallel |
|
||||
| One hot lead | Validate lead, others support |
|
||||
| Multiple leads | Prioritize by evidence strength |
|
||||
| All dead ends | Reframe problem, new threads |
|
||||
| Confirmed cause | Converge, begin fix |
|
||||
|
||||
## Time Management
|
||||
|
||||
```
|
||||
Hour 1:
|
||||
├── 0:00 - Problem decomposition
|
||||
├── 0:10 - Thread assignment
|
||||
├── 0:15 - Parallel investigation begins
|
||||
├── 0:45 - Sync point #1
|
||||
├── 0:50 - Continue/pivot/converge decision
|
||||
|
||||
Hour 2 (if needed):
|
||||
├── 1:00 - Continue investigation
|
||||
├── 1:30 - Sync point #2
|
||||
├── 1:35 - Final convergence
|
||||
```
|
||||
|
||||
## Documentation
|
||||
|
||||
### Final Report Structure
|
||||
|
||||
```markdown
|
||||
# Investigation: [Problem]
|
||||
|
||||
## Summary
|
||||
[Brief description and resolution]
|
||||
|
||||
## Threads Explored
|
||||
|
||||
### Thread A: [Area]
|
||||
- Investigator: [Name]
|
||||
- Findings: [Summary]
|
||||
- Outcome: [Lead/Dead End/Root Cause]
|
||||
|
||||
### Thread B: [Area]
|
||||
...
|
||||
|
||||
## Root Cause
|
||||
[Detailed explanation of what was found]
|
||||
|
||||
## Evidence
|
||||
- [Evidence 1]
|
||||
- [Evidence 2]
|
||||
|
||||
## Resolution
|
||||
[What was done to fix]
|
||||
|
||||
## Lessons Learned
|
||||
- [Learning 1]
|
||||
- [Learning 2]
|
||||
```
|
||||
|
||||
## Integration with Other Skills
|
||||
|
||||
- **debugging/root-cause-analysis**: Each thread follows RCA principles
|
||||
- **debugging/hypothesis-testing**: Threads test specific hypotheses
|
||||
- **handoff-protocols**: When passing thread to another person
|
||||
@@ -0,0 +1,251 @@
|
||||
---
|
||||
name: Structured Code Review
|
||||
description: Multi-stage code review process for thorough and constructive feedback
|
||||
version: 1.0.0
|
||||
triggers:
|
||||
- code review
|
||||
- review this
|
||||
- feedback on code
|
||||
- PR review
|
||||
- review my changes
|
||||
tags:
|
||||
- collaboration
|
||||
- code-review
|
||||
- quality
|
||||
- feedback
|
||||
difficulty: intermediate
|
||||
estimatedTime: 15
|
||||
relatedSkills:
|
||||
- collaboration/parallel-investigation
|
||||
- planning/verification-gates
|
||||
---
|
||||
|
||||
# Structured Code Review
|
||||
|
||||
You are performing a structured, multi-stage code review. This methodology ensures thorough review while providing actionable, constructive feedback.
|
||||
|
||||
## Core Principle
|
||||
|
||||
**Review in stages. Each stage has a specific focus. Don't mix concerns.**
|
||||
|
||||
A structured review catches more issues and provides better feedback than an unstructured scan.
|
||||
|
||||
## Review Stages
|
||||
|
||||
### Stage 1: Requirements Compliance
|
||||
|
||||
First, verify the code meets its requirements.
|
||||
|
||||
**Questions to Answer:**
|
||||
- Does this implement what was requested?
|
||||
- Are all acceptance criteria met?
|
||||
- Are edge cases handled?
|
||||
- Is scope appropriate (not too little, not too much)?
|
||||
|
||||
**Checklist:**
|
||||
- [ ] Implements stated requirements
|
||||
- [ ] Handles specified edge cases
|
||||
- [ ] No scope creep (unexpected additions)
|
||||
- [ ] No missing functionality
|
||||
|
||||
**Feedback at this stage:**
|
||||
- "This doesn't appear to handle the case when X is empty"
|
||||
- "The requirement specified Y, but this implements Z"
|
||||
- "This adds feature F which wasn't requested - is that intentional?"
|
||||
|
||||
### Stage 2: Correctness
|
||||
|
||||
Next, verify the code works correctly.
|
||||
|
||||
**Questions to Answer:**
|
||||
- Is the logic correct?
|
||||
- Are there bugs or errors?
|
||||
- Are error conditions handled?
|
||||
- Is the code complete?
|
||||
|
||||
**Checklist:**
|
||||
- [ ] Logic is sound
|
||||
- [ ] No obvious bugs
|
||||
- [ ] Error paths are handled
|
||||
- [ ] No unfinished code (TODOs without tickets)
|
||||
|
||||
**Feedback at this stage:**
|
||||
- "This will throw if `user` is null"
|
||||
- "The loop exits early before processing all items"
|
||||
- "What happens when the API call fails?"
|
||||
|
||||
### Stage 3: Code Quality
|
||||
|
||||
Then, evaluate code quality and maintainability.
|
||||
|
||||
**Questions to Answer:**
|
||||
- Is the code readable?
|
||||
- Does it follow conventions?
|
||||
- Is it appropriately simple?
|
||||
- Is it maintainable?
|
||||
|
||||
**Checklist:**
|
||||
- [ ] Clear naming
|
||||
- [ ] Reasonable function/method length
|
||||
- [ ] No unnecessary complexity
|
||||
- [ ] Follows project conventions
|
||||
- [ ] Appropriate abstractions
|
||||
|
||||
**Feedback at this stage:**
|
||||
- "Could you rename `data` to `userProfile` for clarity?"
|
||||
- "This function is doing three things - consider splitting"
|
||||
- "We use camelCase for variables in this project"
|
||||
|
||||
### Stage 4: Testing
|
||||
|
||||
Evaluate test coverage and quality.
|
||||
|
||||
**Questions to Answer:**
|
||||
- Is there adequate test coverage?
|
||||
- Do tests verify the right things?
|
||||
- Are tests maintainable?
|
||||
|
||||
**Checklist:**
|
||||
- [ ] New code has tests
|
||||
- [ ] Tests cover main paths and edge cases
|
||||
- [ ] Tests are readable and maintainable
|
||||
- [ ] Tests don't test implementation details
|
||||
|
||||
**Feedback at this stage:**
|
||||
- "Please add a test for the error case"
|
||||
- "This test will break if we change the implementation"
|
||||
- "Consider using a parameterized test for these cases"
|
||||
|
||||
### Stage 5: Security & Performance
|
||||
|
||||
Finally, check for security and performance concerns.
|
||||
|
||||
**Questions to Answer:**
|
||||
- Are there security vulnerabilities?
|
||||
- Are there performance issues?
|
||||
- Is data handled appropriately?
|
||||
|
||||
**Checklist:**
|
||||
- [ ] No SQL injection, XSS, etc.
|
||||
- [ ] Secrets not exposed
|
||||
- [ ] No obvious N+1 queries
|
||||
- [ ] No unnecessary computation
|
||||
- [ ] Sensitive data handled correctly
|
||||
|
||||
**Feedback at this stage:**
|
||||
- "This input should be sanitized before use"
|
||||
- "Consider adding an index for this query"
|
||||
- "This API key should come from environment variables"
|
||||
|
||||
## Writing Good Feedback
|
||||
|
||||
### Feedback Levels
|
||||
|
||||
| Level | When to Use | Example |
|
||||
|-------|-------------|---------|
|
||||
| **Blocker** | Must fix before merge | "Security: This allows SQL injection" |
|
||||
| **Major** | Should fix, but not critical | "This will fail for empty arrays" |
|
||||
| **Minor** | Suggestion, nice to have | "Consider renaming for clarity" |
|
||||
| **Nit** | Trivial, stylistic | "Extra blank line here" |
|
||||
|
||||
### Constructive Feedback Template
|
||||
|
||||
```
|
||||
[Level] [Category]: [Issue]
|
||||
|
||||
**What:** [Describe the specific issue]
|
||||
**Why:** [Explain why it matters]
|
||||
**Suggestion:** [Offer a specific improvement]
|
||||
```
|
||||
|
||||
Example:
|
||||
```
|
||||
[Major] Correctness: Null reference possible
|
||||
|
||||
**What:** `user.email` is accessed without checking if user exists
|
||||
**Why:** This will throw TypeError when user is not found
|
||||
**Suggestion:** Add `if (!user) return null;` before accessing properties
|
||||
```
|
||||
|
||||
### Feedback Anti-Patterns
|
||||
|
||||
**Don't:**
|
||||
- "This is wrong" (not actionable)
|
||||
- "I would have done it differently" (without explanation)
|
||||
- "Why didn't you...?" (sounds accusatory)
|
||||
- Nitpicking on preferences (not conventions)
|
||||
|
||||
**Do:**
|
||||
- Be specific about the issue
|
||||
- Explain the impact
|
||||
- Offer a solution or alternative
|
||||
- Ask questions to understand intent
|
||||
|
||||
## Review Conversation
|
||||
|
||||
### Responding to Feedback
|
||||
|
||||
When receiving review comments:
|
||||
|
||||
1. **Acknowledge** - Confirm you've read and understood
|
||||
2. **Clarify** if needed - Ask questions if unclear
|
||||
3. **Address** - Make changes or explain why not
|
||||
4. **Resolve** - Mark as resolved when done
|
||||
|
||||
### Disagreeing Constructively
|
||||
|
||||
If you disagree with feedback:
|
||||
|
||||
```
|
||||
I see your point about [X]. In this case, I chose [Y] because [reason].
|
||||
Would you like to discuss further, or is this approach acceptable?
|
||||
```
|
||||
|
||||
## Review Checklist Summary
|
||||
|
||||
```markdown
|
||||
## Review: [PR Title]
|
||||
|
||||
### Stage 1: Requirements
|
||||
- [ ] Implements requirements
|
||||
- [ ] Handles edge cases
|
||||
- [ ] Appropriate scope
|
||||
|
||||
### Stage 2: Correctness
|
||||
- [ ] Logic is sound
|
||||
- [ ] No bugs
|
||||
- [ ] Errors handled
|
||||
|
||||
### Stage 3: Quality
|
||||
- [ ] Readable
|
||||
- [ ] Follows conventions
|
||||
- [ ] Maintainable
|
||||
|
||||
### Stage 4: Testing
|
||||
- [ ] Has tests
|
||||
- [ ] Tests are good
|
||||
|
||||
### Stage 5: Security/Performance
|
||||
- [ ] No vulnerabilities
|
||||
- [ ] No performance issues
|
||||
|
||||
### Verdict: [ ] Approve [ ] Request Changes [ ] Comment
|
||||
```
|
||||
|
||||
## Time Management
|
||||
|
||||
For different PR sizes:
|
||||
|
||||
| Size | Expected Time | Approach |
|
||||
|------|---------------|----------|
|
||||
| Small (< 100 lines) | 10-15 minutes | Full structured review |
|
||||
| Medium (100-300 lines) | 20-30 minutes | Full structured review |
|
||||
| Large (300+ lines) | 45-60 minutes | Consider splitting PR |
|
||||
|
||||
If PR is too large, request it be split before review.
|
||||
|
||||
## Integration with Other Skills
|
||||
|
||||
- **planning/verification-gates**: Review is a key gate
|
||||
- **testing/test-patterns**: Evaluate test quality
|
||||
- **testing/anti-patterns**: Spot testing issues
|
||||
@@ -0,0 +1,262 @@
|
||||
---
|
||||
name: Hypothesis Testing
|
||||
description: Scientific approach to debugging with hypothesis formation and testing
|
||||
version: 1.0.0
|
||||
triggers:
|
||||
- hypothesis
|
||||
- theory about bug
|
||||
- might be caused by
|
||||
- test theory
|
||||
- prove theory
|
||||
tags:
|
||||
- debugging
|
||||
- scientific-method
|
||||
- investigation
|
||||
- validation
|
||||
difficulty: intermediate
|
||||
estimatedTime: 15
|
||||
relatedSkills:
|
||||
- debugging/root-cause-analysis
|
||||
- debugging/trace-and-isolate
|
||||
---
|
||||
|
||||
# Hypothesis-Driven Debugging
|
||||
|
||||
You are applying the scientific method to debugging. Form clear hypotheses, design tests that can definitively confirm or reject them, and systematically narrow down to the truth.
|
||||
|
||||
## Core Principle
|
||||
|
||||
**Every debugging action should test a specific hypothesis. Random changes are not debugging.**
|
||||
|
||||
## The Scientific Debugging Method
|
||||
|
||||
### 1. Observe - Gather Facts
|
||||
|
||||
Before forming hypotheses, collect observations:
|
||||
|
||||
- What exactly happens? (specific symptoms)
|
||||
- When does it happen? (timing, frequency)
|
||||
- Where does it happen? (environment, component)
|
||||
- What changed recently? (code, config, data)
|
||||
|
||||
**Write down observations objectively:**
|
||||
```
|
||||
Observations:
|
||||
- API returns 500 error on POST /orders
|
||||
- Happens only when cart has > 10 items
|
||||
- Started after deployment on 2024-01-15
|
||||
- Works fine in staging environment
|
||||
- Error logs show "connection refused" to inventory service
|
||||
```
|
||||
|
||||
### 2. Hypothesize - Form Testable Theories
|
||||
|
||||
A good hypothesis is:
|
||||
- **Specific** - Points to a particular cause
|
||||
- **Testable** - Can be proven true or false
|
||||
- **Falsifiable** - Possible to prove wrong
|
||||
|
||||
**Bad hypotheses:**
|
||||
- "Something is wrong with the network"
|
||||
- "There might be a race condition"
|
||||
- "The code is buggy"
|
||||
|
||||
**Good hypotheses:**
|
||||
- "The inventory service connection pool is exhausted when processing orders with >10 items"
|
||||
- "The order processing timeout (5s) is insufficient for large orders"
|
||||
- "The new inventory service endpoint (v2) returns different response format"
|
||||
|
||||
### 3. Predict - Define Expected Results
|
||||
|
||||
For each hypothesis, define:
|
||||
- If true, what should we observe?
|
||||
- If false, what should we observe?
|
||||
|
||||
```
|
||||
Hypothesis: Connection pool exhausted for large orders
|
||||
|
||||
If TRUE:
|
||||
- Active connections should hit max (20) during large orders
|
||||
- Small orders should still work during this time
|
||||
- Increasing pool size should fix the issue
|
||||
|
||||
If FALSE:
|
||||
- Connection count stays well below max
|
||||
- Small orders also fail during the issue
|
||||
- Pool size change has no effect
|
||||
```
|
||||
|
||||
### 4. Test - Experiment Systematically
|
||||
|
||||
Design tests that definitively confirm or reject:
|
||||
|
||||
```
|
||||
Test Plan for Connection Pool Hypothesis:
|
||||
|
||||
1. Add connection pool monitoring
|
||||
- Log active connections before/after each request
|
||||
- Expected if true: Count reaches 20 during failures
|
||||
|
||||
2. Artificial stress test
|
||||
- Send 5 large orders simultaneously
|
||||
- Expected if true: Failures start when pool exhausted
|
||||
|
||||
3. Increase pool size to 50
|
||||
- Repeat stress test
|
||||
- Expected if true: Failures stop or threshold moves
|
||||
|
||||
4. Control test with small orders
|
||||
- Send 20 small orders simultaneously
|
||||
- Expected if true: No failures (faster processing)
|
||||
```
|
||||
|
||||
### 5. Analyze - Interpret Results
|
||||
|
||||
After testing:
|
||||
|
||||
- Did results match predictions for TRUE or FALSE?
|
||||
- Are results conclusive or ambiguous?
|
||||
- Do results suggest a different hypothesis?
|
||||
|
||||
```
|
||||
Results:
|
||||
- Connection count reached 20/20 during failures ✓
|
||||
- Small orders succeeded during same period ✓
|
||||
- Pool size increase to 50 → failures stopped ✓
|
||||
|
||||
Conclusion: Hypothesis CONFIRMED
|
||||
Connection pool exhaustion is the proximate cause.
|
||||
|
||||
New question: Why do large orders exhaust the pool?
|
||||
New hypothesis: Large orders make multiple inventory calls per item
|
||||
```
|
||||
|
||||
## Hypothesis Tracking Template
|
||||
|
||||
```markdown
|
||||
## Bug: [Description]
|
||||
|
||||
### Hypothesis 1: [Theory]
|
||||
**Status:** Testing | Confirmed | Rejected
|
||||
**Probability:** High | Medium | Low
|
||||
|
||||
**Evidence For:**
|
||||
- [Evidence 1]
|
||||
- [Evidence 2]
|
||||
|
||||
**Evidence Against:**
|
||||
- [Evidence 1]
|
||||
|
||||
**Test Plan:**
|
||||
1. [Test 1] - Expected result if true
|
||||
2. [Test 2] - Expected result if false
|
||||
|
||||
**Test Results:**
|
||||
- [Result 1]: [Supports/Contradicts]
|
||||
- [Result 2]: [Supports/Contradicts]
|
||||
|
||||
**Conclusion:** [Confirmed/Rejected] because [reasoning]
|
||||
|
||||
---
|
||||
|
||||
### Hypothesis 2: [Next Theory]
|
||||
...
|
||||
```
|
||||
|
||||
## Common Debugging Hypotheses
|
||||
|
||||
### Performance Issues
|
||||
- "Query missing index on column X"
|
||||
- "N+1 query problem in relationship Y"
|
||||
- "Memory leak in component Z"
|
||||
- "Inefficient algorithm (O(n²)) in function F"
|
||||
|
||||
### Data Issues
|
||||
- "Invalid data in field X for certain records"
|
||||
- "Character encoding mismatch (UTF-8 vs Latin-1)"
|
||||
- "Stale cache serving outdated data"
|
||||
- "Race condition corrupting shared state"
|
||||
|
||||
### Configuration Issues
|
||||
- "Environment variable X not set in production"
|
||||
- "Timeout value too low for operation Y"
|
||||
- "Feature flag F enabled in wrong environment"
|
||||
|
||||
### Integration Issues
|
||||
- "API response format changed in version V"
|
||||
- "Certificate expired for service S"
|
||||
- "Rate limiting triggered by usage pattern P"
|
||||
|
||||
## Testing Techniques by Hypothesis Type
|
||||
|
||||
### Testing Timing Hypotheses
|
||||
```typescript
|
||||
// Add timing instrumentation
|
||||
const start = performance.now();
|
||||
await suspectedSlowOperation();
|
||||
const duration = performance.now() - start;
|
||||
console.log(`Operation took ${duration}ms`);
|
||||
// Hypothesis confirmed if duration > expected
|
||||
```
|
||||
|
||||
### Testing Data Hypotheses
|
||||
```typescript
|
||||
// Validate data at key points
|
||||
function processWithValidation(data) {
|
||||
console.assert(data.id != null, 'Missing id');
|
||||
console.assert(data.items?.length > 0, 'Empty items');
|
||||
console.assert(typeof data.total === 'number', 'Invalid total');
|
||||
// If assertions fail, data hypothesis likely true
|
||||
}
|
||||
```
|
||||
|
||||
### Testing State Hypotheses
|
||||
```typescript
|
||||
// Snapshot state before and after
|
||||
const stateBefore = JSON.stringify(currentState);
|
||||
suspectedStateMutation();
|
||||
const stateAfter = JSON.stringify(currentState);
|
||||
if (stateBefore !== stateAfter) {
|
||||
console.log('State changed:', diff(stateBefore, stateAfter));
|
||||
}
|
||||
```
|
||||
|
||||
## Avoiding Hypothesis Bias
|
||||
|
||||
### Confirmation Bias
|
||||
- Don't only look for evidence supporting your favorite theory
|
||||
- Actively try to disprove your hypothesis
|
||||
- Give equal weight to contradicting evidence
|
||||
|
||||
### Anchoring Bias
|
||||
- Don't get stuck on first hypothesis
|
||||
- Be willing to abandon theories that don't fit evidence
|
||||
- Consider alternatives even when one seems likely
|
||||
|
||||
### Premature Closure
|
||||
- Don't stop at first plausible explanation
|
||||
- Verify the hypothesis completely before declaring victory
|
||||
- Consider if there might be multiple causes
|
||||
|
||||
## Decision Tree
|
||||
|
||||
```
|
||||
Is the hypothesis testable?
|
||||
├── NO → Refine it to be more specific
|
||||
└── YES → Can I test it without side effects?
|
||||
├── NO → Design a safe test (staging, logs-only)
|
||||
└── YES → Run the test
|
||||
└── Results conclusive?
|
||||
├── NO → Design a better test
|
||||
└── YES → Hypothesis confirmed or rejected?
|
||||
├── CONFIRMED → Root cause found?
|
||||
│ ├── YES → Fix and verify
|
||||
│ └── NO → Form next hypothesis (why?)
|
||||
└── REJECTED → Form next hypothesis
|
||||
```
|
||||
|
||||
## Integration with Other Skills
|
||||
|
||||
- **root-cause-analysis**: Hypothesis testing is a key technique within RCA
|
||||
- **trace-and-isolate**: Use tracing to gather evidence for hypotheses
|
||||
- **testing/red-green-refactor**: Write test that confirms the bug before fixing
|
||||
@@ -0,0 +1,11 @@
|
||||
{
|
||||
"name": "debugging",
|
||||
"version": "1.0.0",
|
||||
"description": "Systematic debugging methodology pack with skills for root cause analysis, trace isolation, and hypothesis-driven debugging",
|
||||
"skills": ["root-cause-analysis", "trace-and-isolate", "hypothesis-testing"],
|
||||
"tags": ["debugging", "troubleshooting", "investigation", "bug-fixing"],
|
||||
"compatibility": ["all"],
|
||||
"author": "SkillKit Team",
|
||||
"repository": "https://github.com/rohitg00/skillkit",
|
||||
"license": "Apache-2.0"
|
||||
}
|
||||
@@ -0,0 +1,206 @@
|
||||
---
|
||||
name: Root Cause Analysis
|
||||
description: Systematic approach to finding the true source of bugs, not just symptoms
|
||||
version: 1.0.0
|
||||
triggers:
|
||||
- root cause
|
||||
- debugging
|
||||
- find the bug
|
||||
- why is this happening
|
||||
- investigate issue
|
||||
- bug investigation
|
||||
tags:
|
||||
- debugging
|
||||
- investigation
|
||||
- problem-solving
|
||||
- systematic
|
||||
difficulty: intermediate
|
||||
estimatedTime: 20
|
||||
relatedSkills:
|
||||
- debugging/trace-and-isolate
|
||||
- debugging/hypothesis-testing
|
||||
---
|
||||
|
||||
# Root Cause Analysis
|
||||
|
||||
You are performing systematic root cause analysis to find the true source of a bug. Do not apply fixes until you understand WHY the bug exists.
|
||||
|
||||
## Core Principle
|
||||
|
||||
**Never fix a symptom. Always find and fix the root cause.**
|
||||
|
||||
A root cause is the earliest point in the causal chain where intervention could prevent the defect.
|
||||
|
||||
## The Five Whys Method
|
||||
|
||||
Ask "Why?" repeatedly to drill down to the root cause:
|
||||
|
||||
1. **Why** did the API return an error?
|
||||
→ The database query failed
|
||||
2. **Why** did the database query fail?
|
||||
→ The connection timed out
|
||||
3. **Why** did the connection time out?
|
||||
→ The connection pool was exhausted
|
||||
4. **Why** was the connection pool exhausted?
|
||||
→ Connections weren't being released
|
||||
5. **Why** weren't connections being released?
|
||||
→ **ROOT CAUSE:** Missing `finally` block to close connections
|
||||
|
||||
## Investigation Phases
|
||||
|
||||
### Phase 1: Reproduce the Bug
|
||||
|
||||
Before investigating:
|
||||
|
||||
1. **Reproduce consistently** - If you can't reproduce it, you can't verify a fix
|
||||
2. **Document reproduction steps** - Exact sequence of actions
|
||||
3. **Note environment details** - OS, versions, configuration
|
||||
4. **Identify minimal reproduction** - Smallest case that shows the bug
|
||||
|
||||
Questions to answer:
|
||||
- Does it happen every time or intermittently?
|
||||
- Does it happen in all environments?
|
||||
- When did it start happening? (recent changes)
|
||||
|
||||
### Phase 2: Gather Evidence
|
||||
|
||||
Collect information before forming theories:
|
||||
|
||||
```
|
||||
Evidence Types:
|
||||
├── Error messages and stack traces
|
||||
├── Log files (application, system, database)
|
||||
├── Recent code changes (git log, blame)
|
||||
├── User reports and reproduction steps
|
||||
├── Monitoring data (metrics, APM)
|
||||
└── Related issues (search issue tracker)
|
||||
```
|
||||
|
||||
Do NOT:
|
||||
- Make changes while gathering evidence
|
||||
- Assume you know the cause without evidence
|
||||
- Ignore related symptoms
|
||||
|
||||
### Phase 3: Form Hypotheses
|
||||
|
||||
Based on evidence, create ranked hypotheses:
|
||||
|
||||
| Priority | Hypothesis | Evidence | Test Plan |
|
||||
|----------|------------|----------|-----------|
|
||||
| 1 | Connection leak in UserService | Stack trace shows connection pool | Add logging, check usage |
|
||||
| 2 | Query timeout too short | Occurs under load | Test with longer timeout |
|
||||
| 3 | Database server overload | Correlates with peak hours | Check DB metrics |
|
||||
|
||||
For each hypothesis:
|
||||
- What evidence supports it?
|
||||
- What evidence contradicts it?
|
||||
- How can we test it?
|
||||
|
||||
### Phase 4: Test Hypotheses
|
||||
|
||||
Test each hypothesis systematically:
|
||||
|
||||
1. **Start with highest probability**
|
||||
2. **Design a definitive test** - Should clearly confirm or reject
|
||||
3. **Make ONE change at a time**
|
||||
4. **Document results**
|
||||
|
||||
If hypothesis is rejected:
|
||||
- Cross it off the list
|
||||
- Re-evaluate remaining hypotheses
|
||||
- Consider if new evidence suggests new hypotheses
|
||||
|
||||
### Phase 5: Verify Root Cause
|
||||
|
||||
Before declaring root cause found:
|
||||
|
||||
- [ ] Can you explain the full causal chain?
|
||||
- [ ] Does fixing it consistently prevent the bug?
|
||||
- [ ] Does it explain ALL observed symptoms?
|
||||
- [ ] Is there nothing earlier in the chain that could be fixed?
|
||||
|
||||
## Common Root Cause Categories
|
||||
|
||||
### Code Defects
|
||||
- Logic errors
|
||||
- Boundary conditions
|
||||
- Race conditions
|
||||
- Resource leaks
|
||||
- Null/undefined handling
|
||||
|
||||
### Design Issues
|
||||
- Missing error handling
|
||||
- Inadequate validation
|
||||
- Poor state management
|
||||
- Coupling issues
|
||||
|
||||
### Environment
|
||||
- Configuration errors
|
||||
- Resource constraints
|
||||
- Version mismatches
|
||||
- Network issues
|
||||
|
||||
### Data Issues
|
||||
- Invalid input data
|
||||
- Data corruption
|
||||
- Schema mismatches
|
||||
- Encoding problems
|
||||
|
||||
## Evidence Collection Commands
|
||||
|
||||
```bash
|
||||
# Recent changes to relevant files
|
||||
git log --oneline -20 -- path/to/file
|
||||
|
||||
# Who changed this line
|
||||
git blame path/to/file
|
||||
|
||||
# Changes since last working version
|
||||
git diff v1.2.3..HEAD -- src/
|
||||
|
||||
# Search for related error handling
|
||||
grep -r "catch\|error\|throw" --include="*.ts" src/
|
||||
```
|
||||
|
||||
## Red Flags - You Haven't Found Root Cause
|
||||
|
||||
- "I'm not sure why, but this fix works"
|
||||
- "The bug went away after I restarted"
|
||||
- "I added a check to prevent this case"
|
||||
- "It's probably a race condition somewhere"
|
||||
|
||||
These suggest symptom treatment, not root cause resolution.
|
||||
|
||||
## Documentation Template
|
||||
|
||||
When root cause is found, document:
|
||||
|
||||
```markdown
|
||||
## Bug: [Description]
|
||||
|
||||
### Root Cause
|
||||
[Clear explanation of why the bug occurred]
|
||||
|
||||
### Evidence
|
||||
- [Evidence 1]
|
||||
- [Evidence 2]
|
||||
|
||||
### Causal Chain
|
||||
1. [Initial trigger]
|
||||
2. [Intermediate cause]
|
||||
3. [Root cause]
|
||||
4. [Observed symptom]
|
||||
|
||||
### Fix
|
||||
[Description of the fix and why it addresses root cause]
|
||||
|
||||
### Prevention
|
||||
[How to prevent similar issues in the future]
|
||||
```
|
||||
|
||||
## Integration with Other Skills
|
||||
|
||||
After finding root cause:
|
||||
- Use **testing/red-green-refactor** to write a test that exposes the bug
|
||||
- Use **planning/verification-gates** to validate the fix
|
||||
- Consider **collaboration/structured-review** for complex fixes
|
||||
@@ -0,0 +1,282 @@
|
||||
---
|
||||
name: Trace and Isolate
|
||||
description: Techniques for tracing code execution and isolating problematic components
|
||||
version: 1.0.0
|
||||
triggers:
|
||||
- trace execution
|
||||
- isolate bug
|
||||
- narrow down
|
||||
- binary search debugging
|
||||
- find where
|
||||
tags:
|
||||
- debugging
|
||||
- tracing
|
||||
- isolation
|
||||
- bisect
|
||||
difficulty: intermediate
|
||||
estimatedTime: 15
|
||||
relatedSkills:
|
||||
- debugging/root-cause-analysis
|
||||
- debugging/hypothesis-testing
|
||||
---
|
||||
|
||||
# Trace and Isolate
|
||||
|
||||
You are using systematic tracing and isolation techniques to narrow down where a bug originates. The goal is to find the exact location in code where behavior diverges from expectation.
|
||||
|
||||
## Core Principle
|
||||
|
||||
**Divide and conquer. Systematically narrow the search space until you find the exact point of failure.**
|
||||
|
||||
## Binary Search Debugging
|
||||
|
||||
When you have a large codebase or complex flow:
|
||||
|
||||
1. **Identify the start** - Last known good state
|
||||
2. **Identify the end** - First observed bad state
|
||||
3. **Test the middle** - Check if behavior is good or bad
|
||||
4. **Repeat** - Binary search on the half with the bug
|
||||
|
||||
### Code Path Binary Search
|
||||
|
||||
```
|
||||
Start: User clicks submit button
|
||||
End: Error shown to user
|
||||
|
||||
Midpoint 1: Form validation
|
||||
→ Data looks correct here? Continue to later code
|
||||
→ Data already wrong? Focus on earlier code
|
||||
|
||||
Midpoint 2: API request construction
|
||||
→ Request payload correct? Focus on server side
|
||||
→ Payload already malformed? Focus on form handling
|
||||
|
||||
...Continue until exact line is found
|
||||
```
|
||||
|
||||
### Git Bisect for Regressions
|
||||
|
||||
When a bug appeared between two commits:
|
||||
|
||||
```bash
|
||||
# Start bisect
|
||||
git bisect start
|
||||
|
||||
# Mark current (broken) state as bad
|
||||
git bisect bad
|
||||
|
||||
# Mark last known good state
|
||||
git bisect good v2.3.0
|
||||
|
||||
# Git checks out middle commit, test and mark
|
||||
git bisect good # or git bisect bad
|
||||
|
||||
# Repeat until found
|
||||
# Git will report: "abc123 is the first bad commit"
|
||||
|
||||
# Clean up
|
||||
git bisect reset
|
||||
```
|
||||
|
||||
Automated bisect with test script:
|
||||
```bash
|
||||
git bisect start HEAD v2.3.0
|
||||
git bisect run npm test -- --grep "failing test"
|
||||
```
|
||||
|
||||
## Tracing Techniques
|
||||
|
||||
### Strategic Logging
|
||||
|
||||
Add temporary logging at key points:
|
||||
|
||||
```typescript
|
||||
function processOrder(order) {
|
||||
console.log('[TRACE] processOrder input:', JSON.stringify(order));
|
||||
|
||||
const validated = validateOrder(order);
|
||||
console.log('[TRACE] after validation:', JSON.stringify(validated));
|
||||
|
||||
const priced = calculatePrice(validated);
|
||||
console.log('[TRACE] after pricing:', JSON.stringify(priced));
|
||||
|
||||
const result = submitOrder(priced);
|
||||
console.log('[TRACE] final result:', JSON.stringify(result));
|
||||
|
||||
return result;
|
||||
}
|
||||
```
|
||||
|
||||
Log template: `[TRACE] <location>: <what> = <value>`
|
||||
|
||||
### Data Flow Tracing
|
||||
|
||||
Track how data transforms through the system:
|
||||
|
||||
```
|
||||
Input: { userId: "123", items: [...] }
|
||||
↓
|
||||
validateUser() → { userId: "123", verified: true }
|
||||
↓
|
||||
enrichItems() → { userId: "123", verified: true, items: [...enriched] }
|
||||
↓
|
||||
calculateTotals() → { ..., subtotal: 100, tax: 8, total: 108 }
|
||||
↓
|
||||
Output: { orderId: "456", total: 108 }
|
||||
```
|
||||
|
||||
At each step, verify:
|
||||
- Is the input what you expected?
|
||||
- Is the output what you expected?
|
||||
- Where does expected diverge from actual?
|
||||
|
||||
### Control Flow Tracing
|
||||
|
||||
Track which code paths execute:
|
||||
|
||||
```typescript
|
||||
function handleRequest(req) {
|
||||
console.log('[TRACE] handleRequest entered');
|
||||
|
||||
if (req.authenticated) {
|
||||
console.log('[TRACE] authenticated path');
|
||||
if (req.isAdmin) {
|
||||
console.log('[TRACE] admin path');
|
||||
return handleAdminRequest(req);
|
||||
} else {
|
||||
console.log('[TRACE] user path');
|
||||
return handleUserRequest(req);
|
||||
}
|
||||
} else {
|
||||
console.log('[TRACE] unauthenticated path');
|
||||
return handlePublicRequest(req);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Isolation Techniques
|
||||
|
||||
### Component Isolation
|
||||
|
||||
Test components in isolation to determine which is faulty:
|
||||
|
||||
```
|
||||
Full System: Frontend → API → Database
|
||||
↓
|
||||
Test 1: Frontend → Mock API
|
||||
→ Works? Problem is in API or Database
|
||||
|
||||
Test 2: Real API → Mock Database
|
||||
→ Works? Problem is in Database
|
||||
|
||||
Test 3: API with minimal data
|
||||
→ Works? Problem is data-dependent
|
||||
```
|
||||
|
||||
### Minimal Reproduction
|
||||
|
||||
Strip away everything non-essential:
|
||||
|
||||
1. **Remove unrelated code** - Comment out or delete
|
||||
2. **Simplify data** - Use minimal test data
|
||||
3. **Remove dependencies** - Mock external services
|
||||
4. **Reduce scope** - Single function/component
|
||||
|
||||
Goal: Smallest possible code that still shows the bug
|
||||
|
||||
### Environment Isolation
|
||||
|
||||
Eliminate environmental factors:
|
||||
|
||||
- [ ] Same behavior in different browsers?
|
||||
- [ ] Same behavior on different machines?
|
||||
- [ ] Same behavior with fresh data?
|
||||
- [ ] Same behavior after clearing cache?
|
||||
- [ ] Same behavior with default config?
|
||||
|
||||
## Breakpoint Strategies
|
||||
|
||||
### Strategic Breakpoint Placement
|
||||
|
||||
```typescript
|
||||
function complexFunction(input) {
|
||||
// BREAKPOINT 1: Entry - check input
|
||||
const step1 = transform(input);
|
||||
// BREAKPOINT 2: After first transformation
|
||||
|
||||
for (const item of step1.items) {
|
||||
// BREAKPOINT 3: Inside loop - conditional on item
|
||||
process(item);
|
||||
}
|
||||
|
||||
// BREAKPOINT 4: Exit - check output
|
||||
return finalize(step1);
|
||||
}
|
||||
```
|
||||
|
||||
### Conditional Breakpoints
|
||||
|
||||
Only break when condition is met:
|
||||
- `item.id === "problematic-id"`
|
||||
- `count > 100`
|
||||
- `response.status !== 200`
|
||||
|
||||
### Watch Expressions
|
||||
|
||||
Monitor values without stopping:
|
||||
- `this.state.items.length`
|
||||
- `performance.now() - startTime`
|
||||
- `Object.keys(cache).length`
|
||||
|
||||
## Isolation Checklist
|
||||
|
||||
Before declaring a component faulty:
|
||||
|
||||
- [ ] Tested in complete isolation?
|
||||
- [ ] All inputs verified correct?
|
||||
- [ ] All dependencies mocked/verified?
|
||||
- [ ] Tested with known-good data?
|
||||
- [ ] Reproduced on clean environment?
|
||||
|
||||
## Common Isolation Patterns
|
||||
|
||||
### Database Isolation
|
||||
```sql
|
||||
-- Create isolated test data
|
||||
BEGIN TRANSACTION;
|
||||
-- Insert test data
|
||||
-- Run test queries
|
||||
-- Verify results
|
||||
ROLLBACK;
|
||||
```
|
||||
|
||||
### Network Isolation
|
||||
```typescript
|
||||
// Intercept and log all network requests
|
||||
const originalFetch = window.fetch;
|
||||
window.fetch = async (...args) => {
|
||||
console.log('[TRACE] fetch:', args[0]);
|
||||
const response = await originalFetch(...args);
|
||||
console.log('[TRACE] response:', response.status);
|
||||
return response;
|
||||
};
|
||||
```
|
||||
|
||||
### Time Isolation
|
||||
```typescript
|
||||
// Control time for debugging
|
||||
const realNow = Date.now;
|
||||
Date.now = () => {
|
||||
const time = realNow();
|
||||
console.log('[TRACE] Date.now():', new Date(time).toISOString());
|
||||
return time;
|
||||
};
|
||||
```
|
||||
|
||||
## When to Move On
|
||||
|
||||
Stop isolating when you have:
|
||||
- Exact file and line number
|
||||
- Minimal reproduction case
|
||||
- Clear understanding of trigger conditions
|
||||
- Evidence for root cause hypothesis
|
||||
@@ -0,0 +1,11 @@
|
||||
{
|
||||
"name": "meta",
|
||||
"version": "1.0.0",
|
||||
"description": "Meta skills for authoring and managing methodology skills effectively",
|
||||
"skills": ["skill-authoring"],
|
||||
"tags": ["meta", "authoring", "skills", "writing", "documentation"],
|
||||
"compatibility": ["all"],
|
||||
"author": "SkillKit Team",
|
||||
"repository": "https://github.com/rohitg00/skillkit",
|
||||
"license": "Apache-2.0"
|
||||
}
|
||||
@@ -0,0 +1,333 @@
|
||||
---
|
||||
name: Skill Authoring
|
||||
description: Guidelines for writing effective AI agent skills
|
||||
version: 1.0.0
|
||||
triggers:
|
||||
- write a skill
|
||||
- create skill
|
||||
- author skill
|
||||
- skill template
|
||||
- how to write skills
|
||||
tags:
|
||||
- meta
|
||||
- authoring
|
||||
- skills
|
||||
- writing
|
||||
difficulty: intermediate
|
||||
estimatedTime: 20
|
||||
relatedSkills: []
|
||||
---
|
||||
|
||||
# Skill Authoring Guide
|
||||
|
||||
You are authoring a skill for AI coding agents. A well-written skill provides clear, actionable guidance that agents can follow consistently.
|
||||
|
||||
## Core Principle
|
||||
|
||||
**A skill should be the description that triggers it, NOT a summary of the workflow.**
|
||||
|
||||
The trigger/description tells the agent WHEN to use the skill. The content tells the agent HOW to execute it.
|
||||
|
||||
## Skill Anatomy
|
||||
|
||||
### SKILL.md Structure
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: [Human-readable name]
|
||||
description: [What this skill does - for triggers]
|
||||
version: [Semantic version]
|
||||
triggers:
|
||||
- [keyword 1]
|
||||
- [keyword 2]
|
||||
tags:
|
||||
- [tag 1]
|
||||
- [tag 2]
|
||||
difficulty: [beginner|intermediate|advanced]
|
||||
estimatedTime: [minutes]
|
||||
relatedSkills:
|
||||
- [pack/skill-name]
|
||||
---
|
||||
|
||||
# [Skill Title]
|
||||
|
||||
[Introduction paragraph explaining the skill's purpose]
|
||||
|
||||
## Core Principle
|
||||
|
||||
**[Single most important rule in bold]**
|
||||
|
||||
[Brief explanation of why this principle matters]
|
||||
|
||||
## [Main Content Sections]
|
||||
|
||||
[Detailed guidance organized into logical sections]
|
||||
|
||||
## [Decision Points / When to Use]
|
||||
|
||||
[Help the agent know when to apply this skill]
|
||||
|
||||
## [Verification / Checklist]
|
||||
|
||||
[How to verify the skill was applied correctly]
|
||||
```
|
||||
|
||||
### Frontmatter Fields
|
||||
|
||||
| Field | Required | Description |
|
||||
|-------|----------|-------------|
|
||||
| name | Yes | Human-readable skill name |
|
||||
| description | Yes | Brief description (triggers) |
|
||||
| version | Yes | Semantic version (1.0.0) |
|
||||
| triggers | Recommended | Keywords that activate skill |
|
||||
| tags | Recommended | Categorization tags |
|
||||
| difficulty | Optional | beginner/intermediate/advanced |
|
||||
| estimatedTime | Optional | Minutes to apply |
|
||||
| relatedSkills | Optional | Related skill IDs |
|
||||
|
||||
## Writing Effective Triggers
|
||||
|
||||
Triggers should be phrases users naturally type:
|
||||
|
||||
**Good triggers:**
|
||||
- "write tests first"
|
||||
- "tdd"
|
||||
- "test driven development"
|
||||
- "failing test before code"
|
||||
|
||||
**Bad triggers:**
|
||||
- "testing methodology" (too vague)
|
||||
- "red-green-refactor-cycle-for-test-driven-development" (too specific)
|
||||
- "skill-123" (not natural language)
|
||||
|
||||
### Trigger Guidelines
|
||||
|
||||
1. **Natural language** - How would a human ask for this?
|
||||
2. **Multiple variations** - Different ways to say the same thing
|
||||
3. **Specific enough** - Don't trigger on too many queries
|
||||
4. **Common terms** - Use terms people actually use
|
||||
|
||||
## Writing Skill Content
|
||||
|
||||
### Voice and Tone
|
||||
|
||||
Use **second person, present tense, active voice**:
|
||||
|
||||
- "You are implementing TDD"
|
||||
- "Write the test first"
|
||||
- "Verify the output"
|
||||
|
||||
Avoid:
|
||||
- "The developer should..." (passive)
|
||||
- "One might consider..." (vague)
|
||||
- "It is recommended that..." (wordy)
|
||||
|
||||
### Structure Guidelines
|
||||
|
||||
1. **Start with context** - What is the agent doing and why
|
||||
2. **State the core principle** - Most important rule upfront
|
||||
3. **Provide process** - Step-by-step guidance
|
||||
4. **Include examples** - Concrete illustrations
|
||||
5. **Add checklists** - Verification criteria
|
||||
6. **End with integration** - How this connects to other skills
|
||||
|
||||
### Directive Language
|
||||
|
||||
Use clear, unambiguous directives:
|
||||
|
||||
**Strong directives:**
|
||||
- "You MUST..."
|
||||
- "ALWAYS..."
|
||||
- "NEVER..."
|
||||
- "Do NOT..."
|
||||
|
||||
**Softer guidance:**
|
||||
- "Prefer..."
|
||||
- "Consider..."
|
||||
- "When possible..."
|
||||
|
||||
Use strong directives for critical rules, softer guidance for recommendations.
|
||||
|
||||
## Content Patterns
|
||||
|
||||
### Decision Trees
|
||||
|
||||
When the agent needs to choose paths:
|
||||
|
||||
```markdown
|
||||
## Decision: [What to Decide]
|
||||
|
||||
If [condition A]:
|
||||
→ [Action for A]
|
||||
|
||||
If [condition B]:
|
||||
→ [Action for B]
|
||||
|
||||
If uncertain:
|
||||
→ [Default action]
|
||||
```
|
||||
|
||||
### Process Steps
|
||||
|
||||
For sequential workflows:
|
||||
|
||||
```markdown
|
||||
### Step 1: [Action]
|
||||
|
||||
[Detailed explanation]
|
||||
|
||||
**Verification:** [How to know step is complete]
|
||||
|
||||
### Step 2: [Action]
|
||||
...
|
||||
```
|
||||
|
||||
### Tables for Comparisons
|
||||
|
||||
```markdown
|
||||
| Situation | Action | Rationale |
|
||||
|-----------|--------|-----------|
|
||||
| [Case 1] | [Do X] | [Why] |
|
||||
| [Case 2] | [Do Y] | [Why] |
|
||||
```
|
||||
|
||||
### Code Examples
|
||||
|
||||
Show, don't just tell:
|
||||
|
||||
```typescript
|
||||
// BAD - Shows what NOT to do
|
||||
const result = doTheThing(badInput);
|
||||
|
||||
// GOOD - Shows correct approach
|
||||
const validated = validate(input);
|
||||
const result = doTheThing(validated);
|
||||
```
|
||||
|
||||
### Checklists
|
||||
|
||||
For verification:
|
||||
|
||||
```markdown
|
||||
## Verification Checklist
|
||||
|
||||
Before marking complete:
|
||||
|
||||
- [ ] [Criterion 1]
|
||||
- [ ] [Criterion 2]
|
||||
- [ ] [Criterion 3]
|
||||
```
|
||||
|
||||
## Anti-Patterns to Avoid
|
||||
|
||||
### The Encyclopedia
|
||||
|
||||
**Problem:** Too much information, agent gets lost
|
||||
**Fix:** Focus on actionable guidance, link to details
|
||||
|
||||
### The Vague Guide
|
||||
|
||||
**Problem:** "Consider best practices" (What practices?)
|
||||
**Fix:** Be specific: "Use Arrange-Act-Assert pattern"
|
||||
|
||||
### The Constraint-Free Skill
|
||||
|
||||
**Problem:** No clear rules, agent improvises
|
||||
**Fix:** Include explicit constraints and rules
|
||||
|
||||
### The Monologue
|
||||
|
||||
**Problem:** Wall of text with no structure
|
||||
**Fix:** Use headers, lists, tables, code blocks
|
||||
|
||||
### The Outdated Skill
|
||||
|
||||
**Problem:** References deprecated patterns/tools
|
||||
**Fix:** Version skills, include validity dates
|
||||
|
||||
## Skill Testing
|
||||
|
||||
Before publishing, verify:
|
||||
|
||||
1. **Trigger test** - Does it activate on expected phrases?
|
||||
2. **Completeness test** - Can agent follow without external info?
|
||||
3. **Clarity test** - Is every instruction unambiguous?
|
||||
4. **Contradiction test** - No conflicting guidance?
|
||||
5. **Edge case test** - Handles unusual situations?
|
||||
|
||||
### Manual Verification
|
||||
|
||||
```
|
||||
Test Query: "[trigger phrase]"
|
||||
Expected: Skill activates and provides relevant guidance
|
||||
Actual: [Record what happened]
|
||||
```
|
||||
|
||||
## Pack Organization
|
||||
|
||||
Skills should be organized into methodology packs:
|
||||
|
||||
```
|
||||
packs/
|
||||
├── testing/
|
||||
│ ├── pack.json
|
||||
│ ├── red-green-refactor/
|
||||
│ │ └── SKILL.md
|
||||
│ └── test-patterns/
|
||||
│ └── SKILL.md
|
||||
├── debugging/
|
||||
│ ├── pack.json
|
||||
│ └── ...
|
||||
```
|
||||
|
||||
### Pack Manifest
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "testing",
|
||||
"version": "1.0.0",
|
||||
"description": "Testing methodology skills",
|
||||
"skills": ["red-green-refactor", "test-patterns"],
|
||||
"tags": ["testing", "tdd", "quality"],
|
||||
"compatibility": ["all"]
|
||||
}
|
||||
```
|
||||
|
||||
## Skill Maintenance
|
||||
|
||||
### Version Updates
|
||||
|
||||
When to increment version:
|
||||
- **Patch (1.0.x):** Typos, clarifications, minor fixes
|
||||
- **Minor (1.x.0):** New sections, examples, capabilities
|
||||
- **Major (x.0.0):** Breaking changes, fundamental rewrites
|
||||
|
||||
### Deprecation
|
||||
|
||||
If skill becomes obsolete:
|
||||
|
||||
```markdown
|
||||
---
|
||||
deprecated: true
|
||||
deprecatedReason: "Superseded by skill-v2"
|
||||
deprecatedSince: "2024-01-15"
|
||||
---
|
||||
|
||||
> **DEPRECATED:** This skill is deprecated. Use [skill-v2] instead.
|
||||
|
||||
[Original content for reference]
|
||||
```
|
||||
|
||||
## Quality Checklist
|
||||
|
||||
Before publishing:
|
||||
|
||||
- [ ] Frontmatter is complete and valid
|
||||
- [ ] Triggers are natural and specific
|
||||
- [ ] Core principle is clear and prominent
|
||||
- [ ] Content is structured with headers
|
||||
- [ ] Examples are included
|
||||
- [ ] Verification checklist exists
|
||||
- [ ] Related skills are linked
|
||||
- [ ] No spelling/grammar errors
|
||||
- [ ] Tested with target agents
|
||||
@@ -0,0 +1,262 @@
|
||||
---
|
||||
name: Design First
|
||||
description: Think before coding - design the solution before implementing
|
||||
version: 1.0.0
|
||||
triggers:
|
||||
- design first
|
||||
- plan before code
|
||||
- architecture
|
||||
- how should I implement
|
||||
- design document
|
||||
tags:
|
||||
- planning
|
||||
- design
|
||||
- architecture
|
||||
- thinking
|
||||
difficulty: intermediate
|
||||
estimatedTime: 20
|
||||
relatedSkills:
|
||||
- planning/task-decomposition
|
||||
- planning/verification-gates
|
||||
---
|
||||
|
||||
# Design First Methodology
|
||||
|
||||
You are following a design-first approach. Before writing any code, design the solution. This prevents costly rewrites and ensures the implementation meets requirements.
|
||||
|
||||
## Core Principle
|
||||
|
||||
**Think first, code second. A good design makes implementation straightforward.**
|
||||
|
||||
The cost of changing a design is 10x lower than changing code. Invest time in design to save time overall.
|
||||
|
||||
## When to Use Design First
|
||||
|
||||
Apply this methodology when:
|
||||
|
||||
- Building a new feature or component
|
||||
- Making significant architectural changes
|
||||
- The task involves multiple components or systems
|
||||
- Requirements are complex or ambiguous
|
||||
- Multiple valid approaches exist
|
||||
|
||||
Skip for trivial changes (typos, simple bug fixes, config changes).
|
||||
|
||||
## Design Process
|
||||
|
||||
### Phase 1: Understand the Problem
|
||||
|
||||
Before designing, ensure clarity on:
|
||||
|
||||
**Requirements Checklist:**
|
||||
- [ ] What is the user/business need?
|
||||
- [ ] What are the inputs and outputs?
|
||||
- [ ] What are the constraints (performance, security, compatibility)?
|
||||
- [ ] What are the edge cases?
|
||||
- [ ] What are the non-requirements (out of scope)?
|
||||
|
||||
**Questions to Ask:**
|
||||
- What exactly should this do?
|
||||
- What should it NOT do?
|
||||
- How will users interact with it?
|
||||
- How will it integrate with existing systems?
|
||||
- What happens when things go wrong?
|
||||
|
||||
### Phase 2: Explore Options
|
||||
|
||||
Generate multiple approaches before choosing:
|
||||
|
||||
```markdown
|
||||
## Option A: [Approach Name]
|
||||
|
||||
**Description:** [Brief explanation]
|
||||
|
||||
**Pros:**
|
||||
- [Advantage 1]
|
||||
- [Advantage 2]
|
||||
|
||||
**Cons:**
|
||||
- [Disadvantage 1]
|
||||
- [Disadvantage 2]
|
||||
|
||||
**Complexity:** Low/Medium/High
|
||||
|
||||
---
|
||||
|
||||
## Option B: [Approach Name]
|
||||
...
|
||||
```
|
||||
|
||||
Evaluate options against:
|
||||
- Requirements fit
|
||||
- Implementation complexity
|
||||
- Maintenance burden
|
||||
- Performance characteristics
|
||||
- Team familiarity
|
||||
|
||||
### Phase 3: Design the Solution
|
||||
|
||||
Create a design document covering:
|
||||
|
||||
#### System Overview
|
||||
```
|
||||
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
|
||||
│ Client │───▶│ Service │───▶│ Database │
|
||||
└─────────────┘ └─────────────┘ └─────────────┘
|
||||
```
|
||||
|
||||
#### Data Model
|
||||
```typescript
|
||||
interface Order {
|
||||
id: string;
|
||||
customerId: string;
|
||||
items: OrderItem[];
|
||||
status: OrderStatus;
|
||||
createdAt: Date;
|
||||
total: Money;
|
||||
}
|
||||
```
|
||||
|
||||
#### API/Interface Design
|
||||
```typescript
|
||||
// Public interface
|
||||
interface OrderService {
|
||||
createOrder(customerId: string, items: OrderItem[]): Promise<Order>;
|
||||
getOrder(orderId: string): Promise<Order | null>;
|
||||
cancelOrder(orderId: string): Promise<void>;
|
||||
}
|
||||
```
|
||||
|
||||
#### Key Algorithms/Logic
|
||||
```
|
||||
Order Total Calculation:
|
||||
1. Sum item prices (price × quantity)
|
||||
2. Apply discounts (percentage-based first, then fixed)
|
||||
3. Calculate tax (rate based on customer location)
|
||||
4. Add shipping (free over threshold, otherwise flat rate)
|
||||
```
|
||||
|
||||
#### Error Handling
|
||||
- What errors can occur?
|
||||
- How should they be handled?
|
||||
- What should users see?
|
||||
|
||||
### Phase 4: Validate the Design
|
||||
|
||||
Before implementing, validate:
|
||||
|
||||
**Self-Review:**
|
||||
- Does it meet all requirements?
|
||||
- Are there simpler alternatives?
|
||||
- What could go wrong?
|
||||
- Is it testable?
|
||||
|
||||
**External Validation:**
|
||||
- Rubber duck explanation (explain to yourself/others)
|
||||
- Quick review with teammate
|
||||
- Check against similar patterns in codebase
|
||||
|
||||
## Design Document Template
|
||||
|
||||
```markdown
|
||||
# Design: [Feature Name]
|
||||
|
||||
## Overview
|
||||
[One paragraph summary of what we're building and why]
|
||||
|
||||
## Requirements
|
||||
### Functional
|
||||
- [Requirement 1]
|
||||
- [Requirement 2]
|
||||
|
||||
### Non-Functional
|
||||
- [Performance requirement]
|
||||
- [Security requirement]
|
||||
|
||||
## Design
|
||||
|
||||
### Architecture
|
||||
[Diagram and explanation of components]
|
||||
|
||||
### Data Model
|
||||
[Entity definitions and relationships]
|
||||
|
||||
### API Design
|
||||
[Interface definitions]
|
||||
|
||||
### Key Decisions
|
||||
| Decision | Options Considered | Choice | Rationale |
|
||||
|----------|-------------------|--------|-----------|
|
||||
| Database | PostgreSQL, MongoDB | PostgreSQL | Need ACID transactions |
|
||||
|
||||
## Implementation Plan
|
||||
1. [First step]
|
||||
2. [Second step]
|
||||
...
|
||||
|
||||
## Testing Strategy
|
||||
- Unit tests for [X]
|
||||
- Integration tests for [Y]
|
||||
|
||||
## Open Questions
|
||||
- [Question 1]
|
||||
- [Question 2]
|
||||
```
|
||||
|
||||
## Design Levels
|
||||
|
||||
### High-Level Design (Architecture)
|
||||
- System components and their interactions
|
||||
- Data flow between systems
|
||||
- Technology choices
|
||||
- Deployment architecture
|
||||
|
||||
### Mid-Level Design (Module/Component)
|
||||
- Class/module structure
|
||||
- Interfaces and contracts
|
||||
- State management
|
||||
- Error handling strategy
|
||||
|
||||
### Low-Level Design (Implementation)
|
||||
- Algorithm details
|
||||
- Data structures
|
||||
- Method signatures
|
||||
- Edge case handling
|
||||
|
||||
## Anti-Patterns to Avoid
|
||||
|
||||
### Big Design Up Front (BDUF)
|
||||
- Don't over-design every detail
|
||||
- Design enough to start, refine as you learn
|
||||
- Balance planning with doing
|
||||
|
||||
### Analysis Paralysis
|
||||
- Set a time limit for design phase
|
||||
- Make decisions with 70% confidence
|
||||
- Plan to iterate
|
||||
|
||||
### Design in Isolation
|
||||
- Consider existing patterns in codebase
|
||||
- Align with team conventions
|
||||
- Don't reinvent existing solutions
|
||||
|
||||
## Integration with Implementation
|
||||
|
||||
After design is approved:
|
||||
|
||||
1. **Review the design** one more time before coding
|
||||
2. **Break into tasks** using task-decomposition skill
|
||||
3. **Implement incrementally** - verify design assumptions as you code
|
||||
4. **Update design** if you discover issues during implementation
|
||||
|
||||
The design document is living - update it as you learn.
|
||||
|
||||
## Signals You Need More Design
|
||||
|
||||
- "I'm not sure where to start"
|
||||
- "This is getting complicated"
|
||||
- "I keep refactoring"
|
||||
- "The requirements are unclear"
|
||||
- "Multiple approaches seem valid"
|
||||
|
||||
Stop and design before proceeding.
|
||||
@@ -0,0 +1,11 @@
|
||||
{
|
||||
"name": "planning",
|
||||
"version": "1.0.0",
|
||||
"description": "Planning methodology pack with skills for design-first approaches, task decomposition, and verification gates",
|
||||
"skills": ["design-first", "task-decomposition", "verification-gates"],
|
||||
"tags": ["planning", "design", "architecture", "decomposition", "verification"],
|
||||
"compatibility": ["all"],
|
||||
"author": "SkillKit Team",
|
||||
"repository": "https://github.com/rohitg00/skillkit",
|
||||
"license": "Apache-2.0"
|
||||
}
|
||||
@@ -0,0 +1,334 @@
|
||||
---
|
||||
name: Task Decomposition
|
||||
description: Break down complex tasks into small, manageable, atomic units
|
||||
version: 1.0.0
|
||||
triggers:
|
||||
- break down
|
||||
- decompose
|
||||
- split into tasks
|
||||
- too big
|
||||
- where to start
|
||||
- complex task
|
||||
tags:
|
||||
- planning
|
||||
- decomposition
|
||||
- tasks
|
||||
- organization
|
||||
difficulty: beginner
|
||||
estimatedTime: 10
|
||||
relatedSkills:
|
||||
- planning/design-first
|
||||
- planning/verification-gates
|
||||
---
|
||||
|
||||
# Task Decomposition
|
||||
|
||||
You are breaking down a complex task into smaller, atomic units. Each unit should be independently completable and verifiable.
|
||||
|
||||
## Core Principle
|
||||
|
||||
**If a task feels too big, it is too big. Break it down until each piece is obvious.**
|
||||
|
||||
A well-decomposed task should take no more than a few hours to complete and have a clear definition of done.
|
||||
|
||||
## What Makes a Good Atomic Task
|
||||
|
||||
A properly decomposed task is:
|
||||
|
||||
- **Small** - Completable in one focused session
|
||||
- **Independent** - Can be done without blocking on other tasks
|
||||
- **Testable** - Has clear success criteria
|
||||
- **Valuable** - Delivers some increment of value
|
||||
- **Estimatable** - Scope is clear enough to estimate
|
||||
|
||||
**Task Size Targets:**
|
||||
- Ideal: 1-2 hours of focused work
|
||||
- Maximum: Half a day
|
||||
- If larger: Break it down further
|
||||
|
||||
## Decomposition Techniques
|
||||
|
||||
### 1. Vertical Slicing
|
||||
|
||||
Break by user-visible functionality:
|
||||
|
||||
```
|
||||
Feature: User Registration
|
||||
|
||||
Slice 1: Email/password signup
|
||||
- Form renders with email and password fields
|
||||
- Validation shows errors for invalid input
|
||||
- Success creates account and shows confirmation
|
||||
|
||||
Slice 2: Email verification
|
||||
- Sends verification email on signup
|
||||
- Clicking link verifies email
|
||||
- Shows different UI for unverified accounts
|
||||
|
||||
Slice 3: Social login (OAuth)
|
||||
- "Sign in with Google" button
|
||||
- OAuth flow completes
|
||||
- Account linked to Google ID
|
||||
```
|
||||
|
||||
Each slice is deployable and testable independently.
|
||||
|
||||
### 2. Horizontal Layering
|
||||
|
||||
Break by system layer:
|
||||
|
||||
```
|
||||
Feature: Order Processing
|
||||
|
||||
Layer 1: Data Model
|
||||
- Create Order entity
|
||||
- Create OrderItem entity
|
||||
- Add database migrations
|
||||
|
||||
Layer 2: Repository/Data Access
|
||||
- Create OrderRepository
|
||||
- Implement CRUD operations
|
||||
- Add query methods
|
||||
|
||||
Layer 3: Business Logic
|
||||
- Create OrderService
|
||||
- Implement order creation flow
|
||||
- Add validation rules
|
||||
|
||||
Layer 4: API Endpoints
|
||||
- Create POST /orders endpoint
|
||||
- Create GET /orders/:id endpoint
|
||||
- Add error handling
|
||||
|
||||
Layer 5: Frontend Integration
|
||||
- Create order form component
|
||||
- Add API client methods
|
||||
- Handle loading and error states
|
||||
```
|
||||
|
||||
### 3. Workflow Decomposition
|
||||
|
||||
Break by process steps:
|
||||
|
||||
```
|
||||
Task: Implement checkout flow
|
||||
|
||||
Step 1: Cart validation
|
||||
- Verify items are in stock
|
||||
- Validate quantities
|
||||
- Calculate totals
|
||||
|
||||
Step 2: Payment processing
|
||||
- Collect payment details
|
||||
- Validate payment method
|
||||
- Process transaction
|
||||
|
||||
Step 3: Order creation
|
||||
- Create order record
|
||||
- Associate with payment
|
||||
- Update inventory
|
||||
|
||||
Step 4: Confirmation
|
||||
- Send confirmation email
|
||||
- Display success page
|
||||
- Generate invoice
|
||||
```
|
||||
|
||||
### 4. Component Decomposition
|
||||
|
||||
Break by UI or system component:
|
||||
|
||||
```
|
||||
Task: Build dashboard page
|
||||
|
||||
Component 1: Header section
|
||||
- Logo and navigation
|
||||
- User menu dropdown
|
||||
|
||||
Component 2: Stats cards row
|
||||
- Revenue card
|
||||
- Orders card
|
||||
- Customers card
|
||||
|
||||
Component 3: Chart section
|
||||
- Sales trend chart
|
||||
- Data fetching and transformation
|
||||
|
||||
Component 4: Recent orders table
|
||||
- Table with sorting
|
||||
- Pagination
|
||||
- Row actions
|
||||
```
|
||||
|
||||
## Task Template
|
||||
|
||||
For each decomposed task, define:
|
||||
|
||||
```markdown
|
||||
## Task: [Brief Title]
|
||||
|
||||
**Description:**
|
||||
[What needs to be done in 1-2 sentences]
|
||||
|
||||
**Files to Create/Modify:**
|
||||
- [ ] path/to/file1.ts
|
||||
- [ ] path/to/file2.ts
|
||||
|
||||
**Steps:**
|
||||
1. [First specific step]
|
||||
2. [Second specific step]
|
||||
3. [Third specific step]
|
||||
|
||||
**Done When:**
|
||||
- [ ] [Success criterion 1]
|
||||
- [ ] [Success criterion 2]
|
||||
- [ ] Tests pass
|
||||
|
||||
**Dependencies:**
|
||||
- Requires: [Other task if any]
|
||||
- Blocks: [What this enables]
|
||||
```
|
||||
|
||||
## Dependency Management
|
||||
|
||||
### Identify Dependencies
|
||||
|
||||
```
|
||||
Task Graph:
|
||||
|
||||
[Data Model] ──┬──▶ [Repository]
|
||||
│
|
||||
└──▶ [API Types]
|
||||
│
|
||||
[Repository] ──────────▶ [Service]
|
||||
│
|
||||
[API Types] ──────────────────┤
|
||||
▼
|
||||
[API Endpoints]
|
||||
```
|
||||
|
||||
### Minimize Dependencies
|
||||
|
||||
- Prefer tasks that can run in parallel
|
||||
- Use interfaces to decouple dependencies
|
||||
- Start with foundational tasks first
|
||||
|
||||
### Order by Dependencies
|
||||
|
||||
```
|
||||
Phase 1 (No dependencies):
|
||||
- Task A: Data model
|
||||
- Task B: API type definitions
|
||||
- Task C: UI component skeletons
|
||||
|
||||
Phase 2 (Depends on Phase 1):
|
||||
- Task D: Repository (needs A)
|
||||
- Task E: API client (needs B)
|
||||
- Task F: UI logic (needs C)
|
||||
|
||||
Phase 3 (Depends on Phase 2):
|
||||
- Task G: Service (needs D)
|
||||
- Task H: Connected UI (needs E, F)
|
||||
```
|
||||
|
||||
## Decomposition Checklist
|
||||
|
||||
For each task, verify:
|
||||
|
||||
- [ ] **Atomic?** - Can be done without interruption
|
||||
- [ ] **Clear?** - Scope is unambiguous
|
||||
- [ ] **Testable?** - Know when it's done
|
||||
- [ ] **Independent?** - Minimal dependencies
|
||||
- [ ] **Small?** - Less than half a day
|
||||
|
||||
## Signs of Poor Decomposition
|
||||
|
||||
- "This task keeps growing"
|
||||
- "I'm not sure where to start"
|
||||
- "It depends on too many things"
|
||||
- "I can't test it yet"
|
||||
- "This is taking longer than expected"
|
||||
|
||||
When you see these signs, stop and re-decompose.
|
||||
|
||||
## Example: Full Decomposition
|
||||
|
||||
```markdown
|
||||
# Feature: Password Reset
|
||||
|
||||
## Epic Overview
|
||||
Users can reset their forgotten password via email link.
|
||||
|
||||
---
|
||||
|
||||
## Task 1: Password Reset Request API
|
||||
|
||||
**Description:** Create endpoint to request password reset.
|
||||
|
||||
**Files:**
|
||||
- [ ] src/api/auth/reset-request.ts
|
||||
- [ ] src/services/email/templates/reset.html
|
||||
|
||||
**Steps:**
|
||||
1. Create POST /auth/reset-password endpoint
|
||||
2. Validate email exists in database
|
||||
3. Generate secure reset token
|
||||
4. Store token with expiry (1 hour)
|
||||
5. Send email with reset link
|
||||
|
||||
**Done When:**
|
||||
- [ ] Endpoint returns 200 for valid email
|
||||
- [ ] Endpoint returns 200 for invalid email (no leak)
|
||||
- [ ] Email sent with valid token
|
||||
- [ ] Token stored in database
|
||||
|
||||
---
|
||||
|
||||
## Task 2: Password Reset Form UI
|
||||
|
||||
**Description:** Create form for entering new password.
|
||||
|
||||
**Files:**
|
||||
- [ ] src/pages/reset-password.tsx
|
||||
- [ ] src/components/PasswordResetForm.tsx
|
||||
|
||||
**Steps:**
|
||||
1. Create page component at /reset-password?token=X
|
||||
2. Build form with password and confirm fields
|
||||
3. Add password strength validation
|
||||
4. Show loading state during submission
|
||||
|
||||
**Done When:**
|
||||
- [ ] Form renders with token in URL
|
||||
- [ ] Validation shows for weak passwords
|
||||
- [ ] Form submits to API
|
||||
|
||||
---
|
||||
|
||||
## Task 3: Password Reset Complete API
|
||||
|
||||
**Description:** Create endpoint to set new password.
|
||||
|
||||
**Files:**
|
||||
- [ ] src/api/auth/reset-complete.ts
|
||||
|
||||
**Steps:**
|
||||
1. Create POST /auth/reset-password/complete endpoint
|
||||
2. Validate token is valid and not expired
|
||||
3. Hash new password
|
||||
4. Update user record
|
||||
5. Invalidate token
|
||||
6. Return success
|
||||
|
||||
**Done When:**
|
||||
- [ ] Valid token + new password updates user
|
||||
- [ ] Expired token returns error
|
||||
- [ ] Invalid token returns error
|
||||
- [ ] Token cannot be reused
|
||||
```
|
||||
|
||||
## Integration with Other Skills
|
||||
|
||||
- Use **design-first** to understand the full scope before decomposing
|
||||
- Use **verification-gates** to define checkpoints between phases
|
||||
- Use **testing/red-green-refactor** to implement each task
|
||||
@@ -0,0 +1,324 @@
|
||||
---
|
||||
name: Verification Gates
|
||||
description: Define checkpoints to validate work before proceeding to next phase
|
||||
version: 1.0.0
|
||||
triggers:
|
||||
- verify before
|
||||
- checkpoint
|
||||
- quality gate
|
||||
- make sure before
|
||||
- validation
|
||||
tags:
|
||||
- planning
|
||||
- verification
|
||||
- quality
|
||||
- gates
|
||||
difficulty: beginner
|
||||
estimatedTime: 10
|
||||
relatedSkills:
|
||||
- planning/design-first
|
||||
- planning/task-decomposition
|
||||
- testing/red-green-refactor
|
||||
---
|
||||
|
||||
# Verification Gates
|
||||
|
||||
You are implementing verification gates - explicit checkpoints where work is validated before proceeding. This prevents cascading errors and ensures quality at each phase.
|
||||
|
||||
## Core Principle
|
||||
|
||||
**Never proceed to the next phase with unverified assumptions from the previous phase.**
|
||||
|
||||
A verification gate is a deliberate pause to confirm that prerequisites are met before continuing.
|
||||
|
||||
## Why Verification Gates Matter
|
||||
|
||||
Without gates:
|
||||
```
|
||||
Phase 1 → Phase 2 → Phase 3 → Phase 4
|
||||
↑
|
||||
└── Error discovered at Phase 4
|
||||
Must redo Phases 2, 3, 4
|
||||
```
|
||||
|
||||
With gates:
|
||||
```
|
||||
Phase 1 → [Gate] → Phase 2 → [Gate] → Phase 3 → [Gate] → Phase 4
|
||||
↑
|
||||
└── Error caught immediately
|
||||
Only redo Phase 1
|
||||
```
|
||||
|
||||
## Standard Verification Gates
|
||||
|
||||
### Gate 1: Requirements Verification
|
||||
|
||||
Before starting design:
|
||||
|
||||
- [ ] All requirements are documented and clear
|
||||
- [ ] Ambiguities have been resolved with stakeholders
|
||||
- [ ] Non-requirements are explicitly stated
|
||||
- [ ] Acceptance criteria are defined
|
||||
- [ ] Edge cases are identified
|
||||
|
||||
**Actions:**
|
||||
1. Review requirements document
|
||||
2. Identify any unclear items
|
||||
3. Get explicit confirmation on ambiguous points
|
||||
4. Document answers
|
||||
|
||||
### Gate 2: Design Verification
|
||||
|
||||
Before starting implementation:
|
||||
|
||||
- [ ] Design addresses all requirements
|
||||
- [ ] Technical approach is validated
|
||||
- [ ] Interfaces are defined
|
||||
- [ ] Data model is complete
|
||||
- [ ] Error handling is planned
|
||||
- [ ] Design has been reviewed (self or peer)
|
||||
|
||||
**Actions:**
|
||||
1. Walk through design against requirements
|
||||
2. Review with rubber duck or teammate
|
||||
3. Check for missing pieces
|
||||
4. Get approval to proceed
|
||||
|
||||
### Gate 3: Implementation Verification
|
||||
|
||||
Before calling task complete:
|
||||
|
||||
- [ ] Code compiles/runs without errors
|
||||
- [ ] All tests pass
|
||||
- [ ] New code has test coverage
|
||||
- [ ] Code follows project conventions
|
||||
- [ ] No obvious bugs or issues
|
||||
- [ ] Dependencies are appropriate
|
||||
|
||||
**Actions:**
|
||||
1. Run full test suite
|
||||
2. Self-review the diff
|
||||
3. Check for code smells
|
||||
4. Verify against acceptance criteria
|
||||
|
||||
### Gate 4: Integration Verification
|
||||
|
||||
Before merging:
|
||||
|
||||
- [ ] Feature works end-to-end
|
||||
- [ ] Integration tests pass
|
||||
- [ ] No regression in existing functionality
|
||||
- [ ] Performance is acceptable
|
||||
- [ ] Documentation is updated
|
||||
|
||||
**Actions:**
|
||||
1. Test the full user flow
|
||||
2. Run integration test suite
|
||||
3. Compare performance metrics
|
||||
4. Review documentation changes
|
||||
|
||||
### Gate 5: Deployment Verification
|
||||
|
||||
Before marking complete:
|
||||
|
||||
- [ ] Feature works in target environment
|
||||
- [ ] Monitoring shows no errors
|
||||
- [ ] Feature flags are properly configured
|
||||
- [ ] Rollback plan exists
|
||||
- [ ] Stakeholders can verify
|
||||
|
||||
**Actions:**
|
||||
1. Smoke test in environment
|
||||
2. Check error logs and metrics
|
||||
3. Get stakeholder sign-off
|
||||
4. Document deployment
|
||||
|
||||
## Gate Types
|
||||
|
||||
### Automated Gates
|
||||
|
||||
Gates that can be enforced automatically:
|
||||
|
||||
```yaml
|
||||
# CI Pipeline Gates
|
||||
gates:
|
||||
- name: lint
|
||||
command: npm run lint
|
||||
required: true
|
||||
|
||||
- name: type-check
|
||||
command: npm run typecheck
|
||||
required: true
|
||||
|
||||
- name: unit-tests
|
||||
command: npm test
|
||||
required: true
|
||||
coverage: 80%
|
||||
|
||||
- name: build
|
||||
command: npm run build
|
||||
required: true
|
||||
```
|
||||
|
||||
### Manual Gates
|
||||
|
||||
Gates requiring human judgment:
|
||||
|
||||
```markdown
|
||||
## Manual Verification Checklist
|
||||
|
||||
Before Code Review:
|
||||
- [ ] I've tested my changes locally
|
||||
- [ ] I've written/updated tests
|
||||
- [ ] I've read my own diff
|
||||
- [ ] I've checked for security issues
|
||||
- [ ] I've updated documentation
|
||||
|
||||
Before Deployment:
|
||||
- [ ] Code review approved
|
||||
- [ ] QA verified (if applicable)
|
||||
- [ ] Stakeholder approved (if required)
|
||||
- [ ] Deployment plan reviewed
|
||||
```
|
||||
|
||||
### Conditional Gates
|
||||
|
||||
Gates that apply in specific situations:
|
||||
|
||||
| Condition | Required Gates |
|
||||
|-----------|---------------|
|
||||
| Security-related | Security review |
|
||||
| Public API change | API review + migration plan |
|
||||
| Database change | DBA review + backup plan |
|
||||
| Performance-sensitive | Performance test |
|
||||
| Breaking change | Deprecation notice + migration |
|
||||
|
||||
## Implementing Gates
|
||||
|
||||
### In Your Workflow
|
||||
|
||||
```
|
||||
Task Start
|
||||
│
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│ Gate: Prereqs │ ← Verify before starting
|
||||
│ - Requirements │
|
||||
│ - Dependencies │
|
||||
└────────┬────────┘
|
||||
│
|
||||
▼
|
||||
Do the work
|
||||
│
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│ Gate: Completion│ ← Verify before proceeding
|
||||
│ - Tests pass │
|
||||
│ - Code reviewed │
|
||||
└────────┬────────┘
|
||||
│
|
||||
▼
|
||||
Task Complete
|
||||
```
|
||||
|
||||
### Gate Documentation Template
|
||||
|
||||
```markdown
|
||||
## Gate: [Name]
|
||||
|
||||
**When:** [Before what action]
|
||||
|
||||
**Purpose:** [What this gate ensures]
|
||||
|
||||
**Checklist:**
|
||||
- [ ] Item 1
|
||||
- [ ] Item 2
|
||||
- [ ] Item 3
|
||||
|
||||
**Verification Method:**
|
||||
- [How to verify each item]
|
||||
|
||||
**Failure Actions:**
|
||||
- [What to do if gate fails]
|
||||
|
||||
**Approver:** [Who can approve passage]
|
||||
```
|
||||
|
||||
## Common Gate Failures
|
||||
|
||||
### "Just this once" Syndrome
|
||||
- **Problem:** Skipping gates for urgent work
|
||||
- **Fix:** Urgent work gets simpler gates, not no gates
|
||||
|
||||
### Gate Inflation
|
||||
- **Problem:** Too many gates slow everything down
|
||||
- **Fix:** Only gates that catch real issues
|
||||
|
||||
### Rubber Stamp Gates
|
||||
- **Problem:** Gates passed without real verification
|
||||
- **Fix:** Specific checklists, evidence requirements
|
||||
|
||||
## Gate Metrics
|
||||
|
||||
Track gate effectiveness:
|
||||
|
||||
```
|
||||
Gate Effectiveness = Issues caught at gate / Total issues
|
||||
Gate Overhead = Time spent at gates / Total development time
|
||||
Gate Value = (Cost of issue caught early) / (Gate overhead cost)
|
||||
```
|
||||
|
||||
Good gates have:
|
||||
- High effectiveness (catch most issues)
|
||||
- Low overhead (quick to pass)
|
||||
- High value (prevent expensive fixes)
|
||||
|
||||
## Integration with CI/CD
|
||||
|
||||
```yaml
|
||||
# GitHub Actions example
|
||||
jobs:
|
||||
gate-lint:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v3
|
||||
- run: npm ci
|
||||
- run: npm run lint
|
||||
|
||||
gate-test:
|
||||
needs: gate-lint
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v3
|
||||
- run: npm ci
|
||||
- run: npm test
|
||||
|
||||
gate-build:
|
||||
needs: gate-test
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v3
|
||||
- run: npm ci
|
||||
- run: npm run build
|
||||
|
||||
deploy:
|
||||
needs: gate-build
|
||||
# Only deploys if all gates pass
|
||||
```
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Phase | Gate Before | Key Checks |
|
||||
|-------|-------------|------------|
|
||||
| Design | Requirements | Clear, complete, approved |
|
||||
| Implementation | Design | Reviewed, feasible |
|
||||
| Review | Implementation | Tests, conventions, working |
|
||||
| Merge | Review | Approved, conflicts resolved |
|
||||
| Deploy | Merge | Environment ready, plan exists |
|
||||
|
||||
## Integration with Other Skills
|
||||
|
||||
- **design-first**: Gates validate design before implementation
|
||||
- **task-decomposition**: Gates between task phases
|
||||
- **testing/red-green-refactor**: Tests are key gate criteria
|
||||
- **collaboration/structured-review**: Review is a gate
|
||||
@@ -0,0 +1,272 @@
|
||||
---
|
||||
name: Testing Anti-Patterns
|
||||
description: Common testing mistakes to avoid for reliable, maintainable tests
|
||||
version: 1.0.0
|
||||
triggers:
|
||||
- test anti-patterns
|
||||
- testing mistakes
|
||||
- bad tests
|
||||
- flaky tests
|
||||
- test smells
|
||||
tags:
|
||||
- testing
|
||||
- anti-patterns
|
||||
- quality
|
||||
- code-smells
|
||||
difficulty: intermediate
|
||||
estimatedTime: 10
|
||||
relatedSkills:
|
||||
- testing/red-green-refactor
|
||||
- testing/test-patterns
|
||||
---
|
||||
|
||||
# Testing Anti-Patterns
|
||||
|
||||
You are identifying and avoiding common testing anti-patterns. These patterns lead to unreliable tests, false confidence, and maintenance burden.
|
||||
|
||||
## Critical Anti-Patterns
|
||||
|
||||
### 1. The Liar - Tests That Always Pass
|
||||
|
||||
**Problem:** Test passes even when the code is broken.
|
||||
|
||||
```typescript
|
||||
// BAD - Always passes because it tests nothing meaningful
|
||||
it('should process data', () => {
|
||||
const result = processData(input);
|
||||
expect(result).toBeDefined(); // Too weak
|
||||
});
|
||||
|
||||
// GOOD - Actually verifies behavior
|
||||
it('should transform input to uppercase', () => {
|
||||
const result = processData({ text: 'hello' });
|
||||
expect(result.text).toBe('HELLO');
|
||||
});
|
||||
```
|
||||
|
||||
**Detection:** Remove or break the implementation - test should fail.
|
||||
|
||||
### 2. The Giant - Tests Too Large
|
||||
|
||||
**Problem:** Single test covers too many behaviors.
|
||||
|
||||
```typescript
|
||||
// BAD - Tests multiple things
|
||||
it('should handle user registration', async () => {
|
||||
const user = await register(userData);
|
||||
expect(user.id).toBeDefined();
|
||||
expect(user.email).toBe(userData.email);
|
||||
expect(user.password).toBeUndefined();
|
||||
expect(sendEmail).toHaveBeenCalled();
|
||||
expect(createProfile).toHaveBeenCalled();
|
||||
// ... 20 more assertions
|
||||
});
|
||||
|
||||
// GOOD - Focused tests
|
||||
it('should create user with provided email', async () => {
|
||||
const user = await register(userData);
|
||||
expect(user.email).toBe(userData.email);
|
||||
});
|
||||
|
||||
it('should send welcome email on registration', async () => {
|
||||
await register(userData);
|
||||
expect(sendEmail).toHaveBeenCalledWith(
|
||||
expect.objectContaining({ type: 'welcome' })
|
||||
);
|
||||
});
|
||||
```
|
||||
|
||||
**Fix:** One test, one logical assertion concept.
|
||||
|
||||
### 3. The Inspector - Testing Implementation Details
|
||||
|
||||
**Problem:** Test breaks when implementation changes, even if behavior is correct.
|
||||
|
||||
```typescript
|
||||
// BAD - Tests internal implementation
|
||||
it('should use QuickSort for sorting', () => {
|
||||
const sorter = new Sorter();
|
||||
const spy = jest.spyOn(sorter, '_quickSort');
|
||||
sorter.sort([3, 1, 2]);
|
||||
expect(spy).toHaveBeenCalled();
|
||||
});
|
||||
|
||||
// GOOD - Tests behavior/output
|
||||
it('should return sorted array', () => {
|
||||
const sorter = new Sorter();
|
||||
expect(sorter.sort([3, 1, 2])).toEqual([1, 2, 3]);
|
||||
});
|
||||
```
|
||||
|
||||
**Fix:** Test what the code does, not how it does it.
|
||||
|
||||
### 4. The Mockery - Over-Mocking
|
||||
|
||||
**Problem:** Too many mocks make tests meaningless.
|
||||
|
||||
```typescript
|
||||
// BAD - Everything is mocked, test proves nothing
|
||||
it('should calculate price', () => {
|
||||
const mockProduct = { getPrice: jest.fn().mockReturnValue(100) };
|
||||
const mockDiscount = { apply: jest.fn().mockReturnValue(80) };
|
||||
const mockTax = { calculate: jest.fn().mockReturnValue(8) };
|
||||
|
||||
const total = calculateTotal(mockProduct, mockDiscount, mockTax);
|
||||
expect(total).toBe(88); // Just testing mock arithmetic
|
||||
});
|
||||
|
||||
// GOOD - Use real objects where feasible
|
||||
it('should apply 20% discount to price', () => {
|
||||
const product = new Product({ price: 100 });
|
||||
const discount = new PercentageDiscount(20);
|
||||
|
||||
const total = calculateTotal(product, discount);
|
||||
expect(total).toBe(80);
|
||||
});
|
||||
```
|
||||
|
||||
**Fix:** Only mock external dependencies and side effects.
|
||||
|
||||
### 5. The Flaky Test - Random Failures
|
||||
|
||||
**Problem:** Test sometimes passes, sometimes fails.
|
||||
|
||||
Common causes:
|
||||
- **Time-dependent logic**
|
||||
- **Race conditions in async code**
|
||||
- **Shared mutable state**
|
||||
- **External dependencies**
|
||||
|
||||
```typescript
|
||||
// BAD - Depends on current time
|
||||
it('should show recent items', () => {
|
||||
const item = { createdAt: new Date() };
|
||||
expect(isRecent(item)).toBe(true);
|
||||
});
|
||||
|
||||
// GOOD - Control the time
|
||||
it('should show items from last 24 hours', () => {
|
||||
const now = new Date('2024-01-15T12:00:00Z');
|
||||
jest.setSystemTime(now);
|
||||
|
||||
const recent = { createdAt: new Date('2024-01-15T00:00:00Z') };
|
||||
const old = { createdAt: new Date('2024-01-13T00:00:00Z') };
|
||||
|
||||
expect(isRecent(recent)).toBe(true);
|
||||
expect(isRecent(old)).toBe(false);
|
||||
});
|
||||
```
|
||||
|
||||
### 6. The Slow Poke - Unnecessarily Slow Tests
|
||||
|
||||
**Problem:** Tests take too long to run.
|
||||
|
||||
```typescript
|
||||
// BAD - Real network call
|
||||
it('should fetch user data', async () => {
|
||||
const response = await fetch('https://api.example.com/users/1');
|
||||
const user = await response.json();
|
||||
expect(user.name).toBeDefined();
|
||||
});
|
||||
|
||||
// GOOD - Mocked network
|
||||
it('should parse user response', async () => {
|
||||
mockFetch.mockResolvedValue({
|
||||
json: () => Promise.resolve({ id: 1, name: 'Test User' })
|
||||
});
|
||||
|
||||
const user = await fetchUser(1);
|
||||
expect(user.name).toBe('Test User');
|
||||
});
|
||||
```
|
||||
|
||||
**Target:** Unit tests < 100ms, Integration tests < 1s.
|
||||
|
||||
### 7. The Chain Gang - Test Dependency
|
||||
|
||||
**Problem:** Tests depend on other tests running first.
|
||||
|
||||
```typescript
|
||||
// BAD - Tests must run in order
|
||||
describe('User operations', () => {
|
||||
let userId;
|
||||
|
||||
it('should create user', () => {
|
||||
userId = createUser(); // Sets state for next test
|
||||
expect(userId).toBeDefined();
|
||||
});
|
||||
|
||||
it('should update user', () => {
|
||||
updateUser(userId, newData); // Depends on previous test
|
||||
expect(getUser(userId).name).toBe(newData.name);
|
||||
});
|
||||
});
|
||||
|
||||
// GOOD - Each test is independent
|
||||
describe('User operations', () => {
|
||||
it('should create user', () => {
|
||||
const userId = createUser();
|
||||
expect(userId).toBeDefined();
|
||||
});
|
||||
|
||||
it('should update user', () => {
|
||||
const userId = createUser(); // Creates its own user
|
||||
updateUser(userId, newData);
|
||||
expect(getUser(userId).name).toBe(newData.name);
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
### 8. The Secret Catcher - Hidden Test Logic
|
||||
|
||||
**Problem:** Test logic is hidden in helpers or setup.
|
||||
|
||||
```typescript
|
||||
// BAD - Assertions hidden in helper
|
||||
function assertValidUser(user) {
|
||||
expect(user.id).toBeDefined();
|
||||
expect(user.email).toMatch(/@/);
|
||||
expect(user.createdAt).toBeInstanceOf(Date);
|
||||
// Many more hidden assertions
|
||||
}
|
||||
|
||||
it('should create valid user', () => {
|
||||
const user = createUser(data);
|
||||
assertValidUser(user); // What is actually being tested?
|
||||
});
|
||||
|
||||
// GOOD - Explicit assertions
|
||||
it('should create user with email', () => {
|
||||
const user = createUser(data);
|
||||
expect(user.email).toBe(data.email);
|
||||
});
|
||||
```
|
||||
|
||||
## Anti-Pattern Detection Checklist
|
||||
|
||||
When reviewing tests, watch for:
|
||||
|
||||
- [ ] Tests without meaningful assertions
|
||||
- [ ] Tests with more than 5-7 assertions
|
||||
- [ ] Tests that mock everything
|
||||
- [ ] Tests that access private methods/properties
|
||||
- [ ] Tests with sleep/wait calls
|
||||
- [ ] Tests that depend on test execution order
|
||||
- [ ] Tests with complex setup that obscures intent
|
||||
|
||||
## Refactoring Strategies
|
||||
|
||||
1. **Too many assertions** → Split into multiple tests
|
||||
2. **Over-mocking** → Use real implementations or fakes
|
||||
3. **Flaky tests** → Control time, mock external calls
|
||||
4. **Slow tests** → Mock I/O, parallelize independent tests
|
||||
5. **Hidden logic** → Inline or clearly name helpers
|
||||
|
||||
## When to Delete Tests
|
||||
|
||||
Tests that:
|
||||
- Always pass regardless of implementation
|
||||
- Test third-party library behavior
|
||||
- Are permanently flaky without fix
|
||||
- Duplicate other tests exactly
|
||||
- Test deprecated code
|
||||
@@ -0,0 +1,11 @@
|
||||
{
|
||||
"name": "testing",
|
||||
"version": "1.0.0",
|
||||
"description": "Test-driven development methodology pack with skills for RED-GREEN-REFACTOR cycles, testing patterns, and avoiding common anti-patterns",
|
||||
"skills": ["red-green-refactor", "test-patterns", "anti-patterns"],
|
||||
"tags": ["tdd", "testing", "quality", "unit-tests", "integration-tests"],
|
||||
"compatibility": ["all"],
|
||||
"author": "SkillKit Team",
|
||||
"repository": "https://github.com/rohitg00/skillkit",
|
||||
"license": "Apache-2.0"
|
||||
}
|
||||
@@ -0,0 +1,135 @@
|
||||
---
|
||||
name: Red-Green-Refactor
|
||||
description: Test-driven development cycle for writing reliable, well-designed code
|
||||
version: 1.0.0
|
||||
triggers:
|
||||
- tdd
|
||||
- test driven
|
||||
- write tests first
|
||||
- red green refactor
|
||||
- failing test
|
||||
tags:
|
||||
- tdd
|
||||
- testing
|
||||
- quality
|
||||
- methodology
|
||||
difficulty: intermediate
|
||||
estimatedTime: 15
|
||||
relatedSkills:
|
||||
- testing/test-patterns
|
||||
- testing/anti-patterns
|
||||
---
|
||||
|
||||
# Red-Green-Refactor Methodology
|
||||
|
||||
You are following the RED-GREEN-REFACTOR cycle for test-driven development. This methodology ensures code is thoroughly tested and well-designed through iterative cycles.
|
||||
|
||||
## Core Principle
|
||||
|
||||
**Write a failing test BEFORE writing any production code.**
|
||||
|
||||
This is not optional. Every new feature, bug fix, or behavior change starts with a test that demonstrates the requirement.
|
||||
|
||||
## The Cycle
|
||||
|
||||
### 1. RED Phase - Write a Failing Test
|
||||
|
||||
Before writing any implementation:
|
||||
|
||||
1. **Understand the requirement** - What specific behavior needs to exist?
|
||||
2. **Write a test** that asserts this behavior
|
||||
3. **Run the test** - It MUST fail (red)
|
||||
4. **Verify the failure** - Ensure it fails for the right reason, not due to syntax errors
|
||||
|
||||
The test should be:
|
||||
- Focused on ONE specific behavior
|
||||
- Named to describe what is being tested
|
||||
- Using clear assertions with meaningful error messages
|
||||
|
||||
```
|
||||
Example test structure:
|
||||
describe('calculateTotal', () => {
|
||||
it('should apply discount when total exceeds threshold', () => {
|
||||
// Arrange - set up test data
|
||||
// Act - call the function
|
||||
// Assert - verify the result
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
### 2. GREEN Phase - Make the Test Pass
|
||||
|
||||
Write the MINIMUM code necessary to make the test pass:
|
||||
|
||||
1. **Focus on passing**, not perfection
|
||||
2. **Take the simplest path** - Even hardcoding is acceptable initially
|
||||
3. **Do not add features** the test doesn't require
|
||||
4. **Run the test** - It MUST pass (green)
|
||||
|
||||
Guidelines:
|
||||
- If tempted to write more code than needed, STOP
|
||||
- The goal is a passing test, not elegant code
|
||||
- Ugly code is acceptable at this stage
|
||||
|
||||
### 3. REFACTOR Phase - Improve the Code
|
||||
|
||||
With a passing test as your safety net:
|
||||
|
||||
1. **Identify code smells** - Duplication, long methods, unclear names
|
||||
2. **Refactor incrementally** - Small changes, run tests after each
|
||||
3. **Maintain green** - Tests must pass after every change
|
||||
4. **Stop when clean** - Don't over-engineer
|
||||
|
||||
Common refactorings:
|
||||
- Extract method/function
|
||||
- Rename for clarity
|
||||
- Remove duplication
|
||||
- Simplify conditionals
|
||||
|
||||
## Workflow Commands
|
||||
|
||||
When implementing a feature or fix:
|
||||
|
||||
1. **Start with a test file** - Create or update the test file first
|
||||
2. **Write ONE failing test** - Focus on the smallest testable unit
|
||||
3. **Implement minimally** - Just enough to pass
|
||||
4. **Refactor if needed** - Clean up while tests are green
|
||||
5. **Repeat** - Next test for next behavior
|
||||
|
||||
## Decision Points
|
||||
|
||||
### When to Write a New Test
|
||||
- Adding a new feature or behavior
|
||||
- Fixing a bug (test the bug first)
|
||||
- Changing existing behavior
|
||||
- Edge cases discovered during implementation
|
||||
|
||||
### When NOT to Write a Test
|
||||
- Pure refactoring (existing tests cover it)
|
||||
- Non-functional changes (formatting, comments)
|
||||
- Third-party library behavior
|
||||
|
||||
## Verification Checklist
|
||||
|
||||
Before considering work complete:
|
||||
|
||||
- [ ] All new code has corresponding tests
|
||||
- [ ] Tests fail when the feature is removed
|
||||
- [ ] Tests pass consistently (not flaky)
|
||||
- [ ] Code has been refactored for clarity
|
||||
- [ ] No unnecessary code was added
|
||||
|
||||
## Common Mistakes to Avoid
|
||||
|
||||
1. **Writing tests after code** - Defeats the purpose of TDD
|
||||
2. **Writing too many tests at once** - One test at a time
|
||||
3. **Making tests pass with hacks** - The test should drive good design
|
||||
4. **Skipping the refactor phase** - Technical debt accumulates
|
||||
5. **Testing implementation details** - Test behavior, not internals
|
||||
|
||||
## Integration with Other Skills
|
||||
|
||||
This skill works well with:
|
||||
- **test-patterns**: Provides patterns for structuring tests
|
||||
- **anti-patterns**: Helps avoid common testing mistakes
|
||||
- **debugging/root-cause-analysis**: When tests reveal unexpected failures
|
||||
@@ -0,0 +1,240 @@
|
||||
---
|
||||
name: Test Patterns
|
||||
description: Effective patterns for writing maintainable, reliable tests
|
||||
version: 1.0.0
|
||||
triggers:
|
||||
- test patterns
|
||||
- testing best practices
|
||||
- how to write tests
|
||||
- test structure
|
||||
- arrange act assert
|
||||
tags:
|
||||
- testing
|
||||
- patterns
|
||||
- quality
|
||||
- best-practices
|
||||
difficulty: intermediate
|
||||
estimatedTime: 10
|
||||
relatedSkills:
|
||||
- testing/red-green-refactor
|
||||
- testing/anti-patterns
|
||||
---
|
||||
|
||||
# Test Patterns
|
||||
|
||||
You are applying proven testing patterns to write maintainable, reliable tests. These patterns help ensure tests are readable, focused, and trustworthy.
|
||||
|
||||
## Core Pattern: Arrange-Act-Assert (AAA)
|
||||
|
||||
Structure every test with three distinct phases:
|
||||
|
||||
```
|
||||
// Arrange - Set up test data and dependencies
|
||||
const user = createTestUser({ role: 'admin' });
|
||||
const service = new UserService(mockRepository);
|
||||
|
||||
// Act - Execute the code under test
|
||||
const result = await service.updateRole(user.id, 'member');
|
||||
|
||||
// Assert - Verify the expected outcome
|
||||
expect(result.role).toBe('member');
|
||||
expect(mockRepository.save).toHaveBeenCalledWith(user);
|
||||
```
|
||||
|
||||
Guidelines:
|
||||
- Keep sections visually separated (blank lines or comments)
|
||||
- Arrange should be minimal - only what's needed for this test
|
||||
- Act should be a single operation
|
||||
- Assert should verify one logical concept
|
||||
|
||||
## Pattern: Given-When-Then (BDD Style)
|
||||
|
||||
For behavior-focused tests:
|
||||
|
||||
```
|
||||
describe('Shopping Cart', () => {
|
||||
describe('when adding an item', () => {
|
||||
it('should increase the item count', () => {
|
||||
// Given
|
||||
const cart = new Cart();
|
||||
|
||||
// When
|
||||
cart.add({ id: '1', quantity: 2 });
|
||||
|
||||
// Then
|
||||
expect(cart.itemCount).toBe(2);
|
||||
});
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
## Pattern: Test Data Builders
|
||||
|
||||
Create flexible test data without repetition:
|
||||
|
||||
```
|
||||
// Builder function
|
||||
function createTestOrder(overrides = {}) {
|
||||
return {
|
||||
id: 'order-123',
|
||||
status: 'pending',
|
||||
items: [],
|
||||
total: 0,
|
||||
...overrides
|
||||
};
|
||||
}
|
||||
|
||||
// Usage
|
||||
const completedOrder = createTestOrder({ status: 'completed', total: 99.99 });
|
||||
const emptyOrder = createTestOrder({ items: [] });
|
||||
```
|
||||
|
||||
Benefits:
|
||||
- Reduces test setup boilerplate
|
||||
- Makes test intent clearer
|
||||
- Easy to create variations
|
||||
|
||||
## Pattern: Object Mother
|
||||
|
||||
Factory for complex test objects:
|
||||
|
||||
```
|
||||
class TestUserFactory {
|
||||
static admin() {
|
||||
return new User({ role: 'admin', permissions: ALL_PERMISSIONS });
|
||||
}
|
||||
|
||||
static guest() {
|
||||
return new User({ role: 'guest', permissions: [] });
|
||||
}
|
||||
|
||||
static withSubscription(tier) {
|
||||
return new User({ subscription: { tier, active: true } });
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Pattern: Parameterized Tests
|
||||
|
||||
Test multiple cases efficiently:
|
||||
|
||||
```
|
||||
describe('isValidEmail', () => {
|
||||
const validCases = [
|
||||
'user@example.com',
|
||||
'user.name@domain.co.uk',
|
||||
'user+tag@example.org'
|
||||
];
|
||||
|
||||
const invalidCases = [
|
||||
'',
|
||||
'not-an-email',
|
||||
'@no-local.com',
|
||||
'no-domain@'
|
||||
];
|
||||
|
||||
test.each(validCases)('should accept valid email: %s', (email) => {
|
||||
expect(isValidEmail(email)).toBe(true);
|
||||
});
|
||||
|
||||
test.each(invalidCases)('should reject invalid email: %s', (email) => {
|
||||
expect(isValidEmail(email)).toBe(false);
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
## Pattern: Test Fixtures
|
||||
|
||||
Reusable test setup:
|
||||
|
||||
```
|
||||
describe('OrderService', () => {
|
||||
let service;
|
||||
let mockPaymentGateway;
|
||||
let mockInventory;
|
||||
|
||||
beforeEach(() => {
|
||||
mockPaymentGateway = createMockPaymentGateway();
|
||||
mockInventory = createMockInventory();
|
||||
service = new OrderService(mockPaymentGateway, mockInventory);
|
||||
});
|
||||
|
||||
afterEach(() => {
|
||||
jest.clearAllMocks();
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
## Pattern: Spy on Dependencies
|
||||
|
||||
Verify interactions without implementation:
|
||||
|
||||
```
|
||||
it('should send notification on order completion', async () => {
|
||||
const notifySpy = jest.spyOn(notificationService, 'send');
|
||||
|
||||
await orderService.complete(orderId);
|
||||
|
||||
expect(notifySpy).toHaveBeenCalledWith({
|
||||
type: 'order_completed',
|
||||
orderId: orderId
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
## Pattern: Test Doubles
|
||||
|
||||
Choose the right type:
|
||||
|
||||
| Type | Purpose | When to Use |
|
||||
|------|---------|-------------|
|
||||
| **Stub** | Returns canned data | Need predictable inputs |
|
||||
| **Mock** | Verifies interactions | Testing side effects |
|
||||
| **Spy** | Records calls | Partial mocking |
|
||||
| **Fake** | Working implementation | Need realistic behavior |
|
||||
|
||||
## Pattern: Test Isolation
|
||||
|
||||
Ensure tests don't affect each other:
|
||||
|
||||
1. **Fresh instances** - Create new objects in each test
|
||||
2. **Reset mocks** - Clear mock state between tests
|
||||
3. **Clean up** - Remove side effects (files, database rows)
|
||||
4. **No shared mutable state** - Avoid global variables
|
||||
|
||||
## Naming Conventions
|
||||
|
||||
Test names should describe:
|
||||
- What is being tested
|
||||
- Under what conditions
|
||||
- What the expected outcome is
|
||||
|
||||
Good examples:
|
||||
- `shouldReturnEmptyArrayWhenNoItemsExist`
|
||||
- `throwsErrorWhenUserNotAuthenticated`
|
||||
- `calculatesDiscountForPremiumMembers`
|
||||
|
||||
## Test Organization
|
||||
|
||||
```
|
||||
src/
|
||||
services/
|
||||
UserService.ts
|
||||
UserService.test.ts # Co-located tests
|
||||
|
||||
tests/
|
||||
integration/
|
||||
api.test.ts # Integration tests
|
||||
e2e/
|
||||
checkout.spec.ts # End-to-end tests
|
||||
```
|
||||
|
||||
## Verification Checklist
|
||||
|
||||
For each test:
|
||||
- [ ] Single responsibility (tests one thing)
|
||||
- [ ] Clear AAA or GWT structure
|
||||
- [ ] Descriptive name
|
||||
- [ ] Fast execution (< 100ms for unit tests)
|
||||
- [ ] Deterministic (no flakiness)
|
||||
- [ ] Independent (runs in any order)
|
||||
@@ -0,0 +1,223 @@
|
||||
/**
|
||||
* Methodology Framework Types
|
||||
*
|
||||
* Defines types for methodology packs, skills, and the management system.
|
||||
* SkillKit's methodology framework is composable, community-driven, and
|
||||
* methodology-agnostic (supports TDD, BDD, DDD, or custom approaches).
|
||||
*/
|
||||
|
||||
import type { AgentType } from '../types.js';
|
||||
|
||||
/**
|
||||
* Methodology pack manifest - defines a collection of related skills
|
||||
*/
|
||||
export interface MethodologyPack {
|
||||
/** Pack name (e.g., 'testing', 'debugging') */
|
||||
name: string;
|
||||
/** Semantic version */
|
||||
version: string;
|
||||
/** Human-readable description */
|
||||
description: string;
|
||||
/** Skills included in this pack */
|
||||
skills: string[];
|
||||
/** Tags for discovery */
|
||||
tags: string[];
|
||||
/** Agent compatibility ('all' or specific agents) */
|
||||
compatibility: ('all' | AgentType)[];
|
||||
/** Author information */
|
||||
author?: string;
|
||||
/** Repository/homepage URL */
|
||||
repository?: string;
|
||||
/** License */
|
||||
license?: string;
|
||||
/** Pack dependencies (other packs) */
|
||||
dependencies?: string[];
|
||||
}
|
||||
|
||||
/**
|
||||
* Methodology skill - a skill within a methodology pack
|
||||
*/
|
||||
export interface MethodologySkill {
|
||||
/** Unique skill identifier */
|
||||
id: string;
|
||||
/** Human-readable name */
|
||||
name: string;
|
||||
/** Skill description */
|
||||
description: string;
|
||||
/** Skill version */
|
||||
version: string;
|
||||
/** Parent pack name */
|
||||
pack: string;
|
||||
/** Tags for discovery */
|
||||
tags: string[];
|
||||
/** File path to SKILL.md content */
|
||||
path: string;
|
||||
/** Raw SKILL.md content */
|
||||
content: string;
|
||||
/** Skill metadata from frontmatter */
|
||||
metadata: MethodologySkillMetadata;
|
||||
}
|
||||
|
||||
/**
|
||||
* Skill metadata from SKILL.md frontmatter
|
||||
*/
|
||||
export interface MethodologySkillMetadata {
|
||||
/** Skill triggers/keywords for activation */
|
||||
triggers?: string[];
|
||||
/** Related skills that work well together */
|
||||
relatedSkills?: string[];
|
||||
/** Difficulty level */
|
||||
difficulty?: 'beginner' | 'intermediate' | 'advanced';
|
||||
/** Estimated time to apply (in minutes) */
|
||||
estimatedTime?: number;
|
||||
/** Prerequisites (other skills or knowledge) */
|
||||
prerequisites?: string[];
|
||||
/** Custom metadata */
|
||||
[key: string]: unknown;
|
||||
}
|
||||
|
||||
/**
|
||||
* Installed methodology state
|
||||
*/
|
||||
export interface MethodologyState {
|
||||
/** State format version */
|
||||
version: number;
|
||||
/** Installed packs */
|
||||
installedPacks: Record<string, InstalledPackInfo>;
|
||||
/** Installed skills (for individual skill installs) */
|
||||
installedSkills: Record<string, InstalledSkillInfo>;
|
||||
/** Last sync timestamp */
|
||||
lastSync?: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* Information about an installed pack
|
||||
*/
|
||||
export interface InstalledPackInfo {
|
||||
/** Pack version */
|
||||
version: string;
|
||||
/** Installation timestamp */
|
||||
installedAt: string;
|
||||
/** Skills installed from this pack */
|
||||
skills: string[];
|
||||
/** Whether auto-sync is enabled */
|
||||
autoSync?: boolean;
|
||||
}
|
||||
|
||||
/**
|
||||
* Information about an installed skill
|
||||
*/
|
||||
export interface InstalledSkillInfo {
|
||||
/** Skill version */
|
||||
version: string;
|
||||
/** Pack name (if installed from pack) */
|
||||
pack?: string;
|
||||
/** Installation timestamp */
|
||||
installedAt: string;
|
||||
/** Agents synced to */
|
||||
syncedAgents: AgentType[];
|
||||
}
|
||||
|
||||
/**
|
||||
* Options for methodology manager
|
||||
*/
|
||||
export interface MethodologyManagerOptions {
|
||||
/** Project path */
|
||||
projectPath: string;
|
||||
/** Custom packs directory */
|
||||
packsDir?: string;
|
||||
/** Whether to auto-sync on install */
|
||||
autoSync?: boolean;
|
||||
}
|
||||
|
||||
/**
|
||||
* Result of pack/skill installation
|
||||
*/
|
||||
export interface InstallResult {
|
||||
/** Whether installation succeeded */
|
||||
success: boolean;
|
||||
/** Installed items */
|
||||
installed: string[];
|
||||
/** Skipped items (already installed) */
|
||||
skipped: string[];
|
||||
/** Failed items with error messages */
|
||||
failed: Array<{ name: string; error: string }>;
|
||||
}
|
||||
|
||||
/**
|
||||
* Result of skill sync operation
|
||||
*/
|
||||
export interface MethodologySyncResult {
|
||||
/** Whether sync succeeded */
|
||||
success: boolean;
|
||||
/** Skills synced */
|
||||
synced: Array<{ skill: string; agents: AgentType[] }>;
|
||||
/** Skills that failed to sync */
|
||||
failed: Array<{ skill: string; agent: AgentType; error: string }>;
|
||||
}
|
||||
|
||||
/**
|
||||
* Pack validation result
|
||||
*/
|
||||
export interface ValidationResult {
|
||||
/** Whether validation passed */
|
||||
valid: boolean;
|
||||
/** Validation errors */
|
||||
errors: ValidationError[];
|
||||
/** Validation warnings */
|
||||
warnings: ValidationWarning[];
|
||||
}
|
||||
|
||||
/**
|
||||
* Validation error
|
||||
*/
|
||||
export interface ValidationError {
|
||||
/** Error code */
|
||||
code: string;
|
||||
/** Error message */
|
||||
message: string;
|
||||
/** Path to the problematic item */
|
||||
path?: string;
|
||||
/** Line number (if applicable) */
|
||||
line?: number;
|
||||
}
|
||||
|
||||
/**
|
||||
* Validation warning
|
||||
*/
|
||||
export interface ValidationWarning {
|
||||
/** Warning code */
|
||||
code: string;
|
||||
/** Warning message */
|
||||
message: string;
|
||||
/** Recommendation */
|
||||
recommendation?: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* Methodology search query
|
||||
*/
|
||||
export interface MethodologySearchQuery {
|
||||
/** Search term */
|
||||
query?: string;
|
||||
/** Filter by tags */
|
||||
tags?: string[];
|
||||
/** Filter by pack name */
|
||||
pack?: string;
|
||||
/** Filter by difficulty */
|
||||
difficulty?: MethodologySkillMetadata['difficulty'];
|
||||
/** Filter by agent compatibility */
|
||||
agent?: AgentType;
|
||||
}
|
||||
|
||||
/**
|
||||
* Methodology search result
|
||||
*/
|
||||
export interface MethodologySearchResult {
|
||||
/** Matching skills */
|
||||
skills: MethodologySkill[];
|
||||
/** Matching packs */
|
||||
packs: MethodologyPack[];
|
||||
/** Total count */
|
||||
total: number;
|
||||
}
|
||||
@@ -0,0 +1,391 @@
|
||||
/**
|
||||
* Methodology Validator
|
||||
*
|
||||
* Validates methodology packs and skills for correctness and completeness.
|
||||
*/
|
||||
|
||||
import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
|
||||
import { join } from 'node:path';
|
||||
import type {
|
||||
MethodologyPack,
|
||||
ValidationResult,
|
||||
ValidationError,
|
||||
ValidationWarning,
|
||||
} from './types.js';
|
||||
|
||||
/**
|
||||
* Validates a methodology pack manifest
|
||||
*/
|
||||
export function validatePackManifest(pack: unknown): ValidationResult {
|
||||
const errors: ValidationError[] = [];
|
||||
const warnings: ValidationWarning[] = [];
|
||||
|
||||
// Type check
|
||||
if (!pack || typeof pack !== 'object') {
|
||||
errors.push({
|
||||
code: 'INVALID_TYPE',
|
||||
message: 'Pack manifest must be an object',
|
||||
});
|
||||
return { valid: false, errors, warnings };
|
||||
}
|
||||
|
||||
const p = pack as Record<string, unknown>;
|
||||
|
||||
// Required fields
|
||||
if (!p.name || typeof p.name !== 'string') {
|
||||
errors.push({
|
||||
code: 'MISSING_NAME',
|
||||
message: 'Pack must have a "name" field (string)',
|
||||
});
|
||||
} else if (!/^[a-z][a-z0-9-]*$/.test(p.name)) {
|
||||
errors.push({
|
||||
code: 'INVALID_NAME',
|
||||
message: 'Pack name must be lowercase, start with a letter, and contain only a-z, 0-9, and hyphens',
|
||||
});
|
||||
}
|
||||
|
||||
if (!p.version || typeof p.version !== 'string') {
|
||||
errors.push({
|
||||
code: 'MISSING_VERSION',
|
||||
message: 'Pack must have a "version" field (string)',
|
||||
});
|
||||
} else if (!/^\d+\.\d+\.\d+/.test(p.version)) {
|
||||
errors.push({
|
||||
code: 'INVALID_VERSION',
|
||||
message: 'Pack version must follow semver (e.g., "1.0.0")',
|
||||
});
|
||||
}
|
||||
|
||||
if (!p.description || typeof p.description !== 'string') {
|
||||
errors.push({
|
||||
code: 'MISSING_DESCRIPTION',
|
||||
message: 'Pack must have a "description" field (string)',
|
||||
});
|
||||
} else if (p.description.length < 10) {
|
||||
warnings.push({
|
||||
code: 'SHORT_DESCRIPTION',
|
||||
message: 'Pack description should be at least 10 characters',
|
||||
recommendation: 'Add a more detailed description to help users understand the pack',
|
||||
});
|
||||
}
|
||||
|
||||
if (!p.skills || !Array.isArray(p.skills)) {
|
||||
errors.push({
|
||||
code: 'MISSING_SKILLS',
|
||||
message: 'Pack must have a "skills" array',
|
||||
});
|
||||
} else if (p.skills.length === 0) {
|
||||
errors.push({
|
||||
code: 'EMPTY_SKILLS',
|
||||
message: 'Pack must contain at least one skill',
|
||||
});
|
||||
} else {
|
||||
for (const skill of p.skills) {
|
||||
if (typeof skill !== 'string') {
|
||||
errors.push({
|
||||
code: 'INVALID_SKILL_ENTRY',
|
||||
message: `Skill entries must be strings, found: ${typeof skill}`,
|
||||
});
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
if (!p.tags || !Array.isArray(p.tags)) {
|
||||
warnings.push({
|
||||
code: 'MISSING_TAGS',
|
||||
message: 'Pack should have a "tags" array for better discoverability',
|
||||
recommendation: 'Add relevant tags like "tdd", "testing", "debugging"',
|
||||
});
|
||||
}
|
||||
|
||||
if (!p.compatibility || !Array.isArray(p.compatibility)) {
|
||||
warnings.push({
|
||||
code: 'MISSING_COMPATIBILITY',
|
||||
message: 'Pack should specify agent compatibility',
|
||||
recommendation: 'Add "compatibility": ["all"] for universal support',
|
||||
});
|
||||
}
|
||||
|
||||
return {
|
||||
valid: errors.length === 0,
|
||||
errors,
|
||||
warnings,
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Validates SKILL.md content
|
||||
*/
|
||||
export function validateSkillContent(content: string): ValidationResult {
|
||||
const errors: ValidationError[] = [];
|
||||
const warnings: ValidationWarning[] = [];
|
||||
|
||||
if (!content || content.trim().length === 0) {
|
||||
errors.push({
|
||||
code: 'EMPTY_CONTENT',
|
||||
message: 'Skill content cannot be empty',
|
||||
});
|
||||
return { valid: false, errors, warnings };
|
||||
}
|
||||
|
||||
const lines = content.split('\n');
|
||||
|
||||
// Check for frontmatter
|
||||
const hasFrontmatter = lines[0] === '---';
|
||||
if (hasFrontmatter) {
|
||||
const frontmatterEnd = lines.slice(1).findIndex((l) => l === '---');
|
||||
if (frontmatterEnd === -1) {
|
||||
errors.push({
|
||||
code: 'UNCLOSED_FRONTMATTER',
|
||||
message: 'Frontmatter opened but not closed',
|
||||
line: 1,
|
||||
});
|
||||
}
|
||||
} else {
|
||||
warnings.push({
|
||||
code: 'NO_FRONTMATTER',
|
||||
message: 'Skill should have YAML frontmatter with metadata',
|
||||
recommendation: 'Add frontmatter with triggers, tags, and description',
|
||||
});
|
||||
}
|
||||
|
||||
// Check for required sections
|
||||
const hasDescription = /^#+\s*(Description|Overview)/im.test(content);
|
||||
const hasInstructions = /^#+\s*(Instructions|Workflow|Steps|Process)/im.test(content);
|
||||
|
||||
if (!hasDescription && !hasInstructions) {
|
||||
warnings.push({
|
||||
code: 'MISSING_STRUCTURE',
|
||||
message: 'Skill should have clear sections (Description, Instructions)',
|
||||
recommendation: 'Structure skill with ## Description and ## Instructions sections',
|
||||
});
|
||||
}
|
||||
|
||||
// Check minimum content length
|
||||
const contentWithoutFrontmatter = content
|
||||
.replace(/^---[\s\S]*?---/, '')
|
||||
.trim();
|
||||
if (contentWithoutFrontmatter.length < 100) {
|
||||
warnings.push({
|
||||
code: 'SHORT_CONTENT',
|
||||
message: 'Skill content seems brief',
|
||||
recommendation: 'Provide detailed instructions for AI agents to follow',
|
||||
});
|
||||
}
|
||||
|
||||
// Check for actionable instructions
|
||||
const hasActionableContent =
|
||||
/\b(must|should|always|never|do not|ensure|verify|check|create|implement)\b/i.test(
|
||||
content
|
||||
);
|
||||
if (!hasActionableContent) {
|
||||
warnings.push({
|
||||
code: 'NO_ACTIONABLE_CONTENT',
|
||||
message: 'Skill may lack clear actionable instructions',
|
||||
recommendation: 'Include directive language (must, should, always, never) for AI agents',
|
||||
});
|
||||
}
|
||||
|
||||
return {
|
||||
valid: errors.length === 0,
|
||||
errors,
|
||||
warnings,
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Validates a pack directory structure
|
||||
*/
|
||||
export function validatePackDirectory(packPath: string): ValidationResult {
|
||||
const errors: ValidationError[] = [];
|
||||
const warnings: ValidationWarning[] = [];
|
||||
|
||||
// Check directory exists
|
||||
if (!existsSync(packPath)) {
|
||||
errors.push({
|
||||
code: 'DIR_NOT_FOUND',
|
||||
message: `Pack directory not found: ${packPath}`,
|
||||
});
|
||||
return { valid: false, errors, warnings };
|
||||
}
|
||||
|
||||
// Check pack.json exists
|
||||
const manifestPath = join(packPath, 'pack.json');
|
||||
if (!existsSync(manifestPath)) {
|
||||
errors.push({
|
||||
code: 'MANIFEST_NOT_FOUND',
|
||||
message: 'Pack must have a pack.json manifest',
|
||||
path: manifestPath,
|
||||
});
|
||||
return { valid: false, errors, warnings };
|
||||
}
|
||||
|
||||
// Validate manifest
|
||||
let manifest: MethodologyPack;
|
||||
try {
|
||||
const raw = readFileSync(manifestPath, 'utf-8');
|
||||
manifest = JSON.parse(raw);
|
||||
const manifestResult = validatePackManifest(manifest);
|
||||
errors.push(...manifestResult.errors);
|
||||
warnings.push(...manifestResult.warnings);
|
||||
} catch (e) {
|
||||
errors.push({
|
||||
code: 'INVALID_MANIFEST',
|
||||
message: `Failed to parse pack.json: ${e instanceof Error ? e.message : 'Unknown error'}`,
|
||||
path: manifestPath,
|
||||
});
|
||||
return { valid: false, errors, warnings };
|
||||
}
|
||||
|
||||
// Check skill directories
|
||||
if (manifest.skills) {
|
||||
for (const skillName of manifest.skills) {
|
||||
const skillDir = join(packPath, skillName);
|
||||
|
||||
if (!existsSync(skillDir)) {
|
||||
errors.push({
|
||||
code: 'SKILL_DIR_NOT_FOUND',
|
||||
message: `Skill directory not found: ${skillName}`,
|
||||
path: skillDir,
|
||||
});
|
||||
continue;
|
||||
}
|
||||
|
||||
if (!statSync(skillDir).isDirectory()) {
|
||||
errors.push({
|
||||
code: 'SKILL_NOT_DIRECTORY',
|
||||
message: `Skill must be a directory: ${skillName}`,
|
||||
path: skillDir,
|
||||
});
|
||||
continue;
|
||||
}
|
||||
|
||||
// Check SKILL.md exists
|
||||
const skillFile = join(skillDir, 'SKILL.md');
|
||||
if (!existsSync(skillFile)) {
|
||||
errors.push({
|
||||
code: 'SKILL_FILE_NOT_FOUND',
|
||||
message: `Skill must have a SKILL.md file: ${skillName}`,
|
||||
path: skillFile,
|
||||
});
|
||||
continue;
|
||||
}
|
||||
|
||||
// Validate skill content
|
||||
const skillContent = readFileSync(skillFile, 'utf-8');
|
||||
const skillResult = validateSkillContent(skillContent);
|
||||
for (const err of skillResult.errors) {
|
||||
errors.push({
|
||||
...err,
|
||||
path: skillFile,
|
||||
});
|
||||
}
|
||||
for (const warn of skillResult.warnings) {
|
||||
warnings.push({
|
||||
...warn,
|
||||
code: `${skillName}:${warn.code}`,
|
||||
});
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return {
|
||||
valid: errors.length === 0,
|
||||
errors,
|
||||
warnings,
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Validates all built-in packs
|
||||
*/
|
||||
export function validateBuiltinPacks(packsDir: string): Map<string, ValidationResult> {
|
||||
const results = new Map<string, ValidationResult>();
|
||||
|
||||
if (!existsSync(packsDir)) {
|
||||
return results;
|
||||
}
|
||||
|
||||
const packDirs = readdirSync(packsDir).filter((name) => {
|
||||
const packPath = join(packsDir, name);
|
||||
return statSync(packPath).isDirectory();
|
||||
});
|
||||
|
||||
for (const packName of packDirs) {
|
||||
const packPath = join(packsDir, packName);
|
||||
results.set(packName, validatePackDirectory(packPath));
|
||||
}
|
||||
|
||||
return results;
|
||||
}
|
||||
|
||||
/**
|
||||
* Extract skill metadata from SKILL.md frontmatter
|
||||
*/
|
||||
export function extractSkillMetadata(content: string): Record<string, unknown> {
|
||||
const metadata: Record<string, unknown> = {};
|
||||
|
||||
const lines = content.split('\n');
|
||||
if (lines[0] !== '---') {
|
||||
return metadata;
|
||||
}
|
||||
|
||||
const frontmatterEnd = lines.slice(1).findIndex((l) => l === '---');
|
||||
if (frontmatterEnd === -1) {
|
||||
return metadata;
|
||||
}
|
||||
|
||||
const frontmatterLines = lines.slice(1, frontmatterEnd + 1);
|
||||
let currentKey: string | null = null;
|
||||
let currentArrayValues: string[] = [];
|
||||
let inArray = false;
|
||||
|
||||
for (const line of frontmatterLines) {
|
||||
// Handle array items
|
||||
if (inArray && line.startsWith(' - ')) {
|
||||
currentArrayValues.push(line.slice(4).trim());
|
||||
continue;
|
||||
}
|
||||
|
||||
// Close array
|
||||
if (inArray && !line.startsWith(' - ')) {
|
||||
if (currentKey) {
|
||||
metadata[currentKey] = currentArrayValues;
|
||||
}
|
||||
inArray = false;
|
||||
currentArrayValues = [];
|
||||
currentKey = null;
|
||||
}
|
||||
|
||||
// Key: value pairs
|
||||
const match = line.match(/^([a-zA-Z_][a-zA-Z0-9_]*)\s*:\s*(.*)$/);
|
||||
if (match) {
|
||||
const [, key, value] = match;
|
||||
if (value.trim() === '') {
|
||||
// Start of array
|
||||
currentKey = key;
|
||||
inArray = true;
|
||||
currentArrayValues = [];
|
||||
} else if (value.startsWith('[') && value.endsWith(']')) {
|
||||
// Inline array
|
||||
metadata[key] = value
|
||||
.slice(1, -1)
|
||||
.split(',')
|
||||
.map((v) => v.trim().replace(/^['"]|['"]$/g, ''));
|
||||
} else if (value === 'true' || value === 'false') {
|
||||
metadata[key] = value === 'true';
|
||||
} else if (/^\d+$/.test(value)) {
|
||||
metadata[key] = parseInt(value, 10);
|
||||
} else {
|
||||
metadata[key] = value.replace(/^['"]|['"]$/g, '');
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Handle final array
|
||||
if (inArray && currentKey) {
|
||||
metadata[currentKey] = currentArrayValues;
|
||||
}
|
||||
|
||||
return metadata;
|
||||
}
|
||||
@@ -0,0 +1,591 @@
|
||||
/**
|
||||
* Team Orchestration Tests
|
||||
*/
|
||||
|
||||
import { describe, it, expect, beforeEach } from 'vitest';
|
||||
import { TaskManager, createTaskManager } from '../task.js';
|
||||
import { TeamMessageBus, createMessageBus } from '../messages.js';
|
||||
import { TeamOrchestrator, createTeamOrchestrator } from '../team.js';
|
||||
import type { Task, TaskPlan, TeamMessage } from '../types.js';
|
||||
|
||||
describe('TaskManager', () => {
|
||||
let manager: TaskManager;
|
||||
|
||||
beforeEach(() => {
|
||||
manager = createTaskManager();
|
||||
});
|
||||
|
||||
describe('createTask', () => {
|
||||
it('should create a task with generated ID', () => {
|
||||
const task = manager.createTask(
|
||||
'Implement feature',
|
||||
'Add login functionality',
|
||||
'Full specification here...'
|
||||
);
|
||||
|
||||
expect(task.id).toBeDefined();
|
||||
expect(task.name).toBe('Implement feature');
|
||||
expect(task.description).toBe('Add login functionality');
|
||||
expect(task.spec).toBe('Full specification here...');
|
||||
expect(task.status).toBe('pending');
|
||||
});
|
||||
|
||||
it('should create a task with options', () => {
|
||||
const task = manager.createTask(
|
||||
'Test task',
|
||||
'Description',
|
||||
'Spec',
|
||||
{
|
||||
files: { create: ['src/new.ts'], modify: ['src/existing.ts'] },
|
||||
priority: 5,
|
||||
dependencies: ['dep-1'],
|
||||
}
|
||||
);
|
||||
|
||||
expect(task.files.create).toEqual(['src/new.ts']);
|
||||
expect(task.files.modify).toEqual(['src/existing.ts']);
|
||||
expect(task.priority).toBe(5);
|
||||
expect(task.dependencies).toEqual(['dep-1']);
|
||||
});
|
||||
});
|
||||
|
||||
describe('assignTask', () => {
|
||||
it('should assign a task to an agent', () => {
|
||||
const task = manager.createTask('Task', 'Desc', 'Spec');
|
||||
const assigned = manager.assignTask(task.id, 'agent-1');
|
||||
|
||||
expect(assigned?.assignee).toBe('agent-1');
|
||||
expect(assigned?.status).toBe('assigned');
|
||||
});
|
||||
|
||||
it('should fail if task has unfinished dependencies', () => {
|
||||
const dep = manager.createTask('Dependency', 'Desc', 'Spec');
|
||||
const task = manager.createTask('Task', 'Desc', 'Spec', {
|
||||
dependencies: [dep.id],
|
||||
});
|
||||
|
||||
expect(() => manager.assignTask(task.id, 'agent-1')).toThrow('unfinished or missing dependencies');
|
||||
});
|
||||
|
||||
it('should allow assignment when dependencies are complete', () => {
|
||||
const dep = manager.createTask('Dependency', 'Desc', 'Spec');
|
||||
manager.completeTask(dep.id, {
|
||||
success: true,
|
||||
output: 'Done',
|
||||
completedAt: new Date(),
|
||||
});
|
||||
|
||||
const task = manager.createTask('Task', 'Desc', 'Spec', {
|
||||
dependencies: [dep.id],
|
||||
});
|
||||
const assigned = manager.assignTask(task.id, 'agent-1');
|
||||
|
||||
expect(assigned?.status).toBe('assigned');
|
||||
});
|
||||
});
|
||||
|
||||
describe('submitPlan', () => {
|
||||
it('should submit a plan for a task', () => {
|
||||
const task = manager.createTask('Task', 'Desc', 'Spec');
|
||||
manager.assignTask(task.id, 'agent-1');
|
||||
|
||||
const plan: Omit<TaskPlan, 'submittedAt'> = {
|
||||
steps: [
|
||||
{ number: 1, description: 'Write tests', type: 'test' },
|
||||
{ number: 2, description: 'Implement', type: 'implement' },
|
||||
],
|
||||
estimatedMinutes: 10,
|
||||
};
|
||||
|
||||
const updated = manager.submitPlan(task.id, plan);
|
||||
|
||||
expect(updated?.plan).toBeDefined();
|
||||
expect(updated?.plan?.steps).toHaveLength(2);
|
||||
expect(updated?.status).toBe('plan_pending');
|
||||
});
|
||||
});
|
||||
|
||||
describe('approvePlan / rejectPlan', () => {
|
||||
it('should approve a plan', () => {
|
||||
const task = manager.createTask('Task', 'Desc', 'Spec');
|
||||
manager.assignTask(task.id, 'agent-1');
|
||||
manager.submitPlan(task.id, {
|
||||
steps: [{ number: 1, description: 'Step', type: 'implement' }],
|
||||
});
|
||||
|
||||
const approved = manager.approvePlan(task.id, 'leader-1');
|
||||
|
||||
expect(approved?.status).toBe('approved');
|
||||
expect(approved?.plan?.approvedBy).toBe('leader-1');
|
||||
expect(approved?.plan?.approvedAt).toBeDefined();
|
||||
});
|
||||
|
||||
it('should reject a plan with reason', () => {
|
||||
const task = manager.createTask('Task', 'Desc', 'Spec');
|
||||
manager.assignTask(task.id, 'agent-1');
|
||||
manager.submitPlan(task.id, {
|
||||
steps: [{ number: 1, description: 'Step', type: 'implement' }],
|
||||
});
|
||||
|
||||
const rejected = manager.rejectPlan(task.id, 'Missing tests');
|
||||
|
||||
expect(rejected?.status).toBe('planning');
|
||||
expect(rejected?.plan?.rejectionReason).toBe('Missing tests');
|
||||
});
|
||||
});
|
||||
|
||||
describe('completeTask / failTask', () => {
|
||||
it('should complete a task successfully', () => {
|
||||
const task = manager.createTask('Task', 'Desc', 'Spec');
|
||||
manager.assignTask(task.id, 'agent-1');
|
||||
manager.startTask(task.id);
|
||||
|
||||
const completed = manager.completeTask(task.id, {
|
||||
success: true,
|
||||
output: 'Feature implemented',
|
||||
filesCreated: ['src/feature.ts'],
|
||||
completedAt: new Date(),
|
||||
});
|
||||
|
||||
expect(completed?.status).toBe('completed');
|
||||
expect(completed?.result?.success).toBe(true);
|
||||
});
|
||||
|
||||
it('should fail a task', () => {
|
||||
const task = manager.createTask('Task', 'Desc', 'Spec');
|
||||
const failed = manager.failTask(task.id, ['Build failed', 'Tests failed']);
|
||||
|
||||
expect(failed?.status).toBe('failed');
|
||||
expect(failed?.result?.success).toBe(false);
|
||||
expect(failed?.result?.errors).toEqual(['Build failed', 'Tests failed']);
|
||||
});
|
||||
});
|
||||
|
||||
describe('getNextTask', () => {
|
||||
it('should return highest priority pending task', () => {
|
||||
manager.createTask('Low priority', 'Desc', 'Spec', { priority: 1 });
|
||||
manager.createTask('High priority', 'Desc', 'Spec', { priority: 10 });
|
||||
manager.createTask('Medium priority', 'Desc', 'Spec', { priority: 5 });
|
||||
|
||||
const next = manager.getNextTask();
|
||||
expect(next?.name).toBe('High priority');
|
||||
});
|
||||
|
||||
it('should respect dependencies', () => {
|
||||
const dep = manager.createTask('Dependency', 'Desc', 'Spec', { priority: 1 });
|
||||
manager.createTask('Blocked task', 'Desc', 'Spec', {
|
||||
priority: 10,
|
||||
dependencies: [dep.id],
|
||||
});
|
||||
|
||||
const next = manager.getNextTask();
|
||||
expect(next?.name).toBe('Dependency');
|
||||
});
|
||||
});
|
||||
|
||||
describe('getStats', () => {
|
||||
it('should return correct stats', () => {
|
||||
manager.createTask('Task 1', 'Desc', 'Spec');
|
||||
manager.createTask('Task 2', 'Desc', 'Spec');
|
||||
const task3 = manager.createTask('Task 3', 'Desc', 'Spec');
|
||||
manager.completeTask(task3.id, {
|
||||
success: true,
|
||||
output: 'Done',
|
||||
completedAt: new Date(),
|
||||
});
|
||||
|
||||
const stats = manager.getStats();
|
||||
|
||||
expect(stats.total).toBe(3);
|
||||
expect(stats.pending).toBe(2);
|
||||
expect(stats.completed).toBe(1);
|
||||
});
|
||||
});
|
||||
|
||||
describe('event listeners', () => {
|
||||
it('should emit task events', () => {
|
||||
const events: string[] = [];
|
||||
manager.addListener((event) => {
|
||||
events.push(event);
|
||||
});
|
||||
|
||||
const task = manager.createTask('Task', 'Desc', 'Spec');
|
||||
manager.assignTask(task.id, 'agent-1');
|
||||
manager.submitPlan(task.id, { steps: [] });
|
||||
manager.approvePlan(task.id, 'leader');
|
||||
manager.startTask(task.id);
|
||||
manager.completeTask(task.id, { success: true, output: '', completedAt: new Date() });
|
||||
|
||||
expect(events).toContain('task:created');
|
||||
expect(events).toContain('task:assigned');
|
||||
expect(events).toContain('task:plan_submitted');
|
||||
expect(events).toContain('task:plan_approved');
|
||||
expect(events).toContain('task:started');
|
||||
expect(events).toContain('task:completed');
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
describe('TeamMessageBus', () => {
|
||||
let bus: TeamMessageBus;
|
||||
|
||||
beforeEach(() => {
|
||||
bus = createMessageBus();
|
||||
});
|
||||
|
||||
describe('send', () => {
|
||||
it('should send a direct message', async () => {
|
||||
const message = await bus.send('agent-1', 'agent-2', 'Hello');
|
||||
|
||||
expect(message.type).toBe('direct');
|
||||
expect(message.from).toBe('agent-1');
|
||||
expect(message.to).toBe('agent-2');
|
||||
expect(message.content).toBe('Hello');
|
||||
});
|
||||
|
||||
it('should notify registered handlers', async () => {
|
||||
let received: TeamMessage | null = null;
|
||||
bus.registerHandler('agent-2', (msg) => {
|
||||
received = msg;
|
||||
});
|
||||
|
||||
await bus.send('agent-1', 'agent-2', 'Test message');
|
||||
|
||||
expect(received).not.toBeNull();
|
||||
expect(received?.content).toBe('Test message');
|
||||
});
|
||||
});
|
||||
|
||||
describe('broadcast', () => {
|
||||
it('should broadcast to all agents', async () => {
|
||||
const messages: TeamMessage[] = [];
|
||||
bus.registerHandler('agent-1', (msg) => messages.push(msg));
|
||||
bus.registerHandler('agent-2', (msg) => messages.push(msg));
|
||||
bus.registerHandler('agent-3', (msg) => messages.push(msg));
|
||||
|
||||
await bus.broadcast('leader', 'Team announcement');
|
||||
|
||||
expect(messages.length).toBe(3);
|
||||
expect(messages.every((m) => m.type === 'broadcast')).toBe(true);
|
||||
});
|
||||
|
||||
it('should not send to the sender', async () => {
|
||||
let received = false;
|
||||
bus.registerHandler('leader', () => {
|
||||
received = true;
|
||||
});
|
||||
|
||||
await bus.broadcast('leader', 'Message');
|
||||
|
||||
expect(received).toBe(false);
|
||||
});
|
||||
});
|
||||
|
||||
describe('plan workflow', () => {
|
||||
it('should submit and approve plans', async () => {
|
||||
const messages: TeamMessage[] = [];
|
||||
bus.registerGlobalHandler((msg) => messages.push(msg));
|
||||
|
||||
await bus.submitPlan('agent-1', 'leader', 'task-1', 'Plan summary');
|
||||
await bus.approvePlan('leader', 'agent-1', 'task-1', 'Looks good');
|
||||
|
||||
expect(messages.length).toBe(2);
|
||||
expect(messages[0].type).toBe('plan_submit');
|
||||
expect(messages[1].type).toBe('plan_approve');
|
||||
});
|
||||
|
||||
it('should reject plans with reason', async () => {
|
||||
const messages: TeamMessage[] = [];
|
||||
bus.registerGlobalHandler((msg) => messages.push(msg));
|
||||
|
||||
await bus.submitPlan('agent-1', 'leader', 'task-1', 'Plan');
|
||||
await bus.rejectPlan('leader', 'agent-1', 'task-1', 'Missing tests');
|
||||
|
||||
expect(messages[1].type).toBe('plan_reject');
|
||||
expect(messages[1].content).toBe('Missing tests');
|
||||
});
|
||||
});
|
||||
|
||||
describe('shutdown workflow', () => {
|
||||
it('should request and approve shutdown', async () => {
|
||||
const messages: TeamMessage[] = [];
|
||||
bus.registerGlobalHandler((msg) => messages.push(msg));
|
||||
|
||||
await bus.requestShutdown('agent-1', 'leader', 'Work complete');
|
||||
await bus.approveShutdown('leader', 'agent-1');
|
||||
|
||||
expect(messages[0].type).toBe('shutdown_request');
|
||||
expect(messages[1].type).toBe('shutdown_approve');
|
||||
});
|
||||
});
|
||||
|
||||
describe('getMessages', () => {
|
||||
it('should get messages for an agent', async () => {
|
||||
await bus.send('agent-1', 'agent-2', 'Hello');
|
||||
await bus.send('agent-3', 'agent-2', 'Hi there');
|
||||
await bus.send('agent-1', 'agent-3', 'Not for agent-2');
|
||||
|
||||
const messages = bus.getMessagesForAgent('agent-2');
|
||||
expect(messages.length).toBe(2);
|
||||
});
|
||||
|
||||
it('should get messages for a task', async () => {
|
||||
await bus.send('agent-1', 'agent-2', 'Message 1', { taskId: 'task-1' });
|
||||
await bus.send('agent-1', 'agent-2', 'Message 2', { taskId: 'task-1' });
|
||||
await bus.send('agent-1', 'agent-2', 'Message 3', { taskId: 'task-2' });
|
||||
|
||||
const messages = bus.getMessagesForTask('task-1');
|
||||
expect(messages.length).toBe(2);
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
describe('TeamOrchestrator', () => {
|
||||
let orchestrator: TeamOrchestrator;
|
||||
|
||||
beforeEach(() => {
|
||||
orchestrator = createTeamOrchestrator({
|
||||
projectPath: '/test/project',
|
||||
requirePlanApproval: true,
|
||||
});
|
||||
});
|
||||
|
||||
describe('spawnTeam', () => {
|
||||
it('should create a team with a leader', async () => {
|
||||
const team = await orchestrator.spawnTeam({
|
||||
name: 'Test Team',
|
||||
leaderAgent: 'claude-code',
|
||||
});
|
||||
|
||||
expect(team.id).toBeDefined();
|
||||
expect(team.name).toBe('Test Team');
|
||||
expect(team.leader.role).toBe('leader');
|
||||
expect(team.leader.agentType).toBe('claude-code');
|
||||
expect(team.status).toBe('working');
|
||||
});
|
||||
|
||||
it('should auto-spawn teammates', async () => {
|
||||
const team = await orchestrator.spawnTeam({
|
||||
name: 'Full Team',
|
||||
leaderAgent: 'claude-code',
|
||||
teammateAgents: ['cursor', 'copilot'],
|
||||
autoSpawn: true,
|
||||
});
|
||||
|
||||
expect(team.teammates.length).toBe(2);
|
||||
expect(team.teammates[0].agentType).toBe('cursor');
|
||||
expect(team.teammates[1].agentType).toBe('copilot');
|
||||
});
|
||||
});
|
||||
|
||||
describe('spawnTeammate', () => {
|
||||
it('should add a teammate to an existing team', async () => {
|
||||
const team = await orchestrator.spawnTeam({
|
||||
name: 'Team',
|
||||
leaderAgent: 'claude-code',
|
||||
});
|
||||
|
||||
const teammate = await orchestrator.spawnTeammate(team.id, 'cursor');
|
||||
|
||||
expect(teammate.role).toBe('teammate');
|
||||
expect(teammate.agentType).toBe('cursor');
|
||||
|
||||
const updatedTeam = orchestrator.getTeam(team.id);
|
||||
expect(updatedTeam?.teammates.length).toBe(1);
|
||||
});
|
||||
});
|
||||
|
||||
describe('createTask', () => {
|
||||
it('should create a task in a team', async () => {
|
||||
const team = await orchestrator.spawnTeam({
|
||||
name: 'Team',
|
||||
leaderAgent: 'claude-code',
|
||||
});
|
||||
|
||||
const task = await orchestrator.createTask(
|
||||
team.id,
|
||||
'Implement feature',
|
||||
'Add login',
|
||||
'Full spec'
|
||||
);
|
||||
|
||||
expect(task.id).toBeDefined();
|
||||
expect(task.name).toBe('Implement feature');
|
||||
});
|
||||
});
|
||||
|
||||
describe('assignTask', () => {
|
||||
it('should assign a task to a teammate', async () => {
|
||||
const team = await orchestrator.spawnTeam({
|
||||
name: 'Team',
|
||||
leaderAgent: 'claude-code',
|
||||
teammateAgents: ['cursor'],
|
||||
autoSpawn: true,
|
||||
});
|
||||
|
||||
const task = await orchestrator.createTask(team.id, 'Task', 'Desc', 'Spec');
|
||||
const assigned = await orchestrator.assignTask(team.id, task.id, team.teammates[0].id);
|
||||
|
||||
expect(assigned?.assignee).toBe(team.teammates[0].id);
|
||||
expect(team.teammates[0].status).toBe('planning');
|
||||
});
|
||||
});
|
||||
|
||||
describe('plan approval workflow', () => {
|
||||
it('should submit and approve plans', async () => {
|
||||
const team = await orchestrator.spawnTeam({
|
||||
name: 'Team',
|
||||
leaderAgent: 'claude-code',
|
||||
teammateAgents: ['cursor'],
|
||||
autoSpawn: true,
|
||||
});
|
||||
|
||||
const task = await orchestrator.createTask(team.id, 'Task', 'Desc', 'Spec');
|
||||
await orchestrator.assignTask(team.id, task.id, team.teammates[0].id);
|
||||
|
||||
await orchestrator.submitPlan(team.id, task.id, {
|
||||
steps: [{ number: 1, description: 'Implement', type: 'implement' }],
|
||||
});
|
||||
|
||||
const taskManager = orchestrator.getTaskManager(team.id);
|
||||
let updated = taskManager?.getTask(task.id);
|
||||
expect(updated?.status).toBe('plan_pending');
|
||||
|
||||
await orchestrator.approvePlan(team.id, task.id);
|
||||
updated = taskManager?.getTask(task.id);
|
||||
expect(updated?.status).toBe('approved');
|
||||
});
|
||||
|
||||
it('should reject plans with feedback', async () => {
|
||||
const team = await orchestrator.spawnTeam({
|
||||
name: 'Team',
|
||||
leaderAgent: 'claude-code',
|
||||
teammateAgents: ['cursor'],
|
||||
autoSpawn: true,
|
||||
});
|
||||
|
||||
const task = await orchestrator.createTask(team.id, 'Task', 'Desc', 'Spec');
|
||||
await orchestrator.assignTask(team.id, task.id, team.teammates[0].id);
|
||||
await orchestrator.submitPlan(team.id, task.id, { steps: [] });
|
||||
|
||||
await orchestrator.rejectPlan(team.id, task.id, 'Need more detail');
|
||||
|
||||
const taskManager = orchestrator.getTaskManager(team.id);
|
||||
const updated = taskManager?.getTask(task.id);
|
||||
expect(updated?.status).toBe('planning');
|
||||
expect(updated?.plan?.rejectionReason).toBe('Need more detail');
|
||||
});
|
||||
});
|
||||
|
||||
describe('shutdown workflow', () => {
|
||||
it('should request and approve agent shutdown', async () => {
|
||||
const team = await orchestrator.spawnTeam({
|
||||
name: 'Team',
|
||||
leaderAgent: 'claude-code',
|
||||
teammateAgents: ['cursor'],
|
||||
autoSpawn: true,
|
||||
});
|
||||
|
||||
const teammate = team.teammates[0];
|
||||
|
||||
await orchestrator.requestShutdown(team.id, teammate.id, 'Work complete');
|
||||
expect(teammate.status).toBe('shutdown_requested');
|
||||
|
||||
await orchestrator.approveShutdown(team.id, teammate.id);
|
||||
expect(teammate.status).toBe('shutdown');
|
||||
});
|
||||
});
|
||||
|
||||
describe('messaging', () => {
|
||||
it('should send direct messages', async () => {
|
||||
const team = await orchestrator.spawnTeam({
|
||||
name: 'Team',
|
||||
leaderAgent: 'claude-code',
|
||||
teammateAgents: ['cursor'],
|
||||
autoSpawn: true,
|
||||
});
|
||||
|
||||
await orchestrator.send(
|
||||
team.id,
|
||||
team.leader.id,
|
||||
team.teammates[0].id,
|
||||
'Start working on task'
|
||||
);
|
||||
|
||||
const bus = orchestrator.getMessageBus(team.id);
|
||||
const messages = bus?.getMessagesFromAgent(team.leader.id);
|
||||
expect(messages?.length).toBe(1);
|
||||
});
|
||||
|
||||
it('should broadcast messages', async () => {
|
||||
const team = await orchestrator.spawnTeam({
|
||||
name: 'Team',
|
||||
leaderAgent: 'claude-code',
|
||||
teammateAgents: ['cursor', 'copilot'],
|
||||
autoSpawn: true,
|
||||
});
|
||||
|
||||
await orchestrator.broadcast(team.id, team.leader.id, 'Team update');
|
||||
|
||||
const bus = orchestrator.getMessageBus(team.id);
|
||||
expect(bus?.messageCount).toBe(1);
|
||||
});
|
||||
});
|
||||
|
||||
describe('shutdownTeam', () => {
|
||||
it('should shutdown a team', async () => {
|
||||
const team = await orchestrator.spawnTeam({
|
||||
name: 'Team',
|
||||
leaderAgent: 'claude-code',
|
||||
teammateAgents: ['cursor'],
|
||||
autoSpawn: true,
|
||||
});
|
||||
|
||||
await orchestrator.shutdownTeam(team.id);
|
||||
|
||||
expect(orchestrator.getTeam(team.id)).toBeUndefined();
|
||||
expect(orchestrator.getTaskManager(team.id)).toBeUndefined();
|
||||
expect(orchestrator.getMessageBus(team.id)).toBeUndefined();
|
||||
});
|
||||
});
|
||||
|
||||
describe('getTeamStats', () => {
|
||||
it('should return team statistics', async () => {
|
||||
const team = await orchestrator.spawnTeam({
|
||||
name: 'Team',
|
||||
leaderAgent: 'claude-code',
|
||||
teammateAgents: ['cursor', 'copilot'],
|
||||
autoSpawn: true,
|
||||
});
|
||||
|
||||
await orchestrator.createTask(team.id, 'Task 1', 'Desc', 'Spec');
|
||||
await orchestrator.createTask(team.id, 'Task 2', 'Desc', 'Spec');
|
||||
|
||||
const stats = orchestrator.getTeamStats(team.id);
|
||||
|
||||
expect(stats?.agents.total).toBe(3); // leader + 2 teammates
|
||||
expect(stats?.tasks.total).toBe(2);
|
||||
});
|
||||
});
|
||||
|
||||
describe('event listeners', () => {
|
||||
it('should emit team events', async () => {
|
||||
const events: string[] = [];
|
||||
orchestrator.addListener((event) => {
|
||||
events.push(event);
|
||||
});
|
||||
|
||||
const team = await orchestrator.spawnTeam({
|
||||
name: 'Team',
|
||||
leaderAgent: 'claude-code',
|
||||
});
|
||||
|
||||
await orchestrator.spawnTeammate(team.id, 'cursor');
|
||||
await orchestrator.shutdownTeam(team.id);
|
||||
|
||||
expect(events).toContain('team:created');
|
||||
expect(events).toContain('team:teammate_spawned');
|
||||
expect(events).toContain('team:shutdown');
|
||||
});
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,67 @@
|
||||
/**
|
||||
* Team Orchestration System
|
||||
*
|
||||
* Provides multi-agent team coordination with task assignment, plan approval,
|
||||
* and review workflows.
|
||||
*
|
||||
* Key features:
|
||||
* - Team lifecycle management (spawn, shutdown)
|
||||
* - Task creation and assignment
|
||||
* - Plan approval workflow
|
||||
* - Review stages (spec-compliance, code-quality)
|
||||
* - Inter-agent messaging (direct + broadcast)
|
||||
* - Universal agent support (17 agents)
|
||||
*/
|
||||
|
||||
// Team Orchestrator
|
||||
export { TeamOrchestrator, createTeamOrchestrator } from './team.js';
|
||||
|
||||
// Task Manager
|
||||
export { TaskManager, createTaskManager } from './task.js';
|
||||
|
||||
// Message Bus
|
||||
export { TeamMessageBus, createMessageBus } from './messages.js';
|
||||
|
||||
// Types
|
||||
export type {
|
||||
// Team types
|
||||
Team,
|
||||
OrchestratorTeamConfig,
|
||||
TeamStatus,
|
||||
TeamEvent,
|
||||
TeamEventListener,
|
||||
|
||||
// Agent types
|
||||
AgentInstance,
|
||||
AgentStatus,
|
||||
|
||||
// Task types
|
||||
Task,
|
||||
OrchestratorTaskStatus,
|
||||
TaskFiles,
|
||||
TaskPlan,
|
||||
TaskResult,
|
||||
TaskFilter,
|
||||
TaskEvent,
|
||||
TaskEventListener,
|
||||
PlanStep,
|
||||
TestResult,
|
||||
|
||||
// Review types
|
||||
ReviewStage,
|
||||
ReviewStageName,
|
||||
ReviewResult,
|
||||
ReviewIssue,
|
||||
IssueSeverity,
|
||||
|
||||
// Message types
|
||||
TeamMessage,
|
||||
MessageType,
|
||||
MessageHandler,
|
||||
|
||||
// Result types
|
||||
PlanResult,
|
||||
|
||||
// Options
|
||||
OrchestratorOptions,
|
||||
} from './types.js';
|
||||
@@ -0,0 +1,367 @@
|
||||
/**
|
||||
* Team Message Bus
|
||||
*
|
||||
* Handles inter-agent communication within a team.
|
||||
*/
|
||||
|
||||
import { randomUUID } from 'node:crypto';
|
||||
import type { TeamMessage, MessageType, MessageHandler } from './types.js';
|
||||
|
||||
/**
|
||||
* TeamMessageBus - Handles team communication
|
||||
*/
|
||||
export class TeamMessageBus {
|
||||
private messages: TeamMessage[] = [];
|
||||
private handlers: Map<string, Set<MessageHandler>> = new Map();
|
||||
private globalHandlers: Set<MessageHandler> = new Set();
|
||||
private maxMessages: number;
|
||||
|
||||
constructor(options?: { maxMessages?: number }) {
|
||||
this.maxMessages = options?.maxMessages ?? 1000;
|
||||
}
|
||||
|
||||
/**
|
||||
* Send a direct message to a specific agent
|
||||
*/
|
||||
async send(
|
||||
from: string,
|
||||
to: string,
|
||||
content: string,
|
||||
options?: {
|
||||
type?: MessageType;
|
||||
taskId?: string;
|
||||
metadata?: Record<string, unknown>;
|
||||
}
|
||||
): Promise<TeamMessage> {
|
||||
const message: TeamMessage = {
|
||||
id: randomUUID(),
|
||||
type: options?.type || 'direct',
|
||||
from,
|
||||
to,
|
||||
content,
|
||||
taskId: options?.taskId,
|
||||
metadata: options?.metadata,
|
||||
timestamp: new Date(),
|
||||
};
|
||||
|
||||
this.addMessage(message);
|
||||
await this.notifyHandlers(to, message);
|
||||
await this.notifyGlobalHandlers(message);
|
||||
|
||||
return message;
|
||||
}
|
||||
|
||||
/**
|
||||
* Broadcast a message to all agents
|
||||
*/
|
||||
async broadcast(
|
||||
from: string,
|
||||
content: string,
|
||||
options?: {
|
||||
taskId?: string;
|
||||
metadata?: Record<string, unknown>;
|
||||
}
|
||||
): Promise<TeamMessage> {
|
||||
const message: TeamMessage = {
|
||||
id: randomUUID(),
|
||||
type: 'broadcast',
|
||||
from,
|
||||
content,
|
||||
taskId: options?.taskId,
|
||||
metadata: options?.metadata,
|
||||
timestamp: new Date(),
|
||||
};
|
||||
|
||||
this.addMessage(message);
|
||||
|
||||
// Notify all registered handlers
|
||||
for (const [agentId, handlers] of this.handlers) {
|
||||
if (agentId !== from) {
|
||||
for (const handler of handlers) {
|
||||
try {
|
||||
await handler(message);
|
||||
} catch {
|
||||
// Ignore handler errors
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
await this.notifyGlobalHandlers(message);
|
||||
|
||||
return message;
|
||||
}
|
||||
|
||||
/**
|
||||
* Submit a plan for approval
|
||||
*/
|
||||
async submitPlan(
|
||||
from: string,
|
||||
leaderId: string,
|
||||
taskId: string,
|
||||
planSummary: string
|
||||
): Promise<TeamMessage> {
|
||||
return this.send(from, leaderId, planSummary, {
|
||||
type: 'plan_submit',
|
||||
taskId,
|
||||
metadata: { action: 'submit_plan' },
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
* Approve a plan
|
||||
*/
|
||||
async approvePlan(
|
||||
leaderId: string,
|
||||
teammateId: string,
|
||||
taskId: string,
|
||||
feedback?: string
|
||||
): Promise<TeamMessage> {
|
||||
return this.send(leaderId, teammateId, feedback || 'Plan approved', {
|
||||
type: 'plan_approve',
|
||||
taskId,
|
||||
metadata: { action: 'approve_plan' },
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
* Reject a plan
|
||||
*/
|
||||
async rejectPlan(
|
||||
leaderId: string,
|
||||
teammateId: string,
|
||||
taskId: string,
|
||||
reason: string
|
||||
): Promise<TeamMessage> {
|
||||
return this.send(leaderId, teammateId, reason, {
|
||||
type: 'plan_reject',
|
||||
taskId,
|
||||
metadata: { action: 'reject_plan' },
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
* Request shutdown
|
||||
*/
|
||||
async requestShutdown(
|
||||
from: string,
|
||||
leaderId: string,
|
||||
reason?: string
|
||||
): Promise<TeamMessage> {
|
||||
return this.send(from, leaderId, reason || 'Requesting shutdown', {
|
||||
type: 'shutdown_request',
|
||||
metadata: { action: 'shutdown_request' },
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
* Approve shutdown
|
||||
*/
|
||||
async approveShutdown(
|
||||
leaderId: string,
|
||||
agentId: string
|
||||
): Promise<TeamMessage> {
|
||||
return this.send(leaderId, agentId, 'Shutdown approved', {
|
||||
type: 'shutdown_approve',
|
||||
metadata: { action: 'shutdown_approve' },
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
* Send task assignment notification
|
||||
*/
|
||||
async notifyTaskAssignment(
|
||||
leaderId: string,
|
||||
agentId: string,
|
||||
taskId: string,
|
||||
taskSummary: string
|
||||
): Promise<TeamMessage> {
|
||||
return this.send(leaderId, agentId, taskSummary, {
|
||||
type: 'task_assign',
|
||||
taskId,
|
||||
metadata: { action: 'assign_task' },
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
* Request review
|
||||
*/
|
||||
async requestReview(
|
||||
from: string,
|
||||
reviewerId: string,
|
||||
taskId: string,
|
||||
details: string
|
||||
): Promise<TeamMessage> {
|
||||
return this.send(from, reviewerId, details, {
|
||||
type: 'review_request',
|
||||
taskId,
|
||||
metadata: { action: 'request_review' },
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
* Complete review
|
||||
*/
|
||||
async completeReview(
|
||||
reviewerId: string,
|
||||
agentId: string,
|
||||
taskId: string,
|
||||
result: string,
|
||||
passed: boolean
|
||||
): Promise<TeamMessage> {
|
||||
return this.send(reviewerId, agentId, result, {
|
||||
type: 'review_complete',
|
||||
taskId,
|
||||
metadata: { action: 'complete_review', passed },
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
* Register a message handler for an agent
|
||||
*/
|
||||
registerHandler(agentId: string, handler: MessageHandler): void {
|
||||
if (!this.handlers.has(agentId)) {
|
||||
this.handlers.set(agentId, new Set());
|
||||
}
|
||||
this.handlers.get(agentId)!.add(handler);
|
||||
}
|
||||
|
||||
/**
|
||||
* Unregister a message handler
|
||||
*/
|
||||
unregisterHandler(agentId: string, handler: MessageHandler): void {
|
||||
const handlers = this.handlers.get(agentId);
|
||||
if (handlers) {
|
||||
handlers.delete(handler);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Register a global message handler (receives all messages)
|
||||
*/
|
||||
registerGlobalHandler(handler: MessageHandler): void {
|
||||
this.globalHandlers.add(handler);
|
||||
}
|
||||
|
||||
/**
|
||||
* Unregister a global handler
|
||||
*/
|
||||
unregisterGlobalHandler(handler: MessageHandler): void {
|
||||
this.globalHandlers.delete(handler);
|
||||
}
|
||||
|
||||
/**
|
||||
* Get messages for an agent
|
||||
*/
|
||||
getMessagesForAgent(agentId: string): TeamMessage[] {
|
||||
return this.messages.filter((m) => m.to === agentId || (m.type === 'broadcast' && m.from !== agentId));
|
||||
}
|
||||
|
||||
/**
|
||||
* Get messages from an agent
|
||||
*/
|
||||
getMessagesFromAgent(agentId: string): TeamMessage[] {
|
||||
return this.messages.filter((m) => m.from === agentId);
|
||||
}
|
||||
|
||||
/**
|
||||
* Get messages for a task
|
||||
*/
|
||||
getMessagesForTask(taskId: string): TeamMessage[] {
|
||||
return this.messages.filter((m) => m.taskId === taskId);
|
||||
}
|
||||
|
||||
/**
|
||||
* Get all messages
|
||||
*/
|
||||
getAllMessages(): TeamMessage[] {
|
||||
return [...this.messages];
|
||||
}
|
||||
|
||||
/**
|
||||
* Get recent messages
|
||||
*/
|
||||
getRecentMessages(count: number): TeamMessage[] {
|
||||
return this.messages.slice(-count);
|
||||
}
|
||||
|
||||
/**
|
||||
* Get messages by type
|
||||
*/
|
||||
getMessagesByType(type: MessageType): TeamMessage[] {
|
||||
return this.messages.filter((m) => m.type === type);
|
||||
}
|
||||
|
||||
/**
|
||||
* Get conversation between two agents
|
||||
*/
|
||||
getConversation(agent1: string, agent2: string): TeamMessage[] {
|
||||
return this.messages.filter(
|
||||
(m) =>
|
||||
m.type === 'direct' &&
|
||||
((m.from === agent1 && m.to === agent2) || (m.from === agent2 && m.to === agent1))
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* Clear all messages
|
||||
*/
|
||||
clear(): void {
|
||||
this.messages = [];
|
||||
}
|
||||
|
||||
/**
|
||||
* Add a message to the history
|
||||
*/
|
||||
private addMessage(message: TeamMessage): void {
|
||||
this.messages.push(message);
|
||||
|
||||
// Trim if exceeds max
|
||||
if (this.messages.length > this.maxMessages) {
|
||||
this.messages = this.messages.slice(-this.maxMessages);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Notify handlers for a specific agent
|
||||
*/
|
||||
private async notifyHandlers(agentId: string, message: TeamMessage): Promise<void> {
|
||||
const handlers = this.handlers.get(agentId);
|
||||
if (!handlers) return;
|
||||
|
||||
for (const handler of handlers) {
|
||||
try {
|
||||
await handler(message);
|
||||
} catch {
|
||||
// Ignore handler errors
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Notify global handlers
|
||||
*/
|
||||
private async notifyGlobalHandlers(message: TeamMessage): Promise<void> {
|
||||
for (const handler of this.globalHandlers) {
|
||||
try {
|
||||
await handler(message);
|
||||
} catch {
|
||||
// Ignore handler errors
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Get message count
|
||||
*/
|
||||
get messageCount(): number {
|
||||
return this.messages.length;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Create a TeamMessageBus instance
|
||||
*/
|
||||
export function createMessageBus(options?: { maxMessages?: number }): TeamMessageBus {
|
||||
return new TeamMessageBus(options);
|
||||
}
|
||||
@@ -0,0 +1,438 @@
|
||||
/**
|
||||
* Task Manager
|
||||
*
|
||||
* Manages tasks within a team with status tracking and assignment.
|
||||
*/
|
||||
|
||||
import { randomUUID } from 'node:crypto';
|
||||
import type {
|
||||
Task,
|
||||
OrchestratorTaskStatus,
|
||||
TaskFiles,
|
||||
TaskPlan,
|
||||
TaskResult,
|
||||
TaskFilter,
|
||||
TaskEvent,
|
||||
TaskEventListener,
|
||||
} from './types.js';
|
||||
|
||||
/**
|
||||
* TaskManager - Manages team tasks
|
||||
*/
|
||||
export class TaskManager {
|
||||
private tasks: Map<string, Task> = new Map();
|
||||
private listeners: Set<TaskEventListener> = new Set();
|
||||
|
||||
/**
|
||||
* Create a new task
|
||||
*/
|
||||
createTask(
|
||||
name: string,
|
||||
description: string,
|
||||
spec: string,
|
||||
options?: {
|
||||
files?: TaskFiles;
|
||||
priority?: number;
|
||||
dependencies?: string[];
|
||||
metadata?: Record<string, unknown>;
|
||||
}
|
||||
): Task {
|
||||
const now = new Date();
|
||||
const task: Task = {
|
||||
id: randomUUID(),
|
||||
name,
|
||||
description,
|
||||
spec,
|
||||
files: options?.files || {},
|
||||
status: 'pending',
|
||||
priority: options?.priority ?? 0,
|
||||
dependencies: options?.dependencies || [],
|
||||
createdAt: now,
|
||||
updatedAt: now,
|
||||
metadata: options?.metadata,
|
||||
};
|
||||
|
||||
this.tasks.set(task.id, task);
|
||||
this.emit('task:created', task);
|
||||
return task;
|
||||
}
|
||||
|
||||
/**
|
||||
* Get a task by ID
|
||||
*/
|
||||
getTask(taskId: string): Task | undefined {
|
||||
return this.tasks.get(taskId);
|
||||
}
|
||||
|
||||
/**
|
||||
* Get all tasks
|
||||
*/
|
||||
getAllTasks(): Task[] {
|
||||
return Array.from(this.tasks.values());
|
||||
}
|
||||
|
||||
/**
|
||||
* List tasks with optional filter
|
||||
*/
|
||||
listTasks(filter?: TaskFilter): Task[] {
|
||||
let tasks = this.getAllTasks();
|
||||
|
||||
if (filter) {
|
||||
if (filter.status) {
|
||||
const statuses = Array.isArray(filter.status) ? filter.status : [filter.status];
|
||||
tasks = tasks.filter((t) => statuses.includes(t.status));
|
||||
}
|
||||
|
||||
if (filter.assignee) {
|
||||
tasks = tasks.filter((t) => t.assignee === filter.assignee);
|
||||
}
|
||||
|
||||
if (filter.minPriority !== undefined) {
|
||||
tasks = tasks.filter((t) => (t.priority || 0) >= filter.minPriority!);
|
||||
}
|
||||
|
||||
if (!filter.includeCompleted) {
|
||||
tasks = tasks.filter((t) => t.status !== 'completed' && t.status !== 'failed');
|
||||
}
|
||||
}
|
||||
|
||||
// Sort by priority (descending) then by creation time
|
||||
return tasks.sort((a, b) => {
|
||||
const priorityDiff = (b.priority || 0) - (a.priority || 0);
|
||||
if (priorityDiff !== 0) return priorityDiff;
|
||||
return a.createdAt.getTime() - b.createdAt.getTime();
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
* Assign a task to an agent
|
||||
*/
|
||||
assignTask(taskId: string, agentId: string): Task | undefined {
|
||||
const task = this.tasks.get(taskId);
|
||||
if (!task) return undefined;
|
||||
|
||||
// Check dependencies
|
||||
if (task.dependencies && task.dependencies.length > 0) {
|
||||
const unfinished = task.dependencies.filter((depId) => {
|
||||
const dep = this.tasks.get(depId);
|
||||
return !dep || dep.status !== 'completed';
|
||||
});
|
||||
|
||||
if (unfinished.length > 0) {
|
||||
throw new Error(`Task has unfinished or missing dependencies: ${unfinished.join(', ')}`);
|
||||
}
|
||||
}
|
||||
|
||||
task.assignee = agentId;
|
||||
task.status = 'assigned';
|
||||
task.updatedAt = new Date();
|
||||
|
||||
this.emit('task:assigned', task);
|
||||
return task;
|
||||
}
|
||||
|
||||
/**
|
||||
* Unassign a task
|
||||
*/
|
||||
unassignTask(taskId: string): Task | undefined {
|
||||
const task = this.tasks.get(taskId);
|
||||
if (!task) return undefined;
|
||||
|
||||
task.assignee = undefined;
|
||||
task.status = 'pending';
|
||||
task.updatedAt = new Date();
|
||||
|
||||
return task;
|
||||
}
|
||||
|
||||
/**
|
||||
* Submit a plan for a task
|
||||
*/
|
||||
submitPlan(taskId: string, plan: Omit<TaskPlan, 'submittedAt'>): Task | undefined {
|
||||
const task = this.tasks.get(taskId);
|
||||
if (!task) return undefined;
|
||||
|
||||
task.plan = {
|
||||
...plan,
|
||||
submittedAt: new Date(),
|
||||
};
|
||||
task.status = 'plan_pending';
|
||||
task.updatedAt = new Date();
|
||||
|
||||
this.emit('task:plan_submitted', task);
|
||||
return task;
|
||||
}
|
||||
|
||||
/**
|
||||
* Approve a task plan
|
||||
*/
|
||||
approvePlan(taskId: string, approverId: string): Task | undefined {
|
||||
const task = this.tasks.get(taskId);
|
||||
if (!task || !task.plan) return undefined;
|
||||
|
||||
task.plan.approvedAt = new Date();
|
||||
task.plan.approvedBy = approverId;
|
||||
task.status = 'approved';
|
||||
task.updatedAt = new Date();
|
||||
|
||||
this.emit('task:plan_approved', task);
|
||||
return task;
|
||||
}
|
||||
|
||||
/**
|
||||
* Reject a task plan
|
||||
*/
|
||||
rejectPlan(taskId: string, reason: string): Task | undefined {
|
||||
const task = this.tasks.get(taskId);
|
||||
if (!task || !task.plan) return undefined;
|
||||
|
||||
task.plan.rejectionReason = reason;
|
||||
task.status = 'planning';
|
||||
task.updatedAt = new Date();
|
||||
|
||||
this.emit('task:plan_rejected', task);
|
||||
return task;
|
||||
}
|
||||
|
||||
/**
|
||||
* Start a task (mark as in progress)
|
||||
*/
|
||||
startTask(taskId: string): Task | undefined {
|
||||
const task = this.tasks.get(taskId);
|
||||
if (!task) return undefined;
|
||||
|
||||
task.status = 'in_progress';
|
||||
task.updatedAt = new Date();
|
||||
|
||||
this.emit('task:started', task);
|
||||
return task;
|
||||
}
|
||||
|
||||
/**
|
||||
* Mark task as under review
|
||||
*/
|
||||
markForReview(taskId: string): Task | undefined {
|
||||
const task = this.tasks.get(taskId);
|
||||
if (!task) return undefined;
|
||||
|
||||
task.status = 'review';
|
||||
task.updatedAt = new Date();
|
||||
|
||||
return task;
|
||||
}
|
||||
|
||||
/**
|
||||
* Complete a task
|
||||
*/
|
||||
completeTask(taskId: string, result: TaskResult): Task | undefined {
|
||||
const task = this.tasks.get(taskId);
|
||||
if (!task) return undefined;
|
||||
|
||||
task.result = result;
|
||||
task.status = result.success ? 'completed' : 'failed';
|
||||
task.updatedAt = new Date();
|
||||
|
||||
this.emit(result.success ? 'task:completed' : 'task:failed', task);
|
||||
return task;
|
||||
}
|
||||
|
||||
/**
|
||||
* Fail a task
|
||||
*/
|
||||
failTask(taskId: string, errors: string[]): Task | undefined {
|
||||
const task = this.tasks.get(taskId);
|
||||
if (!task) return undefined;
|
||||
|
||||
task.result = {
|
||||
success: false,
|
||||
output: 'Task failed',
|
||||
errors,
|
||||
completedAt: new Date(),
|
||||
};
|
||||
task.status = 'failed';
|
||||
task.updatedAt = new Date();
|
||||
|
||||
this.emit('task:failed', task);
|
||||
return task;
|
||||
}
|
||||
|
||||
/**
|
||||
* Update task status
|
||||
*/
|
||||
updateStatus(taskId: string, status: OrchestratorTaskStatus): Task | undefined {
|
||||
const task = this.tasks.get(taskId);
|
||||
if (!task) return undefined;
|
||||
|
||||
task.status = status;
|
||||
task.updatedAt = new Date();
|
||||
|
||||
return task;
|
||||
}
|
||||
|
||||
/**
|
||||
* Delete a task
|
||||
*/
|
||||
deleteTask(taskId: string): boolean {
|
||||
return this.tasks.delete(taskId);
|
||||
}
|
||||
|
||||
/**
|
||||
* Get tasks by status
|
||||
*/
|
||||
getTasksByStatus(status: OrchestratorTaskStatus): Task[] {
|
||||
return this.getAllTasks().filter((t) => t.status === status);
|
||||
}
|
||||
|
||||
/**
|
||||
* Get tasks for an agent
|
||||
*/
|
||||
getTasksForAgent(agentId: string): Task[] {
|
||||
return this.getAllTasks().filter((t) => t.assignee === agentId);
|
||||
}
|
||||
|
||||
/**
|
||||
* Get pending tasks (unassigned)
|
||||
*/
|
||||
getPendingTasks(): Task[] {
|
||||
return this.getTasksByStatus('pending').sort((a, b) => (b.priority || 0) - (a.priority || 0));
|
||||
}
|
||||
|
||||
/**
|
||||
* Get next available task for assignment
|
||||
*/
|
||||
getNextTask(): Task | undefined {
|
||||
const pending = this.getPendingTasks();
|
||||
|
||||
// Find first task with no unfinished dependencies
|
||||
for (const task of pending) {
|
||||
if (!task.dependencies || task.dependencies.length === 0) {
|
||||
return task;
|
||||
}
|
||||
|
||||
const allDepsComplete = task.dependencies.every((depId) => {
|
||||
const dep = this.tasks.get(depId);
|
||||
return dep && dep.status === 'completed';
|
||||
});
|
||||
|
||||
if (allDepsComplete) {
|
||||
return task;
|
||||
}
|
||||
}
|
||||
|
||||
return undefined;
|
||||
}
|
||||
|
||||
/**
|
||||
* Check if all tasks are complete
|
||||
*/
|
||||
allTasksComplete(): boolean {
|
||||
const tasks = this.getAllTasks();
|
||||
return tasks.length > 0 && tasks.every((t) => t.status === 'completed' || t.status === 'failed');
|
||||
}
|
||||
|
||||
/**
|
||||
* Get completion stats
|
||||
*/
|
||||
getStats(): {
|
||||
total: number;
|
||||
pending: number;
|
||||
inProgress: number;
|
||||
completed: number;
|
||||
failed: number;
|
||||
} {
|
||||
const tasks = this.getAllTasks();
|
||||
return {
|
||||
total: tasks.length,
|
||||
pending: tasks.filter((t) => t.status === 'pending' || t.status === 'assigned').length,
|
||||
inProgress: tasks.filter((t) =>
|
||||
['planning', 'plan_pending', 'approved', 'in_progress', 'review'].includes(t.status)
|
||||
).length,
|
||||
completed: tasks.filter((t) => t.status === 'completed').length,
|
||||
failed: tasks.filter((t) => t.status === 'failed').length,
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Add event listener
|
||||
*/
|
||||
addListener(listener: TaskEventListener): void {
|
||||
this.listeners.add(listener);
|
||||
}
|
||||
|
||||
/**
|
||||
* Remove event listener
|
||||
*/
|
||||
removeListener(listener: TaskEventListener): void {
|
||||
this.listeners.delete(listener);
|
||||
}
|
||||
|
||||
/**
|
||||
* Emit task event
|
||||
*/
|
||||
private emit(event: TaskEvent, task: Task): void {
|
||||
for (const listener of this.listeners) {
|
||||
try {
|
||||
// Call listener (may return Promise or void)
|
||||
const result = listener(event, task);
|
||||
// If it returns a Promise, catch rejections
|
||||
if (result instanceof Promise) {
|
||||
result.catch(() => {
|
||||
// Ignore async listener errors
|
||||
});
|
||||
}
|
||||
} catch {
|
||||
// Ignore sync listener errors
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Clear all tasks
|
||||
*/
|
||||
clear(): void {
|
||||
this.tasks.clear();
|
||||
}
|
||||
|
||||
/**
|
||||
* Export tasks to JSON
|
||||
*/
|
||||
toJSON(): Task[] {
|
||||
return this.getAllTasks();
|
||||
}
|
||||
|
||||
/**
|
||||
* Import tasks from JSON
|
||||
*/
|
||||
fromJSON(tasks: Task[]): void {
|
||||
this.clear();
|
||||
for (const task of tasks) {
|
||||
// Rehydrate Date fields that were serialized to strings
|
||||
const hydrated: Task = {
|
||||
...task,
|
||||
createdAt: new Date(task.createdAt),
|
||||
updatedAt: new Date(task.updatedAt),
|
||||
plan: task.plan
|
||||
? {
|
||||
...task.plan,
|
||||
submittedAt: new Date(task.plan.submittedAt),
|
||||
approvedAt: task.plan.approvedAt ? new Date(task.plan.approvedAt) : undefined,
|
||||
}
|
||||
: undefined,
|
||||
result: task.result
|
||||
? {
|
||||
...task.result,
|
||||
completedAt: new Date(task.result.completedAt),
|
||||
}
|
||||
: undefined,
|
||||
};
|
||||
this.tasks.set(hydrated.id, hydrated);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Create a TaskManager instance
|
||||
*/
|
||||
export function createTaskManager(): TaskManager {
|
||||
return new TaskManager();
|
||||
}
|
||||
@@ -0,0 +1,628 @@
|
||||
/**
|
||||
* Team Orchestrator
|
||||
*
|
||||
* Coordinates multi-agent teams with task assignment, plan approval, and review workflows.
|
||||
*/
|
||||
|
||||
import { randomUUID } from 'node:crypto';
|
||||
import type { AgentType } from '../types.js';
|
||||
import type {
|
||||
Team,
|
||||
OrchestratorTeamConfig,
|
||||
AgentInstance,
|
||||
Task,
|
||||
TaskPlan,
|
||||
TaskFilter,
|
||||
ReviewStage,
|
||||
ReviewResult,
|
||||
PlanResult,
|
||||
OrchestratorOptions,
|
||||
TeamEvent,
|
||||
TeamEventListener,
|
||||
} from './types.js';
|
||||
import { TaskManager, createTaskManager } from './task.js';
|
||||
import { TeamMessageBus, createMessageBus } from './messages.js';
|
||||
|
||||
/**
|
||||
* Default review stages
|
||||
*/
|
||||
const DEFAULT_REVIEW_STAGES: ReviewStage[] = [
|
||||
{
|
||||
name: 'spec-compliance',
|
||||
prompt: 'Review the implementation for specification compliance. Verify all requirements are met.',
|
||||
required: true,
|
||||
reviewer: 'leader',
|
||||
},
|
||||
{
|
||||
name: 'code-quality',
|
||||
prompt: 'Review the code quality, style, and best practices. Check for maintainability.',
|
||||
required: true,
|
||||
reviewer: 'leader',
|
||||
},
|
||||
];
|
||||
|
||||
/**
|
||||
* TeamOrchestrator - Coordinates multi-agent teams
|
||||
*/
|
||||
export class TeamOrchestrator {
|
||||
private teams: Map<string, Team> = new Map();
|
||||
private taskManagers: Map<string, TaskManager> = new Map();
|
||||
private messageBuses: Map<string, TeamMessageBus> = new Map();
|
||||
private listeners: Set<TeamEventListener> = new Set();
|
||||
private options: Required<OrchestratorOptions>;
|
||||
|
||||
constructor(options: OrchestratorOptions) {
|
||||
this.options = {
|
||||
projectPath: options.projectPath,
|
||||
defaultReviewStages: options.defaultReviewStages || DEFAULT_REVIEW_STAGES,
|
||||
requirePlanApproval: options.requirePlanApproval ?? true,
|
||||
taskTimeout: options.taskTimeout ?? 300000, // 5 minutes
|
||||
enableMethodology: options.enableMethodology ?? true,
|
||||
verbose: options.verbose ?? false,
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Spawn a new team
|
||||
*/
|
||||
async spawnTeam(config: OrchestratorTeamConfig): Promise<Team> {
|
||||
const teamId = randomUUID();
|
||||
const now = new Date();
|
||||
|
||||
// Create leader agent
|
||||
const leader: AgentInstance = {
|
||||
id: randomUUID(),
|
||||
role: 'leader',
|
||||
agentType: config.leaderAgent,
|
||||
status: 'idle',
|
||||
spawnedAt: now,
|
||||
lastActivityAt: now,
|
||||
};
|
||||
|
||||
// Create team
|
||||
const team: Team = {
|
||||
id: teamId,
|
||||
name: config.name,
|
||||
leader,
|
||||
teammates: [],
|
||||
tasks: [],
|
||||
status: 'forming',
|
||||
createdAt: now,
|
||||
config: {
|
||||
...config,
|
||||
requirePlanApproval: config.requirePlanApproval ?? this.options.requirePlanApproval,
|
||||
reviewStages: config.reviewStages || this.options.defaultReviewStages.map((s) => s.name),
|
||||
},
|
||||
metadata: config.metadata,
|
||||
};
|
||||
|
||||
// Create task manager and message bus for this team
|
||||
this.taskManagers.set(teamId, createTaskManager());
|
||||
this.messageBuses.set(teamId, createMessageBus());
|
||||
|
||||
this.teams.set(teamId, team);
|
||||
|
||||
// Auto-spawn teammates if configured
|
||||
if (config.autoSpawn && config.teammateAgents) {
|
||||
for (const agentType of config.teammateAgents) {
|
||||
await this.spawnTeammate(teamId, agentType);
|
||||
}
|
||||
}
|
||||
|
||||
team.status = 'working';
|
||||
this.emit('team:created', team);
|
||||
|
||||
return team;
|
||||
}
|
||||
|
||||
/**
|
||||
* Spawn a teammate agent
|
||||
*/
|
||||
async spawnTeammate(teamId: string, agentType: AgentType): Promise<AgentInstance> {
|
||||
const team = this.teams.get(teamId);
|
||||
if (!team) throw new Error(`Team not found: ${teamId}`);
|
||||
|
||||
const now = new Date();
|
||||
const teammate: AgentInstance = {
|
||||
id: randomUUID(),
|
||||
role: 'teammate',
|
||||
agentType,
|
||||
status: 'idle',
|
||||
spawnedAt: now,
|
||||
lastActivityAt: now,
|
||||
};
|
||||
|
||||
team.teammates.push(teammate);
|
||||
this.emit('team:teammate_spawned', team, teammate);
|
||||
|
||||
return teammate;
|
||||
}
|
||||
|
||||
/**
|
||||
* Get a team by ID
|
||||
*/
|
||||
getTeam(teamId: string): Team | undefined {
|
||||
return this.teams.get(teamId);
|
||||
}
|
||||
|
||||
/**
|
||||
* Get all teams
|
||||
*/
|
||||
getAllTeams(): Team[] {
|
||||
return Array.from(this.teams.values());
|
||||
}
|
||||
|
||||
/**
|
||||
* Get task manager for a team
|
||||
*/
|
||||
getTaskManager(teamId: string): TaskManager | undefined {
|
||||
return this.taskManagers.get(teamId);
|
||||
}
|
||||
|
||||
/**
|
||||
* Get message bus for a team
|
||||
*/
|
||||
getMessageBus(teamId: string): TeamMessageBus | undefined {
|
||||
return this.messageBuses.get(teamId);
|
||||
}
|
||||
|
||||
/**
|
||||
* Create a task in a team
|
||||
*/
|
||||
async createTask(
|
||||
teamId: string,
|
||||
name: string,
|
||||
description: string,
|
||||
spec: string,
|
||||
options?: Parameters<TaskManager['createTask']>[3]
|
||||
): Promise<Task> {
|
||||
const taskManager = this.taskManagers.get(teamId);
|
||||
if (!taskManager) throw new Error(`Team not found: ${teamId}`);
|
||||
|
||||
const task = taskManager.createTask(name, description, spec, options);
|
||||
|
||||
// Update team's task list
|
||||
const team = this.teams.get(teamId);
|
||||
if (team) {
|
||||
team.tasks.push(task);
|
||||
}
|
||||
|
||||
return task;
|
||||
}
|
||||
|
||||
/**
|
||||
* Assign a task to an agent
|
||||
*/
|
||||
async assignTask(teamId: string, taskId: string, agentId: string): Promise<Task | undefined> {
|
||||
const taskManager = this.taskManagers.get(teamId);
|
||||
const messageBus = this.messageBuses.get(teamId);
|
||||
const team = this.teams.get(teamId);
|
||||
|
||||
if (!taskManager || !messageBus || !team) {
|
||||
throw new Error(`Team not found: ${teamId}`);
|
||||
}
|
||||
|
||||
// Verify agent exists in team
|
||||
const agent = this.findAgent(team, agentId);
|
||||
if (!agent) throw new Error(`Agent not found in team: ${agentId}`);
|
||||
|
||||
const task = taskManager.assignTask(taskId, agentId);
|
||||
if (!task) return undefined;
|
||||
|
||||
// Update agent status
|
||||
agent.currentTask = taskId;
|
||||
agent.status = 'planning';
|
||||
agent.lastActivityAt = new Date();
|
||||
|
||||
// Notify agent
|
||||
await messageBus.notifyTaskAssignment(
|
||||
team.leader.id,
|
||||
agentId,
|
||||
taskId,
|
||||
`Assigned: ${task.name}\n\n${task.description}`
|
||||
);
|
||||
|
||||
return task;
|
||||
}
|
||||
|
||||
/**
|
||||
* List tasks in a team
|
||||
*/
|
||||
listTasks(teamId: string, filter?: TaskFilter): Task[] {
|
||||
const taskManager = this.taskManagers.get(teamId);
|
||||
if (!taskManager) throw new Error(`Team not found: ${teamId}`);
|
||||
|
||||
return taskManager.listTasks(filter);
|
||||
}
|
||||
|
||||
/**
|
||||
* Submit a plan for a task
|
||||
*/
|
||||
async submitPlan(
|
||||
teamId: string,
|
||||
taskId: string,
|
||||
plan: Omit<TaskPlan, 'submittedAt'>
|
||||
): Promise<Task | undefined> {
|
||||
const taskManager = this.taskManagers.get(teamId);
|
||||
const messageBus = this.messageBuses.get(teamId);
|
||||
const team = this.teams.get(teamId);
|
||||
|
||||
if (!taskManager || !messageBus || !team) {
|
||||
throw new Error(`Team not found: ${teamId}`);
|
||||
}
|
||||
|
||||
const task = taskManager.submitPlan(taskId, plan);
|
||||
if (!task) return undefined;
|
||||
|
||||
// Update agent status
|
||||
if (task.assignee) {
|
||||
const agent = this.findAgent(team, task.assignee);
|
||||
if (agent) {
|
||||
agent.status = 'reviewing';
|
||||
agent.lastActivityAt = new Date();
|
||||
}
|
||||
}
|
||||
|
||||
// Notify leader
|
||||
const planSummary = plan.steps.map((s) => `${s.number}. ${s.description}`).join('\n');
|
||||
await messageBus.submitPlan(
|
||||
task.assignee || 'unknown',
|
||||
team.leader.id,
|
||||
taskId,
|
||||
`Plan submitted for: ${task.name}\n\n${planSummary}`
|
||||
);
|
||||
|
||||
// If plan approval not required, auto-approve
|
||||
if (!team.config.requirePlanApproval) {
|
||||
return this.approvePlan(teamId, taskId);
|
||||
}
|
||||
|
||||
return task;
|
||||
}
|
||||
|
||||
/**
|
||||
* Approve a task plan
|
||||
*/
|
||||
async approvePlan(teamId: string, taskId: string): Promise<Task | undefined> {
|
||||
const taskManager = this.taskManagers.get(teamId);
|
||||
const messageBus = this.messageBuses.get(teamId);
|
||||
const team = this.teams.get(teamId);
|
||||
|
||||
if (!taskManager || !messageBus || !team) {
|
||||
throw new Error(`Team not found: ${teamId}`);
|
||||
}
|
||||
|
||||
const task = taskManager.approvePlan(taskId, team.leader.id);
|
||||
if (!task) return undefined;
|
||||
|
||||
// Update agent status
|
||||
if (task.assignee) {
|
||||
const agent = this.findAgent(team, task.assignee);
|
||||
if (agent) {
|
||||
agent.status = 'executing';
|
||||
agent.lastActivityAt = new Date();
|
||||
}
|
||||
}
|
||||
|
||||
// Notify agent
|
||||
await messageBus.approvePlan(team.leader.id, task.assignee || 'unknown', taskId, 'Plan approved. Proceed with implementation.');
|
||||
|
||||
return task;
|
||||
}
|
||||
|
||||
/**
|
||||
* Reject a task plan
|
||||
*/
|
||||
async rejectPlan(teamId: string, taskId: string, reason: string): Promise<Task | undefined> {
|
||||
const taskManager = this.taskManagers.get(teamId);
|
||||
const messageBus = this.messageBuses.get(teamId);
|
||||
const team = this.teams.get(teamId);
|
||||
|
||||
if (!taskManager || !messageBus || !team) {
|
||||
throw new Error(`Team not found: ${teamId}`);
|
||||
}
|
||||
|
||||
const task = taskManager.rejectPlan(taskId, reason);
|
||||
if (!task) return undefined;
|
||||
|
||||
// Update agent status back to planning
|
||||
if (task.assignee) {
|
||||
const agent = this.findAgent(team, task.assignee);
|
||||
if (agent) {
|
||||
agent.status = 'planning';
|
||||
agent.lastActivityAt = new Date();
|
||||
}
|
||||
}
|
||||
|
||||
// Notify agent
|
||||
await messageBus.rejectPlan(team.leader.id, task.assignee || 'unknown', taskId, reason);
|
||||
|
||||
return task;
|
||||
}
|
||||
|
||||
/**
|
||||
* Request agent shutdown
|
||||
*/
|
||||
async requestShutdown(teamId: string, agentId: string, reason?: string): Promise<void> {
|
||||
const messageBus = this.messageBuses.get(teamId);
|
||||
const team = this.teams.get(teamId);
|
||||
|
||||
if (!messageBus || !team) {
|
||||
throw new Error(`Team not found: ${teamId}`);
|
||||
}
|
||||
|
||||
const agent = this.findAgent(team, agentId);
|
||||
if (!agent) throw new Error(`Agent not found: ${agentId}`);
|
||||
|
||||
agent.status = 'shutdown_requested';
|
||||
agent.lastActivityAt = new Date();
|
||||
|
||||
// Notify leader
|
||||
await messageBus.requestShutdown(agentId, team.leader.id, reason);
|
||||
}
|
||||
|
||||
/**
|
||||
* Approve agent shutdown
|
||||
*/
|
||||
async approveShutdown(teamId: string, agentId: string): Promise<void> {
|
||||
const messageBus = this.messageBuses.get(teamId);
|
||||
const team = this.teams.get(teamId);
|
||||
|
||||
if (!messageBus || !team) {
|
||||
throw new Error(`Team not found: ${teamId}`);
|
||||
}
|
||||
|
||||
const agent = this.findAgent(team, agentId);
|
||||
if (!agent) throw new Error(`Agent not found: ${agentId}`);
|
||||
|
||||
agent.status = 'shutdown';
|
||||
agent.lastActivityAt = new Date();
|
||||
agent.currentTask = undefined;
|
||||
|
||||
// Notify agent
|
||||
await messageBus.approveShutdown(team.leader.id, agentId);
|
||||
|
||||
this.emit('team:teammate_shutdown', team, agent);
|
||||
}
|
||||
|
||||
/**
|
||||
* Send a message
|
||||
*/
|
||||
async send(
|
||||
teamId: string,
|
||||
from: string,
|
||||
to: string,
|
||||
content: string,
|
||||
taskId?: string
|
||||
): Promise<void> {
|
||||
const messageBus = this.messageBuses.get(teamId);
|
||||
if (!messageBus) throw new Error(`Team not found: ${teamId}`);
|
||||
|
||||
await messageBus.send(from, to, content, { taskId });
|
||||
}
|
||||
|
||||
/**
|
||||
* Broadcast a message
|
||||
*/
|
||||
async broadcast(teamId: string, from: string, content: string): Promise<void> {
|
||||
const messageBus = this.messageBuses.get(teamId);
|
||||
if (!messageBus) throw new Error(`Team not found: ${teamId}`);
|
||||
|
||||
await messageBus.broadcast(from, content);
|
||||
}
|
||||
|
||||
/**
|
||||
* Run review on a task
|
||||
*/
|
||||
async runReview(
|
||||
teamId: string,
|
||||
taskId: string,
|
||||
stage: ReviewStage,
|
||||
_implementation: string
|
||||
): Promise<ReviewResult> {
|
||||
const team = this.teams.get(teamId);
|
||||
const taskManager = this.taskManagers.get(teamId);
|
||||
|
||||
if (!team || !taskManager) {
|
||||
throw new Error(`Team not found: ${teamId}`);
|
||||
}
|
||||
|
||||
const task = taskManager.getTask(taskId);
|
||||
if (!task) throw new Error(`Task not found: ${taskId}`);
|
||||
|
||||
// Mark task as under review
|
||||
taskManager.markForReview(taskId);
|
||||
|
||||
// Simulate review (in production, this would invoke the reviewer agent)
|
||||
const result: ReviewResult = {
|
||||
passed: true,
|
||||
issues: [],
|
||||
summary: `${stage.name} review passed`,
|
||||
reviewerId: team.leader.id,
|
||||
reviewedAt: new Date(),
|
||||
};
|
||||
|
||||
return result;
|
||||
}
|
||||
|
||||
/**
|
||||
* Execute a full plan with all tasks
|
||||
*/
|
||||
async executePlan(teamId: string): Promise<PlanResult> {
|
||||
const team = this.teams.get(teamId);
|
||||
const taskManager = this.taskManagers.get(teamId);
|
||||
|
||||
if (!team || !taskManager) {
|
||||
throw new Error(`Team not found: ${teamId}`);
|
||||
}
|
||||
|
||||
const startTime = Date.now();
|
||||
const taskResults = new Map();
|
||||
const failedTasks: string[] = [];
|
||||
|
||||
// Process tasks in order, respecting dependencies
|
||||
while (!taskManager.allTasksComplete()) {
|
||||
const nextTask = taskManager.getNextTask();
|
||||
if (!nextTask) {
|
||||
// No more tasks can be executed (might be blocked by dependencies)
|
||||
break;
|
||||
}
|
||||
|
||||
// Find an idle agent to assign
|
||||
const idleTeammate = team.teammates.find((a) => a.status === 'idle');
|
||||
const idleLeader = team.leader.status === 'idle' && !team.leader.currentTask ? team.leader : null;
|
||||
const idleAgent = idleTeammate || idleLeader;
|
||||
|
||||
// Skip task if no idle agent available
|
||||
if (!idleAgent) {
|
||||
// No agent available, task will be retried in next iteration
|
||||
break;
|
||||
}
|
||||
|
||||
// Assign and execute
|
||||
await this.assignTask(teamId, nextTask.id, idleAgent.id);
|
||||
|
||||
// Start task
|
||||
taskManager.startTask(nextTask.id);
|
||||
|
||||
// Simulate execution (in production, agent would do the work)
|
||||
const result = {
|
||||
success: true,
|
||||
output: `Completed: ${nextTask.name}`,
|
||||
completedAt: new Date(),
|
||||
};
|
||||
|
||||
taskManager.completeTask(nextTask.id, result);
|
||||
taskResults.set(nextTask.id, result);
|
||||
|
||||
// Mark agent as idle
|
||||
idleAgent.status = 'idle';
|
||||
idleAgent.currentTask = undefined;
|
||||
}
|
||||
|
||||
// Check for failed or incomplete tasks
|
||||
const allTasks = taskManager.getAllTasks();
|
||||
for (const task of allTasks) {
|
||||
if (task.status === 'failed') {
|
||||
failedTasks.push(task.id);
|
||||
}
|
||||
}
|
||||
|
||||
// Also check for incomplete tasks (pending, in_progress, etc.)
|
||||
const incomplete = allTasks.filter(
|
||||
(task) => task.status !== 'completed' && task.status !== 'failed'
|
||||
);
|
||||
if (incomplete.length > 0) {
|
||||
failedTasks.push(...incomplete.map((task) => task.id));
|
||||
}
|
||||
|
||||
return {
|
||||
success: failedTasks.length === 0,
|
||||
taskResults,
|
||||
failedTasks,
|
||||
durationMs: Date.now() - startTime,
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Shutdown a team
|
||||
*/
|
||||
async shutdownTeam(teamId: string): Promise<void> {
|
||||
const team = this.teams.get(teamId);
|
||||
if (!team) throw new Error(`Team not found: ${teamId}`);
|
||||
|
||||
// Request shutdown for all teammates
|
||||
for (const teammate of team.teammates) {
|
||||
if (teammate.status !== 'shutdown') {
|
||||
teammate.status = 'shutdown';
|
||||
}
|
||||
}
|
||||
|
||||
// Mark leader as shutdown
|
||||
team.leader.status = 'shutdown';
|
||||
team.status = 'shutdown';
|
||||
|
||||
this.emit('team:shutdown', team);
|
||||
|
||||
// Clean up resources
|
||||
this.taskManagers.delete(teamId);
|
||||
this.messageBuses.delete(teamId);
|
||||
this.teams.delete(teamId);
|
||||
}
|
||||
|
||||
/**
|
||||
* Get team stats
|
||||
*/
|
||||
getTeamStats(teamId: string): {
|
||||
agents: { total: number; active: number; idle: number };
|
||||
tasks: ReturnType<TaskManager['getStats']>;
|
||||
messages: number;
|
||||
} | undefined {
|
||||
const team = this.teams.get(teamId);
|
||||
const taskManager = this.taskManagers.get(teamId);
|
||||
const messageBus = this.messageBuses.get(teamId);
|
||||
|
||||
if (!team || !taskManager || !messageBus) return undefined;
|
||||
|
||||
const allAgents = [team.leader, ...team.teammates];
|
||||
|
||||
return {
|
||||
agents: {
|
||||
total: allAgents.length,
|
||||
active: allAgents.filter((a) => a.status !== 'idle' && a.status !== 'shutdown').length,
|
||||
idle: allAgents.filter((a) => a.status === 'idle').length,
|
||||
},
|
||||
tasks: taskManager.getStats(),
|
||||
messages: messageBus.messageCount,
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Add event listener
|
||||
*/
|
||||
addListener(listener: TeamEventListener): void {
|
||||
this.listeners.add(listener);
|
||||
}
|
||||
|
||||
/**
|
||||
* Remove event listener
|
||||
*/
|
||||
removeListener(listener: TeamEventListener): void {
|
||||
this.listeners.delete(listener);
|
||||
}
|
||||
|
||||
/**
|
||||
* Find an agent in a team
|
||||
*/
|
||||
private findAgent(team: Team, agentId: string): AgentInstance | undefined {
|
||||
if (team.leader.id === agentId) return team.leader;
|
||||
return team.teammates.find((t) => t.id === agentId);
|
||||
}
|
||||
|
||||
/**
|
||||
* Emit team event
|
||||
*/
|
||||
private emit(event: TeamEvent, team: Team, agent?: AgentInstance): void {
|
||||
for (const listener of this.listeners) {
|
||||
try {
|
||||
// Call listener (may return Promise or void)
|
||||
const result = listener(event, team, agent);
|
||||
// If it returns a Promise, catch rejections
|
||||
if (result instanceof Promise) {
|
||||
result.catch(() => {
|
||||
// Ignore async listener errors
|
||||
});
|
||||
}
|
||||
} catch {
|
||||
// Ignore sync listener errors
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Create a TeamOrchestrator instance
|
||||
*/
|
||||
export function createTeamOrchestrator(options: OrchestratorOptions): TeamOrchestrator {
|
||||
return new TeamOrchestrator(options);
|
||||
}
|
||||
@@ -0,0 +1,392 @@
|
||||
/**
|
||||
* Team Orchestration Types
|
||||
*
|
||||
* Types for multi-agent team coordination with task assignment and review workflows.
|
||||
*/
|
||||
|
||||
import type { AgentType } from '../types.js';
|
||||
|
||||
/**
|
||||
* Team status
|
||||
*/
|
||||
export type TeamStatus = 'forming' | 'working' | 'reviewing' | 'completing' | 'shutdown';
|
||||
|
||||
/**
|
||||
* Agent instance status
|
||||
*/
|
||||
export type AgentStatus = 'idle' | 'planning' | 'executing' | 'reviewing' | 'shutdown_requested' | 'shutdown';
|
||||
|
||||
/**
|
||||
* Orchestrator task status
|
||||
*/
|
||||
export type OrchestratorTaskStatus =
|
||||
| 'pending'
|
||||
| 'assigned'
|
||||
| 'planning'
|
||||
| 'plan_pending'
|
||||
| 'approved'
|
||||
| 'in_progress'
|
||||
| 'review'
|
||||
| 'completed'
|
||||
| 'failed';
|
||||
|
||||
/**
|
||||
* Message type
|
||||
*/
|
||||
export type MessageType =
|
||||
| 'direct'
|
||||
| 'broadcast'
|
||||
| 'plan_submit'
|
||||
| 'plan_approve'
|
||||
| 'plan_reject'
|
||||
| 'shutdown_request'
|
||||
| 'shutdown_approve'
|
||||
| 'task_assign'
|
||||
| 'task_update'
|
||||
| 'review_request'
|
||||
| 'review_complete';
|
||||
|
||||
/**
|
||||
* Review stage name
|
||||
*/
|
||||
export type ReviewStageName = 'spec-compliance' | 'code-quality' | 'security' | 'testing' | 'custom';
|
||||
|
||||
/**
|
||||
* Issue severity
|
||||
*/
|
||||
export type IssueSeverity = 'critical' | 'important' | 'minor';
|
||||
|
||||
/**
|
||||
* Team orchestrator configuration
|
||||
*/
|
||||
export interface OrchestratorTeamConfig {
|
||||
/** Team name */
|
||||
name: string;
|
||||
/** Leader agent type */
|
||||
leaderAgent: AgentType;
|
||||
/** Teammate agent types */
|
||||
teammateAgents?: AgentType[];
|
||||
/** Auto-spawn teammates */
|
||||
autoSpawn?: boolean;
|
||||
/** Require plan approval before execution */
|
||||
requirePlanApproval?: boolean;
|
||||
/** Review stages to apply */
|
||||
reviewStages?: ReviewStageName[];
|
||||
/** Timeout for tasks (ms) */
|
||||
taskTimeout?: number;
|
||||
/** Metadata */
|
||||
metadata?: Record<string, unknown>;
|
||||
}
|
||||
|
||||
/**
|
||||
* Team instance
|
||||
*/
|
||||
export interface Team {
|
||||
/** Unique team ID */
|
||||
id: string;
|
||||
/** Team name */
|
||||
name: string;
|
||||
/** Leader agent */
|
||||
leader: AgentInstance;
|
||||
/** Teammate agents */
|
||||
teammates: AgentInstance[];
|
||||
/** Team tasks */
|
||||
tasks: Task[];
|
||||
/** Team status */
|
||||
status: TeamStatus;
|
||||
/** Creation time */
|
||||
createdAt: Date;
|
||||
/** Configuration */
|
||||
config: OrchestratorTeamConfig;
|
||||
/** Metadata */
|
||||
metadata?: Record<string, unknown>;
|
||||
}
|
||||
|
||||
/**
|
||||
* Agent instance
|
||||
*/
|
||||
export interface AgentInstance {
|
||||
/** Unique agent ID */
|
||||
id: string;
|
||||
/** Agent role */
|
||||
role: 'leader' | 'teammate';
|
||||
/** Agent type */
|
||||
agentType: AgentType;
|
||||
/** Agent status */
|
||||
status: AgentStatus;
|
||||
/** Current task ID */
|
||||
currentTask?: string;
|
||||
/** Spawn time */
|
||||
spawnedAt: Date;
|
||||
/** Last activity time */
|
||||
lastActivityAt: Date;
|
||||
/** Metadata */
|
||||
metadata?: Record<string, unknown>;
|
||||
}
|
||||
|
||||
/**
|
||||
* Task files specification
|
||||
*/
|
||||
export interface TaskFiles {
|
||||
/** Files to create */
|
||||
create?: string[];
|
||||
/** Files to modify */
|
||||
modify?: string[];
|
||||
/** Test files */
|
||||
test?: string[];
|
||||
}
|
||||
|
||||
/**
|
||||
* Plan step
|
||||
*/
|
||||
export interface PlanStep {
|
||||
/** Step number */
|
||||
number: number;
|
||||
/** Step description */
|
||||
description: string;
|
||||
/** Step type */
|
||||
type: 'test' | 'verify' | 'implement' | 'commit' | 'review';
|
||||
/** Code snippet (optional) */
|
||||
code?: string;
|
||||
/** Command to run (optional) */
|
||||
command?: string;
|
||||
/** Expected output (optional) */
|
||||
expectedOutput?: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* Task plan
|
||||
*/
|
||||
export interface TaskPlan {
|
||||
/** Plan steps */
|
||||
steps: PlanStep[];
|
||||
/** Estimated time in minutes */
|
||||
estimatedMinutes?: number;
|
||||
/** Plan submission time */
|
||||
submittedAt: Date;
|
||||
/** Plan approval time */
|
||||
approvedAt?: Date;
|
||||
/** Rejection reason */
|
||||
rejectionReason?: string;
|
||||
/** Approver ID */
|
||||
approvedBy?: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* Task result
|
||||
*/
|
||||
export interface TaskResult {
|
||||
/** Whether task succeeded */
|
||||
success: boolean;
|
||||
/** Output/summary */
|
||||
output: string;
|
||||
/** Files created */
|
||||
filesCreated?: string[];
|
||||
/** Files modified */
|
||||
filesModified?: string[];
|
||||
/** Test results */
|
||||
testResults?: TestResult[];
|
||||
/** Completion time */
|
||||
completedAt: Date;
|
||||
/** Errors if any */
|
||||
errors?: string[];
|
||||
}
|
||||
|
||||
/**
|
||||
* Test result
|
||||
*/
|
||||
export interface TestResult {
|
||||
/** Test name */
|
||||
name: string;
|
||||
/** Whether test passed */
|
||||
passed: boolean;
|
||||
/** Error message */
|
||||
error?: string;
|
||||
/** Duration in ms */
|
||||
durationMs?: number;
|
||||
}
|
||||
|
||||
/**
|
||||
* Task
|
||||
*/
|
||||
export interface Task {
|
||||
/** Unique task ID */
|
||||
id: string;
|
||||
/** Task name */
|
||||
name: string;
|
||||
/** Task description */
|
||||
description: string;
|
||||
/** Full specification */
|
||||
spec: string;
|
||||
/** Files involved */
|
||||
files: TaskFiles;
|
||||
/** Assigned agent ID */
|
||||
assignee?: string;
|
||||
/** Task status */
|
||||
status: OrchestratorTaskStatus;
|
||||
/** Task plan */
|
||||
plan?: TaskPlan;
|
||||
/** Task result */
|
||||
result?: TaskResult;
|
||||
/** Priority (higher = more important) */
|
||||
priority?: number;
|
||||
/** Dependencies (task IDs) */
|
||||
dependencies?: string[];
|
||||
/** Creation time */
|
||||
createdAt: Date;
|
||||
/** Last update time */
|
||||
updatedAt: Date;
|
||||
/** Metadata */
|
||||
metadata?: Record<string, unknown>;
|
||||
}
|
||||
|
||||
/**
|
||||
* Review issue
|
||||
*/
|
||||
export interface ReviewIssue {
|
||||
/** Issue severity */
|
||||
severity: IssueSeverity;
|
||||
/** Issue description */
|
||||
description: string;
|
||||
/** File path */
|
||||
file?: string;
|
||||
/** Line number */
|
||||
line?: number;
|
||||
/** Suggested fix */
|
||||
suggestion?: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* Review result
|
||||
*/
|
||||
export interface ReviewResult {
|
||||
/** Whether review passed */
|
||||
passed: boolean;
|
||||
/** Review issues */
|
||||
issues: ReviewIssue[];
|
||||
/** Summary */
|
||||
summary: string;
|
||||
/** Reviewer ID */
|
||||
reviewerId?: string;
|
||||
/** Review time */
|
||||
reviewedAt: Date;
|
||||
}
|
||||
|
||||
/**
|
||||
* Review stage
|
||||
*/
|
||||
export interface ReviewStage {
|
||||
/** Stage name */
|
||||
name: ReviewStageName;
|
||||
/** Stage prompt */
|
||||
prompt: string;
|
||||
/** Required to pass */
|
||||
required: boolean;
|
||||
/** Reviewer (leader or specific agent) */
|
||||
reviewer?: 'leader' | string;
|
||||
}
|
||||
|
||||
/**
|
||||
* Team message
|
||||
*/
|
||||
export interface TeamMessage {
|
||||
/** Message ID */
|
||||
id: string;
|
||||
/** Message type */
|
||||
type: MessageType;
|
||||
/** Sender agent ID */
|
||||
from: string;
|
||||
/** Recipient agent ID (for direct messages) */
|
||||
to?: string;
|
||||
/** Message content */
|
||||
content: string;
|
||||
/** Related task ID */
|
||||
taskId?: string;
|
||||
/** Metadata */
|
||||
metadata?: Record<string, unknown>;
|
||||
/** Timestamp */
|
||||
timestamp: Date;
|
||||
}
|
||||
|
||||
/**
|
||||
* Task filter
|
||||
*/
|
||||
export interface TaskFilter {
|
||||
/** Filter by status */
|
||||
status?: OrchestratorTaskStatus | OrchestratorTaskStatus[];
|
||||
/** Filter by assignee */
|
||||
assignee?: string;
|
||||
/** Filter by priority */
|
||||
minPriority?: number;
|
||||
/** Include completed tasks */
|
||||
includeCompleted?: boolean;
|
||||
}
|
||||
|
||||
/**
|
||||
* Team orchestrator options
|
||||
*/
|
||||
export interface OrchestratorOptions {
|
||||
/** Project path */
|
||||
projectPath: string;
|
||||
/** Default review stages */
|
||||
defaultReviewStages?: ReviewStage[];
|
||||
/** Require plan approval by default */
|
||||
requirePlanApproval?: boolean;
|
||||
/** Task timeout (ms) */
|
||||
taskTimeout?: number;
|
||||
/** Enable methodology integration */
|
||||
enableMethodology?: boolean;
|
||||
/** Verbose logging */
|
||||
verbose?: boolean;
|
||||
}
|
||||
|
||||
/**
|
||||
* Plan result
|
||||
*/
|
||||
export interface PlanResult {
|
||||
/** Whether all tasks completed */
|
||||
success: boolean;
|
||||
/** Task results */
|
||||
taskResults: Map<string, TaskResult>;
|
||||
/** Failed tasks */
|
||||
failedTasks: string[];
|
||||
/** Total duration (ms) */
|
||||
durationMs: number;
|
||||
}
|
||||
|
||||
/**
|
||||
* Message handler
|
||||
*/
|
||||
export type MessageHandler = (message: TeamMessage) => void | Promise<void>;
|
||||
|
||||
/**
|
||||
* Task event
|
||||
*/
|
||||
export type TaskEvent =
|
||||
| 'task:created'
|
||||
| 'task:assigned'
|
||||
| 'task:plan_submitted'
|
||||
| 'task:plan_approved'
|
||||
| 'task:plan_rejected'
|
||||
| 'task:started'
|
||||
| 'task:completed'
|
||||
| 'task:failed';
|
||||
|
||||
/**
|
||||
* Team event
|
||||
*/
|
||||
export type TeamEvent =
|
||||
| 'team:created'
|
||||
| 'team:teammate_spawned'
|
||||
| 'team:teammate_shutdown'
|
||||
| 'team:shutdown';
|
||||
|
||||
/**
|
||||
* Task event listener
|
||||
*/
|
||||
export type TaskEventListener = (event: TaskEvent, task: Task) => void | Promise<void>;
|
||||
|
||||
/**
|
||||
* Team event listener
|
||||
*/
|
||||
export type TeamEventListener = (event: TeamEvent, team: Team, agent?: AgentInstance) => void | Promise<void>;
|
||||
@@ -0,0 +1,853 @@
|
||||
/**
|
||||
* Plan System Tests
|
||||
*/
|
||||
|
||||
import { describe, it, expect, beforeEach } from 'vitest';
|
||||
import { PlanParser, createPlanParser } from '../parser.js';
|
||||
import { PlanValidator, createPlanValidator, validatePlan } from '../validator.js';
|
||||
import { PlanGenerator, createPlanGenerator, TASK_TEMPLATES } from '../generator.js';
|
||||
import { PlanExecutor, createPlanExecutor, dryRunExecutor } from '../executor.js';
|
||||
import type { StructuredPlan, PlanTask, TaskStep, PlanTaskResult } from '../types.js';
|
||||
|
||||
describe('PlanParser', () => {
|
||||
let parser: PlanParser;
|
||||
|
||||
beforeEach(() => {
|
||||
parser = createPlanParser();
|
||||
});
|
||||
|
||||
describe('parse', () => {
|
||||
it('should parse a simple plan', () => {
|
||||
const markdown = `
|
||||
# My Plan
|
||||
|
||||
Goal: Build a feature
|
||||
|
||||
## Task 1: Setup
|
||||
|
||||
1. Create files
|
||||
2. Write tests
|
||||
|
||||
## Task 2: Implement
|
||||
|
||||
1. Write code
|
||||
2. Run tests
|
||||
`;
|
||||
|
||||
const plan = parser.parse(markdown);
|
||||
|
||||
expect(plan.name).toBe('My Plan');
|
||||
expect(plan.goal).toBe('Build a feature');
|
||||
expect(plan.tasks).toHaveLength(2);
|
||||
expect(plan.tasks[0].name).toBe('Setup');
|
||||
expect(plan.tasks[0].steps).toHaveLength(2);
|
||||
expect(plan.tasks[1].name).toBe('Implement');
|
||||
});
|
||||
|
||||
it('should parse task with files', () => {
|
||||
const markdown = `
|
||||
# Plan
|
||||
|
||||
Goal: Test
|
||||
|
||||
## Task 1: Create Component
|
||||
|
||||
Files:
|
||||
- Create: \`src/component.ts\`
|
||||
- Modify: \`src/index.ts\`
|
||||
- Test: \`src/__tests__/component.test.ts\`
|
||||
|
||||
1. Create the component
|
||||
`;
|
||||
|
||||
const plan = parser.parse(markdown);
|
||||
|
||||
expect(plan.tasks[0].files.create).toContain('src/component.ts');
|
||||
expect(plan.tasks[0].files.modify).toContain('src/index.ts');
|
||||
expect(plan.tasks[0].files.test).toContain('src/__tests__/component.test.ts');
|
||||
});
|
||||
|
||||
it('should parse task metadata', () => {
|
||||
const markdown = `
|
||||
# Plan
|
||||
|
||||
Goal: Test
|
||||
|
||||
## Task 1: Setup
|
||||
|
||||
Estimated: 5 minutes
|
||||
Depends on: 2, 3
|
||||
Priority: 10
|
||||
Tags: setup, init
|
||||
|
||||
1. Do something
|
||||
`;
|
||||
|
||||
const plan = parser.parse(markdown);
|
||||
|
||||
expect(plan.tasks[0].estimatedMinutes).toBe(5);
|
||||
expect(plan.tasks[0].dependencies).toEqual([2, 3]);
|
||||
expect(plan.tasks[0].priority).toBe(10);
|
||||
expect(plan.tasks[0].tags).toContain('setup');
|
||||
});
|
||||
|
||||
it('should parse code blocks in steps', () => {
|
||||
const markdown = `
|
||||
# Plan
|
||||
|
||||
Goal: Test
|
||||
|
||||
## Task 1: Implement
|
||||
|
||||
1. Write the function
|
||||
|
||||
\`\`\`typescript
|
||||
function hello() {
|
||||
return 'world';
|
||||
}
|
||||
\`\`\`
|
||||
`;
|
||||
|
||||
const plan = parser.parse(markdown);
|
||||
|
||||
expect(plan.tasks[0].steps[0].code).toContain('function hello()');
|
||||
expect(plan.tasks[0].steps[0].language).toBe('typescript');
|
||||
});
|
||||
|
||||
it('should parse step commands and expected output', () => {
|
||||
const markdown = `
|
||||
# Plan
|
||||
|
||||
Goal: Test
|
||||
|
||||
## Task 1: Test
|
||||
|
||||
1. Run the tests
|
||||
- Run: npm test
|
||||
- Expect: All tests pass
|
||||
- Critical
|
||||
`;
|
||||
|
||||
const plan = parser.parse(markdown);
|
||||
|
||||
expect(plan.tasks[0].steps[0].command).toBe('npm test');
|
||||
expect(plan.tasks[0].steps[0].expectedOutput).toBe('All tests pass');
|
||||
expect(plan.tasks[0].steps[0].critical).toBe(true);
|
||||
});
|
||||
|
||||
it('should infer step types', () => {
|
||||
const markdown = `
|
||||
# Plan
|
||||
|
||||
Goal: Test
|
||||
|
||||
## Task 1: Development
|
||||
|
||||
1. Write tests for the feature
|
||||
2. Verify the implementation
|
||||
3. Implement the feature
|
||||
4. Commit the changes
|
||||
`;
|
||||
|
||||
const plan = parser.parse(markdown);
|
||||
|
||||
expect(plan.tasks[0].steps[0].type).toBe('test');
|
||||
expect(plan.tasks[0].steps[1].type).toBe('verify');
|
||||
expect(plan.tasks[0].steps[2].type).toBe('implement');
|
||||
expect(plan.tasks[0].steps[3].type).toBe('commit');
|
||||
});
|
||||
|
||||
it('should parse plan metadata', () => {
|
||||
const markdown = `
|
||||
# My Project Plan
|
||||
|
||||
Version: 1.0.0
|
||||
Author: John Doe
|
||||
Design Doc: https://example.com/design
|
||||
|
||||
Goal: Complete the project
|
||||
|
||||
## Architecture
|
||||
|
||||
Microservices with REST APIs
|
||||
|
||||
## Tech Stack
|
||||
|
||||
- TypeScript
|
||||
- React
|
||||
- Node.js
|
||||
|
||||
## Task 1: Setup
|
||||
|
||||
1. Initialize project
|
||||
`;
|
||||
|
||||
const plan = parser.parse(markdown);
|
||||
|
||||
expect(plan.version).toBe('1.0.0');
|
||||
expect(plan.author).toBe('John Doe');
|
||||
expect(plan.designDoc).toBe('https://example.com/design');
|
||||
expect(plan.architecture).toContain('Microservices');
|
||||
expect(plan.techStack).toContain('TypeScript');
|
||||
expect(plan.techStack).toContain('React');
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
describe('PlanValidator', () => {
|
||||
let validator: PlanValidator;
|
||||
|
||||
beforeEach(() => {
|
||||
validator = createPlanValidator();
|
||||
});
|
||||
|
||||
describe('validate', () => {
|
||||
it('should validate a valid plan', () => {
|
||||
const plan: StructuredPlan = {
|
||||
name: 'Valid Plan',
|
||||
goal: 'Complete tasks',
|
||||
tasks: [
|
||||
{
|
||||
id: 1,
|
||||
name: 'Task 1',
|
||||
files: {},
|
||||
steps: [{ number: 1, description: 'Do something', type: 'implement' }],
|
||||
},
|
||||
],
|
||||
status: 'ready',
|
||||
createdAt: new Date(),
|
||||
};
|
||||
|
||||
const result = validator.validate(plan);
|
||||
|
||||
expect(result.valid).toBe(true);
|
||||
expect(result.issues.filter((i) => i.type === 'error')).toHaveLength(0);
|
||||
});
|
||||
|
||||
it('should detect missing name', () => {
|
||||
const plan: StructuredPlan = {
|
||||
name: '',
|
||||
goal: 'Complete tasks',
|
||||
tasks: [
|
||||
{
|
||||
id: 1,
|
||||
name: 'Task 1',
|
||||
files: {},
|
||||
steps: [{ number: 1, description: 'Do something', type: 'implement' }],
|
||||
},
|
||||
],
|
||||
status: 'draft',
|
||||
createdAt: new Date(),
|
||||
};
|
||||
|
||||
const result = validator.validate(plan);
|
||||
|
||||
expect(result.valid).toBe(false);
|
||||
expect(result.issues.some((i) => i.message.includes('name'))).toBe(true);
|
||||
});
|
||||
|
||||
it('should detect missing goal', () => {
|
||||
const plan: StructuredPlan = {
|
||||
name: 'Plan',
|
||||
goal: '',
|
||||
tasks: [
|
||||
{
|
||||
id: 1,
|
||||
name: 'Task 1',
|
||||
files: {},
|
||||
steps: [{ number: 1, description: 'Do something', type: 'implement' }],
|
||||
},
|
||||
],
|
||||
status: 'draft',
|
||||
createdAt: new Date(),
|
||||
};
|
||||
|
||||
const result = validator.validate(plan);
|
||||
|
||||
expect(result.valid).toBe(false);
|
||||
expect(result.issues.some((i) => i.message.includes('goal'))).toBe(true);
|
||||
});
|
||||
|
||||
it('should detect empty tasks', () => {
|
||||
const plan: StructuredPlan = {
|
||||
name: 'Plan',
|
||||
goal: 'Goal',
|
||||
tasks: [],
|
||||
status: 'draft',
|
||||
createdAt: new Date(),
|
||||
};
|
||||
|
||||
const result = validator.validate(plan);
|
||||
|
||||
expect(result.valid).toBe(false);
|
||||
expect(result.issues.some((i) => i.message.includes('at least one task'))).toBe(true);
|
||||
});
|
||||
|
||||
it('should detect duplicate task IDs', () => {
|
||||
const plan: StructuredPlan = {
|
||||
name: 'Plan',
|
||||
goal: 'Goal',
|
||||
tasks: [
|
||||
{
|
||||
id: 1,
|
||||
name: 'Task 1',
|
||||
files: {},
|
||||
steps: [{ number: 1, description: 'Do something', type: 'implement' }],
|
||||
},
|
||||
{
|
||||
id: 1,
|
||||
name: 'Task 2',
|
||||
files: {},
|
||||
steps: [{ number: 1, description: 'Do something', type: 'implement' }],
|
||||
},
|
||||
],
|
||||
status: 'draft',
|
||||
createdAt: new Date(),
|
||||
};
|
||||
|
||||
const result = validator.validate(plan);
|
||||
|
||||
expect(result.valid).toBe(false);
|
||||
expect(result.issues.some((i) => i.message.includes('Duplicate task ID'))).toBe(true);
|
||||
});
|
||||
|
||||
it('should detect missing dependencies', () => {
|
||||
const plan: StructuredPlan = {
|
||||
name: 'Plan',
|
||||
goal: 'Goal',
|
||||
tasks: [
|
||||
{
|
||||
id: 1,
|
||||
name: 'Task 1',
|
||||
files: {},
|
||||
steps: [{ number: 1, description: 'Do something', type: 'implement' }],
|
||||
dependencies: [999],
|
||||
},
|
||||
],
|
||||
status: 'draft',
|
||||
createdAt: new Date(),
|
||||
};
|
||||
|
||||
const result = validator.validate(plan);
|
||||
|
||||
expect(result.valid).toBe(false);
|
||||
expect(result.issues.some((i) => i.message.includes('non-existent task'))).toBe(true);
|
||||
});
|
||||
|
||||
it('should detect circular dependencies', () => {
|
||||
const plan: StructuredPlan = {
|
||||
name: 'Plan',
|
||||
goal: 'Goal',
|
||||
tasks: [
|
||||
{
|
||||
id: 1,
|
||||
name: 'Task 1',
|
||||
files: {},
|
||||
steps: [{ number: 1, description: 'Do something', type: 'implement' }],
|
||||
dependencies: [2],
|
||||
},
|
||||
{
|
||||
id: 2,
|
||||
name: 'Task 2',
|
||||
files: {},
|
||||
steps: [{ number: 1, description: 'Do something', type: 'implement' }],
|
||||
dependencies: [1],
|
||||
},
|
||||
],
|
||||
status: 'draft',
|
||||
createdAt: new Date(),
|
||||
};
|
||||
|
||||
const result = validator.validate(plan);
|
||||
|
||||
expect(result.valid).toBe(false);
|
||||
expect(result.issues.some((i) => i.message.includes('Circular dependency'))).toBe(true);
|
||||
});
|
||||
|
||||
it('should calculate statistics', () => {
|
||||
const plan: StructuredPlan = {
|
||||
name: 'Plan',
|
||||
goal: 'Goal',
|
||||
tasks: [
|
||||
{
|
||||
id: 1,
|
||||
name: 'Task 1',
|
||||
files: { test: ['test.ts'] },
|
||||
steps: [
|
||||
{ number: 1, description: 'Test', type: 'test' },
|
||||
{ number: 2, description: 'Implement', type: 'implement' },
|
||||
{ number: 3, description: 'Commit', type: 'commit' },
|
||||
],
|
||||
estimatedMinutes: 5,
|
||||
},
|
||||
{
|
||||
id: 2,
|
||||
name: 'Task 2',
|
||||
files: {},
|
||||
steps: [
|
||||
{ number: 1, description: 'Implement', type: 'implement' },
|
||||
{ number: 2, description: 'Verify', type: 'verify' },
|
||||
],
|
||||
estimatedMinutes: 3,
|
||||
},
|
||||
],
|
||||
status: 'ready',
|
||||
createdAt: new Date(),
|
||||
};
|
||||
|
||||
const result = validator.validate(plan);
|
||||
|
||||
expect(result.stats.totalTasks).toBe(2);
|
||||
expect(result.stats.totalSteps).toBe(5);
|
||||
expect(result.stats.estimatedMinutes).toBe(8);
|
||||
expect(result.stats.tasksWithTests).toBe(1);
|
||||
expect(result.stats.tasksWithCommits).toBe(1);
|
||||
expect(result.stats.avgStepsPerTask).toBe(2.5);
|
||||
});
|
||||
});
|
||||
|
||||
describe('isValid', () => {
|
||||
it('should return true for valid plan', () => {
|
||||
const plan: StructuredPlan = {
|
||||
name: 'Plan',
|
||||
goal: 'Goal',
|
||||
tasks: [
|
||||
{
|
||||
id: 1,
|
||||
name: 'Task',
|
||||
files: {},
|
||||
steps: [{ number: 1, description: 'Do', type: 'implement' }],
|
||||
},
|
||||
],
|
||||
status: 'ready',
|
||||
createdAt: new Date(),
|
||||
};
|
||||
|
||||
expect(validator.isValid(plan)).toBe(true);
|
||||
});
|
||||
});
|
||||
|
||||
describe('strict mode', () => {
|
||||
it('should treat warnings as errors in strict mode', () => {
|
||||
const strictValidator = createPlanValidator({ strict: true, requireTests: true });
|
||||
|
||||
const plan: StructuredPlan = {
|
||||
name: 'Plan',
|
||||
goal: 'Goal',
|
||||
tasks: [
|
||||
{
|
||||
id: 1,
|
||||
name: 'Task',
|
||||
files: {},
|
||||
steps: [{ number: 1, description: 'Implement', type: 'implement' }],
|
||||
},
|
||||
],
|
||||
status: 'ready',
|
||||
createdAt: new Date(),
|
||||
};
|
||||
|
||||
const result = strictValidator.validate(plan);
|
||||
|
||||
expect(result.valid).toBe(false);
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
describe('PlanGenerator', () => {
|
||||
let generator: PlanGenerator;
|
||||
|
||||
beforeEach(() => {
|
||||
generator = createPlanGenerator();
|
||||
});
|
||||
|
||||
describe('createPlan', () => {
|
||||
it('should create an empty plan', () => {
|
||||
const plan = generator.createPlan('My Plan', 'Build something');
|
||||
|
||||
expect(plan.name).toBe('My Plan');
|
||||
expect(plan.goal).toBe('Build something');
|
||||
expect(plan.tasks).toHaveLength(0);
|
||||
expect(plan.status).toBe('draft');
|
||||
});
|
||||
});
|
||||
|
||||
describe('addTask', () => {
|
||||
it('should add a task to the plan', () => {
|
||||
const plan = generator.createPlan('Plan', 'Goal');
|
||||
const task = generator.addTask(plan, 'First Task', {
|
||||
description: 'Do something',
|
||||
steps: [{ description: 'Step 1', type: 'implement' }],
|
||||
});
|
||||
|
||||
expect(plan.tasks).toHaveLength(1);
|
||||
expect(task.id).toBe(1);
|
||||
expect(task.name).toBe('First Task');
|
||||
});
|
||||
|
||||
it('should auto-add test and commit steps', () => {
|
||||
const plan = generator.createPlan('Plan', 'Goal');
|
||||
const task = generator.addTask(plan, 'Task', {
|
||||
steps: [{ description: 'Implement', type: 'implement' }],
|
||||
});
|
||||
|
||||
expect(task.steps.some((s) => s.type === 'test')).toBe(true);
|
||||
expect(task.steps.some((s) => s.type === 'commit')).toBe(true);
|
||||
});
|
||||
|
||||
it('should increment task IDs', () => {
|
||||
const plan = generator.createPlan('Plan', 'Goal');
|
||||
generator.addTask(plan, 'Task 1');
|
||||
generator.addTask(plan, 'Task 2');
|
||||
generator.addTask(plan, 'Task 3');
|
||||
|
||||
expect(plan.tasks.map((t) => t.id)).toEqual([1, 2, 3]);
|
||||
});
|
||||
});
|
||||
|
||||
describe('addTaskFromTemplate', () => {
|
||||
it('should add task from template', () => {
|
||||
const plan = generator.createPlan('Plan', 'Goal');
|
||||
const task = generator.addTaskFromTemplate(plan, 'create-component', {
|
||||
name: 'Create Header',
|
||||
});
|
||||
|
||||
expect(task).toBeDefined();
|
||||
expect(task?.name).toBe('Create Header');
|
||||
expect(task?.steps.length).toBeGreaterThan(0);
|
||||
});
|
||||
|
||||
it('should return undefined for unknown template', () => {
|
||||
const plan = generator.createPlan('Plan', 'Goal');
|
||||
const task = generator.addTaskFromTemplate(plan, 'unknown-template');
|
||||
|
||||
expect(task).toBeUndefined();
|
||||
});
|
||||
});
|
||||
|
||||
describe('toMarkdown', () => {
|
||||
it('should generate markdown from plan', () => {
|
||||
const plan = generator.createPlan('My Project', 'Build a feature');
|
||||
plan.architecture = 'Microservices';
|
||||
plan.techStack = ['TypeScript', 'React'];
|
||||
|
||||
generator.addTask(plan, 'Setup', {
|
||||
description: 'Initialize the project',
|
||||
files: { create: ['src/index.ts'] },
|
||||
steps: [{ description: 'Create files', type: 'implement' }],
|
||||
estimatedMinutes: 5,
|
||||
});
|
||||
|
||||
const markdown = generator.toMarkdown(plan);
|
||||
|
||||
expect(markdown).toContain('# My Project');
|
||||
expect(markdown).toContain('Build a feature');
|
||||
expect(markdown).toContain('## Architecture');
|
||||
expect(markdown).toContain('Microservices');
|
||||
expect(markdown).toContain('- TypeScript');
|
||||
expect(markdown).toContain('### Task 1: Setup');
|
||||
expect(markdown).toContain('Create files');
|
||||
});
|
||||
});
|
||||
|
||||
describe('fromTaskList', () => {
|
||||
it('should generate plan from task list', () => {
|
||||
const plan = generator.fromTaskList('Feature', 'Add authentication', ['Setup', 'Login', 'Logout']);
|
||||
|
||||
expect(plan.name).toBe('Feature');
|
||||
expect(plan.tasks).toHaveLength(3);
|
||||
expect(plan.tasks[0].name).toBe('Setup');
|
||||
expect(plan.tasks[1].name).toBe('Login');
|
||||
expect(plan.tasks[2].name).toBe('Logout');
|
||||
});
|
||||
|
||||
it('should set dependencies between tasks', () => {
|
||||
const plan = generator.fromTaskList('Feature', 'Goal', ['A', 'B', 'C']);
|
||||
|
||||
expect(plan.tasks[0].dependencies).toBeUndefined();
|
||||
expect(plan.tasks[1].dependencies).toEqual([1]);
|
||||
expect(plan.tasks[2].dependencies).toEqual([2]);
|
||||
});
|
||||
});
|
||||
|
||||
describe('clonePlan', () => {
|
||||
it('should clone a plan', () => {
|
||||
const original = generator.createPlan('Original', 'Goal');
|
||||
generator.addTask(original, 'Task 1');
|
||||
|
||||
const clone = generator.clonePlan(original, 'Clone');
|
||||
|
||||
expect(clone.name).toBe('Clone');
|
||||
expect(clone.tasks).toHaveLength(1);
|
||||
expect(clone.status).toBe('draft');
|
||||
expect(clone.createdAt).not.toBe(original.createdAt);
|
||||
});
|
||||
});
|
||||
|
||||
describe('mergePlans', () => {
|
||||
it('should merge two plans', () => {
|
||||
const plan1 = generator.createPlan('Plan 1', 'Goal 1');
|
||||
generator.addTask(plan1, 'Task 1');
|
||||
|
||||
const plan2 = generator.createPlan('Plan 2', 'Goal 2');
|
||||
generator.addTask(plan2, 'Task 2');
|
||||
|
||||
const merged = generator.mergePlans(plan1, plan2);
|
||||
|
||||
expect(merged.tasks).toHaveLength(2);
|
||||
expect(merged.tasks[0].name).toBe('Task 1');
|
||||
expect(merged.tasks[1].name).toBe('Task 2');
|
||||
expect(merged.tasks[1].id).toBe(2); // Offset ID
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
describe('PlanExecutor', () => {
|
||||
let executor: PlanExecutor;
|
||||
|
||||
beforeEach(() => {
|
||||
executor = createPlanExecutor({ stepExecutor: dryRunExecutor });
|
||||
});
|
||||
|
||||
describe('execute', () => {
|
||||
it('should execute a plan', async () => {
|
||||
const plan: StructuredPlan = {
|
||||
name: 'Plan',
|
||||
goal: 'Goal',
|
||||
tasks: [
|
||||
{
|
||||
id: 1,
|
||||
name: 'Task 1',
|
||||
files: {},
|
||||
steps: [{ number: 1, description: 'Step 1', type: 'implement' }],
|
||||
},
|
||||
],
|
||||
status: 'ready',
|
||||
createdAt: new Date(),
|
||||
};
|
||||
|
||||
const result = await executor.execute(plan, { dryRun: true });
|
||||
|
||||
expect(result.success).toBe(true);
|
||||
expect(result.completedTasks).toContain(1);
|
||||
expect(result.failedTasks).toHaveLength(0);
|
||||
expect(plan.status).toBe('completed');
|
||||
});
|
||||
|
||||
it('should execute tasks in dependency order', async () => {
|
||||
const executionOrder: number[] = [];
|
||||
|
||||
const trackingExecutor = createPlanExecutor({
|
||||
stepExecutor: async (_step, task) => {
|
||||
executionOrder.push(task.id);
|
||||
return { success: true, output: 'done' };
|
||||
},
|
||||
});
|
||||
|
||||
const plan: StructuredPlan = {
|
||||
name: 'Plan',
|
||||
goal: 'Goal',
|
||||
tasks: [
|
||||
{
|
||||
id: 3,
|
||||
name: 'Task 3',
|
||||
files: {},
|
||||
steps: [{ number: 1, description: 'Step', type: 'implement' }],
|
||||
dependencies: [1, 2],
|
||||
},
|
||||
{
|
||||
id: 1,
|
||||
name: 'Task 1',
|
||||
files: {},
|
||||
steps: [{ number: 1, description: 'Step', type: 'implement' }],
|
||||
},
|
||||
{
|
||||
id: 2,
|
||||
name: 'Task 2',
|
||||
files: {},
|
||||
steps: [{ number: 1, description: 'Step', type: 'implement' }],
|
||||
dependencies: [1],
|
||||
},
|
||||
],
|
||||
status: 'ready',
|
||||
createdAt: new Date(),
|
||||
};
|
||||
|
||||
await trackingExecutor.execute(plan);
|
||||
|
||||
expect(executionOrder).toEqual([1, 2, 3]);
|
||||
});
|
||||
|
||||
it('should skip tasks with failed dependencies', async () => {
|
||||
const failingExecutor = createPlanExecutor({
|
||||
stepExecutor: async (_step, task) => {
|
||||
if (task.id === 1) {
|
||||
return { success: false, output: 'failed', error: 'Error' };
|
||||
}
|
||||
return { success: true, output: 'done' };
|
||||
},
|
||||
});
|
||||
|
||||
const plan: StructuredPlan = {
|
||||
name: 'Plan',
|
||||
goal: 'Goal',
|
||||
tasks: [
|
||||
{
|
||||
id: 1,
|
||||
name: 'Task 1',
|
||||
files: {},
|
||||
steps: [{ number: 1, description: 'Step', type: 'implement' }],
|
||||
},
|
||||
{
|
||||
id: 2,
|
||||
name: 'Task 2',
|
||||
files: {},
|
||||
steps: [{ number: 1, description: 'Step', type: 'implement' }],
|
||||
dependencies: [1],
|
||||
},
|
||||
],
|
||||
status: 'ready',
|
||||
createdAt: new Date(),
|
||||
};
|
||||
|
||||
const result = await failingExecutor.execute(plan, { stopOnError: false });
|
||||
|
||||
expect(result.failedTasks).toContain(1);
|
||||
expect(result.skippedTasks).toContain(2);
|
||||
});
|
||||
|
||||
it('should emit events', async () => {
|
||||
const events: string[] = [];
|
||||
|
||||
executor.addListener((event) => {
|
||||
events.push(event);
|
||||
});
|
||||
|
||||
const plan: StructuredPlan = {
|
||||
name: 'Plan',
|
||||
goal: 'Goal',
|
||||
tasks: [
|
||||
{
|
||||
id: 1,
|
||||
name: 'Task 1',
|
||||
files: {},
|
||||
steps: [{ number: 1, description: 'Step', type: 'implement' }],
|
||||
},
|
||||
],
|
||||
status: 'ready',
|
||||
createdAt: new Date(),
|
||||
};
|
||||
|
||||
await executor.execute(plan, { dryRun: true });
|
||||
|
||||
expect(events).toContain('plan:execution_started');
|
||||
expect(events).toContain('plan:task_started');
|
||||
expect(events).toContain('plan:task_completed');
|
||||
expect(events).toContain('plan:execution_completed');
|
||||
});
|
||||
});
|
||||
|
||||
describe('pause/resume', () => {
|
||||
it('should support pause and resume', async () => {
|
||||
let pauseDetected = false;
|
||||
|
||||
const slowExecutor = createPlanExecutor({
|
||||
stepExecutor: async () => {
|
||||
await new Promise((resolve) => setTimeout(resolve, 50));
|
||||
return { success: true, output: 'done' };
|
||||
},
|
||||
});
|
||||
|
||||
const plan: StructuredPlan = {
|
||||
name: 'Plan',
|
||||
goal: 'Goal',
|
||||
tasks: [
|
||||
{
|
||||
id: 1,
|
||||
name: 'Task 1',
|
||||
files: {},
|
||||
steps: [
|
||||
{ number: 1, description: 'Step 1', type: 'implement' },
|
||||
{ number: 2, description: 'Step 2', type: 'implement' },
|
||||
],
|
||||
},
|
||||
],
|
||||
status: 'ready',
|
||||
createdAt: new Date(),
|
||||
};
|
||||
|
||||
const executePromise = slowExecutor.execute(plan);
|
||||
|
||||
// Pause after a short delay
|
||||
setTimeout(() => {
|
||||
slowExecutor.pause();
|
||||
pauseDetected = slowExecutor.isPausedState();
|
||||
slowExecutor.resume();
|
||||
}, 25);
|
||||
|
||||
const result = await executePromise;
|
||||
|
||||
expect(result.success).toBe(true);
|
||||
// Note: pauseDetected may or may not be true depending on timing
|
||||
});
|
||||
});
|
||||
|
||||
describe('cancel', () => {
|
||||
it('should support cancellation', async () => {
|
||||
const slowExecutor = createPlanExecutor({
|
||||
stepExecutor: async () => {
|
||||
await new Promise((resolve) => setTimeout(resolve, 100));
|
||||
return { success: true, output: 'done' };
|
||||
},
|
||||
});
|
||||
|
||||
const plan: StructuredPlan = {
|
||||
name: 'Plan',
|
||||
goal: 'Goal',
|
||||
tasks: [
|
||||
{
|
||||
id: 1,
|
||||
name: 'Task 1',
|
||||
files: {},
|
||||
steps: [
|
||||
{ number: 1, description: 'Step 1', type: 'implement' },
|
||||
{ number: 2, description: 'Step 2', type: 'implement' },
|
||||
],
|
||||
},
|
||||
],
|
||||
status: 'ready',
|
||||
createdAt: new Date(),
|
||||
};
|
||||
|
||||
const executePromise = slowExecutor.execute(plan);
|
||||
|
||||
// Cancel after a short delay
|
||||
setTimeout(() => {
|
||||
slowExecutor.cancel();
|
||||
}, 10);
|
||||
|
||||
const result = await executePromise;
|
||||
|
||||
expect(result.success).toBe(false);
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
describe('TASK_TEMPLATES', () => {
|
||||
it('should have required templates', () => {
|
||||
expect(TASK_TEMPLATES['create-component']).toBeDefined();
|
||||
expect(TASK_TEMPLATES['add-api-endpoint']).toBeDefined();
|
||||
expect(TASK_TEMPLATES['fix-bug']).toBeDefined();
|
||||
expect(TASK_TEMPLATES['add-feature']).toBeDefined();
|
||||
expect(TASK_TEMPLATES['refactor']).toBeDefined();
|
||||
});
|
||||
|
||||
it('should have valid template structure', () => {
|
||||
for (const [name, template] of Object.entries(TASK_TEMPLATES)) {
|
||||
expect(template.name).toBeDefined();
|
||||
expect(template.description).toBeDefined();
|
||||
expect(template.steps).toBeDefined();
|
||||
expect(template.steps.length).toBeGreaterThan(0);
|
||||
expect(template.estimatedMinutes).toBeGreaterThan(0);
|
||||
}
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,478 @@
|
||||
/**
|
||||
* Plan Executor
|
||||
*
|
||||
* Executes structured plans with progress tracking and event handling.
|
||||
*/
|
||||
|
||||
import type {
|
||||
StructuredPlan,
|
||||
PlanTask,
|
||||
TaskStep,
|
||||
PlanTaskResult,
|
||||
PlanExecutionOptions,
|
||||
PlanExecutionResult,
|
||||
PlanEvent,
|
||||
PlanEventListener,
|
||||
} from './types.js';
|
||||
|
||||
/**
|
||||
* Step executor function type
|
||||
*/
|
||||
export type StepExecutor = (
|
||||
step: TaskStep,
|
||||
task: PlanTask,
|
||||
plan: StructuredPlan
|
||||
) => Promise<{ success: boolean; output: string; error?: string }>;
|
||||
|
||||
/**
|
||||
* PlanExecutor - Execute structured plans
|
||||
*/
|
||||
export class PlanExecutor {
|
||||
private listeners: Set<PlanEventListener> = new Set();
|
||||
private stepExecutor?: StepExecutor;
|
||||
private abortController?: AbortController;
|
||||
private isPaused = false;
|
||||
private resumePromise?: Promise<void>;
|
||||
private resumeResolve?: () => void;
|
||||
|
||||
constructor(options?: { stepExecutor?: StepExecutor }) {
|
||||
this.stepExecutor = options?.stepExecutor;
|
||||
}
|
||||
|
||||
/**
|
||||
* Set the step executor
|
||||
*/
|
||||
setStepExecutor(executor: StepExecutor): void {
|
||||
this.stepExecutor = executor;
|
||||
}
|
||||
|
||||
/**
|
||||
* Execute a plan
|
||||
*/
|
||||
async execute(plan: StructuredPlan, options?: PlanExecutionOptions): Promise<PlanExecutionResult> {
|
||||
const startTime = Date.now();
|
||||
let aborted = false;
|
||||
const result: PlanExecutionResult = {
|
||||
success: true,
|
||||
completedTasks: [],
|
||||
failedTasks: [],
|
||||
skippedTasks: [],
|
||||
durationMs: 0,
|
||||
taskResults: new Map(),
|
||||
};
|
||||
|
||||
// Initialize abort controller
|
||||
this.abortController = new AbortController();
|
||||
this.isPaused = false;
|
||||
|
||||
// Update plan status
|
||||
plan.status = 'executing';
|
||||
this.emit('plan:execution_started', plan);
|
||||
|
||||
try {
|
||||
// Build dependency graph
|
||||
const dependencyGraph = this.buildDependencyGraph(plan);
|
||||
|
||||
// Get execution order
|
||||
const executionOrder = this.getExecutionOrder(plan, dependencyGraph);
|
||||
|
||||
// Execute tasks
|
||||
for (const taskId of executionOrder) {
|
||||
// Check if aborted
|
||||
if (this.abortController.signal.aborted) {
|
||||
aborted = true;
|
||||
result.success = false;
|
||||
result.errors = [...(result.errors ?? []), 'Execution cancelled'];
|
||||
break;
|
||||
}
|
||||
|
||||
// Wait if paused
|
||||
await this.waitIfPaused();
|
||||
|
||||
// Re-check if aborted after resuming from pause
|
||||
if (this.abortController.signal.aborted) {
|
||||
aborted = true;
|
||||
result.success = false;
|
||||
result.errors = [...(result.errors ?? []), 'Execution cancelled'];
|
||||
break;
|
||||
}
|
||||
|
||||
const task = plan.tasks.find((t) => t.id === taskId);
|
||||
if (!task) continue;
|
||||
|
||||
// Check if dependencies completed
|
||||
const depsCompleted = this.checkDependencies(task, result);
|
||||
if (!depsCompleted) {
|
||||
task.status = 'skipped';
|
||||
result.skippedTasks.push(taskId);
|
||||
continue;
|
||||
}
|
||||
|
||||
// Execute task
|
||||
const taskResult = await this.executeTask(task, plan, options);
|
||||
result.taskResults.set(taskId, taskResult);
|
||||
|
||||
if (taskResult.success) {
|
||||
task.status = 'completed';
|
||||
task.result = taskResult;
|
||||
result.completedTasks.push(taskId);
|
||||
this.emit('plan:task_completed', plan, task, taskResult);
|
||||
} else {
|
||||
task.status = 'failed';
|
||||
task.result = taskResult;
|
||||
result.failedTasks.push(taskId);
|
||||
result.success = false;
|
||||
this.emit('plan:task_failed', plan, task, taskResult);
|
||||
|
||||
if (options?.stopOnError) {
|
||||
// Mark remaining tasks as skipped
|
||||
for (const remainingId of executionOrder.slice(executionOrder.indexOf(taskId) + 1)) {
|
||||
const remainingTask = plan.tasks.find((t) => t.id === remainingId);
|
||||
if (remainingTask) {
|
||||
remainingTask.status = 'skipped';
|
||||
result.skippedTasks.push(remainingId);
|
||||
}
|
||||
}
|
||||
break;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Update plan status
|
||||
plan.status = aborted ? 'cancelled' : result.success ? 'completed' : 'failed';
|
||||
plan.updatedAt = new Date();
|
||||
|
||||
result.durationMs = Date.now() - startTime;
|
||||
|
||||
// Emit appropriate event
|
||||
if (aborted) {
|
||||
this.emit('plan:execution_cancelled', plan);
|
||||
} else if (result.success) {
|
||||
this.emit('plan:execution_completed', plan);
|
||||
} else {
|
||||
this.emit('plan:execution_failed', plan);
|
||||
}
|
||||
|
||||
return result;
|
||||
} catch (error) {
|
||||
plan.status = 'failed';
|
||||
result.success = false;
|
||||
result.durationMs = Date.now() - startTime;
|
||||
result.errors = [(error as Error).message];
|
||||
|
||||
this.emit('plan:execution_failed', plan);
|
||||
return result;
|
||||
} finally {
|
||||
// Reset executor state
|
||||
this.abortController = undefined;
|
||||
this.isPaused = false;
|
||||
this.resumePromise = undefined;
|
||||
this.resumeResolve = undefined;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Execute a single task
|
||||
*/
|
||||
private async executeTask(
|
||||
task: PlanTask,
|
||||
plan: StructuredPlan,
|
||||
options?: PlanExecutionOptions
|
||||
): Promise<PlanTaskResult> {
|
||||
const startTime = Date.now();
|
||||
const errors: string[] = [];
|
||||
const filesCreated: string[] = [];
|
||||
const filesModified: string[] = [];
|
||||
|
||||
task.status = 'in_progress';
|
||||
this.emit('plan:task_started', plan, task);
|
||||
|
||||
// Report progress
|
||||
options?.onProgress?.(task.id, 0, 'starting');
|
||||
|
||||
// Execute steps
|
||||
for (let i = 0; i < task.steps.length; i++) {
|
||||
const step = task.steps[i];
|
||||
|
||||
// Check if aborted
|
||||
if (this.abortController?.signal.aborted) {
|
||||
errors.push('Execution aborted');
|
||||
break;
|
||||
}
|
||||
|
||||
// Wait if paused
|
||||
await this.waitIfPaused();
|
||||
|
||||
// Re-check if aborted after resuming from pause
|
||||
if (this.abortController?.signal.aborted) {
|
||||
errors.push('Execution aborted');
|
||||
break;
|
||||
}
|
||||
|
||||
// Report progress
|
||||
options?.onProgress?.(task.id, step.number, `executing step ${step.number}`);
|
||||
|
||||
// Execute step
|
||||
if (options?.dryRun) {
|
||||
// Dry run - just log
|
||||
console.log(`[DRY RUN] Task ${task.id}, Step ${step.number}: ${step.description}`);
|
||||
if (step.command) {
|
||||
console.log(` Command: ${step.command}`);
|
||||
}
|
||||
if (step.code) {
|
||||
console.log(` Code: ${step.code.substring(0, 100)}...`);
|
||||
}
|
||||
} else if (this.stepExecutor) {
|
||||
try {
|
||||
const stepResult = await this.executeWithTimeout(
|
||||
this.stepExecutor(step, task, plan),
|
||||
options?.taskTimeout || 60000
|
||||
);
|
||||
|
||||
if (!stepResult.success) {
|
||||
errors.push(`Step ${step.number}: ${stepResult.error || 'Failed'}`);
|
||||
|
||||
if (step.critical) {
|
||||
break;
|
||||
}
|
||||
}
|
||||
} catch (error) {
|
||||
errors.push(`Step ${step.number}: ${(error as Error).message}`);
|
||||
|
||||
if (step.critical) {
|
||||
break;
|
||||
}
|
||||
}
|
||||
} else {
|
||||
// No step executor configured - fail fast
|
||||
errors.push('No step executor configured');
|
||||
break;
|
||||
}
|
||||
}
|
||||
|
||||
// Collect file changes
|
||||
if (task.files.create) filesCreated.push(...task.files.create);
|
||||
if (task.files.modify) filesModified.push(...task.files.modify);
|
||||
|
||||
const result: PlanTaskResult = {
|
||||
success: errors.length === 0,
|
||||
output: errors.length === 0 ? `Task ${task.id} completed successfully` : `Task ${task.id} failed`,
|
||||
filesCreated: filesCreated.length > 0 ? filesCreated : undefined,
|
||||
filesModified: filesModified.length > 0 ? filesModified : undefined,
|
||||
errors: errors.length > 0 ? errors : undefined,
|
||||
durationMs: Date.now() - startTime,
|
||||
completedAt: new Date(),
|
||||
};
|
||||
|
||||
// Callback
|
||||
options?.onTaskComplete?.(task, result);
|
||||
|
||||
return result;
|
||||
}
|
||||
|
||||
/**
|
||||
* Execute with timeout
|
||||
*/
|
||||
private async executeWithTimeout<T>(promise: Promise<T>, timeoutMs: number): Promise<T> {
|
||||
return Promise.race([
|
||||
promise,
|
||||
new Promise<T>((_, reject) => setTimeout(() => reject(new Error('Timeout')), timeoutMs)),
|
||||
]);
|
||||
}
|
||||
|
||||
/**
|
||||
* Build dependency graph
|
||||
*/
|
||||
private buildDependencyGraph(plan: StructuredPlan): Map<number, number[]> {
|
||||
const graph = new Map<number, number[]>();
|
||||
|
||||
for (const task of plan.tasks) {
|
||||
graph.set(task.id, task.dependencies || []);
|
||||
}
|
||||
|
||||
return graph;
|
||||
}
|
||||
|
||||
/**
|
||||
* Get execution order using topological sort
|
||||
*/
|
||||
private getExecutionOrder(plan: StructuredPlan, graph: Map<number, number[]>): number[] {
|
||||
const order: number[] = [];
|
||||
const visited = new Set<number>();
|
||||
const temp = new Set<number>();
|
||||
|
||||
const visit = (id: number): void => {
|
||||
if (temp.has(id)) {
|
||||
throw new Error(`Circular dependency detected at task ${id}`);
|
||||
}
|
||||
if (visited.has(id)) return;
|
||||
|
||||
temp.add(id);
|
||||
|
||||
const deps = graph.get(id) || [];
|
||||
for (const dep of deps) {
|
||||
visit(dep);
|
||||
}
|
||||
|
||||
temp.delete(id);
|
||||
visited.add(id);
|
||||
order.push(id);
|
||||
};
|
||||
|
||||
for (const task of plan.tasks) {
|
||||
if (!visited.has(task.id)) {
|
||||
visit(task.id);
|
||||
}
|
||||
}
|
||||
|
||||
return order;
|
||||
}
|
||||
|
||||
/**
|
||||
* Check if dependencies are completed
|
||||
*/
|
||||
private checkDependencies(task: PlanTask, result: PlanExecutionResult): boolean {
|
||||
if (!task.dependencies || task.dependencies.length === 0) {
|
||||
return true;
|
||||
}
|
||||
|
||||
return task.dependencies.every((depId) => result.completedTasks.includes(depId));
|
||||
}
|
||||
|
||||
/**
|
||||
* Pause execution
|
||||
*/
|
||||
pause(): void {
|
||||
if (!this.isPaused) {
|
||||
this.isPaused = true;
|
||||
this.resumePromise = new Promise((resolve) => {
|
||||
this.resumeResolve = resolve;
|
||||
});
|
||||
this.emit('plan:paused', {} as StructuredPlan);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Resume execution
|
||||
*/
|
||||
resume(): void {
|
||||
if (this.isPaused && this.resumeResolve) {
|
||||
this.isPaused = false;
|
||||
this.resumeResolve();
|
||||
this.resumeResolve = undefined;
|
||||
this.resumePromise = undefined;
|
||||
this.emit('plan:resumed', {} as StructuredPlan);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Cancel execution
|
||||
*/
|
||||
cancel(): void {
|
||||
this.abortController?.abort();
|
||||
|
||||
// Unblock any pending pause to prevent hanging
|
||||
if (this.isPaused && this.resumeResolve) {
|
||||
this.isPaused = false;
|
||||
this.resumeResolve();
|
||||
this.resumeResolve = undefined;
|
||||
this.resumePromise = undefined;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Wait if paused
|
||||
*/
|
||||
private async waitIfPaused(): Promise<void> {
|
||||
if (this.isPaused && this.resumePromise) {
|
||||
await this.resumePromise;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Add event listener
|
||||
*/
|
||||
addListener(listener: PlanEventListener): void {
|
||||
this.listeners.add(listener);
|
||||
}
|
||||
|
||||
/**
|
||||
* Remove event listener
|
||||
*/
|
||||
removeListener(listener: PlanEventListener): void {
|
||||
this.listeners.delete(listener);
|
||||
}
|
||||
|
||||
/**
|
||||
* Emit event
|
||||
*/
|
||||
private emit(event: PlanEvent, plan: StructuredPlan, task?: PlanTask, result?: PlanTaskResult): void {
|
||||
for (const listener of this.listeners) {
|
||||
try {
|
||||
listener(event, plan, task, result);
|
||||
} catch {
|
||||
// Ignore listener errors
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Check if currently executing
|
||||
*/
|
||||
isExecuting(): boolean {
|
||||
return this.abortController !== undefined && !this.abortController.signal.aborted;
|
||||
}
|
||||
|
||||
/**
|
||||
* Check if paused
|
||||
*/
|
||||
isPausedState(): boolean {
|
||||
return this.isPaused;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Create a PlanExecutor instance
|
||||
*/
|
||||
export function createPlanExecutor(options?: { stepExecutor?: StepExecutor }): PlanExecutor {
|
||||
return new PlanExecutor(options);
|
||||
}
|
||||
|
||||
/**
|
||||
* Default step executor (dry run)
|
||||
*/
|
||||
export const dryRunExecutor: StepExecutor = async (step, task, _plan) => {
|
||||
console.log(`[DRY RUN] Task ${task.id}, Step ${step.number}: ${step.description}`);
|
||||
return { success: true, output: 'Dry run completed' };
|
||||
};
|
||||
|
||||
/**
|
||||
* Shell step executor (runs commands)
|
||||
*/
|
||||
export const shellExecutor: StepExecutor = async (step, _task, _plan) => {
|
||||
if (!step.command) {
|
||||
return { success: true, output: 'No command to execute' };
|
||||
}
|
||||
|
||||
try {
|
||||
const { execSync } = await import('node:child_process');
|
||||
const output = execSync(step.command, { encoding: 'utf-8', timeout: 60000 });
|
||||
|
||||
// Check expected output if provided
|
||||
if (step.expectedOutput && !output.includes(step.expectedOutput)) {
|
||||
return {
|
||||
success: false,
|
||||
output,
|
||||
error: `Expected output "${step.expectedOutput}" not found`,
|
||||
};
|
||||
}
|
||||
|
||||
return { success: true, output };
|
||||
} catch (error) {
|
||||
return {
|
||||
success: false,
|
||||
output: '',
|
||||
error: (error as Error).message,
|
||||
};
|
||||
}
|
||||
};
|
||||
@@ -0,0 +1,467 @@
|
||||
/**
|
||||
* Plan Generator
|
||||
*
|
||||
* Generates structured plans and converts them to markdown format.
|
||||
*/
|
||||
|
||||
import type {
|
||||
StructuredPlan,
|
||||
PlanTask,
|
||||
TaskStep,
|
||||
PlanTaskFiles,
|
||||
GenerateOptions,
|
||||
StepType,
|
||||
} from './types.js';
|
||||
|
||||
/**
|
||||
* Task template for common patterns
|
||||
*/
|
||||
export interface TaskTemplate {
|
||||
name: string;
|
||||
description: string;
|
||||
steps: Array<{
|
||||
type: StepType;
|
||||
description: string;
|
||||
code?: string;
|
||||
command?: string;
|
||||
}>;
|
||||
estimatedMinutes: number;
|
||||
}
|
||||
|
||||
/**
|
||||
* Common task templates
|
||||
*/
|
||||
export const TASK_TEMPLATES: Record<string, TaskTemplate> = {
|
||||
'create-component': {
|
||||
name: 'Create Component',
|
||||
description: 'Create a new React component with tests',
|
||||
steps: [
|
||||
{ type: 'test', description: 'Write failing tests for the component' },
|
||||
{ type: 'implement', description: 'Create the component file' },
|
||||
{ type: 'implement', description: 'Implement the component logic' },
|
||||
{ type: 'verify', description: 'Run tests to verify implementation', command: 'npm test' },
|
||||
{ type: 'commit', description: 'Commit the changes' },
|
||||
],
|
||||
estimatedMinutes: 5,
|
||||
},
|
||||
'add-api-endpoint': {
|
||||
name: 'Add API Endpoint',
|
||||
description: 'Create a new API endpoint with validation and tests',
|
||||
steps: [
|
||||
{ type: 'test', description: 'Write API tests for the endpoint' },
|
||||
{ type: 'implement', description: 'Define the route and handler' },
|
||||
{ type: 'implement', description: 'Add input validation' },
|
||||
{ type: 'implement', description: 'Implement the business logic' },
|
||||
{ type: 'verify', description: 'Run tests', command: 'npm test' },
|
||||
{ type: 'commit', description: 'Commit the endpoint' },
|
||||
],
|
||||
estimatedMinutes: 5,
|
||||
},
|
||||
'fix-bug': {
|
||||
name: 'Fix Bug',
|
||||
description: 'Fix a bug with a regression test',
|
||||
steps: [
|
||||
{ type: 'test', description: 'Write a failing test that reproduces the bug' },
|
||||
{ type: 'implement', description: 'Fix the bug' },
|
||||
{ type: 'verify', description: 'Verify the test passes', command: 'npm test' },
|
||||
{ type: 'commit', description: 'Commit the fix' },
|
||||
],
|
||||
estimatedMinutes: 3,
|
||||
},
|
||||
'add-feature': {
|
||||
name: 'Add Feature',
|
||||
description: 'Add a new feature with TDD',
|
||||
steps: [
|
||||
{ type: 'test', description: 'Write failing tests for the feature' },
|
||||
{ type: 'implement', description: 'Implement the feature' },
|
||||
{ type: 'verify', description: 'Run tests', command: 'npm test' },
|
||||
{ type: 'review', description: 'Review the implementation' },
|
||||
{ type: 'commit', description: 'Commit the feature' },
|
||||
],
|
||||
estimatedMinutes: 5,
|
||||
},
|
||||
'refactor': {
|
||||
name: 'Refactor',
|
||||
description: 'Refactor code while maintaining behavior',
|
||||
steps: [
|
||||
{ type: 'verify', description: 'Ensure all tests pass before refactoring', command: 'npm test' },
|
||||
{ type: 'implement', description: 'Apply the refactoring' },
|
||||
{ type: 'verify', description: 'Verify tests still pass', command: 'npm test' },
|
||||
{ type: 'commit', description: 'Commit the refactoring' },
|
||||
],
|
||||
estimatedMinutes: 4,
|
||||
},
|
||||
};
|
||||
|
||||
/**
|
||||
* PlanGenerator - Generate and format structured plans
|
||||
*/
|
||||
export class PlanGenerator {
|
||||
private options: GenerateOptions;
|
||||
|
||||
constructor(options?: GenerateOptions) {
|
||||
this.options = {
|
||||
targetTaskMinutes: 5,
|
||||
includeTests: true,
|
||||
includeCommits: true,
|
||||
...options,
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Create a new empty plan
|
||||
*/
|
||||
createPlan(name: string, goal: string): StructuredPlan {
|
||||
return {
|
||||
name,
|
||||
goal,
|
||||
tasks: [],
|
||||
status: 'draft',
|
||||
createdAt: new Date(),
|
||||
author: this.options.author,
|
||||
techStack: this.options.techStack,
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Add a task to a plan
|
||||
*/
|
||||
addTask(
|
||||
plan: StructuredPlan,
|
||||
name: string,
|
||||
options?: {
|
||||
description?: string;
|
||||
files?: PlanTaskFiles;
|
||||
steps?: Partial<TaskStep>[];
|
||||
estimatedMinutes?: number;
|
||||
dependencies?: number[];
|
||||
tags?: string[];
|
||||
priority?: number;
|
||||
}
|
||||
): PlanTask {
|
||||
const id = plan.tasks.length > 0 ? Math.max(...plan.tasks.map((t) => t.id)) + 1 : 1;
|
||||
|
||||
const task: PlanTask = {
|
||||
id,
|
||||
name,
|
||||
description: options?.description,
|
||||
files: options?.files || {},
|
||||
steps: (options?.steps || []).map((s, i) => ({
|
||||
number: i + 1,
|
||||
description: s.description || '',
|
||||
type: s.type || 'implement',
|
||||
code: s.code,
|
||||
language: s.language,
|
||||
command: s.command,
|
||||
expectedOutput: s.expectedOutput,
|
||||
critical: s.critical,
|
||||
})),
|
||||
estimatedMinutes: options?.estimatedMinutes || this.options.targetTaskMinutes,
|
||||
dependencies: options?.dependencies,
|
||||
tags: options?.tags,
|
||||
priority: options?.priority,
|
||||
status: 'pending',
|
||||
};
|
||||
|
||||
// Add test step if required and not present
|
||||
if (this.options.includeTests && !task.steps.some((s) => s.type === 'test')) {
|
||||
task.steps.unshift({
|
||||
number: 0,
|
||||
description: 'Write tests for the implementation',
|
||||
type: 'test',
|
||||
});
|
||||
// Renumber steps
|
||||
task.steps.forEach((s, i) => (s.number = i + 1));
|
||||
}
|
||||
|
||||
// Add commit step if required and not present
|
||||
if (this.options.includeCommits && !task.steps.some((s) => s.type === 'commit')) {
|
||||
task.steps.push({
|
||||
number: task.steps.length + 1,
|
||||
description: 'Commit changes',
|
||||
type: 'commit',
|
||||
});
|
||||
}
|
||||
|
||||
plan.tasks.push(task);
|
||||
plan.updatedAt = new Date();
|
||||
|
||||
return task;
|
||||
}
|
||||
|
||||
/**
|
||||
* Add a task from a template
|
||||
*/
|
||||
addTaskFromTemplate(
|
||||
plan: StructuredPlan,
|
||||
templateName: keyof typeof TASK_TEMPLATES | string,
|
||||
customization?: {
|
||||
name?: string;
|
||||
description?: string;
|
||||
files?: PlanTaskFiles;
|
||||
dependencies?: number[];
|
||||
tags?: string[];
|
||||
}
|
||||
): PlanTask | undefined {
|
||||
const template = TASK_TEMPLATES[templateName];
|
||||
if (!template) return undefined;
|
||||
|
||||
return this.addTask(plan, customization?.name || template.name, {
|
||||
description: customization?.description || template.description,
|
||||
files: customization?.files,
|
||||
steps: template.steps,
|
||||
estimatedMinutes: template.estimatedMinutes,
|
||||
dependencies: customization?.dependencies,
|
||||
tags: customization?.tags,
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
* Generate markdown from a structured plan
|
||||
*/
|
||||
toMarkdown(plan: StructuredPlan): string {
|
||||
const lines: string[] = [];
|
||||
|
||||
// Title
|
||||
lines.push(`# ${plan.name}`);
|
||||
lines.push('');
|
||||
|
||||
// Metadata
|
||||
if (plan.version) {
|
||||
lines.push(`Version: ${plan.version}`);
|
||||
}
|
||||
if (plan.author) {
|
||||
lines.push(`Author: ${plan.author}`);
|
||||
}
|
||||
if (plan.designDoc) {
|
||||
lines.push(`Design Doc: ${plan.designDoc}`);
|
||||
}
|
||||
if (plan.version || plan.author || plan.designDoc) {
|
||||
lines.push('');
|
||||
}
|
||||
|
||||
// Goal
|
||||
lines.push('## Goal');
|
||||
lines.push('');
|
||||
lines.push(plan.goal);
|
||||
lines.push('');
|
||||
|
||||
// Architecture
|
||||
if (plan.architecture) {
|
||||
lines.push('## Architecture');
|
||||
lines.push('');
|
||||
lines.push(plan.architecture);
|
||||
lines.push('');
|
||||
}
|
||||
|
||||
// Tech Stack
|
||||
if (plan.techStack && plan.techStack.length > 0) {
|
||||
lines.push('## Tech Stack');
|
||||
lines.push('');
|
||||
for (const tech of plan.techStack) {
|
||||
lines.push(`- ${tech}`);
|
||||
}
|
||||
lines.push('');
|
||||
}
|
||||
|
||||
// Tasks
|
||||
lines.push('## Tasks');
|
||||
lines.push('');
|
||||
|
||||
for (const task of plan.tasks) {
|
||||
lines.push(`### Task ${task.id}: ${task.name}`);
|
||||
lines.push('');
|
||||
|
||||
if (task.description) {
|
||||
lines.push(task.description);
|
||||
lines.push('');
|
||||
}
|
||||
|
||||
// Files
|
||||
const hasFiles =
|
||||
(task.files.create && task.files.create.length > 0) ||
|
||||
(task.files.modify && task.files.modify.length > 0) ||
|
||||
(task.files.test && task.files.test.length > 0) ||
|
||||
(task.files.delete && task.files.delete.length > 0);
|
||||
|
||||
if (hasFiles) {
|
||||
lines.push('**Files:**');
|
||||
if (task.files.create && task.files.create.length > 0) {
|
||||
lines.push(`- Create: ${task.files.create.map((f) => `\`${f}\``).join(', ')}`);
|
||||
}
|
||||
if (task.files.modify && task.files.modify.length > 0) {
|
||||
lines.push(`- Modify: ${task.files.modify.map((f) => `\`${f}\``).join(', ')}`);
|
||||
}
|
||||
if (task.files.test && task.files.test.length > 0) {
|
||||
lines.push(`- Test: ${task.files.test.map((f) => `\`${f}\``).join(', ')}`);
|
||||
}
|
||||
if (task.files.delete && task.files.delete.length > 0) {
|
||||
lines.push(`- Delete: ${task.files.delete.map((f) => `\`${f}\``).join(', ')}`);
|
||||
}
|
||||
lines.push('');
|
||||
}
|
||||
|
||||
// Metadata
|
||||
if (task.estimatedMinutes) {
|
||||
lines.push(`Estimated: ${task.estimatedMinutes} minutes`);
|
||||
}
|
||||
if (task.dependencies && task.dependencies.length > 0) {
|
||||
lines.push(`Depends on: ${task.dependencies.map((d) => `Task ${d}`).join(', ')}`);
|
||||
}
|
||||
if (task.tags && task.tags.length > 0) {
|
||||
lines.push(`Tags: ${task.tags.join(', ')}`);
|
||||
}
|
||||
if (task.priority !== undefined) {
|
||||
lines.push(`Priority: ${task.priority}`);
|
||||
}
|
||||
if (task.estimatedMinutes || task.dependencies?.length || task.tags?.length || task.priority !== undefined) {
|
||||
lines.push('');
|
||||
}
|
||||
|
||||
// Steps
|
||||
lines.push('**Steps:**');
|
||||
lines.push('');
|
||||
|
||||
for (const step of task.steps) {
|
||||
const typeLabel = step.type !== 'implement' ? ` [${step.type}]` : '';
|
||||
lines.push(`${step.number}. ${step.description}${typeLabel}`);
|
||||
|
||||
if (step.command) {
|
||||
lines.push(` - Run: \`${step.command}\``);
|
||||
}
|
||||
if (step.expectedOutput) {
|
||||
lines.push(` - Expect: ${step.expectedOutput}`);
|
||||
}
|
||||
if (step.critical) {
|
||||
lines.push(` - Critical: Yes`);
|
||||
}
|
||||
|
||||
if (step.code) {
|
||||
lines.push('');
|
||||
lines.push(` \`\`\`${step.language || ''}`);
|
||||
for (const codeLine of step.code.split('\n')) {
|
||||
lines.push(` ${codeLine}`);
|
||||
}
|
||||
lines.push(' ```');
|
||||
}
|
||||
}
|
||||
|
||||
lines.push('');
|
||||
}
|
||||
|
||||
// Summary
|
||||
const totalMinutes = plan.tasks.reduce((sum, t) => sum + (t.estimatedMinutes || 3), 0);
|
||||
lines.push('---');
|
||||
lines.push('');
|
||||
lines.push(`**Summary:** ${plan.tasks.length} tasks, ~${totalMinutes} minutes estimated`);
|
||||
lines.push(`**Created:** ${plan.createdAt.toISOString().split('T')[0]}`);
|
||||
if (plan.updatedAt) {
|
||||
lines.push(`**Updated:** ${plan.updatedAt.toISOString().split('T')[0]}`);
|
||||
}
|
||||
|
||||
return lines.join('\n');
|
||||
}
|
||||
|
||||
/**
|
||||
* Generate a plan from a simple task list
|
||||
*/
|
||||
fromTaskList(
|
||||
name: string,
|
||||
goal: string,
|
||||
taskNames: string[],
|
||||
options?: {
|
||||
architecture?: string;
|
||||
techStack?: string[];
|
||||
template?: keyof typeof TASK_TEMPLATES;
|
||||
}
|
||||
): StructuredPlan {
|
||||
const plan = this.createPlan(name, goal);
|
||||
|
||||
if (options?.architecture) {
|
||||
plan.architecture = options.architecture;
|
||||
}
|
||||
if (options?.techStack) {
|
||||
plan.techStack = options.techStack;
|
||||
}
|
||||
|
||||
for (let i = 0; i < taskNames.length; i++) {
|
||||
const taskName = taskNames[i];
|
||||
|
||||
if (options?.template) {
|
||||
this.addTaskFromTemplate(plan, options.template, {
|
||||
name: taskName,
|
||||
dependencies: i > 0 ? [i] : undefined,
|
||||
});
|
||||
} else {
|
||||
this.addTask(plan, taskName, {
|
||||
dependencies: i > 0 ? [i] : undefined,
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
return plan;
|
||||
}
|
||||
|
||||
/**
|
||||
* Clone a plan
|
||||
*/
|
||||
clonePlan(plan: StructuredPlan, newName?: string): StructuredPlan {
|
||||
return {
|
||||
...plan,
|
||||
name: newName || `${plan.name} (copy)`,
|
||||
tasks: plan.tasks.map((t) => ({
|
||||
...t,
|
||||
steps: [...t.steps],
|
||||
files: { ...t.files },
|
||||
dependencies: t.dependencies ? [...t.dependencies] : undefined,
|
||||
tags: t.tags ? [...t.tags] : undefined,
|
||||
status: 'pending',
|
||||
result: undefined,
|
||||
})),
|
||||
status: 'draft',
|
||||
createdAt: new Date(),
|
||||
updatedAt: undefined,
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Merge two plans
|
||||
*/
|
||||
mergePlans(plan1: StructuredPlan, plan2: StructuredPlan, newName?: string): StructuredPlan {
|
||||
const merged = this.clonePlan(plan1, newName || `${plan1.name} + ${plan2.name}`);
|
||||
|
||||
// Offset task IDs from plan2
|
||||
const maxId = Math.max(...merged.tasks.map((t) => t.id), 0);
|
||||
|
||||
for (const task of plan2.tasks) {
|
||||
const newTask: PlanTask = {
|
||||
...task,
|
||||
id: task.id + maxId,
|
||||
steps: [...task.steps],
|
||||
files: { ...task.files },
|
||||
dependencies: task.dependencies?.map((d) => d + maxId),
|
||||
tags: task.tags ? [...task.tags] : undefined,
|
||||
status: 'pending',
|
||||
result: undefined,
|
||||
};
|
||||
merged.tasks.push(newTask);
|
||||
}
|
||||
|
||||
// Merge tech stacks
|
||||
if (plan2.techStack) {
|
||||
merged.techStack = [...(merged.techStack || []), ...plan2.techStack.filter((t) => !(merged.techStack || []).includes(t))];
|
||||
}
|
||||
|
||||
merged.goal = `${merged.goal}\n\n${plan2.goal}`;
|
||||
merged.updatedAt = new Date();
|
||||
|
||||
return merged;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Create a PlanGenerator instance
|
||||
*/
|
||||
export function createPlanGenerator(options?: GenerateOptions): PlanGenerator {
|
||||
return new PlanGenerator(options);
|
||||
}
|
||||
@@ -0,0 +1,56 @@
|
||||
/**
|
||||
* Structured Plan System
|
||||
*
|
||||
* Provides plan parsing, validation, generation, and execution
|
||||
* for bite-sized task plans with structured steps.
|
||||
*
|
||||
* Key features:
|
||||
* - Parse markdown plans to structured format
|
||||
* - Validate plans for completeness and best practices
|
||||
* - Generate plans from task lists or templates
|
||||
* - Execute plans with progress tracking
|
||||
* - Event-driven architecture
|
||||
*/
|
||||
|
||||
// Parser
|
||||
export { PlanParser, createPlanParser } from './parser.js';
|
||||
|
||||
// Validator
|
||||
export { PlanValidator, createPlanValidator, validatePlan } from './validator.js';
|
||||
export type { ValidatorOptions } from './validator.js';
|
||||
|
||||
// Generator
|
||||
export { PlanGenerator, createPlanGenerator, TASK_TEMPLATES } from './generator.js';
|
||||
export type { TaskTemplate } from './generator.js';
|
||||
|
||||
// Executor
|
||||
export { PlanExecutor, createPlanExecutor, dryRunExecutor, shellExecutor } from './executor.js';
|
||||
export type { StepExecutor } from './executor.js';
|
||||
|
||||
// Types
|
||||
export type {
|
||||
// Core types
|
||||
StructuredPlan,
|
||||
PlanTask,
|
||||
TaskStep,
|
||||
PlanTaskResult,
|
||||
PlanTaskFiles,
|
||||
StepType,
|
||||
PlanStatus,
|
||||
|
||||
// Validation
|
||||
PlanValidationResult,
|
||||
ValidationIssue,
|
||||
|
||||
// Options
|
||||
ParseOptions,
|
||||
GenerateOptions,
|
||||
PlanExecutionOptions,
|
||||
|
||||
// Execution
|
||||
PlanExecutionResult,
|
||||
|
||||
// Events
|
||||
PlanEvent,
|
||||
PlanEventListener,
|
||||
} from './types.js';
|
||||
@@ -0,0 +1,456 @@
|
||||
/**
|
||||
* Plan Parser
|
||||
*
|
||||
* Parses markdown plans into structured StructuredPlan format.
|
||||
* Supports multiple plan formats and extracts tasks, steps, and metadata.
|
||||
*/
|
||||
|
||||
import type {
|
||||
StructuredPlan,
|
||||
PlanTask,
|
||||
TaskStep,
|
||||
PlanTaskFiles,
|
||||
StepType,
|
||||
ParseOptions,
|
||||
} from './types.js';
|
||||
|
||||
/**
|
||||
* PlanParser - Parse markdown plans to structured format
|
||||
*/
|
||||
export class PlanParser {
|
||||
private defaultStepType: StepType;
|
||||
|
||||
constructor(options?: { defaultStepType?: StepType }) {
|
||||
this.defaultStepType = options?.defaultStepType || 'implement';
|
||||
}
|
||||
|
||||
/**
|
||||
* Parse a markdown plan into structured format
|
||||
*/
|
||||
parse(markdown: string, _options?: ParseOptions): StructuredPlan {
|
||||
const lines = markdown.split('\n');
|
||||
const plan: StructuredPlan = {
|
||||
name: '',
|
||||
goal: '',
|
||||
tasks: [],
|
||||
status: 'draft',
|
||||
createdAt: new Date(),
|
||||
};
|
||||
|
||||
let currentTask: Partial<PlanTask> | null = null;
|
||||
let currentStep: Partial<TaskStep> | null = null;
|
||||
let inCodeBlock = false;
|
||||
let codeBlockLang = '';
|
||||
let codeBlockContent: string[] = [];
|
||||
let section = '';
|
||||
let taskIdCounter = 1;
|
||||
let stepCounter = 1;
|
||||
|
||||
for (let i = 0; i < lines.length; i++) {
|
||||
const line = lines[i];
|
||||
const trimmed = line.trim();
|
||||
|
||||
// Handle code blocks
|
||||
if (trimmed.startsWith('```')) {
|
||||
if (!inCodeBlock) {
|
||||
inCodeBlock = true;
|
||||
codeBlockLang = trimmed.slice(3).trim();
|
||||
codeBlockContent = [];
|
||||
} else {
|
||||
inCodeBlock = false;
|
||||
if (currentStep) {
|
||||
currentStep.code = codeBlockContent.join('\n');
|
||||
currentStep.language = codeBlockLang || undefined;
|
||||
}
|
||||
codeBlockLang = '';
|
||||
codeBlockContent = [];
|
||||
}
|
||||
continue;
|
||||
}
|
||||
|
||||
if (inCodeBlock) {
|
||||
codeBlockContent.push(line);
|
||||
continue;
|
||||
}
|
||||
|
||||
// Skip empty lines
|
||||
if (!trimmed) continue;
|
||||
|
||||
// Parse headers
|
||||
if (trimmed.startsWith('#')) {
|
||||
const headerMatch = trimmed.match(/^(#+)\s*(.+)$/);
|
||||
if (headerMatch) {
|
||||
const level = headerMatch[1].length;
|
||||
const title = headerMatch[2].trim();
|
||||
|
||||
if (level === 1) {
|
||||
// Main plan title
|
||||
plan.name = title;
|
||||
} else if (level === 2) {
|
||||
// Section or task
|
||||
section = title.toLowerCase();
|
||||
|
||||
// Check if this is a task (numbered or "Task X:")
|
||||
const taskMatch = title.match(/^(?:Task\s*)?(\d+)(?:\.|\:)?\s*(.+)$/i);
|
||||
if (taskMatch) {
|
||||
// Save current step to previous task first
|
||||
if (currentStep && currentStep.description && currentTask) {
|
||||
if (!currentTask.steps) currentTask.steps = [];
|
||||
currentTask.steps.push(this.finalizeStep(currentStep, stepCounter++));
|
||||
}
|
||||
|
||||
// Save previous task
|
||||
if (currentTask && currentTask.name) {
|
||||
plan.tasks.push(this.finalizeTask(currentTask, stepCounter));
|
||||
}
|
||||
|
||||
currentTask = {
|
||||
id: parseInt(taskMatch[1], 10) || taskIdCounter++,
|
||||
name: taskMatch[2].trim(),
|
||||
files: {},
|
||||
steps: [],
|
||||
};
|
||||
stepCounter = 1;
|
||||
currentStep = null;
|
||||
section = 'task';
|
||||
}
|
||||
} else if (level === 3 && currentTask) {
|
||||
// Sub-section within task
|
||||
const subSection = title.toLowerCase();
|
||||
if (subSection.includes('file')) {
|
||||
section = 'files';
|
||||
} else if (subSection.includes('step')) {
|
||||
section = 'steps';
|
||||
}
|
||||
}
|
||||
}
|
||||
continue;
|
||||
}
|
||||
|
||||
// Parse plan metadata
|
||||
if (section === 'goal' || section === 'objective') {
|
||||
plan.goal = (plan.goal ? plan.goal + ' ' : '') + trimmed;
|
||||
continue;
|
||||
}
|
||||
|
||||
if (section === 'architecture') {
|
||||
plan.architecture = (plan.architecture ? plan.architecture + '\n' : '') + trimmed;
|
||||
continue;
|
||||
}
|
||||
|
||||
if (section === 'tech stack' || section === 'technology') {
|
||||
if (trimmed.startsWith('-') || trimmed.startsWith('*')) {
|
||||
if (!plan.techStack) plan.techStack = [];
|
||||
plan.techStack.push(trimmed.slice(1).trim());
|
||||
}
|
||||
continue;
|
||||
}
|
||||
|
||||
// Parse task content
|
||||
if (currentTask) {
|
||||
// Parse files section
|
||||
if (trimmed.toLowerCase() === 'files:' || trimmed.toLowerCase().startsWith('**files')) {
|
||||
section = 'files';
|
||||
continue;
|
||||
}
|
||||
|
||||
if (section === 'files') {
|
||||
const files = this.parseFiles(trimmed);
|
||||
if (files) {
|
||||
currentTask.files = { ...currentTask.files, ...files };
|
||||
}
|
||||
continue;
|
||||
}
|
||||
|
||||
// Parse steps
|
||||
const stepMatch = trimmed.match(/^(\d+)[\.\)]\s*(.+)$/);
|
||||
if (stepMatch) {
|
||||
// Exit files section when we encounter a step
|
||||
if (section === 'files') {
|
||||
section = 'steps';
|
||||
}
|
||||
// Save previous step
|
||||
if (currentStep && currentStep.description) {
|
||||
if (!currentTask.steps) currentTask.steps = [];
|
||||
currentTask.steps.push(this.finalizeStep(currentStep, stepCounter++));
|
||||
}
|
||||
|
||||
currentStep = {
|
||||
description: stepMatch[2].trim(),
|
||||
type: this.inferStepType(stepMatch[2]),
|
||||
};
|
||||
continue;
|
||||
}
|
||||
|
||||
// Parse bullet points as step details
|
||||
if ((trimmed.startsWith('-') || trimmed.startsWith('*')) && currentStep) {
|
||||
const detail = trimmed.slice(1).trim();
|
||||
|
||||
// Check for command
|
||||
if (detail.toLowerCase().startsWith('run:') || detail.toLowerCase().startsWith('command:')) {
|
||||
currentStep.command = detail.split(':').slice(1).join(':').trim();
|
||||
}
|
||||
// Check for expected output
|
||||
else if (detail.toLowerCase().startsWith('expect:') || detail.toLowerCase().startsWith('output:')) {
|
||||
currentStep.expectedOutput = detail.split(':').slice(1).join(':').trim();
|
||||
}
|
||||
// Check for critical flag
|
||||
else if (detail.toLowerCase().includes('critical') || detail.toLowerCase().includes('required')) {
|
||||
currentStep.critical = true;
|
||||
}
|
||||
continue;
|
||||
}
|
||||
|
||||
// Parse inline metadata
|
||||
if (trimmed.toLowerCase().startsWith('estimated:') || trimmed.toLowerCase().startsWith('time:')) {
|
||||
const timeMatch = trimmed.match(/(\d+)\s*(?:min|minutes?|m)/i);
|
||||
if (timeMatch) {
|
||||
currentTask.estimatedMinutes = parseInt(timeMatch[1], 10);
|
||||
}
|
||||
continue;
|
||||
}
|
||||
|
||||
if (trimmed.toLowerCase().startsWith('depends on:') || trimmed.toLowerCase().startsWith('dependencies:')) {
|
||||
const depsStr = trimmed.split(':').slice(1).join(':').trim();
|
||||
currentTask.dependencies = depsStr
|
||||
.split(/[,\s]+/)
|
||||
.map((d) => parseInt(d.replace(/\D/g, ''), 10))
|
||||
.filter((d) => !isNaN(d));
|
||||
continue;
|
||||
}
|
||||
|
||||
if (trimmed.toLowerCase().startsWith('priority:')) {
|
||||
const priority = parseInt(trimmed.split(':')[1].trim(), 10);
|
||||
if (!isNaN(priority)) {
|
||||
currentTask.priority = priority;
|
||||
}
|
||||
continue;
|
||||
}
|
||||
|
||||
if (trimmed.toLowerCase().startsWith('tags:')) {
|
||||
currentTask.tags = trimmed
|
||||
.split(':')
|
||||
.slice(1)
|
||||
.join(':')
|
||||
.split(/[,\s]+/)
|
||||
.map((t) => t.trim())
|
||||
.filter(Boolean);
|
||||
continue;
|
||||
}
|
||||
|
||||
// Add description content
|
||||
if (!currentTask.description) {
|
||||
currentTask.description = trimmed;
|
||||
} else if (section === 'task') {
|
||||
currentTask.description += ' ' + trimmed;
|
||||
}
|
||||
} else {
|
||||
// Parse top-level metadata
|
||||
if (trimmed.toLowerCase().startsWith('goal:') || trimmed.toLowerCase().startsWith('objective:')) {
|
||||
plan.goal = trimmed.split(':').slice(1).join(':').trim();
|
||||
section = 'goal';
|
||||
continue;
|
||||
}
|
||||
|
||||
if (trimmed.toLowerCase().startsWith('architecture:')) {
|
||||
plan.architecture = trimmed.split(':').slice(1).join(':').trim();
|
||||
section = 'architecture';
|
||||
continue;
|
||||
}
|
||||
|
||||
if (trimmed.toLowerCase().startsWith('author:')) {
|
||||
plan.author = trimmed.split(':').slice(1).join(':').trim();
|
||||
continue;
|
||||
}
|
||||
|
||||
if (trimmed.toLowerCase().startsWith('version:')) {
|
||||
plan.version = trimmed.split(':').slice(1).join(':').trim();
|
||||
continue;
|
||||
}
|
||||
|
||||
if (trimmed.toLowerCase().startsWith('design doc:') || trimmed.toLowerCase().startsWith('designdoc:')) {
|
||||
plan.designDoc = trimmed.split(':').slice(1).join(':').trim();
|
||||
continue;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Save last step
|
||||
if (currentStep && currentStep.description && currentTask) {
|
||||
if (!currentTask.steps) currentTask.steps = [];
|
||||
currentTask.steps.push(this.finalizeStep(currentStep, stepCounter));
|
||||
}
|
||||
|
||||
// Save last task
|
||||
if (currentTask && currentTask.name) {
|
||||
plan.tasks.push(this.finalizeTask(currentTask, stepCounter));
|
||||
}
|
||||
|
||||
// Set plan to ready if it has tasks
|
||||
if (plan.tasks.length > 0) {
|
||||
plan.status = 'ready';
|
||||
}
|
||||
|
||||
return plan;
|
||||
}
|
||||
|
||||
/**
|
||||
* Parse files from a line
|
||||
*/
|
||||
private parseFiles(line: string): Partial<PlanTaskFiles> | null {
|
||||
const files: Partial<PlanTaskFiles> = {};
|
||||
|
||||
// Check for create files
|
||||
if (line.toLowerCase().includes('create:')) {
|
||||
const createPart = line.split(/create:/i)[1];
|
||||
if (createPart) {
|
||||
files.create = this.extractFilePaths(createPart);
|
||||
}
|
||||
}
|
||||
|
||||
// Check for modify files
|
||||
if (line.toLowerCase().includes('modify:')) {
|
||||
const modifyPart = line.split(/modify:/i)[1];
|
||||
if (modifyPart) {
|
||||
files.modify = this.extractFilePaths(modifyPart);
|
||||
}
|
||||
}
|
||||
|
||||
// Check for test files
|
||||
if (line.toLowerCase().includes('test:')) {
|
||||
const testPart = line.split(/test:/i)[1];
|
||||
if (testPart) {
|
||||
files.test = this.extractFilePaths(testPart);
|
||||
}
|
||||
}
|
||||
|
||||
// Check for delete files
|
||||
if (line.toLowerCase().includes('delete:')) {
|
||||
const deletePart = line.split(/delete:/i)[1];
|
||||
if (deletePart) {
|
||||
files.delete = this.extractFilePaths(deletePart);
|
||||
}
|
||||
}
|
||||
|
||||
// Check for bullet point with file path
|
||||
if (line.startsWith('-') || line.startsWith('*')) {
|
||||
const content = line.slice(1).trim();
|
||||
const pathMatch = content.match(/`([^`]+)`|(\S+\.\w+)/);
|
||||
if (pathMatch) {
|
||||
const path = pathMatch[1] || pathMatch[2];
|
||||
if (content.toLowerCase().includes('create')) {
|
||||
files.create = [path];
|
||||
} else if (content.toLowerCase().includes('test')) {
|
||||
files.test = [path];
|
||||
} else if (content.toLowerCase().includes('delete')) {
|
||||
files.delete = [path];
|
||||
} else {
|
||||
files.modify = [path];
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return Object.keys(files).length > 0 ? files : null;
|
||||
}
|
||||
|
||||
/**
|
||||
* Extract file paths from a string
|
||||
*/
|
||||
private extractFilePaths(str: string): string[] {
|
||||
const paths: string[] = [];
|
||||
|
||||
// Match paths in backticks
|
||||
const backtickMatches = str.match(/`([^`]+)`/g);
|
||||
if (backtickMatches) {
|
||||
paths.push(...backtickMatches.map((m) => m.slice(1, -1)));
|
||||
}
|
||||
|
||||
// Match common file patterns
|
||||
const pathMatches = str.match(/[\w\-./]+\.\w+/g);
|
||||
if (pathMatches) {
|
||||
paths.push(...pathMatches.filter((p) => !paths.includes(p)));
|
||||
}
|
||||
|
||||
return paths;
|
||||
}
|
||||
|
||||
/**
|
||||
* Infer step type from description
|
||||
*/
|
||||
private inferStepType(description: string): StepType {
|
||||
const lower = description.toLowerCase();
|
||||
|
||||
if (lower.includes('test') || lower.includes('spec') || lower.includes('assert')) {
|
||||
return 'test';
|
||||
}
|
||||
if (lower.includes('verify') || lower.includes('check') || lower.includes('confirm') || lower.includes('ensure')) {
|
||||
return 'verify';
|
||||
}
|
||||
if (lower.includes('commit') || lower.includes('git')) {
|
||||
return 'commit';
|
||||
}
|
||||
if (lower.includes('review') || lower.includes('inspect')) {
|
||||
return 'review';
|
||||
}
|
||||
if (lower.includes('setup') || lower.includes('initialize') || lower.includes('configure')) {
|
||||
return 'setup';
|
||||
}
|
||||
if (lower.includes('cleanup') || lower.includes('clean up') || lower.includes('remove')) {
|
||||
return 'cleanup';
|
||||
}
|
||||
|
||||
return this.defaultStepType;
|
||||
}
|
||||
|
||||
/**
|
||||
* Finalize a step
|
||||
*/
|
||||
private finalizeStep(step: Partial<TaskStep>, number: number): TaskStep {
|
||||
return {
|
||||
number,
|
||||
description: step.description || '',
|
||||
type: step.type || this.defaultStepType,
|
||||
code: step.code,
|
||||
language: step.language,
|
||||
command: step.command,
|
||||
expectedOutput: step.expectedOutput,
|
||||
critical: step.critical,
|
||||
metadata: step.metadata,
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Finalize a task
|
||||
*/
|
||||
private finalizeTask(task: Partial<PlanTask>, _stepCounter: number): PlanTask {
|
||||
return {
|
||||
id: task.id || 1,
|
||||
name: task.name || 'Unnamed Task',
|
||||
description: task.description,
|
||||
files: task.files || {},
|
||||
steps: task.steps || [],
|
||||
estimatedMinutes: task.estimatedMinutes,
|
||||
dependencies: task.dependencies,
|
||||
tags: task.tags,
|
||||
priority: task.priority,
|
||||
status: 'pending',
|
||||
metadata: task.metadata,
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Parse a plan file from path
|
||||
*/
|
||||
async parseFile(filePath: string, options?: ParseOptions): Promise<StructuredPlan> {
|
||||
const fs = await import('node:fs/promises');
|
||||
const content = await fs.readFile(filePath, 'utf-8');
|
||||
return this.parse(content, options);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Create a PlanParser instance
|
||||
*/
|
||||
export function createPlanParser(options?: { defaultStepType?: StepType }): PlanParser {
|
||||
return new PlanParser(options);
|
||||
}
|
||||
@@ -0,0 +1,272 @@
|
||||
/**
|
||||
* Structured Plan Types
|
||||
*
|
||||
* Types for bite-sized task plans with structured execution.
|
||||
* Supports parsing, validation, and execution of development plans.
|
||||
*/
|
||||
|
||||
/**
|
||||
* Step type in a task
|
||||
*/
|
||||
export type StepType = 'test' | 'verify' | 'implement' | 'commit' | 'review' | 'setup' | 'cleanup';
|
||||
|
||||
/**
|
||||
* Plan status
|
||||
*/
|
||||
export type PlanStatus = 'draft' | 'ready' | 'executing' | 'paused' | 'completed' | 'failed' | 'cancelled';
|
||||
|
||||
/**
|
||||
* Task step within a plan task
|
||||
*/
|
||||
export interface TaskStep {
|
||||
/** Step number */
|
||||
number: number;
|
||||
/** Step description */
|
||||
description: string;
|
||||
/** Step type */
|
||||
type: StepType;
|
||||
/** Code snippet (optional) */
|
||||
code?: string;
|
||||
/** Programming language for code */
|
||||
language?: string;
|
||||
/** Command to run (optional) */
|
||||
command?: string;
|
||||
/** Expected output (optional) */
|
||||
expectedOutput?: string;
|
||||
/** Whether this step is critical (failure stops execution) */
|
||||
critical?: boolean;
|
||||
/** Metadata */
|
||||
metadata?: Record<string, unknown>;
|
||||
}
|
||||
|
||||
/**
|
||||
* Task files specification
|
||||
*/
|
||||
export interface PlanTaskFiles {
|
||||
/** Files to create */
|
||||
create?: string[];
|
||||
/** Files to modify */
|
||||
modify?: string[];
|
||||
/** Test files */
|
||||
test?: string[];
|
||||
/** Files to delete */
|
||||
delete?: string[];
|
||||
}
|
||||
|
||||
/**
|
||||
* Task within a structured plan
|
||||
*/
|
||||
export interface PlanTask {
|
||||
/** Task ID */
|
||||
id: number;
|
||||
/** Task name */
|
||||
name: string;
|
||||
/** Task description */
|
||||
description?: string;
|
||||
/** Files involved */
|
||||
files: PlanTaskFiles;
|
||||
/** Steps to complete the task */
|
||||
steps: TaskStep[];
|
||||
/** Estimated time in minutes (target: 2-5 min) */
|
||||
estimatedMinutes?: number;
|
||||
/** Dependencies (task IDs that must complete first) */
|
||||
dependencies?: number[];
|
||||
/** Tags for categorization */
|
||||
tags?: string[];
|
||||
/** Priority (higher = more important) */
|
||||
priority?: number;
|
||||
/** Assigned agent type */
|
||||
assignee?: string;
|
||||
/** Task status */
|
||||
status?: 'pending' | 'in_progress' | 'completed' | 'failed' | 'skipped';
|
||||
/** Completion result */
|
||||
result?: PlanTaskResult;
|
||||
/** Metadata */
|
||||
metadata?: Record<string, unknown>;
|
||||
}
|
||||
|
||||
/**
|
||||
* Task result after execution
|
||||
*/
|
||||
export interface PlanTaskResult {
|
||||
/** Whether task succeeded */
|
||||
success: boolean;
|
||||
/** Output summary */
|
||||
output: string;
|
||||
/** Files created */
|
||||
filesCreated?: string[];
|
||||
/** Files modified */
|
||||
filesModified?: string[];
|
||||
/** Errors if any */
|
||||
errors?: string[];
|
||||
/** Duration in milliseconds */
|
||||
durationMs?: number;
|
||||
/** Completion timestamp */
|
||||
completedAt: Date;
|
||||
}
|
||||
|
||||
/**
|
||||
* Structured plan
|
||||
*/
|
||||
export interface StructuredPlan {
|
||||
/** Plan name */
|
||||
name: string;
|
||||
/** Version */
|
||||
version?: string;
|
||||
/** Goal/objective */
|
||||
goal: string;
|
||||
/** Architecture description */
|
||||
architecture?: string;
|
||||
/** Tech stack */
|
||||
techStack?: string[];
|
||||
/** Tasks in the plan */
|
||||
tasks: PlanTask[];
|
||||
/** Plan status */
|
||||
status: PlanStatus;
|
||||
/** Creation timestamp */
|
||||
createdAt: Date;
|
||||
/** Last update timestamp */
|
||||
updatedAt?: Date;
|
||||
/** Link to design document */
|
||||
designDoc?: string;
|
||||
/** Author */
|
||||
author?: string;
|
||||
/** Tags */
|
||||
tags?: string[];
|
||||
/** Metadata */
|
||||
metadata?: Record<string, unknown>;
|
||||
}
|
||||
|
||||
/**
|
||||
* Validation issue
|
||||
*/
|
||||
export interface ValidationIssue {
|
||||
/** Issue type */
|
||||
type: 'error' | 'warning' | 'info';
|
||||
/** Issue message */
|
||||
message: string;
|
||||
/** Related task ID */
|
||||
taskId?: number;
|
||||
/** Related step number */
|
||||
stepNumber?: number;
|
||||
/** Suggestion for fix */
|
||||
suggestion?: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* Validation result
|
||||
*/
|
||||
export interface PlanValidationResult {
|
||||
/** Whether the plan is valid */
|
||||
valid: boolean;
|
||||
/** Validation issues */
|
||||
issues: ValidationIssue[];
|
||||
/** Statistics */
|
||||
stats: {
|
||||
/** Total tasks */
|
||||
totalTasks: number;
|
||||
/** Total steps */
|
||||
totalSteps: number;
|
||||
/** Estimated total time in minutes */
|
||||
estimatedMinutes: number;
|
||||
/** Tasks with tests */
|
||||
tasksWithTests: number;
|
||||
/** Tasks with commits */
|
||||
tasksWithCommits: number;
|
||||
/** Average steps per task */
|
||||
avgStepsPerTask: number;
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Plan parse options
|
||||
*/
|
||||
export interface ParseOptions {
|
||||
/** Strict mode (fail on warnings) */
|
||||
strict?: boolean;
|
||||
/** Validate after parsing */
|
||||
validate?: boolean;
|
||||
/** Default step type */
|
||||
defaultStepType?: StepType;
|
||||
}
|
||||
|
||||
/**
|
||||
* Plan generation options
|
||||
*/
|
||||
export interface GenerateOptions {
|
||||
/** Target task size in minutes */
|
||||
targetTaskMinutes?: number;
|
||||
/** Include tests in every task */
|
||||
includeTests?: boolean;
|
||||
/** Include commits after each task */
|
||||
includeCommits?: boolean;
|
||||
/** Tech stack to use */
|
||||
techStack?: string[];
|
||||
/** Author name */
|
||||
author?: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* Plan execution options
|
||||
*/
|
||||
export interface PlanExecutionOptions {
|
||||
/** Dry run (don't actually execute) */
|
||||
dryRun?: boolean;
|
||||
/** Stop on first error */
|
||||
stopOnError?: boolean;
|
||||
/** Parallel execution (for independent tasks) */
|
||||
parallel?: boolean;
|
||||
/** Timeout per task in milliseconds */
|
||||
taskTimeout?: number;
|
||||
/** Progress callback */
|
||||
onProgress?: (taskId: number, step: number, status: string) => void;
|
||||
/** Task complete callback */
|
||||
onTaskComplete?: (task: PlanTask, result: PlanTaskResult) => void;
|
||||
}
|
||||
|
||||
/**
|
||||
* Plan execution result
|
||||
*/
|
||||
export interface PlanExecutionResult {
|
||||
/** Whether the plan completed successfully */
|
||||
success: boolean;
|
||||
/** Tasks that completed */
|
||||
completedTasks: number[];
|
||||
/** Tasks that failed */
|
||||
failedTasks: number[];
|
||||
/** Tasks that were skipped */
|
||||
skippedTasks: number[];
|
||||
/** Total duration in milliseconds */
|
||||
durationMs: number;
|
||||
/** Task results */
|
||||
taskResults: Map<number, PlanTaskResult>;
|
||||
/** Errors */
|
||||
errors?: string[];
|
||||
}
|
||||
|
||||
/**
|
||||
* Plan event types
|
||||
*/
|
||||
export type PlanEvent =
|
||||
| 'plan:created'
|
||||
| 'plan:updated'
|
||||
| 'plan:validated'
|
||||
| 'plan:execution_started'
|
||||
| 'plan:task_started'
|
||||
| 'plan:task_completed'
|
||||
| 'plan:task_failed'
|
||||
| 'plan:execution_completed'
|
||||
| 'plan:execution_failed'
|
||||
| 'plan:execution_cancelled'
|
||||
| 'plan:paused'
|
||||
| 'plan:resumed';
|
||||
|
||||
/**
|
||||
* Plan event listener
|
||||
*/
|
||||
export type PlanEventListener = (
|
||||
event: PlanEvent,
|
||||
plan: StructuredPlan,
|
||||
task?: PlanTask,
|
||||
result?: PlanTaskResult
|
||||
) => void | Promise<void>;
|
||||
@@ -0,0 +1,479 @@
|
||||
/**
|
||||
* Plan Validator
|
||||
*
|
||||
* Validates structured plans for completeness, correctness, and best practices.
|
||||
*/
|
||||
|
||||
import type { StructuredPlan, PlanTask, PlanValidationResult, ValidationIssue } from './types.js';
|
||||
|
||||
/**
|
||||
* Validation options
|
||||
*/
|
||||
export interface ValidatorOptions {
|
||||
/** Maximum task duration in minutes */
|
||||
maxTaskMinutes?: number;
|
||||
/** Minimum task duration in minutes */
|
||||
minTaskMinutes?: number;
|
||||
/** Require tests in each task */
|
||||
requireTests?: boolean;
|
||||
/** Require commits in each task */
|
||||
requireCommits?: boolean;
|
||||
/** Maximum steps per task */
|
||||
maxStepsPerTask?: number;
|
||||
/** Minimum steps per task */
|
||||
minStepsPerTask?: number;
|
||||
/** Require file specifications */
|
||||
requireFiles?: boolean;
|
||||
/** Strict mode (treat warnings as errors) */
|
||||
strict?: boolean;
|
||||
}
|
||||
|
||||
const DEFAULT_OPTIONS: ValidatorOptions = {
|
||||
maxTaskMinutes: 10,
|
||||
minTaskMinutes: 1,
|
||||
requireTests: false,
|
||||
requireCommits: false,
|
||||
maxStepsPerTask: 15,
|
||||
minStepsPerTask: 1,
|
||||
requireFiles: false,
|
||||
strict: false,
|
||||
};
|
||||
|
||||
/**
|
||||
* PlanValidator - Validate structured plans
|
||||
*/
|
||||
export class PlanValidator {
|
||||
private options: ValidatorOptions;
|
||||
|
||||
constructor(options?: ValidatorOptions) {
|
||||
this.options = { ...DEFAULT_OPTIONS, ...options };
|
||||
}
|
||||
|
||||
/**
|
||||
* Validate a structured plan
|
||||
*/
|
||||
validate(plan: StructuredPlan): PlanValidationResult {
|
||||
const issues: ValidationIssue[] = [];
|
||||
|
||||
// Validate plan-level fields
|
||||
this.validatePlanFields(plan, issues);
|
||||
|
||||
// Validate tasks
|
||||
this.validateTasks(plan, issues);
|
||||
|
||||
// Validate dependencies
|
||||
this.validateDependencies(plan, issues);
|
||||
|
||||
// Calculate statistics
|
||||
const stats = this.calculateStats(plan);
|
||||
|
||||
// Check if valid (no errors, or no errors/warnings in strict mode)
|
||||
const hasErrors = issues.some((i) => i.type === 'error');
|
||||
const hasWarnings = issues.some((i) => i.type === 'warning');
|
||||
const valid = !hasErrors && (!this.options.strict || !hasWarnings);
|
||||
|
||||
return { valid, issues, stats };
|
||||
}
|
||||
|
||||
/**
|
||||
* Validate plan-level fields
|
||||
*/
|
||||
private validatePlanFields(plan: StructuredPlan, issues: ValidationIssue[]): void {
|
||||
// Name is required
|
||||
if (!plan.name || !plan.name.trim()) {
|
||||
issues.push({
|
||||
type: 'error',
|
||||
message: 'Plan must have a name',
|
||||
suggestion: 'Add a title to the plan using a # header',
|
||||
});
|
||||
}
|
||||
|
||||
// Goal is required
|
||||
if (!plan.goal || !plan.goal.trim()) {
|
||||
issues.push({
|
||||
type: 'error',
|
||||
message: 'Plan must have a goal/objective',
|
||||
suggestion: 'Add a goal: field or Goal section to the plan',
|
||||
});
|
||||
}
|
||||
|
||||
// Tasks are required
|
||||
if (!plan.tasks || plan.tasks.length === 0) {
|
||||
issues.push({
|
||||
type: 'error',
|
||||
message: 'Plan must have at least one task',
|
||||
suggestion: 'Add tasks using ## Task N: Task Name headers',
|
||||
});
|
||||
}
|
||||
|
||||
// Architecture is recommended
|
||||
if (!plan.architecture) {
|
||||
issues.push({
|
||||
type: 'info',
|
||||
message: 'Plan has no architecture description',
|
||||
suggestion: 'Add an architecture section to describe the high-level design',
|
||||
});
|
||||
}
|
||||
|
||||
// Tech stack is recommended
|
||||
if (!plan.techStack || plan.techStack.length === 0) {
|
||||
issues.push({
|
||||
type: 'info',
|
||||
message: 'Plan has no tech stack specified',
|
||||
suggestion: 'Add a tech stack section listing technologies used',
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Validate tasks
|
||||
*/
|
||||
private validateTasks(plan: StructuredPlan, issues: ValidationIssue[]): void {
|
||||
const taskIds = new Set<number>();
|
||||
|
||||
for (const task of plan.tasks) {
|
||||
// Check for duplicate task IDs
|
||||
if (taskIds.has(task.id)) {
|
||||
issues.push({
|
||||
type: 'error',
|
||||
message: `Duplicate task ID: ${task.id}`,
|
||||
taskId: task.id,
|
||||
suggestion: 'Ensure each task has a unique ID',
|
||||
});
|
||||
}
|
||||
taskIds.add(task.id);
|
||||
|
||||
// Validate task fields
|
||||
this.validateTaskFields(task, issues);
|
||||
|
||||
// Validate task steps
|
||||
this.validateTaskSteps(task, issues);
|
||||
|
||||
// Check for tests
|
||||
if (this.options.requireTests) {
|
||||
const hasTestStep = task.steps.some((s) => s.type === 'test');
|
||||
const hasTestFiles = task.files.test && task.files.test.length > 0;
|
||||
|
||||
if (!hasTestStep && !hasTestFiles) {
|
||||
issues.push({
|
||||
type: 'warning',
|
||||
message: `Task ${task.id} has no test step or test files`,
|
||||
taskId: task.id,
|
||||
suggestion: 'Add a test step or specify test files',
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
// Check for commits
|
||||
if (this.options.requireCommits) {
|
||||
const hasCommitStep = task.steps.some((s) => s.type === 'commit');
|
||||
|
||||
if (!hasCommitStep) {
|
||||
issues.push({
|
||||
type: 'warning',
|
||||
message: `Task ${task.id} has no commit step`,
|
||||
taskId: task.id,
|
||||
suggestion: 'Add a commit step at the end of the task',
|
||||
});
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Validate task fields
|
||||
*/
|
||||
private validateTaskFields(task: PlanTask, issues: ValidationIssue[]): void {
|
||||
// Name is required
|
||||
if (!task.name || !task.name.trim()) {
|
||||
issues.push({
|
||||
type: 'error',
|
||||
message: `Task ${task.id} has no name`,
|
||||
taskId: task.id,
|
||||
suggestion: 'Add a descriptive name to the task',
|
||||
});
|
||||
}
|
||||
|
||||
// Steps are required
|
||||
if (!task.steps || task.steps.length === 0) {
|
||||
issues.push({
|
||||
type: 'error',
|
||||
message: `Task ${task.id} has no steps`,
|
||||
taskId: task.id,
|
||||
suggestion: 'Add numbered steps to describe how to complete the task',
|
||||
});
|
||||
}
|
||||
|
||||
// Check step count
|
||||
if (task.steps && task.steps.length > this.options.maxStepsPerTask!) {
|
||||
issues.push({
|
||||
type: 'warning',
|
||||
message: `Task ${task.id} has too many steps (${task.steps.length} > ${this.options.maxStepsPerTask})`,
|
||||
taskId: task.id,
|
||||
suggestion: 'Consider breaking this task into smaller tasks',
|
||||
});
|
||||
}
|
||||
|
||||
if (task.steps && task.steps.length < this.options.minStepsPerTask!) {
|
||||
issues.push({
|
||||
type: 'warning',
|
||||
message: `Task ${task.id} has too few steps (${task.steps.length} < ${this.options.minStepsPerTask})`,
|
||||
taskId: task.id,
|
||||
suggestion: 'Add more detail to the task steps',
|
||||
});
|
||||
}
|
||||
|
||||
// Check estimated time
|
||||
if (task.estimatedMinutes) {
|
||||
if (task.estimatedMinutes > this.options.maxTaskMinutes!) {
|
||||
issues.push({
|
||||
type: 'warning',
|
||||
message: `Task ${task.id} estimated time (${task.estimatedMinutes} min) exceeds maximum (${this.options.maxTaskMinutes} min)`,
|
||||
taskId: task.id,
|
||||
suggestion: 'Consider breaking this task into smaller tasks',
|
||||
});
|
||||
}
|
||||
|
||||
if (task.estimatedMinutes < this.options.minTaskMinutes!) {
|
||||
issues.push({
|
||||
type: 'info',
|
||||
message: `Task ${task.id} estimated time (${task.estimatedMinutes} min) is below minimum (${this.options.minTaskMinutes} min)`,
|
||||
taskId: task.id,
|
||||
suggestion: 'Consider combining with related tasks',
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
// Check files
|
||||
if (this.options.requireFiles) {
|
||||
const hasFiles =
|
||||
(task.files.create && task.files.create.length > 0) ||
|
||||
(task.files.modify && task.files.modify.length > 0) ||
|
||||
(task.files.test && task.files.test.length > 0);
|
||||
|
||||
if (!hasFiles) {
|
||||
issues.push({
|
||||
type: 'warning',
|
||||
message: `Task ${task.id} has no files specified`,
|
||||
taskId: task.id,
|
||||
suggestion: 'Specify which files will be created or modified',
|
||||
});
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Validate task steps
|
||||
*/
|
||||
private validateTaskSteps(task: PlanTask, issues: ValidationIssue[]): void {
|
||||
const stepNumbers = new Set<number>();
|
||||
|
||||
for (const step of task.steps) {
|
||||
// Check for duplicate step numbers
|
||||
if (stepNumbers.has(step.number)) {
|
||||
issues.push({
|
||||
type: 'warning',
|
||||
message: `Task ${task.id} has duplicate step number: ${step.number}`,
|
||||
taskId: task.id,
|
||||
stepNumber: step.number,
|
||||
suggestion: 'Ensure each step has a unique number',
|
||||
});
|
||||
}
|
||||
stepNumbers.add(step.number);
|
||||
|
||||
// Description is required
|
||||
if (!step.description || !step.description.trim()) {
|
||||
issues.push({
|
||||
type: 'error',
|
||||
message: `Task ${task.id}, step ${step.number} has no description`,
|
||||
taskId: task.id,
|
||||
stepNumber: step.number,
|
||||
suggestion: 'Add a description to the step',
|
||||
});
|
||||
}
|
||||
|
||||
// Verify steps should have expected output or command
|
||||
if (step.type === 'verify' && !step.expectedOutput && !step.command) {
|
||||
issues.push({
|
||||
type: 'info',
|
||||
message: `Task ${task.id}, step ${step.number} is a verify step without expected output or command`,
|
||||
taskId: task.id,
|
||||
stepNumber: step.number,
|
||||
suggestion: 'Add expected output or command to verify',
|
||||
});
|
||||
}
|
||||
|
||||
// Test steps should have code or command
|
||||
if (step.type === 'test' && !step.code && !step.command) {
|
||||
issues.push({
|
||||
type: 'info',
|
||||
message: `Task ${task.id}, step ${step.number} is a test step without code or command`,
|
||||
taskId: task.id,
|
||||
stepNumber: step.number,
|
||||
suggestion: 'Add test code or test command',
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
// Check step number sequence
|
||||
const sortedNumbers = Array.from(stepNumbers).sort((a, b) => a - b);
|
||||
for (let i = 0; i < sortedNumbers.length; i++) {
|
||||
if (sortedNumbers[i] !== i + 1) {
|
||||
issues.push({
|
||||
type: 'info',
|
||||
message: `Task ${task.id} has non-sequential step numbers`,
|
||||
taskId: task.id,
|
||||
suggestion: 'Use sequential step numbers starting from 1',
|
||||
});
|
||||
break;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Validate dependencies
|
||||
*/
|
||||
private validateDependencies(plan: StructuredPlan, issues: ValidationIssue[]): void {
|
||||
const taskIds = new Set(plan.tasks.map((t) => t.id));
|
||||
|
||||
for (const task of plan.tasks) {
|
||||
if (task.dependencies) {
|
||||
for (const depId of task.dependencies) {
|
||||
// Check dependency exists
|
||||
if (!taskIds.has(depId)) {
|
||||
issues.push({
|
||||
type: 'error',
|
||||
message: `Task ${task.id} depends on non-existent task ${depId}`,
|
||||
taskId: task.id,
|
||||
suggestion: `Remove dependency on task ${depId} or add the missing task`,
|
||||
});
|
||||
}
|
||||
|
||||
// Check for self-dependency
|
||||
if (depId === task.id) {
|
||||
issues.push({
|
||||
type: 'error',
|
||||
message: `Task ${task.id} depends on itself`,
|
||||
taskId: task.id,
|
||||
suggestion: 'Remove self-dependency',
|
||||
});
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Check for circular dependencies
|
||||
const circularDeps = this.findCircularDependencies(plan);
|
||||
for (const cycle of circularDeps) {
|
||||
issues.push({
|
||||
type: 'error',
|
||||
message: `Circular dependency detected: ${cycle.join(' -> ')}`,
|
||||
suggestion: 'Remove one of the dependencies to break the cycle',
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Find circular dependencies
|
||||
*/
|
||||
private findCircularDependencies(plan: StructuredPlan): number[][] {
|
||||
const cycles: number[][] = [];
|
||||
const taskMap = new Map(plan.tasks.map((t) => [t.id, t]));
|
||||
const visited = new Set<number>();
|
||||
const recursionStack = new Set<number>();
|
||||
const path: number[] = [];
|
||||
|
||||
const dfs = (taskId: number): void => {
|
||||
if (recursionStack.has(taskId)) {
|
||||
// Found a cycle
|
||||
const cycleStart = path.indexOf(taskId);
|
||||
if (cycleStart !== -1) {
|
||||
cycles.push([...path.slice(cycleStart), taskId]);
|
||||
}
|
||||
return;
|
||||
}
|
||||
|
||||
if (visited.has(taskId)) return;
|
||||
|
||||
visited.add(taskId);
|
||||
recursionStack.add(taskId);
|
||||
path.push(taskId);
|
||||
|
||||
const task = taskMap.get(taskId);
|
||||
if (task?.dependencies) {
|
||||
for (const depId of task.dependencies) {
|
||||
dfs(depId);
|
||||
}
|
||||
}
|
||||
|
||||
path.pop();
|
||||
recursionStack.delete(taskId);
|
||||
};
|
||||
|
||||
for (const task of plan.tasks) {
|
||||
if (!visited.has(task.id)) {
|
||||
dfs(task.id);
|
||||
}
|
||||
}
|
||||
|
||||
return cycles;
|
||||
}
|
||||
|
||||
/**
|
||||
* Calculate plan statistics
|
||||
*/
|
||||
private calculateStats(plan: StructuredPlan): PlanValidationResult['stats'] {
|
||||
const totalTasks = plan.tasks.length;
|
||||
const totalSteps = plan.tasks.reduce((sum, t) => sum + t.steps.length, 0);
|
||||
const estimatedMinutes = plan.tasks.reduce((sum, t) => sum + (t.estimatedMinutes || 3), 0);
|
||||
const tasksWithTests = plan.tasks.filter(
|
||||
(t) => t.steps.some((s) => s.type === 'test') || (t.files.test && t.files.test.length > 0)
|
||||
).length;
|
||||
const tasksWithCommits = plan.tasks.filter((t) => t.steps.some((s) => s.type === 'commit')).length;
|
||||
const avgStepsPerTask = totalTasks > 0 ? Math.round((totalSteps / totalTasks) * 10) / 10 : 0;
|
||||
|
||||
return {
|
||||
totalTasks,
|
||||
totalSteps,
|
||||
estimatedMinutes,
|
||||
tasksWithTests,
|
||||
tasksWithCommits,
|
||||
avgStepsPerTask,
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Quick validation check (just returns valid/invalid)
|
||||
*/
|
||||
isValid(plan: StructuredPlan): boolean {
|
||||
return this.validate(plan).valid;
|
||||
}
|
||||
|
||||
/**
|
||||
* Get errors only
|
||||
*/
|
||||
getErrors(plan: StructuredPlan): ValidationIssue[] {
|
||||
return this.validate(plan).issues.filter((i) => i.type === 'error');
|
||||
}
|
||||
|
||||
/**
|
||||
* Get warnings only
|
||||
*/
|
||||
getWarnings(plan: StructuredPlan): ValidationIssue[] {
|
||||
return this.validate(plan).issues.filter((i) => i.type === 'warning');
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Create a PlanValidator instance
|
||||
*/
|
||||
export function createPlanValidator(options?: ValidatorOptions): PlanValidator {
|
||||
return new PlanValidator(options);
|
||||
}
|
||||
|
||||
/**
|
||||
* Quick validation helper
|
||||
*/
|
||||
export function validatePlan(plan: StructuredPlan, options?: ValidatorOptions): PlanValidationResult {
|
||||
return createPlanValidator(options).validate(plan);
|
||||
}
|
||||
+68
-5
@@ -32,16 +32,65 @@ skillkit
|
||||
|
||||
## Screens
|
||||
|
||||
### Home
|
||||
### Home (h)
|
||||
Overview of your project and quick actions. Shows detected agents, installed skills count, and navigation hints.
|
||||
|
||||
### Marketplace (m)
|
||||
Browse curated skill marketplace:
|
||||
- Search across 33+ repositories
|
||||
- Filter by tags and categories
|
||||
- View popularity metrics
|
||||
- Install with one key
|
||||
|
||||
### Browse (b)
|
||||
Explore available skills from curated repositories. Features:
|
||||
Explore available skills from curated repositories:
|
||||
- Search skills with `/`
|
||||
- Filter by tags
|
||||
- View skill details
|
||||
- One-key installation
|
||||
|
||||
### Workflow (w)
|
||||
Manage and execute workflows:
|
||||
- List available workflows
|
||||
- View workflow steps
|
||||
- Execute workflows
|
||||
- Monitor progress
|
||||
|
||||
### Execute (x)
|
||||
Execute skills with checkpoints:
|
||||
- Task-based execution
|
||||
- Decision and review checkpoints
|
||||
- Dry-run mode
|
||||
- Git integration
|
||||
|
||||
### Team (a)
|
||||
Team collaboration management:
|
||||
- Create and share skill bundles
|
||||
- Import team bundles
|
||||
- Sync with remote registry
|
||||
- Manage team members
|
||||
|
||||
### Plugins (p)
|
||||
Plugin system management:
|
||||
- List installed plugins
|
||||
- Install new plugins
|
||||
- Enable/disable plugins
|
||||
- View plugin details
|
||||
|
||||
### Methodology (o)
|
||||
Development methodologies:
|
||||
- Browse 5 methodologies (Agile, TDD, DevOps, Design Thinking, Feature Flags)
|
||||
- View methodology skills
|
||||
- Apply to project
|
||||
- Track adoption
|
||||
|
||||
### Plan (n)
|
||||
Structured plan system:
|
||||
- Parse plan files
|
||||
- Validate plan structure
|
||||
- Execute plans step-by-step
|
||||
- Track progress
|
||||
|
||||
### Recommend (r)
|
||||
AI-powered skill suggestions based on your project:
|
||||
- Analyzes your package.json, configs, and file structure
|
||||
@@ -63,7 +112,14 @@ View and manage project context:
|
||||
- Installed agents
|
||||
- Sync context to all agents
|
||||
|
||||
### Installed (l)
|
||||
### Memory (e)
|
||||
Session memory system:
|
||||
- View learnings
|
||||
- Search past sessions
|
||||
- Compress observations
|
||||
- Export as skills
|
||||
|
||||
### Installed (i)
|
||||
Manage your installed skills:
|
||||
- View all installed skills
|
||||
- Enable/disable skills
|
||||
@@ -87,17 +143,24 @@ Configure SkillKit:
|
||||
| Key | Action |
|
||||
|-----|--------|
|
||||
| `h` | Home screen |
|
||||
| `m` | Marketplace |
|
||||
| `b` | Browse skills |
|
||||
| `w` | Workflows |
|
||||
| `x` | Execute |
|
||||
| `a` | Team collaboration |
|
||||
| `p` | Plugins |
|
||||
| `o` | Methodology |
|
||||
| `n` | Plan system |
|
||||
| `r` | Recommendations |
|
||||
| `t` | Translate skills |
|
||||
| `c` | Context management |
|
||||
| `l` | List installed |
|
||||
| `e` | Memory/Learnings |
|
||||
| `i` | Installed skills |
|
||||
| `s` | Sync skills |
|
||||
| `,` | Settings |
|
||||
| `↑/↓` | Navigate lists |
|
||||
| `Enter` | Select / Confirm |
|
||||
| `/` | Search |
|
||||
| `m` | Multi-select mode |
|
||||
| `Tab` | Switch focus |
|
||||
| `Esc` | Go back |
|
||||
| `?` | Help |
|
||||
|
||||
@@ -16,8 +16,10 @@ import { Marketplace } from './screens/Marketplace.js';
|
||||
import { Memory } from './screens/Memory.js';
|
||||
import { Team } from './screens/Team.js';
|
||||
import { Plugins } from './screens/Plugins.js';
|
||||
import { Methodology } from './screens/Methodology.js';
|
||||
import { Plan } from './screens/Plan.js';
|
||||
|
||||
export type Screen = 'home' | 'browse' | 'installed' | 'sync' | 'settings' | 'recommend' | 'translate' | 'context' | 'workflow' | 'execute' | 'history' | 'marketplace' | 'memory' | 'team' | 'plugins';
|
||||
export type Screen = 'home' | 'browse' | 'installed' | 'sync' | 'settings' | 'recommend' | 'translate' | 'context' | 'workflow' | 'execute' | 'history' | 'marketplace' | 'memory' | 'team' | 'plugins' | 'methodology' | 'plan';
|
||||
|
||||
export function App() {
|
||||
const [screen, setScreen] = useState<Screen>('home');
|
||||
@@ -43,6 +45,8 @@ export function App() {
|
||||
s: 'sync',
|
||||
a: 'team',
|
||||
p: 'plugins',
|
||||
o: 'methodology',
|
||||
n: 'plan',
|
||||
',': 'settings',
|
||||
};
|
||||
|
||||
@@ -78,6 +82,8 @@ export function App() {
|
||||
case 'memory': return <Memory cols={cols} rows={rows} />;
|
||||
case 'team': return <Team cols={cols} rows={rows} />;
|
||||
case 'plugins': return <Plugins cols={cols} rows={rows} />;
|
||||
case 'methodology': return <Methodology cols={cols} rows={rows} />;
|
||||
case 'plan': return <Plan cols={cols} rows={rows} />;
|
||||
}
|
||||
};
|
||||
|
||||
@@ -92,7 +98,7 @@ export function App() {
|
||||
</Box>
|
||||
</Box>
|
||||
<Box>
|
||||
<Text dimColor>h Home m Market b Browse i Inst w Wflow x Exec a Team p Plug r Rec t Trans c Ctx e Mem s Sync , Cfg q Quit</Text>
|
||||
<Text dimColor>h Home m Market b Browse w Wflow x Exec a Team p Plug o Meth n Plan r Rec t Trans c Ctx e Mem i Inst s Sync q Quit</Text>
|
||||
</Box>
|
||||
</Box>
|
||||
);
|
||||
|
||||
@@ -20,6 +20,9 @@ const NAV: { id: Screen; label: string; key: string }[] = [
|
||||
// Collaboration
|
||||
{ id: 'team', label: 'Team', key: 'a' },
|
||||
{ id: 'plugins', label: 'Plugins', key: 'p' },
|
||||
// Methodology
|
||||
{ id: 'methodology', label: 'Methodology', key: 'o' },
|
||||
{ id: 'plan', label: 'Plans', key: 'n' },
|
||||
// Tools
|
||||
{ id: 'recommend', label: 'Recommend', key: 'r' },
|
||||
{ id: 'translate', label: 'Translate', key: 't' },
|
||||
@@ -63,8 +66,8 @@ export function Sidebar({ screen }: SidebarProps) {
|
||||
|
||||
<Text> </Text>
|
||||
|
||||
{/* Tools (8-11) */}
|
||||
{NAV.slice(8, 12).map((item) => (
|
||||
{/* Methodology (8-9) */}
|
||||
{NAV.slice(8, 10).map((item) => (
|
||||
<Text key={item.id} inverse={screen === item.id}>
|
||||
{screen === item.id ? symbols.bullet : ' '}{item.label}
|
||||
</Text>
|
||||
@@ -72,8 +75,17 @@ export function Sidebar({ screen }: SidebarProps) {
|
||||
|
||||
<Text> </Text>
|
||||
|
||||
{/* Management (12-14) */}
|
||||
{NAV.slice(12).map((item) => (
|
||||
{/* Tools (10-13) */}
|
||||
{NAV.slice(10, 14).map((item) => (
|
||||
<Text key={item.id} inverse={screen === item.id}>
|
||||
{screen === item.id ? symbols.bullet : ' '}{item.label}
|
||||
</Text>
|
||||
))}
|
||||
|
||||
<Text> </Text>
|
||||
|
||||
{/* Management (14-16) */}
|
||||
{NAV.slice(14).map((item) => (
|
||||
<Text key={item.id} inverse={screen === item.id}>
|
||||
{screen === item.id ? symbols.bullet : ' '}{item.label}
|
||||
</Text>
|
||||
|
||||
@@ -0,0 +1,186 @@
|
||||
import { useState, useEffect, useMemo } from 'react';
|
||||
import { Box, Text, useInput } from 'ink';
|
||||
import { colors, symbols } from '../theme.js';
|
||||
import {
|
||||
MethodologyManager,
|
||||
type MethodologyPack,
|
||||
type MethodologySkill,
|
||||
} from '@skillkit/core';
|
||||
|
||||
interface Props {
|
||||
cols?: number;
|
||||
rows?: number;
|
||||
}
|
||||
|
||||
type View = 'packs' | 'skills';
|
||||
|
||||
export function Methodology({ rows = 24 }: Props) {
|
||||
const [packs, setPacks] = useState<MethodologyPack[]>([]);
|
||||
const [selectedPack, setSelectedPack] = useState<MethodologyPack | null>(null);
|
||||
const [skills, setSkills] = useState<MethodologySkill[]>([]);
|
||||
const [loading, setLoading] = useState(true);
|
||||
const [view, setView] = useState<View>('packs');
|
||||
const [sel, setSel] = useState(0);
|
||||
const [error, setError] = useState<string | null>(null);
|
||||
const [message, setMessage] = useState<string | null>(null);
|
||||
|
||||
const manager = useMemo(() => new MethodologyManager({
|
||||
projectPath: process.cwd(),
|
||||
}), []);
|
||||
|
||||
const maxVisible = Math.max(5, rows - 10);
|
||||
|
||||
useEffect(() => {
|
||||
loadPacks();
|
||||
}, []);
|
||||
|
||||
const loadPacks = async () => {
|
||||
setLoading(true);
|
||||
setError(null);
|
||||
try {
|
||||
const loadedPacks = await manager.listAvailablePacks();
|
||||
setPacks(loadedPacks);
|
||||
} catch (e) {
|
||||
setError(e instanceof Error ? e.message : 'Failed to load methodology packs');
|
||||
}
|
||||
setLoading(false);
|
||||
};
|
||||
|
||||
const loadSkills = async (pack: MethodologyPack) => {
|
||||
setLoading(true);
|
||||
setError(null);
|
||||
try {
|
||||
const loader = manager.getLoader();
|
||||
const loadedSkills = await loader.loadPackSkills(pack.name);
|
||||
setSkills(loadedSkills);
|
||||
setSelectedPack(pack);
|
||||
setView('skills');
|
||||
setSel(0);
|
||||
} catch (e) {
|
||||
setError(e instanceof Error ? e.message : 'Failed to load skills');
|
||||
}
|
||||
setLoading(false);
|
||||
};
|
||||
|
||||
const installPack = async (pack: MethodologyPack) => {
|
||||
setLoading(true);
|
||||
setMessage(null);
|
||||
try {
|
||||
await manager.installPack(pack.name);
|
||||
setMessage(`Installed ${pack.name} methodology pack`);
|
||||
// Refresh packs list after install
|
||||
await loadPacks();
|
||||
} catch (e) {
|
||||
setError(e instanceof Error ? e.message : 'Failed to install pack');
|
||||
}
|
||||
setLoading(false);
|
||||
};
|
||||
|
||||
const items = view === 'packs' ? packs : skills;
|
||||
const start = Math.max(0, Math.min(sel - Math.floor(maxVisible / 2), items.length - maxVisible));
|
||||
const visible = items.slice(start, start + maxVisible);
|
||||
|
||||
useInput((input, key) => {
|
||||
if (loading) return;
|
||||
|
||||
if (key.upArrow) setSel(i => Math.max(0, i - 1));
|
||||
else if (key.downArrow) setSel(i => Math.min(items.length - 1, i + 1));
|
||||
else if (input === 'r') {
|
||||
if (view === 'packs') loadPacks();
|
||||
else if (selectedPack) loadSkills(selectedPack);
|
||||
}
|
||||
else if (key.escape || input === 'b') {
|
||||
if (view === 'skills') {
|
||||
setView('packs');
|
||||
setSel(0);
|
||||
setSelectedPack(null);
|
||||
}
|
||||
}
|
||||
else if (key.return) {
|
||||
if (view === 'packs' && packs[sel]) {
|
||||
loadSkills(packs[sel]);
|
||||
}
|
||||
}
|
||||
else if (input === 'i' && view === 'packs' && packs[sel]) {
|
||||
installPack(packs[sel]);
|
||||
}
|
||||
});
|
||||
|
||||
const renderPackItem = (pack: MethodologyPack, idx: number) => {
|
||||
const isSel = idx === sel;
|
||||
return (
|
||||
<Box key={pack.name} flexDirection="column">
|
||||
<Text inverse={isSel}>
|
||||
{isSel ? symbols.pointer : ' '} {pack.name} <Text dimColor>v{pack.version}</Text>
|
||||
</Text>
|
||||
{isSel && (
|
||||
<>
|
||||
<Text dimColor> {pack.description}</Text>
|
||||
<Text dimColor> {pack.skills.length} skill(s) | Tags: {pack.tags?.join(', ') || 'none'}</Text>
|
||||
</>
|
||||
)}
|
||||
</Box>
|
||||
);
|
||||
};
|
||||
|
||||
const renderSkillItem = (skill: MethodologySkill, idx: number) => {
|
||||
const isSel = idx === sel;
|
||||
return (
|
||||
<Box key={skill.name} flexDirection="column">
|
||||
<Text inverse={isSel}>
|
||||
{isSel ? symbols.pointer : ' '} {skill.name}
|
||||
</Text>
|
||||
{isSel && skill.description && (
|
||||
<Text dimColor> {skill.description}</Text>
|
||||
)}
|
||||
{isSel && skill.tags && (
|
||||
<Text dimColor> Tags: {skill.tags.join(', ')}</Text>
|
||||
)}
|
||||
</Box>
|
||||
);
|
||||
};
|
||||
|
||||
return (
|
||||
<Box flexDirection="column">
|
||||
<Text bold color={colors.primary}>
|
||||
{view === 'packs' ? 'METHODOLOGY PACKS' : `${selectedPack?.name.toUpperCase()} SKILLS`}
|
||||
</Text>
|
||||
<Text dimColor>
|
||||
{view === 'packs'
|
||||
? `${packs.length} pack(s) available`
|
||||
: `${skills.length} skill(s) in pack`}
|
||||
</Text>
|
||||
|
||||
{loading && <Text color="yellow">Loading...</Text>}
|
||||
{error && <Text color="red">{symbols.error} {error}</Text>}
|
||||
{message && <Text color="green">{symbols.success} {message}</Text>}
|
||||
|
||||
{!loading && items.length === 0 && (
|
||||
<Box marginTop={1}>
|
||||
<Text dimColor>No {view === 'packs' ? 'methodology packs' : 'skills'} found.</Text>
|
||||
</Box>
|
||||
)}
|
||||
|
||||
{!loading && items.length > 0 && (
|
||||
<Box marginTop={1} flexDirection="column">
|
||||
{start > 0 && <Text dimColor> {symbols.arrowUp} {start} more</Text>}
|
||||
{view === 'packs'
|
||||
? (visible as MethodologyPack[]).map((pack, i) => renderPackItem(pack, start + i))
|
||||
: (visible as MethodologySkill[]).map((skill, i) => renderSkillItem(skill, start + i))
|
||||
}
|
||||
{start + maxVisible < items.length && (
|
||||
<Text dimColor> {symbols.arrowDown} {items.length - start - maxVisible} more</Text>
|
||||
)}
|
||||
</Box>
|
||||
)}
|
||||
|
||||
<Box marginTop={1} flexDirection="column">
|
||||
{view === 'packs' ? (
|
||||
<Text dimColor>Enter=view skills i=install r=refresh q=quit</Text>
|
||||
) : (
|
||||
<Text dimColor>b/Esc=back r=refresh q=quit</Text>
|
||||
)}
|
||||
</Box>
|
||||
</Box>
|
||||
);
|
||||
}
|
||||
@@ -0,0 +1,288 @@
|
||||
import { useState, useEffect, useMemo } from 'react';
|
||||
import { Box, Text, useInput } from 'ink';
|
||||
import { colors, symbols } from '../theme.js';
|
||||
import {
|
||||
PlanParser,
|
||||
PlanValidator,
|
||||
PlanExecutor,
|
||||
type StructuredPlan,
|
||||
type PlanTask,
|
||||
} from '@skillkit/core';
|
||||
import * as fs from 'fs';
|
||||
import * as path from 'path';
|
||||
|
||||
interface Props {
|
||||
cols?: number;
|
||||
rows?: number;
|
||||
}
|
||||
|
||||
type View = 'plans' | 'tasks' | 'steps';
|
||||
|
||||
interface PlanFile {
|
||||
name: string;
|
||||
path: string;
|
||||
plan?: StructuredPlan;
|
||||
valid?: boolean;
|
||||
error?: string;
|
||||
}
|
||||
|
||||
export function Plan({ rows = 24 }: Props) {
|
||||
const [planFiles, setPlanFiles] = useState<PlanFile[]>([]);
|
||||
const [selectedPlan, setSelectedPlan] = useState<PlanFile | null>(null);
|
||||
const [selectedTask, setSelectedTask] = useState<PlanTask | null>(null);
|
||||
const [loading, setLoading] = useState(true);
|
||||
const [view, setView] = useState<View>('plans');
|
||||
const [sel, setSel] = useState(0);
|
||||
const [error, setError] = useState<string | null>(null);
|
||||
const [executing, setExecuting] = useState(false);
|
||||
const [message, setMessage] = useState<string | null>(null);
|
||||
|
||||
const parser = useMemo(() => new PlanParser(), []);
|
||||
const validator = useMemo(() => new PlanValidator(), []);
|
||||
|
||||
const maxVisible = Math.max(5, rows - 10);
|
||||
|
||||
useEffect(() => {
|
||||
loadPlans();
|
||||
}, []);
|
||||
|
||||
const loadPlans = async () => {
|
||||
setLoading(true);
|
||||
setError(null);
|
||||
try {
|
||||
const cwd = process.cwd();
|
||||
const files: PlanFile[] = [];
|
||||
|
||||
// Look for plan files in common locations
|
||||
const searchPaths = [
|
||||
cwd,
|
||||
path.join(cwd, 'plans'),
|
||||
path.join(cwd, '.skillkit', 'plans'),
|
||||
];
|
||||
|
||||
for (const searchPath of searchPaths) {
|
||||
if (fs.existsSync(searchPath)) {
|
||||
const entries = fs.readdirSync(searchPath, { withFileTypes: true });
|
||||
for (const entry of entries) {
|
||||
if (entry.isFile() && (entry.name.endsWith('.plan.md') || entry.name.endsWith('-plan.md'))) {
|
||||
const filePath = path.join(searchPath, entry.name);
|
||||
const content = fs.readFileSync(filePath, 'utf-8');
|
||||
try {
|
||||
const plan = parser.parse(content);
|
||||
const validation = validator.validate(plan);
|
||||
const errorIssue = validation.issues.find(i => i.type === 'error');
|
||||
files.push({
|
||||
name: entry.name,
|
||||
path: filePath,
|
||||
plan,
|
||||
valid: validation.valid,
|
||||
error: errorIssue?.message,
|
||||
});
|
||||
} catch {
|
||||
files.push({
|
||||
name: entry.name,
|
||||
path: filePath,
|
||||
valid: false,
|
||||
error: 'Failed to parse plan',
|
||||
});
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
setPlanFiles(files);
|
||||
} catch (e) {
|
||||
setError(e instanceof Error ? e.message : 'Failed to load plans');
|
||||
}
|
||||
setLoading(false);
|
||||
};
|
||||
|
||||
const selectPlan = (planFile: PlanFile) => {
|
||||
if (planFile.plan) {
|
||||
setSelectedPlan(planFile);
|
||||
setView('tasks');
|
||||
setSel(0);
|
||||
}
|
||||
};
|
||||
|
||||
const selectTask = (task: PlanTask) => {
|
||||
setSelectedTask(task);
|
||||
setView('steps');
|
||||
setSel(0);
|
||||
};
|
||||
|
||||
const executePlan = async (planFile: PlanFile) => {
|
||||
if (!planFile.plan) return;
|
||||
|
||||
setExecuting(true);
|
||||
setMessage(null);
|
||||
try {
|
||||
const executor = new PlanExecutor();
|
||||
await executor.execute(planFile.plan, { dryRun: true });
|
||||
setMessage(`Executed plan: ${planFile.plan.name} (dry run)`);
|
||||
} catch (e) {
|
||||
setError(e instanceof Error ? e.message : 'Failed to execute plan');
|
||||
}
|
||||
setExecuting(false);
|
||||
};
|
||||
|
||||
const getItems = () => {
|
||||
if (view === 'plans') return planFiles;
|
||||
if (view === 'tasks' && selectedPlan?.plan) return selectedPlan.plan.tasks;
|
||||
if (view === 'steps' && selectedTask) return selectedTask.steps;
|
||||
return [];
|
||||
};
|
||||
|
||||
const items = getItems();
|
||||
const start = Math.max(0, Math.min(sel - Math.floor(maxVisible / 2), items.length - maxVisible));
|
||||
const visible = items.slice(start, start + maxVisible);
|
||||
|
||||
useInput((input, key) => {
|
||||
if (loading || executing) return;
|
||||
|
||||
if (key.upArrow) setSel(i => Math.max(0, i - 1));
|
||||
else if (key.downArrow) setSel(i => Math.min(items.length - 1, i + 1));
|
||||
else if (input === 'r') loadPlans();
|
||||
else if (key.escape || input === 'b') {
|
||||
if (view === 'steps') {
|
||||
setView('tasks');
|
||||
setSelectedTask(null);
|
||||
setSel(0);
|
||||
} else if (view === 'tasks') {
|
||||
setView('plans');
|
||||
setSelectedPlan(null);
|
||||
setSel(0);
|
||||
}
|
||||
}
|
||||
else if (key.return) {
|
||||
if (view === 'plans' && planFiles[sel]) {
|
||||
selectPlan(planFiles[sel]);
|
||||
} else if (view === 'tasks' && selectedPlan?.plan?.tasks[sel]) {
|
||||
selectTask(selectedPlan.plan.tasks[sel]);
|
||||
}
|
||||
}
|
||||
else if (input === 'x' && view === 'plans' && planFiles[sel]?.plan) {
|
||||
executePlan(planFiles[sel]);
|
||||
}
|
||||
});
|
||||
|
||||
const renderPlanItem = (planFile: PlanFile, idx: number) => {
|
||||
const isSel = idx === sel;
|
||||
const statusIcon = planFile.valid ? symbols.success : symbols.error;
|
||||
const statusColor = planFile.valid ? 'green' : 'red';
|
||||
|
||||
return (
|
||||
<Box key={planFile.path} flexDirection="column">
|
||||
<Text inverse={isSel}>
|
||||
{isSel ? symbols.pointer : ' '} <Text color={statusColor}>{statusIcon}</Text> {planFile.name}
|
||||
</Text>
|
||||
{isSel && planFile.plan && (
|
||||
<>
|
||||
<Text dimColor> {planFile.plan.goal}</Text>
|
||||
<Text dimColor> {planFile.plan.tasks.length} task(s) | {planFile.plan.techStack?.join(', ') || 'No stack'}</Text>
|
||||
</>
|
||||
)}
|
||||
{isSel && planFile.error && (
|
||||
<Text color="red"> {planFile.error}</Text>
|
||||
)}
|
||||
</Box>
|
||||
);
|
||||
};
|
||||
|
||||
const renderTaskItem = (task: PlanTask, idx: number) => {
|
||||
const isSel = idx === sel;
|
||||
return (
|
||||
<Box key={task.id} flexDirection="column">
|
||||
<Text inverse={isSel}>
|
||||
{isSel ? symbols.pointer : ' '} [{task.id}] {task.name}
|
||||
</Text>
|
||||
{isSel && (
|
||||
<>
|
||||
<Text dimColor> {task.steps.length} step(s)</Text>
|
||||
{task.files?.create && <Text dimColor> Create: {task.files.create.join(', ')}</Text>}
|
||||
{task.files?.modify && <Text dimColor> Modify: {task.files.modify.join(', ')}</Text>}
|
||||
{task.files?.test && <Text dimColor> Test: {task.files.test.join(', ')}</Text>}
|
||||
</>
|
||||
)}
|
||||
</Box>
|
||||
);
|
||||
};
|
||||
|
||||
const renderStepItem = (step: { number: number; description: string; type: string }, idx: number) => {
|
||||
const isSel = idx === sel;
|
||||
const typeColors: Record<string, string> = {
|
||||
test: 'yellow',
|
||||
verify: 'cyan',
|
||||
implement: 'green',
|
||||
commit: 'magenta',
|
||||
};
|
||||
|
||||
return (
|
||||
<Box key={step.number} flexDirection="column">
|
||||
<Text inverse={isSel}>
|
||||
{isSel ? symbols.pointer : ' '} <Text color={typeColors[step.type] || 'white'}>[{step.type}]</Text> Step {step.number}
|
||||
</Text>
|
||||
{isSel && (
|
||||
<Text dimColor> {step.description}</Text>
|
||||
)}
|
||||
</Box>
|
||||
);
|
||||
};
|
||||
|
||||
const getTitle = () => {
|
||||
if (view === 'plans') return 'PLANS';
|
||||
if (view === 'tasks') return `TASKS: ${selectedPlan?.plan?.name || ''}`;
|
||||
if (view === 'steps') return `STEPS: Task ${selectedTask?.id}`;
|
||||
return 'PLANS';
|
||||
};
|
||||
|
||||
return (
|
||||
<Box flexDirection="column">
|
||||
<Text bold color={colors.primary}>{getTitle()}</Text>
|
||||
<Text dimColor>
|
||||
{view === 'plans' && `${planFiles.length} plan(s) found`}
|
||||
{view === 'tasks' && selectedPlan?.plan && `${selectedPlan.plan.tasks.length} task(s)`}
|
||||
{view === 'steps' && selectedTask && `${selectedTask.steps.length} step(s)`}
|
||||
</Text>
|
||||
|
||||
{loading && <Text color="yellow">Loading plans...</Text>}
|
||||
{executing && <Text color="yellow">Executing plan...</Text>}
|
||||
{error && <Text color="red">{symbols.error} {error}</Text>}
|
||||
{message && <Text color="green">{symbols.success} {message}</Text>}
|
||||
|
||||
{!loading && !executing && items.length === 0 && (
|
||||
<Box marginTop={1} flexDirection="column">
|
||||
<Text dimColor>No {view} found.</Text>
|
||||
{view === 'plans' && (
|
||||
<Text dimColor>Create a plan file: *.plan.md or *-plan.md</Text>
|
||||
)}
|
||||
</Box>
|
||||
)}
|
||||
|
||||
{!loading && !executing && items.length > 0 && (
|
||||
<Box marginTop={1} flexDirection="column">
|
||||
{start > 0 && <Text dimColor> ↑ {start} more</Text>}
|
||||
{view === 'plans' && (visible as PlanFile[]).map((pf, i) => renderPlanItem(pf, start + i))}
|
||||
{view === 'tasks' && (visible as PlanTask[]).map((t, i) => renderTaskItem(t, start + i))}
|
||||
{view === 'steps' && (visible as Array<{ number: number; description: string; type: string }>).map((s, i) => renderStepItem(s, start + i))}
|
||||
{start + maxVisible < items.length && (
|
||||
<Text dimColor> ↓ {items.length - start - maxVisible} more</Text>
|
||||
)}
|
||||
</Box>
|
||||
)}
|
||||
|
||||
<Box marginTop={1}>
|
||||
{view === 'plans' && (
|
||||
<Text dimColor>Enter=view tasks x=execute (dry-run) r=refresh q=quit</Text>
|
||||
)}
|
||||
{view === 'tasks' && (
|
||||
<Text dimColor>Enter=view steps b/Esc=back q=quit</Text>
|
||||
)}
|
||||
{view === 'steps' && (
|
||||
<Text dimColor>b/Esc=back q=quit</Text>
|
||||
)}
|
||||
</Box>
|
||||
</Box>
|
||||
);
|
||||
}
|
||||
@@ -13,3 +13,5 @@ export { History } from './History.js';
|
||||
export { Marketplace } from './Marketplace.js';
|
||||
export { Team } from './Team.js';
|
||||
export { Plugins } from './Plugins.js';
|
||||
export { Methodology } from './Methodology.js';
|
||||
export { Plan } from './Plan.js';
|
||||
|
||||
Generated
+59
@@ -63,6 +63,9 @@ importers:
|
||||
'@skillkit/core':
|
||||
specifier: workspace:*
|
||||
version: link:../core
|
||||
minimatch:
|
||||
specifier: ^9.0.0
|
||||
version: 9.0.5
|
||||
devDependencies:
|
||||
'@types/node':
|
||||
specifier: ^22.10.5
|
||||
@@ -122,6 +125,12 @@ importers:
|
||||
|
||||
packages/core:
|
||||
dependencies:
|
||||
'@types/minimatch':
|
||||
specifier: ^6.0.0
|
||||
version: 6.0.0
|
||||
minimatch:
|
||||
specifier: ^10.1.1
|
||||
version: 10.1.1
|
||||
yaml:
|
||||
specifier: ^2.6.1
|
||||
version: 2.8.2
|
||||
@@ -485,6 +494,14 @@ packages:
|
||||
cpu: [x64]
|
||||
os: [win32]
|
||||
|
||||
'@isaacs/balanced-match@4.0.1':
|
||||
resolution: {integrity: sha512-yzMTt9lEb8Gv7zRioUilSglI0c0smZ9k5D65677DLWLtWJaXIS3CqcGyUFByYKlnUj6TkjLVs54fBl6+TiGQDQ==}
|
||||
engines: {node: 20 || >=22}
|
||||
|
||||
'@isaacs/brace-expansion@5.0.0':
|
||||
resolution: {integrity: sha512-ZT55BDLV0yv0RBm2czMiZ+SqCGO7AvmOM3G/w2xhVPH+te0aKgFjmBvGlL1dH+ql2tgGO3MVrbb3jCKyvpgnxA==}
|
||||
engines: {node: 20 || >=22}
|
||||
|
||||
'@jridgewell/gen-mapping@0.3.13':
|
||||
resolution: {integrity: sha512-2kkt/7niJ6MgEPxF0bYdQ6etZaA+fQvDcLKckhy1yIQOzaoKjBBjSj63/aLVjYE3qhRt5dvM+uUyfCg6UKCBbA==}
|
||||
|
||||
@@ -639,6 +656,10 @@ packages:
|
||||
'@types/http-cache-semantics@4.0.4':
|
||||
resolution: {integrity: sha512-1m0bIFVc7eJWyve9S0RnuRgcQqF/Xd5QsUZAZeQFr1Q3/p9JWoQQEqmVy+DPTNpGXwhgIetAoYF8JSc33q29QA==}
|
||||
|
||||
'@types/minimatch@6.0.0':
|
||||
resolution: {integrity: sha512-zmPitbQ8+6zNutpwgcQuLcsEpn/Cj54Kbn7L5pX0Os5kdWplB7xPgEh/g+SWOB/qmows2gpuCaPyduq8ZZRnxA==}
|
||||
deprecated: This is a stub types definition. minimatch provides its own type definitions, so you do not need this installed.
|
||||
|
||||
'@types/node@22.19.7':
|
||||
resolution: {integrity: sha512-MciR4AKGHWl7xwxkBa6xUGxQJ4VBOmPTF7sL+iGzuahOFaO0jHCsuEfS80pan1ef4gWId1oWOweIhrDEYLuaOw==}
|
||||
|
||||
@@ -716,9 +737,15 @@ packages:
|
||||
resolution: {integrity: sha512-wvUjBtSGN7+7SjNpq/9M2Tg350UZD3q62IFZLbRAR1bSMlCo1ZaeW+BJ+D090e4hIIZLBcTDWe4Mh4jvUDajzQ==}
|
||||
engines: {node: '>= 0.4'}
|
||||
|
||||
balanced-match@1.0.2:
|
||||
resolution: {integrity: sha512-3oSeUO0TMV67hN1AmbXsK4yaqU7tjiHlbxRDZOpH0KW9+CeX4bRAaX0Anxt0tx2MrpRpWwQaPwIlISEJhYU5Pw==}
|
||||
|
||||
base64-js@1.5.1:
|
||||
resolution: {integrity: sha512-AKpaYlHn8t4SVbOHCy+b5+KKgvR4vrsD8vbvrbiQJps7fKDTkjkDry6ji0rUJjC0kzbNePLwzxq8iypo41qeWA==}
|
||||
|
||||
brace-expansion@2.0.2:
|
||||
resolution: {integrity: sha512-Jt0vHyM+jmUBqojB7E1NIYadt0vI0Qxjxd2TErW94wDz+E2LAm5vKMXXwg6ZZBTHPuUlDgQHKXvjGBdfcF1ZDQ==}
|
||||
|
||||
buffer@6.0.3:
|
||||
resolution: {integrity: sha512-FTiCpNxtwiZZHEZbcbTIcZjERVICn9yq/pDFkTl95/AxzD1naBctN7YO68riM/gLSDY7sdrMby8hofADYuuqOA==}
|
||||
|
||||
@@ -1143,6 +1170,14 @@ packages:
|
||||
resolution: {integrity: sha512-e5ISH9xMYU0DzrT+jl8q2ze9D6eWBto+I8CNpe+VI+K2J/F/k3PdkdTdz4wvGVH4NTpo+NRYTVIuMQEMMcsLqg==}
|
||||
engines: {node: ^12.20.0 || ^14.13.1 || >=16.0.0}
|
||||
|
||||
minimatch@10.1.1:
|
||||
resolution: {integrity: sha512-enIvLvRAFZYXJzkCYG5RKmPfrFArdLv+R+lbQ53BmIMLIry74bjKzX6iHAm8WYamJkhSSEabrWN5D97XnKObjQ==}
|
||||
engines: {node: 20 || >=22}
|
||||
|
||||
minimatch@9.0.5:
|
||||
resolution: {integrity: sha512-G6T0ZX48xgozx7587koeX9Ys2NYy6Gmv//P89sEte9V9whIapMNF4idKxnW2QtCcLiTWlb/wfCabAtAFWhhBow==}
|
||||
engines: {node: '>=16 || 14 >=14.17'}
|
||||
|
||||
minimist@1.2.8:
|
||||
resolution: {integrity: sha512-2yyAR8qBkN3YuheJanUpWC5U3bb5osDywNB8RzDVlDwDHbocAJveqqj1u8+SVD7jkWT4yvsHCpWqqWqAxb0zCA==}
|
||||
|
||||
@@ -1755,6 +1790,12 @@ snapshots:
|
||||
'@esbuild/win32-x64@0.27.2':
|
||||
optional: true
|
||||
|
||||
'@isaacs/balanced-match@4.0.1': {}
|
||||
|
||||
'@isaacs/brace-expansion@5.0.0':
|
||||
dependencies:
|
||||
'@isaacs/balanced-match': 4.0.1
|
||||
|
||||
'@jridgewell/gen-mapping@0.3.13':
|
||||
dependencies:
|
||||
'@jridgewell/sourcemap-codec': 1.5.5
|
||||
@@ -1854,6 +1895,10 @@ snapshots:
|
||||
|
||||
'@types/http-cache-semantics@4.0.4': {}
|
||||
|
||||
'@types/minimatch@6.0.0':
|
||||
dependencies:
|
||||
minimatch: 10.1.1
|
||||
|
||||
'@types/node@22.19.7':
|
||||
dependencies:
|
||||
undici-types: 6.21.0
|
||||
@@ -1931,8 +1976,14 @@ snapshots:
|
||||
dependencies:
|
||||
possible-typed-array-names: 1.1.0
|
||||
|
||||
balanced-match@1.0.2: {}
|
||||
|
||||
base64-js@1.5.1: {}
|
||||
|
||||
brace-expansion@2.0.2:
|
||||
dependencies:
|
||||
balanced-match: 1.0.2
|
||||
|
||||
buffer@6.0.3:
|
||||
dependencies:
|
||||
base64-js: 1.5.1
|
||||
@@ -2370,6 +2421,14 @@ snapshots:
|
||||
|
||||
mimic-response@4.0.0: {}
|
||||
|
||||
minimatch@10.1.1:
|
||||
dependencies:
|
||||
'@isaacs/brace-expansion': 5.0.0
|
||||
|
||||
minimatch@9.0.5:
|
||||
dependencies:
|
||||
brace-expansion: 2.0.2
|
||||
|
||||
minimist@1.2.8: {}
|
||||
|
||||
minimisted@2.0.1:
|
||||
|
||||
Reference in New Issue
Block a user