Template overhaul: identity renames, mern/django packs, doc style restructure

[DeyangChan]

Summary

Thirteen commits in four phases, in review order:

1. Identity renames — repo renamed cavalry-template-spa → vstack-template-base (GitHub redirect in place); packs renamed to identity names: vercel → vercel-csr, taro-fastify-mysql-tencent → wechat, nextjs-nestjs-postgres → enterprise. Naming rule in stacks/README.md rewritten; each pack README records its underlying triple.
2. Two new stack packs — mern (React SPA + Express 5 + MongoDB/Mongoose) and django (React SPA + Django 5/DRF + Postgres), both platform-neutral, with conflict registers and add-on bindings (saas-billing bound, seo unbound).
3. Tooling removals — Spec Kit (.specify/ + skills) deleted; retired seo Spec Kit artifacts (1,708 lines) deleted; CLAUDE.md records both.
4. Documentation restructure — a new Documentation style section in CLAUDE.md (plain purpose-first business English), then all 52 live files under add-ons/ and stacks/ rewritten to semi-strict outlines: specs open Goal → Scope → User stories and end with edge cases / notes & decisions / open questions; pack manifests and appendices get numbered Day-1 checklists, Scope/Operations/Gotchas sections, and registers last. saas-billing reframed to lead with plans, checkout, renewal, and invoices. Two content bugs fixed (provider-name leak in both Vercel infra appendices).

Contract preservation (diff-verified per corpus): every story/flow/requirement/criterion ID, error code, permission name, audit action, config key, copy-paste command block, precedence line, and conflict-register tail is unchanged; cross-file constant couplings (e.g. BACKUP_RETENTION_DAYS) kept word-identical.

Test plan

• Docs-only change; the toolchain placeholders in Common commands are still unfilled, so no lint/typecheck/test/build suite exists to run (stated per the Definition of Done).
• Automated sweeps per corpus: verbatim precedence-line grep (1 per appendix), register position/field checks, ID and error-code set diffs against the previous commit, named-key greps, line caps (~150 add-on / <200 appendix).

🤖 Generated with Claude Code

[DeyangChan]

Ava deep review

Directionally this is a real improvement: the template is more honestly documentation/contract-shaped, the stack identities are clearer, the Spec Kit machinery removal looks intentional, and the mechanical checks I ran did not find broken Markdown links, empty docs, unclosed fences, heading jumps, stale old stack-directory references, or missing seo / saas-billing binding coverage.

I would still fix these before merge:

Medium

1. stacks/wechat/README.md:9 — pack identity says Mini Program, but the pack is H5-only.
   The README says the pack is named for “a WeChat mini-program”, while stacks/wechat/frontend.md:13 says Taro 4, H5 target only — no Mini Program targets active. That makes the identity misleading for adopters. Please either reword the identity around WeChat-market / Tencent H5, or add real Mini Program target bindings if Mini Program is intended.

2. stacks/enterprise/README.md:39 / README.md:94 — copy-paste Day-1 commands still contain a TODO that the final grep misses.
   The enterprise dev block is intended to be copied into root CLAUDE.md, but pnpm bootstrap still says TODO: name the docker-compose Postgres service. The final Day-1 grep only catches TODO: replace and <pm>, so this unresolved TODO can survive while the verification command passes. Please either resolve the service/container convention here or broaden the final grep to catch active TODO / FIXME markers.

3. README.md:83 / .github/workflows/ci.yml:38-39 — the base CI wording still hardcodes “migration round-trip”, but some packs replace that gate.
   Enterprise uses Prisma apply/drift gates (stacks/enterprise/README.md:57), and Django uses apply-from-zero + makemigrations --check (stacks/django/README.md:62). The root checklist still says to wire “the migration up/down round-trip”, and the CI stub names the step “Migration round-trip”. Please rename the base item to a generic “Migration gate” and let each pack’s db.md / README specify whether it is up→down→up, Prisma drift, Django migration drift, etc.

4. README.md:80 / add-ons/saas-billing/README.md:9,30 — saas-billing/bindings.md lifecycle is easy to apply incorrectly.
   Root Day-1 says add-ons with bindings.md should delete sections for packs not adopted, but saas-billing says to copy the active pack entry into backend.md and then delete bindings.md. After deleting it, the saas-billing README still points at bindings.md unless the adopter also edits that README, which is not stated. Please make this lifecycle explicit and consistent: either keep a pruned bindings.md, or document the README cleanup/replacement after copying.

Low

5. stacks/README.md:9 — naming policy omits the new django category.
   The policy allows platform/product names, acronyms, or architectural-character names, but stacks/django/README.md:9 says the new pack is named for its backend framework. Please add backend/framework identity as an allowed naming source, with django as the example.

6. CLAUDE.md:85-89 vs CLAUDE.md:164 / specs/README.md:8-9 — style rule is stricter than nearby active docs.
   The new style section bans em-dash chains, nested parentheticals, and document-history/meta narration, but the Spec Kit removal note and spec convention bullets still use those patterns. This is not a functional blocker, but it makes the new style guidance less mechanically enforceable. Either narrow the rule with explicit exceptions for audit/registry notes, or rewrite those bullets to match the style.

Checks performed

• PR scope: 115 files, net large deletion (+2399 / -7968).
• Markdown relative links/anchors: no broken local links found.
• Empty Markdown files: none.
• Code fences / heading levels: no unclosed fences or heading jumps found.
• Stale old stack paths in head: no stacks/vercel/, stacks/nextjs-nestjs-postgres, stacks/taro-fastify-mysql-tencent, or cavalry-template-spa references found.
• seo and saas-billing binding coverage: all shipped packs covered.
• CI: current ci check is green; PR is mergeable clean.

Verdict: good direction, but I would clean up the Day-1 contradictions above before merging because this repo is mostly instructions. A small wording inconsistency here becomes the generated project’s operating procedure.

[DeyangChan]

One structural question: do we actually want add-ons to carry their own specs/ programs?

I’d lean no. The add-on README should be durable capability guidance: approach, invariants, stack seams, interactions. Actual feature specs should live in the top-level specs/ folder when a project adopts and implements the capability, because they are project-specific and need local decisions.

Right now the PR creates a split spec model:

• specs/ — the normal project feature-spec home
• add-ons/enterprise-compliance/specs/ — 13 bundled docs
• add-ons/saas-billing/specs/ — 9 bundled docs
• add-ons/multi-tenancy/SPEC.md — a third shape

That makes Day-1 adoption heavier and risks generic specs being mistaken for already-adopted implementation plans. For larger add-ons like saas-billing / enterprise-compliance, I’d prefer keeping a concise “Implementation areas” table in the README, then having adopters create or copy real dated specs into top-level specs/ when they start the work.

So the cleaner contract would be:

• add-ons/<name>/README.md = reusable capability guidance
• optional add-ons/<name>/bindings.md = stack-specific bindings, if needed
• specs/ = the single home for actual project feature specs

Not necessarily a blocker, but I think this would make the template easier to adopt and less likely to accumulate stale generic build plans.

[DeyangChan]

Addressed all six review findings in da35756:

1. wechat identity — now states the shipped frontend is Taro's H5 target only (no Mini Program target active), matching frontend.md.
2. enterprise TODO — the dev block names the fixed-name Postgres container (same convention as the sibling packs), and the Day-1 final grep now catches any surviving TODO:, not just TODO: replace.
3. Generic migration gate — the root checklist item and the ci.yml stub are now a generic Migration gate that the active pack's db.md fills in; all pack references updated (vercel/mern fill it with the up→down→up round-trip; enterprise/django replace it with their drift gates per their registers).
4. saas-billing lifecycle — adoption now has an explicit step to update the README's two bindings.md links after the file is deleted, and the root Day-1 step defers to each bindings file's own lifecycle (prune vs copy-then-delete).
5. Naming policy — defining-framework names (django) added as an allowed source.
6. Style consistency — the Spec Kit Learnings note and the two specs/README.md bullets rewritten to the documentation style.

On the structural question (add-ons carrying specs/): discussing options with Adam before changing anything — it affects ~35 files and the add-on packaging contract.

🤖 Generated with Claude Code

[DeyangChan]

Resolved the structural question with Adam: bundled programs stay, but the move to top-level specs/ becomes mandatory at adoption (commit 52c9be8). The add-on keeps durable guidance (README, bindings); its spec program is explicitly a proposal that relocates to the single spec home when adopted, and an unadopted add-on still deletes clean. This keeps the curated programs while removing the split-spec-model and mistaken-for-adopted-plans risks.

🤖 Generated with Claude Code

[DeyangChan]

Correction to the previous resolution, per Adam: add-on spec programs never move into top-level specs/ — that directory is for the project's actual requirement specs only. The bundled programs stay in their add-ons permanently as reference material; implementing an add-on area means writing the project's own requirement spec in specs/, drawing on the program. Updated in 7f350c6 across add-ons/README.md, specs/README.md, and the three add-ons that ship programs.

🤖 Generated with Claude Code

[DeyangChan]

Final shape for the add-on specs question, per Adam: the bundled spec programs are gone, distilled into each README. Every multi-area add-on now carries an Implementation areas section — per area, the coverage checklist and the opinionated calls as directives (saas-billing 90 lines, enterprise-compliance 108, multi-tenancy 66). Top-level specs/ is for the project's actual requirement specs, written per area at implementation time against those checklists. The 23 program files are deleted (recoverable from git history); add-ons/README.md and specs/README.md state the new contract.

🤖 Generated with Claude Code

[DeyangChan]

Bindings system removed, per Adam (e569196). The model is now: an add-on README is the crash course read into context when its capability is planned or built; the concrete stack wiring is derived at adoption from the add-on's Binds to a stack seam list plus the active pack's appendices, and recorded in the implementing requirement spec — nothing pre-written per add-on × pack combination. Deleted: both bindings.md files and all seven pack-side "Add-on bindings" sections plus the pack READMEs' add-on rosters. Kept, because they aren't derivable: new Prerequisites sections (seo requires a server-rendered stack — vercel-ssr or enterprise; saas-billing requires a tenant model) and one-line incompatibility notes in the four CSR pack manifests.

🤖 Generated with Claude Code