bigsmartben · bigsmartben · Jul 26, 2026 · Jul 26, 2026 · Jul 26, 2026 · Jul 26, 2026
diff --git a/.github/workflows/community-smoke.yml b/.github/workflows/community-smoke.yml
@@ -149,7 +149,7 @@ jobs:
               arch)
                 test -f .claude/skills/speckit-arch-generate/SKILL.md
                 test -f .claude/skills/speckit-arch-reverse/SKILL.md
-                grep -q "architecture planning contract" .claude/skills/speckit-arch-generate/SKILL.md
+                grep -q "ARCH_COMMAND_RETIRED" .claude/skills/speckit-arch-generate/SKILL.md
                 ;;
               preview)
                 test -f .claude/skills/speckit-preview-wireflow/SKILL.md

diff --git a/extensions/arch/.extensionignore b/extensions/arch/.extensionignore
diff --git a/extensions/arch/.gitattributes b/extensions/arch/.gitattributes
diff --git a/extensions/arch/.gitignore b/extensions/arch/.gitignore
diff --git a/extensions/arch/AGENTS.md b/extensions/arch/AGENTS.md
diff --git a/extensions/arch/CATALOG-SUBMISSION.md b/extensions/arch/CATALOG-SUBMISSION.md
diff --git a/extensions/arch/CHANGELOG.md b/extensions/arch/CHANGELOG.md
@@ -1,11 +1,22 @@
 # Changelog
 
-## Unreleased
-
-- Strengthen the planning contract quality gate with required `Source / Basis` support on rule-bearing sections.
-- Add open-question planning status validation with `BLOCKS_PLAN` and `CAN_PROCEED_WITH_GUARDRAIL`.
-- Block implementation-level conclusions such as source file edits, API schemas, database schemas, task lists, runbooks, and deployment manifests from passing planning readiness.
-- Tighten the JSON working-model schema with per-section record contracts.
+## v3.0.1 - 2026-07-26
+
+- Replace platform-specific slash command references in compatibility prompts
+  with Spec Kit command placeholders so every agent integration resolves the
+  Constitution handoff correctly.
+
+## v3.0.0 - 2026-07-26
+
+- Retire standalone Architecture generation and move the project Architecture
+  lifecycle into `workflow-preset` `/speckit.constitution`.
+- Keep `/speckit.arch.generate` and `/speckit.arch.reverse` only as write-free
+  compatibility entrypoints that return `ARCH_COMMAND_RETIRED`.
+- Remove 4+1 reasoning, the nine-section planning contract, setup scripts,
+  working-model Schema, Bash/PowerShell Markdown Validators, and artifact
+  templates from the extension package.
+- Document explicit brownfield input authorization and v2
+  `ARCH_LEGACY_FORMAT` migration through the Constitution stage.
 
 ## v2.0.0 - 2026-07-06
 

diff --git a/extensions/arch/README.md b/extensions/arch/README.md
@@ -1,157 +1,111 @@
-# Spec Kit Architecture Planning Contract Extension
+# Spec Kit Architecture Command Migration Extension
 
-Guide downstream Spec Kit plans with explicit architecture constraints.
+This v3 extension retires standalone Architecture generation.
 
-Spec Kit turns feature specs into plans, tasks, and implementation work. Those plans need stable architecture context: which boundaries cannot be crossed, which capabilities own which responsibilities, which decisions have already been made, and which architecture gaps must block or shape planning.
+Project Architecture now belongs to the standard Constitution stage, provided by
+`workflow-preset`. The Constitution command maintains two separate long-lived
+artifacts:
 
-This extension records that context in `.specify/memory/architecture.md` as a planning contract. The contract is intentionally plan-facing: it tells `/plan` what it must preserve, what it must not invent, where extension is allowed, and when architecture review is required.
-
-Each rule-bearing row carries `Source / Basis` so the single artifact remains traceable without a secondary evidence file.
-
-## When You Need This
-
-Use this extension when you want downstream planning to respect project-level architecture:
-
-- You are starting or reshaping a Spec Kit project and want plan guardrails before detailed planning.
-- You have an existing repository and need planning constraints derived from observable repository evidence.
-- You want stable boundaries, constraints, prohibited directions, and open architecture questions captured in one place.
-- You need architecture guidance without producing implementation plans, task lists, API schemas, database schemas, deployment manifests, or runbooks.
-
-## Install
-
-The extension is listed in the Spec Kit community catalog for discovery:
-
-```bash
-specify extension search arch
-specify extension info arch
-```
-
-Install the published release directly from GitHub:
-
-```bash
-specify extension add arch --from https://github.com/bigsmartben/spec-kit-arch/archive/refs/tags/v2.0.0.zip
+```text
+.specify/memory/constitution.md
+.specify/memory/architecture.md
 ```
 
-Install from a local development checkout:
+`constitution.md` contains durable governance. `architecture.md` contains the
+project boundary, conceptual model, technical direction and evidence, planning
+constraints, and unresolved gaps.
 
-```bash
-specify extension add --dev /home/administrator/github/spec-kit-arch
-```
+## Why This Extension Still Exists
 
-After installation, the extension is copied under:
+Existing projects may still have these command names installed:
 
 ```text
-.specify/extensions/arch/
+/speckit.arch.generate
+/speckit.arch.reverse
 ```
 
-## Commands
+In v3 they are compatibility entrypoints only. They perform no discovery,
+generation, setup, validation, or writes. Each command returns
+`ARCH_COMMAND_RETIRED` and directs the user to `/speckit.constitution`.
 
-The extension id is `arch`, and each command uses `.arch` as the command namespace. The extension provides two default commands:
+For example, replace:
 
 ```text
-/speckit.arch.generate
 /speckit.arch.reverse
 ```
 
-| Command | Use when | Evidence source | Writes |
-| --- | --- | --- | --- |
-| `/speckit.arch.generate` | You know the intended product direction and want architecture planning guardrails | User input, current architecture memory, optional `.specify/memory/uc.md` | `.specify/memory/architecture.md` |
-| `/speckit.arch.reverse` | You are onboarding or documenting an existing repository | Observable repository evidence inspected during the command | `.specify/memory/architecture.md` |
-
-## Planning Contract
-
-The primary artifact is:
+with:
 
 ```text
-.specify/memory/architecture.md
+/speckit.constitution Brownfield amendment. Use README.md and services/api/
+configuration as authorized evidence, exclude Git history, and update Architecture.
 ```
 
-It uses this structure:
-
-- Architecture Intent
-- Planning Scope Rules
-- Capability Boundaries
-- Required Constraints
-- Architecture Decisions Already Made
-- Allowed Extension Points
-- Prohibited Plan Directions
-- Open Architecture Questions
-- Plan Review Checklist
+## Target Architecture Workflow
 
-Rule-bearing sections include `Source / Basis`. Open architecture questions also include a planning status: `BLOCKS_PLAN` or `CAN_PROCEED_WITH_GUARDRAIL`.
-
-The contract is usable when the planning readiness validator reports:
+Install or enable
+[workflow-preset](https://github.com/bigsmartben/spec-kit-workflow-preset),
+then run:
 
 ```text
-planning_gate: USABLE
-ready_gate: PASS
+/speckit.constitution
 ```
 
-If readiness is blocked, the validator emits stable blocker codes such as:
+The Constitution stage first confirms:
 
-- `ARCH_PLACEHOLDER_PRESENT`
-- `ARCH_PLANNING_SCOPE_RULES_MISSING`
-- `ARCH_CAPABILITY_BOUNDARIES_MISSING`
-- `ARCH_CONSTRAINTS_OR_DECISIONS_MISSING`
-- `ARCH_PLAN_REVIEW_CHECKLIST_MISSING`
-- `ARCH_SOURCE_MISSING`
-- `ARCH_UNSUPPORTED_CONCLUSION`
-- `ARCH_OPEN_QUESTION_STATUS_INVALID`
+- greenfield, brownfield, or amendment mode;
+- the goal of the run;
+- user-selected sources and the role of each source;
+- excluded sources;
+- whether repository inspection is allowed and its scope;
+- whether Constitution, Architecture, or both may be updated.
 
-Blocked contracts can still expose useful questions, but downstream plans must not treat missing architecture decisions as permission to invent them.
+No UC path or discovered file is automatically authoritative.
 
-## Internal Reasoning Model
+The resulting single-file Architecture uses:
 
-The commands use 4+1 as an internal reasoning lens, not as the default artifact shape:
+```text
+System Boundary
+  -> Conceptual Model
+  -> Technical Decisions & Evidence
+  -> Planning Guardrails & Gaps
+```
 
-- Scenario lens: goals, actors, main paths, alternate paths, and failure paths.
-- Logical lens: capability boundaries, domain concepts, ownership, state responsibility, and invariants.
-- Process lens: runtime collaboration, handoffs, approval points, receipts, and failure closure.
-- Development lens: module boundaries, dependency direction, package ownership, and code-organization constraints.
-- Physical lens: deployment assumptions, external systems, runtime environment, fact sources, and operational constraints.
+There is no 4+1 reasoning, secondary Architecture model, PoC generation,
+working-model Schema, or Markdown readiness Validator in this extension.
 
-These lenses help prevent omissions, but downstream planning consumes the single planning contract.
+## Upgrade Notes
 
-## Files Written
+Existing v2 `.specify/memory/architecture.md` files are not rewritten by the
+compatibility commands. Run `/speckit.constitution`, authorize an Architecture
+amendment, and include the existing file as a selected source. The Constitution
+stage reports `ARCH_LEGACY_FORMAT` before migrating the old nine-section or 4+1
+shape.
 
-Both default commands write only:
+Remove this extension after all integrations and team documentation use
+`/speckit.constitution`; the two compatibility commands are then unnecessary.
 
-```text
-.specify/memory/architecture.md
-```
+## Install
 
-The commands do not edit:
+Published v3 release:
 
-```text
-.specify/memory/uc.md
-.specify/memory/constitution.md
-feature specs
-plans
-tasks
-source code
-tests
-root docs/
-deployment manifests
-package files
-infrastructure files
-runbooks
-other `.specify/memory/architecture*.md` files
+```bash
+specify extension add arch --from https://github.com/bigsmartben/spec-kit-arch/releases/download/v3.0.1/arch-v3.0.1.zip
 ```
 
-## Development
-
-Validate the extension from a fresh project:
+Local development checkout:
 
 ```bash
-specify init /tmp/spec-kit-arch-test --ai codex --ignore-agent-tools --script sh
-cd /tmp/spec-kit-arch-test
-specify extension add --dev /home/administrator/github/spec-kit-arch
-.specify/extensions/arch/scripts/bash/setup-arch.sh --json
-.specify/extensions/arch/scripts/bash/validate-arch-artifacts.sh --json
+specify extension add --dev /path/to/spec-kit-arch
 ```
 
-Run the repository contract test after command, template, schema, setup-script, validator, or documentation changes:
+## Development
+
+Run the source contract:
 
 ```bash
 bash tests/repository-first-contract.sh
 ```
+
+The test verifies that both legacy command names remain safe, write-free
+migration entrypoints and that the removed generation stack is not packaged.