kastell-scaffold

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 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