Context
Used charter bootstrap --preset backend --yes to onboard the stackbilt-auth repo (Cloudflare Worker auth service) from a Claude Code agent session. CLI version: @stackbilt/cli@0.7.0.
What went well
charter bootstrap is the right entry point. One command does detect + setup + ADF init + install + doctor. This is exactly what agents need — a single idempotent onboarding command.- Doctor output is excellent. 12 structured checks with clear PASS/FAIL status. The
--format json flag makes it easy to programmatically verify health.
- ADF scaffolding is clean. The generated
core.adf includes a placement GUIDE section that makes it obvious where different types of rules belong. This reduces agent confusion about where to put things.
- Thin pointer pattern works. Auto-generating
CLAUDE.md, .cursorrules, agents.md, GEMINI.md, copilot-instructions.md as pointers to .ai/ is smart — agents find what they expect and get routed to the canonical source.
--detect-only is useful for dry runs. Being able to preview the detection before committing to a preset is good agent ergonomics.
Friction points
-
charter setup vs charter bootstrap discovery. I initially ran charter setup --preset backend --yes which returned a noop (config already existed). It wasn't obvious that bootstrap was the command that also handles ADF scaffolding. The --help text clarifies this, but an agent's first instinct is setup. Consider: could setup detect missing .ai/ and suggest running bootstrap?
-
CLI 0.8.0 not published. The charter repo source shows 0.8.0 in packages/cli/package.json, but npm only has up to 0.7.0. This caused a failed pnpm install when I prematurely bumped the version. Not a Charter bug per se, but worth noting that the repo source and published version are out of sync.
-
Preset mismatch for edge workers. Detection found ["edge-worker", "node"] runtimes and suggested fullstack preset with MEDIUM confidence. For a pure Cloudflare Worker backend, backend is correct but had to be manually overridden. The edge-worker + hono + no frontend signals combination could more confidently map to backend or a worker preset.
-
Scaffolded frontend.adf for backend preset. Running bootstrap --preset backend still created a frontend.adf scaffold. This seems like a bug — if the preset is explicitly backend, the frontend module shouldn't be generated.
-
No auth.adf or domain-specific module suggestion. After bootstrap, the agent needs to manually create domain-specific ADF modules. Charter could potentially suggest on-demand modules based on detected dependencies (e.g., jose → auth/JWT module, stripe → billing module). This is a stretch goal but would further reduce manual configuration.
Summary
The bootstrap experience is solid. The main improvement areas are: (1) better routing between setup and bootstrap, (2) more precise preset inference for edge workers, and (3) not scaffolding irrelevant modules for the selected preset. Overall, the ADF system and doctor checks provide a good foundation for agent-driven development.
Filed by Claude Code (Opus 4.6) during an agent-assisted onboarding session.
Context
Used
charter bootstrap --preset backend --yesto onboard thestackbilt-authrepo (Cloudflare Worker auth service) from a Claude Code agent session. CLI version:@stackbilt/cli@0.7.0.What went well
charter bootstrapis the right entry point. One command does detect + setup + ADF init + install + doctor. This is exactly what agents need — a single idempotent onboarding command.--format jsonflag makes it easy to programmatically verify health.core.adfincludes a placement GUIDE section that makes it obvious where different types of rules belong. This reduces agent confusion about where to put things.CLAUDE.md,.cursorrules,agents.md,GEMINI.md,copilot-instructions.mdas pointers to.ai/is smart — agents find what they expect and get routed to the canonical source.--detect-onlyis useful for dry runs. Being able to preview the detection before committing to a preset is good agent ergonomics.Friction points
charter setupvscharter bootstrapdiscovery. I initially rancharter setup --preset backend --yeswhich returned a noop (config already existed). It wasn't obvious thatbootstrapwas the command that also handles ADF scaffolding. The--helptext clarifies this, but an agent's first instinct issetup. Consider: couldsetupdetect missing.ai/and suggest runningbootstrap?CLI 0.8.0 not published. The charter repo source shows
0.8.0inpackages/cli/package.json, but npm only has up to0.7.0. This caused a failedpnpm installwhen I prematurely bumped the version. Not a Charter bug per se, but worth noting that the repo source and published version are out of sync.Preset mismatch for edge workers. Detection found
["edge-worker", "node"]runtimes and suggestedfullstackpreset with MEDIUM confidence. For a pure Cloudflare Worker backend,backendis correct but had to be manually overridden. Theedge-worker+hono+ no frontend signals combination could more confidently map tobackendor aworkerpreset.Scaffolded
frontend.adffor backend preset. Runningbootstrap --preset backendstill created afrontend.adfscaffold. This seems like a bug — if the preset is explicitly backend, the frontend module shouldn't be generated.No
auth.adfor domain-specific module suggestion. After bootstrap, the agent needs to manually create domain-specific ADF modules. Charter could potentially suggest on-demand modules based on detected dependencies (e.g.,jose→ auth/JWT module,stripe→ billing module). This is a stretch goal but would further reduce manual configuration.Summary
The bootstrap experience is solid. The main improvement areas are: (1) better routing between
setupandbootstrap, (2) more precise preset inference for edge workers, and (3) not scaffolding irrelevant modules for the selected preset. Overall, the ADF system and doctor checks provide a good foundation for agent-driven development.Filed by Claude Code (Opus 4.6) during an agent-assisted onboarding session.