kastelldev/kastell/kastell-scaffold

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.

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:

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