@agentskillkit/agent-skills 1.0.1 → 3.2.1

package/.agent/skills/requirements-python.txt

@@ -0,0 +1,25 @@
+# Python Dependencies for Agent Skill Kit v3.2.0
+# Skill-level validation scripts
+
+# Security Scanning
+bandit>=1.7.5
+safety>=2.3.0
+
+# Testing & Automation
+playwright>=1.40.0
+pytest>=7.4.0
+
+# Code Quality
+pylint>=3.0.0
+mypy>=1.7.0
+
+# Data Processing
+pyyaml>=6.0
+requests>=2.31.0
+
+# Optional: Performance & Analysis
+# numpy>=1.24.0
+# pandas>=2.0.0
+
+# Optional: ML for SelfEvolution
+# scikit-learn>=1.3.0

package/.agent/skills/requirements.txt

@@ -0,0 +1,96 @@
+# Python Dependencies
+
+## Minimum Requirements
+
+- **Python Version:** 3.8+
+- **pip:** Latest version recommended
+
+## Installation
+
+```bash
+# Install all Python dependencies for skill scripts
+pip install -r .agent/skills/requirements.txt
+
+# Or via npm
+npm run install:python-deps
+```
+
+## Core Dependencies
+
+### Security Scanning
+- `bandit>=1.7.5` - Python AST-based security linter
+- `safety>=2.3.0` - Checks Python dependencies for known vulnerabilities
+
+### Testing & Automation
+- `playwright>=1.40.0` - End-to-end browser testing
+- `pytest>=7.4.0` - Python testing framework
+
+### Code Quality
+- `pylint>=3.0.0` - Python code static checker
+- `mypy>=1.7.0` - Static type checker for Python
+
+### Data Processing
+- `pyyaml>=6.0` - YAML parser and emitter
+- `requests>=2.31.0` - HTTP library
+
+## Optional Dependencies
+
+Some skill scripts may require additional packages:
+
+```bash
+# Performance auditing (Lighthouse wrapper)
+npm install -g lighthouse
+
+# Accessibility testing
+pip install axe-selenium
+
+# ML/Data analysis (for SelfEvolution)
+pip install pandas scikit-learn
+```
+
+## Verification
+
+```bash
+# Verify Python installation
+python --version  # Should be 3.8+
+
+# Test critical scripts
+python .agent/skills/SecurityScanner/scripts/security_scan.py --help
+python .agent/skills/DesignSystem/scripts/ux_audit.py --help
+python .agent/skills/PerfOptimizer/scripts/lighthouse_audit.py --help
+```
+
+## Usage in CI/CD
+
+GitHub Actions example:
+
+```yaml
+- name: Setup Python
+  uses: actions/setup-python@v4
+  with:
+    python-version: '3.11'
+    
+- name: Install Python dependencies
+  run: pip install -r .agent/skills/requirements.txt
+  
+- name: Run skill validation
+  run: npm run verify http://localhost:3000
+```
+
+## Maintenance
+
+Update dependencies regularly:
+
+```bash
+# Update all packages
+pip install --upgrade -r .agent/skills/requirements.txt
+
+# Check for security vulnerabilities
+pip-audit
+```
+
+## See Also
+
+- [PYTHON_STRATEGY.md](../PYTHON_STRATEGY.md) - Architecture decision
+- [MIGRATION.md](../MIGRATION.md) - Migration history
+- [PYTHON_SCRIPTS.md](PYTHON_SCRIPTS.md) - Script reference

package/.agent/skills/state-rollback/SKILL.md

@@ -0,0 +1,240 @@
+---
+name: state-rollback
+description: >-
+  Save state before changes, restore on failure for safe code modifications. Provides
+  rollback capability for risky operations. Triggers on: before risky operations,
+  multi-file edits, rollback requests. Coordinates with: code-craft, problem-checker.
+metadata:
+  category: "core"
+  version: "1.0.0"
+  triggers: "before risky operations, multi-file edits, rollback requests, code breaks"
+  coordinates_with: "code-craft, app-scaffold, problem-checker"
+  success_metrics: "100% restore accuracy, state save <1s"
+---
+
+# state-rollback
+
+> **Purpose:** Save file state before modifications and restore on failure
+
+---
+
+## Safety Philosophy
+
+```
+Safety > Recoverability > Correctness > Cleanliness > Convenience
+```
+
+**Core Principle:** New output can be worse than old one. Always preserve ability to rollback.
+
+---
+
+## When to Invoke
+
+| Trigger | Action |
+|---------|--------|
+| Before modifying >3 files | Save state |
+| Before risky refactoring | Save state |
+| After modification fails | Restore state |
+| User says "rollback", "undo" | Restore state |
+
+---
+
+## State Management Protocol
+
+### Step 1: Save State (Before Modification)
+
+```javascript
+// Save current state of files to be modified
+const saveState = async (files) => {
+  const state = {
+    id: generateId(),
+    timestamp: new Date().toISOString(),
+    files: []
+  };
+  
+  for (const file of files) {
+    state.files.push({
+      path: file,
+      content: fs.readFileSync(file, 'utf8')
+    });
+  }
+  
+  saveToStateStore(state);
+  return state.id;
+};
+```
+
+### Step 2: Perform Modification
+
+```javascript
+// Wrap risky operation
+const safeModify = async (files, modifyFn) => {
+  const stateId = await saveState(files);
+  
+  try {
+    await modifyFn();
+    // Verify with problem-checker
+    const hasErrors = await checkProblems();
+    if (hasErrors) {
+      throw new Error('Modification introduced errors');
+    }
+  } catch (error) {
+    await restoreState(stateId);
+    throw error;
+  }
+};
+```
+
+### Step 3: Restore State (On Failure)
+
+```javascript
+// Restore files to saved state
+const restoreState = async (stateId) => {
+  const state = loadState(stateId);
+  
+  for (const file of state.files) {
+    fs.writeFileSync(file.path, file.content, 'utf8');
+  }
+  
+  console.log(`✅ Restored ${state.files.length} files to state ${stateId}`);
+};
+```
+
+---
+
+## State Storage
+
+Location: `.agent/state/`
+
+```
+.agent/state/
+├── current.json          # Current state ID
+├── states/
+│   ├── state-001.json    # Saved state 1
+│   ├── state-002.json    # Saved state 2
+│   └── ...
+└── history.json          # State history log
+```
+
+### State Format
+
+```json
+{
+  "id": "state-001",
+  "timestamp": "2026-01-29T10:00:00Z",
+  "description": "Before refactoring TodoItem",
+  "files": [
+    {
+      "path": "/path/to/file.tsx",
+      "content": "file contents...",
+      "hash": "sha256..."
+    }
+  ]
+}
+```
+
+---
+
+## Integration with GEMINI.md Safety Rules
+
+### NO DELETE RULE Compliance
+
+```
+state-rollback enforces:
+- Never delete without explicit user confirmation
+- Always save state before any destructive operation
+- Provide instant rollback capability
+```
+
+### WRITE-ONLY DEFAULT Compliance
+
+```
+For modifications:
+1. Save current state
+2. Write to new version (.v2, .new)
+3. Ask user approval
+4. If approved: rename new → original
+5. If rejected: delete new version
+```
+
+---
+
+## Scripts
+
+| Script | Purpose |
+|--------|---------|
+| `state_manager.js` | Save, restore, list states |
+
+---
+
+## Usage Examples
+
+### Before Risky Operation
+
+```javascript
+// Agent about to refactor 5 files
+const stateId = await saveState([
+  'components/TodoItem.tsx',
+  'components/TodoList.tsx',
+  'lib/store.ts',
+  'lib/types.ts',
+  'app/page.tsx'
+]);
+
+console.log(`💾 State saved: ${stateId}`);
+// Proceed with refactoring...
+```
+
+### On Failure
+
+```javascript
+// TypeScript check fails after modification
+if (hasTypeErrors) {
+  await restoreState(stateId);
+  console.log('⏪ Rolled back to previous state');
+  // Notify user about the issue
+}
+```
+
+### Manual Rollback
+
+```
+User: "Rollback the last change"
+
+Agent:
+1. Load latest state from history
+2. Restore all files in state
+3. Confirm: "⏪ Restored 5 files to state-003"
+```
+
+---
+
+## Success Metrics
+
+| Metric | Target |
+|--------|--------|
+| State save time | <1s for 10 files |
+| Restore accuracy | 100% |
+| State retention | 10 most recent |
+| Storage overhead | <10MB |
+
+---
+
+## Commands
+
+```bash
+# Save current state
+node state_manager.js save --files "file1.tsx,file2.tsx" --desc "Before refactor"
+
+# List saved states  
+node state_manager.js list
+
+# Restore specific state
+node state_manager.js restore --id state-001
+
+# Restore latest state
+node state_manager.js restore --latest
+
+# Clean old states (keep last N)
+node state_manager.js clean --keep 10
+```

package/.agent/skills/state-rollback/scripts/state_manager.js

@@ -0,0 +1,282 @@
+#!/usr/bin/env node
+/**
+ * State Manager Script (ES Module)
+ * 
+ * Save and restore file states for safe code modifications.
+ * Part of the state-rollback skill.
+ * 
+ * Usage:
+ *   node state_manager.js save --files "file1,file2" [--desc "description"]
+ *   node state_manager.js restore --id state-001
+ *   node state_manager.js restore --latest
+ *   node state_manager.js list
+ *   node state_manager.js clean --keep 10
+ */
+
+import fs from 'fs';
+import path from 'path';
+import crypto from 'crypto';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// Colors
+const colors = {
+    reset: '\x1b[0m',
+    red: '\x1b[31m',
+    green: '\x1b[32m',
+    yellow: '\x1b[33m',
+    blue: '\x1b[34m',
+    cyan: '\x1b[36m',
+    gray: '\x1b[90m'
+};
+
+// Find project root
+function findProjectRoot() {
+    let current = process.cwd();
+    while (current !== path.dirname(current)) {
+        if (fs.existsSync(path.join(current, '.agent'))) {
+            return current;
+        }
+        current = path.dirname(current);
+    }
+    return process.cwd();
+}
+
+const projectRoot = findProjectRoot();
+const stateDir = path.join(projectRoot, '.agent', 'state');
+const statesDir = path.join(stateDir, 'states');
+const historyPath = path.join(stateDir, 'history.json');
+
+// Ensure directories exist
+function ensureDirs() {
+    if (!fs.existsSync(statesDir)) {
+        fs.mkdirSync(statesDir, { recursive: true });
+    }
+}
+
+// Generate state ID
+function generateId() {
+    const num = Date.now() % 100000;
+    return `state-${String(num).padStart(5, '0')}`;
+}
+
+// Calculate file hash
+function hashContent(content) {
+    return crypto.createHash('sha256').update(content).digest('hex').slice(0, 16);
+}
+
+// Load history
+function loadHistory() {
+    if (!fs.existsSync(historyPath)) {
+        return [];
+    }
+    return JSON.parse(fs.readFileSync(historyPath, 'utf8'));
+}
+
+// Save history
+function saveHistory(history) {
+    fs.writeFileSync(historyPath, JSON.stringify(history, null, 2));
+}
+
+// Save state
+function saveState(files, description = '') {
+    ensureDirs();
+
+    const state = {
+        id: generateId(),
+        timestamp: new Date().toISOString(),
+        description,
+        files: []
+    };
+
+    for (const filePath of files) {
+        const absPath = path.resolve(projectRoot, filePath);
+        if (!fs.existsSync(absPath)) {
+            console.log(`${colors.yellow}⚠️  File not found: ${filePath}${colors.reset}`);
+            continue;
+        }
+
+        const content = fs.readFileSync(absPath, 'utf8');
+        state.files.push({
+            path: absPath,
+            relativePath: path.relative(projectRoot, absPath),
+            content,
+            hash: hashContent(content)
+        });
+    }
+
+    if (state.files.length === 0) {
+        console.log(`${colors.red}❌ No valid files to save${colors.reset}`);
+        return null;
+    }
+
+    // Save state file
+    const statePath = path.join(statesDir, `${state.id}.json`);
+    fs.writeFileSync(statePath, JSON.stringify(state, null, 2));
+
+    // Update history
+    const history = loadHistory();
+    history.push({
+        id: state.id,
+        timestamp: state.timestamp,
+        description,
+        fileCount: state.files.length
+    });
+    saveHistory(history);
+
+    console.log(`${colors.green}💾 State saved: ${state.id}${colors.reset}`);
+    console.log(`${colors.gray}   Files: ${state.files.length}${colors.reset}`);
+    console.log(`${colors.gray}   Description: ${description || '(none)'}${colors.reset}`);
+
+    return state.id;
+}
+
+// Restore state
+function restoreState(stateId) {
+    const statePath = path.join(statesDir, `${stateId}.json`);
+
+    if (!fs.existsSync(statePath)) {
+        console.log(`${colors.red}❌ State not found: ${stateId}${colors.reset}`);
+        return false;
+    }
+
+    const state = JSON.parse(fs.readFileSync(statePath, 'utf8'));
+
+    console.log(`${colors.blue}⏪ Restoring state: ${stateId}${colors.reset}`);
+
+    for (const file of state.files) {
+        const dir = path.dirname(file.path);
+        if (!fs.existsSync(dir)) {
+            fs.mkdirSync(dir, { recursive: true });
+        }
+
+        fs.writeFileSync(file.path, file.content, 'utf8');
+        console.log(`${colors.green}   ✓${colors.reset} ${file.relativePath}`);
+    }
+
+    console.log(`${colors.green}✅ Restored ${state.files.length} files${colors.reset}`);
+    return true;
+}
+
+// Restore latest state
+function restoreLatest() {
+    const history = loadHistory();
+    if (history.length === 0) {
+        console.log(`${colors.yellow}No saved states found${colors.reset}`);
+        return false;
+    }
+
+    const latest = history[history.length - 1];
+    return restoreState(latest.id);
+}
+
+// List states
+function listStates() {
+    const history = loadHistory();
+
+    console.log(`${colors.cyan}╔════════════════════════════════════════╗${colors.reset}`);
+    console.log(`${colors.cyan}║${colors.reset}  💾 Saved States                        ${colors.cyan}║${colors.reset}`);
+    console.log(`${colors.cyan}╚════════════════════════════════════════╝${colors.reset}`);
+    console.log(`${colors.gray}Total: ${history.length} states${colors.reset}\n`);
+
+    if (history.length === 0) {
+        console.log(`${colors.yellow}No saved states.${colors.reset}`);
+        return;
+    }
+
+    for (const state of history.slice(-10).reverse()) {
+        console.log(`${colors.bold}${state.id}${colors.reset} [${state.fileCount} files]`);
+        console.log(`  ${colors.gray}${state.timestamp}${colors.reset}`);
+        if (state.description) {
+            console.log(`  ${colors.gray}${state.description}${colors.reset}`);
+        }
+        console.log('');
+    }
+}
+
+// Clean old states
+function cleanStates(keep = 10) {
+    const history = loadHistory();
+
+    if (history.length <= keep) {
+        console.log(`${colors.yellow}Nothing to clean (${history.length} states, keeping ${keep})${colors.reset}`);
+        return;
+    }
+
+    const toRemove = history.slice(0, -keep);
+    const toKeep = history.slice(-keep);
+
+    for (const state of toRemove) {
+        const statePath = path.join(statesDir, `${state.id}.json`);
+        if (fs.existsSync(statePath)) {
+            fs.unlinkSync(statePath);
+        }
+    }
+
+    saveHistory(toKeep);
+
+    console.log(`${colors.green}🧹 Cleaned ${toRemove.length} old states${colors.reset}`);
+    console.log(`${colors.gray}   Keeping ${toKeep.length} most recent${colors.reset}`);
+}
+
+// Parse arguments
+const args = process.argv.slice(2);
+const command = args[0];
+
+if (command === 'save') {
+    const filesIdx = args.findIndex(a => a === '--files' || a === '-f');
+    const descIdx = args.findIndex(a => a === '--desc' || a === '-d');
+
+    const filesArg = filesIdx >= 0 ? args[filesIdx + 1] : null;
+    const desc = descIdx >= 0 ? args[descIdx + 1] : '';
+
+    if (!filesArg) {
+        console.log(`${colors.red}Error: --files is required${colors.reset}`);
+        process.exit(1);
+    }
+
+    const files = filesArg.split(',').map(f => f.trim());
+    saveState(files, desc);
+
+} else if (command === 'restore') {
+    if (args.includes('--latest')) {
+        restoreLatest();
+    } else {
+        const idIdx = args.findIndex(a => a === '--id');
+        const id = idIdx >= 0 ? args[idIdx + 1] : null;
+
+        if (!id) {
+            console.log(`${colors.red}Error: --id or --latest is required${colors.reset}`);
+            process.exit(1);
+        }
+
+        restoreState(id);
+    }
+
+} else if (command === 'list') {
+    listStates();
+
+} else if (command === 'clean') {
+    const keepIdx = args.findIndex(a => a === '--keep');
+    const keep = keepIdx >= 0 ? parseInt(args[keepIdx + 1]) : 10;
+    cleanStates(keep);
+
+} else {
+    console.log(`${colors.cyan}state-rollback - State Manager${colors.reset}
+
+${colors.bold}Usage:${colors.reset}
+  node state_manager.js save --files "file1,file2" [--desc "description"]
+  node state_manager.js restore --id state-001
+  node state_manager.js restore --latest
+  node state_manager.js list
+  node state_manager.js clean --keep 10
+
+${colors.bold}Commands:${colors.reset}
+  save      Save current state of files
+  restore   Restore files to saved state
+  list      List saved states
+  clean     Remove old states
+`);
+}