superdev-cli 0.1.0

package/skills/docs/assets/fragments/async/scheduler.md

@@ -0,0 +1,13 @@
+# Fragment: Scheduled Jobs
+
+**Activates on evidence:** cron expressions, scheduler configuration, or scheduled-task definitions - record the paths found. Or an accepted decision.
+
+**Fills:** the mechanism sections of the jobs/webhooks template.
+
+## Sections supplied
+
+- **Schedule table:** each job with its cron/interval, timezone (explicit - DST behavior stated), and expected duration.
+- **Overlap policy:** what happens if a run outlasts its interval (skip, queue, run concurrently) - configured, not assumed.
+- **Missed-run policy:** behavior after downtime (catch up vs skip) per job.
+- **Idempotency:** every scheduled job safe to re-run, or its guard documented.
+- **Monitoring:** how a silently-not-running schedule is detected (heartbeat, last-run tracking).

package/skills/docs/assets/fragments/auth/detected-provider.md

@@ -0,0 +1,15 @@
+# Fragment: Authentication - Detected Provider
+
+**Activates on evidence:** a specific auth provider/library in the project (SDK dependency, provider configuration, callback routes) - record the exact evidence. Or an accepted decision. Applies **on top of** the neutral base, filling in provider-specific mechanics.
+
+**Fills:** provider-specific subsections of the auth sections.
+
+## Sections supplied
+
+- **Provider identity:** the detected provider/library and where it is configured (evidence paths).
+- **Managed vs owned:** which parts the provider manages (password storage, MFA, session issuance) vs what the project implements.
+- **Integration points:** callback/webhook routes, middleware, client SDK usage - actual paths.
+- **Configuration surface:** provider settings that change behavior (session lifetime, allowed callback URLs) - names and locations, never secret values.
+- **Migration/exit notes:** what switching providers would touch (recorded honestly as coupling).
+
+**Rule:** the provider's name appears in documentation only through this fragment - universal templates stay provider-free.

package/skills/docs/assets/fragments/auth/neutral-base.md

@@ -0,0 +1,14 @@
+# Fragment: Authentication - Neutral Base
+
+**Activates on evidence:** any authentication machinery in the project (sign-in flows, session/token handling, auth middleware or guards) - record the paths found. Or an accepted decision. Always the starting point when any auth exists; provider-specific detail comes from `detected-provider.md` on top of this base - never instead of it.
+
+**Fills:** auth-related sections of foundations, API, and permissions templates.
+
+## Sections supplied
+
+- **Identity model:** what a user/account/principal is; multi-account and service-principal cases.
+- **Session/credential shape:** session cookie, token, or key - lifetime, renewal, revocation semantics (capability level).
+- **Authentication flows:** sign-up, sign-in, sign-out, recovery, and (if present) MFA - as flows, per the workflow template.
+- **Authorization handoff:** where authenticated identity meets the permission matrices (the enforcement points).
+- **Session edge cases:** expiry mid-flow, revoked-while-active, role-changed-mid-session (edge-case categories 4, 16).
+- **Secret handling:** credentials and signing material are named by location, never printed.

package/skills/docs/assets/fragments/data/document.md

@@ -0,0 +1,13 @@
+# Fragment: Document Store
+
+**Activates on evidence:** document-database client configuration and collection access code - record the paths found. Or an accepted decision.
+
+**Fills:** the "Persistence specifics" section of the data template.
+
+## Sections supplied
+
+- **Collection shape:** collection per entity group; document structure cited from the validation schema or the writing code.
+- **Denormalization rules:** what is duplicated where, and which copy is authoritative; update propagation for each duplicate.
+- **Schema enforcement:** validator rules if the store supports them, else the application-level validation source.
+- **Indexes:** defined indexes and the queries they serve.
+- **Consistency:** read/write concern settings and what staleness consumers must tolerate.

package/skills/docs/assets/fragments/data/external-saas.md

@@ -0,0 +1,13 @@
+# Fragment: External SaaS Persistence
+
+**Activates on evidence:** data stored primarily in a third-party service (SDK configuration, API-based data access as the system of record) - record the paths found. Or an accepted decision.
+
+**Fills:** the "Persistence specifics" section of the data template.
+
+## Sections supplied
+
+- **System of record:** which entities live in the external service vs locally; the boundary stated per entity.
+- **Vendor-owned schema:** fields controlled by the vendor vs custom fields; what the project can and cannot change.
+- **Sync:** how local copies (if any) stay current - webhooks, polling, on-demand - and their staleness window.
+- **Failure mode:** behavior when the service is unavailable (degrade, queue, fail) per operation.
+- **Export/exit:** what data can be exported and how, recorded honestly (lock-in is a documented risk, not a surprise).

package/skills/docs/assets/fragments/data/key-value.md

@@ -0,0 +1,13 @@
+# Fragment: Key-Value Store
+
+**Activates on evidence:** key-value client configuration and key-construction code - record the paths found. Or an accepted decision.
+
+**Fills:** the "Persistence specifics" section of the data template.
+
+## Sections supplied
+
+- **Key schema:** key construction pattern per data class (prefixes, separators, id components) - collisions are a design defect, document the namespace plan.
+- **Value shape:** serialization format and versioning of stored values.
+- **TTL:** expiry policy per key class; what happens when expired data is requested.
+- **Durability:** whether this store is cache (rebuildable) or record (authoritative) - per key class, explicitly.
+- **Eviction:** behavior under memory pressure for cache classes.

package/skills/docs/assets/fragments/data/none.md

@@ -0,0 +1,12 @@
+# Fragment: No Persistence
+
+**Activates on evidence:** no database or durable store configured - state held in memory, files, or the client only. Or an accepted decision.
+
+**Fills:** the "Persistence specifics" section of the data template.
+
+## Sections supplied
+
+- **Statement:** the project persists no server-side data - recorded explicitly so absence is a fact, not an oversight.
+- **Where state lives:** in-memory (lost on restart - stated), local files (paths, formats), or client-side (storage mechanism, clearing behavior).
+- **Restart behavior:** exactly what is lost and what survives a process restart.
+- **Future trigger:** the revisit condition under which persistence would be introduced (becomes a decision when it happens).

package/skills/docs/assets/fragments/data/sql-orm.md

@@ -0,0 +1,13 @@
+# Fragment: SQL with ORM
+
+**Activates on evidence:** an ORM's model/schema definitions plus a SQL database configuration - record the paths found. Or an accepted decision.
+
+**Fills:** the "Persistence specifics" section of the data template.
+
+## Sections supplied
+
+- **Model ↔ table mapping:** model source file per entity; the model file is the schema contract.
+- **Migration discipline:** the project's migration tool and flow (generate → review → apply); hand-edited or skipped migrations are drift. If the project prohibits a push-style shortcut, that prohibition is recorded here and enforced by validation as *usage* detection, not mention detection.
+- **Constraints in code vs database:** which invariants live in ORM validations vs actual DB constraints - both listed; DB-enforced wins for integrity claims.
+- **Transactions:** the project's transaction convention for multi-entity operations.
+- **Seed/test data:** where seeds live and whether they are safe to run per environment.

package/skills/docs/assets/fragments/data/sql-plain.md

@@ -0,0 +1,13 @@
+# Fragment: SQL without ORM
+
+**Activates on evidence:** SQL DDL files, migration directories with raw SQL, or query files without ORM models - record the paths found. Or an accepted decision.
+
+**Fills:** the "Persistence specifics" section of the data template.
+
+## Sections supplied
+
+- **DDL location:** where table definitions live; the DDL is the schema contract.
+- **Migration discipline:** ordered migration files, naming convention, how applied per environment.
+- **Query layer:** where queries live (query files, repository modules); parameterization required at trust boundaries.
+- **Constraints:** DB-enforced constraints listed per entity; application-enforced invariants listed separately.
+- **Transactions:** explicit transaction boundaries for multi-statement operations.

package/skills/docs/assets/fragments/env/conventional.md

@@ -0,0 +1,13 @@
+# Fragment: Environments - Conventional Env Files
+
+**Activates on evidence:** conventional env files (`.env*` patterns, env example/template files) - record filenames only. Or an accepted decision.
+
+**Fills:** environment sections of foundations and operational docs.
+
+## Sections supplied
+
+- **File inventory:** which env files exist per environment, which are committed (examples/templates only) vs ignored.
+- **Variable inventory:** variable **names** with purpose, sourced from the example file or a typed env schema if the project has one; values never appear.
+- **Validation:** where env validation happens (typed schema, startup checks) if present.
+- **Documented rules:** real env files stay uncommitted; the example file is maintained as variables change (drift check); secrets referenced by name only.
+- **Precedence:** process env vs file vs defaults, as the project's loader actually resolves them.

package/skills/docs/assets/fragments/env/envx.md

@@ -0,0 +1,13 @@
+# Fragment: Environments - envx-Managed Secrets
+
+**Activates on evidence:** envx markers (encrypted stage files such as `*.gpg` env files, an envx configuration file) - presence checks only; never decrypt to detect. Or an accepted decision.
+
+**Fills:** environment sections of foundations and operational docs.
+
+## Sections supplied
+
+- **Stages:** the stage names that exist (from encrypted filenames) - names only.
+- **Run convention:** commands execute through `envx run -e <stage> -- <command>`; documented as the project's standard invocation.
+- **Variable inventory:** variable **names** per stage where discoverable without decryption; values never appear anywhere.
+- **Rules recorded:** no decrypting to inspect; no printing decrypted content; no committing plaintext stages; missing-access failures distinguished from application failures.
+- **Onboarding pointer:** how a new developer gets access (key exchange procedure location), without reproducing key material.

package/skills/docs/assets/fragments/env/managed-platform.md

@@ -0,0 +1,13 @@
+# Fragment: Environments - Platform-Managed Configuration
+
+**Activates on evidence:** environment configuration held in a deployment platform (platform config files declaring env bindings, dashboard-managed settings referenced in docs/code) - record the evidence. Or an accepted decision.
+
+**Fills:** environment sections of foundations and operational docs.
+
+## Sections supplied
+
+- **Where configuration lives:** the platform and scope (project/environment level) - names, never values.
+- **Environment map:** the platform's environments and how they map to the project's stages.
+- **Sync procedure:** how local development obtains configuration (platform CLI pull, generated local file) and which direction is authoritative.
+- **Change procedure:** who changes platform config and how changes are recorded (a config change is an operations change class).
+- **Secret rotation:** the rotation path for platform-held secrets, recorded as procedure without values.

package/skills/docs/assets/fragments/env/none.md

@@ -0,0 +1,11 @@
+# Fragment: Environments - No Environment Configuration
+
+**Activates on evidence:** no environment files, no platform config, no stage handling - behavior identical everywhere it runs. Or an accepted decision.
+
+**Fills:** environment sections of foundations.
+
+## Sections supplied
+
+- **Statement:** the project has no environment-dependent configuration - recorded explicitly.
+- **Implications:** any future secret or per-environment value introduces this axis (becomes a decision; the env fragment set is the menu).
+- **Hardcoded-value check:** confirm nothing secret-shaped is hardcoded in lieu of configuration (a finding if it is).

package/skills/docs/assets/fragments/ui/api-only.md

@@ -0,0 +1,13 @@
+# Fragment: API-Only (no first-party UI)
+
+**Activates on evidence:** no first-party user interface - the API is the product. Or an accepted decision.
+
+**Fills:** delivery-shape sections of foundations.
+
+## Sections supplied
+
+- **Statement:** no first-party UI exists - recorded explicitly; consumers are integrators.
+- **Developer experience as the surface:** API reference completeness, error message quality, and onboarding examples take the role UI polish plays elsewhere.
+- **Consumer scenarios:** the integration flows (per the workflow template) that replace user flows.
+- **Versioning and deprecation:** public-contract discipline (edge-case category 20) is the primary compatibility story.
+- **UI steps in the module loop:** marked `N/A - API-only delivery shape` deliberately, per the loop's N/A rule.

package/skills/docs/assets/fragments/ui/cli.md

@@ -0,0 +1,14 @@
+# Fragment: CLI
+
+**Activates on evidence:** a command-line interface (bin entries, command definitions, argument parsers) - record the paths found. Or an accepted decision.
+
+**Fills:** delivery-shape sections of foundations; commands take the place of surfaces in the inventories.
+
+## Sections supplied
+
+- **Command inventory:** every command/subcommand with purpose, flags, arguments - the CLI's action inventory.
+- **Output contract:** human output vs machine output (`--json`), exit codes with meanings, stderr conventions.
+- **Input handling:** stdin, config files, environment variables (names only) and their precedence.
+- **Interactivity:** prompts and their non-interactive equivalents (CI-safety).
+- **Destructive commands:** confirmation behavior and `--force`/dry-run conventions.
+- **Paths:** behavior with spaces, relative vs absolute, cross-platform separators.

package/skills/docs/assets/fragments/ui/desktop.md

@@ -0,0 +1,14 @@
+# Fragment: Desktop UI
+
+**Activates on evidence:** a desktop app project (desktop framework config, packaging targets, native menus) - record the paths found. Or an accepted decision.
+
+**Fills:** delivery-shape sections of foundations and the surfaces/actions inventories.
+
+## Sections supplied
+
+- **Window model:** single/multi-window, tray presence, menu structure.
+- **Platform scope:** OS targets and per-OS conventions honored (shortcuts, menu placement).
+- **Filesystem access:** what it reads/writes locally, where, and cleanup.
+- **Offline/local-first:** typically the default for desktop - sync behavior if a server exists.
+- **Updates:** auto-update mechanism and failure behavior.
+- **OS integration:** protocol handlers, file associations, notifications - each with evidence.

package/skills/docs/assets/fragments/ui/mobile.md

@@ -0,0 +1,14 @@
+# Fragment: Mobile UI
+
+**Activates on evidence:** a mobile app project (native project files, cross-platform framework config, store metadata) - record the paths found. Or an accepted decision.
+
+**Fills:** delivery-shape sections of foundations and the surfaces/actions inventories.
+
+## Sections supplied
+
+- **Navigation model:** stack/tab/drawer structure - the navigation source is the surface inventory's evidence.
+- **Platform scope:** which OS platforms, minimum versions, and any platform-conditional behavior (each with its reason).
+- **Offline behavior:** in scope by default question for mobile - queued actions, sync, conflicts (edge-case category 17 rarely N/A here).
+- **Permissions:** device permissions used (camera, location, notifications) with their request timing and denial states.
+- **Lifecycle:** background/foreground transitions, state restoration after kill, deep links.
+- **Update strategy:** store release vs over-the-air, and version-skew tolerance with the API (edge-case category 20).

package/skills/docs/assets/fragments/ui/web.md

@@ -0,0 +1,14 @@
+# Fragment: Web UI
+
+**Activates on evidence:** a web frontend (framework config, page/component tree, bundler setup) - record the paths found. Or an accepted decision.
+
+**Fills:** delivery-shape sections of foundations and the surfaces/actions inventories.
+
+## Sections supplied
+
+- **Routing model:** how routes map to surfaces (file-based, config-based) - the routing source is the surface inventory's evidence.
+- **Rendering:** the project's actual model (server-rendered, client, hybrid) and what it means for loading states.
+- **Responsive scope:** breakpoints in scope; behavior class per surface.
+- **Offline scope:** in scope or deliberately N/A (drives edge-case category 17).
+- **URL state:** what persists in URLs, back-button behavior (module-decomposition step 17 applies fully).
+- **Accessibility baseline:** keyboard reachability, focus management, accessible names - always in scope for web.

package/skills/docs/assets/templates/adr.md

@@ -0,0 +1,62 @@
+<!-- Template: decision record. Fields per the shared talks schema; bodies immutable
+     after acceptance - status/banner/cross-refs are the only later edits. -->
+# {{ADR-id}}: {{title}}
+
+- **Status:** Proposed | Accepted | Rejected | Deprecated | Partially superseded | Superseded | Time-boxed experiment | Revisit required
+- **Date:** {{date}}
+- **Owner/approver:** {{who}}
+- **Scope:** {{what-this-governs}}
+- **Supersedes:** {{ids-or-none}}
+- **Superseded by:** {{id-or-empty}}
+- **Partially supersedes:** {{id+exact-scope-or-none}}
+- **Expiry:** {{date-if-time-boxed}}
+
+## Context
+
+{{problem-constraints-forces}}
+
+## Evidence
+
+{{findings-with-epistemic-labels-and-sources}}
+
+## Decision criteria
+
+{{what-a-good-option-must-satisfy}}
+
+## Options considered
+
+1. **{{option}}** - {{pros}} / {{cons}} / {{why-not-if-rejected}}
+
+## Decision
+
+{{the-choice-stated-plainly}}
+
+## Rationale
+
+{{observable-reasoning: criteria-applied, tradeoffs-accepted}}
+
+## Consequences
+
+- Positive: {{gains}}
+- Negative: {{costs-accepted}}
+- Neutral: {{shifts}}
+
+## Risks
+
+{{risks-and-mitigations}}
+
+## Enforcement
+
+{{where-this-decision-is-enforced: validator-rule / checklist / code-location}}
+
+## Verification
+
+{{how-we-know-it-worked}}
+
+## Revisit triggers
+
+{{concrete-conditions-that-reopen-this}}
+
+## Related
+
+{{links-to-specs-features-decisions}}

package/skills/docs/assets/templates/api.md

@@ -0,0 +1,30 @@
+<!-- Template: API operation. Universal core - style specifics come from the active
+     API fragment (rest/graphql/rpc/events/local-only), never assumed. -->
+# API: {{operation-name}}
+
+- **Status:** draft | accepted | implemented
+- **Module:** {{owning-module}}
+- **Style:** {{from-active-fragment}}
+- **Implemented at:** {{code-path}}
+- **Last verified:** {{revision}} on {{date}}
+
+## Contract
+
+- **Purpose:** {{what-it-does}}
+- **Callers:** {{surfaces/actions/systems}}
+- **Auth:** {{requirement-and-permission}} - enforced at {{enforcement-point}}
+- **Request:** {{fields-validation-limits}}
+- **Response (success):** {{shape}}
+- **Errors:** {{code → meaning → user-facing-behavior}}
+- **Idempotency:** {{key/semantics-or-deliberate-none}}
+- **Limits:** {{rate/size-from-evidence-or-none-declared}}
+- **Side effects:** {{events-jobs-notifications}}
+- **Versioning:** {{compatibility-expectations}}
+
+## Style specifics
+
+{{filled-by-active-fragment-section}}
+
+## Tests
+
+{{test-references}}

package/skills/docs/assets/templates/architecture.md

@@ -0,0 +1,52 @@
+<!-- Template: architecture overview. Universal - diagram nodes use the project's
+     real names from evidence; no invented vendors or stacks. -->
+# {{project-name}} - Architecture
+
+- **Status:** draft | accepted
+- **Last verified:** {{revision}} on {{date}}
+
+## Shape
+
+{{one-paragraph-system-shape}}
+
+## System context
+
+```mermaid
+graph LR
+  {{actor}} --> {{system}}
+  {{system}} --> {{external-dependency-from-evidence}}
+```
+*Claim: {{what-this-diagram-asserts}}*
+
+## Runtime pieces
+
+| Piece | Runs where | Talks to | Evidence |
+|---|---|---|---|
+| {{piece}} | {{runtime}} | {{peers}} | {{path}} |
+
+## Module map
+
+```mermaid
+graph TD
+  {{module-a}} --> {{module-b}}
+```
+*Claim: {{dependency-direction-assertion}}*
+
+## Data ownership
+
+| Entity group | Owning module | Consumers |
+|---|---|---|
+| {{entities}} | {{module}} | {{consumers}} |
+
+## Critical path
+
+```mermaid
+sequenceDiagram
+  {{actor}}->>{{surface}}: {{action}}
+  {{surface}}->>{{handler}}: {{operation}}
+```
+*Claim: {{the-flow-the-product-exists-for}}*
+
+## Boundaries and constraints
+
+- {{boundary-or-constraint-with-evidence-or-adr}}

package/skills/docs/assets/templates/change-impact-drift-report.md

@@ -0,0 +1,29 @@
+<!-- Template: change-impact / drift report. Generated view - regeneration-marked,
+     rebuildable, never hand-edited as authority. -->
+<!-- REGENERATED - do not hand-edit. Source: change entries + validation run {{run-id}} -->
+# {{project-name}} - Change Impact / Drift Report
+
+- **Generated:** {{date}} against {{revision}}
+- **Scope:** {{diff-or-full-tree}}
+
+## Change impact
+
+| Changed path | Class | Affected artifacts | Status |
+|---|---|---|---|
+| {{path}} | {{change-class}} | {{artifacts}} | updated / pending / deferred({{tracked-entry}}) |
+
+## Drift findings
+
+| # | Class | Evidence (code side) | Evidence (doc side) | Resolution owner |
+|---|---|---|---|---|
+| {{n}} | {{drift-class}} | {{path:line}} | {{doc-path}} | code / docs / decision |
+
+## Contradictions still open
+
+| Since | Sides | Blocking? |
+|---|---|---|
+| {{date}} | {{a-vs-b}} | {{yes/no}} |
+
+## Pending sync (blocks completion of the causing change)
+
+{{list-or-none}}

package/skills/docs/assets/templates/compliance.md

@@ -0,0 +1,29 @@
+<!-- Template: compliance. ONLY declared regimes (recorded decisions) - never
+     inferred from geography or vertical. No regime declared => say exactly that. -->
+# {{project-name}} - Compliance
+
+- **Status:** draft | accepted
+- **Declared regimes:** {{list-with-declaring-decision-ids - or "none declared"}}
+- **Last verified:** {{revision}} on {{date}}
+
+## Regulated data inventory (per declared regime)
+
+| Entity.field | Class under {{regime}} | Modules touching it |
+|---|---|---|
+| {{entity.field}} | {{class}} | {{modules}} |
+
+## Handling rules
+
+| Concern | Rule | Enforced at |
+|---|---|---|
+| Encryption at rest | {{rule}} | {{evidence}} |
+| Encryption in transit | {{rule}} | {{evidence}} |
+| Access control | {{rule}} | {{permission-matrix-link}} |
+| Retention | {{rule-from-decision}} | {{enforcement}} |
+| Subject rights (access/export/delete) | {{supported-operations}} | {{code-paths}} |
+
+## Gaps (open items)
+
+| Gap | Risk | Owner decision needed |
+|---|---|---|
+| {{gap}} | {{risk}} | {{question}} |

package/skills/docs/assets/templates/data-schema.md

@@ -0,0 +1,43 @@
+<!-- Template: data entity. Universal core - persistence specifics come from the
+     active data fragment. Schema source files outrank this prose. -->
+# Entity: {{entity-name}}
+
+- **Status:** draft | accepted | implemented
+- **Owning module:** {{module}}
+- **Schema source:** {{schema-file-path}}
+- **Last verified:** {{revision}} on {{date}}
+
+## Purpose
+
+{{what-this-entity-represents}}
+
+## Fields
+
+| Field | Type | Null | Default | Constraints | Sensitivity |
+|---|---|---|---|---|---|
+| {{field}} | {{type}} | {{y/n}} | {{default}} | {{constraints}} | {{none/personal/secret/regulated-under-declared-regime}} |
+
+## Relationships
+
+| Relation | Target | Cardinality | On delete |
+|---|---|---|---|
+| {{relation}} | {{entity}} | {{1:n}} | {{cascade/restrict/null}} |
+
+## Lifecycle
+
+- **Created by:** {{operations}}
+- **Updated by:** {{operations}}
+- **Deleted:** {{soft/hard-semantics-and-cascades}}
+- **Retention:** {{from-decision-or-none-declared}}
+
+## Indexes and uniqueness
+
+{{from-schema-evidence}}
+
+## Persistence specifics
+
+{{filled-by-active-fragment-section}}
+
+## Migration notes
+
+{{pending-or-completed-migrations-affecting-this-entity}}

package/skills/docs/assets/templates/feature.md

@@ -0,0 +1,43 @@
+<!-- Template: feature specification. Three tiers; fill the tier the risk selects.
+     Microspec = the whole first section. Standard and Full add their sections. -->
+# Feature: {{feature-name}}
+
+- **Status:** draft | accepted | implemented
+- **Depth:** microspec | standard | full
+- **Module:** {{owning-module}}
+- **Risk notes:** {{what-drove-the-depth-choice}}
+
+## Microspec (always)
+
+- **Purpose:** {{why-this-exists}}
+- **User:** {{who-and-goal}}
+- **Scope:** in: {{in}} · out: {{out}}
+- **Primary flow:** {{numbered-steps}}
+- **Acceptance criteria:** {{testable-criteria}}
+- **Affected files/contracts:** {{paths-and-contracts}}
+- **Error and edge behavior:** {{from-edge-case-walk - applicable categories, N/A deliberate}}
+- **Test evidence:** {{planned-tests-and-where-results-live}}
+
+## Standard (adds)
+
+- **Surfaces and actions:** {{link-to-inventory}}
+- **API/data impact:** {{operations-and-entities}}
+- **Roles and permissions:** {{matrix-delta}}
+- **Workflow and states:** {{flow-and-state-changes}}
+- **Non-happy paths:** {{failure-flows}}
+- **Observability:** {{signals-that-prove-it-works}}
+- **Rollout:** {{flag/staged/at-once-and-why}}
+- **Test plan:** {{detailed-cases}}
+
+## Full (adds)
+
+- **Alternatives:** {{options-with-decision-matrix}}
+- **Architecture:** {{design-and-diagrams}}
+- **Migrations:** {{data/schema-migration-plan}}
+- **Security/privacy/compliance:** {{analysis-under-declared-regimes}}
+- **Performance/capacity:** {{evidence-based}}
+- **Failure recovery:** {{what-breaks-and-how-it-recovers}}
+- **Rollback:** {{how-to-undo}}
+- **Operations:** {{runbook-deltas}}
+- **Compatibility:** {{public-contract-impacts}}
+- **Decision records:** {{adrs-created}}

package/skills/docs/assets/templates/foundations.md

@@ -0,0 +1,55 @@
+<!-- Template: project foundations. Universal - no vendors, frameworks, budgets,
+     regions, or compliance regimes may be pre-filled; capability slots are filled
+     by active fragments with evidence. Placeholders use {{double-braces}}. -->
+# {{project-name}} - Foundations
+
+- **Status:** draft | accepted
+- **Last verified:** {{revision}} on {{date}}
+
+## Product
+
+{{what-it-is-one-paragraph}}
+
+**Problem:** {{problem-statement}}
+**Non-goals:** {{explicit-non-goals}}
+
+## Users and roles
+
+| Role | Who | Primary goals |
+|---|---|---|
+| {{role}} | {{who}} | {{goals}} |
+
+## Scope
+
+**In (current horizon):**
+1. {{in-scope-item}}
+
+**Out (deliberate):**
+1. {{out-of-scope-item}} - {{why}}
+
+## Architecture
+
+{{system-shape-summary}}
+
+Diagrams (per the diagram catalogue): system context · {{other-required-diagrams}}
+
+## Stack (capability slots - filled by evidence or accepted decision only)
+
+| Capability | Choice | Evidence / decision |
+|---|---|---|
+| Delivery shape | {{web/mobile/desktop/cli/api-only}} | {{evidence-path-or-adr}} |
+| Persistence | {{style-or-none}} | {{evidence-path-or-adr}} |
+| API style | {{style-or-none}} | {{evidence-path-or-adr}} |
+| Async | {{mechanism-or-none}} | {{evidence-path-or-adr}} |
+| Auth | {{approach-or-none}} | {{evidence-path-or-adr}} |
+| Environments | {{env-handling}} | {{evidence-path-or-adr}} |
+
+## Design direction
+
+{{pointer-to-design-system-or-deliberate-none}}
+
+## Glossary
+
+| Term | Meaning |
+|---|---|
+| {{term}} | {{one-meaning}} |

package/skills/docs/assets/templates/jobs-webhooks.md

@@ -0,0 +1,36 @@
+<!-- Template: async jobs and webhooks. Mechanism specifics come from the active
+     async fragment; "none" is a deliberate statement. -->
+# {{job-or-webhook-name}}
+
+- **Status:** draft | accepted | implemented
+- **Module:** {{owning-module}}
+- **Mechanism:** {{from-active-async-fragment-or-none}}
+- **Last verified:** {{revision}} on {{date}} against {{code-paths}}
+
+## Async job
+
+- **Trigger:** {{schedule/event/enqueue}}
+- **Input:** {{contract}}
+- **Idempotency:** {{safe-to-re-run?-how}}
+- **Retry:** {{policy-and-backoff}}
+- **Failure destination:** {{dead-letter/park/alert}}
+- **Timeout:** {{limit-and-behavior}}
+- **Concurrency:** {{limits}}
+- **Observability:** {{how-a-stuck-job-is-noticed}}
+- **Delivery guarantee:** {{at-least-once/at-most-once - stated honestly}}
+
+## Incoming webhook
+
+- **Endpoint:** {{route}}
+- **Sender verification:** {{signature-scheme-from-evidence}}
+- **Replay protection:** {{idempotency-mechanism}}
+- **Ordering:** {{assumption-and-out-of-order-handling}}
+- **Failure semantics:** {{what-triggers-sender-retry}}
+- **Payload versioning:** {{handling}}
+
+## Outgoing webhook
+
+- **Registration:** {{how-subscribers-register}}
+- **Delivery:** {{guarantees-retry-backoff}}
+- **Signing:** {{scheme}}
+- **Failure visibility:** {{operator-view}}