devspec 0.1.0__py3-none-any.whl

devspec_installer/payload/devspec/adapters/README.md

@@ -0,0 +1,53 @@
+# Multi-Agent Adapter Guide
+
+Use this directory to keep multi-agent support additive. GitHub Copilot prompt and agent files remain the reference implementation; adapters for Claude Code, OpenAI Codex, Cursor, Gemini CLI, Google Antigravity, and future tools must preserve that intent instead of redefining the workflow.
+
+## Adapter Contract
+
+| Contract area | Requirement |
+| --- | --- |
+| Reference source | Use `.github/prompts/*.prompt.md` and `.github/agents/*.agent.md` as the canonical command and agent contracts. |
+| Command registry | Use `devspec/adapters/command-registry.md` for provider-neutral command names, required inputs, outputs, mutation levels, and handoffs. |
+| State source | Recover from Git-tracked `devspec/` artifacts before relying on chat history or tool memory. |
+| Intent preservation | Do not change command purpose, required input, output artifacts, status values, handoff order, readiness gates, review gates, or recovery behavior. |
+| Platform gaps | Document unsupported behavior as a limitation; do not hide gaps by changing `devspec` semantics. |
+| Integration model | Keep provider lookup, CI, scanners, and enterprise systems behind MCP servers, approved connectors, or equivalent internal tools. |
+
+## Adapter Files
+
+| Adapter | Primary files | Role |
+| --- | --- | --- |
+| GitHub Copilot | `.github/prompts/`, `.github/agents/`, `.github/skills/` | Native `/devspec.*` command implementation and reference adapter. |
+| Claude Code | `.claude/skills/devspec-*/SKILL.md` | Project skills that invoke the same command contract from Claude Code. |
+| OpenAI Codex | `AGENTS.md`, `devspec/adapters/codex.md` | Always-on repository guidance and Codex usage notes for the same workflow. |
+| Cursor | `.cursor/rules/devspec-workflow.mdc`, `AGENTS.md` | Project rule guidance for Cursor Agent and Inline Edit. |
+| Gemini CLI | `GEMINI.md`, `.gemini/commands/devspec/*.toml` | Gemini context and project custom commands for the same workflow. |
+| Google Antigravity | `.agents/rules/devspec-workflow.md`, `.agents/skills/devspec-*.md` | Workspace rule and skills for Antigravity agents. |
+| Future tools | `devspec/adapters/command-registry.md`, `AGENTS.md` | Map new tool-specific commands, skills, or rules to the same registry. |
+
+## Usage Examples
+
+For install steps, workflow walkthroughs, and copy-ready command examples across AI coding agents, see [`../../docs/how-to/README.md`](../../docs/how-to/README.md).
+
+## Implementation Order
+
+1. Confirm the command exists in `devspec/adapters/command-registry.md`.
+2. Read the canonical Copilot prompt and agent files named in the registry.
+3. Implement a thin adapter wrapper for the target tool.
+4. Preserve required inputs, artifact writes, gates, handoffs, recovery behavior, and next-action behavior.
+5. Validate with `devspec/adapters/validation-flows.md`.
+
+## No-Intent-Drift Rules
+
+An adapter has drifted when it does any of the following:
+
+- changes the purpose of a command or stage
+- drops a required input or confirmation
+- writes a different artifact set
+- relaxes readiness, review, repository-access, or security gates
+- renames or invents status values outside `devspec/glossary.md`
+- changes the registered next command or handoff order
+- treats platform-specific limitations as workflow changes
+- relies on chat memory when a Git-tracked `devspec` artifact exists
+
+If exact behavior cannot be represented on a platform, record the gap in `devspec/adapters/compatibility-matrix.md` and keep the workflow contract unchanged.

devspec_installer/payload/devspec/adapters/antigravity.md

@@ -0,0 +1,52 @@
+# Google Antigravity Adapter
+
+Google Antigravity support is implemented through workspace rules under `.agents/rules/` and workspace skills under `.agents/skills/`.
+
+## Invocation Model
+
+| Devspec command | Antigravity skill |
+| --- | --- |
+| `/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` |
+
+## Adapter Rules
+
+- `.agents/rules/devspec-workflow.md` provides always-on workspace guidance.
+- `.agents/skills/devspec-*.md` provides command-like wrappers for each canonical command.
+- Each skill references `devspec/adapters/command-registry.md` and the matching Copilot prompt and agent files.
+- Do not add Antigravity workflow files until the target workflow file location and format are confirmed for the team.
+- Antigravity artifacts, task lists, and implementation plans are transient helpers; Git-tracked `devspec/` artifacts remain canonical.
+
+## Enterprise Safety
+
+| Area | Guidance |
+| --- | --- |
+| Rules | Workspace rules live under `.agents/rules/`; keep the devspec rule broad, short, and always on. |
+| Skills | Workspace skills live under `.agents/skills/` and become slash-invokable command wrappers. |
+| Permissions | Prefer Ask or Request Review for terminal commands, browser actions, MCP calls, non-workspace file access, and artifact application. |
+| Strict mode | Use strict mode or equivalent review posture for regulated, security-sensitive, or unfamiliar repositories. |
+| Sandboxing | Enable terminal sandboxing where available; deny network access unless the workflow requires it. |
+| Project boundaries | Keep projects scoped to the repositories recorded in `devspec/foundation/codebase-structure.md`. |
+| Artifact review | Treat Antigravity implementation plans and code diffs as review surfaces; canonical completion evidence still belongs in `devspec` artifacts. |
+| Secrets | Keep credentials, tokens, local settings, and provider secrets outside rules, skills, prompts, and artifacts. |
+
+## Known Gaps
+
+- Exact `/devspec.*` slash parity is not assumed; Antigravity skills use `/devspec-story` style names.
+- Antigravity workflows are intentionally not shipped until their workspace file contract is confirmed for the target environment.
+- Permission, sandbox, project, and artifact-review behavior depends on the user's Antigravity project settings.
+
+## Validation
+
+Run the new repository, existing repository, story, and cross-tool recovery flows in `devspec/adapters/validation-flows.md` with Antigravity before treating the adapter as enterprise-ready.

devspec_installer/payload/devspec/adapters/claude-code.md

@@ -0,0 +1,32 @@
+# Claude Code Adapter
+
+Claude Code support is implemented through project skills under `.claude/skills/devspec-*/SKILL.md`.
+
+## Invocation Model
+
+| Devspec command | Claude skill |
+| --- | --- |
+| `/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` |
+
+## Adapter Rules
+
+- Each skill is a thin wrapper around the canonical command registry.
+- Each skill references the matching Copilot prompt and agent files instead of redefining command behavior.
+- Dotted command names are preserved as canonical `devspec` vocabulary even when Claude invokes hyphenated skill names.
+- Platform limitations belong in `devspec/adapters/compatibility-matrix.md`.
+
+## Validation
+
+Run the new repository, existing repository, story, and cross-tool recovery flows in `devspec/adapters/validation-flows.md` with Claude Code after installing or copying the project skills.

devspec_installer/payload/devspec/adapters/codex-skills/devspec-workflow/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: devspec-workflow
+description: Use when running any /devspec.* workflow from OpenAI Codex while preserving the canonical Copilot command and agent intent.
+---
+
+# Devspec Workflow
+
+Use this optional Codex skill as a starter template for repeated `devspec` workflows.
+
+Before acting:
+
+1. Read `AGENTS.md`.
+2. Read `devspec/adapters/command-registry.md` for the requested `/devspec.*` command.
+3. Read the canonical `.github/prompts/*.prompt.md` and `.github/agents/*.agent.md` files named by the registry.
+4. Follow `AGENTS.md` for recovery, no-intent-drift, structured question behavior, and platform limitation handling.
+
+Do not assume Copilot prompt files register as Codex slash commands. Treat the command name as workflow intent unless the active Codex surface provides its own matching command mechanism.

devspec_installer/payload/devspec/adapters/codex.md

@@ -0,0 +1,22 @@
+# OpenAI Codex Adapter
+
+OpenAI Codex support starts with root `AGENTS.md`, which gives Codex the always-on repository instructions for the `devspec` workflow.
+
+## Invocation Model
+
+| Surface | Expected behavior |
+| --- | --- |
+| `AGENTS.md` | Teaches Codex to treat `/devspec.*` as workflow intent and to use the command registry before acting. |
+| Codex CLI or IDE extension | Users may type the canonical command name in a prompt, but Copilot prompt files are not assumed to register as Codex slash commands. |
+| Codex skills | Optional starter template lives at `devspec/adapters/codex-skills/devspec-workflow/SKILL.md`; any installed skill must remain a thin wrapper over `devspec/adapters/command-registry.md`. |
+
+## Adapter Rules
+
+- Read `AGENTS.md` and `devspec/adapters/command-registry.md` before executing a `devspec` workflow.
+- Preserve Copilot prompt and agent intent from the canonical files listed in the registry.
+- Use Git-tracked `devspec` artifacts for recovery and handoff decisions.
+- Treat Codex-specific slash commands, local/cloud modes, sandboxing, and approvals as platform mechanics, not workflow changes.
+
+## Validation
+
+Run the flow checklists in `devspec/adapters/validation-flows.md` with Codex local workflows before using Codex for enterprise delivery.

devspec_installer/payload/devspec/adapters/command-registry.md

@@ -0,0 +1,38 @@
+# Devspec Command Registry
+
+This registry is the provider-neutral contract for all `devspec` adapters. The GitHub Copilot prompt and agent files named here are the authoritative source for command intent. Adapter files may translate platform mechanics, but they must not change command purpose, required inputs, output artifacts, status values, gates, handoffs, or recovery behavior.
+
+## Mutation Levels
+
+| Level | Meaning |
+| --- | --- |
+| `artifact-write` | May create or update `devspec/` artifacts only. |
+| `code-write` | May edit target repository code when the upstream work item and repository access allow it. |
+| `review-write` | May write review artifacts and report findings, but should not change implementation code. |
+| `diagram-write` | May create or update Mermaid diagram artifacts and related queue state. |
+
+## Registered Commands
+
+| Command | Purpose | Required input | Canonical prompt | Canonical agent | Main outputs | Mutation level | Next handoff |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| `/devspec.extract` | Backfill project foundation, architecture context, constitution candidates, process-flow candidates, and diagram queue candidates from current root, repository URLs, local paths, or named multi-repo sources. | Optional source input; blank input triggers current-root or source selection. | `.github/prompts/devspec.extract.prompt.md` | `.github/agents/devspec.extract.agent.md` | `devspec/foundation/extraction-state.md`, `devspec/constitution.md`, `devspec/architecture/overview.md`, `devspec/architecture/artifact-queue.md`, live `devspec/foundation/*.md` | `artifact-write` | `/devspec.projectcontext` |
+| `/devspec.projectcontext` | Capture product purpose, audiences, stakeholders, outcomes, scope boundaries, metrics, delivery context, sources, confidence, and developer implications. | Product context input. | `.github/prompts/devspec.projectcontext.prompt.md` | `.github/agents/devspec.projectcontext.agent.md` | `devspec/foundation/project-context.md` | `artifact-write` | `/devspec.techstack` |
+| `/devspec.techstack` | Capture technology stack inventory, support status, evidence, confidence, delivery constraints, and implementation impact. | Stack evidence, target stack, hosting, tooling, or constraints. | `.github/prompts/devspec.techstack.prompt.md` | `.github/agents/devspec.techstack.agent.md` | `devspec/foundation/tech-stack.md` | `artifact-write` | `/devspec.codebase-structure` |
+| `/devspec.codebase-structure` | Capture repository layout, work areas, boundaries, integration contracts, multi-repo configuration, and access requirements. | Repository layout, work-area, integration, or multi-repo details. | `.github/prompts/devspec.codebase-structure.prompt.md` | `.github/agents/devspec.codebase-structure.agent.md` | `devspec/foundation/codebase-structure.md` | `artifact-write` | `/devspec.coding-standards` |
+| `/devspec.coding-standards` | Capture evidence-backed engineering standards, observed patterns, anti-patterns, source links, and examples. | Standards input, source links, or evidence to confirm. | `.github/prompts/devspec.coding-standards.prompt.md` | `.github/agents/devspec.coding-standards.agent.md` | `devspec/foundation/coding-standards.md` | `artifact-write` | `/devspec.rules` |
+| `/devspec.rules` | Capture operational hard constraints, compliance requirements, forbidden patterns, delivery gates, exceptions, enforcement points, source, and confidence. | Rules, gates, governance, compliance, or constraint input. | `.github/prompts/devspec.rules.prompt.md` | `.github/agents/devspec.rules.agent.md` | `devspec/foundation/rules.md` | `artifact-write` | `/devspec.story` |
+| `/devspec.story` | Create or update work-item intake artifacts from a provider URL, provider identifier, manual feature request, bug report, security issue, task, or PBI. | Work-item reference or manual intake details. | `.github/prompts/devspec.story.prompt.md` | `.github/agents/devspec.story.agent.md` | `devspec/work-items/<work-item-folder>/meta.md`, `story.md`, `decisions.md`, `notes.md` | `artifact-write` | `/devspec.clarify` if blocked; otherwise `/devspec.finalize` |
+| `/devspec.clarify` | Ask, resolve, and record one active blocking clarification for an existing work item. | Existing work item with a recorded blocker or clarification need. | `.github/prompts/devspec.clarify.prompt.md` | `.github/agents/devspec.clarify.agent.md` | `devspec/work-items/<work-item-folder>/clarify.md` | `artifact-write` | Repeat until unblocked, then `/devspec.finalize` |
+| `/devspec.finalize` | Create or update an implementation readiness brief with readiness assessment, implementation brief, validation plan, and blockers. | Existing upstream work-item artifacts. Optional additive readiness input. | `.github/prompts/devspec.finalize.prompt.md` | `.github/agents/devspec.finalize.agent.md` | `devspec/work-items/<work-item-folder>/finalize.md` | `artifact-write` | `/devspec.tasks` when ready |
+| `/devspec.tasks` | Break a ready finalized brief into ordered executable implementation tasks with planning basis, validation, and done criteria. | `finalize.md` marked `ready`; optional task-planning input. | `.github/prompts/devspec.tasks.prompt.md` | `.github/agents/devspec.tasks.agent.md` | `devspec/work-items/<work-item-folder>/tasks.md` | `artifact-write` | `/devspec.implement` |
+| `/devspec.implement` | Implement pending tasks for the current ready work item, update implementation checkpoints, and confirm after each task. | `finalize.md` marked `ready` and `tasks.md`; optional implementation or validation guidance. | `.github/prompts/devspec.implement.prompt.md` | `.github/agents/devspec.implement-task.agent.md` | `devspec/work-items/<work-item-folder>/implement.md`, code changes when applicable | `code-write` | `/devspec.review` when complete |
+| `/devspec.review` | Review implemented work against the finalized brief and record review outcome. | `finalize.md` and `implement.md`; optional review focus. | `.github/prompts/devspec.review.prompt.md` | `.github/agents/devspec.review.agent.md` | `devspec/work-items/<work-item-folder>/review.md` | `review-write` | Return to `/devspec.implement` for changes or close the work item |
+| `/devspec.diagram` | Generate or update one evidence-backed Mermaid diagram, or batch-generate queued process-flow diagrams when explicitly requested. | Diagram subject, related work item, or explicit process-flow batch request. | `.github/prompts/devspec.diagram.prompt.md` | `.github/agents/devspec.diagram.agent.md` | `devspec/architecture/diagrams/dia-NNN-*.md`, `devspec/architecture/overview.md` for high-level diagrams, or work-item `diagrams.md` for temporary work-item diagrams | `diagram-write` | Continue the current workflow |
+
+## Required Flow Gates
+
+| Flow | Command order | Acceptance signal |
+| --- | --- | --- |
+| New repository foundation | `/devspec.projectcontext` -> `/devspec.techstack` -> `/devspec.codebase-structure` -> `/devspec.coding-standards` -> `/devspec.rules` | Foundation artifacts exist, no extraction artifact is required, and each command records sources, confidence, blockers, and next action. |
+| Existing repository foundation | `/devspec.extract` -> `/devspec.projectcontext` -> `/devspec.techstack` -> `/devspec.codebase-structure` -> `/devspec.coding-standards` -> `/devspec.rules` | Extraction evidence is recorded, foundation artifacts are refined, exclusions are respected, blockers are explicit, and confirmations are preserved. |
+| Story lifecycle | `/devspec.story` -> optional `/devspec.clarify` -> `/devspec.finalize` -> `/devspec.tasks` -> `/devspec.implement` -> `/devspec.review` | Work-item artifacts exist, readiness is honored, tasks are executable, implementation ledger is current, validation evidence is recorded, and review status uses glossary values. |

devspec_installer/payload/devspec/adapters/compatibility-matrix.md

@@ -0,0 +1,21 @@
+# Platform Compatibility Matrix
+
+Use this matrix when adding or reviewing adapter support. A platform limitation must be documented here instead of changing `devspec` command semantics.
+
+| Capability | GitHub Copilot in VS Code | Claude Code | OpenAI Codex | Cursor | Gemini CLI | Google Antigravity | Future adapters |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| Reference status | Reference implementation | Adapter | Adapter | Adapter | Adapter | Adapter | Adapter |
+| Native command surface | `.github/prompts/*.prompt.md` registers `/devspec.*` prompt files. | `.claude/skills/*/SKILL.md` project skills expose command-like workflows. | `AGENTS.md` provides always-on guidance; Codex slash commands are tool-owned and should not be assumed to mirror Copilot prompt files. | `.cursor/rules/*.mdc` provides project rules; exact custom slash parity is not assumed. | `.gemini/commands/devspec/*.toml` provides `/devspec:*` project custom commands. | `.agents/skills/devspec-*.md` provides `/devspec-*` workspace skills. | Must map to `devspec/adapters/command-registry.md`. |
+| Agent surface | `.github/agents/*.agent.md` with tools, model fallback, and handoffs. | Skills may run inline or through Claude subagents when configured. | Skills and app or CLI features may assist, but the repo contract starts from `AGENTS.md`. | Cursor Agent applies project rules and referenced files. | Gemini CLI applies context from `GEMINI.md` and command prompts. | Antigravity agents apply workspace rules, skills, permissions, artifacts, and project settings. | Must preserve command intent and artifact contracts. |
+| Always-on repository guidance | Optional `.github/copilot-instructions.md` or prompt/agent context. | `CLAUDE.md` may be used by adopters; this framework ships skills instead of changing memory. | Root `AGENTS.md`. | Root `AGENTS.md` plus `.cursor/rules`. | Root `GEMINI.md` imports `AGENTS.md`. | `.agents/rules/devspec-workflow.md` plus `AGENTS.md` and `GEMINI.md` when supported. | Prefer `AGENTS.md` when supported. |
+| MCP or external tools | Supported through Copilot and configured VS Code tools. | Supported through Claude Code MCP configuration. | Supported through Codex MCP configuration when enabled by the environment. | Supported through Cursor MCP configuration when enabled by the environment. | Supported through Gemini CLI settings or extensions when enabled. | Supported through Antigravity skills, plugins, and MCP configuration when enabled. | Provider integrations must remain outside prompt artifacts. |
+| Approval and permissions | Governed by VS Code, Copilot, workspace trust, and selected tools. | Governed by Claude Code permissions and tool approvals. | Governed by Codex local, cloud, sandbox, and approval settings. | Governed by Cursor Agent permissions and workspace settings. | Governed by Gemini CLI trusted folders, sandboxing, and enterprise settings. | Governed by Antigravity project permissions, strict mode, sandboxing, and artifact review. | Must document permissions before write workflows. |
+| Telemetry | Use tool-provided telemetry when available; otherwise record unavailable in artifacts. | Use available session, cost, or tool data when exposed. | Use available Codex status or analytics data when exposed. | Use available Cursor session signals when exposed. | Use Gemini CLI telemetry only when configured; otherwise record unavailable. | Use Antigravity session, artifact, or quota signals only when exposed; otherwise record unavailable. | Missing telemetry is recorded as unavailable, not invented. |
+| Known gaps | None for the current reference workflow. | Exact dotted `/devspec.*` command names may depend on skill or command naming behavior. | Copilot prompt files do not automatically register as Codex slash commands. | Cursor rules guide behavior but do not guarantee slash-command registration. | Native commands use `/devspec:story`, not exact `/devspec.story`. | Native skills use `/devspec-story`; workflow files are not shipped until file contracts are confirmed. | Must be captured before enterprise rollout. |
+
+## Compatibility Rules
+
+- Keep command names and artifact contracts stable even when the host tool uses a different invocation surface.
+- Prefer explicit user invocation for stage commands that write artifacts or code.
+- Do not store credentials, tokens, personal settings, or provider secrets in adapter files.
+- Record unsupported host features as platform gaps and continue to use the canonical `devspec` artifacts.

devspec_installer/payload/devspec/adapters/copilot.md

@@ -0,0 +1,20 @@
+# GitHub Copilot Adapter
+
+GitHub Copilot in VS Code is the native and reference adapter for `devspec`.
+
+## Reference Files
+
+| File group | Role |
+| --- | --- |
+| `.github/prompts/*.prompt.md` | Registers the user-invoked `/devspec.*` commands and command-level required input. |
+| `.github/agents/*.agent.md` | Defines stage behavior, tools, model fallback, constraints, handoffs, and output format. |
+| `.github/prompts/PATTERNS.md` | Defines shared workflow, recovery, output, discovery, recommendation, and artifact patterns. |
+| `.github/skills/` | Optional reusable skills that travel with the repository. |
+
+## Compatibility Note
+
+Do not change Copilot prompt or agent intent to support another tool. Other adapters must wrap or translate the Copilot reference behavior and remain conformant with `devspec/adapters/command-registry.md`.
+
+## Validation
+
+Before an enterprise release, verify VS Code with Copilot Chat recognizes every registered `/devspec.*` command and run the flow checklists in `devspec/adapters/validation-flows.md`.

devspec_installer/payload/devspec/adapters/cursor.md

@@ -0,0 +1,22 @@
+# Cursor Adapter
+
+Cursor support is implemented through project rules under `.cursor/rules/` and the shared root `AGENTS.md`.
+
+## Invocation Model
+
+| Surface | Expected behavior |
+| --- | --- |
+| `.cursor/rules/devspec-workflow.mdc` | Provides project-scoped guidance for Cursor Agent and Inline Edit. |
+| `AGENTS.md` | Provides a simple cross-agent fallback for `devspec` workflow behavior. |
+| Chat prompt | Users may type canonical `/devspec.*` command names as workflow intent; exact slash registration is not assumed. |
+
+## Adapter Rules
+
+- Use `devspec/adapters/command-registry.md` for command order, required input, artifact outputs, mutation level, and handoff.
+- Preserve GitHub Copilot prompt and agent intent from the canonical files named in the registry.
+- Do not let Cursor-specific memories or user rules override Git-tracked `devspec` artifacts.
+- Record unsupported Cursor behavior in `devspec/adapters/compatibility-matrix.md`.
+
+## Validation
+
+Run the new repository, existing repository, story, and cross-tool recovery flows in `devspec/adapters/validation-flows.md` before treating Cursor as enterprise-ready.

devspec_installer/payload/devspec/adapters/enterprise-governance.md

@@ -0,0 +1,36 @@
+# Enterprise Operating Guide
+
+Use this guide when adopting `devspec` across teams, repositories, or AI coding tools.
+
+## Governance Controls
+
+| Area | Requirement |
+| --- | --- |
+| Model allowlist | Record approved models or model families per adapter. Do not require adapter files to name a model that the target platform cannot enforce. |
+| Tool permissions | Define which adapters may read, edit, execute commands, use browsers, call MCP tools, or access external systems. |
+| Repository access | Use `devspec/foundation/codebase-structure.md` as the source of truth for `reference-only`, `edit`, `edit-and-test`, `validation-only`, `release-coordination`, and `unavailable` access. |
+| Secrets | Keep tokens, API keys, provider credentials, and local secrets outside prompt, agent, adapter, and artifact files. |
+| Provider access | Use `devspec/foundation/provider-integrations.md` for supported providers, accepted formats, lookup behavior, manual fallback, and access expectations. |
+| Audit evidence | Store decisions, readiness, tasks, implementation checkpoints, validation, and review outcomes in Git-tracked `devspec` artifacts. |
+| Security work | Follow security-vulnerability handling rules from `devspec/foundation/rules.md` and avoid recording unsafe exploit detail unless explicitly approved. |
+| Human approval | Require structured confirmation where the canonical prompt or agent contract requires it, especially provider resolution, repository access, constitution changes, and continuation after blockers. |
+| Gemini CLI posture | Use trusted folders, sandboxing, `.geminiignore`, enterprise settings, and telemetry policy where available; keep Gemini extensions and MCP configuration outside prompt artifacts unless intentionally packaged. |
+| Antigravity posture | Prefer strict mode or request-review settings for terminal commands, browser actions, MCP calls, non-workspace file access, and artifact application; keep projects scoped to recorded repositories. |
+
+## Enterprise Rollout Gates
+
+| Gate | Required evidence |
+| --- | --- |
+| Copilot baseline confirmed | Existing `.github/prompts` and `.github/agents` files remain unchanged in intent and still register the expected workflow in VS Code. |
+| Adapter conformance confirmed | Each adapter maps to `devspec/adapters/command-registry.md` and records platform gaps in `devspec/adapters/compatibility-matrix.md`. |
+| New repository flow passed | The new repository flow in `devspec/adapters/validation-flows.md` passes for the adapter. |
+| Existing repository flow passed | The existing repository flow in `devspec/adapters/validation-flows.md` passes for the adapter. |
+| Story flow passed | One feature, bug, or security work item completes intake through review. |
+| Cross-tool recovery passed | A flow paused in one adapter resumes in another using only Git-tracked artifacts. |
+
+## Operating Principles
+
+- Keep the repository, not the AI session, as the durable source of truth.
+- Prefer small, reviewable adapter changes over broad prompt rewrites.
+- Add new adapters by mapping to the registry first, then validating with flow checklists.
+- Treat compliance, security, production access, and external provider writes as explicit governance decisions.

devspec_installer/payload/devspec/adapters/gemini-cli.md

@@ -0,0 +1,54 @@
+# Gemini CLI Adapter
+
+Gemini CLI support is implemented through root `GEMINI.md` plus project custom commands under `.gemini/commands/devspec/`.
+
+## Invocation Model
+
+| Devspec 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` |
+
+Gemini uses colon namespacing for project commands. Keep canonical dotted `/devspec.*` names in documentation and artifacts.
+
+## Adapter Rules
+
+- `GEMINI.md` imports `AGENTS.md` and adds only Gemini-specific guidance.
+- Each TOML command is a thin wrapper around `devspec/adapters/command-registry.md`.
+- Each TOML command names the matching Copilot prompt and agent files as the source of intent.
+- Gemini CLI command arguments are passed through the native custom-command argument behavior.
+- Do not use Gemini shell injection in devspec command wrappers; let the agent read files through normal tool access and approvals.
+
+## Enterprise Safety
+
+| Area | Guidance |
+| --- | --- |
+| Context hierarchy | Root `GEMINI.md` is the repository context file. Global `~/.gemini/GEMINI.md` may exist, but repository workflow rules should remain here. |
+| Custom commands | Project commands live in `.gemini/commands/devspec/` and should be version-controlled with the framework. |
+| Extensions | Gemini extensions can package prompts, MCP servers, and commands, but this repository ships project commands first for reviewability. |
+| Enterprise configuration | Organization-wide Gemini CLI settings should enforce approved auth, tool access, and MCP policy outside prompt artifacts. |
+| Sandboxing | Prefer sandboxing or command approval for validation and implementation workflows, especially outside trusted folders. |
+| Telemetry | Use Gemini CLI telemetry only when configured by the environment; otherwise record token or telemetry data as unavailable. |
+| Trusted folders | Treat repository trust as a prerequisite before allowing write or execute workflows. |
+| Ignore rules | Use `.geminiignore` in consuming repositories when generated files, secrets, or large local folders need exclusion. |
+
+## Known Gaps
+
+- Gemini CLI custom commands use `/devspec:story` style names, not exact `/devspec.story` names.
+- Copilot prompt files do not automatically register as Gemini commands.
+- Exact permission, sandbox, and telemetry behavior depends on the user's Gemini CLI configuration.
+
+## Validation
+
+Run the new repository, existing repository, story, and cross-tool recovery flows in `devspec/adapters/validation-flows.md` with Gemini CLI before treating the adapter as enterprise-ready.

devspec_installer/payload/devspec/adapters/validation-flows.md

@@ -0,0 +1,90 @@
+# Enterprise Validation Flows
+
+Use these flows as release gates for multi-agent support. Run them per adapter before declaring the adapter enterprise-ready.
+
+## New Repository Flow
+
+Validate the foundation path for a repository with little or no implementation code.
+
+| Step | Command | Expected evidence |
+| --- | --- | --- |
+| 1 | `/devspec.projectcontext` | `devspec/foundation/project-context.md` captures product purpose, users, outcomes, scope boundaries, sources, confidence, and developer implications. |
+| 2 | `/devspec.techstack` | `devspec/foundation/tech-stack.md` captures stack choices, support status, hosting or tooling constraints, sources, and confidence. |
+| 3 | `/devspec.codebase-structure` | `devspec/foundation/codebase-structure.md` captures planned or existing layout, work areas, integration boundaries, and repository access expectations. |
+| 4 | `/devspec.coding-standards` | `devspec/foundation/coding-standards.md` captures implementation standards, testing expectations, observed or selected patterns, and blockers. |
+| 5 | `/devspec.rules` | `devspec/foundation/rules.md` captures operational rules, compliance requirements, delivery gates, and work-item handling rules. |
+
+Acceptance checklist:
+
+- No extraction step is required.
+- Every generated artifact uses its live foundation file, not the `_template` file as the final output.
+- Every command records blockers or confidence gaps instead of guessing.
+- The next recommended action follows `devspec/adapters/command-registry.md`.
+
+## Existing Repository Flow
+
+Validate the foundation path for a repository or multi-repo system that already contains implementation evidence.
+
+| Step | Command | Expected evidence |
+| --- | --- | --- |
+| 1 | `/devspec.extract` | `devspec/foundation/extraction-state.md`, `devspec/architecture/overview.md`, `devspec/architecture/artifact-queue.md`, and live foundation artifacts are seeded from evidence. |
+| 2 | `/devspec.projectcontext` | Product context is refined with human business context that code cannot fully prove. |
+| 3 | `/devspec.techstack` | Extracted stack evidence is confirmed or corrected. |
+| 4 | `/devspec.codebase-structure` | Repository layout, work areas, multi-repo access, and boundaries are confirmed. |
+| 5 | `/devspec.coding-standards` | Evidence-backed coding standards and anti-patterns are confirmed. |
+| 6 | `/devspec.rules` | Operational and compliance rules are confirmed or added. |
+
+Acceptance checklist:
+
+- Discovery exclusions from `devspec/foundation/discovery-exclusions.md` are respected.
+- Extraction does not rewrite `devspec/constitution.md` principles from code inference without confirmation.
+- Missing evidence, access issues, and unresolved provider lookup paths are recorded as blockers.
+- Extracted facts are placed in their target artifacts, not left only in extraction notes.
+
+## End-To-End Story Flow
+
+Validate one full feature, bug, or security-vulnerability lifecycle after the foundation exists.
+
+| Step | Command | Expected evidence |
+| --- | --- | --- |
+| 1 | `/devspec.story` | `meta.md`, `story.md`, `decisions.md`, and `notes.md` exist under one valid work-item folder. |
+| 2 | `/devspec.clarify` when blocked | `clarify.md` records the active question, answer, resolution, and remaining blockers. |
+| 3 | `/devspec.finalize` | `finalize.md` records readiness, implementation brief, validation plan, assumptions, and blockers. |
+| 4 | `/devspec.tasks` | `tasks.md` records executable tasks with repository, target area, validation, done criteria, dependencies, and status. |
+| 5 | `/devspec.implement` | `implement.md` records repository access checks, task ledger, attempts, changed files or areas, validation results, blockers, and resume state. |
+| 6 | `/devspec.review` | `review.md` records findings, scope adherence, validation gaps, rule violations, and review status. |
+
+Acceptance checklist:
+
+- Work-item state uses values from `devspec/glossary.md`.
+- `finalize.md` must be `ready` before `/devspec.tasks` plans implementation tasks.
+- `/devspec.tasks` does not expand scope beyond the finalized brief.
+- `/devspec.implement` respects repository access requirements from `devspec/foundation/codebase-structure.md`.
+- `/devspec.review` reviews against the finalized brief instead of re-planning.
+
+## Cross-Tool Recovery Scenario
+
+Use this scenario to prove the framework is tool-neutral.
+
+1. Start the new repository flow, existing repository flow, or story flow in one supported adapter.
+2. Stop after a command writes a `Resume State` or workflow checkpoint.
+3. Open the same repository in another supported adapter.
+4. Ask the adapter to continue the same registered command or next handoff.
+5. Confirm it reads Git-tracked `devspec` artifacts first and continues from the recorded checkpoint.
+
+Acceptance checklist:
+
+- The second adapter does not rely on the first adapter's chat history.
+- The second adapter preserves pending questions, blockers, current task, and next action.
+- Any unsupported platform feature is recorded as a limitation, not converted into a workflow change.
+
+## Adapter Wrapper Checks
+
+Run these checks before enterprise release:
+
+| Adapter | Required wrapper evidence |
+| --- | --- |
+| Gemini CLI | Root `GEMINI.md` exists; `.gemini/commands/devspec/*.toml` has one wrapper for each registered command; native command names map `/devspec.story` to `/devspec:story` style names. |
+| Google Antigravity | `.agents/rules/devspec-workflow.md` exists; `.agents/skills/devspec-*.md` has one wrapper for each registered command; native skill names map `/devspec.story` to `/devspec-story` style names. |
+
+Each wrapper must reference `devspec/adapters/command-registry.md` and the matching canonical Copilot prompt and agent files.

devspec_installer/payload/devspec/architecture/_template/artifact-queue.md

@@ -0,0 +1,27 @@
+# Architecture Diagram Queue
+
+Use this file as the resumable queue register for proposed and generated architecture diagrams. Keep generated diagram content in the target artifact; keep only queue metadata, evidence, confidence, status, and next action or notes here.
+
+Store high-level diagrams in `devspec/architecture/overview.md`, durable detailed diagrams in `devspec/architecture/diagrams/dia-NNN-<diagram-name>.md`, and temporary work-item diagrams in `devspec/work-items/<work-item-folder>/diagrams.md`.
+
+## Diagram Queue Register
+
+Add rows only when extraction or `/devspec.diagram` identifies real diagram candidates backed by evidence. Keep one row per diagram subject and update the existing row instead of creating duplicates.
+
+| ID | Scope | Diagram type | Subject | Target location | Evidence | Confidence | Status | Tags | Next action or notes |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+
+## Queue Field Definitions
+
+| Field | Guidance |
+| --- | --- |
+| ID | Use stable IDs such as `DIA-001`, preserving existing IDs and assigning the next available number for new rows. |
+| Scope | Use `architecture`, `module`, `feature`, `workflow`, `user-journey`, or `work-item`. Prefer durable scopes over `work-item` unless the diagram is explicitly temporary or work-item-specific. |
+| Diagram type | Use the Mermaid family only: `flowchart`, `sequenceDiagram`, `journey`, `stateDiagram`, `classDiagram`, or `erDiagram`. Do not include orientation here. |
+| Subject | Use a specific lowercase kebab-case subject that can map to one diagram file or one overview section. For queued architecture diagrams, prefix the subject with the lowercase queue ID, such as `dia-001-order-fulfillment-flow`. |
+| Target location | Use `devspec/architecture/overview.md#diagram-reference-index` for high-level overview diagrams, `devspec/architecture/diagrams/dia-NNN-<diagram-name>.md` for durable detailed diagrams, or `devspec/work-items/<work-item-folder>/diagrams.md#diagram-content` for temporary work-item diagrams. |
+| Evidence | Name the source paths, docs, ADRs, queue request, or user-confirmed basis supporting the candidate. |
+| Confidence | Use `observed` for direct evidence, `high-confidence` for inference from multiple local evidence points, or `low-confidence` when useful but incomplete evidence needs assumptions before generation. |
+| Status | Use `devspec/glossary.md#artifact-status-values`; queue status belongs here, not in diagram indexes or generated diagram content. |
+| Tags | Use comma-separated lowercase tags such as `process-flow`, `business-process`, `user-journey`, `lifecycle-flow`, or `hybrid-user-to-data-operational-flow` when they apply. Leave blank only when no durable selection tag is useful. |
+| Next action or notes | Record duplicate-check result, suggested Mermaid declaration such as `flowchart LR` or `sequenceDiagram`, assumptions, blocker details, skip reason, or the next action needed. |

devspec_installer/payload/devspec/architecture/_template/decision.md

@@ -0,0 +1,45 @@
+# Architecture Decision
+
+Use this artifact for one durable architecture decision that affects multiple work items, long-lived system structure, integration boundaries, technology direction, or operational architecture. Create ADR files under `devspec/architecture/decisions/` only when the user explicitly asks or the decision has clear supporting evidence and needs durable cross-work-item tracking.
+
+## Decision Metadata
+
+| Field | Value |
+| --- | --- |
+| ID | ADR-0000 |
+| Title | |
+| Status | proposed, accepted, superseded |
+| Date | |
+| Decision owner | |
+| Supersedes | ADR ID or none |
+
+## Decision Context
+
+Use this section for the problem, forces, constraints, and alternatives that explain why a durable architecture decision is needed. Keep implementation task details in work-item artifacts.
+
+| Context item | Details | Evidence |
+| --- | --- | --- |
+| Problem or driver |  |  |
+| Constraints or forces |  |  |
+| Alternatives considered |  |  |
+
+## Decision Outcome
+
+| Field | Value |
+| --- | --- |
+| Decision statement | |
+| Scope | |
+| Rationale | |
+
+## Impact and References
+
+Use this section for the decision effects and durable links that future agents or developers must preserve. Link related work-item decisions instead of duplicating them here.
+
+| Type | Item | Required handling or relationship |
+| --- | --- | --- |
+| positive consequence |  |  |
+| trade-off |  |  |
+| risk |  |  |
+| related work item |  |  |
+| related architecture artifact |  |  |
+| source evidence |  |  |

devspec_installer/payload/devspec/architecture/_template/diagram.md

@@ -0,0 +1,62 @@
+# Architecture Diagram
+
+Use this artifact for one durable architecture, module, feature, workflow, process-flow, user journey, sequence, state, or domain diagram. Keep diagram status in `devspec/architecture/artifact-queue.md`; keep only generated content, supporting evidence, assumptions, and maintenance notes here.
+
+## Resume State
+
+| Field | Value |
+| --- | --- |
+| Current stage | diagram |
+| Current command | `/devspec.diagram` |
+| Current agent | devspec.diagram |
+| Run status | See `devspec/glossary.md#run-status-values` |
+| Current item | |
+| Last completed step | |
+| Next required action | |
+| Pending user question | |
+| Recommended option | |
+| Resume command | `/devspec.diagram` |
+| Resume notes | |
+| Updated | |
+
+## Diagram Metadata
+
+| Field | Value |
+| --- | --- |
+| ID | |
+| Display title | `DIA-NNN - <Title Case Diagram Name>` |
+| Scope | architecture, module, feature, workflow, user-journey |
+| Diagram type | flowchart, sequenceDiagram, journey, stateDiagram, classDiagram, erDiagram |
+| Mermaid declaration | flowchart TD, flowchart LR, flowchart BT, sequenceDiagram, journey, stateDiagram-v2, classDiagram, erDiagram |
+| Subject | `dia-NNN-<diagram-name>` |
+| Confidence | observed, high-confidence, low-confidence |
+| Tags | |
+| Queue row | `devspec/architecture/artifact-queue.md#diagram-queue-register` |
+
+## Mermaid Diagram
+
+- Keep durable `DIA-*` IDs and `dia-NNN-*` subjects in metadata and filenames only; Mermaid content uses simple internal naming.
+- Use short alphanumeric node IDs, double-quoted node labels of 1-4 words, and 2-3 word edge labels. Do not use `\n` or `<br>` inside node labels or edge labels.
+- Keep architectural flowcharts focused on one primary domain at macro level, structurally unidirectional, and adjacent by layer. Do not include overloaded graphs, cross-layer arrows, decision diamonds, UI micro-interactions, or return/error paths unless the diagram is explicitly an algorithm or activity flowchart.
+- Use `sequenceDiagram` for exact step-by-step request and response behavior. Sequence diagrams should show happy-path messages between distinct participants, collapse pass-through API client helpers, and use method names for message labels.
+- Keep runtime communication and compile-time project dependencies in separate diagrams. Logical architecture diagrams exclude SDLC actors and build artifacts, and keep owned application databases inside the system boundary.
+- Avoid API, Swagger, tech stack, version, library, hosting, and framework boilerplate details in flowchart nodes unless the diagram is specifically about startup, request-pipeline, infrastructure-layer, or physical deployment behavior.
+
+```mermaid
+flowchart TD
+```
+
+## Source Evidence and Assumptions
+
+Use `evidence` for directly supported code, docs, config, ADRs, or user-confirmed facts. Use `assumption` only when the diagram depends on an inference that is not fully confirmed.
+
+| Type | Source or assumption | Diagram impact | Resolution |
+| --- | --- | --- | --- |
+| evidence |  |  | confirmed |
+| assumption |  |  | open |
+
+## Maintenance Notes
+
+| Note | Action or owner | Resolution state |
+| --- | --- | --- |
+|  |  | open |