kastell 2.1.0 → 2.2.1

package/kastell-plugin/skills/kastell-ops/references/pitfalls.md

@@ -0,0 +1,136 @@
+# Kastell Pitfalls
+
+Known traps, symptoms, and fixes. Severity: HIGH (blocks correct behavior), MEDIUM (causes test/maintenance pain), LOW (minor inconsistency).
+
+---
+
+## 1. Adapter Bypass (HIGH)
+
+**Symptom:** `if (server.platform === 'coolify') { port = 8000 } else { port = 3000 }` in `src/commands/`
+
+**Root cause:** Command accesses platform properties directly instead of using the adapter.
+
+**Fix:** Use `getAdapter(platform)` from `factory.ts` and read `adapter.port`, `adapter.defaultLogService`, `adapter.platformPorts`.
+
+```typescript
+// WRONG
+const port = server.platform === 'coolify' ? 8000 : 3000;
+
+// CORRECT
+import { getAdapter } from '../../src/adapters/factory.js';
+const adapter = getAdapter(server.platform);
+const port = adapter.port;
+```
+
+---
+
+## 2. Business Logic in Commands (HIGH)
+
+**Symptom:** Complex calculations, API calls, try/catch blocks, or SSH calls in `src/commands/*.ts`.
+
+**Root cause:** Logic was not extracted to `src/core/`.
+
+**Fix:** Extract all logic to a new `src/core/<name>.ts` function. Command only calls core and displays the result.
+
+---
+
+## 3. UI in Core (HIGH)
+
+**Symptom:** `chalk.green(...)`, `ora('...').start()`, or `console.log()` in `src/core/*.ts`.
+
+**Root cause:** Core function was handling display instead of returning data.
+
+**Fix:** Core functions return plain data objects. The command layer (or MCP handler) handles display using chalk/ora.
+
+---
+
+## 4. Direct Adapter Import (MEDIUM)
+
+**Symptom:** `import { CoolifyAdapter } from '../../src/adapters/coolify.js'` in a command or core file.
+
+**Root cause:** Bypasses the factory cache and breaks the abstraction boundary.
+
+**Fix:** Always use `getAdapter(platform)` from `src/adapters/factory.ts`.
+
+---
+
+## 5. Inline Adapter Mocks in Tests (MEDIUM)
+
+**Symptom:** `const adapter = { healthCheck: jest.fn(), port: 8000, ... }` scattered across test files.
+
+**Root cause:** Not using the centralized mock factory.
+
+**Fix:** Use `createMockAdapter()` from `tests/helpers/mockAdapter.ts`. When the `PlatformAdapter` interface gains new methods, only `mockAdapter.ts` needs updating.
+
+---
+
+## 6. SSH Batch Grouping (MEDIUM)
+
+**Symptom:** Audit or health commands call `sshExec` 4-6 times sequentially, each fetching partially overlapping data.
+
+**Root cause:** Each check independently fetches data instead of using shared batched results.
+
+**Fix:** Batch fast config commands together (single SSH call), batch slow probe commands together. Use head limits appropriate to the data volume (e.g., `head -50` for audit log checks).
+
+---
+
+## 7. Jest requireActual Crash (MEDIUM)
+
+**Symptom:** Tests crash on Node v24+ with an error related to `jest.requireActual`.
+
+**Root cause:** `jest.requireActual` behavior changed in Node v24.
+
+**Fix:** Use inline `jest.fn()` mocks instead of `jest.requireActual`. For module-level mocks, use `jest.mock()` with a factory function.
+
+---
+
+## 8. Module-Level Side Effects (MEDIUM)
+
+**Symptom:** Test imports a module that registers listeners or modifies globals at load time, causing unexpected behavior when other tests run.
+
+**Root cause:** Module has top-level side effects (e.g., `process.on('SIGINT', ...)` at module scope).
+
+**Fix:** Mock the module in ALL test files that import it, not just the direct test file. Side effects occur at import time.
+
+---
+
+## 9. Hardcoded Port Numbers (LOW)
+
+**Symptom:** `8000` or `3000` literals appear in `src/commands/` or `src/core/` files.
+
+**Root cause:** Port copied from constants instead of read from adapter.
+
+**Fix:** Use `adapter.port` for platform HTTP port, `adapter.platformPorts` for firewall protection list.
+
+---
+
+## 10. PROVIDER_REGISTRY Mismatch (LOW)
+
+**Symptom:** New provider works via direct code path but fails CLI validation, completion, or `--provider` flag parsing.
+
+**Root cause:** Provider added to `src/providers/` but not added to `PROVIDER_REGISTRY` in `src/constants.ts`.
+
+**Fix:** Always add to `PROVIDER_REGISTRY` first — it is the single source of truth for provider enumeration, validation, and display.
+
+---
+
+## 11. SSH Timeout Too Short (LOW)
+
+**Symptom:** Long-running commands (lock, audit, update) fail silently or with cryptic timeout errors.
+
+**Root cause:** Default SSH timeout (30s) is insufficient for operations like platform update (~3 minutes).
+
+**Fix:** Use 180s timeout for slow operations:
+```typescript
+await sshExec(ip, command, { timeout: 180_000 });
+```
+
+---
+
+## 12. describe.each + clearAllMocks (LOW)
+
+**Symptom:** Tests pass individually but fail when the full suite runs. Mock call counts are wrong in later tests.
+
+**Root cause:** `jest.clearAllMocks()` clears call history but does not reset mock implementations. `describe.each` reuses the same mock instance across parameterized runs.
+
+**Fix:** Use `jest.resetAllMocks()` in `beforeEach` when using `describe.each`. This resets both call history and implementations.

package/kastell-plugin/skills/kastell-ops/scripts/check_coverage.sh

@@ -0,0 +1,101 @@
+#!/usr/bin/env bash
+# check_coverage.sh — Compare audit check count vs test count.
+# Usage: bash check_coverage.sh [project-root]
+#
+# Counts audit checks defined in src/core/audit/checks/ and matching tests.
+# Requires: node
+
+set -euo pipefail
+
+PROJECT_ROOT="${1:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"
+
+node -e "
+const fs = require('fs');
+const path = require('path');
+
+const root = process.argv[1];
+const checksDir = path.join(root, 'src', 'core', 'audit', 'checks');
+
+if (!fs.existsSync(checksDir)) {
+  console.error('Error: ' + checksDir + ' not found');
+  process.exit(1);
+}
+
+// Read all .ts files in checks dir (excluding index.ts)
+const checkFiles = fs.readdirSync(checksDir)
+  .filter(f => f.endsWith('.ts') && f !== 'index.ts');
+
+let totalChecks = 0;
+const uniqueIds = new Set();
+const perFile = [];
+
+for (const file of checkFiles) {
+  const content = fs.readFileSync(path.join(checksDir, file), 'utf8');
+  const ids = [...content.matchAll(/id:\s*['\"]([^'\"]+)['\"]/g)].map(m => m[1]);
+  totalChecks += ids.length;
+  ids.forEach(id => uniqueIds.add(id));
+  perFile.push({ name: file.replace('.ts', ''), checks: ids.length });
+}
+
+// Count categories from index.ts
+let categories = 0;
+const indexPath = path.join(checksDir, 'index.ts');
+if (fs.existsSync(indexPath)) {
+  const indexContent = fs.readFileSync(indexPath, 'utf8');
+  categories = (indexContent.match(/sectionName/g) || []).length;
+}
+
+// Find audit test files recursively
+function findTests(dir) {
+  let count = 0;
+  if (!fs.existsSync(dir)) return 0;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) count += findTests(full);
+    else if (entry.name.endsWith('.test.ts') && entry.name.includes('audit') ||
+             full.includes('audit') && entry.name.endsWith('.test.ts')) {
+      count++;
+    }
+  }
+  return count;
+}
+const testCount = findTests(path.join(root, 'src'));
+
+// Pre-index all test file contents once (avoids N+1 file reads)
+const testIndex = new Set();
+function indexTests(dir) {
+  try {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) indexTests(full);
+      else if (entry.name.endsWith('.test.ts')) {
+        const content = fs.readFileSync(full, 'utf8');
+        // Extract referenced module names from imports and test descriptions
+        for (const match of content.matchAll(/['\"]([^'\"]*audit[^'\"]*)['\"]|from\s+['\"]([^'\"]+)['\"]/g)) {
+          const ref = match[1] || match[2] || '';
+          ref.split('/').forEach(part => testIndex.add(part.replace('.js', '').replace('.ts', '')));
+        }
+      }
+    }
+  } catch {}
+}
+indexTests(path.join(root, 'src'));
+function hasTestFor(name) { return testIndex.has(name); }
+
+console.log('=== Audit Check Coverage ===');
+console.log('Project: ' + root);
+console.log('');
+console.log('Check source files: ' + checkFiles.length);
+console.log('Categories:         ' + categories);
+console.log('Checks defined:     ' + totalChecks);
+console.log('Unique check IDs:   ' + uniqueIds.size);
+console.log('Audit test files:   ' + testCount);
+console.log('');
+console.log('Per-file breakdown:');
+
+perFile.sort((a, b) => a.name.localeCompare(b.name));
+for (const f of perFile) {
+  const tested = hasTestFor(f.name) ? '✓' : '✗';
+  console.log('  ' + tested + ' ' + f.name.padEnd(20) + ' ' + String(f.checks).padStart(3) + ' checks');
+}
+" "$PROJECT_ROOT"

package/kastell-plugin/skills/kastell-ops/scripts/fleet_report.sh

@@ -0,0 +1,73 @@
+#!/usr/bin/env bash
+# fleet_report.sh — Generate a fleet-wide server score table.
+# Usage: kastell fleet --json | bash fleet_report.sh
+#    OR: bash fleet_report.sh < fleet-output.json
+#    OR: bash fleet_report.sh fleet-output.json
+#
+# Requires: node
+
+set -euo pipefail
+
+if [[ -n "${1:-}" && -f "$1" ]]; then
+  INPUT=$(cat "$1")
+elif [[ ! -t 0 ]]; then
+  INPUT=$(cat)
+else
+  echo "Usage: kastell fleet --json | bash fleet_report.sh" >&2
+  exit 1
+fi
+
+node -e "
+const data = JSON.parse(process.argv[1]);
+const servers = data.servers || data.fleet || data || [];
+
+if (!Array.isArray(servers) || servers.length === 0) {
+  console.log('No servers found in fleet data.');
+  process.exit(0);
+}
+
+// Header
+const cols = { name: 20, ip: 16, provider: 12, mode: 8, score: 6, health: 10 };
+const pad = (s, n) => String(s || '-').slice(0, n).padEnd(n);
+const sep = '-'.repeat(Object.values(cols).reduce((a, b) => a + b + 3, 0));
+
+console.log('=== Kastell Fleet Report ===');
+console.log('Servers: ' + servers.length);
+console.log('');
+console.log(
+  pad('Name', cols.name) + ' | ' +
+  pad('IP', cols.ip) + ' | ' +
+  pad('Provider', cols.provider) + ' | ' +
+  pad('Mode', cols.mode) + ' | ' +
+  pad('Score', cols.score) + ' | ' +
+  pad('Health', cols.health)
+);
+console.log(sep);
+
+// Sort by score (lowest first = needs attention)
+const sorted = [...servers].sort((a, b) => (a.score ?? 0) - (b.score ?? 0));
+
+for (const s of sorted) {
+  const score = s.score ?? s.auditScore ?? '-';
+  const health = s.health ?? s.status ?? '-';
+  const icon = health === 'ONLINE' ? '●' : health === 'DEGRADED' ? '◐' : '○';
+  console.log(
+    pad(s.name, cols.name) + ' | ' +
+    pad(s.ip, cols.ip) + ' | ' +
+    pad(s.provider, cols.provider) + ' | ' +
+    pad(s.mode, cols.mode) + ' | ' +
+    pad(score, cols.score) + ' | ' +
+    icon + ' ' + pad(health, cols.health - 2)
+  );
+}
+
+// Summary
+const scores = sorted.map(s => s.score ?? s.auditScore).filter(s => typeof s === 'number');
+if (scores.length > 0) {
+  const avg = Math.round(scores.reduce((a, b) => a + b, 0) / scores.length);
+  const min = Math.min(...scores);
+  const max = Math.max(...scores);
+  console.log('');
+  console.log('Avg: ' + avg + ' | Min: ' + min + ' | Max: ' + max);
+}
+" "$INPUT"

package/kastell-plugin/skills/kastell-ops/scripts/parse_audit.sh

@@ -0,0 +1,76 @@
+#!/usr/bin/env bash
+# parse_audit.sh — Parse kastell audit JSON into 5 security domain summaries.
+# Usage: kastell audit --server <name> --json | bash parse_audit.sh
+#    OR: bash parse_audit.sh < audit-output.json
+#    OR: bash parse_audit.sh audit-output.json
+#
+# Requires: node (uses inline JS for JSON parsing — no jq dependency)
+
+set -euo pipefail
+
+# Read JSON from file arg, stdin, or pipe
+if [[ -n "${1:-}" && -f "$1" ]]; then
+  INPUT=$(cat "$1")
+elif [[ ! -t 0 ]]; then
+  INPUT=$(cat)
+else
+  echo "Usage: kastell audit --server <name> --json | bash parse_audit.sh" >&2
+  echo "   OR: bash parse_audit.sh <audit-json-file>" >&2
+  exit 1
+fi
+
+node -e "
+const data = JSON.parse(process.argv[1]);
+const checks = data.checks || data.results || [];
+
+// 5 security domain mapping
+const DOMAINS = {
+  'Perimeter':       ['Network', 'Firewall', 'DNS Security'],
+  'Authentication':  ['SSH', 'Auth', 'Crypto', 'Accounts'],
+  'Runtime':         ['Docker', 'Services', 'Boot', 'Scheduling'],
+  'Internals':       ['Filesystem', 'Logging', 'Kernel', 'Memory'],
+  'Compliance':      ['Updates', 'File Integrity', 'Malware', 'MAC', 'Secrets',
+                      'Cloud Metadata', 'Supply Chain', 'Backup Hygiene',
+                      'Resource Limits', 'Incident Readiness', 'Banners', 'Time',
+                      'TLS', 'HTTP Security Headers'],
+};
+
+// Map categories to domains
+const catToDomain = {};
+for (const [domain, cats] of Object.entries(DOMAINS)) {
+  for (const cat of cats) catToDomain[cat.toLowerCase()] = domain;
+}
+
+// Bucket checks
+const buckets = {};
+for (const d of Object.keys(DOMAINS)) buckets[d] = { passed: 0, failed: 0, critical: [] };
+
+for (const c of checks) {
+  const cat = (c.category || '').toLowerCase();
+  let domain = 'Compliance'; // default
+  for (const [key, val] of Object.entries(catToDomain)) {
+    if (cat.includes(key)) { domain = val; break; }
+  }
+  if (c.passed) buckets[domain].passed++;
+  else {
+    buckets[domain].failed++;
+    if (c.severity === 'critical') buckets[domain].critical.push(c.id || c.name);
+  }
+}
+
+// Output
+const score = data.score ?? data.overallScore ?? 'N/A';
+console.log('=== Kastell Audit Domain Summary ===');
+console.log('Overall Score: ' + score + '/100');
+console.log('');
+
+for (const [domain, b] of Object.entries(buckets)) {
+  const total = b.passed + b.failed;
+  const pct = total > 0 ? Math.round(b.passed / total * 100) : 0;
+  const bar = '█'.repeat(Math.round(pct / 5)) + '░'.repeat(20 - Math.round(pct / 5));
+  console.log(domain + ': ' + b.passed + '/' + total + ' (' + pct + '%) ' + bar);
+  if (b.critical.length > 0) {
+    console.log('  Critical: ' + b.critical.slice(0, 3).join(', '));
+  }
+}
+" "$INPUT"

package/kastell-plugin/skills/kastell-research/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: kastell-research
+description: Read-only Kastell codebase exploration. Use when tracing a bug across files, mapping callsites before refactoring, or exploring unfamiliar subsystems. Runs in isolated context with Explore agent.
+context: fork
+agent: Explore
+allowed-tools: Read, Grep, Glob
+effort: medium
+memory: project
+---
+
+# Kastell Research
+
+## Purpose
+
+Explore the Kastell codebase using read-only tools (Read, Grep, Glob). Runs in a forked Explore agent with Kastell architecture knowledge inlined.
+
+## When to Use
+
+- **Bug investigation:** Trace a bug from CLI command through core logic to adapters/providers. Start at the command file, follow imports to core, check utils and adapters.
+- **Feature mapping:** Map all callsites of a function, trace the import chain, understand how subsystems connect before making changes.
+- **Architecture question:** Understand how audit categories work, how the adapter dispatch flows, or how lock hardening steps are structured.
+
+## Live Codebase
+
+**Commands:**
+!`node -e "import('fs').then(f=>console.log(f.readdirSync('src/commands').filter(x=>x.endsWith('.ts')).map(x=>x.replace('.ts','')).join(', '))).catch(()=>console.log('commands dir not found'))"`
+**Provider registry:**
+!`node -e "import('fs').then(f=>{const c=f.readFileSync('src/constants.ts','utf8');const m=c.match(/PROVIDER_REGISTRY[\s\S]{0,200}/);console.log(m?m[0].split('\n').slice(0,4).join('\n'):'not found')}).catch(()=>console.log('constants.ts not found'))"`
+
+## Architecture Map
+
+```
+src/
+  commands/     # 31 thin CLI wrappers (parse args + delegate only)
+  core/         # Business logic (ALL computation here)
+    audit/      # 30 audit categories, 457+ checks
+    lock/       # 24-step server hardening
+  providers/    # Cloud API: hetzner, digitalocean, vultr, linode
+  adapters/     # Platform abstraction: coolify, dokploy
+    factory.ts  # getAdapter(platform) — entry point
+  mcp/
+    server.ts   # 13 tool registrations
+    tools/      # Handler files
+  utils/        # ssh, config, cloudInit, modeGuard
+  types/        # ServerMode, ServerRecord, Platform
+  constants.ts  # PROVIDER_REGISTRY
+```
+
+## Layer Flow
+
+Commands (parse args) --> Core (business logic) --> Providers (cloud API) / Adapters (platform ops). MCP tools also delegate to Core.
+
+## Research Workflows
+
+**Bug investigation:**
+1. Find the command file (`src/commands/<name>.ts`)
+2. Follow the core import (`src/core/<name>.ts`)
+3. Check adapter/provider calls
+4. Check utils (ssh, config)
+
+**Feature mapping:**
+1. Grep for the function name
+2. Follow import chain
+3. Map all callsites
+4. Check test coverage in `__tests__/`
+
+**Architecture question:**
+1. Read the Architecture Map above
+2. Read `kastell-plugin/skills/kastell-ops/SKILL.md` for full detail (adapter contract, provider registry, layer rules)
+3. Trace specific files
+
+## Debug by Symptom
+
+Common failure patterns and where to look first:
+
+| Symptom | Start Here | Then Check |
+|---------|-----------|------------|
+| SSH auth failure | `src/utils/ssh.ts` → `sshExec()` | `assertValidIp()`, server config `~/.kastell/servers.json`, banner parsing |
+| Provider API error | `src/providers/<name>.ts` | `withProviderErrorHandling()` in `src/utils/retry.ts`, API token config |
+| Audit check false positive | `src/core/audit/checks/<category>.ts` | SSH command output parsing, regex pattern, `sshExec` mock in test |
+| Fix rejected (SAFE tier) | `src/core/fix.ts` → `resolveTier()` | `FORBIDDEN_PATTERNS`, shell redirect/pipe in fixCommand string |
+| MCP tool error | `src/mcp/tools/<name>.ts` | Handler → core delegation, Zod schema validation, `result.content` format |
+| Lock step failure | `src/core/lock.ts` | Step's SSH command, `sshExec` stderr, cloud-init completion |
+| Config not found | `src/utils/config.ts` | `~/.kastell/` dir existence, `servers.json` format, migration from `~/.quicklify/` |
+
+**Known pitfalls:** See `kastell-plugin/skills/kastell-ops/references/pitfalls.md`
+
+## ARGUMENTS
+
+$ARGUMENTS

package/kastell-plugin/skills/kastell-scaffold/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: kastell-scaffold
+description: Generate new Kastell components from templates. Creates boilerplate for CLI commands, audit checks, providers, and MCP tools following current architecture (commands thin, core fat, adapters dispatch).
+context: fork
+disable-model-invocation: true
+effort: medium
+allowed-tools: Read, Edit, Write, Bash, Glob, Grep
+argument-hint: "[check|command|provider|mcp-tool] [name]"
+---
+
+# Kastell Scaffold
+
+## Purpose
+
+Generate boilerplate files for new Kastell components. Each template follows the post-P63/P64 architecture: commands are thin wrappers, business logic lives in core/, providers handle cloud API, adapters abstract platform ops.
+
+## Usage
+
+```
+/kastell:scaffold command server-migrate     # creates command + core + test files
+/kastell:scaffold check filesystem-perms     # creates audit check + catalog update
+/kastell:scaffold provider ovhcloud          # creates provider + registry entry + test
+/kastell:scaffold mcp-tool server_migrate    # creates MCP tool + registration + test
+```
+
+`$ARGUMENTS[0]` is the component type. `$ARGUMENTS[1]` is the component name.
+
+## Architecture Rules
+
+These rules apply in every generated file. The forked subagent does not automatically have kastell-ops context — enforce these rules explicitly.
+
+| Layer    | Path              | Rule                                                         |
+|----------|-------------------|--------------------------------------------------------------|
+| Commands | src/commands/     | Parse args + delegate. ZERO business logic.                  |
+| Core     | src/core/         | ALL business logic. No chalk/ora/UI imports.                 |
+| Providers| src/providers/    | Cloud API per provider. Extends BaseProvider.                |
+| Adapters | src/adapters/     | Platform ops via PlatformAdapter. Access via getAdapter().   |
+| MCP      | src/mcp/tools/    | Zod schema + handler. Delegates to core.                     |
+
+**Critical:** Never import CoolifyAdapter or DokployAdapter directly. Always use `getAdapter(platform)` from `src/adapters/factory.ts`.
+
+**ESM:** `"type": "module"` — use `import`, not `require`. All imports use `.js` extension.
+
+## Existing Components
+
+**Commands:**
+!`node -e "import('fs').then(f=>console.log(f.readdirSync('src/commands').filter(x=>x.endsWith('.ts')).map(x=>x.replace('.ts','')).join(', '))).catch(()=>console.log('commands dir not found'))"`
+**Providers:**
+!`node -e "import('fs').then(f=>console.log(f.readdirSync('src/providers').filter(x=>x.endsWith('.ts')&&x!=='base.ts').map(x=>x.replace('.ts','')).join(', '))).catch(()=>console.log('providers dir not found'))"`
+**MCP tools:**
+!`node -e "import('fs').then(f=>console.log(f.readdirSync('src/mcp/tools').filter(x=>x.endsWith('.ts')).map(x=>x.replace('.ts','')).join(', '))).catch(()=>console.log('mcp/tools dir not found'))"`
+**Audit categories:**
+!`node -e "import('fs').then(f=>console.log(f.readdirSync('src/core/audit',{withFileTypes:true}).filter(d=>d.isDirectory()).map(d=>d.name).join(', '))).catch(()=>console.log('audit dir not found'))"`
+
+## Script (Deterministic)
+
+Run the scaffold script to generate boilerplate files:
+
+```bash
+bash scripts/scaffold.sh $ARGUMENTS[0] $ARGUMENTS[1]
+```
+
+The script reads `.tpl` templates from `templates/`, replaces `__NAME__`/`__NAME_PASCAL__`/`__NAME_CAMEL__`/`__NAME_UPPER__` placeholders, and creates files in the project. Add `--dry-run` to preview without writing.
+
+**Files generated per type:**
+- `command` → 3 files: `src/commands/`, `src/core/`, `src/__tests__/core/`
+- `check` → 2 files: `src/core/audit/checks/`, `src/__tests__/core/audit/checks/`
+- `provider` → 2 files: `src/providers/`, `src/__tests__/providers/`
+- `mcp-tool` → 2 files: `src/mcp/tools/`, `src/__tests__/mcp/`
+
+## Template Reference (Context for LLM)
+
+After running the script, read the matching reference for registration details:
+
+| Type       | Reference File                                 |
+|------------|------------------------------------------------|
+| `command`  | references/template-command.md                 |
+| `check`    | references/template-audit-check.md             |
+| `provider` | references/template-provider.md                |
+| `mcp-tool` | references/template-mcp-tool.md                |
+
+## After Generation
+
+Perform these steps after creating the boilerplate files:
+
+- [ ] Write tests first (TDD preferred — test core, not command)
+- [ ] Register the component:
+  - Commands: add import in `src/index.ts`
+  - MCP tools: `registerTool()` in `src/mcp/server.ts`
+  - Providers: add to `PROVIDER_REGISTRY` in `src/constants.ts`
+  - Audit checks: add entry to `src/core/audit/catalog.ts`
+- [ ] Run `npm run build && npm test && npm run lint`
+- [ ] Update README.md
+
+## Skill/Agent Oluşturma Kuralları (Yeni skill/agent scaffold ediliyorsa)
+
+Yeni skill veya agent oluşturulurken aşağıdaki koşullar ZORUNLU:
+- [ ] **Ersin kriteri:** scripts/ klasörü oluştur — deterministik iş LLM'e bırakılmayacak
+- [ ] **Progressive disclosure:** SKILL.md < 500 satır, detaylar references/ klasöründe
+- [ ] **Frontmatter:** `effort` + `allowed-tools` ekle (minimum zorunlu)
+- [ ] **Yan etki varsa:** `disable-model-invocation: true` ekle
+- [ ] **Agent ise:** `maxTurns` belirle, `memory` scope tanımla
+- [ ] **Script dili:** Shell (sh/bash) tercih et — Node.js ekosistemiyle uyumlu
+- [ ] **Evaluation:** Gerçek task'ta test et, struggle noktalarını gözlemle