Enhance the commands and protocols

.agents/skills/devspec-codebase-structure.md

@@ -1,5 +1,5 @@
 ---
 name: devspec-codebase-structure
-description: Capture owned source roots, module boundaries, integrations, and repository access.
+description: Capture or customize owned source roots, repository layouts, module boundaries, integrations, and repository access.
 ---
 Read and execute `devspec/contracts/devspec.codebase-structure.md`.

.agents/skills/devspec-coding-standards.md

@@ -1,5 +1,5 @@
 ---
 name: devspec-coding-standards
-description: Capture reusable observed or developer-defined coding standards with numbered examples.
+description: Capture concise, reusable coding conventions, followable examples, and anti-patterns from source evidence or developer-defined standards.
 ---
 Read and execute `devspec/contracts/devspec.coding-standards.md`.

.agents/skills/devspec-extract.md

@@ -1,5 +1,5 @@
 ---
 name: devspec-extract
-description: Backfill concise foundation evidence from an existing repository.
+description: Inspect the approved existing system end-to-end, produce its technical, business, workflow, and rule baseline, and prepare an evidence-backed diagram candidate list for explicit generation approval.
 ---
 Read and execute `devspec/contracts/devspec.extract.md`.

.agents/skills/devspec-grooming.md

@@ -1,5 +1,5 @@
 ---
 name: devspec-grooming
-description: Make one draft story buildable through scoped review and targeted questions.
+description: Make one draft story buildable through scoped review and material questions.
 ---
 Read and execute `devspec/contracts/devspec.grooming.md`.

.claude/skills/devspec-codebase-structure/SKILL.md

@@ -1,5 +1,5 @@
 ---
 name: devspec-codebase-structure
-description: Capture owned source roots, module boundaries, integrations, and repository access.
+description: Capture or customize owned source roots, repository layouts, module boundaries, integrations, and repository access.
 ---
 Read and execute `devspec/contracts/devspec.codebase-structure.md`.

.claude/skills/devspec-coding-standards/SKILL.md

@@ -1,5 +1,5 @@
 ---
 name: devspec-coding-standards
-description: Capture short, evidence-backed conventions and anti-patterns.
+description: Capture concise, reusable coding conventions, followable examples, and anti-patterns from source evidence or developer-defined standards.
 ---
 Read and execute `devspec/contracts/devspec.coding-standards.md`.

.claude/skills/devspec-extract/SKILL.md

@@ -1,5 +1,5 @@
 ---
 name: devspec-extract
-description: Inspect the approved existing system end-to-end and produce its technical, business, workflow, rule, and diagram baseline without requiring separate foundation or diagram commands.
+description: Inspect the approved existing system end-to-end, produce its technical, business, workflow, and rule baseline, and prepare an evidence-backed diagram candidate list for explicit generation approval.
 ---
 Read and execute `devspec/contracts/devspec.extract.md`.

.cursor/rules/devspec-workflow.mdc

@@ -2,4 +2,4 @@
 description: Devspec Lite workflow
 alwaysApply: false
 ---
-For `devspec.changerequest`, `devspec.clarify`, `devspec.codebase-structure`, `devspec.coding-standards`, `devspec.diagram`, `devspec.extract`, `devspec.finalize`, `devspec.grooming`, `devspec.implement`, `devspec.projectcontext`, `devspec.quickfix`, `devspec.review`, `devspec.rules`, `devspec.story`, `devspec.tasks`, `devspec.techstack`, read the matching `devspec/contracts/` file and listed protocols. For a clear continuation, resolve per-worktree current context and run only the saved next action; ask before switching stories.
+For `devspec.extract`, `devspec.projectcontext`, `devspec.techstack`, `devspec.codebase-structure`, `devspec.coding-standards`, `devspec.rules`, `devspec.story`, `devspec.grooming`, `devspec.clarify`, `devspec.changerequest`, `devspec.finalize`, `devspec.tasks`, `devspec.implement`, `devspec.review`, `devspec.diagram`, `devspec.quickfix`, read the matching `devspec/contracts/` file and listed protocols. For a clear continuation, resolve per-worktree current context and run only the saved next action; ask before switching stories.

.gemini/commands/devspec/codebase-structure.toml

@@ -1,2 +1,2 @@
-description = "Capture owned source roots, module boundaries, integrations, and repository access."
+description = "Capture or customize owned source roots, repository layouts, module boundaries, integrations, and repository access."
 prompt = "Read and execute devspec/contracts/devspec.codebase-structure.md"

.gemini/commands/devspec/coding-standards.toml

@@ -1,2 +1,2 @@
-description = "Capture short, evidence-backed conventions and anti-patterns."
+description = "Capture concise, reusable coding conventions, followable examples, and anti-patterns from source evidence or developer-defined standards."
 prompt = "Read and execute devspec/contracts/devspec.coding-standards.md"

.gemini/commands/devspec/extract.toml

@@ -1,2 +1,2 @@
-description = "Inspect the approved existing system end-to-end and produce its technical, business, workflow, rule, and diagram baseline without requiring separate foundation or diagram commands."
+description = "Inspect the approved existing system end-to-end, produce its technical, business, workflow, and rule baseline, and prepare an evidence-backed diagram candidate list for explicit generation approval."
 prompt = "Read and execute devspec/contracts/devspec.extract.md"

.github/agents/devspec.codebase-structure.agent.md

@@ -1,6 +1,6 @@
 ---
 name: devspec.codebase-structure
-description: Capture owned source roots, module boundaries, integrations, and repository access.
+description: Capture or customize owned source roots, repository layouts, module boundaries, integrations, and repository access.
 user-invocable: true
 ---
 Execute `devspec/contracts/devspec.codebase-structure.md`.

.github/agents/devspec.coding-standards.agent.md

@@ -1,6 +1,6 @@
 ---
 name: devspec.coding-standards
-description: Capture short, evidence-backed conventions and anti-patterns.
+description: Capture concise, reusable coding conventions, followable examples, and anti-patterns from source evidence or developer-defined standards.
 user-invocable: true
 ---
 Execute `devspec/contracts/devspec.coding-standards.md`.

.github/agents/devspec.extract.agent.md

@@ -1,6 +1,6 @@
 ---
 name: devspec.extract
-description: Backfill concise foundation evidence from an existing repository.
+description: Inspect the approved existing system end-to-end, produce its technical, business, workflow, and rule baseline, and prepare an evidence-backed diagram candidate list for explicit generation approval.
 user-invocable: true
 ---
 Execute `devspec/contracts/devspec.extract.md`.

README.md

@@ -12,10 +12,12 @@ Devspec Lite is a compact, resumable spec-driven workflow for AI coding agents.
 | macOS/Linux package-manager installation | [Homebrew](docs/setup-homebrew.md) |
 | Already installed the CLI; need init, upgrade, or profile changes | [CLI lifecycle](docs/setup-lifecycle.md) |
 
-Manual copying and CLI installation produce the same canonical `devspec/` content and agent wrappers. In either route, set the target repository's `repository-state.md` to `new` or `existing`. Choose one setup route; the CLI is optional.
+Manual copying and CLI installation produce the same canonical `devspec/` content and agent wrappers, once the manual route resets the project records listed in its guide. In either route, set the target repository's `repository-state.md` to `new` or `existing`. Choose one setup route; the CLI is optional.
 
 ## CLI quick start
 
+The [CLI quick start](docs/quickstart.md) walks through initializing, validating, and choosing the first command.
+
 After choosing a CLI route, initialize and validate the repository:
 
 ```powershell
@@ -28,7 +30,7 @@ uvx devspec-lite init --target . --profile all --repo-state new
 uvx devspec-lite doctor --target . --profile all
 ```
 
-`init` copies canonical Markdown + XML contracts, concise templates, and the wrappers for the selected agent profile. Use the `devspec.*` commands exposed by your agent host. Use `devspec-lite diff --target .` to inspect installed-framework drift and `devspec-lite sync --target . --profile all --dry-run` before applying a framework upgrade.
+`init` copies canonical Markdown + XML contracts, concise templates, and the wrappers for the selected agent profile. It generates `devspec/foundation/repository-state.md` from `--repo-state` and seeds empty `devspec/architecture/overview.md` and `artifact-queue.md` from their templates. Those two, plus `devspec/constitution.md`, are project-owned: `init` and `sync` never overwrite them, even with `--force`. Use the `devspec.*` commands exposed by your agent host. Use `devspec-lite diff --target .` to inspect installed-framework drift and `devspec-lite sync --target . --profile all --dry-run` before applying a framework upgrade.
 
 ## Choose a workflow route
 

devspec/README.md

@@ -1,10 +1,12 @@
 # Devspec Lite
 
-New repository foundation: `projectcontext → techstack → codebase-structure → coding-standards → rules`. Existing repository baseline: `extract` completes the foundation, prepares the applicable diagram list, and asks whether to generate all or selected diagrams. Rare durable cross-work-item principles live in `constitution.md`; `projectcontext` promotes or retires them only on explicit input.
+New repository foundation: `projectcontext → techstack → codebase-structure → coding-standards → rules`. Existing repository baseline: `extract` completes the foundation, prepares the applicable diagram list, and asks whether to generate all or selected diagrams. Rare durable cross-work-item principles live in `constitution.md` with stable `CP-###` IDs. `extract` records candidates from evidence; `projectcontext` promotes or retires them only on explicit input.
 
 Work item: `story → grooming` when needed `→ finalize → tasks → implement → review`. Story intake accepts one manual request or, when an authenticated MCP connector is available, one read-only provider work-item reference.
 After `story` selects a work item, use the normal work-item commands without repeating its ID. Per-worktree private context resolves the selected story and its recorded `next` action; use an ID only to switch or disambiguate stories.
 
 Use `clarify` only for an active blocker and `quickfix` only for localized, low-risk changes. See `lifecycle.md` for all command transitions.
 
+Each contract in `contracts/` states its own intent, scope, rules, and transitions, and loads the shared behavior it needs from `protocols/`: `state` for the run-state and evidence vocabulary, `run` for preflight and checkpoints, `work` for scope and change discipline, `ask` for material questions, `current-work-item` for ID-free continuation, `revision` for scope revisions, `repo-access` for repository boundaries, and `security` for the OWASP baseline. A rule belongs in a protocol when more than one command needs it.
+
 `diagram` creates static SVG by default. Use `motion=explain` only for an evidence-backed sequence, flow, or state transition; animated output must retain complete static and reduced-motion meaning.