Skip to content

feat(setup): add docs/planning preset for non-code workspaces (ADX-006) #3

@SmartBrandStrategies

Description

@SmartBrandStrategies

Context

Charter v0.4.2 was installed into stackbilt_llc, a pure planning/docs workspace (markdown files, no application code). This is the first non-code workspace adoption and surfaces a preset gap.

Problem

  1. No docs preset: detectStack() returns confidence: LOW, suggestedPreset: fullstack for repos with no framework dependencies. The valid preset enum is worker | frontend | backend | fullstack — there is no docs/planning option.

  2. adf init scaffolds irrelevant modules: Always creates frontend.adf (triggers: React, CSS, UI) and backend.adf (triggers: API, Node, DB) regardless of repo type. A planning workspace needs decisions.adf and planning.adf instead.

  3. LOW confidence gives no guidance: When nothing is detected, no explanation of why or suggestion that this might be a docs-only workspace.

  4. charter drift is a silent noop: Drift scanner checks **/*.ts,js files. Docs repo has none. No "nothing to scan" notice.

Proposed Solution

Add docs to StackPreset union

Detection signals:

  • Majority .md files in repo root and docs/
  • Presence of docs/, ADR/, or papers/ directories
  • Absence of any framework dependency in package.json (or no package.json)
  • package.json description containing planning/docs/governance keywords

Preset-conditional ADF scaffold

For docs preset, adf init would create:

  • decisions.adf (Triggers: ADR, decision, tradeoff, architecture) instead of frontend.adf
  • planning.adf (Triggers: sprint, milestone, roadmap, OKR, timeline) instead of backend.adf

Docs-specific blessed-stack patterns

Replace code-oriented patterns with:

  • Decision record structure
  • Document versioning/dating conventions
  • Cross-reference integrity

Better LOW confidence messaging

When confidence === 'LOW' and no frameworks detected:

Warning: No code stack detected. This may be a docs-only or planning workspace.
Consider: charter setup --preset docs

Files Affected

  • packages/types/src/index.ts — add docs to StackPreset
  • packages/cli/src/commands/setup.ts — detection signals, fallback warning
  • packages/cli/src/commands/init.tsPATTERN_TEMPLATES['docs'], isValidPreset
  • packages/cli/src/commands/adf.ts — preset-conditional scaffold in adfInit
  • README.md + packages/cli/README.md — update preset list
  • CHANGELOG.md

Evidence

Full AAR from the onboarding: stackbilt_llc/docs/aar-charter-onboarding.md

{
  "detected": {
    "runtime": [],
    "frameworks": [],
    "confidence": "LOW",
    "suggestedPreset": "fullstack",
    "signals": {
      "hasFrontend": false,
      "hasBackend": false,
      "hasWorker": false,
      "hasCloudflare": false
    }
  }
}

Charter v0.4.2, Node v22.17.0, WSL2/Ubuntu.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions