devspec 0.1.0__py3-none-any.whl

devspec_installer/payload/.github/skills/exploration-recovery/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: exploration-recovery
+description: Reuse known working exploration methods, apply discovery exclusions, and avoid repeating failed discovery or repair paths. Use for discovery-heavy, repeated, or failure-prone work such as repository extraction, provider lookup, dependency or code-pattern mapping, validation discovery, implementation repair, and review investigation.
+---
+
+# Exploration Recovery
+
+Use this skill to keep repository and provider discovery focused, cheap, and recoverable. Treat `.github/prompts/PATTERNS.md` as the policy source; this skill is the runtime checklist.
+
+## Checklist
+
+1. Define the current scope and goal before probing.
+   - Scope examples: repo path, provider, work item, module, technology, or source URL.
+   - Goal examples: repository extraction, provider resolution, dependency mapping, code-pattern search, validation discovery, implementation repair, or review investigation.
+
+2. Apply discovery exclusions before broad search, Explore runs, generated scripts, or helper commands.
+   - Read `devspec/foundation/discovery-exclusions.md` when present.
+   - If it is missing, use `devspec/foundation/_template/discovery-exclusions.md` as the section contract before creating or updating the live artifact.
+   - Apply baseline exclusions and ecosystem discovery rules unless the user asks or a project override includes a normally excluded path.
+   - Prefer manifests, lockfiles, framework config, scripts, docs, tests, and owned source roots as evidence.
+
+3. Check reusable exploration state before new probing.
+   - Read `devspec/foundation/exploration-state.md` when present.
+   - If it is missing, continue without it unless this run produces a reusable method outcome worth preserving.
+   - Use `devspec/foundation/_template/exploration-state.md` as the section contract before creating the live artifact.
+   - Check session memory only as transient context; Git-tracked devspec artifacts remain canonical.
+   - Use `Method Ledger` rows matched by both scope and goal, and ignore stale entries from different contexts.
+
+4. Prefer known working and low-cost methods.
+   - Use rows with `working` outcome first when the scope, goal, and environment assumptions still match.
+   - Skip rows with `failed` outcome unless the retry condition is met or the user gives new direction.
+   - Ignore rows with `superseded` outcome when a newer matching method exists.
+   - Prefer targeted search, targeted reads, manifests, devspec artifacts, and configured provider tools before generated scripts or broad scans.
+   - Limit each scope and goal to one new generated script, helper command, provider lookup path, or expensive search strategy before falling back to direct search and file reads.
+
+5. Record only reusable results.
+   - Update `devspec/foundation/exploration-state.md` only for reusable discoveries, skipped failures that changed the path, or successful fallback paths after a failure.
+   - Record scope, goal, method, outcome, evidence or failure reason, retry or reuse condition, last verified date, and brief notes.
+   - Do not record every search, one-off read, or expected empty result.
+
+## Reporting
+
+- Mention skipped known failures only when they materially changed the path taken.
+- Mention excluded paths only when they prevented a likely expensive scan, changed the evidence gathered, or the user asked for diagnostics.
+- Keep final output aligned with the active agent's Output Format and the shared Output Closure Pattern.

devspec_installer/payload/.github/workflows/python-package-ci.yml

@@ -0,0 +1,42 @@
+name: Python Package CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  test:
+    name: Python package test (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Run tests
+        run: uv run pytest
+
+      - name: Build Python wheel and sdist
+        run: uv build
+
+      - name: Smoke test Python package
+        shell: bash
+        run: |
+          wheel="$(ls dist/*.whl | head -n 1)"
+          temp_dir="$(mktemp -d)"
+          uvx --from "$wheel" devspec version
+          uvx --from "$wheel" devspec init --target "$temp_dir" --profile core --repo-state existing
+          uvx --from "$wheel" devspec doctor --target "$temp_dir" --profile core

devspec_installer/payload/.github/workflows/python-package-publish.yml

@@ -0,0 +1,69 @@
+name: Python Package Publish
+
+on:
+  workflow_dispatch:
+    inputs:
+      publish:
+        description: "Publish Python package to PyPI"
+        required: true
+        default: "false"
+        type: choice
+        options:
+          - "false"
+          - "true"
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  python-package:
+    name: Build and publish Python package
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Test
+        run: uv run pytest
+
+      - name: Build Python wheel and sdist
+        run: uv build
+
+      - name: Build devspec framework payload zip
+        run: |
+          zip -r "dist/devspec-framework-payload-${GITHUB_REF_NAME:-local}.zip" \
+            AGENTS.md GEMINI.md README.md devspec .github .claude .cursor .gemini .agents packaging/devspec-profiles.json
+          find dist -maxdepth 1 -type f ! -name devspec-python-package-checksums.txt -print0 \
+            | sort -z \
+            | xargs -0 sha256sum > dist/devspec-python-package-checksums.txt
+
+      - name: Upload Python package release artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: devspec-python-package-dist
+          path: dist/*
+
+      - name: Publish Python package to TestPyPI
+        if: github.event_name == 'workflow_dispatch' && github.event.inputs.publish == 'false'
+        run: uv publish --publish-url https://test.pypi.org/legacy/ dist/*.tar.gz dist/*.whl
+
+      - name: Publish Python package to PyPI
+        if: startsWith(github.ref, 'refs/tags/v') || (github.event_name == 'workflow_dispatch' && github.event.inputs.publish == 'true')
+        run: uv publish dist/*.tar.gz dist/*.whl
+
+      - name: Attach Python package release artifacts
+        if: startsWith(github.ref, 'refs/tags/v')
+        uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*

devspec_installer/payload/.github/workflows/winget-package-publish.yml

@@ -0,0 +1,110 @@
+name: WinGet Package Publish
+
+on:
+  workflow_dispatch:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write
+
+jobs:
+  winget-package:
+    name: Build WinGet portable package
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Run tests
+        run: uv run pytest
+
+      - name: Build Python wheel
+        run: uv build
+
+      - name: Build devspec.exe
+        shell: pwsh
+        run: |
+          $ErrorActionPreference = "Stop"
+          $wheel = Get-ChildItem dist -Filter "*.whl" | Select-Object -First 1
+          if (-not $wheel) {
+            throw "No wheel found in dist."
+          }
+
+          uv venv .venv-winget --python 3.12 --clear
+          uv pip install --python .\.venv-winget\Scripts\python.exe "pyinstaller>=6.0" $wheel.FullName
+
+          New-Item -ItemType Directory -Force -Path build\winget | Out-Null
+          @(
+            "from devspec_installer.cli import main"
+            ""
+            "raise SystemExit(main())"
+          ) | Set-Content -Path build\winget\devspec-entry.py -Encoding UTF8
+
+          .\.venv-winget\Scripts\pyinstaller.exe `
+            --noconfirm `
+            --clean `
+            --onefile `
+            --name devspec `
+            --distpath dist\winget `
+            --workpath build\pyinstaller `
+            --specpath build\pyinstaller `
+            --collect-data devspec_installer `
+            build\winget\devspec-entry.py
+
+      - name: Smoke test devspec.exe
+        shell: pwsh
+        run: |
+          $ErrorActionPreference = "Stop"
+          $target = Join-Path $env:RUNNER_TEMP "devspec-winget-smoke"
+          New-Item -ItemType Directory -Force -Path $target | Out-Null
+
+          .\dist\winget\devspec.exe version
+          .\dist\winget\devspec.exe init --target $target --profile core --repo-state existing
+          .\dist\winget\devspec.exe doctor --target $target --profile core
+
+      - name: Generate WinGet manifests
+        shell: pwsh
+        run: |
+          $ErrorActionPreference = "Stop"
+          $hash = (Get-FileHash dist\winget\devspec.exe -Algorithm SHA256).Hash.ToLowerInvariant()
+          "$hash  devspec.exe" | Set-Content -Path dist\winget\devspec.exe.sha256 -Encoding ASCII
+
+          $sourceRoot = "packaging\winget\manifests\s\SpecLabs\Devspec\0.1.0"
+          $manifestRoot = "dist\winget\manifests\s\SpecLabs\Devspec\0.1.0"
+          New-Item -ItemType Directory -Force -Path $manifestRoot | Out-Null
+          Copy-Item -Path "$sourceRoot\*.yaml" -Destination $manifestRoot
+
+          $installerManifest = Join-Path $manifestRoot "SpecLabs.Devspec.installer.yaml"
+          $manifest = Get-Content $installerManifest -Raw
+          $manifest = $manifest.Replace("REPLACE_WITH_RELEASE_SHA256", $hash)
+          $manifest | Set-Content -Path $installerManifest -Encoding UTF8
+
+          Write-Host "devspec.exe SHA256: $hash"
+          Write-Host "WinGet manifests: $manifestRoot"
+
+      - name: Upload WinGet package artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: devspec-winget-package
+          path: |
+            dist/winget/devspec.exe
+            dist/winget/devspec.exe.sha256
+            dist/winget/manifests/**/*.yaml
+
+      - name: Attach WinGet package artifacts
+        if: startsWith(github.ref, 'refs/tags/v')
+        uses: softprops/action-gh-release@v2
+        with:
+          files: |
+            dist/winget/devspec.exe
+            dist/winget/devspec.exe.sha256
+            dist/winget/manifests/**/*.yaml

devspec_installer/payload/AGENTS.md

@@ -0,0 +1,80 @@
+# Devspec Agent Instructions
+
+Use these instructions for OpenAI Codex, Cursor, Gemini CLI, Google Antigravity, and other agents that read `AGENTS.md`.
+
+## Canonical Workflow
+
+`devspec` is a spec-driven development framework. The Git-tracked `devspec/` artifacts are the durable source of truth; chat history and tool memory are transient.
+
+Before running or continuing any `devspec` workflow:
+
+1. Read `devspec/adapters/command-registry.md` for the requested command.
+2. Read the canonical Copilot prompt and agent files named in that registry row.
+3. Follow `.github/prompts/PATTERNS.md` for shared workflow, recovery, output, discovery, and recommendation behavior.
+4. Recover from existing `devspec/` artifacts before relying on memory.
+5. Preserve required inputs, output artifacts, status values, gates, handoff order, and recovery behavior.
+
+## Structured Questions
+
+Follow `.github/prompts/PATTERNS.md#interactive-question-pattern` for user questions. Use clickable multiple-choice options when the host supports them; otherwise render the same option labels as text and ask the user to reply with one label or `Custom Answer`. Preserve question intent, option labels, the recommended option, and the continuation condition in the relevant `Resume State` or `Workflow State` before waiting for input.
+
+## No Intent Drift
+
+Do not change the original intent of `.github/prompts/*.prompt.md` or `.github/agents/*.agent.md`.
+
+An adapter or agent must not:
+
+- change command purpose
+- skip required input or confirmation
+- write a different artifact set
+- relax readiness, review, access, or security gates
+- invent status values outside `devspec/glossary.md`
+- recommend unregistered commands
+- hide platform limitations by changing workflow semantics
+
+Record platform gaps in `devspec/adapters/compatibility-matrix.md` when needed.
+
+## Required Flows
+
+New repository foundation:
+
+```text
+/devspec.projectcontext
+/devspec.techstack
+/devspec.codebase-structure
+/devspec.coding-standards
+/devspec.rules
+```
+
+Existing repository foundation:
+
+```text
+/devspec.extract
+/devspec.projectcontext
+/devspec.techstack
+/devspec.codebase-structure
+/devspec.coding-standards
+/devspec.rules
+```
+
+Work-item story lifecycle:
+
+```text
+/devspec.story
+/devspec.finalize
+/devspec.tasks
+/devspec.implement
+/devspec.review
+```
+
+Use `/devspec.clarify` only when work-item intake or finalization records a blocking question. Use `/devspec.diagram` for diagram work after relevant context exists.
+
+## Enterprise Validation
+
+Use `devspec/adapters/validation-flows.md` as the acceptance checklist for new repository, existing repository, story lifecycle, and cross-tool recovery validation.
+
+## Gemini and Antigravity Notes
+
+- Gemini CLI reads `GEMINI.md`, which imports this file and maps native `/devspec:*` commands to canonical `/devspec.*` workflow intent.
+- Google Antigravity reads workspace rules and skills from `.agents/`; native skills use `/devspec-*` names while preserving canonical `/devspec.*` command behavior.
+- Gemini and Antigravity adapters must document platform-specific permission, sandbox, telemetry, and command-name limitations without changing `devspec` semantics.

devspec_installer/payload/GEMINI.md

@@ -0,0 +1,35 @@
+# Devspec Gemini Instructions
+
+Use this file as Gemini CLI and Gemini-backed agent context for this repository.
+
+@./AGENTS.md
+
+## Gemini Adapter Rules
+
+- Treat `AGENTS.md` as the shared cross-agent baseline.
+- Treat `devspec/adapters/command-registry.md` as the canonical command registry.
+- Treat `.github/prompts/*.prompt.md` and `.github/agents/*.agent.md` as the protected reference implementation.
+- Preserve canonical `/devspec.*` command vocabulary even when Gemini CLI invokes native commands such as `/devspec:story`.
+- Recover from Git-tracked `devspec/` artifacts before relying on Gemini session memory.
+- Preserve structured question behavior from `.github/prompts/PATTERNS.md#interactive-question-pattern`; if Gemini does not provide clickable options, render the same option labels as text and preserve the recommended option.
+- Do not store credentials, API keys, tokens, personal settings, or provider secrets in Gemini context, commands, or artifacts.
+
+## Native Gemini Commands
+
+Gemini CLI project commands live under `.gemini/commands/devspec/`.
+
+| Canonical command | Gemini CLI command |
+| --- | --- |
+| `/devspec.extract` | `/devspec:extract` |
+| `/devspec.projectcontext` | `/devspec:projectcontext` |
+| `/devspec.techstack` | `/devspec:techstack` |
+| `/devspec.codebase-structure` | `/devspec:codebase-structure` |
+| `/devspec.coding-standards` | `/devspec:coding-standards` |
+| `/devspec.rules` | `/devspec:rules` |
+| `/devspec.story` | `/devspec:story` |
+| `/devspec.clarify` | `/devspec:clarify` |
+| `/devspec.finalize` | `/devspec:finalize` |
+| `/devspec.tasks` | `/devspec:tasks` |
+| `/devspec.implement` | `/devspec:implement` |
+| `/devspec.review` | `/devspec:review` |
+| `/devspec.diagram` | `/devspec:diagram` |

devspec_installer/payload/README.md

@@ -0,0 +1,301 @@
+# devspec
+
+`devspec` is a spec-driven development framework for teams using GitHub Copilot and other AI coding agents.
+
+It stores planning, implementation, review, and recovery state in Git-tracked files instead of relying on chat history.
+
+Use it when you want agents to follow the same workflow for:
+
+- project context, architecture, engineering rules, and coding standards
+- feature, bug, and security work-item intake
+- clarification, finalization, task planning, implementation, and review
+- session recovery from repository artifacts
+
+## Quick Start
+
+Install with the `devspec` CLI. The recommended one-off path is `uvx`, which avoids a permanent global install and works well on machines where developers cannot write to shared PATH folders.
+
+For install, workflow, AI coding agent, multi-repo, provider, validation, and upgrade examples, see [`docs/how-to/README.md`](docs/how-to/README.md).
+
+1. Open the target repository in VS Code or the selected AI coding tool.
+2. Install all supported adapter files into the repository:
+
+   ```text
+   uvx devspec init --target . --profile all --repo-state existing
+   ```
+
+   Use `--repo-state new` for a new repository.
+
+3. Validate the install:
+
+   ```text
+   uvx devspec doctor --target . --profile all
+   ```
+
+4. Commit the copied files.
+5. Run the foundation flow for a new or existing repository.
+6. Start the first work item.
+
+Manual copy remains supported as a fallback when package managers are blocked. Copy the framework folders listed in [Manual Copy Fallback](#manual-copy-fallback), then commit the copied files.
+
+For a new project:
+
+```text
+/devspec.projectcontext
+/devspec.techstack
+/devspec.codebase-structure
+/devspec.coding-standards
+/devspec.rules
+```
+
+For an existing project:
+
+```text
+/devspec.extract
+/devspec.projectcontext
+/devspec.techstack
+/devspec.codebase-structure
+/devspec.coding-standards
+/devspec.rules
+```
+
+Then run the work-item flow:
+
+```text
+/devspec.story
+/devspec.finalize
+/devspec.tasks
+/devspec.implement
+/devspec.review
+```
+
+Use `/devspec.clarify` only when a work item records a blocking question. Use `/devspec.diagram` when a diagram would clarify architecture, workflow, state, sequence, or domain behavior.
+
+## How It Works
+
+`devspec` has two workflow layers.
+
+| Layer | Purpose | Commands |
+| --- | --- | --- |
+| Foundation | Capture stable project context, architecture, stack, structure, standards, and rules. | `/devspec.extract`, `/devspec.projectcontext`, `/devspec.techstack`, `/devspec.codebase-structure`, `/devspec.coding-standards`, `/devspec.rules` |
+| Work items | Move one feature, bug, or security issue from intake to review. | `/devspec.story`, `/devspec.clarify`, `/devspec.finalize`, `/devspec.tasks`, `/devspec.implement`, `/devspec.review` |
+
+```mermaid
+flowchart TD
+    Start["Start"] --> State{"Project state?"}
+    State -- "new" --> ProjectContext["/devspec.projectcontext"]
+    State -- "existing" --> Extract["/devspec.extract"]
+    Extract --> ProjectContext
+    ProjectContext --> TechStack["/devspec.techstack"]
+    TechStack --> Structure["/devspec.codebase-structure"]
+    Structure --> Standards["/devspec.coding-standards"]
+    Standards --> Rules["/devspec.rules"]
+    Rules --> Story["/devspec.story"]
+    Story --> Blocked{"Blocking question?"}
+    Blocked -- "yes" --> Clarify["/devspec.clarify"]
+    Clarify --> Story
+    Blocked -- "no" --> Finalize["/devspec.finalize"]
+    Finalize --> Ready{"Ready?"}
+    Ready -- "no" --> Clarify
+    Ready -- "yes" --> Tasks["/devspec.tasks"]
+    Tasks --> Implement["/devspec.implement"]
+    Implement --> Review["/devspec.review"]
+    Review --> Outcome{"Review outcome?"}
+    Outcome -- "changes requested" --> Implement
+    Outcome -- "approved" --> Done["Done"]
+```
+
+## Command Reference
+
+| Command | Use when | Main output |
+| --- | --- | --- |
+| `/devspec.extract` | Existing code/docs should seed the foundation. | Foundation, architecture, extraction, and diagram queue artifacts. |
+| `/devspec.projectcontext` | Product and business context must be recorded. | `devspec/foundation/project-context.md` |
+| `/devspec.techstack` | Stack, runtime, hosting, tooling, or support status must be recorded. | `devspec/foundation/tech-stack.md` |
+| `/devspec.codebase-structure` | Repository layout, boundaries, multi-repo access, or integration contracts must be recorded. | `devspec/foundation/codebase-structure.md` |
+| `/devspec.coding-standards` | Engineering standards and observed patterns must be recorded. | `devspec/foundation/coding-standards.md` |
+| `/devspec.rules` | Operational rules, compliance requirements, and gates must be recorded. | `devspec/foundation/rules.md` |
+| `/devspec.story` | A feature, bug, security issue, task, PBI, or provider reference needs intake. | Work-item `meta.md`, `story.md`, `decisions.md`, `notes.md` |
+| `/devspec.clarify` | A blocking question must be resolved. | Work-item `clarify.md` |
+| `/devspec.finalize` | A work item needs an implementation-ready brief. | Work-item `finalize.md` |
+| `/devspec.tasks` | A ready brief needs executable tasks. | Work-item `tasks.md` |
+| `/devspec.implement` | Pending tasks should be implemented and recorded. | Work-item `implement.md` and code changes when applicable |
+| `/devspec.review` | Implemented work needs review against the finalized brief. | Work-item `review.md` |
+| `/devspec.diagram` | A diagram should be created or updated. | Architecture or work-item Mermaid diagram artifacts |
+
+For exact command contracts, see `devspec/adapters/command-registry.md`.
+
+## AI Tool Support
+
+GitHub Copilot prompt and agent files are the reference implementation. Other adapters are thin wrappers around the same command registry and Git-tracked artifacts.
+
+| Tool | Files | Notes |
+| --- | --- | --- |
+| GitHub Copilot | `.github/prompts/`, `.github/agents/` | Native `/devspec.*` command implementation. |
+| Claude Code | `.claude/skills/devspec-*/SKILL.md` | Project skills for canonical commands. |
+| OpenAI Codex | `AGENTS.md`, `devspec/adapters/codex.md` | Repository instructions and Codex guidance. |
+| Cursor | `.cursor/rules/devspec-workflow.mdc`, `AGENTS.md` | Project rules plus shared fallback instructions. |
+| Gemini CLI | `GEMINI.md`, optional `.gemini/commands/devspec/*.toml` | `GEMINI.md` is enough for context; TOML files only add native `/devspec:*` shortcuts. |
+| Google Antigravity | `.agents/rules/devspec-workflow.md`, `.agents/skills/devspec-*.md` | Workspace rule and skills using `/devspec-*` names. |
+
+Canonical command names remain `/devspec.*`. Some adapters expose host-native shortcuts such as `/devspec:story` or `/devspec-story`.
+
+Related docs:
+
+- [`docs/how-to/README.md`](docs/how-to/README.md)
+- [`devspec/adapters/README.md`](devspec/adapters/README.md)
+- [`devspec/adapters/compatibility-matrix.md`](devspec/adapters/compatibility-matrix.md)
+- [`devspec/adapters/validation-flows.md`](devspec/adapters/validation-flows.md)
+- [`devspec/adapters/enterprise-governance.md`](devspec/adapters/enterprise-governance.md)
+
+## Repository Layout
+
+| Path | Purpose |
+| --- | --- |
+| `devspec/constitution.md` | Durable project principles across all work items and agents. |
+| `devspec/foundation/` | Product context, stack, structure, standards, rules, exclusions, and provider policy. |
+| `devspec/architecture/` | Architecture overview, diagrams, ADR templates, and artifact queue. |
+| `devspec/work-items/` | One folder per feature, bug, or security work item. |
+| `devspec/adapters/` | Multi-agent registry, compatibility, validation, and governance docs. |
+| `docs/how-to/` | User manual with install, workflow, AI coding agent, multi-repo, provider, validation, and upgrade examples. |
+| `.github/prompts/` | Copilot slash-command prompts. |
+| `.github/agents/` | Copilot agent definitions. |
+| `.github/skills/` | Optional reusable skills. |
+| `AGENTS.md` | Shared instructions for tools that read `AGENTS.md`. |
+| `GEMINI.md` | Gemini-native repository context. |
+| `.claude/`, `.cursor/`, `.gemini/`, `.agents/` | Optional adapter support. |
+
+## Manual Copy Fallback
+
+Use manual copy only when the CLI, `uvx`, package managers, and release ZIP automation are blocked. Copy these core files and folders from the `devspec` release into the target repository root:
+
+```text
+devspec/
+.github/prompts/
+.github/agents/
+AGENTS.md
+docs/how-to/
+```
+
+Then copy only the adapter files your team uses:
+
+| Tool | Additional files |
+| --- | --- |
+| GitHub Copilot | `.github/skills/` |
+| Claude Code | `.claude/` |
+| OpenAI Codex | No extra files beyond `AGENTS.md` |
+| Cursor | `.cursor/` |
+| Gemini CLI | `GEMINI.md`, `.gemini/` |
+| Google Antigravity | `.agents/` |
+
+Do not copy this framework repository's root `README.md` over a target project's README. Keep credentials, provider tokens, local auth files, and personal settings outside copied framework files.
+
+## Operating Rules
+
+- Keep `.github/prompts/*.prompt.md` and `.github/agents/*.agent.md` as the protected reference contracts.
+- Keep adapter support additive; do not change command intent for another tool.
+- Store workflow state in Git-tracked `devspec/` artifacts, not chat memory.
+- Use `devspec/glossary.md` for status values.
+- Use `devspec/foundation/codebase-structure.md` for repository access requirements.
+- Keep secrets and provider credentials outside prompt, agent, adapter, and artifact files.
+- Record blockers instead of guessing.
+- Recommend only registered `/devspec.*` commands.
+
+## Multi-Repo Work
+
+For multi-repo systems, open one workspace or tool project that includes every repository agents should inspect, edit, test, or coordinate.
+
+Record repository roles, local paths, access requirements, and boundaries in:
+
+```text
+devspec/foundation/codebase-structure.md
+```
+
+Access values are defined in:
+
+```text
+devspec/glossary.md#access-requirement-values
+```
+
+## Provider Integrations
+
+Use provider integrations when `/devspec.story` should resolve GitHub, Jira, Azure DevOps, or other external work-item references.
+
+Provider policy lives in:
+
+```text
+devspec/foundation/provider-integrations.md
+```
+
+Keep authentication outside prompt artifacts. Prefer read-only provider access unless write-back is explicitly required.
+
+## Validation
+
+Enterprise readiness requires these flows to pass for each supported adapter:
+
+- new repository foundation flow
+- existing repository extraction flow
+- full story lifecycle
+- cross-tool recovery from Git-tracked artifacts
+
+Use:
+
+```text
+devspec/adapters/validation-flows.md
+```
+
+## Upgrade Notes
+
+Use the CLI to inspect and apply framework upgrades:
+
+```text
+devspec diff --target .
+devspec sync --target . --profile all --dry-run
+devspec sync --target . --profile all
+```
+
+Framework-owned files may be replaced or diff-applied during upgrades:
+
+- `.github/prompts/`
+- `.github/agents/`
+- `.github/skills/`
+- adapter support folders
+- `AGENTS.md`
+- `GEMINI.md`
+- `devspec/adapters/`
+- `devspec/**/_template/`
+- `docs/how-to/`
+
+Project-owned files should be migrated or merged, not overwritten:
+
+- `devspec/foundation/*.md`
+- `devspec/architecture/*.md`
+- `devspec/architecture/diagrams/*.md`
+- `devspec/work-items/**`
+- `devspec/constitution.md`
+- `devspec/glossary.md`
+
+## Recommended Adoption
+
+1. Install into one target repository with `uvx devspec init --target . --profile all --repo-state existing`.
+2. Run the foundation flow.
+3. Complete one real feature work item.
+4. Complete one real bug work item.
+5. Add security-vulnerability flow validation if relevant.
+6. Adjust foundation docs based on what the first runs teach the team.
+
+## Deployment Development
+
+When changing the installer, profile manifest, package metadata, or release automation, run:
+
+```text
+uv run pytest
+powershell -ExecutionPolicy Bypass -File scripts/test-local-install.ps1
+bash scripts/test-local-install.sh
+```
+
+Update `packaging/devspec-profiles.json` whenever adapter files are added, removed, or moved.
+
+## License
+
+This repository is released under the [Apache License 2.0](LICENSE).