chore: import upstream snapshot with attribution
This commit is contained in:
wehub-resource-sync
@@ -0,0 +1,92 @@
|
||||
# Evolving Specs in Existing Projects
|
||||
|
||||
Existing projects need two separate maintenance loops:
|
||||
|
||||
- **Spec Kit project-file updates** refresh managed commands, scripts,
|
||||
templates, and shared memory files.
|
||||
- **Feature artifact evolution** keeps repository-specific `specs/` artifacts
|
||||
aligned with the code and product behavior you intend to ship.
|
||||
|
||||
Use the [upgrade workflow](../upgrade.md) when you need newer Spec Kit project
|
||||
files. Use one of the artifact persistence models below when requirements or
|
||||
implementation insights change an existing project.
|
||||
|
||||
For the conceptual model definitions, see
|
||||
[Spec Persistence Models](../concepts/spec-persistence.md).
|
||||
|
||||
## Flow-Forward Spec
|
||||
|
||||
Use flow-forward when each feature directory should remain a historical record.
|
||||
|
||||
When you add another feature or make a substantial follow-up change, create a
|
||||
new feature spec through your installed `/speckit.specify` command and continue
|
||||
through the standard flow:
|
||||
|
||||
1. Run `/speckit.specify` to create a new feature directory under `specs/`.
|
||||
2. Run `/speckit.plan` to define the implementation approach.
|
||||
3. Run `/speckit.tasks` to derive the work breakdown.
|
||||
4. Run `/speckit.implement` and review the resulting code and artifact diffs.
|
||||
5. Run `/speckit.converge` to verify completeness and generate tasks for remaining gaps. If tasks are appended, repeat `/speckit.implement` and `/speckit.converge` until the feature is fully complete.
|
||||
|
||||
The previous feature directory remains intact for audit, comparison, or
|
||||
explaining how the project reached its current state. Use clear feature names or
|
||||
cross-links when a new directory supersedes or extends earlier work.
|
||||
|
||||
## Living Spec
|
||||
|
||||
Use living spec when `spec.md` is the contract and `plan.md` and `tasks.md` are
|
||||
derived from it.
|
||||
|
||||
When intended behavior changes, revise the existing `spec.md` first. Then
|
||||
regenerate or manually revise downstream artifacts so they match the updated
|
||||
spec:
|
||||
|
||||
1. Start from a clean working tree or a dedicated branch so every generated
|
||||
change is reviewable.
|
||||
2. Update `spec.md` with `/speckit.clarify` or an explicit edit.
|
||||
3. Rerun `/speckit.plan` or revise `plan.md` so the technical approach matches
|
||||
the revised spec.
|
||||
4. Rerun `/speckit.tasks` or revise `tasks.md` so implementation work matches
|
||||
the revised plan.
|
||||
5. Run `/speckit.analyze` before implementation resumes to catch gaps between
|
||||
the spec, plan, and tasks.
|
||||
6. Run `/speckit.implement`, then review the code and artifact diffs together.
|
||||
7. Run `/speckit.converge` to assess completion and append any remaining work to `tasks.md`. If tasks are appended, repeat `/speckit.implement` and `/speckit.converge` until the feature is fully complete.
|
||||
|
||||
Preserve important implementation rationale before replacing derived artifacts.
|
||||
If a plan or task list contains decisions that still matter, carry them forward
|
||||
explicitly.
|
||||
|
||||
## Flow-Back Spec
|
||||
|
||||
Use flow-back when implementation discoveries are allowed to reshape the
|
||||
artifact set.
|
||||
|
||||
In this model, the first useful edit can happen wherever the insight lands:
|
||||
`spec.md`, `plan.md`, `tasks.md`, or the implementation. After the change, bring
|
||||
the artifact set back into alignment:
|
||||
|
||||
1. Capture the discovery in the artifact closest to the work.
|
||||
2. Decide whether it changes intended behavior, implementation strategy, task
|
||||
breakdown, or only code.
|
||||
3. Update any other artifacts that now disagree with the accepted direction.
|
||||
4. Run `/speckit.analyze` to check for gaps across `spec.md`, `plan.md`, and
|
||||
`tasks.md`.
|
||||
5. Continue implementation only after the artifact set describes the behavior
|
||||
and approach you want future contributors to trust.
|
||||
|
||||
Flow-back is flexible, but it requires discipline. Do not leave a lower-level
|
||||
change in `tasks.md` or code if `spec.md` still says something different and the
|
||||
spec is meant to remain trustworthy.
|
||||
|
||||
## Before Updating Spec Kit Project Files
|
||||
|
||||
Before refreshing Spec Kit project files with the terminal command
|
||||
`specify init --here --force --integration <your-agent>`, protect any
|
||||
project-specific material that lives outside `specs/`, especially
|
||||
`.specify/memory/constitution.md` and customized files under
|
||||
`.specify/templates/` or `.specify/scripts/`. Use `<your-agent>` for the AI
|
||||
coding agent integration used by the target project.
|
||||
|
||||
Your `specs/` directory is not part of the template package, but shared project
|
||||
files can be overwritten by a forced refresh.
|
||||
@@ -0,0 +1,123 @@
|
||||
# Using Spec Kit in a Monorepo
|
||||
|
||||
A Spec Kit project is **directory-scoped**: the project is whichever directory
|
||||
contains `.specify/`. A monorepo can hold several independent Spec Kit projects
|
||||
under one repository root, each with its own `.specify/`, `specs/`, constitution,
|
||||
and feature numbering.
|
||||
|
||||
Root resolution already prefers the **nearest** `.specify/` over the Git
|
||||
toplevel, so commands run from inside a member project resolve to that project,
|
||||
not the repo root.
|
||||
|
||||
## Layout
|
||||
|
||||
```text
|
||||
my-monorepo/
|
||||
├── .git/ # one Git repository at the root
|
||||
├── apps/
|
||||
│ ├── web/
|
||||
│ │ └── .specify/ # Spec Kit project "web"
|
||||
│ │ └── memory/constitution.md
|
||||
│ └── api/
|
||||
│ └── .specify/ # Spec Kit project "api"
|
||||
│ └── memory/constitution.md
|
||||
└── packages/
|
||||
└── ui/
|
||||
└── .specify/ # Spec Kit project "ui"
|
||||
```
|
||||
|
||||
Initialize each member project independently:
|
||||
|
||||
```bash
|
||||
specify init apps/web --integration claude
|
||||
specify init apps/api --integration claude
|
||||
```
|
||||
|
||||
Each project keeps its own `specs/` directory and numbers features
|
||||
independently (`apps/web/specs/001-…`, `apps/api/specs/001-…`).
|
||||
|
||||
## Working inside a member project
|
||||
|
||||
The default workflow is unchanged: change into the project directory and run the
|
||||
slash commands. Root resolution finds the nearest `.specify/`.
|
||||
|
||||
```bash
|
||||
cd apps/web
|
||||
# then run /speckit.specify, /speckit.plan, … in your agent
|
||||
```
|
||||
|
||||
## Targeting a member project from the repo root
|
||||
|
||||
For non-interactive or CI runs where you do not want to `cd`, set
|
||||
**`SPECIFY_INIT_DIR`** to the member project root (the directory *containing*
|
||||
`.specify/`). Relative paths resolve against the current directory.
|
||||
|
||||
```bash
|
||||
# operate on apps/web from the monorepo root (no cd required)
|
||||
export SPECIFY_INIT_DIR=apps/web
|
||||
```
|
||||
|
||||
The path must exist and contain `.specify/`. If it does not, the command
|
||||
**errors and does not fall back** to the current directory or the Git toplevel.
|
||||
This is deliberate: a typo never writes specs into the wrong project. A
|
||||
nonexistent path is reported as you typed it; a path that exists but is not a
|
||||
Spec Kit project is reported as its resolved absolute path:
|
||||
|
||||
```text
|
||||
# SPECIFY_INIT_DIR=apps/wbe (typo: no such directory)
|
||||
ERROR: SPECIFY_INIT_DIR does not point to an existing directory: apps/wbe
|
||||
|
||||
# SPECIFY_INIT_DIR=apps (exists, but has no .specify/ of its own)
|
||||
ERROR: SPECIFY_INIT_DIR is not a Spec Kit project (no .specify/ directory): /home/you/my-monorepo/apps
|
||||
```
|
||||
|
||||
`SPECIFY_INIT_DIR` selects the **project**; `SPECIFY_FEATURE_DIRECTORY` selects
|
||||
the **feature** within it. They compose: set both to pick a project and a
|
||||
feature non-interactively. See the
|
||||
[`SPECIFY_INIT_DIR` reference](../reference/core.md#environment-variables) for
|
||||
the full contract and the two-axes model.
|
||||
|
||||
The `specify` CLI's project-scoped subcommands honor the same variable, so they
|
||||
target a member project from the root without `cd` too:
|
||||
|
||||
```bash
|
||||
export SPECIFY_INIT_DIR=apps/web
|
||||
specify workflow list # lists apps/web's workflows
|
||||
specify integration status # reports apps/web's integration
|
||||
```
|
||||
|
||||
The validation rules are the same: the path must exist and contain `.specify/`,
|
||||
with no fallback to the current directory.
|
||||
|
||||
## How `SPECIFY_INIT_DIR` reaches your agent
|
||||
|
||||
`SPECIFY_INIT_DIR` is read by the shell scripts that the slash commands invoke
|
||||
(`get_repo_root` in Bash, `Get-RepoRoot` in PowerShell). It takes effect only
|
||||
when it is present in the environment of the shell that runs those scripts.
|
||||
|
||||
- **Scripted / CI runs:** export it in the same shell that drives the commands;
|
||||
it is reliable there.
|
||||
- **Interactive agents:** whether an exported variable reaches the shell tool an
|
||||
agent uses is agent-specific. Export `SPECIFY_INIT_DIR` *before* launching the
|
||||
agent, and verify once (e.g. run `/speckit.specify` and confirm the new feature
|
||||
landed under the intended project's `specs/`).
|
||||
|
||||
## Git in a monorepo
|
||||
|
||||
> [!NOTE]
|
||||
> Spec Kit project files are scoped to the **resolved project root**, but Git
|
||||
> operations still run in the containing Git work tree. In a monorepo with a
|
||||
> single Git repository at the root and projects in subdirectories, feature
|
||||
> branch creation creates or switches branches in the shared root repository.
|
||||
> Spec directories still live under the selected member project, while the Git
|
||||
> branch namespace is shared by the whole monorepo. Manage branches and commits
|
||||
> at the repository root, or initialize Git per member project if you want
|
||||
> isolated per-project branch namespaces.
|
||||
|
||||
## Constitutions
|
||||
|
||||
Each member project has its own `.specify/memory/constitution.md` and
|
||||
`/speckit.constitution` edits the local project's file. Spec Kit does not provide
|
||||
a built-in base/inheritance mechanism; if you want one constitution to reference
|
||||
shared rules elsewhere in the monorepo, you need to maintain that wiring yourself.
|
||||
Otherwise, duplicate or sync shared engineering rules per project.
|
||||
Reference in New Issue
Block a user