From d6d3a775e13fa7544e2f248781ea53cceb879243 Mon Sep 17 00:00:00 2001 From: PChemGuy <39730837+pchemguy@users.noreply.github.com> Date: Thu, 2 Apr 2026 13:40:24 +0300 Subject: [PATCH 01/25] Create DEVELOPMENT.md outline --- DEVELOPMENT.md | 73 ++++ Development Guide Dev/Untitled.md | 364 ++++++++++++++++++ Development Guide Dev/deep-research-report.md | 188 +++++++++ 3 files changed, 625 insertions(+) create mode 100644 DEVELOPMENT.md create mode 100644 Development Guide Dev/Untitled.md create mode 100644 Development Guide Dev/deep-research-report.md diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md new file mode 100644 index 000000000..fbdd5fabc --- /dev/null +++ b/DEVELOPMENT.md @@ -0,0 +1,73 @@ +# Development Guide + +## 1. Purpose + +- Who this document is for +- How it differs from README.md and CONTRIBUTING.md + +## 2. Spec Kit for Maintainers + +- What Spec Kit is internally +- Core workflow it supports +- Main system surfaces + +## 3. System Mental Model +### 3.1 Artifact and workflow lifecycle +### 3.2 Source assets vs generated/project assets +### 3.3 Templates, scripts, CLI, agent integrations, extensions, presets + +## 4. Repository Anatomy +### 4.1 templates/ +### 4.2 scripts/ +### 4.3 CLI/package code +### 4.4 memory assets +### 4.5 extensions/ +### 4.6 presets/ +### 4.7 catalogs and community metadata +### 4.8 top-level docs + +## 5. If You Want to Change X, Edit Y + +- Generated artifact content +- Workflow behavior +- Installation/bootstrap +- Docs +- Extensions +- Presets +- Catalog/community entries + +## 6. Development Workflows +### 6.1 Template changes +### 6.2 Script changes +### 6.3 CLI/bootstrap changes +### 6.4 Docs-only changes +### 6.5 Extension/preset/catalog changes + +## 7. Validation and Testing Map + +- Automated checks +- Manual agent-flow validation +- Packaged-output validation +- When each is needed + +## 8. Documentation Map + +- README.md +- CONTRIBUTING.md +- TESTING.md +- spec-driven.md +- extension/preset publishing docs +- changelog/release docs + +## 9. Architectural Invariants + +- Workflow consistency +- Cross-agent compatibility +- Docs/templates alignment +- Packaging/scaffolding integrity + +## 10. Common Pitfalls + +## 11. Release and Compatibility Notes + +## 12. Maintainer Onboarding Checklist diff --git a/Development Guide Dev/Untitled.md b/Development Guide Dev/Untitled.md new file mode 100644 index 000000000..761bacda7 --- /dev/null +++ b/Development Guide Dev/Untitled.md @@ -0,0 +1,364 @@ +Yes, it makes sense. + +A top-level `DEVELOPMENT.md` is a good fit here because the current `README.md` is clearly optimized for users adopting Spec Kit in projects, while `CONTRIBUTING.md` is narrower: contribution mechanics, validation flow, and PR hygiene. It is not really a full developer mental-model document. The repo also already has specialized docs like `TESTING.md`, the extension publishing guide, and preset publishing guide, which means a developer-facing entry document should primarily orient, map, and route rather than duplicate details. ([GitHub][1]) + +I would treat `DEVELOPMENT.md` as the **developer map of the system**: + +* what Spec Kit is internally, +* how the repository is organized, +* how the main moving parts interact, +* where to edit for each class of change, +* how to validate changes, +* and where deeper docs live. + That is the missing layer between user docs and contribution rules. ([GitHub][1]) + +## What `DEVELOPMENT.md` should do + +It should not try to be: + +* another `README.md`, +* another `CONTRIBUTING.md`, +* or a giant reference manual. + +It should be the **primary entry point for maintainers and contributors who need system understanding before editing**. + +The right emphasis is: + +1. mental model, +2. repository anatomy, +3. change workflows, +4. document map, +5. common modification scenarios. + +That is especially important in this repo because the core is not just Python code; it is a coordinated kit of templates, scripts, CLI behavior, agent integrations, memory files, extensions, presets, and documentation. The current docs already imply this multi-part system, but they are distributed across several places. ([GitHub][2]) + +## Recommended top-level structure + +Here is the outline I would use. + +### 1. Purpose of this document + +Very short. Explain that: + +* `README.md` is for users adopting Spec Kit, +* `DEVELOPMENT.md` is for people modifying Spec Kit itself, +* `CONTRIBUTING.md` covers contribution process and PR expectations, +* deeper component docs are linked below. ([GitHub][2]) + +### 2. What Spec Kit is, from a maintainer perspective + +Give a concise internal framing, for example: + +* Spec Kit is a toolkit for Spec-Driven Development. +* The repo packages prompts/templates, command scaffolding, scripts, CLI support, agent-specific integration assets, and ecosystem mechanisms such as extensions and presets. +* The generated user workflow is roughly: constitution → specify → plan → tasks → implement. ([GitHub][1]) + +This section should answer: **what are we actually maintaining?** + +### 3. System mental model + +This is one of the most important sections. + +Suggested subsections: + +* **Core artifact flow** + How the main SDD flow progresses through constitution, specification, plan, tasks, implementation. ([GitHub][1]) +* **Delivery model** + Clarify what lives in the repo versus what gets installed/scaffolded into user projects. +* **Main abstraction layers** + For example: + + * templates/content, + * command scaffolding, + * CLI/bootstrap/install logic, + * agent-specific integration surfaces, + * extension/preset ecosystem, + * docs/catalog/community surfaces. + +A simple diagram would help a lot here. + +### 4. Repository anatomy + +This should be a guided map, not just a tree dump. + +For each major top-level area, explain: + +* what it contains, +* why it exists, +* when to edit it, +* what else it interacts with. + +You already mentioned this, and yes, it should absolutely be included. + +Likely subsections: + +* `templates/` — core artifact templates and command templates; probably the most important content layer for generated workflow behavior. The repo README and contribution workflow both point contributors to template validation. ([GitHub][2]) +* `scripts/` — automation/bootstrap/helper scripts; `CONTRIBUTING.md` explicitly calls out script functionality as something contributors should test. ([GitHub][2]) +* `memory/` or `.specify/memory`-related assets — constitution/project-memory behavior; contribution guidance explicitly references `memory/constitution.md` updates for major process changes. ([GitHub][2]) +* CLI/package code — where install/scaffold behavior and local `specify` execution live. +* `extensions/` — extension model and publishing support; the repo includes a dedicated extension publishing guide. ([GitHub][3]) +* `presets/` — preset model and publishing support; there is also a dedicated presets publishing guide. ([GitHub][4]) +* catalogs/community metadata — where ecosystem discoverability is maintained; the README includes community extensions, presets, walkthroughs, and related ecosystem surfaces. ([GitHub][5]) +* top-level docs — which are user docs, contributor docs, testing docs, release docs, etc. + +### 5. “If you want to change X, edit Y” + +This is the most practical section, and many repos miss it. + +Examples: + +* To change the wording/structure of generated feature specs → edit relevant template files. +* To change slash-command behavior or workflow sequencing → inspect command templates plus any supporting scripts/CLI glue. +* To change installation/bootstrap behavior → inspect CLI/package/bootstrap code. +* To add or modify extension publishing behavior → see `extensions/EXTENSION-PUBLISHING-GUIDE.md`. +* To add or modify presets behavior → see `presets/PUBLISHING.md`. +* To adjust docs shown to end users → update `README.md` and possibly `spec-driven.md`, which `CONTRIBUTING.md` explicitly names for user-facing changes. ([GitHub][2]) + +This section makes the doc operational instead of descriptive. + +### 6. End-to-end development workflows + +Not contribution policy in the abstract, but concrete developer workflows. + +Suggested subsections: + +* **Template change workflow** +* **Script change workflow** +* **CLI/bootstrap change workflow** +* **Docs-only workflow** +* **Extension/preset/catalog change workflow** + +For each: + +* where to edit, +* how to test locally, +* what docs to update, +* what regressions to watch for. + +This aligns well with the current contribution guidance, which already says to test CLI commands in an agent, verify templates in `templates/`, test scripts in `scripts/`, and update memory/docs where relevant. ([GitHub][2]) + +### 7. Validation and testing map + +Do not restate all of `TESTING.md`. Instead, summarize the validation layers and link outward. + +Suggested structure: + +* quick local checks, +* focused automated checks, +* manual workflow tests in real agents, +* packaging/release-output validation, +* when each level is required. + +This matches the current recommended validation flow in `CONTRIBUTING.md`, which points developers to focused automated checks first, then manual workflow tests, then local release package inspection when needed. ([GitHub][2]) + +### 8. Documentation map + +This should be explicit and curated. + +A table works well: + +| Document | Audience | Purpose | When to read | +| -------- | -------- | ------- | ------------ | + +Include at least: + +* `README.md` +* `CONTRIBUTING.md` +* `TESTING.md` +* `spec-driven.md` +* `extensions/EXTENSION-PUBLISHING-GUIDE.md` +* `presets/PUBLISHING.md` +* maybe `CHANGELOG.md` and release-related docs if relevant. ([GitHub][2]) + +This section is especially valuable because the repo’s documentation surface has grown. + +### 9. Architectural invariants / guardrails + +This is another high-value section. + +List the things maintainers should preserve, such as: + +* user workflow consistency across supported agents, +* template and script changes should remain compatible with the expected SDD flow, +* generated artifacts and packaging should remain coherent, +* docs and templates must stay aligned, +* agent-specific adaptations should not silently break the general model. + +These should be framed as maintainer guardrails, not as vague philosophy. The README’s emphasis on the standard workflow and the contribution doc’s insistence on testing the CLI workflow with real agents strongly suggest this kind of invariant section is warranted. ([GitHub][1]) + +### 10. Common pitfalls + +Very useful for new contributors. + +Examples: + +* changing a template without validating it through an actual agent flow, +* updating docs but not generated behavior, +* changing workflow semantics without updating memory/process docs, +* forgetting ecosystem/catalog impact, +* testing only source form but not packaged output. ([GitHub][2]) + +### 11. Release-awareness and compatibility notes + +Brief section only. + +Could cover: + +* generated assets vs source assets, +* keeping changes compatible across agent modes, +* watching changelog/release behavior, +* any versioning expectations for templates/extensions/presets where applicable. ([GitHub][6]) + +### 12. Getting started as a maintainer + +A compact onboarding checklist: + +* read this document, +* read `CONTRIBUTING.md`, +* read `TESTING.md`, +* inspect repository layout, +* run local install, +* run representative workflow tests, +* make a narrow change first. + +## What else to include beyond your current idea + +Your instinct is right, but I would add four things that are easy to overlook: + +### A. A maintainer mental model, not just repository overview + +Without this, the document becomes a directory tour. + +The key question is: +**How do templates, scripts, CLI/bootstrap, docs, and ecosystem surfaces combine to produce the user experience?** + +That is the real “developer README”. + +### B. Change-oriented guidance + +The “if you want to change X, edit Y” section is disproportionately valuable. + +It reduces contributor hesitation and prevents wrong-entry-point edits. + +### C. Invariants / non-obvious rules + +These are the things experienced maintainers know but new contributors do not. + +For Spec Kit, that likely includes preserving the workflow sequence and validating changes in real agent flows rather than treating the repo as ordinary static docs. ([GitHub][2]) + +### D. A curated doc index + +Not a raw list of files. A role-based map. + +That is what turns scattered documentation into an actual developer entry point. + +## What not to do + +I would avoid: + +* duplicating installation instructions from `README.md`, +* duplicating PR policy from `CONTRIBUTING.md`, +* duplicating detailed test procedures from `TESTING.md`, +* documenting every file, +* writing a long historical narrative. + +`DEVELOPMENT.md` should stay navigational and architectural. + +## Suggested section order + +If you want a clean final shape, I would order it like this: + +1. Purpose of this document +2. Spec Kit at a glance for maintainers +3. System mental model +4. Repository anatomy +5. Change map: if you want to change X, edit Y +6. Development workflows +7. Validation and testing map +8. Documentation map +9. Architectural invariants and guardrails +10. Common pitfalls +11. Release and compatibility notes +12. Maintainer onboarding checklist + +## My recommendation on naming + +`DEVELOPMENT.md` is a reasonable name here. It is more natural than `README_DEV.md`. + +`README_DEV.md` is understandable, but it feels slightly ad hoc. `DEVELOPMENT.md` reads like a first-class top-level maintainer document and pairs well with `README.md`, `CONTRIBUTING.md`, `TESTING.md`, and `CHANGELOG.md`. That naming style is also consistent with the repo already having specialized top-level docs rather than overloading a second README. ([GitHub][2]) + +## A compact draft outline you can start from + +```md +# Development Guide + +## 1. Purpose +- Who this document is for +- How it differs from README.md and CONTRIBUTING.md + +## 2. Spec Kit for Maintainers +- What Spec Kit is internally +- Core workflow it supports +- Main system surfaces + +## 3. System Mental Model +### 3.1 Artifact and workflow lifecycle +### 3.2 Source assets vs generated/project assets +### 3.3 Templates, scripts, CLI, agent integrations, extensions, presets + +## 4. Repository Anatomy +### 4.1 templates/ +### 4.2 scripts/ +### 4.3 CLI/package code +### 4.4 memory assets +### 4.5 extensions/ +### 4.6 presets/ +### 4.7 catalogs and community metadata +### 4.8 top-level docs + +## 5. If You Want to Change X, Edit Y +- Generated artifact content +- Workflow behavior +- Installation/bootstrap +- Docs +- Extensions +- Presets +- Catalog/community entries + +## 6. Development Workflows +### 6.1 Template changes +### 6.2 Script changes +### 6.3 CLI/bootstrap changes +### 6.4 Docs-only changes +### 6.5 Extension/preset/catalog changes + +## 7. Validation and Testing Map +- Automated checks +- Manual agent-flow validation +- Packaged-output validation +- When each is needed + +## 8. Documentation Map +- README.md +- CONTRIBUTING.md +- TESTING.md +- spec-driven.md +- extension/preset publishing docs +- changelog/release docs + +## 9. Architectural Invariants +- Workflow consistency +- Cross-agent compatibility +- Docs/templates alignment +- Packaging/scaffolding integrity + +## 10. Common Pitfalls + +## 11. Release and Compatibility Notes + +## 12. Maintainer Onboarding Checklist +``` + +This is the structure I would use unless you want `DEVELOPMENT.md` to be intentionally shorter and more of a “developer landing page” that links out aggressively. + +I can turn this into a concrete first-pass `DEVELOPMENT.md` skeleton with section text, not just the outline. diff --git a/Development Guide Dev/deep-research-report.md b/Development Guide Dev/deep-research-report.md new file mode 100644 index 000000000..c81ff9acb --- /dev/null +++ b/Development Guide Dev/deep-research-report.md @@ -0,0 +1,188 @@ +# Deep research on Spec Kit development documentation coverage + +## Executive summary + +The GitHub github/spec-kit repository does contain **meaningful developer-oriented documentation** that explains *how templates fit into Spec Kit’s workflow*—especially in the main README.md, the DocFX-backed docs/ site sources, AGENTS.md, and the preset system documentation (presets/README.md \+ presets/ARCHITECTURE.md). These sources provide a workable mental model for the **Spec‑Driven Development (SDD) lifecycle**, and for **template resolution / overrides** (core vs extensions vs presets vs project overrides). + +However, the repository does **not** appear to contain a **single, systematic, developer-facing “Template System” guide** that (a) enumerates **every file under templates/**, (b) explains each one’s role in the pipeline, and (c) provides **glue/jump-start guidance** for maintainers (how to safely modify templates, keep scripts and command prompts aligned, and test changes end-to-end). The absence of an index/README inside templates/ and multiple “path confusion” / “template behavior confusion” issues suggest the mental model is dispersed and easy to miss. + +## Inventory and analysis of templates/ + +### Directory structure overview + +At the time of review (repo main), templates/ contains 7 top-level assets plus a commands/ subdirectory with 9 command templates (total: 16 files). + +### Table of all files under templates/ + +The “Developer-oriented guidance?” column below is strictly about **human-developer onboarding/mental model** content *inside the file itself* (as opposed to “LLM-facing instructions that a developer could reverse-engineer”). Many of these files primarily serve as **prompt directives/templates** for agents, which is useful but not the same as curated developer documentation. + +| File (path) | Purpose (what it is for) | Type | Developer-oriented guidance inside file? | +| :---------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------: | :--------------------------------------------------------------------------------------------------------------------------------------- | +| templates/agent-file-template.md | Skeleton for a generated “Development Guidelines” / agent context file (placeholders for technologies, structure, commands, recent changes, plus a manual-additions region). | md | **Partial**: structure \+ placeholders; minimal “why/how.” | +| templates/checklist-template.md | Output template for checklist artifacts; explicitly notes generation by /speckit.checklist and includes a large **“sample items must be replaced”** instruction block. | md | **Yes (light)**: explains it is command-generated and warns not to keep sample items. | +| templates/constitution-template.md | Placeholder constitution format (principles, governance, version metadata) with inline examples in comments. | md | **Partial**: examples hint at intent; not a full maintainer guide. | +| templates/plan-template.md | Output template for a feature’s implementation plan and design artifacts; includes “technical context,” constitution gate, project structure, and phased deliverables. It states it’s filled by /speckit.plan. | md | **Yes (moderate)**: contains “ACTION REQUIRED” guidance and process structure, but mostly LLM/task-facing rather than maintainer-facing. | +| templates/spec-template.md | Output template for feature specifications (user stories, acceptance scenarios, requirement structure). Includes strong guidance on testable, prioritized stories. | md | **Yes (moderate)**: good guidance for spec authors; still not a “template system” doc. | +| templates/tasks-template.md | Output template for actionable task lists; includes prerequisites, path conventions, parallelization strategy, and “sample tasks must be replaced” warnings. | md | **Yes (high)**: substantial operational guidance for task authoring and organization. | +| templates/vscode-settings.json | VS Code settings enabling prompt file recommendations for speckit.\* and auto-approving terminal tools in .specify/scripts/\*\*. | data (json) | **No**: configuration only; no explanatory doc text. | +| templates/commands/analyze.md | Command prompt for /speckit.analyze: read-only cross-artifact consistency/quality pass (spec/plan/tasks), driven via prerequisite script outputs. | md | **Yes (moderate)**: documents what analysis does and constraints; still “agent instruction.” | +| templates/commands/checklist.md | Command prompt for /speckit.checklist: frames checklists as “unit tests for requirements writing” and clarifies what they’re *not* (not implementation verification). | md | **Yes (high)**: contains a clear mental model and usage framing. | +| templates/commands/clarify.md | Command prompt for /speckit.clarify: targeted clarification questions, completion before planning, and a handoff to /speckit.plan. | md | **Yes (moderate)**: documents where clarify fits and why. | +| templates/commands/constitution.md | Command prompt for /speckit.constitution: fill constitution template and propagate changes to dependent artifacts; includes explicit note about .specify/memory/constitution.md and initialization from templates. | md | **Yes (moderate)**: provides maintainer-relevant propagation expectations. | +| templates/commands/implement.md | Command prompt for /speckit.implement: execute tasks, check checklists, apply extension hooks, and enforce safety constraints (secrets patterns, etc.). | md | **Yes (moderate)**: good operational constraints; not an architecture guide. | +| templates/commands/plan.md | Command prompt for /speckit.plan: sets up plan workflow using scripts; includes handoffs to tasks and checklist; references loading templates copied into place. | md | **Yes (moderate)**: explains sequencing and handoffs. | +| templates/commands/specify.md | Command prompt for /speckit.specify: create/update feature spec from natural language; handoffs to plan and clarify; calls create-new-feature script. | md | **Yes (moderate)**: explains behavior and chaining. | +| templates/commands/tasks.md | Command prompt for /speckit.tasks: generate tasks from design artifacts; handoffs to analyze \+ implement; uses prerequisite scripts. | md | **Yes (moderate)**: describes role in lifecycle. | +| templates/commands/taskstoissues.md | Command prompt for converting tasks into GitHub issues; includes issue\_write tool usage and explicit guardrails to only act on matching GitHub remotes. | md | **Yes (light)**: explains constraints; minimal broader context. | + +### What the templates collectively imply as a mental model + +Across the command templates (templates/commands/\*.md) and artifact templates (\*-template.md), a consistent implied model emerges: + +* **Commands** (specify/clarify/plan/tasks/analyze/implement/checklist/…) define *procedures \+ guardrails* for an AI agent. Many include prerequisite scripts, expected inputs/outputs, and optional handoffs to the next command. +* **Templates** (spec-template.md, plan-template.md, tasks-template.md, etc.) define *artifact structure* and embed quality constraints (e.g., “replace sample tasks,” “prioritized, independently testable user stories”). +* Some files mix guidance roles (e.g., tasks-template.md doubles as a playbook for parallelization and incremental delivery). + +This is strong “operational documentation,” but it is **not packaged as a maintainer-facing, systematic explanation of the template system**. + +## Repository documentation that explains templates for developers + +### Core docs that supply “glue” and a developer mental model + +The repository’s main README.md explains key “template system” concepts in a developer-friendly way: + +* It describes a **priority stack** for template resolution with a Mermaid diagram and explicitly states that templates are resolved at runtime (highest-priority match wins), while commands are applied at install time. +* It also shows example project directory structures and demonstrates where templates live after initialization (under .specify/templates/ in the user project). + +The DocFX-backed docs/ content includes: + +* A quickstart that describes the end-to-end **6-step workflow** (init → constitution → specify → clarify → plan → tasks → implement) and emphasizes **“context awareness”** via active feature detection (branch-based). +* Installation and upgrade guidance that clarifies what “project files” get refreshed (commands, scripts, templates, memory) versus what is “safe” (specs/ and code), and explicitly discusses .specify/templates/ as upgrade-targeted infrastructure. +* Local development instructions for iterating on the CLI without release publishing, including running via python \-m src.specify\_cli and uvx \--from .. +* The docs/README.md indicates docs are built via DocFX and deployed to GitHub Pages. + +AGENTS.md is a maintainer-oriented guide that explains how agent integrations work (directory conventions, command formats, argument placeholders) and gives a step-by-step procedure for adding support for new tools/agents. + +### Presets / extensions documentation that clarifies template customization + +The repository contains a fairly systematic explanation of template customization mechanics in the **preset system** docs: + +* presets/README.md defines presets as priority-ordered overrides for templates and commands, explains runtime template resolution vs install-time command registration, and documents specify preset resolve for tracing resolution. +* presets/ARCHITECTURE.md goes deeper: it includes Mermaid diagrams for template resolution and command registration, and explicitly lists the multiple implementations (Python \+ Bash \+ PowerShell) to keep behavior consistent. +* The extensions system docs and publishing guide define expected repo structures and strongly encourage extension documentation quality (README structure, command documentation, etc.). + +This preset documentation is the closest thing in-repo to a “template architecture doc,” but it is **scoped to presets** rather than the canonical templates/ directory inventory. + +## Issues, pull requests, and discussions that surface documentation gaps + +A recurring theme in repo activity is **path confusion** and missing “single source of truth” documentation for where templates/commands/scripts “should live” and how they relate (repo-internal templates/ vs installed .specify/templates/). + +### Repeated path and structure confusion + +* Some users flagged incorrect or confusing path references from templates to command files, e.g., plan-template.md referencing a .specify/templates/commands/... path that didn’t match expectations. +* Multiple issues question whether templates and scripts should refer to /templates/... vs /.specify/templates/..., and whether specs belong under .specify/specs/ or at repo root—indicating onboarding/docs ambiguity and drift. + +### Template mutability and “who is allowed to edit what” + +* A reported behavior: an agent (Codex CLI) modified files in .specify/templates during /speckit.constitution, even though templates were expected to remain base assets only updated on init/upgrade. This is a classic “mental model mismatch” symptom: users lack explicit, enforced rules (and docs) about mutability boundaries. + +### “How do I test template changes?” as a maintainership pain point + +* A maintainer/dev workflow issue: local modifications to templates/commands/\*.md and scripts were “ignored” because init flows pulled templates from releases (at least in the reported environment), making it hard to validate changes without publishing. + +### Explicit calls for onboard-oriented guidance + +* Issue \#295 explicitly proposes onboarding improvements (tour, quick reference, diagram) to reinforce the Specify → Plan → Tasks sequence and discourage users from running later steps out of order. + +### PR signals related to templates as a customizable surface + +* PR \#1466 (open as viewed) proposes removing branch-numbering logic from a template and adding a \--template-repo option to specify init so users can pull templates from a fork—an implicit acknowledgement that templates are a customization surface that benefits from better “how to modify safely” documentation. +* PR \#1987 (open as viewed) is nominally a docs rename, but the “files changed” view indicates it includes functional modifications related to template format selection (“compact” templates). Even the existence of a “compact format” notion increases the need for a single, coherent template developer guide. +* Recent/active issues discuss template resolution improvements (e.g., adding resolver/source attribution for extension templates). + +## Gaps in systematic developer-oriented documentation + +### Missing “one-stop” index for template assets + +The repository has strong building blocks (command templates that describe their behavior; a README that explains resolution stacks; preset architecture docs). But there is no central document that answers, in one place: + +* *What are all template files and command templates?* (Inventory \+ purpose) +* *Which ones are inputs vs outputs?* (What gets copied into a project vs generated as feature artifacts) +* *Which scripts and CLI operations touch which files?* +* *What is “safe to edit,” when, and by whom?* (Human vs agent vs init/upgrade) +* *How to test a template change end-to-end without publishing a release?* + +The lack of such a doc is consistent with the volume of issues asking where assets belong and how tooling should interpret them. + +### “Developer-oriented” guidance is embedded, but mostly LLM-facing + +Many template/command files contain substantial guidance, but it is largely phrased as **agent instructions** (MUST/SHOULD), not as curated maintainer documentation. That’s helpful for reverse engineering, yet brittle as onboarding material—particularly when paths or assumptions drift. + +Concrete example: tasks-template.md is rich in operational guidance but serves primarily as *an output template \+ generator contract*, not a doc explaining how to evolve the template system. + +## Recommendations for documentation to add + +### Add a maintainer-facing “Template System” guide + +A strong candidate is docs/templates.md (and link it from docs/index.md \+ root README), or a templates/README.md plus a doc-site page. The doc should explicitly bridge: + +* repo templates/\*\* (source of truth) +* installed .specify/templates/\*\* (copied into projects) +* generated specs/\/\*.md artifacts (outputs) + +**Proposed outline** + +* Purpose of templates vs commands vs scripts vs memory +* Full inventory of templates/ (auto-generate this table in CI to prevent drift) +* Artifact lifecycle: what every /speckit.\* reads/writes +* Mutability rules: what agents may edit vs what must remain stable +* Path conventions and historical migrations (templates/ → .specify/templates/) +* Testing workflow for template changes (local, without publishing) + +**Example content snippet (illustrative)** + +``` +## Template roles + +- templates/*-template.md: base artifact formats copied into .specify/templates/ +- templates/commands/*.md: agent command procedures installed into agent-specific folders +- scripts/**: runtime glue (select active feature, copy templates, update agent context) +``` + +### Add a Mermaid “project structure + flow” diagram set + +The repo already uses Mermaid for template/preset diagrams; extend that style to make the *full pipeline* obvious. + +Suggested diagrams to include (and where) + +* In docs/quickstart.md (or a new docs/how-it-works.md): + * **SDD lifecycle flowchart**: constitution → specify → clarify → plan → tasks → analyze/checklist → implement → taskstoissues +* In the proposed template guide: + * **File I/O map**: each command node lists inputs/outputs (e.g., clarify reads spec.md, writes clarifications back; plan reads spec.md \+ constitution, writes plan.md \+ design docs; tasks reads plan.md \+ artifacts, writes tasks.md). +* In the preset/extension docs (already present): + * Keep the **template resolution stack**, but cross-link to the main template guide. + +### Add a “Template change checklist” for contributors + +Given recurring drift issues, introduce a short checklist (either in CONTRIBUTING.md or a dedicated doc) that enforces cross-asset consistency: + +* If you change spec-template.md, confirm: + * templates/commands/specify.md instructions remain aligned + * templates/commands/clarify.md taxonomy still matches spec sections +* If you change template paths or structure: + * update Bash + PowerShell scripts consistently (and the preset resolver references, if applicable) + * Add “Docs impact” section: update docs/upgrade.md and docs/quickstart.md if user-facing behavior changed. + +### Add “How to test template/command changes locally” documentation + +Augment docs/local-development.md with a template-focused section that addresses the reported pain: + +* How to run the CLI from source (python \-m src.specify\_cli ...) +* How to initialize a sandbox project using local assets +* How to validate that the sandbox project is using your modified templates/commands/scripts +* How to run a minimal “golden path” (specify → plan → tasks) to ensure nothing breaks + +This would directly address the workflow gap implied by “local changes ignored” reports. + +--- + From 5fa5a882c5876b09bc6fa94a57410529981bc0e9 Mon Sep 17 00:00:00 2001 From: PChemGuy <39730837+pchemguy@users.noreply.github.com> Date: Thu, 2 Apr 2026 13:57:34 +0300 Subject: [PATCH 02/25] AI-generated DEVELOPMENT.md draft --- DEVELOPMENT.md | 493 +++++++++++++++++++++++++--- Development Guide Dev/Untitled 1.md | 458 ++++++++++++++++++++++++++ 2 files changed, 897 insertions(+), 54 deletions(-) create mode 100644 Development Guide Dev/Untitled 1.md diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index fbdd5fabc..4454c598d 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -1,73 +1,458 @@ # Development Guide -## 1. Purpose +This document is the primary entry point for people modifying Spec Kit itself. -- Who this document is for -- How it differs from README.md and CONTRIBUTING.md +Use this guide when you need to understand how the repository fits together, where different kinds of changes belong, how to validate them, and which deeper documents to read next. -## 2. Spec Kit for Maintainers +## Relationship to Other Top-Level Documents -- What Spec Kit is internally -- Core workflow it supports -- Main system surfaces +Spec Kit has several top-level documents with different roles. They should not duplicate each other. -## 3. System Mental Model -### 3.1 Artifact and workflow lifecycle -### 3.2 Source assets vs generated/project assets -### 3.3 Templates, scripts, CLI, agent integrations, extensions, presets +- `README.md` is the primary entry point for users adopting Spec Kit in a project. +- `DEVELOPMENT.md` is the primary entry point for contributors and maintainers changing Spec Kit itself. +- `CONTRIBUTING.md` defines contribution mechanics, review expectations, and required development practices. +- `TESTING.md` describes validation strategy and testing procedures in more detail. +- Other specialized documents cover specific subsystems or publishing workflows. -## 4. Repository Anatomy -### 4.1 templates/ -### 4.2 scripts/ -### 4.3 CLI/package code -### 4.4 memory assets -### 4.5 extensions/ -### 4.6 presets/ -### 4.7 catalogs and community metadata -### 4.8 top-level docs +This document is intentionally focused on system understanding, repository navigation, and change workflows. -## 5. If You Want to Change X, Edit Y +## What Spec Kit Is, from a Maintainer Perspective -- Generated artifact content -- Workflow behavior -- Installation/bootstrap -- Docs -- Extensions -- Presets -- Catalog/community entries +Spec Kit is a toolkit for spec-driven development. It provides a structured workflow, scaffolding assets, and supporting integrations that help users move from an idea to a defined specification, an implementation plan, task breakdowns, and executable project work. -## 6. Development Workflows -### 6.1 Template changes -### 6.2 Script changes -### 6.3 CLI/bootstrap changes -### 6.4 Docs-only changes -### 6.5 Extension/preset/catalog changes +From a maintainer perspective, the repository is not just "documentation" and not just "code". It is a coordinated system composed of several interacting surfaces: -## 7. Validation and Testing Map +- workflow-defining templates, +- command and scaffolding assets, +- scripts and automation helpers, +- CLI and installation behavior, +- agent-specific integration surfaces, +- extension and preset publishing assets, +- documentation that explains and stabilizes the user and developer model. -- Automated checks -- Manual agent-flow validation -- Packaged-output validation -- When each is needed +Maintaining Spec Kit means preserving coherence across those surfaces. A change in one layer often affects documentation, validation expectations, and user-visible workflow behavior in other layers. -## 8. Documentation Map +## System Mental Model -- README.md -- CONTRIBUTING.md -- TESTING.md -- spec-driven.md -- extension/preset publishing docs -- changelog/release docs +### Core User Workflow -## 9. Architectural Invariants +At a high level, Spec Kit supports a staged workflow in which a user moves through structured project definition and execution steps. The exact implementation details may vary by agent or integration surface, but the core conceptual flow is consistent: -- Workflow consistency -- Cross-agent compatibility -- Docs/templates alignment -- Packaging/scaffolding integrity +1. establish or refine governing project principles, +2. define a concrete specification, +3. derive an implementation plan, +4. derive an actionable task breakdown, +5. execute implementation against the defined artifacts. -## 10. Common Pitfalls +When changing Spec Kit, first identify which part of that lifecycle your change affects. -## 11. Release and Compatibility Notes +### Source Assets vs Generated Project Assets -## 12. Maintainer Onboarding Checklist +A useful distinction for maintainers is the difference between: + +- **source assets in this repository**, and +- **artifacts that users consume in their own repositories or agent sessions**. + +Source assets in this repository define behavior, structure, wording, conventions, and scaffolding rules. Generated or installed assets are the user-facing outputs of those source assets. + +When editing repository files, think in terms of downstream consequences: + +- What will change in the user-visible workflow? +- What will change in generated project content? +- What must be revalidated manually in a real end-to-end flow? + +### Main System Surfaces + +Most changes fall into one or more of these surfaces: + +- **Templates**: define workflow artifacts, prompts, scaffolding content, and generated project structure. +- **Scripts and automation**: support local generation, packaging, installation, or validation flows. +- **CLI and bootstrap behavior**: define how users initialize, install, or execute Spec Kit workflows. +- **Agent integration surfaces**: adapt the kit to specific agent environments without changing the underlying workflow intent. +- **Extensions and presets**: package additional reusable behavior or opinionated configurations. +- **Documentation**: explain the intended model, workflow, usage, and maintenance practices. + +A contributor should be able to identify which surface they are editing before making a change. + +## Repository Anatomy + +This section explains the role of the major repository areas. It is intended as a guided map, not a full file inventory. + +### `templates/` + +This directory contains the core workflow and content assets that shape the user experience. In many cases, this is the most important part of the repository because it defines the structure and wording of the spec-driven workflow itself. + +Edit `templates/` when you are changing: + +- generated artifact structure, +- workflow prompt wording, +- command or template content, +- default project scaffolding semantics. + +Treat template changes as behavior changes, not as passive documentation edits. Even small text changes can alter how users and agents interpret the workflow. + +### `scripts/` + +This directory contains automation and helper logic used for validation, packaging, generation, or related maintenance tasks. + +Edit `scripts/` when you are changing: + +- automation that supports local development, +- packaging or build helpers, +- maintenance utilities, +- validation support logic. + +Script changes should be validated both for local correctness and for their role in the broader development workflow. + +### CLI and Package Code + +Where applicable, repository code for installation, bootstrap, packaging, or command execution defines how Spec Kit is delivered and invoked. + +Edit the CLI or package code when you are changing: + +- installation behavior, +- initialization flow, +- local command behavior, +- execution semantics exposed to users. + +Changes here are usually high-impact because they affect how users enter the system. + +### Memory and Governing Assets + +Some repository assets define persistent project conventions, constitutions, or other workflow-governing content. + +Edit these assets when you are changing: + +- core workflow assumptions, +- project constitution defaults, +- stable behavioral expectations carried across the kit. + +These changes often require corresponding documentation updates because they affect the conceptual model, not just wording. + +### `extensions/` + +This area supports extension mechanisms and related publishing flows. + +Edit `extensions/` when you are: + +- adding a new extension, +- modifying extension behavior, +- updating extension packaging or publishing guidance. + +Extension changes should preserve compatibility with the main Spec Kit model unless the extension is explicitly intended to be a bounded deviation. + +### `presets/` + +This area supports reusable preset configurations and their publishing workflows. + +Edit `presets/` when you are: + +- adding a new preset, +- changing how presets are defined, +- updating preset publishing or maintenance logic. + +Presets should remain understandable as opinionated selections layered on top of the core workflow, not as silent redefinitions of that workflow. + +### Documentation Surface + +Top-level and subsystem documentation explains the user model, maintainer model, testing expectations, and publishing flows. + +Edit documentation whenever code, templates, scripts, or workflow semantics change in a way that affects: + +- user understanding, +- contributor understanding, +- validation expectations, +- extension or preset author behavior. + +Do not treat docs as an afterthought. In Spec Kit, documentation is part of the product surface. + +## Change Map: If You Want to Change X, Edit Y + +This section is a practical routing guide. Use it before making edits. + +### Change generated specification or planning content + +Start with the relevant files under `templates/`. + +Typical examples: + +- generated spec wording, +- plan structure, +- task generation wording, +- default scaffolded project artifacts. + +### Change workflow behavior or sequencing + +Inspect the relevant templates first, then any supporting script or CLI logic that participates in workflow execution. + +Typical examples: + +- command flow changes, +- stage ordering changes, +- added or removed workflow steps, +- changes in how generated assets reference one another. + +### Change installation or bootstrap behavior + +Inspect CLI or package code, install helpers, and any supporting scripts involved in setup or initialization. + +Typical examples: + +- init behavior, +- install commands, +- local executable behavior, +- package layout expectations. + +### Change user-facing documentation + +Update `README.md` and any other user-facing docs affected by the change. If the workflow model changes, also update any supporting conceptual documentation so the documented model remains aligned with actual behavior. + +### Change contributor-facing guidance + +Update `DEVELOPMENT.md`, `CONTRIBUTING.md`, `TESTING.md`, or more specialized contributor documentation as appropriate. + +### Change extension behavior or extension publishing + +Start in `extensions/` and then update related publishing guidance and any ecosystem references. + +### Change preset behavior or preset publishing + +Start in `presets/` and then update related publishing guidance and any ecosystem references. + +### Change system-wide conceptual assumptions + +Treat the change as cross-cutting. Review templates, governing assets, docs, validation expectations, and any affected packaging or integration surfaces together. + +## Development Workflows + +This section describes the normal paths for common kinds of changes. + +### Template Change Workflow + +Use this workflow when changing prompt content, generated artifact structure, or other template-defined behavior. + +1. Identify the exact user-visible behavior that should change. +2. Locate the relevant template files. +3. Make the smallest coherent change that expresses the intended behavior. +4. Review adjacent templates for consistency. +5. Update documentation if the conceptual or visible behavior changed. +6. Validate the change through focused checks and at least one realistic end-to-end flow. + +For template changes, wording is behavior. Treat wording edits with the same care as code changes. + +### Script Change Workflow + +Use this workflow when changing repository automation or support utilities. + +1. Identify the workflow that depends on the script. +2. Edit the relevant script with minimal scope. +3. Validate the script directly. +4. Validate the higher-level workflow that depends on it. +5. Update docs if the script changes how contributors or users are expected to work. + +### CLI or Bootstrap Change Workflow + +Use this workflow when changing how users enter or operate Spec Kit through commands or package installation. + +1. Identify the affected command or entry path. +2. Trace the code and any related templates or scripts. +3. Make the change with attention to backward compatibility and user expectations. +4. Validate the affected command locally. +5. Validate at least one realistic user entry flow end to end. +6. Update user-facing and developer-facing docs as needed. + +### Docs-Only Workflow + +Use this workflow when making documentation changes that do not intentionally alter behavior. + +1. Confirm that the change is actually documentation-only. +2. Update the relevant docs. +3. Check for overlap with other docs that may now be inconsistent. +4. Ensure terminology remains aligned across documents. + +Be cautious: many apparent "docs-only" changes in this repository are actually behavioral if they describe workflow semantics that templates or scripts already implement. + +### Extension or Preset Workflow + +Use this workflow when changing extension or preset assets. + +1. Identify whether the change affects the core model or only the extension/preset layer. +2. Edit the relevant extension or preset files. +3. Validate packaging, discoverability, and usage expectations. +4. Update publishing and maintenance guidance where needed. +5. Ensure the relationship to core Spec Kit remains explicit. + +## Validation and Testing Map + +This section is a routing summary. For detailed procedures, see `TESTING.md` and related validation documentation. + +### Focused Local Validation + +Use focused validation first when changing a narrow part of the system. + +Examples include: + +- validating the specific template you changed, +- running the script you modified, +- exercising the CLI path you edited, +- checking a packaging or publishing path affected by your change. + +### End-to-End Workflow Validation + +Use realistic manual validation when the change affects user-visible workflow semantics. + +This is especially important for: + +- template changes, +- command flow changes, +- initialization or bootstrap changes, +- agent-facing workflow changes. + +A change is not well validated if it only passes isolated checks but has not been exercised in a real workflow context. + +### Documentation Validation + +When behavior changes, documentation must be checked for alignment. This includes: + +- top-level user docs, +- maintainer docs, +- subsystem docs, +- extension or preset publishing docs. + +### Packaging and Distribution Validation + +When changing install, release, extension, or preset behavior, confirm that the change remains correct in the form users actually consume. + +Do not assume that source-level correctness is sufficient. + +## Documentation Map + +This section routes contributors to the right deeper documents. + +### `README.md` + +Primary user-facing introduction. + +Read this when you need to understand how the repository presents itself to adopters and what promises are made to users. + +### `CONTRIBUTING.md` + +Contribution process, expectations, and contribution hygiene. + +Read this before opening a pull request or when you need the repository's current contribution rules. + +### `TESTING.md` + +Validation strategy and test guidance. + +Read this when planning or executing validation for non-trivial changes. + +### Extension Publishing Documentation + +Read the extension-specific publishing guide when working on extension creation, packaging, or publication. + +### Preset Publishing Documentation + +Read the preset-specific publishing guide when working on preset creation, packaging, or publication. + +### Other Specialized Documents + +Read subsystem-specific documents when your change targets a specific area rather than the core maintainer workflow. + +As the repository evolves, keep this section curated. It should remain a developer routing table, not a raw list of markdown files. + +## Architectural Invariants and Guardrails + +The following guardrails should remain true unless there is an explicit, repository-wide decision to change them. + +### Preserve Workflow Coherence + +The core spec-driven workflow should remain understandable as a staged progression from governing principles to specification, planning, tasking, and execution. + +Do not introduce local optimizations that make the overall model less coherent. + +### Preserve Cross-Surface Alignment + +Templates, scripts, CLI behavior, and docs should describe the same system. + +A contributor should not be able to follow the docs and encounter materially different behavior in the actual workflow. + +### Treat Templates as Product Logic + +Template wording, structure, and default content are part of the product, not just decoration. + +Do not make casual wording changes without considering behavioral consequences. + +### Keep Agent-Specific Adaptation Secondary to the Core Model + +Agent-specific support is important, but it should adapt the core workflow rather than fragment it into unrelated systems unless such divergence is deliberate and documented. + +### Keep Extensions and Presets Legible + +Extensions and presets should remain understandable additions or variations, not opaque redefinitions of the core workflow. + +## Common Pitfalls + +The following mistakes are easy to make in this repository. + +### Treating a Template Edit as a Mere Copy Change + +Template wording often changes behavior. Review it the same way you would review logic changes. + +### Updating One Surface but Not the Others + +A workflow change may require updates in templates, docs, tests, and installation or execution behavior. Check for cross-surface impact before considering the work complete. + +### Validating Too Narrowly + +A focused unit check may pass while the real user workflow is broken. Use end-to-end validation when the change affects behavior users or agents actually experience. + +### Letting Contributor Docs Drift + +When the repository structure or maintainer workflow changes, `DEVELOPMENT.md` and related docs need to change too. + +### Hiding a Conceptual Change Inside a Small Edit + +If a change alters the mental model or expected workflow, document it as such. Do not let significant semantic changes masquerade as tiny text cleanups. + +## Release and Compatibility Notes + +When making changes that affect packaging, installation, extensions, presets, or generated outputs, consider compatibility from the perspective of actual users and downstream maintainers. + +Questions to ask: + +Does this change + +- alter the expected workflow? +- affect generated artifacts? +- require documentation updates? +- affect extension or preset compatibility? +- need explicit release-note treatment? + +When in doubt, assume user-visible workflow changes deserve explicit documentation and release awareness. + +## Maintainer Onboarding Checklist + +A new maintainer should usually do the following before making broad changes: + +1. read `README.md` to understand the user-facing model, +2. read this document to understand the maintainer-facing model, +3. read `CONTRIBUTING.md` before preparing changes, +4. read `TESTING.md` before validating non-trivial work, +5. inspect the repository layout, especially `templates/`, `scripts/`, and any CLI or packaging code, +6. trace at least one representative end-to-end workflow, +7. start with a narrow, well-scoped change before attempting structural revisions. + +## Keeping This Document Healthy + +This document should evolve with the repository. + +Update it when: + +- repository structure changes, +- the maintainer mental model changes, +- new core subsystems are introduced, +- the recommended development workflow changes, +- the document map needs rerouting. + +The goal is to keep this file useful as a top-level maintainer entry point, not to turn it into an exhaustive reference manual. diff --git a/Development Guide Dev/Untitled 1.md b/Development Guide Dev/Untitled 1.md new file mode 100644 index 000000000..4454c598d --- /dev/null +++ b/Development Guide Dev/Untitled 1.md @@ -0,0 +1,458 @@ +# Development Guide + +This document is the primary entry point for people modifying Spec Kit itself. + +Use this guide when you need to understand how the repository fits together, where different kinds of changes belong, how to validate them, and which deeper documents to read next. + +## Relationship to Other Top-Level Documents + +Spec Kit has several top-level documents with different roles. They should not duplicate each other. + +- `README.md` is the primary entry point for users adopting Spec Kit in a project. +- `DEVELOPMENT.md` is the primary entry point for contributors and maintainers changing Spec Kit itself. +- `CONTRIBUTING.md` defines contribution mechanics, review expectations, and required development practices. +- `TESTING.md` describes validation strategy and testing procedures in more detail. +- Other specialized documents cover specific subsystems or publishing workflows. + +This document is intentionally focused on system understanding, repository navigation, and change workflows. + +## What Spec Kit Is, from a Maintainer Perspective + +Spec Kit is a toolkit for spec-driven development. It provides a structured workflow, scaffolding assets, and supporting integrations that help users move from an idea to a defined specification, an implementation plan, task breakdowns, and executable project work. + +From a maintainer perspective, the repository is not just "documentation" and not just "code". It is a coordinated system composed of several interacting surfaces: + +- workflow-defining templates, +- command and scaffolding assets, +- scripts and automation helpers, +- CLI and installation behavior, +- agent-specific integration surfaces, +- extension and preset publishing assets, +- documentation that explains and stabilizes the user and developer model. + +Maintaining Spec Kit means preserving coherence across those surfaces. A change in one layer often affects documentation, validation expectations, and user-visible workflow behavior in other layers. + +## System Mental Model + +### Core User Workflow + +At a high level, Spec Kit supports a staged workflow in which a user moves through structured project definition and execution steps. The exact implementation details may vary by agent or integration surface, but the core conceptual flow is consistent: + +1. establish or refine governing project principles, +2. define a concrete specification, +3. derive an implementation plan, +4. derive an actionable task breakdown, +5. execute implementation against the defined artifacts. + +When changing Spec Kit, first identify which part of that lifecycle your change affects. + +### Source Assets vs Generated Project Assets + +A useful distinction for maintainers is the difference between: + +- **source assets in this repository**, and +- **artifacts that users consume in their own repositories or agent sessions**. + +Source assets in this repository define behavior, structure, wording, conventions, and scaffolding rules. Generated or installed assets are the user-facing outputs of those source assets. + +When editing repository files, think in terms of downstream consequences: + +- What will change in the user-visible workflow? +- What will change in generated project content? +- What must be revalidated manually in a real end-to-end flow? + +### Main System Surfaces + +Most changes fall into one or more of these surfaces: + +- **Templates**: define workflow artifacts, prompts, scaffolding content, and generated project structure. +- **Scripts and automation**: support local generation, packaging, installation, or validation flows. +- **CLI and bootstrap behavior**: define how users initialize, install, or execute Spec Kit workflows. +- **Agent integration surfaces**: adapt the kit to specific agent environments without changing the underlying workflow intent. +- **Extensions and presets**: package additional reusable behavior or opinionated configurations. +- **Documentation**: explain the intended model, workflow, usage, and maintenance practices. + +A contributor should be able to identify which surface they are editing before making a change. + +## Repository Anatomy + +This section explains the role of the major repository areas. It is intended as a guided map, not a full file inventory. + +### `templates/` + +This directory contains the core workflow and content assets that shape the user experience. In many cases, this is the most important part of the repository because it defines the structure and wording of the spec-driven workflow itself. + +Edit `templates/` when you are changing: + +- generated artifact structure, +- workflow prompt wording, +- command or template content, +- default project scaffolding semantics. + +Treat template changes as behavior changes, not as passive documentation edits. Even small text changes can alter how users and agents interpret the workflow. + +### `scripts/` + +This directory contains automation and helper logic used for validation, packaging, generation, or related maintenance tasks. + +Edit `scripts/` when you are changing: + +- automation that supports local development, +- packaging or build helpers, +- maintenance utilities, +- validation support logic. + +Script changes should be validated both for local correctness and for their role in the broader development workflow. + +### CLI and Package Code + +Where applicable, repository code for installation, bootstrap, packaging, or command execution defines how Spec Kit is delivered and invoked. + +Edit the CLI or package code when you are changing: + +- installation behavior, +- initialization flow, +- local command behavior, +- execution semantics exposed to users. + +Changes here are usually high-impact because they affect how users enter the system. + +### Memory and Governing Assets + +Some repository assets define persistent project conventions, constitutions, or other workflow-governing content. + +Edit these assets when you are changing: + +- core workflow assumptions, +- project constitution defaults, +- stable behavioral expectations carried across the kit. + +These changes often require corresponding documentation updates because they affect the conceptual model, not just wording. + +### `extensions/` + +This area supports extension mechanisms and related publishing flows. + +Edit `extensions/` when you are: + +- adding a new extension, +- modifying extension behavior, +- updating extension packaging or publishing guidance. + +Extension changes should preserve compatibility with the main Spec Kit model unless the extension is explicitly intended to be a bounded deviation. + +### `presets/` + +This area supports reusable preset configurations and their publishing workflows. + +Edit `presets/` when you are: + +- adding a new preset, +- changing how presets are defined, +- updating preset publishing or maintenance logic. + +Presets should remain understandable as opinionated selections layered on top of the core workflow, not as silent redefinitions of that workflow. + +### Documentation Surface + +Top-level and subsystem documentation explains the user model, maintainer model, testing expectations, and publishing flows. + +Edit documentation whenever code, templates, scripts, or workflow semantics change in a way that affects: + +- user understanding, +- contributor understanding, +- validation expectations, +- extension or preset author behavior. + +Do not treat docs as an afterthought. In Spec Kit, documentation is part of the product surface. + +## Change Map: If You Want to Change X, Edit Y + +This section is a practical routing guide. Use it before making edits. + +### Change generated specification or planning content + +Start with the relevant files under `templates/`. + +Typical examples: + +- generated spec wording, +- plan structure, +- task generation wording, +- default scaffolded project artifacts. + +### Change workflow behavior or sequencing + +Inspect the relevant templates first, then any supporting script or CLI logic that participates in workflow execution. + +Typical examples: + +- command flow changes, +- stage ordering changes, +- added or removed workflow steps, +- changes in how generated assets reference one another. + +### Change installation or bootstrap behavior + +Inspect CLI or package code, install helpers, and any supporting scripts involved in setup or initialization. + +Typical examples: + +- init behavior, +- install commands, +- local executable behavior, +- package layout expectations. + +### Change user-facing documentation + +Update `README.md` and any other user-facing docs affected by the change. If the workflow model changes, also update any supporting conceptual documentation so the documented model remains aligned with actual behavior. + +### Change contributor-facing guidance + +Update `DEVELOPMENT.md`, `CONTRIBUTING.md`, `TESTING.md`, or more specialized contributor documentation as appropriate. + +### Change extension behavior or extension publishing + +Start in `extensions/` and then update related publishing guidance and any ecosystem references. + +### Change preset behavior or preset publishing + +Start in `presets/` and then update related publishing guidance and any ecosystem references. + +### Change system-wide conceptual assumptions + +Treat the change as cross-cutting. Review templates, governing assets, docs, validation expectations, and any affected packaging or integration surfaces together. + +## Development Workflows + +This section describes the normal paths for common kinds of changes. + +### Template Change Workflow + +Use this workflow when changing prompt content, generated artifact structure, or other template-defined behavior. + +1. Identify the exact user-visible behavior that should change. +2. Locate the relevant template files. +3. Make the smallest coherent change that expresses the intended behavior. +4. Review adjacent templates for consistency. +5. Update documentation if the conceptual or visible behavior changed. +6. Validate the change through focused checks and at least one realistic end-to-end flow. + +For template changes, wording is behavior. Treat wording edits with the same care as code changes. + +### Script Change Workflow + +Use this workflow when changing repository automation or support utilities. + +1. Identify the workflow that depends on the script. +2. Edit the relevant script with minimal scope. +3. Validate the script directly. +4. Validate the higher-level workflow that depends on it. +5. Update docs if the script changes how contributors or users are expected to work. + +### CLI or Bootstrap Change Workflow + +Use this workflow when changing how users enter or operate Spec Kit through commands or package installation. + +1. Identify the affected command or entry path. +2. Trace the code and any related templates or scripts. +3. Make the change with attention to backward compatibility and user expectations. +4. Validate the affected command locally. +5. Validate at least one realistic user entry flow end to end. +6. Update user-facing and developer-facing docs as needed. + +### Docs-Only Workflow + +Use this workflow when making documentation changes that do not intentionally alter behavior. + +1. Confirm that the change is actually documentation-only. +2. Update the relevant docs. +3. Check for overlap with other docs that may now be inconsistent. +4. Ensure terminology remains aligned across documents. + +Be cautious: many apparent "docs-only" changes in this repository are actually behavioral if they describe workflow semantics that templates or scripts already implement. + +### Extension or Preset Workflow + +Use this workflow when changing extension or preset assets. + +1. Identify whether the change affects the core model or only the extension/preset layer. +2. Edit the relevant extension or preset files. +3. Validate packaging, discoverability, and usage expectations. +4. Update publishing and maintenance guidance where needed. +5. Ensure the relationship to core Spec Kit remains explicit. + +## Validation and Testing Map + +This section is a routing summary. For detailed procedures, see `TESTING.md` and related validation documentation. + +### Focused Local Validation + +Use focused validation first when changing a narrow part of the system. + +Examples include: + +- validating the specific template you changed, +- running the script you modified, +- exercising the CLI path you edited, +- checking a packaging or publishing path affected by your change. + +### End-to-End Workflow Validation + +Use realistic manual validation when the change affects user-visible workflow semantics. + +This is especially important for: + +- template changes, +- command flow changes, +- initialization or bootstrap changes, +- agent-facing workflow changes. + +A change is not well validated if it only passes isolated checks but has not been exercised in a real workflow context. + +### Documentation Validation + +When behavior changes, documentation must be checked for alignment. This includes: + +- top-level user docs, +- maintainer docs, +- subsystem docs, +- extension or preset publishing docs. + +### Packaging and Distribution Validation + +When changing install, release, extension, or preset behavior, confirm that the change remains correct in the form users actually consume. + +Do not assume that source-level correctness is sufficient. + +## Documentation Map + +This section routes contributors to the right deeper documents. + +### `README.md` + +Primary user-facing introduction. + +Read this when you need to understand how the repository presents itself to adopters and what promises are made to users. + +### `CONTRIBUTING.md` + +Contribution process, expectations, and contribution hygiene. + +Read this before opening a pull request or when you need the repository's current contribution rules. + +### `TESTING.md` + +Validation strategy and test guidance. + +Read this when planning or executing validation for non-trivial changes. + +### Extension Publishing Documentation + +Read the extension-specific publishing guide when working on extension creation, packaging, or publication. + +### Preset Publishing Documentation + +Read the preset-specific publishing guide when working on preset creation, packaging, or publication. + +### Other Specialized Documents + +Read subsystem-specific documents when your change targets a specific area rather than the core maintainer workflow. + +As the repository evolves, keep this section curated. It should remain a developer routing table, not a raw list of markdown files. + +## Architectural Invariants and Guardrails + +The following guardrails should remain true unless there is an explicit, repository-wide decision to change them. + +### Preserve Workflow Coherence + +The core spec-driven workflow should remain understandable as a staged progression from governing principles to specification, planning, tasking, and execution. + +Do not introduce local optimizations that make the overall model less coherent. + +### Preserve Cross-Surface Alignment + +Templates, scripts, CLI behavior, and docs should describe the same system. + +A contributor should not be able to follow the docs and encounter materially different behavior in the actual workflow. + +### Treat Templates as Product Logic + +Template wording, structure, and default content are part of the product, not just decoration. + +Do not make casual wording changes without considering behavioral consequences. + +### Keep Agent-Specific Adaptation Secondary to the Core Model + +Agent-specific support is important, but it should adapt the core workflow rather than fragment it into unrelated systems unless such divergence is deliberate and documented. + +### Keep Extensions and Presets Legible + +Extensions and presets should remain understandable additions or variations, not opaque redefinitions of the core workflow. + +## Common Pitfalls + +The following mistakes are easy to make in this repository. + +### Treating a Template Edit as a Mere Copy Change + +Template wording often changes behavior. Review it the same way you would review logic changes. + +### Updating One Surface but Not the Others + +A workflow change may require updates in templates, docs, tests, and installation or execution behavior. Check for cross-surface impact before considering the work complete. + +### Validating Too Narrowly + +A focused unit check may pass while the real user workflow is broken. Use end-to-end validation when the change affects behavior users or agents actually experience. + +### Letting Contributor Docs Drift + +When the repository structure or maintainer workflow changes, `DEVELOPMENT.md` and related docs need to change too. + +### Hiding a Conceptual Change Inside a Small Edit + +If a change alters the mental model or expected workflow, document it as such. Do not let significant semantic changes masquerade as tiny text cleanups. + +## Release and Compatibility Notes + +When making changes that affect packaging, installation, extensions, presets, or generated outputs, consider compatibility from the perspective of actual users and downstream maintainers. + +Questions to ask: + +Does this change + +- alter the expected workflow? +- affect generated artifacts? +- require documentation updates? +- affect extension or preset compatibility? +- need explicit release-note treatment? + +When in doubt, assume user-visible workflow changes deserve explicit documentation and release awareness. + +## Maintainer Onboarding Checklist + +A new maintainer should usually do the following before making broad changes: + +1. read `README.md` to understand the user-facing model, +2. read this document to understand the maintainer-facing model, +3. read `CONTRIBUTING.md` before preparing changes, +4. read `TESTING.md` before validating non-trivial work, +5. inspect the repository layout, especially `templates/`, `scripts/`, and any CLI or packaging code, +6. trace at least one representative end-to-end workflow, +7. start with a narrow, well-scoped change before attempting structural revisions. + +## Keeping This Document Healthy + +This document should evolve with the repository. + +Update it when: + +- repository structure changes, +- the maintainer mental model changes, +- new core subsystems are introduced, +- the recommended development workflow changes, +- the document map needs rerouting. + +The goal is to keep this file useful as a top-level maintainer entry point, not to turn it into an exhaustive reference manual. From 74387c6bf56e7a1c6df0d5fb4b614a8b669318e9 Mon Sep 17 00:00:00 2001 From: PChemGuy <39730837+pchemguy@users.noreply.github.com> Date: Thu, 2 Apr 2026 14:19:17 +0300 Subject: [PATCH 03/25] Update DEVELOPMENT.md --- DEVELOPMENT.md | 25 ++++++++++++++++--------- 1 file changed, 16 insertions(+), 9 deletions(-) diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 4454c598d..6c8d771ae 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -2,19 +2,26 @@ This document is the primary entry point for people modifying Spec Kit itself. -Use this guide when you need to understand how the repository fits together, where different kinds of changes belong, how to validate them, and which deeper documents to read next. +Use this guide when you need to understand how the repository fits together, where different kinds of changes belong, how to validate them, and which deeper documents to read next. This document is intentionally focused on system understanding, repository navigation, and change workflows. -## Relationship to Other Top-Level Documents +## Maintainer Onboarding Checklist + +Spec Kit has several top-level documents with different roles. They should not duplicate each other. A new maintainer should usually do the following before making broad changes: + +1. Read core top-level documents: -Spec Kit has several top-level documents with different roles. They should not duplicate each other. +| Document | Focus | +| ------------------------------------------ | ---------------------------------------------------------------------------------- | +| [README.md](./README.md) | The primary entry point for users adopting Spec Kit in a project. | +| This document | The primary entry point for contributors and maintainers changing Spec Kit itself. | +| [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md) | | +| [CONTRIBUTING.md](./CONTRIBUTING.md) | Contribution mechanics, review expectations, and required development practices. | +| [TESTING.md](./TESTING.md) | Validation strategy and testing procedures. | -- `README.md` is the primary entry point for users adopting Spec Kit in a project. -- `DEVELOPMENT.md` is the primary entry point for contributors and maintainers changing Spec Kit itself. -- `CONTRIBUTING.md` defines contribution mechanics, review expectations, and required development practices. -- `TESTING.md` describes validation strategy and testing procedures in more detail. -- Other specialized documents cover specific subsystems or publishing workflows. +2. inspect the repository layout, especially `templates/`, `scripts/`, and any CLI or packaging code, +3. trace at least one representative end-to-end workflow, +4. start with a narrow, well-scoped change before attempting structural revisions. -This document is intentionally focused on system understanding, repository navigation, and change workflows. ## What Spec Kit Is, from a Maintainer Perspective From 61fe969b0736580acc0a52698b4180662d031504 Mon Sep 17 00:00:00 2001 From: PChemGuy <39730837+pchemguy@users.noreply.github.com> Date: Thu, 2 Apr 2026 17:08:22 +0300 Subject: [PATCH 04/25] Update DEVELOPMENT.md --- DEVELOPMENT.md | 32 ++++++++++++++++++++------------ 1 file changed, 20 insertions(+), 12 deletions(-) diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 6c8d771ae..6874fb2c5 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -6,22 +6,30 @@ Use this guide when you need to understand how the repository fits together, whe ## Maintainer Onboarding Checklist -Spec Kit has several top-level documents with different roles. They should not duplicate each other. A new maintainer should usually do the following before making broad changes: +Start here before making broad changes to Spec Kit. -1. Read core top-level documents: +### 1. Read the core top-level documents -| Document | Focus | -| ------------------------------------------ | ---------------------------------------------------------------------------------- | -| [README.md](./README.md) | The primary entry point for users adopting Spec Kit in a project. | -| This document | The primary entry point for contributors and maintainers changing Spec Kit itself. | -| [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md) | | -| [CONTRIBUTING.md](./CONTRIBUTING.md) | Contribution mechanics, review expectations, and required development practices. | -| [TESTING.md](./TESTING.md) | Validation strategy and testing procedures. | +Spec Kit has several top-level documents with different roles. They should not duplicate each other. -2. inspect the repository layout, especially `templates/`, `scripts/`, and any CLI or packaging code, -3. trace at least one representative end-to-end workflow, -4. start with a narrow, well-scoped change before attempting structural revisions. +| Document | Focus | +| ------------------------------------------ | -------------------------------------------------------------------------------- | +| [README.md](./README.md) | Primary entry point for users adopting Spec Kit in a project. | +| [DEVELOPMENT.md](./DEVELOPMENT.md) | Primary entry point for contributors and maintainers changing Spec Kit itself. | +| [CONTRIBUTING.md](./CONTRIBUTING.md) | Contribution mechanics, review expectations, and required development practices. | +| [TESTING.md](./TESTING.md) | Validation strategy and testing procedures. | +### 2. Inspect the repository layout + +Inspect the repository layout, especially `templates/`, `scripts/`, and any CLI or packaging code. + +### 3. Trace a representative workflow + +Trace at least one representative end-to-end workflow so you can connect the repository's source assets to the user-visible behavior they produce. + +### 4. Start with a narrow change + +Start with a narrow, well-scoped change before attempting broader structural revisions. ## What Spec Kit Is, from a Maintainer Perspective From 162e8c62202599fba9c07c3b273a834806af97f5 Mon Sep 17 00:00:00 2001 From: PChemGuy <39730837+pchemguy@users.noreply.github.com> Date: Thu, 2 Apr 2026 17:11:20 +0300 Subject: [PATCH 05/25] Create Untitled 2.md --- Development Guide Dev/Untitled 2.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) create mode 100644 Development Guide Dev/Untitled 2.md diff --git a/Development Guide Dev/Untitled 2.md b/Development Guide Dev/Untitled 2.md new file mode 100644 index 000000000..adfccb663 --- /dev/null +++ b/Development Guide Dev/Untitled 2.md @@ -0,0 +1,12 @@ +Top-level documents are not sufficient for full onboarding. Before editing, read the relevant subsystem documentation for the surface you plan to modify. + +Use the following routing guide. + +| If you plan to change... | Read... | +| -------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | +| Core workflow templates and generated artifact structure | The relevant documents under `templates/` and any linked workflow-specific documentation | +| Validation behavior or test expectations | [TESTING.md](./TESTING.md) and any related subsystem-specific testing documentation | +| Extensions | The documentation under `extensions/`, including extension publishing and maintenance guidance | +| Presets | The documentation under `presets/`, including preset publishing and maintenance guidance | +| User-facing workflow semantics | The relevant templates, [README.md](./README.md), and any conceptual workflow documentation | +| Installation, packaging, or bootstrap behavior | The relevant CLI/package code, scripts, and associated development or publishing documentation | From cdc8276a24064c8bf9ec15dbbcae5781398938b2 Mon Sep 17 00:00:00 2001 From: PChemGuy <39730837+pchemguy@users.noreply.github.com> Date: Thu, 2 Apr 2026 18:15:13 +0300 Subject: [PATCH 06/25] Update DEVELOPMENT.md --- DEVELOPMENT.md | 82 ++++++++------------------------------------------ 1 file changed, 13 insertions(+), 69 deletions(-) diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 6874fb2c5..d4c54a6cc 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -6,30 +6,22 @@ Use this guide when you need to understand how the repository fits together, whe ## Maintainer Onboarding Checklist -Start here before making broad changes to Spec Kit. +Read the essential project documents. -### 1. Read the core top-level documents +| Document | Focus | +| ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- | +| [README.md](./README.md) | Primary user-facing entry point and high-level overview of what Spec Kit is, how it is used, and what workflow it supports. | +| [DEVELOPMENT.md](./DEVELOPMENT.md) | Primary maintainer-facing entry point for contributors changing Spec Kit itself. | +| [spec-driven.md](./spec-driven.md) | Full conceptual and procedural walkthrough of the Spec-Driven Development workflow supported by Spec Kit. | +| [RELEASE-PROCESS.md](./.github/workflows/RELEASE-PROCESS.md) | Release workflow, versioning model, changelog generation, and release-process invariants. | +| [docs/index.md](./docs/index.md) | Entry point to the documentation under `docs/`, including installation, quick start, upgrade, and local development guidance. | +| [CONTRIBUTING.md](./CONTRIBUTING.md) | Contribution mechanics, review expectations, and required development practices. | +| [TESTING.md](./TESTING.md) | Validation strategy and testing procedures. | -Spec Kit has several top-level documents with different roles. They should not duplicate each other. +Inspect the repository layout, especially -| Document | Focus | -| ------------------------------------------ | -------------------------------------------------------------------------------- | -| [README.md](./README.md) | Primary entry point for users adopting Spec Kit in a project. | -| [DEVELOPMENT.md](./DEVELOPMENT.md) | Primary entry point for contributors and maintainers changing Spec Kit itself. | -| [CONTRIBUTING.md](./CONTRIBUTING.md) | Contribution mechanics, review expectations, and required development practices. | -| [TESTING.md](./TESTING.md) | Validation strategy and testing procedures. | - -### 2. Inspect the repository layout - -Inspect the repository layout, especially `templates/`, `scripts/`, and any CLI or packaging code. - -### 3. Trace a representative workflow - -Trace at least one representative end-to-end workflow so you can connect the repository's source assets to the user-visible behavior they produce. - -### 4. Start with a narrow change - -Start with a narrow, well-scoped change before attempting broader structural revisions. +- `templates/` - core project +- `scripts/`, and any CLI or packaging code. ## What Spec Kit Is, from a Maintainer Perspective @@ -340,42 +332,6 @@ When changing install, release, extension, or preset behavior, confirm that the Do not assume that source-level correctness is sufficient. -## Documentation Map - -This section routes contributors to the right deeper documents. - -### `README.md` - -Primary user-facing introduction. - -Read this when you need to understand how the repository presents itself to adopters and what promises are made to users. - -### `CONTRIBUTING.md` - -Contribution process, expectations, and contribution hygiene. - -Read this before opening a pull request or when you need the repository's current contribution rules. - -### `TESTING.md` - -Validation strategy and test guidance. - -Read this when planning or executing validation for non-trivial changes. - -### Extension Publishing Documentation - -Read the extension-specific publishing guide when working on extension creation, packaging, or publication. - -### Preset Publishing Documentation - -Read the preset-specific publishing guide when working on preset creation, packaging, or publication. - -### Other Specialized Documents - -Read subsystem-specific documents when your change targets a specific area rather than the core maintainer workflow. - -As the repository evolves, keep this section curated. It should remain a developer routing table, not a raw list of markdown files. - ## Architectural Invariants and Guardrails The following guardrails should remain true unless there is an explicit, repository-wide decision to change them. @@ -446,18 +402,6 @@ Does this change When in doubt, assume user-visible workflow changes deserve explicit documentation and release awareness. -## Maintainer Onboarding Checklist - -A new maintainer should usually do the following before making broad changes: - -1. read `README.md` to understand the user-facing model, -2. read this document to understand the maintainer-facing model, -3. read `CONTRIBUTING.md` before preparing changes, -4. read `TESTING.md` before validating non-trivial work, -5. inspect the repository layout, especially `templates/`, `scripts/`, and any CLI or packaging code, -6. trace at least one representative end-to-end workflow, -7. start with a narrow, well-scoped change before attempting structural revisions. - ## Keeping This Document Healthy This document should evolve with the repository. From 98be363be4cbf5f55168f64bdf5bbd5017e872a1 Mon Sep 17 00:00:00 2001 From: PChemGuy <39730837+pchemguy@users.noreply.github.com> Date: Thu, 2 Apr 2026 19:50:22 +0300 Subject: [PATCH 07/25] Update DEVELOPMENT.md --- DEVELOPMENT.md | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index d4c54a6cc..820e2243b 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -4,9 +4,9 @@ This document is the primary entry point for people modifying Spec Kit itself. Use this guide when you need to understand how the repository fits together, where different kinds of changes belong, how to validate them, and which deeper documents to read next. This document is intentionally focused on system understanding, repository navigation, and change workflows. -## Maintainer Onboarding Checklist +## Maintainer Onboarding -Read the essential project documents. +**Read the essential project documents**: | Document | Focus | | ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- | @@ -18,10 +18,15 @@ Read the essential project documents. | [CONTRIBUTING.md](./CONTRIBUTING.md) | Contribution mechanics, review expectations, and required development practices. | | [TESTING.md](./TESTING.md) | Validation strategy and testing procedures. | -Inspect the repository layout, especially +**Inspect the repository layout**: -- `templates/` - core project -- `scripts/`, and any CLI or packaging code. +| Directory | Role | +| ------------------ | ---------------------------------------------------------------------- | +| `templates/` | Core project framework, LLM templated prompts and associated templates | +| `scripts/` | Deterministic component of the project framework. | +| `src/specify_cli/` | Python sources of `specify` CLI. | +| `extensions/` | Documentation and associated files for the `extensions` feature. | +| `presets/` | Documentation and associated files for the `presets` feature. | ## What Spec Kit Is, from a Maintainer Perspective From 73137e85e3dff57d6fd43cf3112659e4f9d39d8c Mon Sep 17 00:00:00 2001 From: PChemGuy <39730837+pchemguy@users.noreply.github.com> Date: Thu, 2 Apr 2026 19:57:52 +0300 Subject: [PATCH 08/25] Update DEVELOPMENT.md --- DEVELOPMENT.md | 44 +++++++++++++++++++++++--------------------- 1 file changed, 23 insertions(+), 21 deletions(-) diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 820e2243b..3a21e9443 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -6,27 +6,29 @@ Use this guide when you need to understand how the repository fits together, whe ## Maintainer Onboarding -**Read the essential project documents**: - -| Document | Focus | -| ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- | -| [README.md](./README.md) | Primary user-facing entry point and high-level overview of what Spec Kit is, how it is used, and what workflow it supports. | -| [DEVELOPMENT.md](./DEVELOPMENT.md) | Primary maintainer-facing entry point for contributors changing Spec Kit itself. | -| [spec-driven.md](./spec-driven.md) | Full conceptual and procedural walkthrough of the Spec-Driven Development workflow supported by Spec Kit. | -| [RELEASE-PROCESS.md](./.github/workflows/RELEASE-PROCESS.md) | Release workflow, versioning model, changelog generation, and release-process invariants. | -| [docs/index.md](./docs/index.md) | Entry point to the documentation under `docs/`, including installation, quick start, upgrade, and local development guidance. | -| [CONTRIBUTING.md](./CONTRIBUTING.md) | Contribution mechanics, review expectations, and required development practices. | -| [TESTING.md](./TESTING.md) | Validation strategy and testing procedures. | - -**Inspect the repository layout**: - -| Directory | Role | -| ------------------ | ---------------------------------------------------------------------- | -| `templates/` | Core project framework, LLM templated prompts and associated templates | -| `scripts/` | Deterministic component of the project framework. | -| `src/specify_cli/` | Python sources of `specify` CLI. | -| `extensions/` | Documentation and associated files for the `extensions` feature. | -| `presets/` | Documentation and associated files for the `presets` feature. | +**Read the essential project documents:** + +| Document | Role | +| --- | --- | +| [README.md](./README.md) | Primary user-facing overview of Spec Kit, its purpose, and its workflow. | +| [DEVELOPMENT.md](./DEVELOPMENT.md) | Primary maintainer-facing guide to modifying Spec Kit itself. | +| [spec-driven.md](./spec-driven.md) | End-to-end explanation of the Spec-Driven Development model supported by Spec Kit. | +| [RELEASE-PROCESS.md](./.github/workflows/RELEASE-PROCESS.md) | Release workflow, versioning rules, and changelog generation process. | +| [docs/index.md](./docs/index.md) | Entry point to the `docs/` documentation set. | +| [CONTRIBUTING.md](./CONTRIBUTING.md) | Contribution process, review expectations, and required development practices. | +| [TESTING.md](./TESTING.md) | Validation strategy and testing procedures. | + +**Inspect the repository layout:** + +| Directory | Role | +| --- | --- | +| `templates/` | Core templates, prompt assets, and scaffold content that define the workflow surface. | +| `scripts/` | Supporting scripts used by the generated workflow and repository tooling. | +| `src/specify_cli/` | Python source for the `specify` CLI. | +| `extensions/` | Extension-related docs, catalogs, and supporting assets. | +| `presets/` | Preset-related docs, catalogs, and supporting assets. | + +**Trace a representative end-to-end workflow** to connect the repository's source assets to the user-visible behavior they produce. ## What Spec Kit Is, from a Maintainer Perspective From d63c8d9b1fc691dfcf4ebe0eaafb935773501ef5 Mon Sep 17 00:00:00 2001 From: PChemGuy <39730837+pchemguy@users.noreply.github.com> Date: Thu, 2 Apr 2026 20:11:52 +0300 Subject: [PATCH 09/25] Update DEVELOPMENT.md --- DEVELOPMENT.md | 16 +++++++--------- 1 file changed, 7 insertions(+), 9 deletions(-) diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 3a21e9443..1ca1b7946 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -20,15 +20,13 @@ Use this guide when you need to understand how the repository fits together, whe **Inspect the repository layout:** -| Directory | Role | -| --- | --- | -| `templates/` | Core templates, prompt assets, and scaffold content that define the workflow surface. | -| `scripts/` | Supporting scripts used by the generated workflow and repository tooling. | -| `src/specify_cli/` | Python source for the `specify` CLI. | -| `extensions/` | Extension-related docs, catalogs, and supporting assets. | -| `presets/` | Preset-related docs, catalogs, and supporting assets. | - -**Trace a representative end-to-end workflow** to connect the repository's source assets to the user-visible behavior they produce. +| Directory | Role | +| ------------------ | --------------------------------------------------------------------- | +| `templates/` | Prompt assets and templates that define the workflow surface. | +| `scripts/` | Supporting scripts used by the generated workflow. | +| `src/specify_cli/` | Python source for the `specify` CLI, including agent-specific assets. | +| `extensions/` | Extension-related docs, catalogs, and supporting assets. | +| `presets/` | Preset-related docs, catalogs, and supporting assets. | ## What Spec Kit Is, from a Maintainer Perspective From ca35df7a568713f9f7d383b3b42166499d188950 Mon Sep 17 00:00:00 2001 From: PChemGuy <39730837+pchemguy@users.noreply.github.com> Date: Thu, 2 Apr 2026 20:18:48 +0300 Subject: [PATCH 10/25] Update DEVELOPMENT.md --- DEVELOPMENT.md | 42 ++++++++++++++---------------------------- 1 file changed, 14 insertions(+), 28 deletions(-) diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 1ca1b7946..e1fe8e725 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -1,48 +1,34 @@ # Development Guide -This document is the primary entry point for people modifying Spec Kit itself. +This document is the primary entry point for people modifying Spec Kit itself. Use this guide when you need to understand how the repository fits together, where different kinds of changes belong, how to validate them, and which deeper documents to read next. This document is intentionally focused on system understanding, repository navigation, and change workflows. -Use this guide when you need to understand how the repository fits together, where different kinds of changes belong, how to validate them, and which deeper documents to read next. This document is intentionally focused on system understanding, repository navigation, and change workflows. +## Maintainer Orientation -## Maintainer Onboarding +Spec Kit is a toolkit for spec-driven development. It provides the workflow, scaffolding assets, and supporting integrations that turn an idea into a specification, an implementation plan, task breakdowns, and executable project work. From a maintainer perspective, the repository is not just documentation and not just code. It is a coordinated system whose templates, scripts, CLI, agent integrations, extensions, presets, and documentation must remain aligned. -**Read the essential project documents:** +**Essential project documents:** | Document | Role | | --- | --- | -| [README.md](./README.md) | Primary user-facing overview of Spec Kit, its purpose, and its workflow. | +| [README.md](./README.md) | Primary user-facing overview of Spec Kit and its workflow. | | [DEVELOPMENT.md](./DEVELOPMENT.md) | Primary maintainer-facing guide to modifying Spec Kit itself. | -| [spec-driven.md](./spec-driven.md) | End-to-end explanation of the Spec-Driven Development model supported by Spec Kit. | +| [spec-driven.md](./spec-driven.md) | End-to-end explanation of the Spec-Driven Development workflow supported by Spec Kit. | | [RELEASE-PROCESS.md](./.github/workflows/RELEASE-PROCESS.md) | Release workflow, versioning rules, and changelog generation process. | | [docs/index.md](./docs/index.md) | Entry point to the `docs/` documentation set. | | [CONTRIBUTING.md](./CONTRIBUTING.md) | Contribution process, review expectations, and required development practices. | | [TESTING.md](./TESTING.md) | Validation strategy and testing procedures. | -**Inspect the repository layout:** +**Main repository surfaces:** -| Directory | Role | -| ------------------ | --------------------------------------------------------------------- | -| `templates/` | Prompt assets and templates that define the workflow surface. | -| `scripts/` | Supporting scripts used by the generated workflow. | +| Directory | Role | +| --- | --- | +| `templates/` | Prompt assets and templates that define the core workflow behavior and generated artifacts. | +| `scripts/` | Supporting scripts used by the workflow, setup, and repository tooling. | | `src/specify_cli/` | Python source for the `specify` CLI, including agent-specific assets. | -| `extensions/` | Extension-related docs, catalogs, and supporting assets. | -| `presets/` | Preset-related docs, catalogs, and supporting assets. | - -## What Spec Kit Is, from a Maintainer Perspective - -Spec Kit is a toolkit for spec-driven development. It provides a structured workflow, scaffolding assets, and supporting integrations that help users move from an idea to a defined specification, an implementation plan, task breakdowns, and executable project work. - -From a maintainer perspective, the repository is not just "documentation" and not just "code". It is a coordinated system composed of several interacting surfaces: - -- workflow-defining templates, -- command and scaffolding assets, -- scripts and automation helpers, -- CLI and installation behavior, -- agent-specific integration surfaces, -- extension and preset publishing assets, -- documentation that explains and stabilizes the user and developer model. +| `extensions/` | Extension-related docs, catalogs, and supporting assets. | +| `presets/` | Preset-related docs, catalogs, and supporting assets. | -Maintaining Spec Kit means preserving coherence across those surfaces. A change in one layer often affects documentation, validation expectations, and user-visible workflow behavior in other layers. +These documents and repository surfaces form the minimum context needed to reason about changes safely. Maintaining Spec Kit means preserving coherence across those surfaces. A change in one layer often affects documentation, validation expectations, and user-visible workflow behavior in other layers. ## System Mental Model From b49fa02ede8ba0cf7c10adf28893e19e2a13be72 Mon Sep 17 00:00:00 2001 From: PChemGuy <39730837+pchemguy@users.noreply.github.com> Date: Thu, 2 Apr 2026 22:00:08 +0300 Subject: [PATCH 11/25] Update DEVELOPMENT.md --- DEVELOPMENT.md | 59 +------------------------------------------------- 1 file changed, 1 insertion(+), 58 deletions(-) diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index e1fe8e725..b7a6bf5f4 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -4,7 +4,7 @@ This document is the primary entry point for people modifying Spec Kit itself. U ## Maintainer Orientation -Spec Kit is a toolkit for spec-driven development. It provides the workflow, scaffolding assets, and supporting integrations that turn an idea into a specification, an implementation plan, task breakdowns, and executable project work. From a maintainer perspective, the repository is not just documentation and not just code. It is a coordinated system whose templates, scripts, CLI, agent integrations, extensions, presets, and documentation must remain aligned. +Spec Kit is a toolkit for spec-driven development. At its core, it is a coordinated set of prompts, templates, scripts, and CLI/integration assets that define and deliver a spec-driven workflow for AI coding agents. The tables below summarize the essential project documents and main repository surfaces for developers. **Essential project documents:** @@ -28,50 +28,6 @@ Spec Kit is a toolkit for spec-driven development. It provides the workflow, sca | `extensions/` | Extension-related docs, catalogs, and supporting assets. | | `presets/` | Preset-related docs, catalogs, and supporting assets. | -These documents and repository surfaces form the minimum context needed to reason about changes safely. Maintaining Spec Kit means preserving coherence across those surfaces. A change in one layer often affects documentation, validation expectations, and user-visible workflow behavior in other layers. - -## System Mental Model - -### Core User Workflow - -At a high level, Spec Kit supports a staged workflow in which a user moves through structured project definition and execution steps. The exact implementation details may vary by agent or integration surface, but the core conceptual flow is consistent: - -1. establish or refine governing project principles, -2. define a concrete specification, -3. derive an implementation plan, -4. derive an actionable task breakdown, -5. execute implementation against the defined artifacts. - -When changing Spec Kit, first identify which part of that lifecycle your change affects. - -### Source Assets vs Generated Project Assets - -A useful distinction for maintainers is the difference between: - -- **source assets in this repository**, and -- **artifacts that users consume in their own repositories or agent sessions**. - -Source assets in this repository define behavior, structure, wording, conventions, and scaffolding rules. Generated or installed assets are the user-facing outputs of those source assets. - -When editing repository files, think in terms of downstream consequences: - -- What will change in the user-visible workflow? -- What will change in generated project content? -- What must be revalidated manually in a real end-to-end flow? - -### Main System Surfaces - -Most changes fall into one or more of these surfaces: - -- **Templates**: define workflow artifacts, prompts, scaffolding content, and generated project structure. -- **Scripts and automation**: support local generation, packaging, installation, or validation flows. -- **CLI and bootstrap behavior**: define how users initialize, install, or execute Spec Kit workflows. -- **Agent integration surfaces**: adapt the kit to specific agent environments without changing the underlying workflow intent. -- **Extensions and presets**: package additional reusable behavior or opinionated configurations. -- **Documentation**: explain the intended model, workflow, usage, and maintenance practices. - -A contributor should be able to identify which surface they are editing before making a change. - ## Repository Anatomy This section explains the role of the major repository areas. It is intended as a guided map, not a full file inventory. @@ -151,19 +107,6 @@ Edit `presets/` when you are: Presets should remain understandable as opinionated selections layered on top of the core workflow, not as silent redefinitions of that workflow. -### Documentation Surface - -Top-level and subsystem documentation explains the user model, maintainer model, testing expectations, and publishing flows. - -Edit documentation whenever code, templates, scripts, or workflow semantics change in a way that affects: - -- user understanding, -- contributor understanding, -- validation expectations, -- extension or preset author behavior. - -Do not treat docs as an afterthought. In Spec Kit, documentation is part of the product surface. - ## Change Map: If You Want to Change X, Edit Y This section is a practical routing guide. Use it before making edits. From 4001de2ec874333338bc15776d15ae8a775d2afb Mon Sep 17 00:00:00 2001 From: PChemGuy <39730837+pchemguy@users.noreply.github.com> Date: Thu, 2 Apr 2026 22:14:26 +0300 Subject: [PATCH 12/25] Compact DEVELOPMENT.md --- DEVELOPMENT.md | 348 +------------ Development Guide Dev/Untitled 1.md | 458 ------------------ Development Guide Dev/Untitled 2.md | 12 - Development Guide Dev/Untitled.md | 364 -------------- Development Guide Dev/deep-research-report.md | 188 ------- 5 files changed, 11 insertions(+), 1359 deletions(-) delete mode 100644 Development Guide Dev/Untitled 1.md delete mode 100644 Development Guide Dev/Untitled 2.md delete mode 100644 Development Guide Dev/Untitled.md delete mode 100644 Development Guide Dev/deep-research-report.md diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index b7a6bf5f4..03b46b31d 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -1,351 +1,25 @@ -# Development Guide +# Development Notes -This document is the primary entry point for people modifying Spec Kit itself. Use this guide when you need to understand how the repository fits together, where different kinds of changes belong, how to validate them, and which deeper documents to read next. This document is intentionally focused on system understanding, repository navigation, and change workflows. - -## Maintainer Orientation - -Spec Kit is a toolkit for spec-driven development. At its core, it is a coordinated set of prompts, templates, scripts, and CLI/integration assets that define and deliver a spec-driven workflow for AI coding agents. The tables below summarize the essential project documents and main repository surfaces for developers. +Spec Kit is a toolkit for spec-driven development. At its core, it is a coordinated set of prompts, templates, scripts, and CLI/integration assets that define and deliver a spec-driven workflow for AI coding agents. This document is a starting point for people modifying Spec Kit itself, with a compact orientation to the key project documents and repository organization. **Essential project documents:** | Document | Role | | --- | --- | | [README.md](./README.md) | Primary user-facing overview of Spec Kit and its workflow. | -| [DEVELOPMENT.md](./DEVELOPMENT.md) | Primary maintainer-facing guide to modifying Spec Kit itself. | +| [DEVELOPMENT.md](./DEVELOPMENT.md) | This document. | | [spec-driven.md](./spec-driven.md) | End-to-end explanation of the Spec-Driven Development workflow supported by Spec Kit. | | [RELEASE-PROCESS.md](./.github/workflows/RELEASE-PROCESS.md) | Release workflow, versioning rules, and changelog generation process. | | [docs/index.md](./docs/index.md) | Entry point to the `docs/` documentation set. | | [CONTRIBUTING.md](./CONTRIBUTING.md) | Contribution process, review expectations, and required development practices. | | [TESTING.md](./TESTING.md) | Validation strategy and testing procedures. | -**Main repository surfaces:** - -| Directory | Role | -| --- | --- | -| `templates/` | Prompt assets and templates that define the core workflow behavior and generated artifacts. | -| `scripts/` | Supporting scripts used by the workflow, setup, and repository tooling. | -| `src/specify_cli/` | Python source for the `specify` CLI, including agent-specific assets. | -| `extensions/` | Extension-related docs, catalogs, and supporting assets. | -| `presets/` | Preset-related docs, catalogs, and supporting assets. | - -## Repository Anatomy - -This section explains the role of the major repository areas. It is intended as a guided map, not a full file inventory. - -### `templates/` - -This directory contains the core workflow and content assets that shape the user experience. In many cases, this is the most important part of the repository because it defines the structure and wording of the spec-driven workflow itself. - -Edit `templates/` when you are changing: - -- generated artifact structure, -- workflow prompt wording, -- command or template content, -- default project scaffolding semantics. - -Treat template changes as behavior changes, not as passive documentation edits. Even small text changes can alter how users and agents interpret the workflow. - -### `scripts/` - -This directory contains automation and helper logic used for validation, packaging, generation, or related maintenance tasks. - -Edit `scripts/` when you are changing: - -- automation that supports local development, -- packaging or build helpers, -- maintenance utilities, -- validation support logic. - -Script changes should be validated both for local correctness and for their role in the broader development workflow. - -### CLI and Package Code - -Where applicable, repository code for installation, bootstrap, packaging, or command execution defines how Spec Kit is delivered and invoked. - -Edit the CLI or package code when you are changing: - -- installation behavior, -- initialization flow, -- local command behavior, -- execution semantics exposed to users. - -Changes here are usually high-impact because they affect how users enter the system. - -### Memory and Governing Assets - -Some repository assets define persistent project conventions, constitutions, or other workflow-governing content. - -Edit these assets when you are changing: - -- core workflow assumptions, -- project constitution defaults, -- stable behavioral expectations carried across the kit. - -These changes often require corresponding documentation updates because they affect the conceptual model, not just wording. - -### `extensions/` - -This area supports extension mechanisms and related publishing flows. - -Edit `extensions/` when you are: - -- adding a new extension, -- modifying extension behavior, -- updating extension packaging or publishing guidance. - -Extension changes should preserve compatibility with the main Spec Kit model unless the extension is explicitly intended to be a bounded deviation. - -### `presets/` - -This area supports reusable preset configurations and their publishing workflows. - -Edit `presets/` when you are: - -- adding a new preset, -- changing how presets are defined, -- updating preset publishing or maintenance logic. - -Presets should remain understandable as opinionated selections layered on top of the core workflow, not as silent redefinitions of that workflow. - -## Change Map: If You Want to Change X, Edit Y - -This section is a practical routing guide. Use it before making edits. - -### Change generated specification or planning content - -Start with the relevant files under `templates/`. - -Typical examples: - -- generated spec wording, -- plan structure, -- task generation wording, -- default scaffolded project artifacts. - -### Change workflow behavior or sequencing - -Inspect the relevant templates first, then any supporting script or CLI logic that participates in workflow execution. - -Typical examples: - -- command flow changes, -- stage ordering changes, -- added or removed workflow steps, -- changes in how generated assets reference one another. - -### Change installation or bootstrap behavior - -Inspect CLI or package code, install helpers, and any supporting scripts involved in setup or initialization. - -Typical examples: - -- init behavior, -- install commands, -- local executable behavior, -- package layout expectations. - -### Change user-facing documentation - -Update `README.md` and any other user-facing docs affected by the change. If the workflow model changes, also update any supporting conceptual documentation so the documented model remains aligned with actual behavior. - -### Change contributor-facing guidance - -Update `DEVELOPMENT.md`, `CONTRIBUTING.md`, `TESTING.md`, or more specialized contributor documentation as appropriate. - -### Change extension behavior or extension publishing - -Start in `extensions/` and then update related publishing guidance and any ecosystem references. - -### Change preset behavior or preset publishing - -Start in `presets/` and then update related publishing guidance and any ecosystem references. - -### Change system-wide conceptual assumptions - -Treat the change as cross-cutting. Review templates, governing assets, docs, validation expectations, and any affected packaging or integration surfaces together. - -## Development Workflows - -This section describes the normal paths for common kinds of changes. - -### Template Change Workflow - -Use this workflow when changing prompt content, generated artifact structure, or other template-defined behavior. - -1. Identify the exact user-visible behavior that should change. -2. Locate the relevant template files. -3. Make the smallest coherent change that expresses the intended behavior. -4. Review adjacent templates for consistency. -5. Update documentation if the conceptual or visible behavior changed. -6. Validate the change through focused checks and at least one realistic end-to-end flow. - -For template changes, wording is behavior. Treat wording edits with the same care as code changes. - -### Script Change Workflow - -Use this workflow when changing repository automation or support utilities. - -1. Identify the workflow that depends on the script. -2. Edit the relevant script with minimal scope. -3. Validate the script directly. -4. Validate the higher-level workflow that depends on it. -5. Update docs if the script changes how contributors or users are expected to work. - -### CLI or Bootstrap Change Workflow - -Use this workflow when changing how users enter or operate Spec Kit through commands or package installation. - -1. Identify the affected command or entry path. -2. Trace the code and any related templates or scripts. -3. Make the change with attention to backward compatibility and user expectations. -4. Validate the affected command locally. -5. Validate at least one realistic user entry flow end to end. -6. Update user-facing and developer-facing docs as needed. - -### Docs-Only Workflow - -Use this workflow when making documentation changes that do not intentionally alter behavior. - -1. Confirm that the change is actually documentation-only. -2. Update the relevant docs. -3. Check for overlap with other docs that may now be inconsistent. -4. Ensure terminology remains aligned across documents. - -Be cautious: many apparent "docs-only" changes in this repository are actually behavioral if they describe workflow semantics that templates or scripts already implement. - -### Extension or Preset Workflow - -Use this workflow when changing extension or preset assets. - -1. Identify whether the change affects the core model or only the extension/preset layer. -2. Edit the relevant extension or preset files. -3. Validate packaging, discoverability, and usage expectations. -4. Update publishing and maintenance guidance where needed. -5. Ensure the relationship to core Spec Kit remains explicit. - -## Validation and Testing Map - -This section is a routing summary. For detailed procedures, see `TESTING.md` and related validation documentation. - -### Focused Local Validation - -Use focused validation first when changing a narrow part of the system. - -Examples include: - -- validating the specific template you changed, -- running the script you modified, -- exercising the CLI path you edited, -- checking a packaging or publishing path affected by your change. - -### End-to-End Workflow Validation - -Use realistic manual validation when the change affects user-visible workflow semantics. - -This is especially important for: - -- template changes, -- command flow changes, -- initialization or bootstrap changes, -- agent-facing workflow changes. - -A change is not well validated if it only passes isolated checks but has not been exercised in a real workflow context. - -### Documentation Validation - -When behavior changes, documentation must be checked for alignment. This includes: - -- top-level user docs, -- maintainer docs, -- subsystem docs, -- extension or preset publishing docs. - -### Packaging and Distribution Validation - -When changing install, release, extension, or preset behavior, confirm that the change remains correct in the form users actually consume. - -Do not assume that source-level correctness is sufficient. - -## Architectural Invariants and Guardrails - -The following guardrails should remain true unless there is an explicit, repository-wide decision to change them. - -### Preserve Workflow Coherence - -The core spec-driven workflow should remain understandable as a staged progression from governing principles to specification, planning, tasking, and execution. - -Do not introduce local optimizations that make the overall model less coherent. - -### Preserve Cross-Surface Alignment - -Templates, scripts, CLI behavior, and docs should describe the same system. - -A contributor should not be able to follow the docs and encounter materially different behavior in the actual workflow. - -### Treat Templates as Product Logic - -Template wording, structure, and default content are part of the product, not just decoration. - -Do not make casual wording changes without considering behavioral consequences. - -### Keep Agent-Specific Adaptation Secondary to the Core Model - -Agent-specific support is important, but it should adapt the core workflow rather than fragment it into unrelated systems unless such divergence is deliberate and documented. - -### Keep Extensions and Presets Legible - -Extensions and presets should remain understandable additions or variations, not opaque redefinitions of the core workflow. - -## Common Pitfalls - -The following mistakes are easy to make in this repository. - -### Treating a Template Edit as a Mere Copy Change - -Template wording often changes behavior. Review it the same way you would review logic changes. - -### Updating One Surface but Not the Others - -A workflow change may require updates in templates, docs, tests, and installation or execution behavior. Check for cross-surface impact before considering the work complete. - -### Validating Too Narrowly - -A focused unit check may pass while the real user workflow is broken. Use end-to-end validation when the change affects behavior users or agents actually experience. - -### Letting Contributor Docs Drift - -When the repository structure or maintainer workflow changes, `DEVELOPMENT.md` and related docs need to change too. - -### Hiding a Conceptual Change Inside a Small Edit - -If a change alters the mental model or expected workflow, document it as such. Do not let significant semantic changes masquerade as tiny text cleanups. - -## Release and Compatibility Notes - -When making changes that affect packaging, installation, extensions, presets, or generated outputs, consider compatibility from the perspective of actual users and downstream maintainers. - -Questions to ask: - -Does this change - -- alter the expected workflow? -- affect generated artifacts? -- require documentation updates? -- affect extension or preset compatibility? -- need explicit release-note treatment? - -When in doubt, assume user-visible workflow changes deserve explicit documentation and release awareness. - -## Keeping This Document Healthy - -This document should evolve with the repository. - -Update it when: - -- repository structure changes, -- the maintainer mental model changes, -- new core subsystems are introduced, -- the recommended development workflow changes, -- the document map needs rerouting. +**Main repository components:** -The goal is to keep this file useful as a top-level maintainer entry point, not to turn it into an exhaustive reference manual. +| Directory | Role | +| ------------------ | ------------------------------------------------------------------------------------------- | +| `templates/` | Prompt assets and templates that define the core workflow behavior and generated artifacts. | +| `scripts/` | Supporting scripts used by the workflow, setup, and repository tooling. | +| `src/specify_cli/` | Python source for the `specify` CLI, including agent-specific assets. | +| `extensions/` | Extension-related docs, catalogs, and supporting assets. | +| `presets/` | Preset-related docs, catalogs, and supporting assets. | diff --git a/Development Guide Dev/Untitled 1.md b/Development Guide Dev/Untitled 1.md deleted file mode 100644 index 4454c598d..000000000 --- a/Development Guide Dev/Untitled 1.md +++ /dev/null @@ -1,458 +0,0 @@ -# Development Guide - -This document is the primary entry point for people modifying Spec Kit itself. - -Use this guide when you need to understand how the repository fits together, where different kinds of changes belong, how to validate them, and which deeper documents to read next. - -## Relationship to Other Top-Level Documents - -Spec Kit has several top-level documents with different roles. They should not duplicate each other. - -- `README.md` is the primary entry point for users adopting Spec Kit in a project. -- `DEVELOPMENT.md` is the primary entry point for contributors and maintainers changing Spec Kit itself. -- `CONTRIBUTING.md` defines contribution mechanics, review expectations, and required development practices. -- `TESTING.md` describes validation strategy and testing procedures in more detail. -- Other specialized documents cover specific subsystems or publishing workflows. - -This document is intentionally focused on system understanding, repository navigation, and change workflows. - -## What Spec Kit Is, from a Maintainer Perspective - -Spec Kit is a toolkit for spec-driven development. It provides a structured workflow, scaffolding assets, and supporting integrations that help users move from an idea to a defined specification, an implementation plan, task breakdowns, and executable project work. - -From a maintainer perspective, the repository is not just "documentation" and not just "code". It is a coordinated system composed of several interacting surfaces: - -- workflow-defining templates, -- command and scaffolding assets, -- scripts and automation helpers, -- CLI and installation behavior, -- agent-specific integration surfaces, -- extension and preset publishing assets, -- documentation that explains and stabilizes the user and developer model. - -Maintaining Spec Kit means preserving coherence across those surfaces. A change in one layer often affects documentation, validation expectations, and user-visible workflow behavior in other layers. - -## System Mental Model - -### Core User Workflow - -At a high level, Spec Kit supports a staged workflow in which a user moves through structured project definition and execution steps. The exact implementation details may vary by agent or integration surface, but the core conceptual flow is consistent: - -1. establish or refine governing project principles, -2. define a concrete specification, -3. derive an implementation plan, -4. derive an actionable task breakdown, -5. execute implementation against the defined artifacts. - -When changing Spec Kit, first identify which part of that lifecycle your change affects. - -### Source Assets vs Generated Project Assets - -A useful distinction for maintainers is the difference between: - -- **source assets in this repository**, and -- **artifacts that users consume in their own repositories or agent sessions**. - -Source assets in this repository define behavior, structure, wording, conventions, and scaffolding rules. Generated or installed assets are the user-facing outputs of those source assets. - -When editing repository files, think in terms of downstream consequences: - -- What will change in the user-visible workflow? -- What will change in generated project content? -- What must be revalidated manually in a real end-to-end flow? - -### Main System Surfaces - -Most changes fall into one or more of these surfaces: - -- **Templates**: define workflow artifacts, prompts, scaffolding content, and generated project structure. -- **Scripts and automation**: support local generation, packaging, installation, or validation flows. -- **CLI and bootstrap behavior**: define how users initialize, install, or execute Spec Kit workflows. -- **Agent integration surfaces**: adapt the kit to specific agent environments without changing the underlying workflow intent. -- **Extensions and presets**: package additional reusable behavior or opinionated configurations. -- **Documentation**: explain the intended model, workflow, usage, and maintenance practices. - -A contributor should be able to identify which surface they are editing before making a change. - -## Repository Anatomy - -This section explains the role of the major repository areas. It is intended as a guided map, not a full file inventory. - -### `templates/` - -This directory contains the core workflow and content assets that shape the user experience. In many cases, this is the most important part of the repository because it defines the structure and wording of the spec-driven workflow itself. - -Edit `templates/` when you are changing: - -- generated artifact structure, -- workflow prompt wording, -- command or template content, -- default project scaffolding semantics. - -Treat template changes as behavior changes, not as passive documentation edits. Even small text changes can alter how users and agents interpret the workflow. - -### `scripts/` - -This directory contains automation and helper logic used for validation, packaging, generation, or related maintenance tasks. - -Edit `scripts/` when you are changing: - -- automation that supports local development, -- packaging or build helpers, -- maintenance utilities, -- validation support logic. - -Script changes should be validated both for local correctness and for their role in the broader development workflow. - -### CLI and Package Code - -Where applicable, repository code for installation, bootstrap, packaging, or command execution defines how Spec Kit is delivered and invoked. - -Edit the CLI or package code when you are changing: - -- installation behavior, -- initialization flow, -- local command behavior, -- execution semantics exposed to users. - -Changes here are usually high-impact because they affect how users enter the system. - -### Memory and Governing Assets - -Some repository assets define persistent project conventions, constitutions, or other workflow-governing content. - -Edit these assets when you are changing: - -- core workflow assumptions, -- project constitution defaults, -- stable behavioral expectations carried across the kit. - -These changes often require corresponding documentation updates because they affect the conceptual model, not just wording. - -### `extensions/` - -This area supports extension mechanisms and related publishing flows. - -Edit `extensions/` when you are: - -- adding a new extension, -- modifying extension behavior, -- updating extension packaging or publishing guidance. - -Extension changes should preserve compatibility with the main Spec Kit model unless the extension is explicitly intended to be a bounded deviation. - -### `presets/` - -This area supports reusable preset configurations and their publishing workflows. - -Edit `presets/` when you are: - -- adding a new preset, -- changing how presets are defined, -- updating preset publishing or maintenance logic. - -Presets should remain understandable as opinionated selections layered on top of the core workflow, not as silent redefinitions of that workflow. - -### Documentation Surface - -Top-level and subsystem documentation explains the user model, maintainer model, testing expectations, and publishing flows. - -Edit documentation whenever code, templates, scripts, or workflow semantics change in a way that affects: - -- user understanding, -- contributor understanding, -- validation expectations, -- extension or preset author behavior. - -Do not treat docs as an afterthought. In Spec Kit, documentation is part of the product surface. - -## Change Map: If You Want to Change X, Edit Y - -This section is a practical routing guide. Use it before making edits. - -### Change generated specification or planning content - -Start with the relevant files under `templates/`. - -Typical examples: - -- generated spec wording, -- plan structure, -- task generation wording, -- default scaffolded project artifacts. - -### Change workflow behavior or sequencing - -Inspect the relevant templates first, then any supporting script or CLI logic that participates in workflow execution. - -Typical examples: - -- command flow changes, -- stage ordering changes, -- added or removed workflow steps, -- changes in how generated assets reference one another. - -### Change installation or bootstrap behavior - -Inspect CLI or package code, install helpers, and any supporting scripts involved in setup or initialization. - -Typical examples: - -- init behavior, -- install commands, -- local executable behavior, -- package layout expectations. - -### Change user-facing documentation - -Update `README.md` and any other user-facing docs affected by the change. If the workflow model changes, also update any supporting conceptual documentation so the documented model remains aligned with actual behavior. - -### Change contributor-facing guidance - -Update `DEVELOPMENT.md`, `CONTRIBUTING.md`, `TESTING.md`, or more specialized contributor documentation as appropriate. - -### Change extension behavior or extension publishing - -Start in `extensions/` and then update related publishing guidance and any ecosystem references. - -### Change preset behavior or preset publishing - -Start in `presets/` and then update related publishing guidance and any ecosystem references. - -### Change system-wide conceptual assumptions - -Treat the change as cross-cutting. Review templates, governing assets, docs, validation expectations, and any affected packaging or integration surfaces together. - -## Development Workflows - -This section describes the normal paths for common kinds of changes. - -### Template Change Workflow - -Use this workflow when changing prompt content, generated artifact structure, or other template-defined behavior. - -1. Identify the exact user-visible behavior that should change. -2. Locate the relevant template files. -3. Make the smallest coherent change that expresses the intended behavior. -4. Review adjacent templates for consistency. -5. Update documentation if the conceptual or visible behavior changed. -6. Validate the change through focused checks and at least one realistic end-to-end flow. - -For template changes, wording is behavior. Treat wording edits with the same care as code changes. - -### Script Change Workflow - -Use this workflow when changing repository automation or support utilities. - -1. Identify the workflow that depends on the script. -2. Edit the relevant script with minimal scope. -3. Validate the script directly. -4. Validate the higher-level workflow that depends on it. -5. Update docs if the script changes how contributors or users are expected to work. - -### CLI or Bootstrap Change Workflow - -Use this workflow when changing how users enter or operate Spec Kit through commands or package installation. - -1. Identify the affected command or entry path. -2. Trace the code and any related templates or scripts. -3. Make the change with attention to backward compatibility and user expectations. -4. Validate the affected command locally. -5. Validate at least one realistic user entry flow end to end. -6. Update user-facing and developer-facing docs as needed. - -### Docs-Only Workflow - -Use this workflow when making documentation changes that do not intentionally alter behavior. - -1. Confirm that the change is actually documentation-only. -2. Update the relevant docs. -3. Check for overlap with other docs that may now be inconsistent. -4. Ensure terminology remains aligned across documents. - -Be cautious: many apparent "docs-only" changes in this repository are actually behavioral if they describe workflow semantics that templates or scripts already implement. - -### Extension or Preset Workflow - -Use this workflow when changing extension or preset assets. - -1. Identify whether the change affects the core model or only the extension/preset layer. -2. Edit the relevant extension or preset files. -3. Validate packaging, discoverability, and usage expectations. -4. Update publishing and maintenance guidance where needed. -5. Ensure the relationship to core Spec Kit remains explicit. - -## Validation and Testing Map - -This section is a routing summary. For detailed procedures, see `TESTING.md` and related validation documentation. - -### Focused Local Validation - -Use focused validation first when changing a narrow part of the system. - -Examples include: - -- validating the specific template you changed, -- running the script you modified, -- exercising the CLI path you edited, -- checking a packaging or publishing path affected by your change. - -### End-to-End Workflow Validation - -Use realistic manual validation when the change affects user-visible workflow semantics. - -This is especially important for: - -- template changes, -- command flow changes, -- initialization or bootstrap changes, -- agent-facing workflow changes. - -A change is not well validated if it only passes isolated checks but has not been exercised in a real workflow context. - -### Documentation Validation - -When behavior changes, documentation must be checked for alignment. This includes: - -- top-level user docs, -- maintainer docs, -- subsystem docs, -- extension or preset publishing docs. - -### Packaging and Distribution Validation - -When changing install, release, extension, or preset behavior, confirm that the change remains correct in the form users actually consume. - -Do not assume that source-level correctness is sufficient. - -## Documentation Map - -This section routes contributors to the right deeper documents. - -### `README.md` - -Primary user-facing introduction. - -Read this when you need to understand how the repository presents itself to adopters and what promises are made to users. - -### `CONTRIBUTING.md` - -Contribution process, expectations, and contribution hygiene. - -Read this before opening a pull request or when you need the repository's current contribution rules. - -### `TESTING.md` - -Validation strategy and test guidance. - -Read this when planning or executing validation for non-trivial changes. - -### Extension Publishing Documentation - -Read the extension-specific publishing guide when working on extension creation, packaging, or publication. - -### Preset Publishing Documentation - -Read the preset-specific publishing guide when working on preset creation, packaging, or publication. - -### Other Specialized Documents - -Read subsystem-specific documents when your change targets a specific area rather than the core maintainer workflow. - -As the repository evolves, keep this section curated. It should remain a developer routing table, not a raw list of markdown files. - -## Architectural Invariants and Guardrails - -The following guardrails should remain true unless there is an explicit, repository-wide decision to change them. - -### Preserve Workflow Coherence - -The core spec-driven workflow should remain understandable as a staged progression from governing principles to specification, planning, tasking, and execution. - -Do not introduce local optimizations that make the overall model less coherent. - -### Preserve Cross-Surface Alignment - -Templates, scripts, CLI behavior, and docs should describe the same system. - -A contributor should not be able to follow the docs and encounter materially different behavior in the actual workflow. - -### Treat Templates as Product Logic - -Template wording, structure, and default content are part of the product, not just decoration. - -Do not make casual wording changes without considering behavioral consequences. - -### Keep Agent-Specific Adaptation Secondary to the Core Model - -Agent-specific support is important, but it should adapt the core workflow rather than fragment it into unrelated systems unless such divergence is deliberate and documented. - -### Keep Extensions and Presets Legible - -Extensions and presets should remain understandable additions or variations, not opaque redefinitions of the core workflow. - -## Common Pitfalls - -The following mistakes are easy to make in this repository. - -### Treating a Template Edit as a Mere Copy Change - -Template wording often changes behavior. Review it the same way you would review logic changes. - -### Updating One Surface but Not the Others - -A workflow change may require updates in templates, docs, tests, and installation or execution behavior. Check for cross-surface impact before considering the work complete. - -### Validating Too Narrowly - -A focused unit check may pass while the real user workflow is broken. Use end-to-end validation when the change affects behavior users or agents actually experience. - -### Letting Contributor Docs Drift - -When the repository structure or maintainer workflow changes, `DEVELOPMENT.md` and related docs need to change too. - -### Hiding a Conceptual Change Inside a Small Edit - -If a change alters the mental model or expected workflow, document it as such. Do not let significant semantic changes masquerade as tiny text cleanups. - -## Release and Compatibility Notes - -When making changes that affect packaging, installation, extensions, presets, or generated outputs, consider compatibility from the perspective of actual users and downstream maintainers. - -Questions to ask: - -Does this change - -- alter the expected workflow? -- affect generated artifacts? -- require documentation updates? -- affect extension or preset compatibility? -- need explicit release-note treatment? - -When in doubt, assume user-visible workflow changes deserve explicit documentation and release awareness. - -## Maintainer Onboarding Checklist - -A new maintainer should usually do the following before making broad changes: - -1. read `README.md` to understand the user-facing model, -2. read this document to understand the maintainer-facing model, -3. read `CONTRIBUTING.md` before preparing changes, -4. read `TESTING.md` before validating non-trivial work, -5. inspect the repository layout, especially `templates/`, `scripts/`, and any CLI or packaging code, -6. trace at least one representative end-to-end workflow, -7. start with a narrow, well-scoped change before attempting structural revisions. - -## Keeping This Document Healthy - -This document should evolve with the repository. - -Update it when: - -- repository structure changes, -- the maintainer mental model changes, -- new core subsystems are introduced, -- the recommended development workflow changes, -- the document map needs rerouting. - -The goal is to keep this file useful as a top-level maintainer entry point, not to turn it into an exhaustive reference manual. diff --git a/Development Guide Dev/Untitled 2.md b/Development Guide Dev/Untitled 2.md deleted file mode 100644 index adfccb663..000000000 --- a/Development Guide Dev/Untitled 2.md +++ /dev/null @@ -1,12 +0,0 @@ -Top-level documents are not sufficient for full onboarding. Before editing, read the relevant subsystem documentation for the surface you plan to modify. - -Use the following routing guide. - -| If you plan to change... | Read... | -| -------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | -| Core workflow templates and generated artifact structure | The relevant documents under `templates/` and any linked workflow-specific documentation | -| Validation behavior or test expectations | [TESTING.md](./TESTING.md) and any related subsystem-specific testing documentation | -| Extensions | The documentation under `extensions/`, including extension publishing and maintenance guidance | -| Presets | The documentation under `presets/`, including preset publishing and maintenance guidance | -| User-facing workflow semantics | The relevant templates, [README.md](./README.md), and any conceptual workflow documentation | -| Installation, packaging, or bootstrap behavior | The relevant CLI/package code, scripts, and associated development or publishing documentation | diff --git a/Development Guide Dev/Untitled.md b/Development Guide Dev/Untitled.md deleted file mode 100644 index 761bacda7..000000000 --- a/Development Guide Dev/Untitled.md +++ /dev/null @@ -1,364 +0,0 @@ -Yes, it makes sense. - -A top-level `DEVELOPMENT.md` is a good fit here because the current `README.md` is clearly optimized for users adopting Spec Kit in projects, while `CONTRIBUTING.md` is narrower: contribution mechanics, validation flow, and PR hygiene. It is not really a full developer mental-model document. The repo also already has specialized docs like `TESTING.md`, the extension publishing guide, and preset publishing guide, which means a developer-facing entry document should primarily orient, map, and route rather than duplicate details. ([GitHub][1]) - -I would treat `DEVELOPMENT.md` as the **developer map of the system**: - -* what Spec Kit is internally, -* how the repository is organized, -* how the main moving parts interact, -* where to edit for each class of change, -* how to validate changes, -* and where deeper docs live. - That is the missing layer between user docs and contribution rules. ([GitHub][1]) - -## What `DEVELOPMENT.md` should do - -It should not try to be: - -* another `README.md`, -* another `CONTRIBUTING.md`, -* or a giant reference manual. - -It should be the **primary entry point for maintainers and contributors who need system understanding before editing**. - -The right emphasis is: - -1. mental model, -2. repository anatomy, -3. change workflows, -4. document map, -5. common modification scenarios. - -That is especially important in this repo because the core is not just Python code; it is a coordinated kit of templates, scripts, CLI behavior, agent integrations, memory files, extensions, presets, and documentation. The current docs already imply this multi-part system, but they are distributed across several places. ([GitHub][2]) - -## Recommended top-level structure - -Here is the outline I would use. - -### 1. Purpose of this document - -Very short. Explain that: - -* `README.md` is for users adopting Spec Kit, -* `DEVELOPMENT.md` is for people modifying Spec Kit itself, -* `CONTRIBUTING.md` covers contribution process and PR expectations, -* deeper component docs are linked below. ([GitHub][2]) - -### 2. What Spec Kit is, from a maintainer perspective - -Give a concise internal framing, for example: - -* Spec Kit is a toolkit for Spec-Driven Development. -* The repo packages prompts/templates, command scaffolding, scripts, CLI support, agent-specific integration assets, and ecosystem mechanisms such as extensions and presets. -* The generated user workflow is roughly: constitution → specify → plan → tasks → implement. ([GitHub][1]) - -This section should answer: **what are we actually maintaining?** - -### 3. System mental model - -This is one of the most important sections. - -Suggested subsections: - -* **Core artifact flow** - How the main SDD flow progresses through constitution, specification, plan, tasks, implementation. ([GitHub][1]) -* **Delivery model** - Clarify what lives in the repo versus what gets installed/scaffolded into user projects. -* **Main abstraction layers** - For example: - - * templates/content, - * command scaffolding, - * CLI/bootstrap/install logic, - * agent-specific integration surfaces, - * extension/preset ecosystem, - * docs/catalog/community surfaces. - -A simple diagram would help a lot here. - -### 4. Repository anatomy - -This should be a guided map, not just a tree dump. - -For each major top-level area, explain: - -* what it contains, -* why it exists, -* when to edit it, -* what else it interacts with. - -You already mentioned this, and yes, it should absolutely be included. - -Likely subsections: - -* `templates/` — core artifact templates and command templates; probably the most important content layer for generated workflow behavior. The repo README and contribution workflow both point contributors to template validation. ([GitHub][2]) -* `scripts/` — automation/bootstrap/helper scripts; `CONTRIBUTING.md` explicitly calls out script functionality as something contributors should test. ([GitHub][2]) -* `memory/` or `.specify/memory`-related assets — constitution/project-memory behavior; contribution guidance explicitly references `memory/constitution.md` updates for major process changes. ([GitHub][2]) -* CLI/package code — where install/scaffold behavior and local `specify` execution live. -* `extensions/` — extension model and publishing support; the repo includes a dedicated extension publishing guide. ([GitHub][3]) -* `presets/` — preset model and publishing support; there is also a dedicated presets publishing guide. ([GitHub][4]) -* catalogs/community metadata — where ecosystem discoverability is maintained; the README includes community extensions, presets, walkthroughs, and related ecosystem surfaces. ([GitHub][5]) -* top-level docs — which are user docs, contributor docs, testing docs, release docs, etc. - -### 5. “If you want to change X, edit Y” - -This is the most practical section, and many repos miss it. - -Examples: - -* To change the wording/structure of generated feature specs → edit relevant template files. -* To change slash-command behavior or workflow sequencing → inspect command templates plus any supporting scripts/CLI glue. -* To change installation/bootstrap behavior → inspect CLI/package/bootstrap code. -* To add or modify extension publishing behavior → see `extensions/EXTENSION-PUBLISHING-GUIDE.md`. -* To add or modify presets behavior → see `presets/PUBLISHING.md`. -* To adjust docs shown to end users → update `README.md` and possibly `spec-driven.md`, which `CONTRIBUTING.md` explicitly names for user-facing changes. ([GitHub][2]) - -This section makes the doc operational instead of descriptive. - -### 6. End-to-end development workflows - -Not contribution policy in the abstract, but concrete developer workflows. - -Suggested subsections: - -* **Template change workflow** -* **Script change workflow** -* **CLI/bootstrap change workflow** -* **Docs-only workflow** -* **Extension/preset/catalog change workflow** - -For each: - -* where to edit, -* how to test locally, -* what docs to update, -* what regressions to watch for. - -This aligns well with the current contribution guidance, which already says to test CLI commands in an agent, verify templates in `templates/`, test scripts in `scripts/`, and update memory/docs where relevant. ([GitHub][2]) - -### 7. Validation and testing map - -Do not restate all of `TESTING.md`. Instead, summarize the validation layers and link outward. - -Suggested structure: - -* quick local checks, -* focused automated checks, -* manual workflow tests in real agents, -* packaging/release-output validation, -* when each level is required. - -This matches the current recommended validation flow in `CONTRIBUTING.md`, which points developers to focused automated checks first, then manual workflow tests, then local release package inspection when needed. ([GitHub][2]) - -### 8. Documentation map - -This should be explicit and curated. - -A table works well: - -| Document | Audience | Purpose | When to read | -| -------- | -------- | ------- | ------------ | - -Include at least: - -* `README.md` -* `CONTRIBUTING.md` -* `TESTING.md` -* `spec-driven.md` -* `extensions/EXTENSION-PUBLISHING-GUIDE.md` -* `presets/PUBLISHING.md` -* maybe `CHANGELOG.md` and release-related docs if relevant. ([GitHub][2]) - -This section is especially valuable because the repo’s documentation surface has grown. - -### 9. Architectural invariants / guardrails - -This is another high-value section. - -List the things maintainers should preserve, such as: - -* user workflow consistency across supported agents, -* template and script changes should remain compatible with the expected SDD flow, -* generated artifacts and packaging should remain coherent, -* docs and templates must stay aligned, -* agent-specific adaptations should not silently break the general model. - -These should be framed as maintainer guardrails, not as vague philosophy. The README’s emphasis on the standard workflow and the contribution doc’s insistence on testing the CLI workflow with real agents strongly suggest this kind of invariant section is warranted. ([GitHub][1]) - -### 10. Common pitfalls - -Very useful for new contributors. - -Examples: - -* changing a template without validating it through an actual agent flow, -* updating docs but not generated behavior, -* changing workflow semantics without updating memory/process docs, -* forgetting ecosystem/catalog impact, -* testing only source form but not packaged output. ([GitHub][2]) - -### 11. Release-awareness and compatibility notes - -Brief section only. - -Could cover: - -* generated assets vs source assets, -* keeping changes compatible across agent modes, -* watching changelog/release behavior, -* any versioning expectations for templates/extensions/presets where applicable. ([GitHub][6]) - -### 12. Getting started as a maintainer - -A compact onboarding checklist: - -* read this document, -* read `CONTRIBUTING.md`, -* read `TESTING.md`, -* inspect repository layout, -* run local install, -* run representative workflow tests, -* make a narrow change first. - -## What else to include beyond your current idea - -Your instinct is right, but I would add four things that are easy to overlook: - -### A. A maintainer mental model, not just repository overview - -Without this, the document becomes a directory tour. - -The key question is: -**How do templates, scripts, CLI/bootstrap, docs, and ecosystem surfaces combine to produce the user experience?** - -That is the real “developer README”. - -### B. Change-oriented guidance - -The “if you want to change X, edit Y” section is disproportionately valuable. - -It reduces contributor hesitation and prevents wrong-entry-point edits. - -### C. Invariants / non-obvious rules - -These are the things experienced maintainers know but new contributors do not. - -For Spec Kit, that likely includes preserving the workflow sequence and validating changes in real agent flows rather than treating the repo as ordinary static docs. ([GitHub][2]) - -### D. A curated doc index - -Not a raw list of files. A role-based map. - -That is what turns scattered documentation into an actual developer entry point. - -## What not to do - -I would avoid: - -* duplicating installation instructions from `README.md`, -* duplicating PR policy from `CONTRIBUTING.md`, -* duplicating detailed test procedures from `TESTING.md`, -* documenting every file, -* writing a long historical narrative. - -`DEVELOPMENT.md` should stay navigational and architectural. - -## Suggested section order - -If you want a clean final shape, I would order it like this: - -1. Purpose of this document -2. Spec Kit at a glance for maintainers -3. System mental model -4. Repository anatomy -5. Change map: if you want to change X, edit Y -6. Development workflows -7. Validation and testing map -8. Documentation map -9. Architectural invariants and guardrails -10. Common pitfalls -11. Release and compatibility notes -12. Maintainer onboarding checklist - -## My recommendation on naming - -`DEVELOPMENT.md` is a reasonable name here. It is more natural than `README_DEV.md`. - -`README_DEV.md` is understandable, but it feels slightly ad hoc. `DEVELOPMENT.md` reads like a first-class top-level maintainer document and pairs well with `README.md`, `CONTRIBUTING.md`, `TESTING.md`, and `CHANGELOG.md`. That naming style is also consistent with the repo already having specialized top-level docs rather than overloading a second README. ([GitHub][2]) - -## A compact draft outline you can start from - -```md -# Development Guide - -## 1. Purpose -- Who this document is for -- How it differs from README.md and CONTRIBUTING.md - -## 2. Spec Kit for Maintainers -- What Spec Kit is internally -- Core workflow it supports -- Main system surfaces - -## 3. System Mental Model -### 3.1 Artifact and workflow lifecycle -### 3.2 Source assets vs generated/project assets -### 3.3 Templates, scripts, CLI, agent integrations, extensions, presets - -## 4. Repository Anatomy -### 4.1 templates/ -### 4.2 scripts/ -### 4.3 CLI/package code -### 4.4 memory assets -### 4.5 extensions/ -### 4.6 presets/ -### 4.7 catalogs and community metadata -### 4.8 top-level docs - -## 5. If You Want to Change X, Edit Y -- Generated artifact content -- Workflow behavior -- Installation/bootstrap -- Docs -- Extensions -- Presets -- Catalog/community entries - -## 6. Development Workflows -### 6.1 Template changes -### 6.2 Script changes -### 6.3 CLI/bootstrap changes -### 6.4 Docs-only changes -### 6.5 Extension/preset/catalog changes - -## 7. Validation and Testing Map -- Automated checks -- Manual agent-flow validation -- Packaged-output validation -- When each is needed - -## 8. Documentation Map -- README.md -- CONTRIBUTING.md -- TESTING.md -- spec-driven.md -- extension/preset publishing docs -- changelog/release docs - -## 9. Architectural Invariants -- Workflow consistency -- Cross-agent compatibility -- Docs/templates alignment -- Packaging/scaffolding integrity - -## 10. Common Pitfalls - -## 11. Release and Compatibility Notes - -## 12. Maintainer Onboarding Checklist -``` - -This is the structure I would use unless you want `DEVELOPMENT.md` to be intentionally shorter and more of a “developer landing page” that links out aggressively. - -I can turn this into a concrete first-pass `DEVELOPMENT.md` skeleton with section text, not just the outline. diff --git a/Development Guide Dev/deep-research-report.md b/Development Guide Dev/deep-research-report.md deleted file mode 100644 index c81ff9acb..000000000 --- a/Development Guide Dev/deep-research-report.md +++ /dev/null @@ -1,188 +0,0 @@ -# Deep research on Spec Kit development documentation coverage - -## Executive summary - -The GitHub github/spec-kit repository does contain **meaningful developer-oriented documentation** that explains *how templates fit into Spec Kit’s workflow*—especially in the main README.md, the DocFX-backed docs/ site sources, AGENTS.md, and the preset system documentation (presets/README.md \+ presets/ARCHITECTURE.md). These sources provide a workable mental model for the **Spec‑Driven Development (SDD) lifecycle**, and for **template resolution / overrides** (core vs extensions vs presets vs project overrides). - -However, the repository does **not** appear to contain a **single, systematic, developer-facing “Template System” guide** that (a) enumerates **every file under templates/**, (b) explains each one’s role in the pipeline, and (c) provides **glue/jump-start guidance** for maintainers (how to safely modify templates, keep scripts and command prompts aligned, and test changes end-to-end). The absence of an index/README inside templates/ and multiple “path confusion” / “template behavior confusion” issues suggest the mental model is dispersed and easy to miss. - -## Inventory and analysis of templates/ - -### Directory structure overview - -At the time of review (repo main), templates/ contains 7 top-level assets plus a commands/ subdirectory with 9 command templates (total: 16 files). - -### Table of all files under templates/ - -The “Developer-oriented guidance?” column below is strictly about **human-developer onboarding/mental model** content *inside the file itself* (as opposed to “LLM-facing instructions that a developer could reverse-engineer”). Many of these files primarily serve as **prompt directives/templates** for agents, which is useful but not the same as curated developer documentation. - -| File (path) | Purpose (what it is for) | Type | Developer-oriented guidance inside file? | -| :---------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------: | :--------------------------------------------------------------------------------------------------------------------------------------- | -| templates/agent-file-template.md | Skeleton for a generated “Development Guidelines” / agent context file (placeholders for technologies, structure, commands, recent changes, plus a manual-additions region). | md | **Partial**: structure \+ placeholders; minimal “why/how.” | -| templates/checklist-template.md | Output template for checklist artifacts; explicitly notes generation by /speckit.checklist and includes a large **“sample items must be replaced”** instruction block. | md | **Yes (light)**: explains it is command-generated and warns not to keep sample items. | -| templates/constitution-template.md | Placeholder constitution format (principles, governance, version metadata) with inline examples in comments. | md | **Partial**: examples hint at intent; not a full maintainer guide. | -| templates/plan-template.md | Output template for a feature’s implementation plan and design artifacts; includes “technical context,” constitution gate, project structure, and phased deliverables. It states it’s filled by /speckit.plan. | md | **Yes (moderate)**: contains “ACTION REQUIRED” guidance and process structure, but mostly LLM/task-facing rather than maintainer-facing. | -| templates/spec-template.md | Output template for feature specifications (user stories, acceptance scenarios, requirement structure). Includes strong guidance on testable, prioritized stories. | md | **Yes (moderate)**: good guidance for spec authors; still not a “template system” doc. | -| templates/tasks-template.md | Output template for actionable task lists; includes prerequisites, path conventions, parallelization strategy, and “sample tasks must be replaced” warnings. | md | **Yes (high)**: substantial operational guidance for task authoring and organization. | -| templates/vscode-settings.json | VS Code settings enabling prompt file recommendations for speckit.\* and auto-approving terminal tools in .specify/scripts/\*\*. | data (json) | **No**: configuration only; no explanatory doc text. | -| templates/commands/analyze.md | Command prompt for /speckit.analyze: read-only cross-artifact consistency/quality pass (spec/plan/tasks), driven via prerequisite script outputs. | md | **Yes (moderate)**: documents what analysis does and constraints; still “agent instruction.” | -| templates/commands/checklist.md | Command prompt for /speckit.checklist: frames checklists as “unit tests for requirements writing” and clarifies what they’re *not* (not implementation verification). | md | **Yes (high)**: contains a clear mental model and usage framing. | -| templates/commands/clarify.md | Command prompt for /speckit.clarify: targeted clarification questions, completion before planning, and a handoff to /speckit.plan. | md | **Yes (moderate)**: documents where clarify fits and why. | -| templates/commands/constitution.md | Command prompt for /speckit.constitution: fill constitution template and propagate changes to dependent artifacts; includes explicit note about .specify/memory/constitution.md and initialization from templates. | md | **Yes (moderate)**: provides maintainer-relevant propagation expectations. | -| templates/commands/implement.md | Command prompt for /speckit.implement: execute tasks, check checklists, apply extension hooks, and enforce safety constraints (secrets patterns, etc.). | md | **Yes (moderate)**: good operational constraints; not an architecture guide. | -| templates/commands/plan.md | Command prompt for /speckit.plan: sets up plan workflow using scripts; includes handoffs to tasks and checklist; references loading templates copied into place. | md | **Yes (moderate)**: explains sequencing and handoffs. | -| templates/commands/specify.md | Command prompt for /speckit.specify: create/update feature spec from natural language; handoffs to plan and clarify; calls create-new-feature script. | md | **Yes (moderate)**: explains behavior and chaining. | -| templates/commands/tasks.md | Command prompt for /speckit.tasks: generate tasks from design artifacts; handoffs to analyze \+ implement; uses prerequisite scripts. | md | **Yes (moderate)**: describes role in lifecycle. | -| templates/commands/taskstoissues.md | Command prompt for converting tasks into GitHub issues; includes issue\_write tool usage and explicit guardrails to only act on matching GitHub remotes. | md | **Yes (light)**: explains constraints; minimal broader context. | - -### What the templates collectively imply as a mental model - -Across the command templates (templates/commands/\*.md) and artifact templates (\*-template.md), a consistent implied model emerges: - -* **Commands** (specify/clarify/plan/tasks/analyze/implement/checklist/…) define *procedures \+ guardrails* for an AI agent. Many include prerequisite scripts, expected inputs/outputs, and optional handoffs to the next command. -* **Templates** (spec-template.md, plan-template.md, tasks-template.md, etc.) define *artifact structure* and embed quality constraints (e.g., “replace sample tasks,” “prioritized, independently testable user stories”). -* Some files mix guidance roles (e.g., tasks-template.md doubles as a playbook for parallelization and incremental delivery). - -This is strong “operational documentation,” but it is **not packaged as a maintainer-facing, systematic explanation of the template system**. - -## Repository documentation that explains templates for developers - -### Core docs that supply “glue” and a developer mental model - -The repository’s main README.md explains key “template system” concepts in a developer-friendly way: - -* It describes a **priority stack** for template resolution with a Mermaid diagram and explicitly states that templates are resolved at runtime (highest-priority match wins), while commands are applied at install time. -* It also shows example project directory structures and demonstrates where templates live after initialization (under .specify/templates/ in the user project). - -The DocFX-backed docs/ content includes: - -* A quickstart that describes the end-to-end **6-step workflow** (init → constitution → specify → clarify → plan → tasks → implement) and emphasizes **“context awareness”** via active feature detection (branch-based). -* Installation and upgrade guidance that clarifies what “project files” get refreshed (commands, scripts, templates, memory) versus what is “safe” (specs/ and code), and explicitly discusses .specify/templates/ as upgrade-targeted infrastructure. -* Local development instructions for iterating on the CLI without release publishing, including running via python \-m src.specify\_cli and uvx \--from .. -* The docs/README.md indicates docs are built via DocFX and deployed to GitHub Pages. - -AGENTS.md is a maintainer-oriented guide that explains how agent integrations work (directory conventions, command formats, argument placeholders) and gives a step-by-step procedure for adding support for new tools/agents. - -### Presets / extensions documentation that clarifies template customization - -The repository contains a fairly systematic explanation of template customization mechanics in the **preset system** docs: - -* presets/README.md defines presets as priority-ordered overrides for templates and commands, explains runtime template resolution vs install-time command registration, and documents specify preset resolve for tracing resolution. -* presets/ARCHITECTURE.md goes deeper: it includes Mermaid diagrams for template resolution and command registration, and explicitly lists the multiple implementations (Python \+ Bash \+ PowerShell) to keep behavior consistent. -* The extensions system docs and publishing guide define expected repo structures and strongly encourage extension documentation quality (README structure, command documentation, etc.). - -This preset documentation is the closest thing in-repo to a “template architecture doc,” but it is **scoped to presets** rather than the canonical templates/ directory inventory. - -## Issues, pull requests, and discussions that surface documentation gaps - -A recurring theme in repo activity is **path confusion** and missing “single source of truth” documentation for where templates/commands/scripts “should live” and how they relate (repo-internal templates/ vs installed .specify/templates/). - -### Repeated path and structure confusion - -* Some users flagged incorrect or confusing path references from templates to command files, e.g., plan-template.md referencing a .specify/templates/commands/... path that didn’t match expectations. -* Multiple issues question whether templates and scripts should refer to /templates/... vs /.specify/templates/..., and whether specs belong under .specify/specs/ or at repo root—indicating onboarding/docs ambiguity and drift. - -### Template mutability and “who is allowed to edit what” - -* A reported behavior: an agent (Codex CLI) modified files in .specify/templates during /speckit.constitution, even though templates were expected to remain base assets only updated on init/upgrade. This is a classic “mental model mismatch” symptom: users lack explicit, enforced rules (and docs) about mutability boundaries. - -### “How do I test template changes?” as a maintainership pain point - -* A maintainer/dev workflow issue: local modifications to templates/commands/\*.md and scripts were “ignored” because init flows pulled templates from releases (at least in the reported environment), making it hard to validate changes without publishing. - -### Explicit calls for onboard-oriented guidance - -* Issue \#295 explicitly proposes onboarding improvements (tour, quick reference, diagram) to reinforce the Specify → Plan → Tasks sequence and discourage users from running later steps out of order. - -### PR signals related to templates as a customizable surface - -* PR \#1466 (open as viewed) proposes removing branch-numbering logic from a template and adding a \--template-repo option to specify init so users can pull templates from a fork—an implicit acknowledgement that templates are a customization surface that benefits from better “how to modify safely” documentation. -* PR \#1987 (open as viewed) is nominally a docs rename, but the “files changed” view indicates it includes functional modifications related to template format selection (“compact” templates). Even the existence of a “compact format” notion increases the need for a single, coherent template developer guide. -* Recent/active issues discuss template resolution improvements (e.g., adding resolver/source attribution for extension templates). - -## Gaps in systematic developer-oriented documentation - -### Missing “one-stop” index for template assets - -The repository has strong building blocks (command templates that describe their behavior; a README that explains resolution stacks; preset architecture docs). But there is no central document that answers, in one place: - -* *What are all template files and command templates?* (Inventory \+ purpose) -* *Which ones are inputs vs outputs?* (What gets copied into a project vs generated as feature artifacts) -* *Which scripts and CLI operations touch which files?* -* *What is “safe to edit,” when, and by whom?* (Human vs agent vs init/upgrade) -* *How to test a template change end-to-end without publishing a release?* - -The lack of such a doc is consistent with the volume of issues asking where assets belong and how tooling should interpret them. - -### “Developer-oriented” guidance is embedded, but mostly LLM-facing - -Many template/command files contain substantial guidance, but it is largely phrased as **agent instructions** (MUST/SHOULD), not as curated maintainer documentation. That’s helpful for reverse engineering, yet brittle as onboarding material—particularly when paths or assumptions drift. - -Concrete example: tasks-template.md is rich in operational guidance but serves primarily as *an output template \+ generator contract*, not a doc explaining how to evolve the template system. - -## Recommendations for documentation to add - -### Add a maintainer-facing “Template System” guide - -A strong candidate is docs/templates.md (and link it from docs/index.md \+ root README), or a templates/README.md plus a doc-site page. The doc should explicitly bridge: - -* repo templates/\*\* (source of truth) -* installed .specify/templates/\*\* (copied into projects) -* generated specs/\/\*.md artifacts (outputs) - -**Proposed outline** - -* Purpose of templates vs commands vs scripts vs memory -* Full inventory of templates/ (auto-generate this table in CI to prevent drift) -* Artifact lifecycle: what every /speckit.\* reads/writes -* Mutability rules: what agents may edit vs what must remain stable -* Path conventions and historical migrations (templates/ → .specify/templates/) -* Testing workflow for template changes (local, without publishing) - -**Example content snippet (illustrative)** - -``` -## Template roles - -- templates/*-template.md: base artifact formats copied into .specify/templates/ -- templates/commands/*.md: agent command procedures installed into agent-specific folders -- scripts/**: runtime glue (select active feature, copy templates, update agent context) -``` - -### Add a Mermaid “project structure + flow” diagram set - -The repo already uses Mermaid for template/preset diagrams; extend that style to make the *full pipeline* obvious. - -Suggested diagrams to include (and where) - -* In docs/quickstart.md (or a new docs/how-it-works.md): - * **SDD lifecycle flowchart**: constitution → specify → clarify → plan → tasks → analyze/checklist → implement → taskstoissues -* In the proposed template guide: - * **File I/O map**: each command node lists inputs/outputs (e.g., clarify reads spec.md, writes clarifications back; plan reads spec.md \+ constitution, writes plan.md \+ design docs; tasks reads plan.md \+ artifacts, writes tasks.md). -* In the preset/extension docs (already present): - * Keep the **template resolution stack**, but cross-link to the main template guide. - -### Add a “Template change checklist” for contributors - -Given recurring drift issues, introduce a short checklist (either in CONTRIBUTING.md or a dedicated doc) that enforces cross-asset consistency: - -* If you change spec-template.md, confirm: - * templates/commands/specify.md instructions remain aligned - * templates/commands/clarify.md taxonomy still matches spec sections -* If you change template paths or structure: - * update Bash + PowerShell scripts consistently (and the preset resolver references, if applicable) - * Add “Docs impact” section: update docs/upgrade.md and docs/quickstart.md if user-facing behavior changed. - -### Add “How to test template/command changes locally” documentation - -Augment docs/local-development.md with a template-focused section that addresses the reported pain: - -* How to run the CLI from source (python \-m src.specify\_cli ...) -* How to initialize a sandbox project using local assets -* How to validate that the sandbox project is using your modified templates/commands/scripts -* How to run a minimal “golden path” (specify → plan → tasks) to ensure nothing breaks - -This would directly address the workflow gap implied by “local changes ignored” reports. - ---- - From 5a37e7ee10fd669d0aee58932925f7e0ca006513 Mon Sep 17 00:00:00 2001 From: PChemGuy <39730837+pchemguy@users.noreply.github.com> Date: Thu, 2 Apr 2026 13:40:24 +0300 Subject: [PATCH 13/25] Create DEVELOPMENT.md outline --- DEVELOPMENT.md | 73 ++++ Development Guide Dev/Untitled.md | 364 ++++++++++++++++++ Development Guide Dev/deep-research-report.md | 188 +++++++++ 3 files changed, 625 insertions(+) create mode 100644 DEVELOPMENT.md create mode 100644 Development Guide Dev/Untitled.md create mode 100644 Development Guide Dev/deep-research-report.md diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md new file mode 100644 index 000000000..fbdd5fabc --- /dev/null +++ b/DEVELOPMENT.md @@ -0,0 +1,73 @@ +# Development Guide + +## 1. Purpose + +- Who this document is for +- How it differs from README.md and CONTRIBUTING.md + +## 2. Spec Kit for Maintainers + +- What Spec Kit is internally +- Core workflow it supports +- Main system surfaces + +## 3. System Mental Model +### 3.1 Artifact and workflow lifecycle +### 3.2 Source assets vs generated/project assets +### 3.3 Templates, scripts, CLI, agent integrations, extensions, presets + +## 4. Repository Anatomy +### 4.1 templates/ +### 4.2 scripts/ +### 4.3 CLI/package code +### 4.4 memory assets +### 4.5 extensions/ +### 4.6 presets/ +### 4.7 catalogs and community metadata +### 4.8 top-level docs + +## 5. If You Want to Change X, Edit Y + +- Generated artifact content +- Workflow behavior +- Installation/bootstrap +- Docs +- Extensions +- Presets +- Catalog/community entries + +## 6. Development Workflows +### 6.1 Template changes +### 6.2 Script changes +### 6.3 CLI/bootstrap changes +### 6.4 Docs-only changes +### 6.5 Extension/preset/catalog changes + +## 7. Validation and Testing Map + +- Automated checks +- Manual agent-flow validation +- Packaged-output validation +- When each is needed + +## 8. Documentation Map + +- README.md +- CONTRIBUTING.md +- TESTING.md +- spec-driven.md +- extension/preset publishing docs +- changelog/release docs + +## 9. Architectural Invariants + +- Workflow consistency +- Cross-agent compatibility +- Docs/templates alignment +- Packaging/scaffolding integrity + +## 10. Common Pitfalls + +## 11. Release and Compatibility Notes + +## 12. Maintainer Onboarding Checklist diff --git a/Development Guide Dev/Untitled.md b/Development Guide Dev/Untitled.md new file mode 100644 index 000000000..761bacda7 --- /dev/null +++ b/Development Guide Dev/Untitled.md @@ -0,0 +1,364 @@ +Yes, it makes sense. + +A top-level `DEVELOPMENT.md` is a good fit here because the current `README.md` is clearly optimized for users adopting Spec Kit in projects, while `CONTRIBUTING.md` is narrower: contribution mechanics, validation flow, and PR hygiene. It is not really a full developer mental-model document. The repo also already has specialized docs like `TESTING.md`, the extension publishing guide, and preset publishing guide, which means a developer-facing entry document should primarily orient, map, and route rather than duplicate details. ([GitHub][1]) + +I would treat `DEVELOPMENT.md` as the **developer map of the system**: + +* what Spec Kit is internally, +* how the repository is organized, +* how the main moving parts interact, +* where to edit for each class of change, +* how to validate changes, +* and where deeper docs live. + That is the missing layer between user docs and contribution rules. ([GitHub][1]) + +## What `DEVELOPMENT.md` should do + +It should not try to be: + +* another `README.md`, +* another `CONTRIBUTING.md`, +* or a giant reference manual. + +It should be the **primary entry point for maintainers and contributors who need system understanding before editing**. + +The right emphasis is: + +1. mental model, +2. repository anatomy, +3. change workflows, +4. document map, +5. common modification scenarios. + +That is especially important in this repo because the core is not just Python code; it is a coordinated kit of templates, scripts, CLI behavior, agent integrations, memory files, extensions, presets, and documentation. The current docs already imply this multi-part system, but they are distributed across several places. ([GitHub][2]) + +## Recommended top-level structure + +Here is the outline I would use. + +### 1. Purpose of this document + +Very short. Explain that: + +* `README.md` is for users adopting Spec Kit, +* `DEVELOPMENT.md` is for people modifying Spec Kit itself, +* `CONTRIBUTING.md` covers contribution process and PR expectations, +* deeper component docs are linked below. ([GitHub][2]) + +### 2. What Spec Kit is, from a maintainer perspective + +Give a concise internal framing, for example: + +* Spec Kit is a toolkit for Spec-Driven Development. +* The repo packages prompts/templates, command scaffolding, scripts, CLI support, agent-specific integration assets, and ecosystem mechanisms such as extensions and presets. +* The generated user workflow is roughly: constitution → specify → plan → tasks → implement. ([GitHub][1]) + +This section should answer: **what are we actually maintaining?** + +### 3. System mental model + +This is one of the most important sections. + +Suggested subsections: + +* **Core artifact flow** + How the main SDD flow progresses through constitution, specification, plan, tasks, implementation. ([GitHub][1]) +* **Delivery model** + Clarify what lives in the repo versus what gets installed/scaffolded into user projects. +* **Main abstraction layers** + For example: + + * templates/content, + * command scaffolding, + * CLI/bootstrap/install logic, + * agent-specific integration surfaces, + * extension/preset ecosystem, + * docs/catalog/community surfaces. + +A simple diagram would help a lot here. + +### 4. Repository anatomy + +This should be a guided map, not just a tree dump. + +For each major top-level area, explain: + +* what it contains, +* why it exists, +* when to edit it, +* what else it interacts with. + +You already mentioned this, and yes, it should absolutely be included. + +Likely subsections: + +* `templates/` — core artifact templates and command templates; probably the most important content layer for generated workflow behavior. The repo README and contribution workflow both point contributors to template validation. ([GitHub][2]) +* `scripts/` — automation/bootstrap/helper scripts; `CONTRIBUTING.md` explicitly calls out script functionality as something contributors should test. ([GitHub][2]) +* `memory/` or `.specify/memory`-related assets — constitution/project-memory behavior; contribution guidance explicitly references `memory/constitution.md` updates for major process changes. ([GitHub][2]) +* CLI/package code — where install/scaffold behavior and local `specify` execution live. +* `extensions/` — extension model and publishing support; the repo includes a dedicated extension publishing guide. ([GitHub][3]) +* `presets/` — preset model and publishing support; there is also a dedicated presets publishing guide. ([GitHub][4]) +* catalogs/community metadata — where ecosystem discoverability is maintained; the README includes community extensions, presets, walkthroughs, and related ecosystem surfaces. ([GitHub][5]) +* top-level docs — which are user docs, contributor docs, testing docs, release docs, etc. + +### 5. “If you want to change X, edit Y” + +This is the most practical section, and many repos miss it. + +Examples: + +* To change the wording/structure of generated feature specs → edit relevant template files. +* To change slash-command behavior or workflow sequencing → inspect command templates plus any supporting scripts/CLI glue. +* To change installation/bootstrap behavior → inspect CLI/package/bootstrap code. +* To add or modify extension publishing behavior → see `extensions/EXTENSION-PUBLISHING-GUIDE.md`. +* To add or modify presets behavior → see `presets/PUBLISHING.md`. +* To adjust docs shown to end users → update `README.md` and possibly `spec-driven.md`, which `CONTRIBUTING.md` explicitly names for user-facing changes. ([GitHub][2]) + +This section makes the doc operational instead of descriptive. + +### 6. End-to-end development workflows + +Not contribution policy in the abstract, but concrete developer workflows. + +Suggested subsections: + +* **Template change workflow** +* **Script change workflow** +* **CLI/bootstrap change workflow** +* **Docs-only workflow** +* **Extension/preset/catalog change workflow** + +For each: + +* where to edit, +* how to test locally, +* what docs to update, +* what regressions to watch for. + +This aligns well with the current contribution guidance, which already says to test CLI commands in an agent, verify templates in `templates/`, test scripts in `scripts/`, and update memory/docs where relevant. ([GitHub][2]) + +### 7. Validation and testing map + +Do not restate all of `TESTING.md`. Instead, summarize the validation layers and link outward. + +Suggested structure: + +* quick local checks, +* focused automated checks, +* manual workflow tests in real agents, +* packaging/release-output validation, +* when each level is required. + +This matches the current recommended validation flow in `CONTRIBUTING.md`, which points developers to focused automated checks first, then manual workflow tests, then local release package inspection when needed. ([GitHub][2]) + +### 8. Documentation map + +This should be explicit and curated. + +A table works well: + +| Document | Audience | Purpose | When to read | +| -------- | -------- | ------- | ------------ | + +Include at least: + +* `README.md` +* `CONTRIBUTING.md` +* `TESTING.md` +* `spec-driven.md` +* `extensions/EXTENSION-PUBLISHING-GUIDE.md` +* `presets/PUBLISHING.md` +* maybe `CHANGELOG.md` and release-related docs if relevant. ([GitHub][2]) + +This section is especially valuable because the repo’s documentation surface has grown. + +### 9. Architectural invariants / guardrails + +This is another high-value section. + +List the things maintainers should preserve, such as: + +* user workflow consistency across supported agents, +* template and script changes should remain compatible with the expected SDD flow, +* generated artifacts and packaging should remain coherent, +* docs and templates must stay aligned, +* agent-specific adaptations should not silently break the general model. + +These should be framed as maintainer guardrails, not as vague philosophy. The README’s emphasis on the standard workflow and the contribution doc’s insistence on testing the CLI workflow with real agents strongly suggest this kind of invariant section is warranted. ([GitHub][1]) + +### 10. Common pitfalls + +Very useful for new contributors. + +Examples: + +* changing a template without validating it through an actual agent flow, +* updating docs but not generated behavior, +* changing workflow semantics without updating memory/process docs, +* forgetting ecosystem/catalog impact, +* testing only source form but not packaged output. ([GitHub][2]) + +### 11. Release-awareness and compatibility notes + +Brief section only. + +Could cover: + +* generated assets vs source assets, +* keeping changes compatible across agent modes, +* watching changelog/release behavior, +* any versioning expectations for templates/extensions/presets where applicable. ([GitHub][6]) + +### 12. Getting started as a maintainer + +A compact onboarding checklist: + +* read this document, +* read `CONTRIBUTING.md`, +* read `TESTING.md`, +* inspect repository layout, +* run local install, +* run representative workflow tests, +* make a narrow change first. + +## What else to include beyond your current idea + +Your instinct is right, but I would add four things that are easy to overlook: + +### A. A maintainer mental model, not just repository overview + +Without this, the document becomes a directory tour. + +The key question is: +**How do templates, scripts, CLI/bootstrap, docs, and ecosystem surfaces combine to produce the user experience?** + +That is the real “developer README”. + +### B. Change-oriented guidance + +The “if you want to change X, edit Y” section is disproportionately valuable. + +It reduces contributor hesitation and prevents wrong-entry-point edits. + +### C. Invariants / non-obvious rules + +These are the things experienced maintainers know but new contributors do not. + +For Spec Kit, that likely includes preserving the workflow sequence and validating changes in real agent flows rather than treating the repo as ordinary static docs. ([GitHub][2]) + +### D. A curated doc index + +Not a raw list of files. A role-based map. + +That is what turns scattered documentation into an actual developer entry point. + +## What not to do + +I would avoid: + +* duplicating installation instructions from `README.md`, +* duplicating PR policy from `CONTRIBUTING.md`, +* duplicating detailed test procedures from `TESTING.md`, +* documenting every file, +* writing a long historical narrative. + +`DEVELOPMENT.md` should stay navigational and architectural. + +## Suggested section order + +If you want a clean final shape, I would order it like this: + +1. Purpose of this document +2. Spec Kit at a glance for maintainers +3. System mental model +4. Repository anatomy +5. Change map: if you want to change X, edit Y +6. Development workflows +7. Validation and testing map +8. Documentation map +9. Architectural invariants and guardrails +10. Common pitfalls +11. Release and compatibility notes +12. Maintainer onboarding checklist + +## My recommendation on naming + +`DEVELOPMENT.md` is a reasonable name here. It is more natural than `README_DEV.md`. + +`README_DEV.md` is understandable, but it feels slightly ad hoc. `DEVELOPMENT.md` reads like a first-class top-level maintainer document and pairs well with `README.md`, `CONTRIBUTING.md`, `TESTING.md`, and `CHANGELOG.md`. That naming style is also consistent with the repo already having specialized top-level docs rather than overloading a second README. ([GitHub][2]) + +## A compact draft outline you can start from + +```md +# Development Guide + +## 1. Purpose +- Who this document is for +- How it differs from README.md and CONTRIBUTING.md + +## 2. Spec Kit for Maintainers +- What Spec Kit is internally +- Core workflow it supports +- Main system surfaces + +## 3. System Mental Model +### 3.1 Artifact and workflow lifecycle +### 3.2 Source assets vs generated/project assets +### 3.3 Templates, scripts, CLI, agent integrations, extensions, presets + +## 4. Repository Anatomy +### 4.1 templates/ +### 4.2 scripts/ +### 4.3 CLI/package code +### 4.4 memory assets +### 4.5 extensions/ +### 4.6 presets/ +### 4.7 catalogs and community metadata +### 4.8 top-level docs + +## 5. If You Want to Change X, Edit Y +- Generated artifact content +- Workflow behavior +- Installation/bootstrap +- Docs +- Extensions +- Presets +- Catalog/community entries + +## 6. Development Workflows +### 6.1 Template changes +### 6.2 Script changes +### 6.3 CLI/bootstrap changes +### 6.4 Docs-only changes +### 6.5 Extension/preset/catalog changes + +## 7. Validation and Testing Map +- Automated checks +- Manual agent-flow validation +- Packaged-output validation +- When each is needed + +## 8. Documentation Map +- README.md +- CONTRIBUTING.md +- TESTING.md +- spec-driven.md +- extension/preset publishing docs +- changelog/release docs + +## 9. Architectural Invariants +- Workflow consistency +- Cross-agent compatibility +- Docs/templates alignment +- Packaging/scaffolding integrity + +## 10. Common Pitfalls + +## 11. Release and Compatibility Notes + +## 12. Maintainer Onboarding Checklist +``` + +This is the structure I would use unless you want `DEVELOPMENT.md` to be intentionally shorter and more of a “developer landing page” that links out aggressively. + +I can turn this into a concrete first-pass `DEVELOPMENT.md` skeleton with section text, not just the outline. diff --git a/Development Guide Dev/deep-research-report.md b/Development Guide Dev/deep-research-report.md new file mode 100644 index 000000000..c81ff9acb --- /dev/null +++ b/Development Guide Dev/deep-research-report.md @@ -0,0 +1,188 @@ +# Deep research on Spec Kit development documentation coverage + +## Executive summary + +The GitHub github/spec-kit repository does contain **meaningful developer-oriented documentation** that explains *how templates fit into Spec Kit’s workflow*—especially in the main README.md, the DocFX-backed docs/ site sources, AGENTS.md, and the preset system documentation (presets/README.md \+ presets/ARCHITECTURE.md). These sources provide a workable mental model for the **Spec‑Driven Development (SDD) lifecycle**, and for **template resolution / overrides** (core vs extensions vs presets vs project overrides). + +However, the repository does **not** appear to contain a **single, systematic, developer-facing “Template System” guide** that (a) enumerates **every file under templates/**, (b) explains each one’s role in the pipeline, and (c) provides **glue/jump-start guidance** for maintainers (how to safely modify templates, keep scripts and command prompts aligned, and test changes end-to-end). The absence of an index/README inside templates/ and multiple “path confusion” / “template behavior confusion” issues suggest the mental model is dispersed and easy to miss. + +## Inventory and analysis of templates/ + +### Directory structure overview + +At the time of review (repo main), templates/ contains 7 top-level assets plus a commands/ subdirectory with 9 command templates (total: 16 files). + +### Table of all files under templates/ + +The “Developer-oriented guidance?” column below is strictly about **human-developer onboarding/mental model** content *inside the file itself* (as opposed to “LLM-facing instructions that a developer could reverse-engineer”). Many of these files primarily serve as **prompt directives/templates** for agents, which is useful but not the same as curated developer documentation. + +| File (path) | Purpose (what it is for) | Type | Developer-oriented guidance inside file? | +| :---------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------: | :--------------------------------------------------------------------------------------------------------------------------------------- | +| templates/agent-file-template.md | Skeleton for a generated “Development Guidelines” / agent context file (placeholders for technologies, structure, commands, recent changes, plus a manual-additions region). | md | **Partial**: structure \+ placeholders; minimal “why/how.” | +| templates/checklist-template.md | Output template for checklist artifacts; explicitly notes generation by /speckit.checklist and includes a large **“sample items must be replaced”** instruction block. | md | **Yes (light)**: explains it is command-generated and warns not to keep sample items. | +| templates/constitution-template.md | Placeholder constitution format (principles, governance, version metadata) with inline examples in comments. | md | **Partial**: examples hint at intent; not a full maintainer guide. | +| templates/plan-template.md | Output template for a feature’s implementation plan and design artifacts; includes “technical context,” constitution gate, project structure, and phased deliverables. It states it’s filled by /speckit.plan. | md | **Yes (moderate)**: contains “ACTION REQUIRED” guidance and process structure, but mostly LLM/task-facing rather than maintainer-facing. | +| templates/spec-template.md | Output template for feature specifications (user stories, acceptance scenarios, requirement structure). Includes strong guidance on testable, prioritized stories. | md | **Yes (moderate)**: good guidance for spec authors; still not a “template system” doc. | +| templates/tasks-template.md | Output template for actionable task lists; includes prerequisites, path conventions, parallelization strategy, and “sample tasks must be replaced” warnings. | md | **Yes (high)**: substantial operational guidance for task authoring and organization. | +| templates/vscode-settings.json | VS Code settings enabling prompt file recommendations for speckit.\* and auto-approving terminal tools in .specify/scripts/\*\*. | data (json) | **No**: configuration only; no explanatory doc text. | +| templates/commands/analyze.md | Command prompt for /speckit.analyze: read-only cross-artifact consistency/quality pass (spec/plan/tasks), driven via prerequisite script outputs. | md | **Yes (moderate)**: documents what analysis does and constraints; still “agent instruction.” | +| templates/commands/checklist.md | Command prompt for /speckit.checklist: frames checklists as “unit tests for requirements writing” and clarifies what they’re *not* (not implementation verification). | md | **Yes (high)**: contains a clear mental model and usage framing. | +| templates/commands/clarify.md | Command prompt for /speckit.clarify: targeted clarification questions, completion before planning, and a handoff to /speckit.plan. | md | **Yes (moderate)**: documents where clarify fits and why. | +| templates/commands/constitution.md | Command prompt for /speckit.constitution: fill constitution template and propagate changes to dependent artifacts; includes explicit note about .specify/memory/constitution.md and initialization from templates. | md | **Yes (moderate)**: provides maintainer-relevant propagation expectations. | +| templates/commands/implement.md | Command prompt for /speckit.implement: execute tasks, check checklists, apply extension hooks, and enforce safety constraints (secrets patterns, etc.). | md | **Yes (moderate)**: good operational constraints; not an architecture guide. | +| templates/commands/plan.md | Command prompt for /speckit.plan: sets up plan workflow using scripts; includes handoffs to tasks and checklist; references loading templates copied into place. | md | **Yes (moderate)**: explains sequencing and handoffs. | +| templates/commands/specify.md | Command prompt for /speckit.specify: create/update feature spec from natural language; handoffs to plan and clarify; calls create-new-feature script. | md | **Yes (moderate)**: explains behavior and chaining. | +| templates/commands/tasks.md | Command prompt for /speckit.tasks: generate tasks from design artifacts; handoffs to analyze \+ implement; uses prerequisite scripts. | md | **Yes (moderate)**: describes role in lifecycle. | +| templates/commands/taskstoissues.md | Command prompt for converting tasks into GitHub issues; includes issue\_write tool usage and explicit guardrails to only act on matching GitHub remotes. | md | **Yes (light)**: explains constraints; minimal broader context. | + +### What the templates collectively imply as a mental model + +Across the command templates (templates/commands/\*.md) and artifact templates (\*-template.md), a consistent implied model emerges: + +* **Commands** (specify/clarify/plan/tasks/analyze/implement/checklist/…) define *procedures \+ guardrails* for an AI agent. Many include prerequisite scripts, expected inputs/outputs, and optional handoffs to the next command. +* **Templates** (spec-template.md, plan-template.md, tasks-template.md, etc.) define *artifact structure* and embed quality constraints (e.g., “replace sample tasks,” “prioritized, independently testable user stories”). +* Some files mix guidance roles (e.g., tasks-template.md doubles as a playbook for parallelization and incremental delivery). + +This is strong “operational documentation,” but it is **not packaged as a maintainer-facing, systematic explanation of the template system**. + +## Repository documentation that explains templates for developers + +### Core docs that supply “glue” and a developer mental model + +The repository’s main README.md explains key “template system” concepts in a developer-friendly way: + +* It describes a **priority stack** for template resolution with a Mermaid diagram and explicitly states that templates are resolved at runtime (highest-priority match wins), while commands are applied at install time. +* It also shows example project directory structures and demonstrates where templates live after initialization (under .specify/templates/ in the user project). + +The DocFX-backed docs/ content includes: + +* A quickstart that describes the end-to-end **6-step workflow** (init → constitution → specify → clarify → plan → tasks → implement) and emphasizes **“context awareness”** via active feature detection (branch-based). +* Installation and upgrade guidance that clarifies what “project files” get refreshed (commands, scripts, templates, memory) versus what is “safe” (specs/ and code), and explicitly discusses .specify/templates/ as upgrade-targeted infrastructure. +* Local development instructions for iterating on the CLI without release publishing, including running via python \-m src.specify\_cli and uvx \--from .. +* The docs/README.md indicates docs are built via DocFX and deployed to GitHub Pages. + +AGENTS.md is a maintainer-oriented guide that explains how agent integrations work (directory conventions, command formats, argument placeholders) and gives a step-by-step procedure for adding support for new tools/agents. + +### Presets / extensions documentation that clarifies template customization + +The repository contains a fairly systematic explanation of template customization mechanics in the **preset system** docs: + +* presets/README.md defines presets as priority-ordered overrides for templates and commands, explains runtime template resolution vs install-time command registration, and documents specify preset resolve for tracing resolution. +* presets/ARCHITECTURE.md goes deeper: it includes Mermaid diagrams for template resolution and command registration, and explicitly lists the multiple implementations (Python \+ Bash \+ PowerShell) to keep behavior consistent. +* The extensions system docs and publishing guide define expected repo structures and strongly encourage extension documentation quality (README structure, command documentation, etc.). + +This preset documentation is the closest thing in-repo to a “template architecture doc,” but it is **scoped to presets** rather than the canonical templates/ directory inventory. + +## Issues, pull requests, and discussions that surface documentation gaps + +A recurring theme in repo activity is **path confusion** and missing “single source of truth” documentation for where templates/commands/scripts “should live” and how they relate (repo-internal templates/ vs installed .specify/templates/). + +### Repeated path and structure confusion + +* Some users flagged incorrect or confusing path references from templates to command files, e.g., plan-template.md referencing a .specify/templates/commands/... path that didn’t match expectations. +* Multiple issues question whether templates and scripts should refer to /templates/... vs /.specify/templates/..., and whether specs belong under .specify/specs/ or at repo root—indicating onboarding/docs ambiguity and drift. + +### Template mutability and “who is allowed to edit what” + +* A reported behavior: an agent (Codex CLI) modified files in .specify/templates during /speckit.constitution, even though templates were expected to remain base assets only updated on init/upgrade. This is a classic “mental model mismatch” symptom: users lack explicit, enforced rules (and docs) about mutability boundaries. + +### “How do I test template changes?” as a maintainership pain point + +* A maintainer/dev workflow issue: local modifications to templates/commands/\*.md and scripts were “ignored” because init flows pulled templates from releases (at least in the reported environment), making it hard to validate changes without publishing. + +### Explicit calls for onboard-oriented guidance + +* Issue \#295 explicitly proposes onboarding improvements (tour, quick reference, diagram) to reinforce the Specify → Plan → Tasks sequence and discourage users from running later steps out of order. + +### PR signals related to templates as a customizable surface + +* PR \#1466 (open as viewed) proposes removing branch-numbering logic from a template and adding a \--template-repo option to specify init so users can pull templates from a fork—an implicit acknowledgement that templates are a customization surface that benefits from better “how to modify safely” documentation. +* PR \#1987 (open as viewed) is nominally a docs rename, but the “files changed” view indicates it includes functional modifications related to template format selection (“compact” templates). Even the existence of a “compact format” notion increases the need for a single, coherent template developer guide. +* Recent/active issues discuss template resolution improvements (e.g., adding resolver/source attribution for extension templates). + +## Gaps in systematic developer-oriented documentation + +### Missing “one-stop” index for template assets + +The repository has strong building blocks (command templates that describe their behavior; a README that explains resolution stacks; preset architecture docs). But there is no central document that answers, in one place: + +* *What are all template files and command templates?* (Inventory \+ purpose) +* *Which ones are inputs vs outputs?* (What gets copied into a project vs generated as feature artifacts) +* *Which scripts and CLI operations touch which files?* +* *What is “safe to edit,” when, and by whom?* (Human vs agent vs init/upgrade) +* *How to test a template change end-to-end without publishing a release?* + +The lack of such a doc is consistent with the volume of issues asking where assets belong and how tooling should interpret them. + +### “Developer-oriented” guidance is embedded, but mostly LLM-facing + +Many template/command files contain substantial guidance, but it is largely phrased as **agent instructions** (MUST/SHOULD), not as curated maintainer documentation. That’s helpful for reverse engineering, yet brittle as onboarding material—particularly when paths or assumptions drift. + +Concrete example: tasks-template.md is rich in operational guidance but serves primarily as *an output template \+ generator contract*, not a doc explaining how to evolve the template system. + +## Recommendations for documentation to add + +### Add a maintainer-facing “Template System” guide + +A strong candidate is docs/templates.md (and link it from docs/index.md \+ root README), or a templates/README.md plus a doc-site page. The doc should explicitly bridge: + +* repo templates/\*\* (source of truth) +* installed .specify/templates/\*\* (copied into projects) +* generated specs/\/\*.md artifacts (outputs) + +**Proposed outline** + +* Purpose of templates vs commands vs scripts vs memory +* Full inventory of templates/ (auto-generate this table in CI to prevent drift) +* Artifact lifecycle: what every /speckit.\* reads/writes +* Mutability rules: what agents may edit vs what must remain stable +* Path conventions and historical migrations (templates/ → .specify/templates/) +* Testing workflow for template changes (local, without publishing) + +**Example content snippet (illustrative)** + +``` +## Template roles + +- templates/*-template.md: base artifact formats copied into .specify/templates/ +- templates/commands/*.md: agent command procedures installed into agent-specific folders +- scripts/**: runtime glue (select active feature, copy templates, update agent context) +``` + +### Add a Mermaid “project structure + flow” diagram set + +The repo already uses Mermaid for template/preset diagrams; extend that style to make the *full pipeline* obvious. + +Suggested diagrams to include (and where) + +* In docs/quickstart.md (or a new docs/how-it-works.md): + * **SDD lifecycle flowchart**: constitution → specify → clarify → plan → tasks → analyze/checklist → implement → taskstoissues +* In the proposed template guide: + * **File I/O map**: each command node lists inputs/outputs (e.g., clarify reads spec.md, writes clarifications back; plan reads spec.md \+ constitution, writes plan.md \+ design docs; tasks reads plan.md \+ artifacts, writes tasks.md). +* In the preset/extension docs (already present): + * Keep the **template resolution stack**, but cross-link to the main template guide. + +### Add a “Template change checklist” for contributors + +Given recurring drift issues, introduce a short checklist (either in CONTRIBUTING.md or a dedicated doc) that enforces cross-asset consistency: + +* If you change spec-template.md, confirm: + * templates/commands/specify.md instructions remain aligned + * templates/commands/clarify.md taxonomy still matches spec sections +* If you change template paths or structure: + * update Bash + PowerShell scripts consistently (and the preset resolver references, if applicable) + * Add “Docs impact” section: update docs/upgrade.md and docs/quickstart.md if user-facing behavior changed. + +### Add “How to test template/command changes locally” documentation + +Augment docs/local-development.md with a template-focused section that addresses the reported pain: + +* How to run the CLI from source (python \-m src.specify\_cli ...) +* How to initialize a sandbox project using local assets +* How to validate that the sandbox project is using your modified templates/commands/scripts +* How to run a minimal “golden path” (specify → plan → tasks) to ensure nothing breaks + +This would directly address the workflow gap implied by “local changes ignored” reports. + +--- + From 824978be7304abee5c32d25b6fc7bc40976368b1 Mon Sep 17 00:00:00 2001 From: PChemGuy <39730837+pchemguy@users.noreply.github.com> Date: Thu, 2 Apr 2026 13:57:34 +0300 Subject: [PATCH 14/25] AI-generated DEVELOPMENT.md draft --- DEVELOPMENT.md | 493 +++++++++++++++++++++++++--- Development Guide Dev/Untitled 1.md | 458 ++++++++++++++++++++++++++ 2 files changed, 897 insertions(+), 54 deletions(-) create mode 100644 Development Guide Dev/Untitled 1.md diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index fbdd5fabc..4454c598d 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -1,73 +1,458 @@ # Development Guide -## 1. Purpose +This document is the primary entry point for people modifying Spec Kit itself. -- Who this document is for -- How it differs from README.md and CONTRIBUTING.md +Use this guide when you need to understand how the repository fits together, where different kinds of changes belong, how to validate them, and which deeper documents to read next. -## 2. Spec Kit for Maintainers +## Relationship to Other Top-Level Documents -- What Spec Kit is internally -- Core workflow it supports -- Main system surfaces +Spec Kit has several top-level documents with different roles. They should not duplicate each other. -## 3. System Mental Model -### 3.1 Artifact and workflow lifecycle -### 3.2 Source assets vs generated/project assets -### 3.3 Templates, scripts, CLI, agent integrations, extensions, presets +- `README.md` is the primary entry point for users adopting Spec Kit in a project. +- `DEVELOPMENT.md` is the primary entry point for contributors and maintainers changing Spec Kit itself. +- `CONTRIBUTING.md` defines contribution mechanics, review expectations, and required development practices. +- `TESTING.md` describes validation strategy and testing procedures in more detail. +- Other specialized documents cover specific subsystems or publishing workflows. -## 4. Repository Anatomy -### 4.1 templates/ -### 4.2 scripts/ -### 4.3 CLI/package code -### 4.4 memory assets -### 4.5 extensions/ -### 4.6 presets/ -### 4.7 catalogs and community metadata -### 4.8 top-level docs +This document is intentionally focused on system understanding, repository navigation, and change workflows. -## 5. If You Want to Change X, Edit Y +## What Spec Kit Is, from a Maintainer Perspective -- Generated artifact content -- Workflow behavior -- Installation/bootstrap -- Docs -- Extensions -- Presets -- Catalog/community entries +Spec Kit is a toolkit for spec-driven development. It provides a structured workflow, scaffolding assets, and supporting integrations that help users move from an idea to a defined specification, an implementation plan, task breakdowns, and executable project work. -## 6. Development Workflows -### 6.1 Template changes -### 6.2 Script changes -### 6.3 CLI/bootstrap changes -### 6.4 Docs-only changes -### 6.5 Extension/preset/catalog changes +From a maintainer perspective, the repository is not just "documentation" and not just "code". It is a coordinated system composed of several interacting surfaces: -## 7. Validation and Testing Map +- workflow-defining templates, +- command and scaffolding assets, +- scripts and automation helpers, +- CLI and installation behavior, +- agent-specific integration surfaces, +- extension and preset publishing assets, +- documentation that explains and stabilizes the user and developer model. -- Automated checks -- Manual agent-flow validation -- Packaged-output validation -- When each is needed +Maintaining Spec Kit means preserving coherence across those surfaces. A change in one layer often affects documentation, validation expectations, and user-visible workflow behavior in other layers. -## 8. Documentation Map +## System Mental Model -- README.md -- CONTRIBUTING.md -- TESTING.md -- spec-driven.md -- extension/preset publishing docs -- changelog/release docs +### Core User Workflow -## 9. Architectural Invariants +At a high level, Spec Kit supports a staged workflow in which a user moves through structured project definition and execution steps. The exact implementation details may vary by agent or integration surface, but the core conceptual flow is consistent: -- Workflow consistency -- Cross-agent compatibility -- Docs/templates alignment -- Packaging/scaffolding integrity +1. establish or refine governing project principles, +2. define a concrete specification, +3. derive an implementation plan, +4. derive an actionable task breakdown, +5. execute implementation against the defined artifacts. -## 10. Common Pitfalls +When changing Spec Kit, first identify which part of that lifecycle your change affects. -## 11. Release and Compatibility Notes +### Source Assets vs Generated Project Assets -## 12. Maintainer Onboarding Checklist +A useful distinction for maintainers is the difference between: + +- **source assets in this repository**, and +- **artifacts that users consume in their own repositories or agent sessions**. + +Source assets in this repository define behavior, structure, wording, conventions, and scaffolding rules. Generated or installed assets are the user-facing outputs of those source assets. + +When editing repository files, think in terms of downstream consequences: + +- What will change in the user-visible workflow? +- What will change in generated project content? +- What must be revalidated manually in a real end-to-end flow? + +### Main System Surfaces + +Most changes fall into one or more of these surfaces: + +- **Templates**: define workflow artifacts, prompts, scaffolding content, and generated project structure. +- **Scripts and automation**: support local generation, packaging, installation, or validation flows. +- **CLI and bootstrap behavior**: define how users initialize, install, or execute Spec Kit workflows. +- **Agent integration surfaces**: adapt the kit to specific agent environments without changing the underlying workflow intent. +- **Extensions and presets**: package additional reusable behavior or opinionated configurations. +- **Documentation**: explain the intended model, workflow, usage, and maintenance practices. + +A contributor should be able to identify which surface they are editing before making a change. + +## Repository Anatomy + +This section explains the role of the major repository areas. It is intended as a guided map, not a full file inventory. + +### `templates/` + +This directory contains the core workflow and content assets that shape the user experience. In many cases, this is the most important part of the repository because it defines the structure and wording of the spec-driven workflow itself. + +Edit `templates/` when you are changing: + +- generated artifact structure, +- workflow prompt wording, +- command or template content, +- default project scaffolding semantics. + +Treat template changes as behavior changes, not as passive documentation edits. Even small text changes can alter how users and agents interpret the workflow. + +### `scripts/` + +This directory contains automation and helper logic used for validation, packaging, generation, or related maintenance tasks. + +Edit `scripts/` when you are changing: + +- automation that supports local development, +- packaging or build helpers, +- maintenance utilities, +- validation support logic. + +Script changes should be validated both for local correctness and for their role in the broader development workflow. + +### CLI and Package Code + +Where applicable, repository code for installation, bootstrap, packaging, or command execution defines how Spec Kit is delivered and invoked. + +Edit the CLI or package code when you are changing: + +- installation behavior, +- initialization flow, +- local command behavior, +- execution semantics exposed to users. + +Changes here are usually high-impact because they affect how users enter the system. + +### Memory and Governing Assets + +Some repository assets define persistent project conventions, constitutions, or other workflow-governing content. + +Edit these assets when you are changing: + +- core workflow assumptions, +- project constitution defaults, +- stable behavioral expectations carried across the kit. + +These changes often require corresponding documentation updates because they affect the conceptual model, not just wording. + +### `extensions/` + +This area supports extension mechanisms and related publishing flows. + +Edit `extensions/` when you are: + +- adding a new extension, +- modifying extension behavior, +- updating extension packaging or publishing guidance. + +Extension changes should preserve compatibility with the main Spec Kit model unless the extension is explicitly intended to be a bounded deviation. + +### `presets/` + +This area supports reusable preset configurations and their publishing workflows. + +Edit `presets/` when you are: + +- adding a new preset, +- changing how presets are defined, +- updating preset publishing or maintenance logic. + +Presets should remain understandable as opinionated selections layered on top of the core workflow, not as silent redefinitions of that workflow. + +### Documentation Surface + +Top-level and subsystem documentation explains the user model, maintainer model, testing expectations, and publishing flows. + +Edit documentation whenever code, templates, scripts, or workflow semantics change in a way that affects: + +- user understanding, +- contributor understanding, +- validation expectations, +- extension or preset author behavior. + +Do not treat docs as an afterthought. In Spec Kit, documentation is part of the product surface. + +## Change Map: If You Want to Change X, Edit Y + +This section is a practical routing guide. Use it before making edits. + +### Change generated specification or planning content + +Start with the relevant files under `templates/`. + +Typical examples: + +- generated spec wording, +- plan structure, +- task generation wording, +- default scaffolded project artifacts. + +### Change workflow behavior or sequencing + +Inspect the relevant templates first, then any supporting script or CLI logic that participates in workflow execution. + +Typical examples: + +- command flow changes, +- stage ordering changes, +- added or removed workflow steps, +- changes in how generated assets reference one another. + +### Change installation or bootstrap behavior + +Inspect CLI or package code, install helpers, and any supporting scripts involved in setup or initialization. + +Typical examples: + +- init behavior, +- install commands, +- local executable behavior, +- package layout expectations. + +### Change user-facing documentation + +Update `README.md` and any other user-facing docs affected by the change. If the workflow model changes, also update any supporting conceptual documentation so the documented model remains aligned with actual behavior. + +### Change contributor-facing guidance + +Update `DEVELOPMENT.md`, `CONTRIBUTING.md`, `TESTING.md`, or more specialized contributor documentation as appropriate. + +### Change extension behavior or extension publishing + +Start in `extensions/` and then update related publishing guidance and any ecosystem references. + +### Change preset behavior or preset publishing + +Start in `presets/` and then update related publishing guidance and any ecosystem references. + +### Change system-wide conceptual assumptions + +Treat the change as cross-cutting. Review templates, governing assets, docs, validation expectations, and any affected packaging or integration surfaces together. + +## Development Workflows + +This section describes the normal paths for common kinds of changes. + +### Template Change Workflow + +Use this workflow when changing prompt content, generated artifact structure, or other template-defined behavior. + +1. Identify the exact user-visible behavior that should change. +2. Locate the relevant template files. +3. Make the smallest coherent change that expresses the intended behavior. +4. Review adjacent templates for consistency. +5. Update documentation if the conceptual or visible behavior changed. +6. Validate the change through focused checks and at least one realistic end-to-end flow. + +For template changes, wording is behavior. Treat wording edits with the same care as code changes. + +### Script Change Workflow + +Use this workflow when changing repository automation or support utilities. + +1. Identify the workflow that depends on the script. +2. Edit the relevant script with minimal scope. +3. Validate the script directly. +4. Validate the higher-level workflow that depends on it. +5. Update docs if the script changes how contributors or users are expected to work. + +### CLI or Bootstrap Change Workflow + +Use this workflow when changing how users enter or operate Spec Kit through commands or package installation. + +1. Identify the affected command or entry path. +2. Trace the code and any related templates or scripts. +3. Make the change with attention to backward compatibility and user expectations. +4. Validate the affected command locally. +5. Validate at least one realistic user entry flow end to end. +6. Update user-facing and developer-facing docs as needed. + +### Docs-Only Workflow + +Use this workflow when making documentation changes that do not intentionally alter behavior. + +1. Confirm that the change is actually documentation-only. +2. Update the relevant docs. +3. Check for overlap with other docs that may now be inconsistent. +4. Ensure terminology remains aligned across documents. + +Be cautious: many apparent "docs-only" changes in this repository are actually behavioral if they describe workflow semantics that templates or scripts already implement. + +### Extension or Preset Workflow + +Use this workflow when changing extension or preset assets. + +1. Identify whether the change affects the core model or only the extension/preset layer. +2. Edit the relevant extension or preset files. +3. Validate packaging, discoverability, and usage expectations. +4. Update publishing and maintenance guidance where needed. +5. Ensure the relationship to core Spec Kit remains explicit. + +## Validation and Testing Map + +This section is a routing summary. For detailed procedures, see `TESTING.md` and related validation documentation. + +### Focused Local Validation + +Use focused validation first when changing a narrow part of the system. + +Examples include: + +- validating the specific template you changed, +- running the script you modified, +- exercising the CLI path you edited, +- checking a packaging or publishing path affected by your change. + +### End-to-End Workflow Validation + +Use realistic manual validation when the change affects user-visible workflow semantics. + +This is especially important for: + +- template changes, +- command flow changes, +- initialization or bootstrap changes, +- agent-facing workflow changes. + +A change is not well validated if it only passes isolated checks but has not been exercised in a real workflow context. + +### Documentation Validation + +When behavior changes, documentation must be checked for alignment. This includes: + +- top-level user docs, +- maintainer docs, +- subsystem docs, +- extension or preset publishing docs. + +### Packaging and Distribution Validation + +When changing install, release, extension, or preset behavior, confirm that the change remains correct in the form users actually consume. + +Do not assume that source-level correctness is sufficient. + +## Documentation Map + +This section routes contributors to the right deeper documents. + +### `README.md` + +Primary user-facing introduction. + +Read this when you need to understand how the repository presents itself to adopters and what promises are made to users. + +### `CONTRIBUTING.md` + +Contribution process, expectations, and contribution hygiene. + +Read this before opening a pull request or when you need the repository's current contribution rules. + +### `TESTING.md` + +Validation strategy and test guidance. + +Read this when planning or executing validation for non-trivial changes. + +### Extension Publishing Documentation + +Read the extension-specific publishing guide when working on extension creation, packaging, or publication. + +### Preset Publishing Documentation + +Read the preset-specific publishing guide when working on preset creation, packaging, or publication. + +### Other Specialized Documents + +Read subsystem-specific documents when your change targets a specific area rather than the core maintainer workflow. + +As the repository evolves, keep this section curated. It should remain a developer routing table, not a raw list of markdown files. + +## Architectural Invariants and Guardrails + +The following guardrails should remain true unless there is an explicit, repository-wide decision to change them. + +### Preserve Workflow Coherence + +The core spec-driven workflow should remain understandable as a staged progression from governing principles to specification, planning, tasking, and execution. + +Do not introduce local optimizations that make the overall model less coherent. + +### Preserve Cross-Surface Alignment + +Templates, scripts, CLI behavior, and docs should describe the same system. + +A contributor should not be able to follow the docs and encounter materially different behavior in the actual workflow. + +### Treat Templates as Product Logic + +Template wording, structure, and default content are part of the product, not just decoration. + +Do not make casual wording changes without considering behavioral consequences. + +### Keep Agent-Specific Adaptation Secondary to the Core Model + +Agent-specific support is important, but it should adapt the core workflow rather than fragment it into unrelated systems unless such divergence is deliberate and documented. + +### Keep Extensions and Presets Legible + +Extensions and presets should remain understandable additions or variations, not opaque redefinitions of the core workflow. + +## Common Pitfalls + +The following mistakes are easy to make in this repository. + +### Treating a Template Edit as a Mere Copy Change + +Template wording often changes behavior. Review it the same way you would review logic changes. + +### Updating One Surface but Not the Others + +A workflow change may require updates in templates, docs, tests, and installation or execution behavior. Check for cross-surface impact before considering the work complete. + +### Validating Too Narrowly + +A focused unit check may pass while the real user workflow is broken. Use end-to-end validation when the change affects behavior users or agents actually experience. + +### Letting Contributor Docs Drift + +When the repository structure or maintainer workflow changes, `DEVELOPMENT.md` and related docs need to change too. + +### Hiding a Conceptual Change Inside a Small Edit + +If a change alters the mental model or expected workflow, document it as such. Do not let significant semantic changes masquerade as tiny text cleanups. + +## Release and Compatibility Notes + +When making changes that affect packaging, installation, extensions, presets, or generated outputs, consider compatibility from the perspective of actual users and downstream maintainers. + +Questions to ask: + +Does this change + +- alter the expected workflow? +- affect generated artifacts? +- require documentation updates? +- affect extension or preset compatibility? +- need explicit release-note treatment? + +When in doubt, assume user-visible workflow changes deserve explicit documentation and release awareness. + +## Maintainer Onboarding Checklist + +A new maintainer should usually do the following before making broad changes: + +1. read `README.md` to understand the user-facing model, +2. read this document to understand the maintainer-facing model, +3. read `CONTRIBUTING.md` before preparing changes, +4. read `TESTING.md` before validating non-trivial work, +5. inspect the repository layout, especially `templates/`, `scripts/`, and any CLI or packaging code, +6. trace at least one representative end-to-end workflow, +7. start with a narrow, well-scoped change before attempting structural revisions. + +## Keeping This Document Healthy + +This document should evolve with the repository. + +Update it when: + +- repository structure changes, +- the maintainer mental model changes, +- new core subsystems are introduced, +- the recommended development workflow changes, +- the document map needs rerouting. + +The goal is to keep this file useful as a top-level maintainer entry point, not to turn it into an exhaustive reference manual. diff --git a/Development Guide Dev/Untitled 1.md b/Development Guide Dev/Untitled 1.md new file mode 100644 index 000000000..4454c598d --- /dev/null +++ b/Development Guide Dev/Untitled 1.md @@ -0,0 +1,458 @@ +# Development Guide + +This document is the primary entry point for people modifying Spec Kit itself. + +Use this guide when you need to understand how the repository fits together, where different kinds of changes belong, how to validate them, and which deeper documents to read next. + +## Relationship to Other Top-Level Documents + +Spec Kit has several top-level documents with different roles. They should not duplicate each other. + +- `README.md` is the primary entry point for users adopting Spec Kit in a project. +- `DEVELOPMENT.md` is the primary entry point for contributors and maintainers changing Spec Kit itself. +- `CONTRIBUTING.md` defines contribution mechanics, review expectations, and required development practices. +- `TESTING.md` describes validation strategy and testing procedures in more detail. +- Other specialized documents cover specific subsystems or publishing workflows. + +This document is intentionally focused on system understanding, repository navigation, and change workflows. + +## What Spec Kit Is, from a Maintainer Perspective + +Spec Kit is a toolkit for spec-driven development. It provides a structured workflow, scaffolding assets, and supporting integrations that help users move from an idea to a defined specification, an implementation plan, task breakdowns, and executable project work. + +From a maintainer perspective, the repository is not just "documentation" and not just "code". It is a coordinated system composed of several interacting surfaces: + +- workflow-defining templates, +- command and scaffolding assets, +- scripts and automation helpers, +- CLI and installation behavior, +- agent-specific integration surfaces, +- extension and preset publishing assets, +- documentation that explains and stabilizes the user and developer model. + +Maintaining Spec Kit means preserving coherence across those surfaces. A change in one layer often affects documentation, validation expectations, and user-visible workflow behavior in other layers. + +## System Mental Model + +### Core User Workflow + +At a high level, Spec Kit supports a staged workflow in which a user moves through structured project definition and execution steps. The exact implementation details may vary by agent or integration surface, but the core conceptual flow is consistent: + +1. establish or refine governing project principles, +2. define a concrete specification, +3. derive an implementation plan, +4. derive an actionable task breakdown, +5. execute implementation against the defined artifacts. + +When changing Spec Kit, first identify which part of that lifecycle your change affects. + +### Source Assets vs Generated Project Assets + +A useful distinction for maintainers is the difference between: + +- **source assets in this repository**, and +- **artifacts that users consume in their own repositories or agent sessions**. + +Source assets in this repository define behavior, structure, wording, conventions, and scaffolding rules. Generated or installed assets are the user-facing outputs of those source assets. + +When editing repository files, think in terms of downstream consequences: + +- What will change in the user-visible workflow? +- What will change in generated project content? +- What must be revalidated manually in a real end-to-end flow? + +### Main System Surfaces + +Most changes fall into one or more of these surfaces: + +- **Templates**: define workflow artifacts, prompts, scaffolding content, and generated project structure. +- **Scripts and automation**: support local generation, packaging, installation, or validation flows. +- **CLI and bootstrap behavior**: define how users initialize, install, or execute Spec Kit workflows. +- **Agent integration surfaces**: adapt the kit to specific agent environments without changing the underlying workflow intent. +- **Extensions and presets**: package additional reusable behavior or opinionated configurations. +- **Documentation**: explain the intended model, workflow, usage, and maintenance practices. + +A contributor should be able to identify which surface they are editing before making a change. + +## Repository Anatomy + +This section explains the role of the major repository areas. It is intended as a guided map, not a full file inventory. + +### `templates/` + +This directory contains the core workflow and content assets that shape the user experience. In many cases, this is the most important part of the repository because it defines the structure and wording of the spec-driven workflow itself. + +Edit `templates/` when you are changing: + +- generated artifact structure, +- workflow prompt wording, +- command or template content, +- default project scaffolding semantics. + +Treat template changes as behavior changes, not as passive documentation edits. Even small text changes can alter how users and agents interpret the workflow. + +### `scripts/` + +This directory contains automation and helper logic used for validation, packaging, generation, or related maintenance tasks. + +Edit `scripts/` when you are changing: + +- automation that supports local development, +- packaging or build helpers, +- maintenance utilities, +- validation support logic. + +Script changes should be validated both for local correctness and for their role in the broader development workflow. + +### CLI and Package Code + +Where applicable, repository code for installation, bootstrap, packaging, or command execution defines how Spec Kit is delivered and invoked. + +Edit the CLI or package code when you are changing: + +- installation behavior, +- initialization flow, +- local command behavior, +- execution semantics exposed to users. + +Changes here are usually high-impact because they affect how users enter the system. + +### Memory and Governing Assets + +Some repository assets define persistent project conventions, constitutions, or other workflow-governing content. + +Edit these assets when you are changing: + +- core workflow assumptions, +- project constitution defaults, +- stable behavioral expectations carried across the kit. + +These changes often require corresponding documentation updates because they affect the conceptual model, not just wording. + +### `extensions/` + +This area supports extension mechanisms and related publishing flows. + +Edit `extensions/` when you are: + +- adding a new extension, +- modifying extension behavior, +- updating extension packaging or publishing guidance. + +Extension changes should preserve compatibility with the main Spec Kit model unless the extension is explicitly intended to be a bounded deviation. + +### `presets/` + +This area supports reusable preset configurations and their publishing workflows. + +Edit `presets/` when you are: + +- adding a new preset, +- changing how presets are defined, +- updating preset publishing or maintenance logic. + +Presets should remain understandable as opinionated selections layered on top of the core workflow, not as silent redefinitions of that workflow. + +### Documentation Surface + +Top-level and subsystem documentation explains the user model, maintainer model, testing expectations, and publishing flows. + +Edit documentation whenever code, templates, scripts, or workflow semantics change in a way that affects: + +- user understanding, +- contributor understanding, +- validation expectations, +- extension or preset author behavior. + +Do not treat docs as an afterthought. In Spec Kit, documentation is part of the product surface. + +## Change Map: If You Want to Change X, Edit Y + +This section is a practical routing guide. Use it before making edits. + +### Change generated specification or planning content + +Start with the relevant files under `templates/`. + +Typical examples: + +- generated spec wording, +- plan structure, +- task generation wording, +- default scaffolded project artifacts. + +### Change workflow behavior or sequencing + +Inspect the relevant templates first, then any supporting script or CLI logic that participates in workflow execution. + +Typical examples: + +- command flow changes, +- stage ordering changes, +- added or removed workflow steps, +- changes in how generated assets reference one another. + +### Change installation or bootstrap behavior + +Inspect CLI or package code, install helpers, and any supporting scripts involved in setup or initialization. + +Typical examples: + +- init behavior, +- install commands, +- local executable behavior, +- package layout expectations. + +### Change user-facing documentation + +Update `README.md` and any other user-facing docs affected by the change. If the workflow model changes, also update any supporting conceptual documentation so the documented model remains aligned with actual behavior. + +### Change contributor-facing guidance + +Update `DEVELOPMENT.md`, `CONTRIBUTING.md`, `TESTING.md`, or more specialized contributor documentation as appropriate. + +### Change extension behavior or extension publishing + +Start in `extensions/` and then update related publishing guidance and any ecosystem references. + +### Change preset behavior or preset publishing + +Start in `presets/` and then update related publishing guidance and any ecosystem references. + +### Change system-wide conceptual assumptions + +Treat the change as cross-cutting. Review templates, governing assets, docs, validation expectations, and any affected packaging or integration surfaces together. + +## Development Workflows + +This section describes the normal paths for common kinds of changes. + +### Template Change Workflow + +Use this workflow when changing prompt content, generated artifact structure, or other template-defined behavior. + +1. Identify the exact user-visible behavior that should change. +2. Locate the relevant template files. +3. Make the smallest coherent change that expresses the intended behavior. +4. Review adjacent templates for consistency. +5. Update documentation if the conceptual or visible behavior changed. +6. Validate the change through focused checks and at least one realistic end-to-end flow. + +For template changes, wording is behavior. Treat wording edits with the same care as code changes. + +### Script Change Workflow + +Use this workflow when changing repository automation or support utilities. + +1. Identify the workflow that depends on the script. +2. Edit the relevant script with minimal scope. +3. Validate the script directly. +4. Validate the higher-level workflow that depends on it. +5. Update docs if the script changes how contributors or users are expected to work. + +### CLI or Bootstrap Change Workflow + +Use this workflow when changing how users enter or operate Spec Kit through commands or package installation. + +1. Identify the affected command or entry path. +2. Trace the code and any related templates or scripts. +3. Make the change with attention to backward compatibility and user expectations. +4. Validate the affected command locally. +5. Validate at least one realistic user entry flow end to end. +6. Update user-facing and developer-facing docs as needed. + +### Docs-Only Workflow + +Use this workflow when making documentation changes that do not intentionally alter behavior. + +1. Confirm that the change is actually documentation-only. +2. Update the relevant docs. +3. Check for overlap with other docs that may now be inconsistent. +4. Ensure terminology remains aligned across documents. + +Be cautious: many apparent "docs-only" changes in this repository are actually behavioral if they describe workflow semantics that templates or scripts already implement. + +### Extension or Preset Workflow + +Use this workflow when changing extension or preset assets. + +1. Identify whether the change affects the core model or only the extension/preset layer. +2. Edit the relevant extension or preset files. +3. Validate packaging, discoverability, and usage expectations. +4. Update publishing and maintenance guidance where needed. +5. Ensure the relationship to core Spec Kit remains explicit. + +## Validation and Testing Map + +This section is a routing summary. For detailed procedures, see `TESTING.md` and related validation documentation. + +### Focused Local Validation + +Use focused validation first when changing a narrow part of the system. + +Examples include: + +- validating the specific template you changed, +- running the script you modified, +- exercising the CLI path you edited, +- checking a packaging or publishing path affected by your change. + +### End-to-End Workflow Validation + +Use realistic manual validation when the change affects user-visible workflow semantics. + +This is especially important for: + +- template changes, +- command flow changes, +- initialization or bootstrap changes, +- agent-facing workflow changes. + +A change is not well validated if it only passes isolated checks but has not been exercised in a real workflow context. + +### Documentation Validation + +When behavior changes, documentation must be checked for alignment. This includes: + +- top-level user docs, +- maintainer docs, +- subsystem docs, +- extension or preset publishing docs. + +### Packaging and Distribution Validation + +When changing install, release, extension, or preset behavior, confirm that the change remains correct in the form users actually consume. + +Do not assume that source-level correctness is sufficient. + +## Documentation Map + +This section routes contributors to the right deeper documents. + +### `README.md` + +Primary user-facing introduction. + +Read this when you need to understand how the repository presents itself to adopters and what promises are made to users. + +### `CONTRIBUTING.md` + +Contribution process, expectations, and contribution hygiene. + +Read this before opening a pull request or when you need the repository's current contribution rules. + +### `TESTING.md` + +Validation strategy and test guidance. + +Read this when planning or executing validation for non-trivial changes. + +### Extension Publishing Documentation + +Read the extension-specific publishing guide when working on extension creation, packaging, or publication. + +### Preset Publishing Documentation + +Read the preset-specific publishing guide when working on preset creation, packaging, or publication. + +### Other Specialized Documents + +Read subsystem-specific documents when your change targets a specific area rather than the core maintainer workflow. + +As the repository evolves, keep this section curated. It should remain a developer routing table, not a raw list of markdown files. + +## Architectural Invariants and Guardrails + +The following guardrails should remain true unless there is an explicit, repository-wide decision to change them. + +### Preserve Workflow Coherence + +The core spec-driven workflow should remain understandable as a staged progression from governing principles to specification, planning, tasking, and execution. + +Do not introduce local optimizations that make the overall model less coherent. + +### Preserve Cross-Surface Alignment + +Templates, scripts, CLI behavior, and docs should describe the same system. + +A contributor should not be able to follow the docs and encounter materially different behavior in the actual workflow. + +### Treat Templates as Product Logic + +Template wording, structure, and default content are part of the product, not just decoration. + +Do not make casual wording changes without considering behavioral consequences. + +### Keep Agent-Specific Adaptation Secondary to the Core Model + +Agent-specific support is important, but it should adapt the core workflow rather than fragment it into unrelated systems unless such divergence is deliberate and documented. + +### Keep Extensions and Presets Legible + +Extensions and presets should remain understandable additions or variations, not opaque redefinitions of the core workflow. + +## Common Pitfalls + +The following mistakes are easy to make in this repository. + +### Treating a Template Edit as a Mere Copy Change + +Template wording often changes behavior. Review it the same way you would review logic changes. + +### Updating One Surface but Not the Others + +A workflow change may require updates in templates, docs, tests, and installation or execution behavior. Check for cross-surface impact before considering the work complete. + +### Validating Too Narrowly + +A focused unit check may pass while the real user workflow is broken. Use end-to-end validation when the change affects behavior users or agents actually experience. + +### Letting Contributor Docs Drift + +When the repository structure or maintainer workflow changes, `DEVELOPMENT.md` and related docs need to change too. + +### Hiding a Conceptual Change Inside a Small Edit + +If a change alters the mental model or expected workflow, document it as such. Do not let significant semantic changes masquerade as tiny text cleanups. + +## Release and Compatibility Notes + +When making changes that affect packaging, installation, extensions, presets, or generated outputs, consider compatibility from the perspective of actual users and downstream maintainers. + +Questions to ask: + +Does this change + +- alter the expected workflow? +- affect generated artifacts? +- require documentation updates? +- affect extension or preset compatibility? +- need explicit release-note treatment? + +When in doubt, assume user-visible workflow changes deserve explicit documentation and release awareness. + +## Maintainer Onboarding Checklist + +A new maintainer should usually do the following before making broad changes: + +1. read `README.md` to understand the user-facing model, +2. read this document to understand the maintainer-facing model, +3. read `CONTRIBUTING.md` before preparing changes, +4. read `TESTING.md` before validating non-trivial work, +5. inspect the repository layout, especially `templates/`, `scripts/`, and any CLI or packaging code, +6. trace at least one representative end-to-end workflow, +7. start with a narrow, well-scoped change before attempting structural revisions. + +## Keeping This Document Healthy + +This document should evolve with the repository. + +Update it when: + +- repository structure changes, +- the maintainer mental model changes, +- new core subsystems are introduced, +- the recommended development workflow changes, +- the document map needs rerouting. + +The goal is to keep this file useful as a top-level maintainer entry point, not to turn it into an exhaustive reference manual. From 51eb80d79803beff11931e4f4f1dc1100e555b9a Mon Sep 17 00:00:00 2001 From: PChemGuy <39730837+pchemguy@users.noreply.github.com> Date: Thu, 2 Apr 2026 14:19:17 +0300 Subject: [PATCH 15/25] Update DEVELOPMENT.md --- DEVELOPMENT.md | 25 ++++++++++++++++--------- 1 file changed, 16 insertions(+), 9 deletions(-) diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 4454c598d..6c8d771ae 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -2,19 +2,26 @@ This document is the primary entry point for people modifying Spec Kit itself. -Use this guide when you need to understand how the repository fits together, where different kinds of changes belong, how to validate them, and which deeper documents to read next. +Use this guide when you need to understand how the repository fits together, where different kinds of changes belong, how to validate them, and which deeper documents to read next. This document is intentionally focused on system understanding, repository navigation, and change workflows. -## Relationship to Other Top-Level Documents +## Maintainer Onboarding Checklist + +Spec Kit has several top-level documents with different roles. They should not duplicate each other. A new maintainer should usually do the following before making broad changes: + +1. Read core top-level documents: -Spec Kit has several top-level documents with different roles. They should not duplicate each other. +| Document | Focus | +| ------------------------------------------ | ---------------------------------------------------------------------------------- | +| [README.md](./README.md) | The primary entry point for users adopting Spec Kit in a project. | +| This document | The primary entry point for contributors and maintainers changing Spec Kit itself. | +| [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md) | | +| [CONTRIBUTING.md](./CONTRIBUTING.md) | Contribution mechanics, review expectations, and required development practices. | +| [TESTING.md](./TESTING.md) | Validation strategy and testing procedures. | -- `README.md` is the primary entry point for users adopting Spec Kit in a project. -- `DEVELOPMENT.md` is the primary entry point for contributors and maintainers changing Spec Kit itself. -- `CONTRIBUTING.md` defines contribution mechanics, review expectations, and required development practices. -- `TESTING.md` describes validation strategy and testing procedures in more detail. -- Other specialized documents cover specific subsystems or publishing workflows. +2. inspect the repository layout, especially `templates/`, `scripts/`, and any CLI or packaging code, +3. trace at least one representative end-to-end workflow, +4. start with a narrow, well-scoped change before attempting structural revisions. -This document is intentionally focused on system understanding, repository navigation, and change workflows. ## What Spec Kit Is, from a Maintainer Perspective From 2cbdb6bb57e0e68bfdc6b4e22da52457037cdce2 Mon Sep 17 00:00:00 2001 From: PChemGuy <39730837+pchemguy@users.noreply.github.com> Date: Thu, 2 Apr 2026 17:08:22 +0300 Subject: [PATCH 16/25] Update DEVELOPMENT.md --- DEVELOPMENT.md | 32 ++++++++++++++++++++------------ 1 file changed, 20 insertions(+), 12 deletions(-) diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 6c8d771ae..6874fb2c5 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -6,22 +6,30 @@ Use this guide when you need to understand how the repository fits together, whe ## Maintainer Onboarding Checklist -Spec Kit has several top-level documents with different roles. They should not duplicate each other. A new maintainer should usually do the following before making broad changes: +Start here before making broad changes to Spec Kit. -1. Read core top-level documents: +### 1. Read the core top-level documents -| Document | Focus | -| ------------------------------------------ | ---------------------------------------------------------------------------------- | -| [README.md](./README.md) | The primary entry point for users adopting Spec Kit in a project. | -| This document | The primary entry point for contributors and maintainers changing Spec Kit itself. | -| [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md) | | -| [CONTRIBUTING.md](./CONTRIBUTING.md) | Contribution mechanics, review expectations, and required development practices. | -| [TESTING.md](./TESTING.md) | Validation strategy and testing procedures. | +Spec Kit has several top-level documents with different roles. They should not duplicate each other. -2. inspect the repository layout, especially `templates/`, `scripts/`, and any CLI or packaging code, -3. trace at least one representative end-to-end workflow, -4. start with a narrow, well-scoped change before attempting structural revisions. +| Document | Focus | +| ------------------------------------------ | -------------------------------------------------------------------------------- | +| [README.md](./README.md) | Primary entry point for users adopting Spec Kit in a project. | +| [DEVELOPMENT.md](./DEVELOPMENT.md) | Primary entry point for contributors and maintainers changing Spec Kit itself. | +| [CONTRIBUTING.md](./CONTRIBUTING.md) | Contribution mechanics, review expectations, and required development practices. | +| [TESTING.md](./TESTING.md) | Validation strategy and testing procedures. | +### 2. Inspect the repository layout + +Inspect the repository layout, especially `templates/`, `scripts/`, and any CLI or packaging code. + +### 3. Trace a representative workflow + +Trace at least one representative end-to-end workflow so you can connect the repository's source assets to the user-visible behavior they produce. + +### 4. Start with a narrow change + +Start with a narrow, well-scoped change before attempting broader structural revisions. ## What Spec Kit Is, from a Maintainer Perspective From fd55ea48832ffe24d890689c22d8d8068a762dfd Mon Sep 17 00:00:00 2001 From: PChemGuy <39730837+pchemguy@users.noreply.github.com> Date: Thu, 2 Apr 2026 17:11:20 +0300 Subject: [PATCH 17/25] Create Untitled 2.md --- Development Guide Dev/Untitled 2.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) create mode 100644 Development Guide Dev/Untitled 2.md diff --git a/Development Guide Dev/Untitled 2.md b/Development Guide Dev/Untitled 2.md new file mode 100644 index 000000000..adfccb663 --- /dev/null +++ b/Development Guide Dev/Untitled 2.md @@ -0,0 +1,12 @@ +Top-level documents are not sufficient for full onboarding. Before editing, read the relevant subsystem documentation for the surface you plan to modify. + +Use the following routing guide. + +| If you plan to change... | Read... | +| -------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | +| Core workflow templates and generated artifact structure | The relevant documents under `templates/` and any linked workflow-specific documentation | +| Validation behavior or test expectations | [TESTING.md](./TESTING.md) and any related subsystem-specific testing documentation | +| Extensions | The documentation under `extensions/`, including extension publishing and maintenance guidance | +| Presets | The documentation under `presets/`, including preset publishing and maintenance guidance | +| User-facing workflow semantics | The relevant templates, [README.md](./README.md), and any conceptual workflow documentation | +| Installation, packaging, or bootstrap behavior | The relevant CLI/package code, scripts, and associated development or publishing documentation | From 4d944e998f78ab61e85593355c2c20bab9d9f12c Mon Sep 17 00:00:00 2001 From: PChemGuy <39730837+pchemguy@users.noreply.github.com> Date: Thu, 2 Apr 2026 18:15:13 +0300 Subject: [PATCH 18/25] Update DEVELOPMENT.md --- DEVELOPMENT.md | 82 ++++++++------------------------------------------ 1 file changed, 13 insertions(+), 69 deletions(-) diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 6874fb2c5..d4c54a6cc 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -6,30 +6,22 @@ Use this guide when you need to understand how the repository fits together, whe ## Maintainer Onboarding Checklist -Start here before making broad changes to Spec Kit. +Read the essential project documents. -### 1. Read the core top-level documents +| Document | Focus | +| ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- | +| [README.md](./README.md) | Primary user-facing entry point and high-level overview of what Spec Kit is, how it is used, and what workflow it supports. | +| [DEVELOPMENT.md](./DEVELOPMENT.md) | Primary maintainer-facing entry point for contributors changing Spec Kit itself. | +| [spec-driven.md](./spec-driven.md) | Full conceptual and procedural walkthrough of the Spec-Driven Development workflow supported by Spec Kit. | +| [RELEASE-PROCESS.md](./.github/workflows/RELEASE-PROCESS.md) | Release workflow, versioning model, changelog generation, and release-process invariants. | +| [docs/index.md](./docs/index.md) | Entry point to the documentation under `docs/`, including installation, quick start, upgrade, and local development guidance. | +| [CONTRIBUTING.md](./CONTRIBUTING.md) | Contribution mechanics, review expectations, and required development practices. | +| [TESTING.md](./TESTING.md) | Validation strategy and testing procedures. | -Spec Kit has several top-level documents with different roles. They should not duplicate each other. +Inspect the repository layout, especially -| Document | Focus | -| ------------------------------------------ | -------------------------------------------------------------------------------- | -| [README.md](./README.md) | Primary entry point for users adopting Spec Kit in a project. | -| [DEVELOPMENT.md](./DEVELOPMENT.md) | Primary entry point for contributors and maintainers changing Spec Kit itself. | -| [CONTRIBUTING.md](./CONTRIBUTING.md) | Contribution mechanics, review expectations, and required development practices. | -| [TESTING.md](./TESTING.md) | Validation strategy and testing procedures. | - -### 2. Inspect the repository layout - -Inspect the repository layout, especially `templates/`, `scripts/`, and any CLI or packaging code. - -### 3. Trace a representative workflow - -Trace at least one representative end-to-end workflow so you can connect the repository's source assets to the user-visible behavior they produce. - -### 4. Start with a narrow change - -Start with a narrow, well-scoped change before attempting broader structural revisions. +- `templates/` - core project +- `scripts/`, and any CLI or packaging code. ## What Spec Kit Is, from a Maintainer Perspective @@ -340,42 +332,6 @@ When changing install, release, extension, or preset behavior, confirm that the Do not assume that source-level correctness is sufficient. -## Documentation Map - -This section routes contributors to the right deeper documents. - -### `README.md` - -Primary user-facing introduction. - -Read this when you need to understand how the repository presents itself to adopters and what promises are made to users. - -### `CONTRIBUTING.md` - -Contribution process, expectations, and contribution hygiene. - -Read this before opening a pull request or when you need the repository's current contribution rules. - -### `TESTING.md` - -Validation strategy and test guidance. - -Read this when planning or executing validation for non-trivial changes. - -### Extension Publishing Documentation - -Read the extension-specific publishing guide when working on extension creation, packaging, or publication. - -### Preset Publishing Documentation - -Read the preset-specific publishing guide when working on preset creation, packaging, or publication. - -### Other Specialized Documents - -Read subsystem-specific documents when your change targets a specific area rather than the core maintainer workflow. - -As the repository evolves, keep this section curated. It should remain a developer routing table, not a raw list of markdown files. - ## Architectural Invariants and Guardrails The following guardrails should remain true unless there is an explicit, repository-wide decision to change them. @@ -446,18 +402,6 @@ Does this change When in doubt, assume user-visible workflow changes deserve explicit documentation and release awareness. -## Maintainer Onboarding Checklist - -A new maintainer should usually do the following before making broad changes: - -1. read `README.md` to understand the user-facing model, -2. read this document to understand the maintainer-facing model, -3. read `CONTRIBUTING.md` before preparing changes, -4. read `TESTING.md` before validating non-trivial work, -5. inspect the repository layout, especially `templates/`, `scripts/`, and any CLI or packaging code, -6. trace at least one representative end-to-end workflow, -7. start with a narrow, well-scoped change before attempting structural revisions. - ## Keeping This Document Healthy This document should evolve with the repository. From 5222e7e2ff7d856d84761d6e130e829c7485bad5 Mon Sep 17 00:00:00 2001 From: PChemGuy <39730837+pchemguy@users.noreply.github.com> Date: Thu, 2 Apr 2026 19:50:22 +0300 Subject: [PATCH 19/25] Update DEVELOPMENT.md --- DEVELOPMENT.md | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index d4c54a6cc..820e2243b 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -4,9 +4,9 @@ This document is the primary entry point for people modifying Spec Kit itself. Use this guide when you need to understand how the repository fits together, where different kinds of changes belong, how to validate them, and which deeper documents to read next. This document is intentionally focused on system understanding, repository navigation, and change workflows. -## Maintainer Onboarding Checklist +## Maintainer Onboarding -Read the essential project documents. +**Read the essential project documents**: | Document | Focus | | ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- | @@ -18,10 +18,15 @@ Read the essential project documents. | [CONTRIBUTING.md](./CONTRIBUTING.md) | Contribution mechanics, review expectations, and required development practices. | | [TESTING.md](./TESTING.md) | Validation strategy and testing procedures. | -Inspect the repository layout, especially +**Inspect the repository layout**: -- `templates/` - core project -- `scripts/`, and any CLI or packaging code. +| Directory | Role | +| ------------------ | ---------------------------------------------------------------------- | +| `templates/` | Core project framework, LLM templated prompts and associated templates | +| `scripts/` | Deterministic component of the project framework. | +| `src/specify_cli/` | Python sources of `specify` CLI. | +| `extensions/` | Documentation and associated files for the `extensions` feature. | +| `presets/` | Documentation and associated files for the `presets` feature. | ## What Spec Kit Is, from a Maintainer Perspective From b7b2ad08e7538bbd7b28bdbb32c1e49997b4995f Mon Sep 17 00:00:00 2001 From: PChemGuy <39730837+pchemguy@users.noreply.github.com> Date: Thu, 2 Apr 2026 19:57:52 +0300 Subject: [PATCH 20/25] Update DEVELOPMENT.md --- DEVELOPMENT.md | 44 +++++++++++++++++++++++--------------------- 1 file changed, 23 insertions(+), 21 deletions(-) diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 820e2243b..3a21e9443 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -6,27 +6,29 @@ Use this guide when you need to understand how the repository fits together, whe ## Maintainer Onboarding -**Read the essential project documents**: - -| Document | Focus | -| ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- | -| [README.md](./README.md) | Primary user-facing entry point and high-level overview of what Spec Kit is, how it is used, and what workflow it supports. | -| [DEVELOPMENT.md](./DEVELOPMENT.md) | Primary maintainer-facing entry point for contributors changing Spec Kit itself. | -| [spec-driven.md](./spec-driven.md) | Full conceptual and procedural walkthrough of the Spec-Driven Development workflow supported by Spec Kit. | -| [RELEASE-PROCESS.md](./.github/workflows/RELEASE-PROCESS.md) | Release workflow, versioning model, changelog generation, and release-process invariants. | -| [docs/index.md](./docs/index.md) | Entry point to the documentation under `docs/`, including installation, quick start, upgrade, and local development guidance. | -| [CONTRIBUTING.md](./CONTRIBUTING.md) | Contribution mechanics, review expectations, and required development practices. | -| [TESTING.md](./TESTING.md) | Validation strategy and testing procedures. | - -**Inspect the repository layout**: - -| Directory | Role | -| ------------------ | ---------------------------------------------------------------------- | -| `templates/` | Core project framework, LLM templated prompts and associated templates | -| `scripts/` | Deterministic component of the project framework. | -| `src/specify_cli/` | Python sources of `specify` CLI. | -| `extensions/` | Documentation and associated files for the `extensions` feature. | -| `presets/` | Documentation and associated files for the `presets` feature. | +**Read the essential project documents:** + +| Document | Role | +| --- | --- | +| [README.md](./README.md) | Primary user-facing overview of Spec Kit, its purpose, and its workflow. | +| [DEVELOPMENT.md](./DEVELOPMENT.md) | Primary maintainer-facing guide to modifying Spec Kit itself. | +| [spec-driven.md](./spec-driven.md) | End-to-end explanation of the Spec-Driven Development model supported by Spec Kit. | +| [RELEASE-PROCESS.md](./.github/workflows/RELEASE-PROCESS.md) | Release workflow, versioning rules, and changelog generation process. | +| [docs/index.md](./docs/index.md) | Entry point to the `docs/` documentation set. | +| [CONTRIBUTING.md](./CONTRIBUTING.md) | Contribution process, review expectations, and required development practices. | +| [TESTING.md](./TESTING.md) | Validation strategy and testing procedures. | + +**Inspect the repository layout:** + +| Directory | Role | +| --- | --- | +| `templates/` | Core templates, prompt assets, and scaffold content that define the workflow surface. | +| `scripts/` | Supporting scripts used by the generated workflow and repository tooling. | +| `src/specify_cli/` | Python source for the `specify` CLI. | +| `extensions/` | Extension-related docs, catalogs, and supporting assets. | +| `presets/` | Preset-related docs, catalogs, and supporting assets. | + +**Trace a representative end-to-end workflow** to connect the repository's source assets to the user-visible behavior they produce. ## What Spec Kit Is, from a Maintainer Perspective From c010b04f533fae460a9649e76f6e4c7d8f95570c Mon Sep 17 00:00:00 2001 From: PChemGuy <39730837+pchemguy@users.noreply.github.com> Date: Thu, 2 Apr 2026 20:11:52 +0300 Subject: [PATCH 21/25] Update DEVELOPMENT.md --- DEVELOPMENT.md | 16 +++++++--------- 1 file changed, 7 insertions(+), 9 deletions(-) diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 3a21e9443..1ca1b7946 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -20,15 +20,13 @@ Use this guide when you need to understand how the repository fits together, whe **Inspect the repository layout:** -| Directory | Role | -| --- | --- | -| `templates/` | Core templates, prompt assets, and scaffold content that define the workflow surface. | -| `scripts/` | Supporting scripts used by the generated workflow and repository tooling. | -| `src/specify_cli/` | Python source for the `specify` CLI. | -| `extensions/` | Extension-related docs, catalogs, and supporting assets. | -| `presets/` | Preset-related docs, catalogs, and supporting assets. | - -**Trace a representative end-to-end workflow** to connect the repository's source assets to the user-visible behavior they produce. +| Directory | Role | +| ------------------ | --------------------------------------------------------------------- | +| `templates/` | Prompt assets and templates that define the workflow surface. | +| `scripts/` | Supporting scripts used by the generated workflow. | +| `src/specify_cli/` | Python source for the `specify` CLI, including agent-specific assets. | +| `extensions/` | Extension-related docs, catalogs, and supporting assets. | +| `presets/` | Preset-related docs, catalogs, and supporting assets. | ## What Spec Kit Is, from a Maintainer Perspective From 5db3859a448bd909f15de0e4f145261a4cd4d1df Mon Sep 17 00:00:00 2001 From: PChemGuy <39730837+pchemguy@users.noreply.github.com> Date: Thu, 2 Apr 2026 20:18:48 +0300 Subject: [PATCH 22/25] Update DEVELOPMENT.md --- DEVELOPMENT.md | 42 ++++++++++++++---------------------------- 1 file changed, 14 insertions(+), 28 deletions(-) diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 1ca1b7946..e1fe8e725 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -1,48 +1,34 @@ # Development Guide -This document is the primary entry point for people modifying Spec Kit itself. +This document is the primary entry point for people modifying Spec Kit itself. Use this guide when you need to understand how the repository fits together, where different kinds of changes belong, how to validate them, and which deeper documents to read next. This document is intentionally focused on system understanding, repository navigation, and change workflows. -Use this guide when you need to understand how the repository fits together, where different kinds of changes belong, how to validate them, and which deeper documents to read next. This document is intentionally focused on system understanding, repository navigation, and change workflows. +## Maintainer Orientation -## Maintainer Onboarding +Spec Kit is a toolkit for spec-driven development. It provides the workflow, scaffolding assets, and supporting integrations that turn an idea into a specification, an implementation plan, task breakdowns, and executable project work. From a maintainer perspective, the repository is not just documentation and not just code. It is a coordinated system whose templates, scripts, CLI, agent integrations, extensions, presets, and documentation must remain aligned. -**Read the essential project documents:** +**Essential project documents:** | Document | Role | | --- | --- | -| [README.md](./README.md) | Primary user-facing overview of Spec Kit, its purpose, and its workflow. | +| [README.md](./README.md) | Primary user-facing overview of Spec Kit and its workflow. | | [DEVELOPMENT.md](./DEVELOPMENT.md) | Primary maintainer-facing guide to modifying Spec Kit itself. | -| [spec-driven.md](./spec-driven.md) | End-to-end explanation of the Spec-Driven Development model supported by Spec Kit. | +| [spec-driven.md](./spec-driven.md) | End-to-end explanation of the Spec-Driven Development workflow supported by Spec Kit. | | [RELEASE-PROCESS.md](./.github/workflows/RELEASE-PROCESS.md) | Release workflow, versioning rules, and changelog generation process. | | [docs/index.md](./docs/index.md) | Entry point to the `docs/` documentation set. | | [CONTRIBUTING.md](./CONTRIBUTING.md) | Contribution process, review expectations, and required development practices. | | [TESTING.md](./TESTING.md) | Validation strategy and testing procedures. | -**Inspect the repository layout:** +**Main repository surfaces:** -| Directory | Role | -| ------------------ | --------------------------------------------------------------------- | -| `templates/` | Prompt assets and templates that define the workflow surface. | -| `scripts/` | Supporting scripts used by the generated workflow. | +| Directory | Role | +| --- | --- | +| `templates/` | Prompt assets and templates that define the core workflow behavior and generated artifacts. | +| `scripts/` | Supporting scripts used by the workflow, setup, and repository tooling. | | `src/specify_cli/` | Python source for the `specify` CLI, including agent-specific assets. | -| `extensions/` | Extension-related docs, catalogs, and supporting assets. | -| `presets/` | Preset-related docs, catalogs, and supporting assets. | - -## What Spec Kit Is, from a Maintainer Perspective - -Spec Kit is a toolkit for spec-driven development. It provides a structured workflow, scaffolding assets, and supporting integrations that help users move from an idea to a defined specification, an implementation plan, task breakdowns, and executable project work. - -From a maintainer perspective, the repository is not just "documentation" and not just "code". It is a coordinated system composed of several interacting surfaces: - -- workflow-defining templates, -- command and scaffolding assets, -- scripts and automation helpers, -- CLI and installation behavior, -- agent-specific integration surfaces, -- extension and preset publishing assets, -- documentation that explains and stabilizes the user and developer model. +| `extensions/` | Extension-related docs, catalogs, and supporting assets. | +| `presets/` | Preset-related docs, catalogs, and supporting assets. | -Maintaining Spec Kit means preserving coherence across those surfaces. A change in one layer often affects documentation, validation expectations, and user-visible workflow behavior in other layers. +These documents and repository surfaces form the minimum context needed to reason about changes safely. Maintaining Spec Kit means preserving coherence across those surfaces. A change in one layer often affects documentation, validation expectations, and user-visible workflow behavior in other layers. ## System Mental Model From 997904ded41f6facc6a73109aac570181ba3a46a Mon Sep 17 00:00:00 2001 From: PChemGuy <39730837+pchemguy@users.noreply.github.com> Date: Thu, 2 Apr 2026 22:00:08 +0300 Subject: [PATCH 23/25] Update DEVELOPMENT.md --- DEVELOPMENT.md | 59 +------------------------------------------------- 1 file changed, 1 insertion(+), 58 deletions(-) diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index e1fe8e725..b7a6bf5f4 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -4,7 +4,7 @@ This document is the primary entry point for people modifying Spec Kit itself. U ## Maintainer Orientation -Spec Kit is a toolkit for spec-driven development. It provides the workflow, scaffolding assets, and supporting integrations that turn an idea into a specification, an implementation plan, task breakdowns, and executable project work. From a maintainer perspective, the repository is not just documentation and not just code. It is a coordinated system whose templates, scripts, CLI, agent integrations, extensions, presets, and documentation must remain aligned. +Spec Kit is a toolkit for spec-driven development. At its core, it is a coordinated set of prompts, templates, scripts, and CLI/integration assets that define and deliver a spec-driven workflow for AI coding agents. The tables below summarize the essential project documents and main repository surfaces for developers. **Essential project documents:** @@ -28,50 +28,6 @@ Spec Kit is a toolkit for spec-driven development. It provides the workflow, sca | `extensions/` | Extension-related docs, catalogs, and supporting assets. | | `presets/` | Preset-related docs, catalogs, and supporting assets. | -These documents and repository surfaces form the minimum context needed to reason about changes safely. Maintaining Spec Kit means preserving coherence across those surfaces. A change in one layer often affects documentation, validation expectations, and user-visible workflow behavior in other layers. - -## System Mental Model - -### Core User Workflow - -At a high level, Spec Kit supports a staged workflow in which a user moves through structured project definition and execution steps. The exact implementation details may vary by agent or integration surface, but the core conceptual flow is consistent: - -1. establish or refine governing project principles, -2. define a concrete specification, -3. derive an implementation plan, -4. derive an actionable task breakdown, -5. execute implementation against the defined artifacts. - -When changing Spec Kit, first identify which part of that lifecycle your change affects. - -### Source Assets vs Generated Project Assets - -A useful distinction for maintainers is the difference between: - -- **source assets in this repository**, and -- **artifacts that users consume in their own repositories or agent sessions**. - -Source assets in this repository define behavior, structure, wording, conventions, and scaffolding rules. Generated or installed assets are the user-facing outputs of those source assets. - -When editing repository files, think in terms of downstream consequences: - -- What will change in the user-visible workflow? -- What will change in generated project content? -- What must be revalidated manually in a real end-to-end flow? - -### Main System Surfaces - -Most changes fall into one or more of these surfaces: - -- **Templates**: define workflow artifacts, prompts, scaffolding content, and generated project structure. -- **Scripts and automation**: support local generation, packaging, installation, or validation flows. -- **CLI and bootstrap behavior**: define how users initialize, install, or execute Spec Kit workflows. -- **Agent integration surfaces**: adapt the kit to specific agent environments without changing the underlying workflow intent. -- **Extensions and presets**: package additional reusable behavior or opinionated configurations. -- **Documentation**: explain the intended model, workflow, usage, and maintenance practices. - -A contributor should be able to identify which surface they are editing before making a change. - ## Repository Anatomy This section explains the role of the major repository areas. It is intended as a guided map, not a full file inventory. @@ -151,19 +107,6 @@ Edit `presets/` when you are: Presets should remain understandable as opinionated selections layered on top of the core workflow, not as silent redefinitions of that workflow. -### Documentation Surface - -Top-level and subsystem documentation explains the user model, maintainer model, testing expectations, and publishing flows. - -Edit documentation whenever code, templates, scripts, or workflow semantics change in a way that affects: - -- user understanding, -- contributor understanding, -- validation expectations, -- extension or preset author behavior. - -Do not treat docs as an afterthought. In Spec Kit, documentation is part of the product surface. - ## Change Map: If You Want to Change X, Edit Y This section is a practical routing guide. Use it before making edits. From be6d39bb6ca7553de78070bc04d69cb3eaa2f1b4 Mon Sep 17 00:00:00 2001 From: PChemGuy <39730837+pchemguy@users.noreply.github.com> Date: Thu, 2 Apr 2026 22:14:26 +0300 Subject: [PATCH 24/25] Compact DEVELOPMENT.md --- DEVELOPMENT.md | 348 +------------ Development Guide Dev/Untitled 1.md | 458 ------------------ Development Guide Dev/Untitled 2.md | 12 - Development Guide Dev/Untitled.md | 364 -------------- Development Guide Dev/deep-research-report.md | 188 ------- 5 files changed, 11 insertions(+), 1359 deletions(-) delete mode 100644 Development Guide Dev/Untitled 1.md delete mode 100644 Development Guide Dev/Untitled 2.md delete mode 100644 Development Guide Dev/Untitled.md delete mode 100644 Development Guide Dev/deep-research-report.md diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index b7a6bf5f4..03b46b31d 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -1,351 +1,25 @@ -# Development Guide +# Development Notes -This document is the primary entry point for people modifying Spec Kit itself. Use this guide when you need to understand how the repository fits together, where different kinds of changes belong, how to validate them, and which deeper documents to read next. This document is intentionally focused on system understanding, repository navigation, and change workflows. - -## Maintainer Orientation - -Spec Kit is a toolkit for spec-driven development. At its core, it is a coordinated set of prompts, templates, scripts, and CLI/integration assets that define and deliver a spec-driven workflow for AI coding agents. The tables below summarize the essential project documents and main repository surfaces for developers. +Spec Kit is a toolkit for spec-driven development. At its core, it is a coordinated set of prompts, templates, scripts, and CLI/integration assets that define and deliver a spec-driven workflow for AI coding agents. This document is a starting point for people modifying Spec Kit itself, with a compact orientation to the key project documents and repository organization. **Essential project documents:** | Document | Role | | --- | --- | | [README.md](./README.md) | Primary user-facing overview of Spec Kit and its workflow. | -| [DEVELOPMENT.md](./DEVELOPMENT.md) | Primary maintainer-facing guide to modifying Spec Kit itself. | +| [DEVELOPMENT.md](./DEVELOPMENT.md) | This document. | | [spec-driven.md](./spec-driven.md) | End-to-end explanation of the Spec-Driven Development workflow supported by Spec Kit. | | [RELEASE-PROCESS.md](./.github/workflows/RELEASE-PROCESS.md) | Release workflow, versioning rules, and changelog generation process. | | [docs/index.md](./docs/index.md) | Entry point to the `docs/` documentation set. | | [CONTRIBUTING.md](./CONTRIBUTING.md) | Contribution process, review expectations, and required development practices. | | [TESTING.md](./TESTING.md) | Validation strategy and testing procedures. | -**Main repository surfaces:** - -| Directory | Role | -| --- | --- | -| `templates/` | Prompt assets and templates that define the core workflow behavior and generated artifacts. | -| `scripts/` | Supporting scripts used by the workflow, setup, and repository tooling. | -| `src/specify_cli/` | Python source for the `specify` CLI, including agent-specific assets. | -| `extensions/` | Extension-related docs, catalogs, and supporting assets. | -| `presets/` | Preset-related docs, catalogs, and supporting assets. | - -## Repository Anatomy - -This section explains the role of the major repository areas. It is intended as a guided map, not a full file inventory. - -### `templates/` - -This directory contains the core workflow and content assets that shape the user experience. In many cases, this is the most important part of the repository because it defines the structure and wording of the spec-driven workflow itself. - -Edit `templates/` when you are changing: - -- generated artifact structure, -- workflow prompt wording, -- command or template content, -- default project scaffolding semantics. - -Treat template changes as behavior changes, not as passive documentation edits. Even small text changes can alter how users and agents interpret the workflow. - -### `scripts/` - -This directory contains automation and helper logic used for validation, packaging, generation, or related maintenance tasks. - -Edit `scripts/` when you are changing: - -- automation that supports local development, -- packaging or build helpers, -- maintenance utilities, -- validation support logic. - -Script changes should be validated both for local correctness and for their role in the broader development workflow. - -### CLI and Package Code - -Where applicable, repository code for installation, bootstrap, packaging, or command execution defines how Spec Kit is delivered and invoked. - -Edit the CLI or package code when you are changing: - -- installation behavior, -- initialization flow, -- local command behavior, -- execution semantics exposed to users. - -Changes here are usually high-impact because they affect how users enter the system. - -### Memory and Governing Assets - -Some repository assets define persistent project conventions, constitutions, or other workflow-governing content. - -Edit these assets when you are changing: - -- core workflow assumptions, -- project constitution defaults, -- stable behavioral expectations carried across the kit. - -These changes often require corresponding documentation updates because they affect the conceptual model, not just wording. - -### `extensions/` - -This area supports extension mechanisms and related publishing flows. - -Edit `extensions/` when you are: - -- adding a new extension, -- modifying extension behavior, -- updating extension packaging or publishing guidance. - -Extension changes should preserve compatibility with the main Spec Kit model unless the extension is explicitly intended to be a bounded deviation. - -### `presets/` - -This area supports reusable preset configurations and their publishing workflows. - -Edit `presets/` when you are: - -- adding a new preset, -- changing how presets are defined, -- updating preset publishing or maintenance logic. - -Presets should remain understandable as opinionated selections layered on top of the core workflow, not as silent redefinitions of that workflow. - -## Change Map: If You Want to Change X, Edit Y - -This section is a practical routing guide. Use it before making edits. - -### Change generated specification or planning content - -Start with the relevant files under `templates/`. - -Typical examples: - -- generated spec wording, -- plan structure, -- task generation wording, -- default scaffolded project artifacts. - -### Change workflow behavior or sequencing - -Inspect the relevant templates first, then any supporting script or CLI logic that participates in workflow execution. - -Typical examples: - -- command flow changes, -- stage ordering changes, -- added or removed workflow steps, -- changes in how generated assets reference one another. - -### Change installation or bootstrap behavior - -Inspect CLI or package code, install helpers, and any supporting scripts involved in setup or initialization. - -Typical examples: - -- init behavior, -- install commands, -- local executable behavior, -- package layout expectations. - -### Change user-facing documentation - -Update `README.md` and any other user-facing docs affected by the change. If the workflow model changes, also update any supporting conceptual documentation so the documented model remains aligned with actual behavior. - -### Change contributor-facing guidance - -Update `DEVELOPMENT.md`, `CONTRIBUTING.md`, `TESTING.md`, or more specialized contributor documentation as appropriate. - -### Change extension behavior or extension publishing - -Start in `extensions/` and then update related publishing guidance and any ecosystem references. - -### Change preset behavior or preset publishing - -Start in `presets/` and then update related publishing guidance and any ecosystem references. - -### Change system-wide conceptual assumptions - -Treat the change as cross-cutting. Review templates, governing assets, docs, validation expectations, and any affected packaging or integration surfaces together. - -## Development Workflows - -This section describes the normal paths for common kinds of changes. - -### Template Change Workflow - -Use this workflow when changing prompt content, generated artifact structure, or other template-defined behavior. - -1. Identify the exact user-visible behavior that should change. -2. Locate the relevant template files. -3. Make the smallest coherent change that expresses the intended behavior. -4. Review adjacent templates for consistency. -5. Update documentation if the conceptual or visible behavior changed. -6. Validate the change through focused checks and at least one realistic end-to-end flow. - -For template changes, wording is behavior. Treat wording edits with the same care as code changes. - -### Script Change Workflow - -Use this workflow when changing repository automation or support utilities. - -1. Identify the workflow that depends on the script. -2. Edit the relevant script with minimal scope. -3. Validate the script directly. -4. Validate the higher-level workflow that depends on it. -5. Update docs if the script changes how contributors or users are expected to work. - -### CLI or Bootstrap Change Workflow - -Use this workflow when changing how users enter or operate Spec Kit through commands or package installation. - -1. Identify the affected command or entry path. -2. Trace the code and any related templates or scripts. -3. Make the change with attention to backward compatibility and user expectations. -4. Validate the affected command locally. -5. Validate at least one realistic user entry flow end to end. -6. Update user-facing and developer-facing docs as needed. - -### Docs-Only Workflow - -Use this workflow when making documentation changes that do not intentionally alter behavior. - -1. Confirm that the change is actually documentation-only. -2. Update the relevant docs. -3. Check for overlap with other docs that may now be inconsistent. -4. Ensure terminology remains aligned across documents. - -Be cautious: many apparent "docs-only" changes in this repository are actually behavioral if they describe workflow semantics that templates or scripts already implement. - -### Extension or Preset Workflow - -Use this workflow when changing extension or preset assets. - -1. Identify whether the change affects the core model or only the extension/preset layer. -2. Edit the relevant extension or preset files. -3. Validate packaging, discoverability, and usage expectations. -4. Update publishing and maintenance guidance where needed. -5. Ensure the relationship to core Spec Kit remains explicit. - -## Validation and Testing Map - -This section is a routing summary. For detailed procedures, see `TESTING.md` and related validation documentation. - -### Focused Local Validation - -Use focused validation first when changing a narrow part of the system. - -Examples include: - -- validating the specific template you changed, -- running the script you modified, -- exercising the CLI path you edited, -- checking a packaging or publishing path affected by your change. - -### End-to-End Workflow Validation - -Use realistic manual validation when the change affects user-visible workflow semantics. - -This is especially important for: - -- template changes, -- command flow changes, -- initialization or bootstrap changes, -- agent-facing workflow changes. - -A change is not well validated if it only passes isolated checks but has not been exercised in a real workflow context. - -### Documentation Validation - -When behavior changes, documentation must be checked for alignment. This includes: - -- top-level user docs, -- maintainer docs, -- subsystem docs, -- extension or preset publishing docs. - -### Packaging and Distribution Validation - -When changing install, release, extension, or preset behavior, confirm that the change remains correct in the form users actually consume. - -Do not assume that source-level correctness is sufficient. - -## Architectural Invariants and Guardrails - -The following guardrails should remain true unless there is an explicit, repository-wide decision to change them. - -### Preserve Workflow Coherence - -The core spec-driven workflow should remain understandable as a staged progression from governing principles to specification, planning, tasking, and execution. - -Do not introduce local optimizations that make the overall model less coherent. - -### Preserve Cross-Surface Alignment - -Templates, scripts, CLI behavior, and docs should describe the same system. - -A contributor should not be able to follow the docs and encounter materially different behavior in the actual workflow. - -### Treat Templates as Product Logic - -Template wording, structure, and default content are part of the product, not just decoration. - -Do not make casual wording changes without considering behavioral consequences. - -### Keep Agent-Specific Adaptation Secondary to the Core Model - -Agent-specific support is important, but it should adapt the core workflow rather than fragment it into unrelated systems unless such divergence is deliberate and documented. - -### Keep Extensions and Presets Legible - -Extensions and presets should remain understandable additions or variations, not opaque redefinitions of the core workflow. - -## Common Pitfalls - -The following mistakes are easy to make in this repository. - -### Treating a Template Edit as a Mere Copy Change - -Template wording often changes behavior. Review it the same way you would review logic changes. - -### Updating One Surface but Not the Others - -A workflow change may require updates in templates, docs, tests, and installation or execution behavior. Check for cross-surface impact before considering the work complete. - -### Validating Too Narrowly - -A focused unit check may pass while the real user workflow is broken. Use end-to-end validation when the change affects behavior users or agents actually experience. - -### Letting Contributor Docs Drift - -When the repository structure or maintainer workflow changes, `DEVELOPMENT.md` and related docs need to change too. - -### Hiding a Conceptual Change Inside a Small Edit - -If a change alters the mental model or expected workflow, document it as such. Do not let significant semantic changes masquerade as tiny text cleanups. - -## Release and Compatibility Notes - -When making changes that affect packaging, installation, extensions, presets, or generated outputs, consider compatibility from the perspective of actual users and downstream maintainers. - -Questions to ask: - -Does this change - -- alter the expected workflow? -- affect generated artifacts? -- require documentation updates? -- affect extension or preset compatibility? -- need explicit release-note treatment? - -When in doubt, assume user-visible workflow changes deserve explicit documentation and release awareness. - -## Keeping This Document Healthy - -This document should evolve with the repository. - -Update it when: - -- repository structure changes, -- the maintainer mental model changes, -- new core subsystems are introduced, -- the recommended development workflow changes, -- the document map needs rerouting. +**Main repository components:** -The goal is to keep this file useful as a top-level maintainer entry point, not to turn it into an exhaustive reference manual. +| Directory | Role | +| ------------------ | ------------------------------------------------------------------------------------------- | +| `templates/` | Prompt assets and templates that define the core workflow behavior and generated artifacts. | +| `scripts/` | Supporting scripts used by the workflow, setup, and repository tooling. | +| `src/specify_cli/` | Python source for the `specify` CLI, including agent-specific assets. | +| `extensions/` | Extension-related docs, catalogs, and supporting assets. | +| `presets/` | Preset-related docs, catalogs, and supporting assets. | diff --git a/Development Guide Dev/Untitled 1.md b/Development Guide Dev/Untitled 1.md deleted file mode 100644 index 4454c598d..000000000 --- a/Development Guide Dev/Untitled 1.md +++ /dev/null @@ -1,458 +0,0 @@ -# Development Guide - -This document is the primary entry point for people modifying Spec Kit itself. - -Use this guide when you need to understand how the repository fits together, where different kinds of changes belong, how to validate them, and which deeper documents to read next. - -## Relationship to Other Top-Level Documents - -Spec Kit has several top-level documents with different roles. They should not duplicate each other. - -- `README.md` is the primary entry point for users adopting Spec Kit in a project. -- `DEVELOPMENT.md` is the primary entry point for contributors and maintainers changing Spec Kit itself. -- `CONTRIBUTING.md` defines contribution mechanics, review expectations, and required development practices. -- `TESTING.md` describes validation strategy and testing procedures in more detail. -- Other specialized documents cover specific subsystems or publishing workflows. - -This document is intentionally focused on system understanding, repository navigation, and change workflows. - -## What Spec Kit Is, from a Maintainer Perspective - -Spec Kit is a toolkit for spec-driven development. It provides a structured workflow, scaffolding assets, and supporting integrations that help users move from an idea to a defined specification, an implementation plan, task breakdowns, and executable project work. - -From a maintainer perspective, the repository is not just "documentation" and not just "code". It is a coordinated system composed of several interacting surfaces: - -- workflow-defining templates, -- command and scaffolding assets, -- scripts and automation helpers, -- CLI and installation behavior, -- agent-specific integration surfaces, -- extension and preset publishing assets, -- documentation that explains and stabilizes the user and developer model. - -Maintaining Spec Kit means preserving coherence across those surfaces. A change in one layer often affects documentation, validation expectations, and user-visible workflow behavior in other layers. - -## System Mental Model - -### Core User Workflow - -At a high level, Spec Kit supports a staged workflow in which a user moves through structured project definition and execution steps. The exact implementation details may vary by agent or integration surface, but the core conceptual flow is consistent: - -1. establish or refine governing project principles, -2. define a concrete specification, -3. derive an implementation plan, -4. derive an actionable task breakdown, -5. execute implementation against the defined artifacts. - -When changing Spec Kit, first identify which part of that lifecycle your change affects. - -### Source Assets vs Generated Project Assets - -A useful distinction for maintainers is the difference between: - -- **source assets in this repository**, and -- **artifacts that users consume in their own repositories or agent sessions**. - -Source assets in this repository define behavior, structure, wording, conventions, and scaffolding rules. Generated or installed assets are the user-facing outputs of those source assets. - -When editing repository files, think in terms of downstream consequences: - -- What will change in the user-visible workflow? -- What will change in generated project content? -- What must be revalidated manually in a real end-to-end flow? - -### Main System Surfaces - -Most changes fall into one or more of these surfaces: - -- **Templates**: define workflow artifacts, prompts, scaffolding content, and generated project structure. -- **Scripts and automation**: support local generation, packaging, installation, or validation flows. -- **CLI and bootstrap behavior**: define how users initialize, install, or execute Spec Kit workflows. -- **Agent integration surfaces**: adapt the kit to specific agent environments without changing the underlying workflow intent. -- **Extensions and presets**: package additional reusable behavior or opinionated configurations. -- **Documentation**: explain the intended model, workflow, usage, and maintenance practices. - -A contributor should be able to identify which surface they are editing before making a change. - -## Repository Anatomy - -This section explains the role of the major repository areas. It is intended as a guided map, not a full file inventory. - -### `templates/` - -This directory contains the core workflow and content assets that shape the user experience. In many cases, this is the most important part of the repository because it defines the structure and wording of the spec-driven workflow itself. - -Edit `templates/` when you are changing: - -- generated artifact structure, -- workflow prompt wording, -- command or template content, -- default project scaffolding semantics. - -Treat template changes as behavior changes, not as passive documentation edits. Even small text changes can alter how users and agents interpret the workflow. - -### `scripts/` - -This directory contains automation and helper logic used for validation, packaging, generation, or related maintenance tasks. - -Edit `scripts/` when you are changing: - -- automation that supports local development, -- packaging or build helpers, -- maintenance utilities, -- validation support logic. - -Script changes should be validated both for local correctness and for their role in the broader development workflow. - -### CLI and Package Code - -Where applicable, repository code for installation, bootstrap, packaging, or command execution defines how Spec Kit is delivered and invoked. - -Edit the CLI or package code when you are changing: - -- installation behavior, -- initialization flow, -- local command behavior, -- execution semantics exposed to users. - -Changes here are usually high-impact because they affect how users enter the system. - -### Memory and Governing Assets - -Some repository assets define persistent project conventions, constitutions, or other workflow-governing content. - -Edit these assets when you are changing: - -- core workflow assumptions, -- project constitution defaults, -- stable behavioral expectations carried across the kit. - -These changes often require corresponding documentation updates because they affect the conceptual model, not just wording. - -### `extensions/` - -This area supports extension mechanisms and related publishing flows. - -Edit `extensions/` when you are: - -- adding a new extension, -- modifying extension behavior, -- updating extension packaging or publishing guidance. - -Extension changes should preserve compatibility with the main Spec Kit model unless the extension is explicitly intended to be a bounded deviation. - -### `presets/` - -This area supports reusable preset configurations and their publishing workflows. - -Edit `presets/` when you are: - -- adding a new preset, -- changing how presets are defined, -- updating preset publishing or maintenance logic. - -Presets should remain understandable as opinionated selections layered on top of the core workflow, not as silent redefinitions of that workflow. - -### Documentation Surface - -Top-level and subsystem documentation explains the user model, maintainer model, testing expectations, and publishing flows. - -Edit documentation whenever code, templates, scripts, or workflow semantics change in a way that affects: - -- user understanding, -- contributor understanding, -- validation expectations, -- extension or preset author behavior. - -Do not treat docs as an afterthought. In Spec Kit, documentation is part of the product surface. - -## Change Map: If You Want to Change X, Edit Y - -This section is a practical routing guide. Use it before making edits. - -### Change generated specification or planning content - -Start with the relevant files under `templates/`. - -Typical examples: - -- generated spec wording, -- plan structure, -- task generation wording, -- default scaffolded project artifacts. - -### Change workflow behavior or sequencing - -Inspect the relevant templates first, then any supporting script or CLI logic that participates in workflow execution. - -Typical examples: - -- command flow changes, -- stage ordering changes, -- added or removed workflow steps, -- changes in how generated assets reference one another. - -### Change installation or bootstrap behavior - -Inspect CLI or package code, install helpers, and any supporting scripts involved in setup or initialization. - -Typical examples: - -- init behavior, -- install commands, -- local executable behavior, -- package layout expectations. - -### Change user-facing documentation - -Update `README.md` and any other user-facing docs affected by the change. If the workflow model changes, also update any supporting conceptual documentation so the documented model remains aligned with actual behavior. - -### Change contributor-facing guidance - -Update `DEVELOPMENT.md`, `CONTRIBUTING.md`, `TESTING.md`, or more specialized contributor documentation as appropriate. - -### Change extension behavior or extension publishing - -Start in `extensions/` and then update related publishing guidance and any ecosystem references. - -### Change preset behavior or preset publishing - -Start in `presets/` and then update related publishing guidance and any ecosystem references. - -### Change system-wide conceptual assumptions - -Treat the change as cross-cutting. Review templates, governing assets, docs, validation expectations, and any affected packaging or integration surfaces together. - -## Development Workflows - -This section describes the normal paths for common kinds of changes. - -### Template Change Workflow - -Use this workflow when changing prompt content, generated artifact structure, or other template-defined behavior. - -1. Identify the exact user-visible behavior that should change. -2. Locate the relevant template files. -3. Make the smallest coherent change that expresses the intended behavior. -4. Review adjacent templates for consistency. -5. Update documentation if the conceptual or visible behavior changed. -6. Validate the change through focused checks and at least one realistic end-to-end flow. - -For template changes, wording is behavior. Treat wording edits with the same care as code changes. - -### Script Change Workflow - -Use this workflow when changing repository automation or support utilities. - -1. Identify the workflow that depends on the script. -2. Edit the relevant script with minimal scope. -3. Validate the script directly. -4. Validate the higher-level workflow that depends on it. -5. Update docs if the script changes how contributors or users are expected to work. - -### CLI or Bootstrap Change Workflow - -Use this workflow when changing how users enter or operate Spec Kit through commands or package installation. - -1. Identify the affected command or entry path. -2. Trace the code and any related templates or scripts. -3. Make the change with attention to backward compatibility and user expectations. -4. Validate the affected command locally. -5. Validate at least one realistic user entry flow end to end. -6. Update user-facing and developer-facing docs as needed. - -### Docs-Only Workflow - -Use this workflow when making documentation changes that do not intentionally alter behavior. - -1. Confirm that the change is actually documentation-only. -2. Update the relevant docs. -3. Check for overlap with other docs that may now be inconsistent. -4. Ensure terminology remains aligned across documents. - -Be cautious: many apparent "docs-only" changes in this repository are actually behavioral if they describe workflow semantics that templates or scripts already implement. - -### Extension or Preset Workflow - -Use this workflow when changing extension or preset assets. - -1. Identify whether the change affects the core model or only the extension/preset layer. -2. Edit the relevant extension or preset files. -3. Validate packaging, discoverability, and usage expectations. -4. Update publishing and maintenance guidance where needed. -5. Ensure the relationship to core Spec Kit remains explicit. - -## Validation and Testing Map - -This section is a routing summary. For detailed procedures, see `TESTING.md` and related validation documentation. - -### Focused Local Validation - -Use focused validation first when changing a narrow part of the system. - -Examples include: - -- validating the specific template you changed, -- running the script you modified, -- exercising the CLI path you edited, -- checking a packaging or publishing path affected by your change. - -### End-to-End Workflow Validation - -Use realistic manual validation when the change affects user-visible workflow semantics. - -This is especially important for: - -- template changes, -- command flow changes, -- initialization or bootstrap changes, -- agent-facing workflow changes. - -A change is not well validated if it only passes isolated checks but has not been exercised in a real workflow context. - -### Documentation Validation - -When behavior changes, documentation must be checked for alignment. This includes: - -- top-level user docs, -- maintainer docs, -- subsystem docs, -- extension or preset publishing docs. - -### Packaging and Distribution Validation - -When changing install, release, extension, or preset behavior, confirm that the change remains correct in the form users actually consume. - -Do not assume that source-level correctness is sufficient. - -## Documentation Map - -This section routes contributors to the right deeper documents. - -### `README.md` - -Primary user-facing introduction. - -Read this when you need to understand how the repository presents itself to adopters and what promises are made to users. - -### `CONTRIBUTING.md` - -Contribution process, expectations, and contribution hygiene. - -Read this before opening a pull request or when you need the repository's current contribution rules. - -### `TESTING.md` - -Validation strategy and test guidance. - -Read this when planning or executing validation for non-trivial changes. - -### Extension Publishing Documentation - -Read the extension-specific publishing guide when working on extension creation, packaging, or publication. - -### Preset Publishing Documentation - -Read the preset-specific publishing guide when working on preset creation, packaging, or publication. - -### Other Specialized Documents - -Read subsystem-specific documents when your change targets a specific area rather than the core maintainer workflow. - -As the repository evolves, keep this section curated. It should remain a developer routing table, not a raw list of markdown files. - -## Architectural Invariants and Guardrails - -The following guardrails should remain true unless there is an explicit, repository-wide decision to change them. - -### Preserve Workflow Coherence - -The core spec-driven workflow should remain understandable as a staged progression from governing principles to specification, planning, tasking, and execution. - -Do not introduce local optimizations that make the overall model less coherent. - -### Preserve Cross-Surface Alignment - -Templates, scripts, CLI behavior, and docs should describe the same system. - -A contributor should not be able to follow the docs and encounter materially different behavior in the actual workflow. - -### Treat Templates as Product Logic - -Template wording, structure, and default content are part of the product, not just decoration. - -Do not make casual wording changes without considering behavioral consequences. - -### Keep Agent-Specific Adaptation Secondary to the Core Model - -Agent-specific support is important, but it should adapt the core workflow rather than fragment it into unrelated systems unless such divergence is deliberate and documented. - -### Keep Extensions and Presets Legible - -Extensions and presets should remain understandable additions or variations, not opaque redefinitions of the core workflow. - -## Common Pitfalls - -The following mistakes are easy to make in this repository. - -### Treating a Template Edit as a Mere Copy Change - -Template wording often changes behavior. Review it the same way you would review logic changes. - -### Updating One Surface but Not the Others - -A workflow change may require updates in templates, docs, tests, and installation or execution behavior. Check for cross-surface impact before considering the work complete. - -### Validating Too Narrowly - -A focused unit check may pass while the real user workflow is broken. Use end-to-end validation when the change affects behavior users or agents actually experience. - -### Letting Contributor Docs Drift - -When the repository structure or maintainer workflow changes, `DEVELOPMENT.md` and related docs need to change too. - -### Hiding a Conceptual Change Inside a Small Edit - -If a change alters the mental model or expected workflow, document it as such. Do not let significant semantic changes masquerade as tiny text cleanups. - -## Release and Compatibility Notes - -When making changes that affect packaging, installation, extensions, presets, or generated outputs, consider compatibility from the perspective of actual users and downstream maintainers. - -Questions to ask: - -Does this change - -- alter the expected workflow? -- affect generated artifacts? -- require documentation updates? -- affect extension or preset compatibility? -- need explicit release-note treatment? - -When in doubt, assume user-visible workflow changes deserve explicit documentation and release awareness. - -## Maintainer Onboarding Checklist - -A new maintainer should usually do the following before making broad changes: - -1. read `README.md` to understand the user-facing model, -2. read this document to understand the maintainer-facing model, -3. read `CONTRIBUTING.md` before preparing changes, -4. read `TESTING.md` before validating non-trivial work, -5. inspect the repository layout, especially `templates/`, `scripts/`, and any CLI or packaging code, -6. trace at least one representative end-to-end workflow, -7. start with a narrow, well-scoped change before attempting structural revisions. - -## Keeping This Document Healthy - -This document should evolve with the repository. - -Update it when: - -- repository structure changes, -- the maintainer mental model changes, -- new core subsystems are introduced, -- the recommended development workflow changes, -- the document map needs rerouting. - -The goal is to keep this file useful as a top-level maintainer entry point, not to turn it into an exhaustive reference manual. diff --git a/Development Guide Dev/Untitled 2.md b/Development Guide Dev/Untitled 2.md deleted file mode 100644 index adfccb663..000000000 --- a/Development Guide Dev/Untitled 2.md +++ /dev/null @@ -1,12 +0,0 @@ -Top-level documents are not sufficient for full onboarding. Before editing, read the relevant subsystem documentation for the surface you plan to modify. - -Use the following routing guide. - -| If you plan to change... | Read... | -| -------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | -| Core workflow templates and generated artifact structure | The relevant documents under `templates/` and any linked workflow-specific documentation | -| Validation behavior or test expectations | [TESTING.md](./TESTING.md) and any related subsystem-specific testing documentation | -| Extensions | The documentation under `extensions/`, including extension publishing and maintenance guidance | -| Presets | The documentation under `presets/`, including preset publishing and maintenance guidance | -| User-facing workflow semantics | The relevant templates, [README.md](./README.md), and any conceptual workflow documentation | -| Installation, packaging, or bootstrap behavior | The relevant CLI/package code, scripts, and associated development or publishing documentation | diff --git a/Development Guide Dev/Untitled.md b/Development Guide Dev/Untitled.md deleted file mode 100644 index 761bacda7..000000000 --- a/Development Guide Dev/Untitled.md +++ /dev/null @@ -1,364 +0,0 @@ -Yes, it makes sense. - -A top-level `DEVELOPMENT.md` is a good fit here because the current `README.md` is clearly optimized for users adopting Spec Kit in projects, while `CONTRIBUTING.md` is narrower: contribution mechanics, validation flow, and PR hygiene. It is not really a full developer mental-model document. The repo also already has specialized docs like `TESTING.md`, the extension publishing guide, and preset publishing guide, which means a developer-facing entry document should primarily orient, map, and route rather than duplicate details. ([GitHub][1]) - -I would treat `DEVELOPMENT.md` as the **developer map of the system**: - -* what Spec Kit is internally, -* how the repository is organized, -* how the main moving parts interact, -* where to edit for each class of change, -* how to validate changes, -* and where deeper docs live. - That is the missing layer between user docs and contribution rules. ([GitHub][1]) - -## What `DEVELOPMENT.md` should do - -It should not try to be: - -* another `README.md`, -* another `CONTRIBUTING.md`, -* or a giant reference manual. - -It should be the **primary entry point for maintainers and contributors who need system understanding before editing**. - -The right emphasis is: - -1. mental model, -2. repository anatomy, -3. change workflows, -4. document map, -5. common modification scenarios. - -That is especially important in this repo because the core is not just Python code; it is a coordinated kit of templates, scripts, CLI behavior, agent integrations, memory files, extensions, presets, and documentation. The current docs already imply this multi-part system, but they are distributed across several places. ([GitHub][2]) - -## Recommended top-level structure - -Here is the outline I would use. - -### 1. Purpose of this document - -Very short. Explain that: - -* `README.md` is for users adopting Spec Kit, -* `DEVELOPMENT.md` is for people modifying Spec Kit itself, -* `CONTRIBUTING.md` covers contribution process and PR expectations, -* deeper component docs are linked below. ([GitHub][2]) - -### 2. What Spec Kit is, from a maintainer perspective - -Give a concise internal framing, for example: - -* Spec Kit is a toolkit for Spec-Driven Development. -* The repo packages prompts/templates, command scaffolding, scripts, CLI support, agent-specific integration assets, and ecosystem mechanisms such as extensions and presets. -* The generated user workflow is roughly: constitution → specify → plan → tasks → implement. ([GitHub][1]) - -This section should answer: **what are we actually maintaining?** - -### 3. System mental model - -This is one of the most important sections. - -Suggested subsections: - -* **Core artifact flow** - How the main SDD flow progresses through constitution, specification, plan, tasks, implementation. ([GitHub][1]) -* **Delivery model** - Clarify what lives in the repo versus what gets installed/scaffolded into user projects. -* **Main abstraction layers** - For example: - - * templates/content, - * command scaffolding, - * CLI/bootstrap/install logic, - * agent-specific integration surfaces, - * extension/preset ecosystem, - * docs/catalog/community surfaces. - -A simple diagram would help a lot here. - -### 4. Repository anatomy - -This should be a guided map, not just a tree dump. - -For each major top-level area, explain: - -* what it contains, -* why it exists, -* when to edit it, -* what else it interacts with. - -You already mentioned this, and yes, it should absolutely be included. - -Likely subsections: - -* `templates/` — core artifact templates and command templates; probably the most important content layer for generated workflow behavior. The repo README and contribution workflow both point contributors to template validation. ([GitHub][2]) -* `scripts/` — automation/bootstrap/helper scripts; `CONTRIBUTING.md` explicitly calls out script functionality as something contributors should test. ([GitHub][2]) -* `memory/` or `.specify/memory`-related assets — constitution/project-memory behavior; contribution guidance explicitly references `memory/constitution.md` updates for major process changes. ([GitHub][2]) -* CLI/package code — where install/scaffold behavior and local `specify` execution live. -* `extensions/` — extension model and publishing support; the repo includes a dedicated extension publishing guide. ([GitHub][3]) -* `presets/` — preset model and publishing support; there is also a dedicated presets publishing guide. ([GitHub][4]) -* catalogs/community metadata — where ecosystem discoverability is maintained; the README includes community extensions, presets, walkthroughs, and related ecosystem surfaces. ([GitHub][5]) -* top-level docs — which are user docs, contributor docs, testing docs, release docs, etc. - -### 5. “If you want to change X, edit Y” - -This is the most practical section, and many repos miss it. - -Examples: - -* To change the wording/structure of generated feature specs → edit relevant template files. -* To change slash-command behavior or workflow sequencing → inspect command templates plus any supporting scripts/CLI glue. -* To change installation/bootstrap behavior → inspect CLI/package/bootstrap code. -* To add or modify extension publishing behavior → see `extensions/EXTENSION-PUBLISHING-GUIDE.md`. -* To add or modify presets behavior → see `presets/PUBLISHING.md`. -* To adjust docs shown to end users → update `README.md` and possibly `spec-driven.md`, which `CONTRIBUTING.md` explicitly names for user-facing changes. ([GitHub][2]) - -This section makes the doc operational instead of descriptive. - -### 6. End-to-end development workflows - -Not contribution policy in the abstract, but concrete developer workflows. - -Suggested subsections: - -* **Template change workflow** -* **Script change workflow** -* **CLI/bootstrap change workflow** -* **Docs-only workflow** -* **Extension/preset/catalog change workflow** - -For each: - -* where to edit, -* how to test locally, -* what docs to update, -* what regressions to watch for. - -This aligns well with the current contribution guidance, which already says to test CLI commands in an agent, verify templates in `templates/`, test scripts in `scripts/`, and update memory/docs where relevant. ([GitHub][2]) - -### 7. Validation and testing map - -Do not restate all of `TESTING.md`. Instead, summarize the validation layers and link outward. - -Suggested structure: - -* quick local checks, -* focused automated checks, -* manual workflow tests in real agents, -* packaging/release-output validation, -* when each level is required. - -This matches the current recommended validation flow in `CONTRIBUTING.md`, which points developers to focused automated checks first, then manual workflow tests, then local release package inspection when needed. ([GitHub][2]) - -### 8. Documentation map - -This should be explicit and curated. - -A table works well: - -| Document | Audience | Purpose | When to read | -| -------- | -------- | ------- | ------------ | - -Include at least: - -* `README.md` -* `CONTRIBUTING.md` -* `TESTING.md` -* `spec-driven.md` -* `extensions/EXTENSION-PUBLISHING-GUIDE.md` -* `presets/PUBLISHING.md` -* maybe `CHANGELOG.md` and release-related docs if relevant. ([GitHub][2]) - -This section is especially valuable because the repo’s documentation surface has grown. - -### 9. Architectural invariants / guardrails - -This is another high-value section. - -List the things maintainers should preserve, such as: - -* user workflow consistency across supported agents, -* template and script changes should remain compatible with the expected SDD flow, -* generated artifacts and packaging should remain coherent, -* docs and templates must stay aligned, -* agent-specific adaptations should not silently break the general model. - -These should be framed as maintainer guardrails, not as vague philosophy. The README’s emphasis on the standard workflow and the contribution doc’s insistence on testing the CLI workflow with real agents strongly suggest this kind of invariant section is warranted. ([GitHub][1]) - -### 10. Common pitfalls - -Very useful for new contributors. - -Examples: - -* changing a template without validating it through an actual agent flow, -* updating docs but not generated behavior, -* changing workflow semantics without updating memory/process docs, -* forgetting ecosystem/catalog impact, -* testing only source form but not packaged output. ([GitHub][2]) - -### 11. Release-awareness and compatibility notes - -Brief section only. - -Could cover: - -* generated assets vs source assets, -* keeping changes compatible across agent modes, -* watching changelog/release behavior, -* any versioning expectations for templates/extensions/presets where applicable. ([GitHub][6]) - -### 12. Getting started as a maintainer - -A compact onboarding checklist: - -* read this document, -* read `CONTRIBUTING.md`, -* read `TESTING.md`, -* inspect repository layout, -* run local install, -* run representative workflow tests, -* make a narrow change first. - -## What else to include beyond your current idea - -Your instinct is right, but I would add four things that are easy to overlook: - -### A. A maintainer mental model, not just repository overview - -Without this, the document becomes a directory tour. - -The key question is: -**How do templates, scripts, CLI/bootstrap, docs, and ecosystem surfaces combine to produce the user experience?** - -That is the real “developer README”. - -### B. Change-oriented guidance - -The “if you want to change X, edit Y” section is disproportionately valuable. - -It reduces contributor hesitation and prevents wrong-entry-point edits. - -### C. Invariants / non-obvious rules - -These are the things experienced maintainers know but new contributors do not. - -For Spec Kit, that likely includes preserving the workflow sequence and validating changes in real agent flows rather than treating the repo as ordinary static docs. ([GitHub][2]) - -### D. A curated doc index - -Not a raw list of files. A role-based map. - -That is what turns scattered documentation into an actual developer entry point. - -## What not to do - -I would avoid: - -* duplicating installation instructions from `README.md`, -* duplicating PR policy from `CONTRIBUTING.md`, -* duplicating detailed test procedures from `TESTING.md`, -* documenting every file, -* writing a long historical narrative. - -`DEVELOPMENT.md` should stay navigational and architectural. - -## Suggested section order - -If you want a clean final shape, I would order it like this: - -1. Purpose of this document -2. Spec Kit at a glance for maintainers -3. System mental model -4. Repository anatomy -5. Change map: if you want to change X, edit Y -6. Development workflows -7. Validation and testing map -8. Documentation map -9. Architectural invariants and guardrails -10. Common pitfalls -11. Release and compatibility notes -12. Maintainer onboarding checklist - -## My recommendation on naming - -`DEVELOPMENT.md` is a reasonable name here. It is more natural than `README_DEV.md`. - -`README_DEV.md` is understandable, but it feels slightly ad hoc. `DEVELOPMENT.md` reads like a first-class top-level maintainer document and pairs well with `README.md`, `CONTRIBUTING.md`, `TESTING.md`, and `CHANGELOG.md`. That naming style is also consistent with the repo already having specialized top-level docs rather than overloading a second README. ([GitHub][2]) - -## A compact draft outline you can start from - -```md -# Development Guide - -## 1. Purpose -- Who this document is for -- How it differs from README.md and CONTRIBUTING.md - -## 2. Spec Kit for Maintainers -- What Spec Kit is internally -- Core workflow it supports -- Main system surfaces - -## 3. System Mental Model -### 3.1 Artifact and workflow lifecycle -### 3.2 Source assets vs generated/project assets -### 3.3 Templates, scripts, CLI, agent integrations, extensions, presets - -## 4. Repository Anatomy -### 4.1 templates/ -### 4.2 scripts/ -### 4.3 CLI/package code -### 4.4 memory assets -### 4.5 extensions/ -### 4.6 presets/ -### 4.7 catalogs and community metadata -### 4.8 top-level docs - -## 5. If You Want to Change X, Edit Y -- Generated artifact content -- Workflow behavior -- Installation/bootstrap -- Docs -- Extensions -- Presets -- Catalog/community entries - -## 6. Development Workflows -### 6.1 Template changes -### 6.2 Script changes -### 6.3 CLI/bootstrap changes -### 6.4 Docs-only changes -### 6.5 Extension/preset/catalog changes - -## 7. Validation and Testing Map -- Automated checks -- Manual agent-flow validation -- Packaged-output validation -- When each is needed - -## 8. Documentation Map -- README.md -- CONTRIBUTING.md -- TESTING.md -- spec-driven.md -- extension/preset publishing docs -- changelog/release docs - -## 9. Architectural Invariants -- Workflow consistency -- Cross-agent compatibility -- Docs/templates alignment -- Packaging/scaffolding integrity - -## 10. Common Pitfalls - -## 11. Release and Compatibility Notes - -## 12. Maintainer Onboarding Checklist -``` - -This is the structure I would use unless you want `DEVELOPMENT.md` to be intentionally shorter and more of a “developer landing page” that links out aggressively. - -I can turn this into a concrete first-pass `DEVELOPMENT.md` skeleton with section text, not just the outline. diff --git a/Development Guide Dev/deep-research-report.md b/Development Guide Dev/deep-research-report.md deleted file mode 100644 index c81ff9acb..000000000 --- a/Development Guide Dev/deep-research-report.md +++ /dev/null @@ -1,188 +0,0 @@ -# Deep research on Spec Kit development documentation coverage - -## Executive summary - -The GitHub github/spec-kit repository does contain **meaningful developer-oriented documentation** that explains *how templates fit into Spec Kit’s workflow*—especially in the main README.md, the DocFX-backed docs/ site sources, AGENTS.md, and the preset system documentation (presets/README.md \+ presets/ARCHITECTURE.md). These sources provide a workable mental model for the **Spec‑Driven Development (SDD) lifecycle**, and for **template resolution / overrides** (core vs extensions vs presets vs project overrides). - -However, the repository does **not** appear to contain a **single, systematic, developer-facing “Template System” guide** that (a) enumerates **every file under templates/**, (b) explains each one’s role in the pipeline, and (c) provides **glue/jump-start guidance** for maintainers (how to safely modify templates, keep scripts and command prompts aligned, and test changes end-to-end). The absence of an index/README inside templates/ and multiple “path confusion” / “template behavior confusion” issues suggest the mental model is dispersed and easy to miss. - -## Inventory and analysis of templates/ - -### Directory structure overview - -At the time of review (repo main), templates/ contains 7 top-level assets plus a commands/ subdirectory with 9 command templates (total: 16 files). - -### Table of all files under templates/ - -The “Developer-oriented guidance?” column below is strictly about **human-developer onboarding/mental model** content *inside the file itself* (as opposed to “LLM-facing instructions that a developer could reverse-engineer”). Many of these files primarily serve as **prompt directives/templates** for agents, which is useful but not the same as curated developer documentation. - -| File (path) | Purpose (what it is for) | Type | Developer-oriented guidance inside file? | -| :---------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------: | :--------------------------------------------------------------------------------------------------------------------------------------- | -| templates/agent-file-template.md | Skeleton for a generated “Development Guidelines” / agent context file (placeholders for technologies, structure, commands, recent changes, plus a manual-additions region). | md | **Partial**: structure \+ placeholders; minimal “why/how.” | -| templates/checklist-template.md | Output template for checklist artifacts; explicitly notes generation by /speckit.checklist and includes a large **“sample items must be replaced”** instruction block. | md | **Yes (light)**: explains it is command-generated and warns not to keep sample items. | -| templates/constitution-template.md | Placeholder constitution format (principles, governance, version metadata) with inline examples in comments. | md | **Partial**: examples hint at intent; not a full maintainer guide. | -| templates/plan-template.md | Output template for a feature’s implementation plan and design artifacts; includes “technical context,” constitution gate, project structure, and phased deliverables. It states it’s filled by /speckit.plan. | md | **Yes (moderate)**: contains “ACTION REQUIRED” guidance and process structure, but mostly LLM/task-facing rather than maintainer-facing. | -| templates/spec-template.md | Output template for feature specifications (user stories, acceptance scenarios, requirement structure). Includes strong guidance on testable, prioritized stories. | md | **Yes (moderate)**: good guidance for spec authors; still not a “template system” doc. | -| templates/tasks-template.md | Output template for actionable task lists; includes prerequisites, path conventions, parallelization strategy, and “sample tasks must be replaced” warnings. | md | **Yes (high)**: substantial operational guidance for task authoring and organization. | -| templates/vscode-settings.json | VS Code settings enabling prompt file recommendations for speckit.\* and auto-approving terminal tools in .specify/scripts/\*\*. | data (json) | **No**: configuration only; no explanatory doc text. | -| templates/commands/analyze.md | Command prompt for /speckit.analyze: read-only cross-artifact consistency/quality pass (spec/plan/tasks), driven via prerequisite script outputs. | md | **Yes (moderate)**: documents what analysis does and constraints; still “agent instruction.” | -| templates/commands/checklist.md | Command prompt for /speckit.checklist: frames checklists as “unit tests for requirements writing” and clarifies what they’re *not* (not implementation verification). | md | **Yes (high)**: contains a clear mental model and usage framing. | -| templates/commands/clarify.md | Command prompt for /speckit.clarify: targeted clarification questions, completion before planning, and a handoff to /speckit.plan. | md | **Yes (moderate)**: documents where clarify fits and why. | -| templates/commands/constitution.md | Command prompt for /speckit.constitution: fill constitution template and propagate changes to dependent artifacts; includes explicit note about .specify/memory/constitution.md and initialization from templates. | md | **Yes (moderate)**: provides maintainer-relevant propagation expectations. | -| templates/commands/implement.md | Command prompt for /speckit.implement: execute tasks, check checklists, apply extension hooks, and enforce safety constraints (secrets patterns, etc.). | md | **Yes (moderate)**: good operational constraints; not an architecture guide. | -| templates/commands/plan.md | Command prompt for /speckit.plan: sets up plan workflow using scripts; includes handoffs to tasks and checklist; references loading templates copied into place. | md | **Yes (moderate)**: explains sequencing and handoffs. | -| templates/commands/specify.md | Command prompt for /speckit.specify: create/update feature spec from natural language; handoffs to plan and clarify; calls create-new-feature script. | md | **Yes (moderate)**: explains behavior and chaining. | -| templates/commands/tasks.md | Command prompt for /speckit.tasks: generate tasks from design artifacts; handoffs to analyze \+ implement; uses prerequisite scripts. | md | **Yes (moderate)**: describes role in lifecycle. | -| templates/commands/taskstoissues.md | Command prompt for converting tasks into GitHub issues; includes issue\_write tool usage and explicit guardrails to only act on matching GitHub remotes. | md | **Yes (light)**: explains constraints; minimal broader context. | - -### What the templates collectively imply as a mental model - -Across the command templates (templates/commands/\*.md) and artifact templates (\*-template.md), a consistent implied model emerges: - -* **Commands** (specify/clarify/plan/tasks/analyze/implement/checklist/…) define *procedures \+ guardrails* for an AI agent. Many include prerequisite scripts, expected inputs/outputs, and optional handoffs to the next command. -* **Templates** (spec-template.md, plan-template.md, tasks-template.md, etc.) define *artifact structure* and embed quality constraints (e.g., “replace sample tasks,” “prioritized, independently testable user stories”). -* Some files mix guidance roles (e.g., tasks-template.md doubles as a playbook for parallelization and incremental delivery). - -This is strong “operational documentation,” but it is **not packaged as a maintainer-facing, systematic explanation of the template system**. - -## Repository documentation that explains templates for developers - -### Core docs that supply “glue” and a developer mental model - -The repository’s main README.md explains key “template system” concepts in a developer-friendly way: - -* It describes a **priority stack** for template resolution with a Mermaid diagram and explicitly states that templates are resolved at runtime (highest-priority match wins), while commands are applied at install time. -* It also shows example project directory structures and demonstrates where templates live after initialization (under .specify/templates/ in the user project). - -The DocFX-backed docs/ content includes: - -* A quickstart that describes the end-to-end **6-step workflow** (init → constitution → specify → clarify → plan → tasks → implement) and emphasizes **“context awareness”** via active feature detection (branch-based). -* Installation and upgrade guidance that clarifies what “project files” get refreshed (commands, scripts, templates, memory) versus what is “safe” (specs/ and code), and explicitly discusses .specify/templates/ as upgrade-targeted infrastructure. -* Local development instructions for iterating on the CLI without release publishing, including running via python \-m src.specify\_cli and uvx \--from .. -* The docs/README.md indicates docs are built via DocFX and deployed to GitHub Pages. - -AGENTS.md is a maintainer-oriented guide that explains how agent integrations work (directory conventions, command formats, argument placeholders) and gives a step-by-step procedure for adding support for new tools/agents. - -### Presets / extensions documentation that clarifies template customization - -The repository contains a fairly systematic explanation of template customization mechanics in the **preset system** docs: - -* presets/README.md defines presets as priority-ordered overrides for templates and commands, explains runtime template resolution vs install-time command registration, and documents specify preset resolve for tracing resolution. -* presets/ARCHITECTURE.md goes deeper: it includes Mermaid diagrams for template resolution and command registration, and explicitly lists the multiple implementations (Python \+ Bash \+ PowerShell) to keep behavior consistent. -* The extensions system docs and publishing guide define expected repo structures and strongly encourage extension documentation quality (README structure, command documentation, etc.). - -This preset documentation is the closest thing in-repo to a “template architecture doc,” but it is **scoped to presets** rather than the canonical templates/ directory inventory. - -## Issues, pull requests, and discussions that surface documentation gaps - -A recurring theme in repo activity is **path confusion** and missing “single source of truth” documentation for where templates/commands/scripts “should live” and how they relate (repo-internal templates/ vs installed .specify/templates/). - -### Repeated path and structure confusion - -* Some users flagged incorrect or confusing path references from templates to command files, e.g., plan-template.md referencing a .specify/templates/commands/... path that didn’t match expectations. -* Multiple issues question whether templates and scripts should refer to /templates/... vs /.specify/templates/..., and whether specs belong under .specify/specs/ or at repo root—indicating onboarding/docs ambiguity and drift. - -### Template mutability and “who is allowed to edit what” - -* A reported behavior: an agent (Codex CLI) modified files in .specify/templates during /speckit.constitution, even though templates were expected to remain base assets only updated on init/upgrade. This is a classic “mental model mismatch” symptom: users lack explicit, enforced rules (and docs) about mutability boundaries. - -### “How do I test template changes?” as a maintainership pain point - -* A maintainer/dev workflow issue: local modifications to templates/commands/\*.md and scripts were “ignored” because init flows pulled templates from releases (at least in the reported environment), making it hard to validate changes without publishing. - -### Explicit calls for onboard-oriented guidance - -* Issue \#295 explicitly proposes onboarding improvements (tour, quick reference, diagram) to reinforce the Specify → Plan → Tasks sequence and discourage users from running later steps out of order. - -### PR signals related to templates as a customizable surface - -* PR \#1466 (open as viewed) proposes removing branch-numbering logic from a template and adding a \--template-repo option to specify init so users can pull templates from a fork—an implicit acknowledgement that templates are a customization surface that benefits from better “how to modify safely” documentation. -* PR \#1987 (open as viewed) is nominally a docs rename, but the “files changed” view indicates it includes functional modifications related to template format selection (“compact” templates). Even the existence of a “compact format” notion increases the need for a single, coherent template developer guide. -* Recent/active issues discuss template resolution improvements (e.g., adding resolver/source attribution for extension templates). - -## Gaps in systematic developer-oriented documentation - -### Missing “one-stop” index for template assets - -The repository has strong building blocks (command templates that describe their behavior; a README that explains resolution stacks; preset architecture docs). But there is no central document that answers, in one place: - -* *What are all template files and command templates?* (Inventory \+ purpose) -* *Which ones are inputs vs outputs?* (What gets copied into a project vs generated as feature artifacts) -* *Which scripts and CLI operations touch which files?* -* *What is “safe to edit,” when, and by whom?* (Human vs agent vs init/upgrade) -* *How to test a template change end-to-end without publishing a release?* - -The lack of such a doc is consistent with the volume of issues asking where assets belong and how tooling should interpret them. - -### “Developer-oriented” guidance is embedded, but mostly LLM-facing - -Many template/command files contain substantial guidance, but it is largely phrased as **agent instructions** (MUST/SHOULD), not as curated maintainer documentation. That’s helpful for reverse engineering, yet brittle as onboarding material—particularly when paths or assumptions drift. - -Concrete example: tasks-template.md is rich in operational guidance but serves primarily as *an output template \+ generator contract*, not a doc explaining how to evolve the template system. - -## Recommendations for documentation to add - -### Add a maintainer-facing “Template System” guide - -A strong candidate is docs/templates.md (and link it from docs/index.md \+ root README), or a templates/README.md plus a doc-site page. The doc should explicitly bridge: - -* repo templates/\*\* (source of truth) -* installed .specify/templates/\*\* (copied into projects) -* generated specs/\/\*.md artifacts (outputs) - -**Proposed outline** - -* Purpose of templates vs commands vs scripts vs memory -* Full inventory of templates/ (auto-generate this table in CI to prevent drift) -* Artifact lifecycle: what every /speckit.\* reads/writes -* Mutability rules: what agents may edit vs what must remain stable -* Path conventions and historical migrations (templates/ → .specify/templates/) -* Testing workflow for template changes (local, without publishing) - -**Example content snippet (illustrative)** - -``` -## Template roles - -- templates/*-template.md: base artifact formats copied into .specify/templates/ -- templates/commands/*.md: agent command procedures installed into agent-specific folders -- scripts/**: runtime glue (select active feature, copy templates, update agent context) -``` - -### Add a Mermaid “project structure + flow” diagram set - -The repo already uses Mermaid for template/preset diagrams; extend that style to make the *full pipeline* obvious. - -Suggested diagrams to include (and where) - -* In docs/quickstart.md (or a new docs/how-it-works.md): - * **SDD lifecycle flowchart**: constitution → specify → clarify → plan → tasks → analyze/checklist → implement → taskstoissues -* In the proposed template guide: - * **File I/O map**: each command node lists inputs/outputs (e.g., clarify reads spec.md, writes clarifications back; plan reads spec.md \+ constitution, writes plan.md \+ design docs; tasks reads plan.md \+ artifacts, writes tasks.md). -* In the preset/extension docs (already present): - * Keep the **template resolution stack**, but cross-link to the main template guide. - -### Add a “Template change checklist” for contributors - -Given recurring drift issues, introduce a short checklist (either in CONTRIBUTING.md or a dedicated doc) that enforces cross-asset consistency: - -* If you change spec-template.md, confirm: - * templates/commands/specify.md instructions remain aligned - * templates/commands/clarify.md taxonomy still matches spec sections -* If you change template paths or structure: - * update Bash + PowerShell scripts consistently (and the preset resolver references, if applicable) - * Add “Docs impact” section: update docs/upgrade.md and docs/quickstart.md if user-facing behavior changed. - -### Add “How to test template/command changes locally” documentation - -Augment docs/local-development.md with a template-focused section that addresses the reported pain: - -* How to run the CLI from source (python \-m src.specify\_cli ...) -* How to initialize a sandbox project using local assets -* How to validate that the sandbox project is using your modified templates/commands/scripts -* How to run a minimal “golden path” (specify → plan → tasks) to ensure nothing breaks - -This would directly address the workflow gap implied by “local changes ignored” reports. - ---- - From 7a9fb0d102ac053678fa23e755dbc418405947c6 Mon Sep 17 00:00:00 2001 From: PChemGuy <39730837+pchemguy@users.noreply.github.com> Date: Thu, 2 Apr 2026 22:29:38 +0300 Subject: [PATCH 25/25] Update DEVELOPMENT.md --- DEVELOPMENT.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 03b46b31d..dc35bc6fe 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -4,15 +4,15 @@ Spec Kit is a toolkit for spec-driven development. At its core, it is a coordina **Essential project documents:** -| Document | Role | -| --- | --- | -| [README.md](./README.md) | Primary user-facing overview of Spec Kit and its workflow. | -| [DEVELOPMENT.md](./DEVELOPMENT.md) | This document. | -| [spec-driven.md](./spec-driven.md) | End-to-end explanation of the Spec-Driven Development workflow supported by Spec Kit. | -| [RELEASE-PROCESS.md](./.github/workflows/RELEASE-PROCESS.md) | Release workflow, versioning rules, and changelog generation process. | -| [docs/index.md](./docs/index.md) | Entry point to the `docs/` documentation set. | -| [CONTRIBUTING.md](./CONTRIBUTING.md) | Contribution process, review expectations, and required development practices. | -| [TESTING.md](./TESTING.md) | Validation strategy and testing procedures. | +| Document | Role | +| ---------------------------------------------------------- | ------------------------------------------------------------------------------------- | +| [README.md](README.md) | Primary user-facing overview of Spec Kit and its workflow. | +| [DEVELOPMENT.md](DEVELOPMENT.md) | This document. | +| [spec-driven.md](spec-driven.md) | End-to-end explanation of the Spec-Driven Development workflow supported by Spec Kit. | +| [RELEASE-PROCESS.md](.github/workflows/RELEASE-PROCESS.md) | Release workflow, versioning rules, and changelog generation process. | +| [docs/index.md](docs/index.md) | Entry point to the `docs/` documentation set. | +| [CONTRIBUTING.md](CONTRIBUTING.md) | Contribution process, review expectations, and required development practices. | +| [TESTING.md](TESTING.md) | Validation strategy and testing procedures. | **Main repository components:**