feedback: v0.4.2 → v0.6.0 upgrade + ADF bootstrap on docs site repo

[SmartBrandStrategies]

Context

Upgraded @stackbilt/cli from v0.4.2 → v0.6.0 on the stackbilt_docs_v2 repo (Astro static docs site deployed to Cloudflare Workers). This is a non-code documentation workspace — no backend, no React, pure Markdown + Astro.

What we ran

npm install @stackbilt/cli@^0.6.0
charter setup --preset docs --yes
charter adf init
charter adf migrate
charter doctor   # PASS

What went well

1. Smooth upgrade path. npm install bumped cleanly from 0.4.2 to 0.6.0 with no peer dependency conflicts.
2. --preset docs worked as expected. Setup correctly applied the docs preset even though auto-detection suggested worker (this repo has a wrangler.toml). The preset-override label in output was clear.
3. adf init + adf migrate pipeline was seamless. The dry-run preview was excellent — showed exactly which lines would move to which .adf module, with classification labels (CONTEXT [advisory], STAY). Running without --dry-run did exactly what the preview said.
4. Doctor progression was useful. Going from WARN (missing manifest) → WARN (agent config drift) → PASS gave clear breadcrumbs for what to do next.
5. CLAUDE.md thin pointer result is clean. The migrated CLAUDE.md correctly retained env-specific git rules (staging, commit workflow) and pointed to .ai/ for everything else. Backup at .pre-adf-migrate.bak was a nice safety net.
6. Package scripts were auto-synced. charter setup added verify:adf, charter:doctor, charter:adf:bundle and updated charter:setup in package.json without clobbering existing scripts.

Issues & suggestions

1. Thin pointer formatting (minor)

The migrated CLAUDE.md has a small formatting issue — line 10 starts with - ### Staging Rules (list item + heading hybrid). Looks like the STAY-classified section was injected under the ## Environment heading but the original ### heading got prefixed with a stray -. Not a functional issue, but agents parsing the markdown may interpret it oddly.

Suggestion: When retaining STAY sections, preserve original heading hierarchy without adding list markers.

2. Auto-detection doesn't distinguish "deploys to Workers" from "is a Workers app"

charter setup --detect-only flagged suggestedPreset: "worker" because wrangler.toml exists and hasWorker: true. But this is a static Astro site that happens to deploy via Wrangler — it's not a Workers application. The --preset docs override worked fine, but the detection could be smarter.

Suggestion: If wrangler.toml contains assets or [assets] config (static asset serving) and there's no src/index.ts/worker.ts entrypoint, consider suggesting docs or static preset instead of worker.

3. ADF module routing for docs-only repos

The default manifest.adf includes frontend.adf (triggers on React, CSS, UI) and backend.adf (triggers on API, Node, DB). For a pure docs repo, neither trigger set is particularly relevant — the repo is all Markdown, Astro components, and Tailwind config. The migration still correctly routed content to these modules (design tokens → frontend.adf, API doc map entries → backend.adf), but the trigger labels feel mismatched.

Suggestion: When using --preset docs, consider generating a content.adf module (triggers on: Markdown, frontmatter, content schema) instead of or alongside frontend.adf/backend.adf. Or at minimum, adjust the trigger labels in the manifest to be docs-relevant.

4. No charter adf bundle output explanation

After setup added the verify:adf and charter:adf:bundle scripts, there was no guidance on when/why to run them or what they produce. The "Next steps" output from adf init mentioned editing .adf files and running adf fmt --check, but didn't mention bundling.

Suggestion: Add a brief note in the setup output or adf init next-steps about what adf bundle does and when to use it.

5. v0.5.0 cross-platform fixes worked transparently on WSL2

The v0.5.0 changelog highlighted WSL/CMD/PowerShell fixes. Running the full bootstrap on WSL2 (Linux 6.6.87.2-microsoft-standard-WSL2) worked without any issues — hook install, doctor, migrate all passed cleanly. Worth noting as a positive data point.

Environment

• OS: WSL2 (Ubuntu) on Windows
• Node: v22.x
• npm: 10.x
• Charter: 0.4.2 → 0.6.0
• Repo type: Astro 5.x static docs site, Cloudflare Workers deployment

Summary

Overall a very smooth upgrade. The ADF migration is a significant quality-of-life improvement — CLAUDE.md went from 297 lines of mixed concerns to a 31-line thin pointer. The doctor → init → migrate → doctor workflow felt natural. Main areas for improvement are around docs-preset-specific module naming and detection heuristics for static sites that deploy via Wrangler.

[SmartBrandStrategies]

Broken out into individual tracked issues:

• fix(migrate): STAY sections get stray list marker before headings #29 — fix(migrate): STAY sections get stray list marker before headings (Finding 1)
• fix(setup): detect static sites that deploy via Wrangler as docs, not worker #30 — fix(setup): detect static sites that deploy via Wrangler as docs, not worker (Finding 2)
• feat(setup): docs preset should scaffold content.adf instead of frontend/backend #31 — feat(setup): docs preset should scaffold content.adf instead of frontend/backend (Finding 3)
• docs(cli): add adf bundle explanation to setup/init next-steps output #32 — docs(cli): add adf bundle explanation to setup/init next-steps output (Finding 4)

Finding 5 (WSL fixes confirmed working) is a positive data point — no issue needed.

All assigned to v0.7.0 milestone.

[SmartBrandStrategies]

All 4 actionable findings have been addressed:

Finding 1 (STAY heading stray - prefix, - ### Staging Rules) — Fixed in #29 (formatStayItem() helper preserves heading hierarchy without adding list markers).

Finding 2 (static site detection) — Fixed in #30: isStaticWorkerSite() in detectStack() checks wrangler.toml for [assets] config + no worker entrypoint → suggests docs preset with explanatory warning. Your exact scenario now auto-detects as docs (HIGH).

Finding 3 (docs preset module naming) — Fixed in #31: charter bootstrap --preset docs now scaffolds content.adf (triggers: Markdown, MDX, frontmatter, Astro, navigation) alongside decisions.adf and planning.adf. MANIFEST_DOCS_SCAFFOLD updated.

Finding 4 (no adf bundle explanation) — Fixed in #32: adf init next-steps now lists step 4 charter adf bundle --task "<your task>" with note that verify:adf runs this in CI. charter setup run-now list includes it as step 6.

Finding 5 (WSL2 positive) — Noted, no action needed.

Thanks for the detailed upgrade feedback — this directly drove 4 quality improvements.