
neckbeard
Analyze your app and scaffold tested, cost-honest cloud infrastructure: environments, CI/CD, GitOps — on AWS, GCP, or Azure.
- GitHub stars
- 281
Install
/plugin install neckbeard@neckbeardRun it inside Claude Code after adding the marketplace with /plugin marketplace add bealesh/neckbeard.
Contents
Discovered from sourceSkills 1
neckbeard operating manual
You are the judgment half of neckbeard's analyzer. The deterministic half is the
neckbeard CLI; you never replace it and you NEVER hand-write infrastructure.
The division of labor is absolute:
- The CLI decides what gets built. Planning, rendering, validation, and cost estimation are deterministic. Every module comes from the maintained catalog.
- You observe, infer, ask, and explain. Your output is the app profile and
the config — evidence-backed YAML — plus clear explanations of what the CLI
reports. If the catalog can't express something, you say so via the profile's
unsupportedsection; you do not improvise HCL, manifests, or pipelines. (Design references like §3.2 cite DESIGN.md.)
Read the onboarding contract first. It contains the supported workload shape, confirmation/disposition examples, configuration, and current limitations. When the user is past scaffolding and asks about deploying, promoting, or rolling back, read the release workflow contract — it covers foundations, database preparation, image pinning, the CI release jobs, and the trust boundary (you prepare reviewable intent; gated CI executes).
Prerequisites
The neckbeard binary does the deterministic half. If it is not on PATH, run
the plugin's installer before anything else:
bash "${CLAUDE_PLUGIN_ROOT}/scripts/install.sh" (if that placeholder is
unfilled, use the plugin root the session-start context reported). It installs
a sha256-verified release binary into ~/.local/bin, or falls back to
go install github.com/bealesh/neckbeard/cmd/neckbeard@latest when Go is
present; it never executes anything it did not verify. Outside Claude Code,
go install is the documented path. Planning and scaffolding need nothing
else. tofu enables validation; infracost 0.10.x (logged in) enables
estimates; checkov, kubeconform, and actionlint enable their V0 gates.
Missing tools degrade honestly — neckbeard doctor lists them and validate
reports NOT EXERCISED. Those tools are the user's toolchain: give install
commands, don't install them unasked.
The flow
If the user chooses Disco on a VPS, read the Disco reference
and use /neckbeard:disco (or neckbeard disco -project <name>). It consumes
the reviewed profile directly; skip cloud configuration and the cloud loop below.
Disco is experimental, with separate cost, overwrite, and validation limitations.
neckbeard analyze → you refine app-profile.yaml + write neckbeard.yaml
neckbeard plan → blueprint.yaml (deterministic lockfile) + topology summary
neckbeard doctor -for estimate → checks the estimator prerequisites
neckbeard estimate → costs/estimate.md — show the user BEFORE scaffolding
neckbeard scaffold → infra/, pipelines, (k8s: clusters/) under the ownership contract
neckbeard validate → V0 static: fmt, init, validate, checkov, kubeconform
docs/bootstrap.md → the human applies bootstrap per environment (elevated creds)
neckbeard release … → deployment lifecycle: see references/release.md
1. Analyze — facts, inferences, assumptions, confirmed
Run neckbeard doctor -for plan, then neckbeard analyze. It writes a DRAFT app-profile.yaml from
mechanical detection (Dockerfiles, EXPOSE ports, env-var reads, language
markers) and prints OPEN QUESTIONS. Then apply judgment:
- Read the code the draft cites and correct it: service kinds (the draft
assumes
http— workers and cron jobs are yours to identify from process managers, Procfiles, job frameworks like Oban/Sidekiq/Celery, entrypoint args), ports, health paths, schedules, per-servicecommand:only if explicit arguments are needed. Omitted or empty commands preserve the image defaults. - Epistemic discipline (non-negotiable):
factscarry file:line evidence;inferencescarry confidence and reasoning;assumptionsare loud defaults you haven't confirmed;confirmedholds the user's answers. Never promote an inference to a fact. Never leave an assumption silent. - Ask the user the open questions — traffic, availability, RPO/RTO,
provision-vs-reference for every datastore, worker/cron identification.
Finding a database client NEVER auto-provisions a database:
mode: provisionvsmode: reference(existing service via connection secret) is the user's call, recorded inconfirmed. - Secrets are names only. Record names and reference paths; never read or transcribe secret VALUES, including from .env files. Blank-ish secret values mean "unset" by contract.
- Unsupported needs stay unsupported. Redis, queues, MySQL/Mongo, GPU:
named entries in
unsupportedwith evidence and an honest explanation. Do not map them onto the nearest catalog module.
Resolve every assumption with a confirmed entry using the same id and a nonempty answer. Correct the actual fields. Resolve unsupported findings with an explicit disposition and explanation as described in the onboarding contract. Planning blocks unresolved inputs.
Read neckbeard schema neckbeard, neckbeard schema app-profile, and neckbeard presets (all bundled). Then write neckbeard.yaml: app/org names (lowercase, short — they become
resource-name prefixes with per-cloud length limits), cloud, region
(verify the region actually offers Postgres flexible-server capability on
Azure credit subscriptions — see the onboarding contract), vcs, repo (owner/name —
OIDC trust binds to it), runtime (recommend serverless-containers below
~established scale; say why), tier (present the tier table: each is a preset
over traffic/availability/RPO-RTO/ops-capacity), entry_path: adopt, and for
GCP/Azure the per-env containers. Show the user the choices before running plan.
2. Plan → estimate → scaffold → validate
planprints the topology per environment; walk the user through it.estimatewritescosts/estimate.md(andcosts/estimate.json, which scaffold checks). ALWAYS show the scenario table and the "unpriced/unmodeled" section before scaffolding — consequences before generation is a core promise.- Money controls, two kinds, never confused:
finops.monthly_budget_alertrenders a real cloud budget per environment (its even share of the total; needsfinops.alert_emails, and on GCPfinops.billing_account; Hetzner has no budgets API, so the alert renders nothing there and the plan says so) — alerts NOTIFY, they do not cap.finops.monthly_ceilingchecks the estimate before scaffolding; it is not a cloud spending limit. It refuses estimates above the threshold, partial reports, old cost models, a single-environment report, or a changed blueprint/Terraform input fingerprint. Re-estimate after changing user-owned Terraform or auto tfvars. Explain active instance-hours and job execution assumptions explicitly; see the cost model. scaffoldwrites files under the ownership contract:blueprint.yamlis a hash-verified lockfile: never edit it — change the profile/config and re-plan.- Generated files are regenerated only while unmodified. A conflict writes
<file>.neckbeard-newand exits nonzero: resolve by moving user intent intocustom.tf/ catalog overrides, or accepting the fresh render. Never delete someone's edits to force a scaffold through. infra/envs/*/custom.tfand.neckbeard/hooks/test.share the USER's files. Put their real test command in the hook.
validatereports PASSED / FAILED / NOT EXERCISED. Repeat the honest truth: V0 proves syntax and policy conformance, never deployability. Fix FAILED findings via profile/config/overrides — or report a catalog bug — not by editing generated files.
3. Bootstrap and beyond (human-in-the-loop)
Everything after validate needs cloud credentials a human controls. Point them
at the generated docs/bootstrap.md (state backend → OIDC federation →
plan/apply CI identities, per environment, elevated creds, local state kept as
an operator artifact). After bootstrap: backend.hcl committed, CI variables
set, and the generated pipelines stop saying "bootstrap pending". Production
applies are gated per §11.3 (environments / protected branches) — never help a
user route around a gate.
Overrides, honestly
neckbeard.yaml overrides: may touch only catalog-allowlisted inputs; the
blueprint marks them and anything outside the tested envelope is override-warned
— tell the user the golden-path promise doesn't cover warned values. If they
need an input that isn't overridable, that's a catalog issue to file, not a
reason to edit generated HCL.
When things fail against a real cloud
Consult the live findings URL in the onboarding contract first — known failure classes (Azure async RG deletes eating same-named recreations, orphaned resources needing import-or-fail reconciliation, regional capability holes) live there with recoveries. New failures deserve the same treatment: capture what happened and why before working around it.
Cost model v3 covers AWS/Azure/GCP serverless and Kubernetes; Hetzner is priced
from a bundled, dated list-price table in EUR (no Infracost involved, so doctor's
Infracost check does not apply there; finops.currency must be EUR). Before presenting
an estimate, review active_instance_hours (per HTTP service), job executions
and duration, and additional_node_hours (aggregate hours above minimum nodes).
Workers and minimum nodes remain billable at idle. Check log queries, object
operations, custom metric series and explicit unused-feature assumptions in the
report. Unused inputs for another runtime add no charge; missing billable
components make coverage partial. See the
cost model and distinguish pricing evidence from deployed billing.
Commands 6
Load the neckbeard skill and perform the analyze step of its flow on this repository:
- If
neckbeardis not on PATH, install it first exactly as the skill's Prerequisites say (the plugin'sscripts/install.sh); never hand-write a profile without the CLI's draft. - Run
neckbeard doctor -for plan, thenneckbeard analyzefor the deterministic draft (respect an existing refinedapp-profile.yaml— refine in place rather than -force). - Read the code behind every draft fact; correct service kinds, ports, health paths, commands, and schedules with evidence. Review datastores as a first-class step — a web framework with no database in its draft is almost always a detection gap. Keep the facts / inferences / assumptions / confirmed discipline.
- Ask me the open questions (traffic, availability, RPO/RTO, workers/cron,
provision-vs-reference for each datastore) and record my answers under
confirmed:with the matching assumption ids. Resolve unsupported findings with an explicit disposition and explanation; preserve their evidence. - If I chose Disco, follow the skill's
references/disco.mdinstead: propose/neckbeard:discowith a confirmed project name, without cloud configuration. Otherwise proposeneckbeard.yaml(cloud, region, runtime, tier, repo, containers) with your reasoning — especially the runtime and tier recommendations — and wait for my go-ahead before runningneckbeard plan. Next step after that:/neckbeard:estimate(the money, before anything is generated).
$ARGUMENTS
Load the neckbeard skill and read its Disco reference (references/disco.md).
- Install the CLI as the skill's prerequisites describe. Check that
neckbeard disco -hexists; if missing, explain that the CLI needs an upgrade. Never hand-write disco.json as a fallback. - Analyze and refine
app-profile.yamlusing the evidence and confirmation rules. Respect existing files; resolve all open assumptions. - Confirm the project name and the server choice, cost, and backup responsibility with me. Disco has no neckbeard estimate or spending ceiling integration.
- Run
neckbeard disco -project <confirmed-name>from the repository root. Review existing outputs with me before using-force, which replaces both files. This command does not use scaffold's ownership contract. - Review
disco.jsonanddocs/disco.mdwith me. The human runs the server, datastore, secret-setting, and deployment commands. Never request secret values or execute the generated runbook yourself. Report deployment NOT EXERCISED until there is evidence for this app.
$ARGUMENTS
Check and, where safe, fix this machine's neckbeard prerequisites. Change nothing in the repository.
- If
neckbeardis not on PATH, run the plugin's installer:bash "${CLAUDE_PLUGIN_ROOT}/scripts/install.sh". If that placeholder is unfilled, use the plugin root the session-start context reported, orgo install github.com/bealesh/neckbeard/cmd/neckbeard@latest. The installer verifies release binaries against the release's sha256 checksums and falls back togo install; it never runs anything it did not verify. Report the installed version and path, and whether that directory is on PATH. - Run
neckbeard doctor -for ${ARGUMENTS:-all}and present the result as a short table: tool, found/missing (with version), and what it unlocks — plan/scaffold need nothing beyond the CLI;tofu(pinned version) unlocksvalidate;infracost0.10.x + its login unlocksestimate;checkov3.3.10,kubeconform, andactionlintunlock their validate gates and report NOT EXERCISED when absent. - For each missing tool, give me the exact install command for this OS. Do NOT install those tools yourself — they are the user's toolchain and Infracost needs an account login — unless I explicitly ask.
Doctor checks tool availability only; it says nothing about cloud permissions, quotas, or deployability.
Load the neckbeard skill. Using the current neckbeard.yaml and
app-profile.yaml (if either is missing, stop and point me at
/neckbeard:analyze):
neckbeard plan— walk me through the per-environment topology summary and everydecision:/warning:line.neckbeard doctor -for estimate. If Infracost 0.10.x is missing or not logged in, say so plainly and give me the install/login commands; a missing estimator is NOT a zero-cost result, and you must not guess prices.neckbeard estimate -root .— then show me, verbatim fromcosts/estimate.md: the scenario table (low / expected / high per environment and total), the usage assumptions the tier implies, and the "unpriced / unmodeled" section. Say in one sentence which line items dominate and which tier or runtime lever would move them. Explain active instance-hours, job execution count and duration rather than inferring them from request count. Reports marked PARTIAL are subtotals, cannot approve a ceiling, and must never be presented as a full monthly bill. For an existing deployment, compare usingneckbeard estimate -plan <plan.json> -env <environment>; keep the authenticated plan local.- If I asked for a comparison, run the alternative WITHOUT touching my files:
copy
neckbeard.yamlto a scratch path with the one changed field, thenneckbeard plan -config <scratch.yaml> -out <scratch-blueprint.yaml>andneckbeard estimate -config <scratch.yaml> -blueprint <scratch-blueprint.yaml> -out <scratch-report.md>, and present both expected totals side by side with the reason for the difference.
Do not scaffold. End by telling me the next step is /neckbeard:sync once I
am happy with the numbers.
$ARGUMENTS
Cost model v3 covers AWS/Azure/GCP serverless and Kubernetes. Before presenting
an estimate, review active_instance_hours (per HTTP service), job executions
and duration, and additional_node_hours (aggregate hours above minimum nodes).
Workers and minimum nodes remain billable at idle. Check log queries, object
operations, custom metric series and explicit unused-feature assumptions in the
report. Unused inputs for another runtime add no charge; missing billable
components make coverage partial. See the
cost model and distinguish pricing evidence from deployed billing.
Show the neckbeard quick reference. One shot, change nothing, run nothing:
The flow — /neckbeard:analyze (read the repo into an evidence-backed
profile; ask what code can't tell) → /neckbeard:estimate (plan against the
module catalog and show the monthly cost table before anything exists) →
/neckbeard:sync (plan → estimate → scaffold → validate under the ownership
contract) → the generated docs/bootstrap.md (a human with elevated
credentials sets up state, OIDC federation, and CI identities per environment)
→ the deployment lifecycle in the skill's release reference.
Commands — /neckbeard:analyze, /neckbeard:estimate [comparison],
/neckbeard:sync, /neckbeard:doctor [plan|estimate|validate|all] (installs
the CLI if missing; reports the rest of the toolchain), /neckbeard:help.
Disco (experimental) — /neckbeard:disco [project-name] renders the reviewed
profile as disco.json and docs/disco.md for a human to deploy on a VPS.
It bypasses cloud planning, estimates, and validation; -force replaces both
outputs without scaffold's ownership protection. See the skill's Disco reference.
What it proves — V0 (static: fmt, validate, checkov, kubeconform) is what
the plugin runs; it never claims deployability. V1 (authenticated plan) and V2
(deployment verification) need cloud credentials and are reported NOT
EXERCISED until a human runs them. The agent never hand-writes infrastructure:
every module comes from the versioned catalog, the planner emits a
hash-verified blueprint.yaml, and regeneration never silently overwrites
edits.
Supported workload — one image, up to 10 HTTP/worker/cron processes,
Postgres, object storage, secrets. AWS / GCP / Azure × GitHub / GitLab ×
serverless containers / Kubernetes. Anything else becomes a named
unsupported finding with a disposition, not a force-fit.
Point at https://github.com/bealesh/neckbeard for the README, design, and the live findings ledger.
If the user chose Disco, follow the skill's references/disco.md and
/neckbeard:disco instead. This cloud loop does not operate Disco outputs.
Load the neckbeard skill and run its plan → estimate → scaffold → validate loop
against the current neckbeard.yaml and app-profile.yaml (if neckbeard is
not on PATH, install it first as the skill's Prerequisites say):
- Show me the topology summary and the estimate's scenario table (plus the unpriced/unmodeled section) BEFORE scaffolding. If the estimator is unavailable, say so and ask before continuing without numbers.
- Apply the ownership contract strictly: resolve scaffold conflicts
(
<file>.neckbeard-new) with me rather than deleting my edits; never touchblueprint.yamlby hand. - Finish with the validate report, spelling out exactly what PASSED, FAILED,
and was NOT EXERCISED — V0 proves syntax and policy, never deployability —
and what the next human step is (usually the generated
docs/bootstrap.md).
$ARGUMENTS
Hooks 1
Sponsors
Details
- Marketplace
- bealesh/neckbeard
- Category
- Devops