@rsaglobaltech/specgate 0.8.1

package/package.json

@@ -0,0 +1,105 @@
+{
+  "name": "@rsaglobaltech/specgate",
+  "version": "0.8.1",
+  "description": "Specs as executable contracts — requirements, scenarios and traceability that CI enforces.",
+  "license": "MIT",
+  "type": "commonjs",
+  "bin": {
+    "specgate": "bin/specgate.js",
+    "csda": "bin/specgate.js",
+    "create-spec-driven-app": "bin/specgate.js"
+  },
+  "files": [
+    "bin/",
+    "dist/bin/",
+    "dist/scripts/",
+    "dist/packages/core/",
+    "templates/",
+    "examples/",
+    "vendor/",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rsaglobaltech/specgate.git"
+  },
+  "keywords": [
+    "spec-driven-development",
+    "sdd",
+    "gherkin",
+    "traceability",
+    "ci-gate",
+    "ai-agents",
+    "cli"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
+    "prebuild": "npm run clean",
+    "prepack": "npm run build",
+    "pretest": "npm run build",
+    "test": "node --test dist/tests/cli.test.js",
+    "test:unit": "node scripts/run-tests.cjs dist/tests/unit",
+    "test:core-unit": "node scripts/run-tests.cjs dist/packages/core/test/unit",
+    "test:vscode-unit": "node scripts/run-tests.cjs dist/packages/vscode-spec-driven/test/unit",
+    "test:mcp-unit": "node scripts/run-tests.cjs dist/packages/mcp-spec-driven/test/unit",
+    "test:registry-unit": "node scripts/run-tests.cjs dist/packages/pack-registry/test/unit",
+    "test:lsp-unit": "node scripts/run-tests.cjs dist/packages/lsp-spec-driven/test/unit",
+    "registry:build": "node dist/packages/pack-registry/src/build.js",
+    "test:snapshot": "node scripts/run-tests.cjs dist/tests/snapshot",
+    "mutation:pilot": "npm run build && node scripts/check-mutation-targets.mjs && stryker run stryker.config.mjs",
+    "test:coverage": "c8 --config .c8rc.json node scripts/run-tests.cjs dist/tests/unit dist/packages/core/test/unit",
+    "test:bdd": "cucumber-js",
+    "test:all": "npm test && npm run test:coverage && npm run test:bdd && npm run test:core-unit && npm run test:vscode-unit && npm run test:mcp-unit && npm run test:registry-unit && npm run test:lsp-unit && npm run test:snapshot && npm run registry:build",
+    "pack:dry-run": "npm pack --dry-run",
+    "pack": "npm pack",
+    "demo:video": "bash scripts/demo/build-video.sh",
+    "demo:video:de": "bash scripts/demo/de/build-video.sh --real-agent",
+    "smoke:help": "node bin/specgate.js --help",
+    "smoke:init": "node bin/specgate.js init --config examples/project.config.example --out .smoke-tmp --no-git --force",
+    "smoke:validate": "node bin/specgate.js validate .smoke-tmp/acme-energy-hub",
+    "smoke:report": "node bin/specgate.js report --project-dir .smoke-tmp/acme-energy-hub --stdout",
+    "smoke:expand": "node bin/specgate.js expand --pack-root tests/fixtures/domain-packs --pack parking-management/backend --project-dir /private/tmp/acme-energy-hub --var PROJECT_NAME='Acme Energy Hub' --var PROJECT_SLUG=acme-energy-hub --var DOMAIN='community energy' --dry-run",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint \"bin/**/*.{ts,js}\" \"scripts/**/*.ts\" \"tests/**/*.ts\" \"packages/**/*.ts\" \"features/**/*.ts\"",
+    "lint:fix": "eslint --fix \"bin/**/*.{ts,js}\" \"scripts/**/*.ts\" \"tests/**/*.ts\" \"packages/**/*.ts\" \"features/**/*.ts\"",
+    "format": "prettier --write \"bin/**/*.{ts,js}\" \"scripts/**/*.ts\" \"tests/**/*.ts\" \"packages/**/*.ts\" \"features/**/*.ts\"",
+    "format:check": "prettier --check \"bin/**/*.{ts,js}\" \"scripts/**/*.ts\" \"tests/**/*.ts\" \"packages/**/*.ts\" \"features/**/*.ts\"",
+    "verify": "npm run typecheck && npm run lint && npm test && npm run pack:dry-run && npm run selfcheck",
+    "selfcheck": "node bin/specgate.js validate .",
+    "docs:agent-contract": "node dist/scripts/gen_agent_contract.js",
+    "docs:agent-contract:check": "node dist/scripts/gen_agent_contract.js --check",
+    "docs:terminal": "node dist/scripts/docs/record-terminal.js",
+    "docs:terminal:check": "node dist/scripts/docs/record-terminal.js --check",
+    "sbom": "npm sbom --sbom-format cyclonedx > sbom.cyclonedx.json",
+    "licenses": "npm run sbom && node dist/scripts/license_check.js --sbom sbom.cyclonedx.json"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "devDependencies": {
+    "@cucumber/cucumber": "^13.2.1",
+    "@cucumber/gherkin": "^42.0.0",
+    "@eslint/js": "^9.39.4",
+    "@stryker-mutator/core": "^10.0.0",
+    "@types/cucumber": "^7.0.3",
+    "@types/node": "^26.2.0",
+    "@types/vscode": "^1.134.0",
+    "@typescript-eslint/eslint-plugin": "^8.59.3",
+    "@typescript-eslint/parser": "^8.59.3",
+    "ajv": "^8.20.0",
+    "c8": "^12.0.0",
+    "eslint": "^10.8.1",
+    "fast-check": "^4.8.0",
+    "js-yaml": "^5.2.3",
+    "marked": "^18.0.10",
+    "prettier": "^3.8.3",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.59.3"
+  }
+}

package/templates/adopt/AI_RULES.md.tpl

@@ -0,0 +1,27 @@
+# AI Rules — {{PROJECT_NAME}}
+
+Rules for any AI coding agent (and any human) working on this repository.
+
+## Project facts
+
+- Domain: {{DOMAIN}}
+- Stack: {{STACK}}
+- Testing: {{TESTING}}
+- Test command: `{{TEST_CMD}}`
+
+## Boundaries
+
+- `spec.md`, `features/**/*.feature` and `docs/specs/traceability.md` are the
+  source of truth. Do not edit them to make a failing gate pass.
+- Never delete or weaken an existing test to get to green.
+- Implement one requirement (REQ-NNN) at a time; write or extend the test
+  first, then the production code.
+- Keep changes inside this repository; do not modify generated or vendored
+  code unless the requirement says so.
+
+## Definition of done
+
+1. The scenario(s) for the requirement pass.
+2. `{{TEST_CMD}}` passes.
+3. `specgate validate . --strict-tdd` passes.
+4. The traceability row is updated via `specgate done REQ-NNN`.

package/templates/adopt/adr-readme.md.tpl

@@ -0,0 +1,5 @@
+# Architecture Decision Records — {{PROJECT_NAME}}
+
+One markdown file per accepted design decision, numbered `NNNN-title.md`.
+Record the context, the decision, and the consequences. Decisions made
+before adoption can be back-filled as they resurface.

package/templates/adopt/baseline.feature.tpl

@@ -0,0 +1,9 @@
+Feature: Existing behaviour is preserved
+  The project was adopted into spec-driven development with code already
+  written. This baseline scenario pins the adoption invariant: nothing
+  that worked before adoption may silently break after it.
+
+  Scenario: Existing test suite stays green
+    Given the project is built from a clean checkout
+    When the full test suite runs
+    Then every existing test passes

package/templates/adopt/spec.md.tpl

@@ -0,0 +1,25 @@
+# {{PROJECT_NAME}} — Specification
+
+> Adopted into Spec-Driven Development on an existing codebase (brownfield).
+> `specgate req add "<title>"` reserves the next `REQ-NNN` and adds its row to
+> `docs/specs/traceability.md` — it does not write a section here or a
+> `.feature`. Add a `## REQ-NNN — <title>` section below and a Gherkin
+> scenario under `features/`, then `specgate req link REQ-NNN --feature … --test …`
+> to point the row at both. Existing behaviour is retro-filled requirement by
+> requirement — start with the ones your team is actively changing.
+
+## Context
+
+- Domain: {{DOMAIN}}
+- Stack: {{STACK}}
+- API style: {{API_STYLE}}
+- Testing: {{TESTING}}
+
+## Requirements
+
+## REQ-001 — Existing behaviour is preserved
+
+The adopted codebase keeps working: the full test suite passes on every
+change. This requirement anchors the traceability matrix until real
+requirements are retro-filled from the existing code and tests.
+{{PROPOSED_REQUIREMENTS}}

package/templates/adopt/traceability.md.tpl

@@ -0,0 +1,11 @@
+# Traceability Matrix — {{PROJECT_NAME}}
+
+Every requirement in `spec.md` maps to a scenario, its feature file, and the
+artifacts that implement and verify it. `specgate plan` lists
+what is still missing; `specgate done REQ-NNN` flips a row to
+Implemented.
+
+| Requirement | Scenario ID | Feature file | Use Case | Command/Query | Aggregate | Event | Technical artifact | Test artifact | Status |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| REQ-001 | SCN-001 | `features/adoption/baseline.feature` | UC-001 Preserve existing behaviour | - | - | - | existing codebase | `{{TEST_CMD}}` | Draft |
+{{PROPOSED_ROWS}}

package/templates/backend/AI_RULES.md.tpl

@@ -0,0 +1,35 @@
+# AI Rules - Backend ({{PROJECT_NAME}})
+
+## Role
+You are the Lead Backend Engineer. Implement strictly from `spec.md` and `features/`.
+
+## Project Initialization & Stack
+- Project: {{PROJECT_NAME}} ({{PROJECT_SLUG}})
+- Domain: {{DOMAIN}}
+- Stack: {{STACK}}
+- Architecture: {{ARCHITECTURE}}
+- API style: {{API_STYLE}}
+- Testing: {{TESTING}}
+
+## Stack Rules
+- Do not infer or replace the stack from preference or prior projects.
+- If any stack field is `TBD`, stop implementation and update `AI_RULES.md` or `spec.md` with the Product Owner first.
+- Respect layered architecture and domain boundaries within the declared stack.
+
+## Non-Negotiables
+- Domain logic isolated from framework details.
+- Tests aligned to acceptance criteria in Gherkin.
+- No implementation without a traceability entry.
+
+## Domain Modeling Rules
+{{ARCHITECTURE_MODELING_RULES}}
+
+## Pre-Implementation Gates
+{{ARCHITECTURE_GATES}}
+
+## Workflow
+1. Read `spec.md`.
+{{ARCHITECTURE_READS}}
+3. Read scenarios in `features/`.
+4. Update `docs/specs/traceability.md`.
+5. Implement and validate acceptance criteria.

package/templates/backend/features/core/health.feature.tpl

@@ -0,0 +1,7 @@
+Feature: Platform health baseline
+  @REQ-000 @SCN-000
+  Scenario: API reports service as healthy
+    Given the backend service is running
+    When I request the "/health" endpoint
+    Then the response status should be 200
+    And the payload should include "status" with value "UP"

package/templates/base/.devcontainer/devcontainer.json.tpl

@@ -0,0 +1,18 @@
+{
+  "name": "{{PROJECT_NAME}}",
+  "dockerComposeFile": "../docker-compose.yml",
+  "service": "workspace",
+  "workspaceFolder": "/workspace",
+  "shutdownAction": "stopCompose",
+  "remoteEnv": {
+    "APP_ENV": "{{DEFAULT_ENV}}"
+  },
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "ms-azuretools.vscode-docker",
+        "redhat.vscode-yaml"
+      ]
+    }
+  }
+}

package/templates/base/.dockerignore.tpl

@@ -0,0 +1,11 @@
+.git
+.devcontainer
+node_modules
+target
+build
+dist
+.env
+.env.*
+!.env.example
+!.env.*.app
+!.env.*.infra

package/templates/base/.env.dev.app.tpl

@@ -0,0 +1,13 @@
+# Application variables for the dev environment.
+# Consumed by the application process (not Docker Compose infrastructure).
+# Safe to commit to version control; never put real secrets here.
+APP_ENV=dev
+PROJECT_SLUG={{PROJECT_SLUG}}
+
+DATABASE_ENGINE={{DATABASE_ENGINE}}
+DATABASE_HOST={{DATABASE_HOST}}
+DATABASE_PORT={{DATABASE_PORT_DEV}}
+DATABASE_NAME={{DATABASE_NAME_DEV}}
+DATABASE_USER={{DATABASE_USER}}
+DATABASE_PASSWORD={{DATABASE_PASSWORD}}
+DATABASE_URL={{DATABASE_URL_DEV}}

package/templates/base/.env.dev.infra.tpl

@@ -0,0 +1,6 @@
+# Infrastructure variables for the dev environment.
+# Consumed by Docker Compose for the db service.
+# Do NOT put application-level config here.
+POSTGRES_DB={{DATABASE_NAME_DEV}}
+POSTGRES_USER={{DATABASE_USER}}
+POSTGRES_PASSWORD={{DATABASE_PASSWORD}}

package/templates/base/.env.dev.tpl

@@ -0,0 +1,16 @@
+APP_ENV=dev
+PROJECT_SLUG={{PROJECT_SLUG}}
+
+DATABASE_ENGINE={{DATABASE_ENGINE}}
+DATABASE_IMAGE={{DATABASE_IMAGE}}
+DATABASE_HOST={{DATABASE_HOST}}
+DATABASE_PORT={{DATABASE_PORT_DEV}}
+DATABASE_CONTAINER_PORT={{DATABASE_CONTAINER_PORT}}
+DATABASE_NAME={{DATABASE_NAME_DEV}}
+DATABASE_USER={{DATABASE_USER}}
+DATABASE_PASSWORD={{DATABASE_PASSWORD}}
+DATABASE_URL={{DATABASE_URL_DEV}}
+
+POSTGRES_DB={{DATABASE_NAME_DEV}}
+POSTGRES_USER={{DATABASE_USER}}
+POSTGRES_PASSWORD={{DATABASE_PASSWORD}}

package/templates/base/.env.example.tpl

@@ -0,0 +1,17 @@
+# Copy one environment file to `.env` or set `APP_ENV` before running Docker Compose.
+APP_ENV={{DEFAULT_ENV}}
+PROJECT_SLUG={{PROJECT_SLUG}}
+
+DATABASE_ENGINE={{DATABASE_ENGINE}}
+DATABASE_IMAGE={{DATABASE_IMAGE}}
+DATABASE_HOST={{DATABASE_HOST}}
+DATABASE_PORT={{DATABASE_PORT}}
+DATABASE_CONTAINER_PORT={{DATABASE_CONTAINER_PORT}}
+DATABASE_NAME={{DATABASE_NAME_DEV}}
+DATABASE_USER={{DATABASE_USER}}
+DATABASE_PASSWORD={{DATABASE_PASSWORD}}
+DATABASE_URL={{DATABASE_URL_DEV}}
+
+POSTGRES_DB={{DATABASE_NAME_DEV}}
+POSTGRES_USER={{DATABASE_USER}}
+POSTGRES_PASSWORD={{DATABASE_PASSWORD}}

package/templates/base/.env.feature.app.tpl

@@ -0,0 +1,11 @@
+# Application variables for the feature environment.
+APP_ENV=feature
+PROJECT_SLUG={{PROJECT_SLUG}}
+
+DATABASE_ENGINE={{DATABASE_ENGINE}}
+DATABASE_HOST={{DATABASE_HOST}}
+DATABASE_PORT={{DATABASE_PORT_FEATURE}}
+DATABASE_NAME={{DATABASE_NAME_FEATURE}}
+DATABASE_USER={{DATABASE_USER}}
+DATABASE_PASSWORD={{DATABASE_PASSWORD}}
+DATABASE_URL={{DATABASE_URL_FEATURE}}

package/templates/base/.env.feature.infra.tpl

@@ -0,0 +1,4 @@
+# Infrastructure variables for the feature environment.
+POSTGRES_DB={{DATABASE_NAME_FEATURE}}
+POSTGRES_USER={{DATABASE_USER}}
+POSTGRES_PASSWORD={{DATABASE_PASSWORD}}

package/templates/base/.env.feature.tpl

@@ -0,0 +1,16 @@
+APP_ENV=feature
+PROJECT_SLUG={{PROJECT_SLUG}}
+
+DATABASE_ENGINE={{DATABASE_ENGINE}}
+DATABASE_IMAGE={{DATABASE_IMAGE}}
+DATABASE_HOST={{DATABASE_HOST}}
+DATABASE_PORT={{DATABASE_PORT_FEATURE}}
+DATABASE_CONTAINER_PORT={{DATABASE_CONTAINER_PORT}}
+DATABASE_NAME={{DATABASE_NAME_FEATURE}}
+DATABASE_USER={{DATABASE_USER}}
+DATABASE_PASSWORD={{DATABASE_PASSWORD}}
+DATABASE_URL={{DATABASE_URL_FEATURE}}
+
+POSTGRES_DB={{DATABASE_NAME_FEATURE}}
+POSTGRES_USER={{DATABASE_USER}}
+POSTGRES_PASSWORD={{DATABASE_PASSWORD}}

package/templates/base/.env.prod.app.tpl

@@ -0,0 +1,13 @@
+# Application variables for the prod environment.
+# WARNING: Replace placeholder values before deploying.
+# Inject DATABASE_PASSWORD and DATABASE_URL via CI secrets or a secrets manager.
+APP_ENV=prod
+PROJECT_SLUG={{PROJECT_SLUG}}
+
+DATABASE_ENGINE={{DATABASE_ENGINE}}
+DATABASE_HOST={{DATABASE_HOST}}
+DATABASE_PORT={{DATABASE_PORT_PROD}}
+DATABASE_NAME={{DATABASE_NAME_PROD}}
+DATABASE_USER={{DATABASE_USER}}
+DATABASE_PASSWORD={{DATABASE_PASSWORD}}
+DATABASE_URL={{DATABASE_URL_PROD}}

package/templates/base/.env.prod.infra.tpl

@@ -0,0 +1,6 @@
+# Infrastructure variables for the prod environment.
+# WARNING: Do NOT commit real production credentials.
+# Inject POSTGRES_PASSWORD via CI secrets or a secrets manager (doppler, sops, etc.)
+POSTGRES_DB={{DATABASE_NAME_PROD}}
+POSTGRES_USER={{DATABASE_USER}}
+POSTGRES_PASSWORD={{DATABASE_PASSWORD}}

package/templates/base/.env.prod.tpl

@@ -0,0 +1,16 @@
+APP_ENV=prod
+PROJECT_SLUG={{PROJECT_SLUG}}
+
+DATABASE_ENGINE={{DATABASE_ENGINE}}
+DATABASE_IMAGE={{DATABASE_IMAGE}}
+DATABASE_HOST={{DATABASE_HOST}}
+DATABASE_PORT={{DATABASE_PORT_PROD}}
+DATABASE_CONTAINER_PORT={{DATABASE_CONTAINER_PORT}}
+DATABASE_NAME={{DATABASE_NAME_PROD}}
+DATABASE_USER={{DATABASE_USER}}
+DATABASE_PASSWORD={{DATABASE_PASSWORD}}
+DATABASE_URL={{DATABASE_URL_PROD}}
+
+POSTGRES_DB={{DATABASE_NAME_PROD}}
+POSTGRES_USER={{DATABASE_USER}}
+POSTGRES_PASSWORD={{DATABASE_PASSWORD}}

package/templates/base/.github/workflows/specs.yml.tpl

@@ -0,0 +1,26 @@
+name: Spec Validation
+
+on:
+  pull_request:
+    branches: [main, develop]
+  push:
+    branches: [main]
+
+jobs:
+  validate-specs:
+    name: Validate Specification Tree
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+
+      - name: Install specgate
+        run: npm install -g @rsaglobaltech/specgate@latest
+
+      - name: Validate spec tree
+        run: specgate validate .

package/templates/base/.gitignore.tpl

@@ -0,0 +1,9 @@
+.DS_Store
+node_modules/
+.next/
+out/
+build/
+dist/
+coverage/
+.env
+.env.local

package/templates/base/.pre-commit-config.yaml.tpl

@@ -0,0 +1,10 @@
+repos:
+  - repo: local
+    hooks:
+      - id: validate-specs
+        name: Validate spec tree
+        language: system
+        entry: npx @rsaglobaltech/specgate validate .
+        pass_filenames: false
+        always_run: true
+        stages: [pre-commit]

package/templates/base/AGENTS.md.tpl

@@ -0,0 +1,32 @@
+# Agent Manifest — {{PROJECT_NAME}}
+
+> This file helps AI coding agents (Claude, Copilot, Cursor, Aider, etc.)
+> understand the structure and constraints of this project.
+
+## Project overview
+- **Name**: {{PROJECT_NAME}}
+- **Domain**: {{DOMAIN}}
+- **Stack**: {{STACK}}
+- **API style**: {{API_STYLE}}
+- **Testing**: {{TESTING}}
+
+## Specification entry points
+| Artefact | Path | Purpose |
+|---|---|---|
+| Root spec | `spec.md` | Vision, requirements, bounded contexts, risks |
+| Domain model | `docs/specs/domain-model.md` | Aggregates, bounded contexts, value objects |
+| Traceability | `docs/specs/traceability.md` | REQ → Scenario → UC → Aggregate → test |
+| AI guardrails | `AI_RULES.md` | Stack constraints and conventions for this project |
+| ADRs | `docs/specs/adr/` | Architecture decision records |
+
+## Constraints
+- **Always read `AI_RULES.md` before writing any code.** It specifies the exact stack, conventions and forbidden patterns.
+- **Always check `docs/specs/traceability.md`** before claiming a requirement is implemented.
+- **Do not implement features not linked to a requirement** in `spec.md`.
+- **Run `npx @rsaglobaltech/specgate validate .`** after any change to `docs/specs/` or `features/`.
+
+## Quality gates
+A change is considered complete only when:
+1. `npx @rsaglobaltech/specgate validate .` exits 0.
+2. All Gherkin scenarios linked to the changed requirement are passing.
+3. The traceability matrix is updated to reflect the new status.

package/templates/base/README.md.tpl

@@ -0,0 +1,32 @@
+# {{PROJECT_NAME}} - Spec-Driven Development
+
+This project was generated from the SDD MVP template.
+
+## Context
+- Project type: `{{PROJECT_TYPE}}`
+- Domain: `{{DOMAIN}}`
+
+## Structure
+- `spec.md`: business manifesto and goals.
+- `AI_RULES.md`: AI execution contract.
+- `features/`: acceptance criteria in Gherkin.
+- `docs/specs/traceability.md`: requirement -> scenario -> domain -> implementation -> test mapping.
+- `docs/specs/domain-model.md`: bounded contexts, aggregates, value objects, and events.
+- `docs/specs/use-cases.md`: use cases mapped to requirements and commands/queries.
+- `docs/specs/commands.md`: commands and queries expected by the application layer.
+- `docs/specs/events.md`: domain events used for meaningful state changes.
+- `docs/specs/aggregates.md`: aggregate roots and invariants.
+- `docs/specs/status-model.md`: lightweight Unified Process maturity states.
+- `docs/specs/review-checklist.md`: pre-implementation and architecture gates.
+- `docs/specs/adr/`: architecture decision records.
+
+## Recommended Workflow
+1. Define or refine `spec.md`.
+2. Refine domain model documents in `docs/specs/`.
+3. Adapt scenarios in `features/`.
+4. Map scenarios in `docs/specs/traceability.md`.
+5. Implement software until acceptance criteria pass.
+
+## Support Command
+- Validate spec structure:
+  - `../mvp-spec-template/scripts/validate_specs.sh .`

package/templates/base/docker-compose.yml.tpl

@@ -0,0 +1,13 @@
+name: {{PROJECT_SLUG}}-${APP_ENV:-{{DEFAULT_ENV}}}
+
+services:
+  workspace:
+    image: mcr.microsoft.com/devcontainers/base:ubuntu
+    command: sleep infinity
+    working_dir: /workspace
+    volumes:
+      - .:/workspace:cached
+    env_file:
+      - .env.${APP_ENV:-{{DEFAULT_ENV}}}.app
+{{COMPOSE_DEPENDS_ON}}
+{{COMPOSE_DB_SERVICE}}

package/templates/base/docs/specs/adr/README.md.tpl

@@ -0,0 +1,10 @@
+# 🧠 ADR (Architecture Decision Records)
+
+Use this folder to track relevant technical decisions.
+
+Suggested format:
+- `ADR-0001-short-title.md`
+- Context
+- Decision
+- Consequences
+- Status (proposed, accepted, replaced)

package/templates/base/docs/specs/aggregates.md.tpl

@@ -0,0 +1,5 @@
+# Aggregates
+
+| ID | Aggregate | Context | Invariants |
+|---|---|---|---|
+| AGG-001 | CoreAggregate | Core | Define the first consistency rules. |

package/templates/base/docs/specs/commands.md.tpl

@@ -0,0 +1,13 @@
+# Commands and Queries
+
+## Commands
+
+| ID | Command | Use Case | Fields |
+|---|---|---|---|
+| CMD-001 | ExampleCommand | UC-001 | example_id, occurred_at |
+
+## Queries
+
+| ID | Query | Use Case | Returns |
+|---|---|---|---|
+| QRY-001 | ExampleQuery | UC-001 | ExampleReadModel |

package/templates/base/docs/specs/domain-model.md.tpl

@@ -0,0 +1,30 @@
+# Domain Model
+
+## Bounded Contexts
+
+| ID | Name | Type | Responsibility | Aggregates |
+|---|---|---|---|---|
+| BC-001 | Core | Core | Own the central business rules. | AGG-001 CoreAggregate |
+
+## Aggregates
+
+| ID | Aggregate | Context | Invariants |
+|---|---|---|---|
+| AGG-001 | CoreAggregate | Core | Define the first consistency rules. |
+
+## Value Objects
+
+| ID | Value Object | Fields | Invariants |
+|---|---|---|---|
+| VO-001 | ExampleValue | value | Must be valid for the business process. |
+
+## Domain Events
+
+| ID | Event | Producer | Consumers | Payload |
+|---|---|---|---|---|
+| EVT-001 | ExampleEvent | CoreAggregate | TBD | occurred_at |
+
+## Context Notes
+
+- Keep domain logic independent from HTTP, database, queues, and framework code.
+- Add structure only when it improves clarity, traceability, generation, review, or validation.

package/templates/base/docs/specs/events.md.tpl

@@ -0,0 +1,5 @@
+# Domain Events
+
+| ID | Event | Producer | Consumers | Payload |
+|---|---|---|---|---|
+| EVT-001 | ExampleEvent | CoreAggregate | TBD | occurred_at |

package/templates/base/docs/specs/review-checklist.md.tpl

@@ -0,0 +1,18 @@
+# Review Checklist
+
+## Pre-Implementation Gates
+
+- [ ] Requirement has an ID.
+- [ ] Scenario has an ID.
+- [ ] Scenario maps to a use case.
+- [ ] Use case maps to a command or query.
+- [ ] Command or query maps to an aggregate or read model.
+- [ ] Domain events are listed when state changes matter.
+- [ ] Traceability row is complete.
+
+## Architecture Gates
+
+- [ ] Domain logic is independent from HTTP, database, queues, and framework code.
+- [ ] Controllers and adapters call application use cases, not repositories directly.
+- [ ] Business rules live in domain entities, value objects, or domain services.
+- [ ] ADRs exist for decisions that affect architecture boundaries.

package/templates/base/docs/specs/runtime-environments.md.tpl

@@ -0,0 +1,26 @@
+# Runtime Environments
+
+> Normative contract, generated by `specgate init`. The environments below are the
+> only ones this project recognises. Code must read its configuration from the
+> environment — never hardcode a host, port or credential.
+
+## Environment catalog
+
+{{RUNTIME_ENV_TABLE}}
+
+Declared environments: `{{ENVIRONMENTS}}`
+Default environment: `{{DEFAULT_ENV}}`
+
+The active environment is selected with `APP_ENV`. An unset `APP_ENV` means
+`{{DEFAULT_ENV}}`.
+
+{{RUNTIME_DATABASE_SECTION}}
+
+{{RUNTIME_DOCKER_SECTION}}
+
+## Invariants
+
+These hold for every environment. A change that breaks one is a defect, not a
+configuration choice.
+
+{{RUNTIME_INVARIANTS}}