Plan: Issue 20 TanStack Start Wiki

Status: Planned Mode: parallel by task wave Backlog mirror: https://github.com/wearedevpunks/harness-intelligence/issues/20

Initial Situation

Issue #20 reports that the scaffolded wiki should support TanStack Start. The current makeWikiScaffoldTemplate() emits a Next.js Fumadocs app only. runStageScaffold() prompts for backlog provider and writes backlog-provider.md, but it has no wiki framework prompt or pin. runUpdate() rebuilds expected wiki output by calling scaffoldWikiForDirectory(), so an operator-converted TanStack Start wiki would drift back toward the Next template.

Issue

The wiki scaffold needs a durable framework choice that affects both initial generation and future update alignment. The generated TanStack Start app must remain equivalent to the current Next scaffold from a Harness operator perspective: same project docs tree, content sync, Mermaid support, source loader, search endpoint, wiki bookkeeping, and scoped agent guidance.

Solution Shape

Persist a wiki-local wiki-framework.md file with values next or tanstack-start, mirroring the existing backlog-provider pin. Prompt for it during dp scaffold init, default to Next.js, and have update read the pin with a Next.js fallback. Parameterize the wiki template into shared content/bookkeeping files plus framework-specific app/package/config files.

Resolved Decision Ledger

Codebase Findings

• apps/cli/src/scaffold/stage.ts owns the stage prompt, wiki target, wiki file writes, and current backlog-provider pin.
• apps/cli/src/content/wiki.ts owns the hard-coded Next.js Fumadocs template.
• apps/cli/src/update/run.ts stages expected wiki output during update and currently assumes Next.js through scaffoldWikiForDirectory().
• apps/cli/src/scaffold/stage.test.ts covers init wiki output, existing-file preservation, monorepo apps/wiki, and no nested apps/wiki/wiki.
• apps/cli/src/update/run.test.ts covers wiki update alignment.

External Research

• Fumadocs quick start lists TanStack Start as a built-in create-fumadocs-app framework.
• Fumadocs TanStack Start manual install uses Tailwind 4, Fumadocs MDX Vite setup, routes/docs/$.tsx, routes/api/search.ts, and fumadocs-ui/provider/tanstack.
• TanStack Start uses file-based routing under src/routes and root route src/routes/__root.tsx.
• TanStack Start server routes follow route-file conventions such as routes/api/file/$.ts.
• Local Fumadocs source includes examples/tanstack-start with Vite, TanStack Start, Fumadocs MDX, search route, docs route, and .source gitignore behavior.

Dependency Graph

T1 -> T2 -> T3 -> T4 T1 -> T5

T1: Add wiki framework prompt and pin

• depends_on: []
• location: apps/cli/src/scaffold/stage.ts, apps/cli/src/content/stage-scaffold.ts, apps/cli/src/scaffold/stage.test.ts
• description: Model WikiFramework, prompt for Next.js/TanStack Start after backlog provider, render wiki-framework.md, and include the selected framework in operator output.
• validation: Stage tests prove the default is Next.js, selectable TanStack Start is accepted, and the pin is written beside backlog-provider.md.
• status: Planned
• log:
• files edited/created:
• backlog_item_id: #20
• backlog_item_url: https://github.com/wearedevpunks/harness-intelligence/issues/20
• relation_mode: body-links
• assigned_skills: [effect-authoring, simplify, tdd]
• tdd_target: runStageScaffold() with no framework answer writes wiki/wiki-framework.md containing next; with tanstack-start answer it records tanstack-start.
• review_mode: cli

T2: Parameterize wiki template by framework

• depends_on: [T1]
• location: apps/cli/src/content/wiki.ts, apps/cli/src/scaffold/stage.test.ts
• description: Split shared wiki files from framework-specific package/config/routes and emit TanStack Start equivalents for package scripts, Vite config, routes, provider, source loader, styles, search, and Mermaid.
• validation: Stage tests prove TanStack output includes @tanstack/react-start, fumadocs-mdx/vite, vite build, src/routes/docs/$.tsx, src/routes/api/search.ts, src/routes/__root.tsx, shared project content, sync script, and Mermaid components.
• status: Planned
• log:
• files edited/created:
• backlog_item_id: #20
• backlog_item_url: https://github.com/wearedevpunks/harness-intelligence/issues/20
• relation_mode: body-links
• assigned_skills: [effect-authoring, simplify, tdd]
• tdd_target: A selected TanStack Start scaffold fails until generated package/routes match the expected framework-specific surface while preserving shared wiki content.
• review_mode: cli

T3: Preserve framework choice during update

• depends_on: [T2]
• location: apps/cli/src/scaffold/stage.ts, apps/cli/src/update/run.ts, apps/cli/src/update/run.test.ts
• description: Read <wiki-root>/wiki-framework.md from the copied current wiki during update alignment; default to next when missing; restage expected wiki output with that framework.
• validation: Update tests prove a pinned TanStack Start wiki is not converted back to Next.js.
• status: Planned
• log:
• files edited/created:
• backlog_item_id: #20
• backlog_item_url: https://github.com/wearedevpunks/harness-intelligence/issues/20
• relation_mode: body-links
• assigned_skills: [effect-authoring, simplify, tdd]
• tdd_target: runUpdate() against an existing apps/wiki/wiki-framework.md with tanstack-start fails while expected changes contain Next-only files or scripts.
• review_mode: cli

T4: Align docs and closeout artifacts

• depends_on: [T1, T2, T3]
• location: docs/README.md, docs/runbooks/dp-cli-scaffolding.md, docs/reference/dp-requirements.md, apps/wiki/content/docs/project/specs/cli/issue-20-tanstack-start-wiki/IMPLEMENTATION-NOTES.md, apps/wiki/content/docs/project/tech-debt/cli/issue-20-tanstack-start-wiki.md
• description: Update operator docs and record implementation evidence, validation, and debt resolution.
• validation: Docs mention wiki framework selection and update preservation; implementation notes link the issue, plan, debt, and validation commands.
• status: Planned
• log:
• files edited/created:
• backlog_item_id: #20
• backlog_item_url: https://github.com/wearedevpunks/harness-intelligence/issues/20
• relation_mode: body-links
• assigned_skills: [parallel-research, simplify]
• tdd_target: Documentation review fails while docs still imply the wiki scaffold is Next-only.
• review_mode: cli

T5: Review generated equivalence

• depends_on: [T2]
• location: apps/cli/src/content/wiki.ts, generated temp scaffold output
• description: Inspect generated Next and TanStack Start wiki trees for equivalent Harness content, metadata, source loading, and operator guidance.
• validation: Generated-file inspection shows both frameworks include the same project docs content tree and framework-appropriate runtime files.
• status: Planned
• log:
• files edited/created:
• backlog_item_id: #20
• backlog_item_url: https://github.com/wearedevpunks/harness-intelligence/issues/20
• relation_mode: body-links
• assigned_skills: [parallel-research, simplify]
• tdd_target: Manual/generated tree review catches missing shared files in the TanStack output.
• review_mode: cli

Parallel Execution Waves

• Wave 1: T1.
• Wave 2: T2 and T5 can run together after the first TanStack template is available.
• Wave 3: T3.
• Wave 4: T4.

Testing Strategy

• bun run --cwd apps/cli test -- src/scaffold/stage.test.ts src/update/run.test.ts
• bun run check-types --filter=@punks/cli
• bun run check --filter=@punks/cli
• git diff --check

Risks And Mitigations

• Risk: TanStack output diverges from the existing project docs tree. Mitigation: keep shared content files framework-agnostic and test shared file presence.
• Risk: Update converts existing TanStack apps back to Next.js. Mitigation: wiki-local pin drives update expected output with missing pin fallback to Next.
• Risk: Prompt order breaks existing tests. Mitigation: test queue explicitly accounts for backlog provider first and framework second.
• Risk: Framework abstraction grows too broad. Mitigation: support only next and tanstack-start in this issue.

Unresolved Questions

None.