devspec 0.1.0__py3-none-any.whl

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

@@ -0,0 +1,37 @@
+# Architecture Overview
+
+Use this artifact for confirmed high-level architecture context, durable diagram references, ADR pointers, and unresolved architecture gaps. Keep detailed repository layout in `devspec/foundation/codebase-structure.md`, integration contracts in `devspec/foundation/codebase-structure.md#integration-contracts`, diagram queue state in `devspec/architecture/artifact-queue.md`, and full ADR content in ADR files created under `devspec/architecture/decisions/` when needed.
+
+## Architecture Context
+
+Use this section for confirmed architecture facts that affect system understanding across major components, integration relationships, runtime boundaries, and important data movement. Keep implementation file placement in `devspec/foundation/codebase-structure.md#work-areas-and-boundaries` and detailed contracts in `devspec/foundation/codebase-structure.md#integration-contracts`.
+
+| Context type | Subject | Summary | Source | Confidence | Developer relevance |
+| --- | --- | --- | --- | --- | --- |
+| component |  |  |  |  |  |
+| integration |  |  |  |  |  |
+| data-flow |  |  |  |  |  |
+
+## Diagram Reference Index
+
+Use this section for confirmed high-level diagrams in this file and links to durable detailed diagrams. Do not mirror queue status here; track proposed, confirmed, generated, skipped, or blocked diagram work in `devspec/architecture/artifact-queue.md`.
+
+| ID | Scope | Diagram type | Subject | Link or section | Usage notes |
+| --- | --- | --- | --- | --- | --- |
+|  | architecture, module, feature, workflow, user-journey | flowchart, sequenceDiagram, journey, stateDiagram, classDiagram, erDiagram |  | `devspec/architecture/diagrams/dia-NNN-<diagram-name>.md` or section anchor |  |
+
+## Decision Reference Index
+
+Use this section only for pointers to durable ADRs or confirmed architecture decisions. Keep metadata, context, outcome, impact, and references in the ADR file.
+
+| Decision | Reference | Architecture relevance |
+| --- | --- | --- |
+|  | `devspec/architecture/decisions/<adr-file>.md` |  |
+
+## Architecture Gaps and Blockers
+
+Use this section only for missing or conflicting architecture facts that prevent reliable planning, diagram generation, or architecture decision recording. Keep implementation blockers in work-item artifacts.
+
+| Gap or blocker | Impact | Required resolution | Resolution state |
+| --- | --- | --- | --- |
+|  |  |  | open |

devspec_installer/payload/devspec/architecture/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/diagrams/README.md

@@ -0,0 +1,44 @@
+# Architecture Diagrams
+
+Use this folder for durable Mermaid diagrams that are more specific than the high-level architecture context in `devspec/architecture/overview.md`.
+
+Store module, feature workflow, process-flow, user journey, sequence, state, class/domain, and cross-feature diagrams as one Markdown file per subject. Track proposed, generated, skipped, or blocked diagram work with evidence, confidence, and tags in `devspec/architecture/artifact-queue.md`.
+
+## File and Queue Naming
+
+Use Title Case for diagram display names and lowercase sequence-prefixed kebab-case for subject slugs and filenames. Queue ID `DIA-001` maps to subject and file prefix `dia-001-`; for example, `DIA-001 - Order Fulfillment Flow` uses `devspec/architecture/diagrams/dia-001-order-fulfillment-flow.md`. Existing `DIA-*` numbers and `dia-NNN-*` files must not be renumbered.
+
+Keep default subjects language-neutral after the sequence prefix, such as `dia-NNN-system-context`, `dia-NNN-runtime-containers`, `dia-NNN-dependency-graph`, or `dia-NNN-authentication-authorization-flow`. Use `dia-NNN-hybrid-user-to-data-operational-flow` for the durable hybrid flow that connects user entry points, application boundaries, services, data stores, validations, operational states, and outcomes.
+
+Queue `Diagram type` records the Mermaid family only. The generated diagram artifact records the full Mermaid declaration, such as `flowchart LR`, `flowchart TD`, `sequenceDiagram`, `stateDiagram-v2`, or `erDiagram`.
+
+`DIA-*` IDs, `dia-NNN-*` subjects, and `dia-NNN-*` filenames are durable diagram file and diagram queue naming conventions. They must not leak into Mermaid internal naming unless they are part of metadata outside the diagram block.
+
+## Mermaid Readability
+
+- Use simple internal names: short alphanumeric node IDs such as `AuthCtrl` or `ProviderSvc`, double-quoted node labels of 1-4 words such as `AuthCtrl["Authentication Controller"]`, and 2-3 word edge labels such as `-->|"API Calls"|`.
+- Put interaction context on edge labels, not inside node labels.
+- Do not use `\n` or `<br>` line breaks inside node labels or edge labels.
+
+## Flowchart Scope
+
+- Keep architectural flowcharts and graphs structurally unidirectional and adjacent by layer.
+- Map dependency or invocation direction, such as UI -> API -> service -> repository -> database.
+- Avoid cross-layer arrows that skip layers.
+- Treat return paths as implied by downward invocation arrows.
+- Keep each architectural flowchart focused on one primary business domain at macro level, not overloaded graphs or component internals.
+- Do not use decision diamonds, if/else paths, validation loops, error branches, UI micro-interactions, HTTP return codes, validation exceptions, or database error returns unless the user explicitly requests an algorithm or activity flowchart.
+
+## Sequence and Boundary Guidance
+
+- Use `sequenceDiagram` when exact step-by-step request and response behavior is required.
+- Show messages between distinct participants only.
+- Default to the happy path, omit generic error `alt` or `opt` blocks unless requested, collapse pass-through API client helpers, and use method names such as `AuthenticateAsync(req)` for message labels.
+- Keep runtime communication and compile-time project dependencies in separate diagrams; default to runtime or logical data flow unless the user explicitly requests a project dependency graph.
+- Logical architecture diagrams must include only actual end users, client applications, runtime components, data stores, and external systems that interact with the live application.
+- Exclude developers, maintainers, Git, CI/CD, deployment pipelines, build artifacts, and source-code project files unless the diagram is specifically about SDLC, build, deployment, or static project dependencies.
+- Place databases owned and exclusively used by the application inside the system boundary.
+
+## Detail to Avoid
+
+Avoid API, tech stack, and framework bloat in generated Mermaid content. Do not put HTTP verbs, route templates, status codes, DTO or payload names, Swagger details, framework versions, specific library names, hosting models, or standard framework wiring into flowchart nodes unless the requested diagram is specifically about startup, request-pipeline, infrastructure-layer, or physical deployment behavior.

devspec_installer/payload/devspec/architecture/overview.md

@@ -0,0 +1,37 @@
+# Architecture Overview
+
+Use this artifact for confirmed high-level architecture context, durable diagram references, ADR pointers, and unresolved architecture gaps. Keep detailed repository layout in `devspec/foundation/codebase-structure.md`, integration contracts in `devspec/foundation/codebase-structure.md#integration-contracts`, diagram queue state in `devspec/architecture/artifact-queue.md`, and full ADR content in ADR files created under `devspec/architecture/decisions/` when needed.
+
+## Architecture Context
+
+Use this section for confirmed architecture facts that affect system understanding across major components, integration relationships, runtime boundaries, and important data movement. Keep implementation file placement in `devspec/foundation/codebase-structure.md#work-areas-and-boundaries` and detailed contracts in `devspec/foundation/codebase-structure.md#integration-contracts`.
+
+| Context type | Subject | Summary | Source | Confidence | Developer relevance |
+| --- | --- | --- | --- | --- | --- |
+| component |  |  |  |  |  |
+| integration |  |  |  |  |  |
+| data-flow |  |  |  |  |  |
+
+## Diagram Reference Index
+
+Use this section for confirmed high-level diagrams in this file and links to durable detailed diagrams. Do not mirror queue status here; track proposed, confirmed, generated, skipped, or blocked diagram work in `devspec/architecture/artifact-queue.md`.
+
+| ID | Scope | Diagram type | Subject | Link or section | Usage notes |
+| --- | --- | --- | --- | --- | --- |
+|  | architecture, module, feature, workflow, user-journey | flowchart, sequenceDiagram, journey, stateDiagram, classDiagram, erDiagram |  | `devspec/architecture/diagrams/dia-NNN-<diagram-name>.md` or section anchor |  |
+
+## Decision Reference Index
+
+Use this section only for pointers to durable ADRs or confirmed architecture decisions. Keep metadata, context, outcome, impact, and references in the ADR file.
+
+| Decision | Reference | Architecture relevance |
+| --- | --- | --- |
+|  | `devspec/architecture/decisions/<adr-file>.md` |  |
+
+## Architecture Gaps and Blockers
+
+Use this section only for missing or conflicting architecture facts that prevent reliable planning, diagram generation, or architecture decision recording. Keep implementation blockers in work-item artifacts.
+
+| Gap or blocker | Impact | Required resolution | Resolution state |
+| --- | --- | --- | --- |
+|  |  |  | open |

devspec_installer/payload/devspec/constitution.md

@@ -0,0 +1,26 @@
+# Constitution
+
+This file holds enduring principles that apply across work items and agents. Use it for rare, durable guidance; put operational delivery gates, evolving compliance rules, and enforcement details in `devspec/foundation/rules.md`.
+
+## Durable Principles
+
+| Area | Principle |
+| --- | --- |
+| Engineering | Prefer simple solutions over speculative abstractions. |
+| Engineering | Favor readable, maintainable code over cleverness. |
+| Delivery | Keep requirements, implementation, and validation aligned. |
+| Delivery | Changes must stay within approved scope. |
+| Delivery | Significant scope changes must return to an earlier devspec stage. |
+| Validation | Validation is required before work is considered complete. |
+| Validation | New behavior should have corresponding validation. |
+| Validation | Regressions should be captured in tests when practical. |
+| Security and compliance | Do not weaken security controls without explicit approval. |
+| Security and compliance | Handle sensitive data according to project and organizational rules. |
+
+## Amendment Policy
+
+| Rule | Requirement |
+| --- | --- |
+| Change threshold | Update this file only for durable principles that rarely change. |
+| Confirmation | Principle-level changes require explicit confirmation before writing. |
+| Operational rules | Put operational delivery gates and evolving compliance rules in `devspec/foundation/rules.md`. |

devspec_installer/payload/devspec/foundation/_template/codebase-structure.md

@@ -0,0 +1,64 @@
+# Codebase Structure
+
+Use this artifact to help developers and agents decide where work belongs, which repositories are usable, and which boundaries must be preserved. Keep repository trees selective and keep optional tables only when they contain real project facts or unresolved blockers.
+
+## Repository Layouts
+
+Use this section for selective repository trees, up to a maximum of 4-5 levels, that help agents decide where to create, edit, or inspect files. Include important source roots, feature or module folders, tests, scripts, config, infrastructure, docs, and routing-critical files when relevant. Do not list every file. When deeper detail is needed for placement, capture the specific path or rule in `Work Areas and Boundaries` instead of expanding the tree. Omit paths excluded by `devspec/foundation/discovery-exclusions.md` unless a project override marks them source-owned.
+
+Use one `### Repository: <repository-name>` subsection per repository when multiple repositories participate.
+
+### Repository: <repository-name>
+
+```text
+<repository-name>/
+|-- <source-root>/
+|   |-- <feature-or-module>/
+|   |   |-- <components-or-handlers>/
+|   |   `-- <services-or-utils>/
+|-- <tests>/
+|   |-- <unit-or-integration>/
+|   `-- <e2e>/
+|-- <scripts-or-tools>/
+|-- <config-or-infra>/
+|-- <docs>/
+`-- <routing-or-package-file>
+```
+
+## Repository Configuration
+
+Use this section only when multiple repositories participate in delivery, or when a non-default repository path or access limit affects work. Do not omit it for multi-repo sources or dependencies; record missing role, workspace, path, or access facts as blockers instead of dropping the section.
+
+Rows may be seeded from named `/devspec.extract` input such as `UI - D:\repo-ui, API - D:\repo-api`. Use the supplied label as the initial repository name and role candidate, then refine it with evidence or user confirmation.
+
+| Repository | Role | Local path | In current workspace | Access requirement | Evidence | Confidence | Work guidance |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| <repository-name> | <delivery-role> | <local-path-or-unknown> | yes, no, unknown | See `devspec/glossary.md#access-requirement-values` | <input-or-source> | confirmed, observed, inferred, blocked | <how work should use-or-avoid-this-repository> |
+
+Do not infer access from repository location. For missing or ambiguous access requirements, ask the user to confirm one value from `devspec/glossary.md#access-requirement-values` before relying on the row.
+
+## Work Areas and Boundaries
+
+Use this section for internal file-placement decisions: modules, bounded contexts, layers, shared packages, ownership or review routing, and cross-cutting code placement. Put a fact here only when it tells future work where code belongs, who owns it, what must not cross a boundary, or how related code should be grouped. Put external service, API, event, database, or cross-repo contracts in `Integration Contracts` instead.
+
+Common area types include `module`, `feature`, `layer`, `service`, `shared-package`, `cross-cutting`, and `ownership`.
+
+| Scope | Area | Area type | Responsibility | Key paths | Boundary or placement rule | Owner or reviewer | Evidence | Confidence | Work guidance |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| repository:<repository-name> | <area-name> | <area-type> | <primary-responsibility> | <path-or-pattern> | <allowed-dependencies-placement-or-review-rule> | <owner-team-reviewer-or-unknown> | <source-path-or-input> | confirmed, observed, inferred, blocked | <what future work should do> |
+
+## Integration Contracts
+
+Use this section for boundaries between repositories, modules, services, users, data stores, queues, APIs, providers, or external systems. A row belongs here when future work must preserve a protocol, data shape, dependency direction, lifecycle, or validation expectation.
+
+| Source scope | Target or system | Contract or interface | Direction | Data or protocol | Required handling | Evidence | Confidence |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| repository:<repository-name> | <target-system> | <api-event-db-package-or-user-contract> | inbound, outbound, bidirectional | <data-shape-or-protocol> | <what to preserve-or-validate> | <source-path-or-input> | confirmed, observed, inferred, blocked |
+
+## Structure Gaps and Blockers
+
+Use this section only for missing or conflicting facts that prevent reliable repository selection, file placement, access validation, ownership routing, or integration handling. Do not duplicate normal open risks from work-item artifacts.
+
+| Gap or blocker | Affected section | Impact | Required resolution | Status |
+| --- | --- | --- | --- | --- |
+| <missing-or-conflicting-fact> | Repository Configuration, Work Areas and Boundaries, Integration Contracts, or Repository Layouts | <why agents cannot proceed safely> | <question-evidence-or-access-needed> | open |

devspec_installer/payload/devspec/foundation/_template/coding-standards.md

@@ -0,0 +1,46 @@
+# Coding Standards
+
+Use this artifact as a compact, evidence-backed catalog for how developers should write, test, document, and review code. Prefer source references and short rules over copied prose. Omit optional rows or sections with no real standards or evidence.
+
+## Standards Evidence Sources
+
+Use this section only for source documents, configuration files, or representative code that support one or more catalog rows. Do not infer coding standards from paths excluded by `devspec/foundation/discovery-exclusions.md`, such as installed dependencies or generated output.
+
+| Source | Source type | Applies to | Confidence | Notes |
+| --- | --- | --- | --- | --- |
+| <path-or-link> | formatter, linter, standards-doc, config, source-sample, user-input | <language-framework-layer-or-area> | confirmed, observed, inferred, blocked | <why-this-source-matters> |
+
+## Standards Catalog
+
+Use this as the single place for language, framework, testing, error-handling, logging, documentation, review, observed-pattern, and anti-pattern guidance. Add a row only when the rule changes how developers should write or review code. Keep examples as references to `Standards Examples`, not long snippets in this table.
+
+Use `Type` values as follows:
+- `rule`: explicit standard from a project source, user instruction, or config.
+- `observed-pattern`: recurring style or structure found in source evidence.
+- `anti-pattern`: forbidden or discouraged pattern with the preferred replacement in `Developer guidance`.
+- `expectation`: cross-cutting review or quality expectation that applies across multiple areas.
+
+| ID | Scope | Category | Type | Developer guidance | Evidence | Confidence | Example |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| CS-001 | <language-framework-layer-or-area> | file-naming, formatting, sql-layout, comments, member-ordering, linting, testing, framework, error-handling, logging, documentation, review | rule, observed-pattern, anti-pattern, expectation | <what-to-do-or-avoid-and-preferred-pattern> | <source-id-path-or-link> | confirmed, observed, inferred, blocked | EX-001 or n/a |
+
+## Standards Examples
+
+Include this section only when a short snippet clarifies a style, indentation, naming, grouping, SQL layout, testing pattern, or framework pattern better than a catalog row alone. Keep examples minimal and canonical, usually 5-20 lines. Link each example to one or more catalog row IDs.
+
+### EX-001: <example-name>
+
+Applies to: CS-001
+Source: `<source-path>`
+
+```text
+<short representative snippet>
+```
+
+## Standards Blockers and Conflicts
+
+Use this section only when standards evidence conflicts, required source evidence is missing, or a project decision is needed before agents can apply a standard.
+
+| Topic | Affected catalog row | Conflict or gap | Evidence | Resolution needed | Status |
+| --- | --- | --- | --- | --- | --- |
+| <topic> | CS-001 or new | <conflict-or-gap> | <source-paths-or-input> | <question-or-decision> | open |

devspec_installer/payload/devspec/foundation/_template/discovery-exclusions.md

@@ -0,0 +1,52 @@
+# Discovery Exclusions
+
+Use this file to keep discovery focused on project-owned source, configuration, tests, scripts, infrastructure, and docs.
+
+Apply exclusions before broad search, extraction, code-pattern discovery, layout mapping, generated helper scripts, and validation discovery. Respect repository ignore files as a baseline while still applying this file. Do not infer coding standards, architecture, ownership, or implementation behavior from installed dependencies, generated output, caches, coverage output, VCS internals, or tool output. Use manifests, lockfiles, framework config, CI config, docs, source roots, tests, and scripts as evidence instead. Omit excluded folders from layout maps unless `Project Overrides` includes them.
+
+Record intentional exceptions in `Project Overrides` before relying on normally excluded paths or adding project-specific exclusions.
+
+## Baseline Exclusions
+
+Use these categories for every repository, regardless of ecosystem. Ecosystem rules below add framework-specific patterns and evidence hints; they do not replace these defaults.
+
+| Category | Exclude by default | Reason | Include only if |
+| --- | --- | --- | --- |
+| VCS internals | `.git/`, `.svn/`, `.hg/` | Version-control metadata is not project source. | User explicitly asks for VCS internals. |
+| Generated or build output | `dist/`, `build/`, `out/`, generated artifacts | Output can be stale, duplicated, minified, or machine-produced. | Output is intentionally source-owned and recorded in `Project Overrides`. |
+| Test and coverage output | `coverage/`, `.nyc_output/`, test result folders | Reports are run artifacts, not source conventions. | User asks for coverage or test-output diagnostics. |
+| Cache and temporary output | `.cache/`, `tmp/`, `temp/`, tool caches | Cache content is transient and often huge. | User asks for cache diagnostics. |
+| Local IDE or machine metadata | `.idea/`, `.vscode/`, editor user settings | Local settings usually reflect one machine, not project standards. | Repository standards explicitly depend on these files. |
+| Dependency installs and package caches | Installed dependency folders and package manager caches | Third-party code and package caches should not drive project conventions. | Dependency source inspection is explicitly requested or overridden. |
+
+## Ecosystem Discovery Rules
+
+Use this table after detecting the ecosystem. Exclusions listed here are ecosystem-specific additions to `Baseline Exclusions`. Preferred evidence sources are safe discovery targets unless a project override says otherwise.
+
+| Ecosystem or framework | Detect from | Additional exclusions | Prefer as evidence |
+| --- | --- | --- | --- |
+| JavaScript and TypeScript, Node.js | `package.json`, lockfiles, `.npmrc`, `.yarnrc*`, `pnpm-workspace.yaml` | `node_modules/`, `.npm/`, `.yarn/cache/`, `.pnpm-store/` | `package.json`, lockfiles, `tsconfig*.json`, scripts, source roots, tests |
+| Angular | `angular.json`, `package.json`, `tsconfig*.json` | `.angular/`, `.nx/` | `angular.json`, `tsconfig*.json`, `src/`, `projects/`, tests |
+| React, Vue, Vite, SvelteKit, Astro, Remix | `package.json`, `vite.config.*`, `vue.config.*`, `svelte.config.*`, `astro.config.*`, `remix.config.*` | `.vite/`, `.svelte-kit/`, `.astro/` | framework config, `src/`, `app/`, `pages/`, `components/`, tests |
+| Next.js and Nuxt | `next.config.*`, `nuxt.config.*`, `package.json` | `.next/`, `.nuxt/`, `.output/`, `.vercel/` | framework config, `app/`, `pages/`, `components/`, `server/`, tests |
+| Nx and Turborepo | `nx.json`, `workspace.json`, `project.json`, `turbo.json`, `pnpm-workspace.yaml` | `.nx/`, `.turbo/` | workspace config, project config, package scripts, source roots |
+| .NET SDK, ASP.NET, Blazor, MAUI | `.sln`, `.csproj`, `.fsproj`, `Directory.Build.*`, `global.json` | `bin/`, `obj/`, `TestResults/`, `artifacts/`, `.vs/` | solution, project files, props, targets, app settings, source and tests |
+| JVM: Java, Kotlin, Spring, Maven, Gradle | `pom.xml`, `build.gradle*`, `settings.gradle*`, `gradle.properties`, `src/main/` | `target/`, `.gradle/`, `.mvn/wrapper/maven-wrapper.jar` | build files, wrapper config, `src/`, resources, tests |
+| Python, Django, Flask, FastAPI, pytest, Poetry, uv | `pyproject.toml`, `requirements*.txt`, `setup.py`, `tox.ini`, `poetry.lock`, `uv.lock`, `manage.py` | `.venv/`, `venv/`, `env/`, `__pycache__/`, `.pytest_cache/`, `.mypy_cache/`, `.ruff_cache/`, `.tox/`, `site-packages/`, `htmlcov/` | project metadata, lockfiles, app packages, source and tests |
+| PHP, Composer, Laravel, Symfony | `composer.json`, `composer.lock`, `artisan`, `symfony.lock` | `vendor/`, `var/cache/`, `var/log/`, `storage/framework/`, `storage/logs/`, `bootstrap/cache/`, `public/build/` | composer files, framework config, `app/`, `src/`, routes, tests |
+| Ruby, Bundler, Rails | `Gemfile`, `Gemfile.lock`, `.ruby-version`, `config/application.rb` | `vendor/bundle/`, `.bundle/`, `tmp/`, `log/`, `public/assets/`, `storage/` | Gemfile, lockfile, `app/`, `config/`, `lib/`, tests |
+| Go | `go.mod`, `go.work` | module cache, generated `vendor/` unless source-owned, `bin/`, `coverage.out` | `go.mod`, `go.sum`, `go.work`, source and tests |
+| Rust | `Cargo.toml`, `Cargo.lock` | `target/`, `tarpaulin-report.html` | manifests, lockfile, `src/`, tests, benches |
+| Android | `settings.gradle*`, `build.gradle*`, `gradle.properties`, `AndroidManifest.xml` | `.gradle/`, `build/`, `app/build/`, `.cxx/`, `captures/` | Gradle files, manifests, `src/`, resources, tests |
+| iOS, SwiftPM, CocoaPods | `Package.swift`, `*.xcodeproj`, `*.xcworkspace`, `Podfile`, `Cartfile` | `DerivedData/`, `Pods/`, `.build/`, `build/`, `xcuserdata/`, `Carthage/Build/` | package manifests, project/workspace files, `Sources/`, `Tests/`, app source |
+| C/C++, CMake, Bazel, Meson, Make | `CMakeLists.txt`, `WORKSPACE`, `MODULE.bazel`, `BUILD.bazel`, `meson.build`, `Makefile` | `cmake-build-*/`, `bazel-*`, `CMakeFiles/`, generated `compile_commands.json` | build files, `src/`, `include/`, `tests/`, toolchain files |
+| Data and ML: notebooks, MLflow, Weights & Biases, checkpoints | `*.ipynb`, `mlflow.yml`, `wandb/`, `requirements*.txt`, `pyproject.toml` | `.ipynb_checkpoints/`, `mlruns/`, `wandb/`, `checkpoints/`, `models/`, `outputs/`, `runs/`, `lightning_logs/` unless source-owned | notebooks, experiment config, requirements, source modules, tests, docs |
+| Infrastructure as code: Terraform, Terragrunt, Pulumi, CDK, Serverless, Helm, Kustomize | `*.tf`, `.terraform.lock.hcl`, `terragrunt.hcl`, `Pulumi.yaml`, `cdk.json`, `serverless.yml`, `Chart.yaml`, `kustomization.yaml` | `.terraform/`, `.terragrunt-cache/`, `cdk.out/`, `.serverless/`, `.pulumi/`, `tfplan`, `crash.log`, packaged `*.tgz` charts | IaC source, lockfiles, modules, manifests, environment config, docs |
+
+## Project Overrides
+
+Use this table only when a project intentionally owns a normally excluded path or needs an additional exclusion. Overrides must be specific enough that future agents know whether to include the path for evidence, exclude it from broad discovery, or inspect it only for a named purpose.
+
+| Scope | Pattern | Action | Purpose | Confirmed by |
+| --- | --- | --- | --- | --- |
+| <repository-or-area> | <path-or-glob> | include, exclude, include-for-purpose | <why-this-exception-exists> | <user-source-or-date> |

devspec_installer/payload/devspec/foundation/_template/exploration-state.md

@@ -0,0 +1,15 @@
+# Exploration State
+
+Use this file to avoid repeating failed searches, generated scripts, helper commands, provider lookups, validation discovery paths, and repair probes. Record only reusable exploration results, not every search or one-off file read.
+
+Apply `devspec/foundation/discovery-exclusions.md` before recording or reusing exploration methods.
+
+Keep entries concise and evidence-based. Scope must be specific enough to prevent false matches, such as a repository path, provider name, work item, module, technology, or source URL. Goal must describe the exploration task, such as repository extraction, provider resolution, dependency mapping, implementation repair, version lookup, or validation discovery. Remove or update stale entries when the environment changes.
+
+## Method Ledger
+
+Use this as the single recovery view for reusable exploration methods. Prefer `working` methods first when scope, goal, and assumptions still match. Skip `failed` methods unless the retry condition is met, the user gives new direction, or the method materially changes. Use `superseded` when a better working method replaces an older entry.
+
+| Scope | Goal | Method | Outcome | Evidence or failure reason | Retry or reuse condition | Last verified | Notes |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| <repository-provider-work-item-module-or-technology> | <repository-extraction-provider-resolution-dependency-mapping-repair-version-lookup-or-validation-discovery> | <search-command-provider-tool-or-process> | working, failed, superseded | <why-it-worked-or-failed> | <when-to-reuse-or-retry> | <date-or-unknown> | <brief-context> |

devspec_installer/payload/devspec/foundation/_template/extraction-state.md

@@ -0,0 +1,45 @@
+# Extraction State
+
+Use this artifact only for the `/devspec.extract` queue, resume state, blockers, and confirmations. Keep extracted facts in target artifacts, reusable discovery methods in `devspec/foundation/exploration-state.md`, and diagram queue state in `devspec/architecture/artifact-queue.md`.
+
+## Resume State
+
+| Field | Value |
+| --- | --- |
+| Current stage | extract |
+| Current command | `/devspec.extract` |
+| Current agent | devspec.extract |
+| Run status | See `devspec/glossary.md#run-status-values` |
+| Current task | |
+| Last completed step | |
+| Next required action | |
+| Pending user question | |
+| Recommended option | |
+| Resume command | `/devspec.extract` |
+| Resume notes | |
+| Updated | |
+
+## Extraction Queue
+
+Use status values from `devspec/glossary.md#task-status-values`; keep exactly one row `active` while extraction is running.
+
+| ID | Stage | Target artifact | Evidence focus | Status | Next action | Notes |
+| --- | --- | --- | --- | --- | --- | --- |
+| EXT-001 | source-and-access | `devspec/foundation/extraction-state.md` | source input, source labels, source validation, access requirements | pending | Validate sources and required access. | |
+| EXT-002 | discovery-preparation | `devspec/foundation/discovery-exclusions.md` | exclusion rules, ignore files, reusable discovery methods | pending | Apply discovery rules before broad search. | |
+| EXT-003 | project-context | `devspec/foundation/project-context.md` | documentation, README files, product signals, user-facing behavior | pending | Extract evidence-backed project context. | |
+| EXT-004 | technology-stack | `devspec/foundation/tech-stack.md` | manifests, lockfiles, runtime configuration, tooling, CI/CD | pending | Extract stack and version evidence. | |
+| EXT-005 | codebase-structure | `devspec/foundation/codebase-structure.md` | layout, modules, work areas, boundaries, integration contracts, multi-repo configuration | pending | Extract placement and boundary guidance. | |
+| EXT-006 | coding-standards | `devspec/foundation/coding-standards.md` | style guides, observed patterns, tests, examples | pending | Extract standards and anti-patterns. | |
+| EXT-007 | rules-and-constraints | `devspec/foundation/rules.md` | compliance, security, delivery gates, operational constraints | pending | Extract actionable rules only. | |
+| EXT-008 | architecture-overview | `devspec/architecture/overview.md` | components, integrations, runtime boundaries, data movement | pending | Extract high-level architecture context. | |
+| EXT-009 | process-flows | `devspec/architecture/artifact-queue.md` | business-centric end-to-end workflows, user journeys, lifecycle flows, cross-service process sequences, hybrid user-to-data operational flow | pending | Queue eligible process-flow diagram candidates. | |
+| EXT-010 | diagram-candidates | `devspec/architecture/artifact-queue.md` | evidence-backed diagram candidates and duplicate checks | pending | Queue eligible non-process-flow diagram candidates. | |
+| EXT-011 | constitution-candidates | `devspec/constitution.md` | durable principle candidates requiring confirmation | pending | Ask before writing principle changes. | |
+| EXT-012 | closure | `devspec/foundation/extraction-state.md` | artifact update summary, blockers, confirmations, next action | pending | Summarize extraction and select one next action. | |
+
+## Blockers and Confirmations
+
+| ID | Kind | Related task | Subject | Required action | Resolution | Notes |
+| --- | --- | --- | --- | --- | --- | --- |
+|  | blocker or confirmation |  |  |  |  |  |

devspec_installer/payload/devspec/foundation/_template/project-context.md

@@ -0,0 +1,37 @@
+# Project Context
+
+Use this artifact for durable product facts that should shape future work items. Keep it concise and developer-facing. Omit optional rows or sections with no project content.
+
+## Product Overview
+
+| Field | Description | Source | Confidence |
+| --- | --- | --- | --- |
+| Purpose | <why the product exists> | <user-input-or-source> | confirmed |
+| Problem | <user-or-business-problem-being-addressed> | <user-input-or-source> | confirmed |
+| Target outcome | <intended-user-or-business-result> | <user-input-or-source> | confirmed |
+
+## Audiences and Stakeholders
+
+| Group | Category | Need or responsibility | Source | Confidence |
+| --- | --- | --- | --- | --- |
+| <primary-user-group> | user | <need-or-responsibility> | <user-input-or-source> | confirmed |
+| <stakeholder-group> | stakeholder | <need-or-responsibility> | <user-input-or-source> | confirmed |
+
+## Outcomes and Scope
+
+Use this section for product goals, explicit scope exclusions, and measurable success signals. Keep operational rules and delivery gates in `rules.md`.
+
+| Type | Outcome, boundary, or metric | Implementation implication | Source | Confidence |
+| --- | --- | --- | --- | --- |
+| goal | <desired-product-result> | <how-this-should-shape-implementation-decisions> | <user-input-or-source> | confirmed |
+| scope exclusion | <explicit-exclusion> | <what-not-to-build-or-optimize-for> | <user-input-or-source> | confirmed |
+| success metric | <target-or-signal> | <what to instrument, preserve, or optimize> | <user-input-or-source> | confirmed |
+
+## Delivery Context
+
+Use this section for product or business constraints and unresolved blockers that affect implementation planning. Keep repository location, access, ownership, and path facts in `codebase-structure.md`.
+
+| Type | Context item | Scope | Required handling or next step | Source | Confidence | Status |
+| --- | --- | --- | --- | --- | --- | --- |
+| constraint | <product-or-business-constraint> | <affected-scope> | <required-action-or-limit> | <user-input-or-source> | confirmed | active |
+| blocker | <unresolved-blocker-or-question> | <affected-scope> | <next-action-needed> | <user-input-or-source> | confirmed | open |

devspec_installer/payload/devspec/foundation/_template/provider-integrations.md

@@ -0,0 +1,94 @@
+# Provider Integrations
+
+Use this policy to resolve external work items during `/devspec.story`. Keep provider-specific lookup behind MCP servers or equivalent integration tools. Manual intake is an explicit fallback, available only when provider resolution is unavailable or intentionally skipped.
+
+## Resolution Policy
+
+| Policy area | Requirement |
+| --- | --- |
+| Workflow boundary | Keep work-item intake provider-agnostic; provider-specific lookup belongs in integration tools. |
+| Resolution preference | Prefer exact provider URLs or provider-qualified identifiers over inferred matches. |
+| Ambiguity handling | Ask one structured `clarification` question before resolving an ambiguous provider or identifier. |
+| Manual fallback | Allow manual intake only when external resolution is unavailable and the user explicitly chooses to proceed. |
+| Work-item creation gate | Do not create or update the work-item folder from provider input until the resolved item is shown to the user and explicitly confirmed. |
+| Secret handling | Keep provider authentication, credentials, and secrets outside prompt artifacts. |
+
+## Supported Provider Inputs
+
+| Provider | Preferred input | Accepted shorthand | Validation guardrail |
+| --- | --- | --- | --- |
+| GitHub | Full issue URL or supported pull request URL | `owner/repo#123` | Reject bare numbers unless repository context is configured. |
+| Jira | Full issue URL | Issue key such as `ABC-123` | Reject malformed keys or keys outside configured project patterns. |
+| Azure DevOps | Full work item URL | Numeric ID only with configured organization and project context | Reject numeric IDs when organization or project context is missing. |
+
+## Resolution Flow and Outcomes
+
+Resolve inputs in this order:
+
+| Order | Input path | Required handling |
+| --- | --- | --- |
+| 1 | Full provider URL | Validate format, resolve through the configured provider tool, and request structured confirmation on success. |
+| 2 | Provider-qualified identifier | Validate provider context, resolve through the configured provider tool, and request structured confirmation on success. |
+| 3 | Ambiguous identifier | Ask a structured provider `clarification` question before lookup. |
+| 4 | Manual intake | Continue only after the user explicitly chooses manual intake and supplies required manual fields. |
+
+Handle outcomes as follows:
+
+| Condition | Required handling |
+| --- | --- |
+| Invalid input format | Stop intake and explain why the input is invalid. |
+| Ambiguous provider | Ask one structured `clarification` question to identify the provider. |
+| Known provider cannot resolve item | Stop intake and classify the failure as not found, access denied, or integration unavailable when possible. |
+| Integration unavailable | Offer manual intake as an explicit fallback. |
+| Provider resolution succeeds | Show the confirmation summary and require structured confirmation before creating or updating the work-item folder. |
+| Unverified provider input | Treat as blocked or manual fallback only; do not create a normal resolved work item. |
+
+## Confirmation Requirements
+
+Show this minimum summary when provider resolution succeeds:
+
+| Field | Required |
+| --- | --- |
+| Provider | yes |
+| Identifier | yes |
+| Title | yes |
+| Type | when available |
+| Current external status | when available |
+| Canonical link | yes |
+| Short summary | yes |
+
+Offer only these structured `confirmation` actions:
+
+| Action | Result |
+| --- | --- |
+| Confirm and continue | Continue normal resolved intake. |
+| Reject and retry input | Ask a structured `retry` or source-correction question. |
+| Switch to manual intake | Continue only with manual intake requirements. |
+| Cancel | Stop intake. |
+| Custom Answer | Route to clarification; do not create or update the work-item folder until resolved. |
+
+## Integration Tooling and Access
+
+| Area | Requirement |
+| --- | --- |
+| Tooling model | Use a provider-specific MCP server or one internal MCP server that wraps multiple providers. |
+| Lookup tools | Validate and fetch work items by URL or provider-specific identifier. |
+| Returned data | Include title, description, status, labels or type, links, and relevant metadata. |
+| Failure detail | Distinguish not found, unauthorized, malformed input, and transient provider failures. |
+| Authentication configuration | Keep provider authentication outside prompt artifacts. |
+| Privilege model | Use least-privilege tokens or service identities. |
+| Access mode | Prefer read-only access for intake and review unless write-back is required. |
+
+## Work-Item Intake Recording Requirements
+
+| Recording area | Requirement |
+| --- | --- |
+| Source resolution status | Record a value from `devspec/glossary.md#source-resolution-status-values` in `meta.md`. |
+| Lookup attempt | Record provider and resolution notes. |
+| Manual source status | Use source resolution status `manual` only when the user explicitly chooses to continue without external resolution. |
+| Manual intake | Require external reference, manual description, and manual acceptance criteria. |
+| Resolved items | Require structured confirmation after showing resolved details. |
+| Blocked status | Use when input is invalid or required resolution failed. |
+| Confirmation result | Record it in `meta.md` and record the shown summary in `story.md`. |
+| Provider policy ownership | Keep provider-specific details here instead of duplicating them across prompt files. |
+| Maintenance trigger | Update this file when provider formats, supported tools, authentication expectations, or fallback policy changes. |

devspec_installer/payload/devspec/foundation/_template/rules.md

@@ -0,0 +1,54 @@
+# Operational Rules
+
+Use this artifact for project-operational rules that affect planning, implementation, review, or release. Keep enduring principles in `devspec/constitution.md`; keep product goals and scope boundaries in `project-context.md`.
+
+## Rule Governance
+
+| Boundary | Guidance |
+| --- | --- |
+| Purpose | Record operational constraints, governance requirements, delivery gates, and evolving project rules. |
+| Exclusions | Do not duplicate durable principles from `devspec/constitution.md` or product intent from `project-context.md`. |
+| Record quality | Write actionable records with scope, enforcement point, source, and confidence. |
+| Optional content | Omit rows or sections that have no project-specific content. |
+
+## Operational Rule Catalog
+
+Use this section for hard constraints, compliance requirements, and forbidden patterns. Use `Type` to distinguish the rule kind instead of creating separate overlapping sections.
+
+| Type | Rule | Scope | Requirement or prohibition | Enforcement point | Evidence, rationale, or preferred alternative | Source | Confidence |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| hard constraint | <rule-name> | <system-or-work-scope> | <must-do-or-must-not-do> | <planning-implementation-review-release> | <why-or-how-to-apply> | <source-or-user-input> | confirmed |
+| compliance requirement | <requirement-name> | <data-system-or-work-type> | <action-required> | <planning-implementation-review-release> | <evidence-or-policy-source> | <source-or-user-input> | confirmed |
+| forbidden pattern | <pattern-name> | <system-or-work-scope> | <pattern-or-practice-to-avoid> | <planning-implementation-review-release> | <risk-or-preferred-alternative> | <source-or-user-input> | confirmed |
+
+## Delivery Gate Catalog
+
+| Gate | Applies to | Required evidence | Blocking condition | Source | Confidence |
+| --- | --- | --- | --- | --- | --- |
+| <gate-name> | <work-type-or-release-stage> | <validation-or-approval-required> | <what-blocks-completion> | <source-or-user-input> | confirmed |
+
+## Work-Item Handling Rules
+
+Use this section for rules that vary by work-item type or workflow stage. These defaults apply unless a stricter project-specific rule or delivery gate supersedes them.
+
+| Work-item type | Stage | Requirement |
+| --- | --- | --- |
+| bug | Intake and readiness | Capture expected behavior, actual behavior, reproduction steps, impact, and regression context unless blocked. |
+| bug | Planning | Include reproduce, fix, and regression-validation work when practical. |
+| bug | Implementation | Record regression validation and useful before-and-after snippets for code fixes. |
+| bug | Review | Review bugs with meaningful regression risk before closure. |
+| security-vulnerability | Intake and readiness | Capture severity, affected scope, attack surface, exploitability, disclosure status, and containment or remediation plan. |
+| security-vulnerability | Shared artifacts | Minimize or redact sensitive exploit details when full disclosure is unsafe. |
+| security-vulnerability | Planning | Include impact confirmation, remediation, supported-version verification, and follow-up needs when applicable. |
+| security-vulnerability | Implementation | Verify remediation across affected supported versions and record backport, release, or advisory follow-up. |
+| security-vulnerability | Review | Review security vulnerabilities before closure. |
+| all | Review | Check scope adherence, bugs, regressions, missing validation, and rule violations against the finalized brief. |
+| all | Changes requested | Route the work item back to implementation before marking it complete. |
+
+## Exceptions and Waivers
+
+Include this section only when exception handling differs from the normal rules or gates.
+
+| Exception | Affected rule or gate | Approval or handling process | Status | Source |
+| --- | --- | --- | --- | --- |
+| <exception-name> | <rule-or-gate-id> | <approval-process-or-compensating-control> | open | <source-or-user-input> |