From e4d46ae5007c785f1ce114a7356cbaf03b74ea82 Mon Sep 17 00:00:00 2001 From: Jason Frisch Date: Sun, 6 Sep 2026 11:45:14 +0900 Subject: [PATCH] docs: reconcile maintenance and specification guidance Signed-off-by: Jason Frisch --- .bootstrap/config/AGENTS.md | 20 ++++---------------- CONTRIBUTING.md | 6 +++++- 2 files changed, 9 insertions(+), 17 deletions(-) diff --git a/.bootstrap/config/AGENTS.md b/.bootstrap/config/AGENTS.md index 1760569ec..9702b1ae6 100644 --- a/.bootstrap/config/AGENTS.md +++ b/.bootstrap/config/AGENTS.md @@ -59,25 +59,13 @@ ALWAYS open and follow `{cf-studio-path}/config/rules/anti-patterns.md` WHEN rev NEVER edit files inside `{cf-studio-path}/.core/` or `{cf-studio-path}/.gen/` directly — they are read-only copies. ALWAYS edit the canonical source files under project root (`skills/`, `kits/`, `schemas/`, etc.) and then run `cfs update --source . --force` to sync changes into `{cf-studio-path}/`. -### Specs-First Development Workflow +### Code and specification changes -ALWAYS update specs and documentation in `architecture/` FIRST BEFORE writing any code. +Follow [Making Changes](../../../CONTRIBUTING.md#making-changes) for maintenance of Constructor Studio itself. Edit canonical source files directly when implementing or repairing behavior already described by the specifications. Preserve the applicable traceability markers; do not require an unrelated specification edit merely to change code. -**Mandatory sequence for any code change**: +When the requested change alters requirements, architecture, or a specified contract, update the affected artifacts in `architecture/` before implementing the changed contract. Validate affected specifications and traceability with the checks described in CONTRIBUTING.md. -1. **Update specs** — modify or create relevant artifacts in `architecture/`: - - `architecture/PRD.md` — for new requirements or use cases - - `architecture/DESIGN.md` — for architectural changes or new components - - `architecture/DECOMPOSITION.md` — for new features or work breakdown - - `architecture/features/*.md` — for feature-level specs - - `architecture/specs/*.md` — for technical specs (CDSL, CLISPEC, etc.) - - `architecture/ADR/*.md` — for architecture decisions - -2. **Validate specs** — run `cfs validate` to ensure artifact integrity - -3. **Generate code via Constructor Studio** — use `/cf-generate` workflow to implement code from specs with traceability markers - -NEVER write code directly without first updating the corresponding specs. This ensures design-to-code traceability and prevents implementation drift from design intent. +Use `/cf-generate` when the selected workflow calls for generation from specifications. Its prerequisites belong to that workflow; it is not a prerequisite for every maintenance edit. --- diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4e8133b6f..0fd315fef 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -108,7 +108,7 @@ studio/ # Project root ### Critical Rule -> **Do not edit files under `.bootstrap/` directly when contributing.** +> **Do not edit generated mirrors under `.bootstrap/.core/` or `.bootstrap/.gen/` directly when contributing.** > In this self-hosted repo, `.bootstrap/` is a bootstrap copy of a Constructor Studio version used > to develop Constructor Studio itself — similar to bootstrapping a compiler. > This is a repo-specific self-hosted setup, not the general user-project layout described in the README. @@ -120,6 +120,8 @@ studio/ # Project root > whenever you need to refresh the local bootstrap for manual verification, but do not commit > `.bootstrap/.core/`, `.bootstrap/.gen/`, or generated host integration files. +The tracked `.bootstrap/config/AGENTS.md` and `.bootstrap/config/SKILL.md` are user-editable instructions for this repository. Edit them directly when changing local workflow guidance; they are not source-code mirrors. Generated kit outputs under `.bootstrap/config/kits/` still come from their canonical kit sources. + The `make update` command runs `cfs update --source . --force`, which: 1. Copies canonical sources into `.bootstrap/.core/` 2. Regenerates `.bootstrap/.gen/` aggregates @@ -385,6 +387,8 @@ list. ### Code Changes +For maintenance that preserves an existing specified contract, edit the canonical code directly and preserve its traceability markers. If requirements, architecture, or a specified contract change, update the affected specifications first. `/cf-generate` applies when the selected workflow calls for generation, rather than to every code edit. + 1. Edit canonical files under `skills/studio/scripts/studio/` (skill engine), `src/studio_proxy/` (CLI proxy), or other project-root source directories 2. Do not patch mirrored files under `.bootstrap/` directly 3. If you need a live manual check against the bootstrap copy, run `make update`, perform the test, and then revert `.bootstrap/` back to the previous state before opening the PR