spec-kitty / spec-kitty/spec-kitty

Default charter mechanism: guide new-project operators to author their own charter.yaml via the interview (no example content scaffolded)

Open
#2,808 1 comment 0 reactions 0 assignees View on GitHub
doctrine enhancement
Dominant language
Python
Stars
1.6k
Forks
165
Avg merge
14h 52m
Merged PRs (30d)
303

Description

Part of #2519 (Epic: Charter authoring & lifecycle robustness).

## Capability

Provide a **default charter mechanism**: a guided, interview-driven path that helps a new-project operator author *their own* project `charter.yaml` — the authoritative, git-tracked governance file — instead of getting pre-baked example governance/assets scaffolded into their repo. The path is built on `spec-kitty charter interview`: answer the question set, and the mechanism helps the operator produce a real, project-specific charter rather than shipping example content they must later delete.

## Why

- The old model **auto-scaffolded example doctrine content into every new project** (e.g. an auto-installed PowerShell toolguide). That example/default content was stale-example debt in consumer repos and was just **removed in PR #2805** (commit `bf7917b43`).
- **#2773** inverted charter authority: `charter.yaml` is now the authoritative, structured, git-tracked resolving source (with `charter.md` as a curated companion reference, never a resolving input). Given that inversion, the right onboarding artifact to help operators produce is *their own* `charter.yaml`, authored deliberately — not example content pushed in by the tool.
- The direction is therefore a shift from **push example content → guide authoring**: replace "scaffold defaults into the user's repo" with "guide the user to author their governance via the interview."

## Who

- **New-project operators** running charter setup on a fresh (or freshly-migrated) repo, who today either inherit example content they must prune, or face a blank `charter.yaml` with no guided on-ramp.

## Intended effect

- A guided, interview-driven path (on top of `spec-kitty charter interview`) that walks an operator from the charter question set to an authored, project-specific `charter.yaml`.
- **No example governance/assets content is scaffolded into user repos** as a side effect of setup — the shipped catalog remains the seed library; the operator's charter is authored, not injected.
- The resulting `charter.yaml` is the single authoritative, git-tracked governance source (per #2773), consistent with the activation surfaces the rest of #2519 hardens.

## Scope guard

Epic-child capability, not an implementation spec. This is deliberately **distinct** from its neighbors under #2519 and should coordinate with, not duplicate, them:

- **#2522** — doctrine-authoring `charter author` scaffold + maintainer how-to (maintainer-facing doctrine-artifact authoring), vs. this issue's new-project charter onboarding.
- **#2521** — charter-init freshness preflight + deterministic intake plumbing (the input-derivation chain), vs. this issue's interview-driven authoring UX.
- **#2657** — provisioned default charter for the *mission-type activation set* (retire the implicit "all built-in" default). Complementary: a fail-closed provisioned baseline can coexist with an interview-guided authoring on-ramp; this issue owns the "author your own, no example content pushed" experience.

## References

- PR #2805 — removed the auto-installed example toolguide (the model this replaces).
- #2773 — charter.yaml authority inversion (authoritative, git-tracked resolving source).
- ADR `docs/adr/3.x/2026-07-15-1-doctrine-offers-charter-activates-runtime-consumes.md` — "all built-in doctrine active by default" retired.

Contributor guide

Open the contributing guide

Research direction

Start with the `spec-kitty charter interview` entry point and read `docs/adr/3.x/2026-07-15-1-doctrine-offers-charter-activates-runtime-consumes.md`, plus the changes described in PR #2805 and issue #2773. Done means a new-project operator can author a project-specific, git-tracked `charter.yaml` through the interview without example governance or assets being scaffolded into the repository.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
cli, developer-experience
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.