Bootstrap UX: feedback from real-world adoption on existing repo

[stackbilt-admin]

Context

Ran charter bootstrap --yes --preset worker --ci github on aegis-oss, an existing Cloudflare Worker project with a mature .ai/ directory (6 ADF modules, rich production content). This is feedback from that real adoption experience.

What worked well

• Stack detection was excellent — correctly identified worker preset at HIGH confidence
• CLAUDE.md migration — pulled existing rules into core.adf CONTEXT and CONSTRAINTS sections automatically
• CI workflow generation — charter-governance.yml dropped in with no manual wiring
• Non-destructive on unknown modules — existing agent.adf, channels.adf, kernel.adf, persona.adf were left untouched (not deleted)
• Pointer file generation — .cursorrules, agents.md, GEMINI.md, copilot-instructions.md all created

Issues found

1. --yes conflates "non-interactive" with "force overwrite"

The bootstrap source has const force = options.yes; — these are the same flag. Running --yes on a repo with existing .ai/core.adf and .ai/state.adf (containing rich, hand-written production context) overwrites them with scaffolds.

Suggestion: Separate --yes (non-interactive, accept defaults) from --force (overwrite existing content). --yes without --force should still refuse to overwrite non-scaffold ADF files, or at minimum back them up.

2. No backup of overwritten ADF files

When bootstrap overwrites core.adf and state.adf, the original content is gone. The migration step only processed CLAUDE.md — the existing ADF file content was not migrated or preserved.

Suggestion: Before overwriting, copy existing files to .ai/.backup/ or .ai/<file>.pre-bootstrap. Or at least print a warning listing what will be destroyed with byte counts.

3. Install phase assumes root package.json

Detected as HIGH confidence worker preset, but npm install ran at project root where there's no package.json. The actual package.json lives in web/ — a common pattern for Cloudflare Worker projects that have docs, scripts, and other directories alongside the worker.

Suggestion: For the worker preset, also check web/package.json, worker/package.json, src/package.json. Or respect the detection phase's knowledge of where the package context was found.

4. Orphaned modules not registered in manifest

Bootstrap generated a manifest referencing only core.adf, state.adf, backend.adf. But the .ai/ directory still contains agent.adf, channels.adf, kernel.adf, persona.adf from the existing project. These modules are now invisible to Charter's module system — charter adf bundle won't load them, charter adf sync won't track them, evidence won't measure them.

Suggestion: After scaffold, scan .ai/ for .adf files not in the manifest and either:

• Auto-register them as ON_DEMAND modules (prompt for trigger keywords, or infer from section names)
• Warn: "Found 4 unregistered .adf modules: agent.adf, channels.adf, kernel.adf, persona.adf. Run charter adf register to add them to the manifest."

5. CLAUDE.md migration loses structural fidelity

The migrated content in core.adf has some formatting artifacts. Multi-line content from CLAUDE.md sections got concatenated into single list items:

- [code] aegis-oss/
- [Build commands] cd web; # Install deps; npm install (...)

The original CLAUDE.md had a clear ## Structure section with a code block and a ## Commands section with bash blocks. These don't map cleanly to ADF list format.

Suggestion: For code blocks and structured sections, consider preserving them as ADF text blocks rather than forcing them into list items. Or add a CODE or REFERENCE section type for this kind of content.

6. charter adf populate should be opt-in during bootstrap

For existing repos with code, populate could extract a lot of useful context automatically. It's listed as a "next step" but could be a bootstrap phase (Phase 3.5) with --skip-populate to opt out.

7. charter serve not mentioned in next steps

Charter has MCP server support (charter serve) which is highly relevant for Claude Code users. Bootstrap could suggest adding it to .claude/settings.json as a next step, especially since it just generated a CLAUDE.md pointer.

Environment

• Charter: latest via npx @stackbilt/cli
• OS: WSL2 (Linux 6.6.87.2)
• Repo: Existing Cloudflare Worker project with 6 pre-existing ADF modules
• Command: npx @stackbilt/cli bootstrap --yes --preset worker --ci github

Summary

The happy path (greenfield repo) is smooth. The rough edges appear when bootstrapping into an existing project with pre-existing .ai/ content — which is arguably the most important adoption path, since teams with existing agent configs are Charter's primary audience.

The core theme: bootstrap should be additive/merging by default, destructive only with explicit --force.

[stackbilt-admin]

Critical items fixed in PR #67 (merged 2026-03-27): --yes vs --force separation, backup to .ai/.backup/, orphan auto-registration. Remaining polish (package.json detection, migration fidelity, populate opt-in, serve suggestion) can be tracked in a follow-up issue if needed.