Kastell Research
kastell-research
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.
SKILL.md
Full skill instructions
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:
- Find the command file (
src/commands/<name>.ts) - Follow the core import (
src/core/<name>.ts) - Check adapter/provider calls
- Check utils (ssh, config)
Feature mapping:
- Grep for the function name
- Follow import chain
- Map all callsites
- Check test coverage in
__tests__/
Architecture question:
- Read the Architecture Map above
- Read
kastell-plugin/skills/kastell-ops/SKILL.mdfor full detail (adapter contract, provider registry, layer rules) - 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