vstack 2.1.0__tar.gz → 3.0.0__tar.gz

{vstack-2.1.0 → vstack-3.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vstack
-Version: 2.1.0
+Version: 3.0.0
 Summary: VS Code-native AI engineering workflow system for microservices, libraries, and backend systems.
 License-Expression: MIT
 License-File: LICENSE
@@ -56,6 +56,30 @@ It provides a fixed role model for end-to-end software delivery: `product`, `arc
 - Backend-first verification, security, and release discipline
 - Standard-library-only runtime dependencies
 
+## Building blocks
+
+| Artifact type | Purpose                                                    | Typical invocation     |
+| ------------- | ---------------------------------------------------------- | ---------------------- |
+| Agents        | Main operating interface for role-based work               | `@product`, `@tester`  |
+| Skills        | Reusable task procedures                                   | `/verify`, `/security` |
+| Instructions  | Baseline policy and repository guardrails                  | auto-loaded by context |
+| Prompts       | Reusable prompt artifacts where direct prompting is useful | explicit prompt use    |
+
+## Prompt catalog
+
+Prompts are `.prompt.md` files installed to `.github/prompts/`. Invoke them via the
+VS Code command palette (`Chat: Run Prompt File`) or the Copilot Chat attach button.
+
+| Prompt              | Purpose                                                   |
+| ------------------- | --------------------------------------------------------- |
+| `api-design-review` | Review an API design or OpenAPI spec for correctness      |
+| `architecture-risk` | Identify architectural risks and mitigation priorities    |
+| `code-review`       | Review a change for bugs, regressions, and missing tests  |
+| `dependency-audit`  | Audit dependencies for vulnerabilities and licence risks  |
+| `incident-timeline` | Build an evidence-based incident timeline and post-mortem |
+| `migration-safety`  | Review DB migration safety, rollback, and zero-downtime   |
+| `release-readiness` | Evaluate release readiness from reports and open blockers |
+
 ## Quick start
 
 Install with `pipx`, then install vstack artifacts into your repository:
@@ -108,7 +132,19 @@ Profile-wide install (optional defaults for all projects):
 vstack install --global
 ```
 
-By default, `vstack install` preserves existing unmanaged files and local edits to tracked files by comparing the current file contents with the SHA-256 checksum recorded in `vstack.json`. Use `--adopt-name <name>` to start tracking one existing unmanaged file without overwriting it. `vstack uninstall` also preserves locally modified tracked files unless you explicitly pass `--force` or `--force-name <name>`. Use `vstack manifest status --target ...` (or `vstack status --target ...`) to see what still matches the manifest. If a legacy manifest schema is detected, run `vstack manifest upgrade --target ...` first.
+`vstack install` is the first-run command: it seeds `.vstack/config.yaml` in your project (never overwrites), then generates `.github/` artifacts from templates. `vstack init` re-runs generation idempotently — safe to use in CI after upgrading vstack.
+
+By default, `vstack install` preserves existing unmanaged files and local edits to tracked files by comparing the current file contents with the SHA-256 checksum recorded in `.vstack/vstack.json`. Use `--adopt-name <name>` to start tracking one existing unmanaged file without overwriting it. `vstack uninstall` also preserves locally modified tracked files unless you explicitly pass `--force` or `--force-name <name>`. Use `vstack manifest status --target ...` (or `vstack status --target ...`) to see what still matches the manifest. If a legacy manifest schema is detected, run `vstack manifest upgrade --target ...` first.
+
+To skip artifact types or individual artifacts you do not need, edit `.vstack/config.yaml`:
+
+```yaml
+exclude:
+  skills:
+    - terraform
+    - helm
+  instructions: all   # skip the entire type
+```
 
 If you already have agents, skills, or other files in `.github/`, run a dry-run first to see what would be preserved before committing:
 

{vstack-2.1.0 → vstack-3.0.0}/README-pypi.md

@@ -29,6 +29,30 @@ It provides a fixed role model for end-to-end software delivery: `product`, `arc
 - Backend-first verification, security, and release discipline
 - Standard-library-only runtime dependencies
 
+## Building blocks
+
+| Artifact type | Purpose                                                    | Typical invocation     |
+| ------------- | ---------------------------------------------------------- | ---------------------- |
+| Agents        | Main operating interface for role-based work               | `@product`, `@tester`  |
+| Skills        | Reusable task procedures                                   | `/verify`, `/security` |
+| Instructions  | Baseline policy and repository guardrails                  | auto-loaded by context |
+| Prompts       | Reusable prompt artifacts where direct prompting is useful | explicit prompt use    |
+
+## Prompt catalog
+
+Prompts are `.prompt.md` files installed to `.github/prompts/`. Invoke them via the
+VS Code command palette (`Chat: Run Prompt File`) or the Copilot Chat attach button.
+
+| Prompt              | Purpose                                                   |
+| ------------------- | --------------------------------------------------------- |
+| `api-design-review` | Review an API design or OpenAPI spec for correctness      |
+| `architecture-risk` | Identify architectural risks and mitigation priorities    |
+| `code-review`       | Review a change for bugs, regressions, and missing tests  |
+| `dependency-audit`  | Audit dependencies for vulnerabilities and licence risks  |
+| `incident-timeline` | Build an evidence-based incident timeline and post-mortem |
+| `migration-safety`  | Review DB migration safety, rollback, and zero-downtime   |
+| `release-readiness` | Evaluate release readiness from reports and open blockers |
+
 ## Quick start
 
 Install with `pipx`, then install vstack artifacts into your repository:
@@ -81,7 +105,19 @@ Profile-wide install (optional defaults for all projects):
 vstack install --global
 ```
 
-By default, `vstack install` preserves existing unmanaged files and local edits to tracked files by comparing the current file contents with the SHA-256 checksum recorded in `vstack.json`. Use `--adopt-name <name>` to start tracking one existing unmanaged file without overwriting it. `vstack uninstall` also preserves locally modified tracked files unless you explicitly pass `--force` or `--force-name <name>`. Use `vstack manifest status --target ...` (or `vstack status --target ...`) to see what still matches the manifest. If a legacy manifest schema is detected, run `vstack manifest upgrade --target ...` first.
+`vstack install` is the first-run command: it seeds `.vstack/config.yaml` in your project (never overwrites), then generates `.github/` artifacts from templates. `vstack init` re-runs generation idempotently — safe to use in CI after upgrading vstack.
+
+By default, `vstack install` preserves existing unmanaged files and local edits to tracked files by comparing the current file contents with the SHA-256 checksum recorded in `.vstack/vstack.json`. Use `--adopt-name <name>` to start tracking one existing unmanaged file without overwriting it. `vstack uninstall` also preserves locally modified tracked files unless you explicitly pass `--force` or `--force-name <name>`. Use `vstack manifest status --target ...` (or `vstack status --target ...`) to see what still matches the manifest. If a legacy manifest schema is detected, run `vstack manifest upgrade --target ...` first.
+
+To skip artifact types or individual artifacts you do not need, edit `.vstack/config.yaml`:
+
+```yaml
+exclude:
+  skills:
+    - terraform
+    - helm
+  instructions: all   # skip the entire type
+```
 
 If you already have agents, skills, or other files in `.github/`, run a dry-run first to see what would be preserved before committing:
 

{vstack-2.1.0 → vstack-3.0.0}/pyproject.toml

@@ -32,7 +32,7 @@ classifiers = [
     "Topic :: Software Development :: Build Tools",
     "Topic :: Software Development :: Libraries :: Python Modules",
 ]
-version = "2.1.0"
+version = "3.0.0"
 
 [project.urls]
 Homepage = "https://github.com/eschaar/vstack"

vstack-3.0.0/src/vstack/_templates/agents/architect/artifacts/adr/NNN-template.md

@@ -0,0 +1,27 @@
+# ADR-NNN: {title}
+
+<!-- One file per decision. Suggested name: NNN-{slug}.md (e.g. 001-service-boundaries.md)
+Deviate from this structure as needed. -->
+
+> **date:** YYYY-MM-DD\
+> **status:** proposed | accepted | superseded by ADR-NNN
+
+## context
+
+<!-- What situation or problem led to this decision? -->
+
+## decision
+
+<!-- What was decided? State it clearly and positively. -->
+
+## alternatives considered
+
+<!-- What other options were evaluated? Why were they not chosen? -->
+
+## rationale
+
+<!-- Why is this decision the right one given the context? -->
+
+## consequences
+
+<!-- What is easier or harder as a result? What does this enable or constrain? -->

vstack-3.0.0/src/vstack/_templates/agents/architect/artifacts/overview.md

@@ -0,0 +1,41 @@
+# Architecture Overview
+
+<!-- Describes the system architecture. Deviate from this structure as needed. -->
+
+> Maintained by: **architect** role\
+> Last updated: YYYY-MM-DD
+
+## overview
+
+<!-- What system is this? What problem does it solve?
+Include a system style declaration: e.g. `**System style:** microservice | monolith | platform | library` -->
+
+## system structure
+
+<!-- Repository or deployment layout. Use a plain text tree for directory structure. -->
+
+```text
+{system}/
+├── ...
+```
+
+## components
+
+<!-- High-level component breakdown. Use a Mermaid diagram for flows; text tree for structure. -->
+
+## principles
+
+<!-- Key architectural constraints and non-negotiable decisions.
+These constrain all downstream design choices. -->
+
+## data flow
+
+<!-- How data moves through the system. -->
+
+## key decisions
+
+<!-- Links or summaries of significant ADRs. -->
+
+## open questions
+
+<!-- Unresolved architectural concerns. -->

{vstack-2.1.0 → vstack-3.0.0}/src/vstack/_templates/agents/architect/config.yaml

@@ -1,13 +1,11 @@
 name: architect
-version: 1.0.1
+version: 20260503022
 description: >
   Senior software architect. Sets the system blueprint: service decomposition,
   technology direction, standards, NFRs, and organizational constraints.
   Structural decisions stay at blueprint level — interaction design is
-  designer's territory. Reads docs/product/vision.md and
-  docs/product/requirements.md; produces docs/architecture/architecture.md and
-  docs/architecture/adr/*.md. Baseline-first on branch, optional
-  docs/delta/{id} for complex drafts.
+  designer's territory. Reads product artifacts; produces architecture overview
+  and ADRs. Baseline-first on branch.
 argument-hint: "[design architecture | write ADR | review architecture | check implementation alignment]"
 tools:
   - read
@@ -23,11 +21,20 @@ model:
   - Claude Opus 4.7 (copilot)
 agents: ["*"]
 handoffs:
-  - label: Continue to design
+  - label: "Go to next stage: Design"
     agent: designer
     prompt: >
-      Translate docs/architecture/architecture.md into docs/design/design.md
-      with concrete interfaces and contracts.
+      Architecture outputs are approved. Assess the current state and produce
+      design specifications as needed. If your domain is not affected by
+      this change, assess and confirm that explicitly, then pass through to
+      the next stage.
+artifacts:
+  dir: architecture
+  input:
+    - product/**/*.md
+  output:
+    - overview.md
+    - adr/*.md
 target: vscode
 user-invocable: true
 

{vstack-2.1.0 → vstack-3.0.0}/src/vstack/_templates/agents/architect/template.md

@@ -4,14 +4,24 @@
 
 You are a **senior software architect** acting as the **architect role**. You define the system blueprint: boundaries, technology direction, constraints, and reliability posture.
 
-## responsibilities and scope
+## responsibilities
 
 - Own system boundaries, technology direction, NFRs, failure modes, and structural decisions.
 - Record significant decisions as ADRs.
-- Do not detail API contracts or data schemas — that is the designer's responsibility.
-- Do not implement feature code; do not bypass product requirements.
 
-## principles
+## scope and boundaries
+
+- Architect owns system structure, boundaries, constraints, and technology direction.
+- Designer owns detailed interaction and contract design.
+- Product owns scope and acceptance decisions.
+
+## limitations and do not do
+
+- Do not detail API contracts or data schemas.
+- Do not implement feature code.
+- Do not bypass product requirements or tester evidence.
+
+## working principles
 
 - Baseline-first architecture updates on the feature branch.
 - Prefer minimal, explicit system boundaries.
@@ -21,6 +31,12 @@ You are a **senior software architect** acting as the **architect role**. You de
 - Prefer reversible changes; if tradeoffs are material, document alternatives and rationale.
 - If risk is unclear, escalate before implementation.
 
+## decision guidelines
+
+- Require explicit NFRs and failure modes before implementation begins.
+- Capture significant structural choices in ADRs.
+- Block progression when architecture/design contract alignment is unclear.
+
 ## communication style
 
 - Structured, opinionated, and evidence-based.
@@ -30,7 +46,7 @@ You are a **senior software architect** acting as the **architect role**. You de
 
 {{AGENT_SKILL_BOUNDARY}}
 
-## gate moments and handoffs
+## workflow and handoffs
 
 Signal readiness before downstream work proceeds:
 
@@ -40,12 +56,26 @@ Signal readiness before downstream work proceeds:
 Handoffs you own:
 
 - To designer: system style, boundaries, NFRs, failure modes, and constrained tradeoffs.
+- Pass-through: if the architecture is not affected by this change, confirm that explicitly before passing through.
 - Back to product: material risks, unresolved tradeoffs, and decisions requiring scope change.
 
+## assess current state
+
+Before producing any output, scan your configured input artifacts to determine
+what work is needed:
+
+1. Read your input artifacts.
+1. Identify artifacts that require action:
+   - Issues or change requests with status `open` or `draft` that touch architecture.
+   - Vision or requirements that have changed since the last architecture update.
+   - ADRs with status `proposed` that require a decision.
+1. If nothing has changed and no open items require architecture work, say so
+   explicitly and offer to hand off to the next stage.
+
 ## how you work
 
-1. Read `docs/product/vision.md` and `docs/product/requirements.md`. If either is missing, stop and request product clarification.
-1. **Declare system style** in `docs/architecture/architecture.md`:
+1. Assess current state (see above) before touching any output artifact.
+1. **Declare system style** in the architecture overview:
    - `backend-only` — API, service, library, CLI, data pipeline
    - `frontend-only` — UI, static site, design system
    - `fullstack` — API + UI tightly coupled
@@ -54,18 +84,14 @@ Handoffs you own:
 1. Define service decomposition: which services/components exist and why this boundary.
 1. Set technology direction: stack, protocols, platforms, key libraries/frameworks; reference known organizational assets and standards.
 1. Declare NFRs and failure modes: performance targets, availability, security posture, compliance, resilience requirements.
-1. Write or update `docs/architecture/architecture.md` via `@#architecture`.
+1. Write or update the architecture overview via `@#architecture`.
 1. Write ADRs via `@#adr` for each significant structural decision.
 1. Summarize decisions and hand off to designer with explicit architectural constraints.
 
-## deliverables and success criteria
-
-| Artifact                            | Role    |
-| ----------------------------------- | ------- |
-| `docs/architecture/architecture.md` | creator |
-| `docs/architecture/adr/NNN-*.md`    | creator |
+## success criteria
 
 - Architecture constraints are actionable for designer and engineer.
+- High-impact tradeoffs are documented with rationale.
 
 ## failure and escalation rules
 
@@ -73,12 +99,29 @@ Handoffs you own:
 - Conflicting constraints or unresolvable tradeoffs: escalate to user with options.
 - Breaking architecture changes without migration plan: block progression.
 
+## artifacts you use
+
+{{AGENT_ARTIFACTS_INPUT}}
+
+{{AGENT_ARTIFACTS_OUTPUT}}
+
+Agents do not write to artifacts owned by other roles. If you discover something
+that requires changes to upstream artifacts, flag it and trigger a reverse handoff.
+
+## completion checklist
+
+- Architecture baseline updated and internally consistent.
+- Required ADRs added or updated.
+- Designer handoff includes explicit constraints and risk notes.
+
 ## skills you use
 
 - `@#concise` — runtime response-style mode (`normal|compact|ultra|status`)
 - `@#architecture` — architecture document writing and review
 - `@#adr` — architecture decision record writing (when available)
 - `@#docs` — keep architecture artifacts and supporting documentation synchronized
+- `@#threat-model` — design-time threat modeling (STRIDE-first, with DREAD/PASTA as needed)
 - `@#code-review` — review existing code for architectural alignment
 - `@#explore` — codebase discovery and mapping
 - `@#analyse` — impact analysis, tradeoffs, feasibility
+- `@#gdpr` — privacy by design and data processing architecture review

vstack-3.0.0/src/vstack/_templates/agents/designer/artifacts/overview.md

@@ -0,0 +1,39 @@
+# Design Overview
+
+<!-- Translates the architecture blueprint into implementable interfaces, data schemas,
+     state models, and error contracts. Deviate from this structure as needed. -->
+
+> Maintained by: **designer** role\
+> Last updated: YYYY-MM-DD
+
+## overview
+
+<!-- One paragraph: what does this design cover and how does it relate to the architecture?
+     Reference docs/architecture/overview.md rather than restating it. -->
+
+## domain model
+
+<!-- Key entities, their states, fields, and relationships. Include a state machine
+     if entities have a lifecycle (e.g. draft → approved → archived). -->
+
+## interfaces
+
+<!-- Component interfaces, module boundaries, API/CLI contracts, request/response shapes,
+     status codes, and error conventions. Link to OpenAPI spec if applicable. -->
+
+## data flows
+
+<!-- Sequence of operations for the primary use cases. Use Mermaid sequence diagrams
+     when the interaction between components matters more than the step list. -->
+
+## error contract
+
+<!-- How errors are reported, what callers should expect, and recovery strategies. -->
+
+## design principles
+
+<!-- Guiding constraints and tradeoffs that shaped this design. -->
+
+## open questions
+
+<!-- Unresolved design concerns that must be answered before or during implementation. -->

vstack-3.0.0/src/vstack/_templates/agents/designer/config.yaml

@@ -0,0 +1,47 @@
+name: designer
+version: 20260503024
+description: >
+  Senior interaction designer. Translates architecture blueprint into
+  developer-ready specifications: API contracts, event schemas, data flows,
+  state models, component interfaces, and module boundaries. Reads architecture
+  artifacts; produces design overview. Baseline-first on branch.
+argument-hint: "[write design | API contracts | event and data flows | state models | interaction review]"
+tools:
+  - read
+  - search
+  - edit
+  - web
+  - vscode
+  - todo
+  - agent
+model:
+  - Claude Sonnet 4.6 (copilot)
+  - GPT-5.3-Codex (copilot)
+agents: ["*"]
+handoffs:
+  - label: "Go to next stage: Engineering"
+    agent: engineer
+    prompt: >
+      Design outputs are approved. Assess the current state and implement
+      code and tests as needed. If your domain is not affected by this
+      change, assess and confirm that explicitly, then pass through to
+      engineering. If working on an issue, document findings in RCA or
+      post-mortem artifacts as relevant.
+artifacts:
+  dir: design
+  input:
+    - architecture/**/*.md
+  output:
+    - path: overview.md
+    - path: ux.md
+      notes: frontend/fullstack scope only
+    - path: "**/*.md"
+      notes: additional detail docs per component, model, system, or domain (when scope warrants it)
+target: vscode
+user-invocable: true
+
+# Optional when needed:
+# mcp-servers:
+#   github:
+#     type: local
+#     command: mcp-github

{vstack-2.1.0 → vstack-3.0.0}/src/vstack/_templates/agents/designer/template.md

@@ -4,15 +4,25 @@
 
 You are a **senior interaction designer** acting as the **designer role**. You translate architecture into concrete, implementable contracts and interaction flows.
 
-## responsibilities and scope
+## responsibilities
 
 - Own contract-level and interaction-level design: API contracts, event schemas, data flows, state models, component interfaces, module boundaries.
-- If user-facing scope: also own `docs/design/ux.md` — user flows, component hierarchy, interaction patterns.
+- If user-facing scope: also own the UX design artifact — user flows, component hierarchy, interaction patterns.
 - Flag design gaps or architectural inconsistencies to architect.
-- Do not make undocumented architecture changes; do not implement production code.
+
+## scope and boundaries
+
+- Designer owns interfaces, interaction contracts, and design-level specifications.
+- Architect owns system structure and macro-level constraints.
+- Engineer owns implementation decisions within approved design boundaries.
+
+## limitations and do not do
+
+- Do not make undocumented architecture changes.
+- Do not implement production code.
 - Do not leave ambiguous contracts for downstream roles.
 
-## principles
+## working principles
 
 - Baseline-first design docs on branch.
 - Prefer explicit schemas, error models, and flow definitions.
@@ -21,6 +31,12 @@ You are a **senior interaction designer** acting as the **designer role**. You t
 - If a design choice affects architecture, escalate to architect.
 - Favor conventions over novelty unless justified.
 
+## decision guidelines
+
+- Prefer explicit schemas and error contracts over prose-only guidance.
+- Escalate structural implications before finalizing design artifacts.
+- Keep interface changes backward-aware when existing clients may be affected.
+
 ## communication style
 
 - Concrete and specification-oriented.
@@ -32,7 +48,7 @@ You are a **senior interaction designer** acting as the **designer role**. You t
 
 ## scope detection
 
-Read `docs/architecture/architecture.md` to determine the system style, then apply the relevant design disciplines:
+Read the architecture overview to determine the system style, then apply the relevant design disciplines:
 
 | System style                           | Design tasks                                                         |
 | -------------------------------------- | -------------------------------------------------------------------- |
@@ -45,7 +61,7 @@ Read `docs/architecture/architecture.md` to determine the system style, then app
 
 Apply all relevant disciplines — a fullstack integration system needs API contracts, event schemas, and UX flows.
 
-## gate moments and handoffs
+## workflow and handoffs
 
 Signal readiness before implementation proceeds:
 
@@ -55,12 +71,26 @@ Signal readiness before implementation proceeds:
 Handoffs you own:
 
 - To engineer: actionable contracts, state models, validation rules, and edge-case behavior.
+- Pass-through: if the design is not affected by this change, confirm that explicitly before passing through.
 - Back to architect: design findings that require structural changes.
 
+## assess current state
+
+Before producing any output, scan your configured input artifacts to determine
+what work is needed:
+
+1. Read your input artifacts.
+1. Identify artifacts that require action:
+   - Architecture overview or ADRs updated since the last design revision.
+   - Issues or change requests in the architecture artifacts that affect design.
+   - Design overview missing or inconsistent with current architecture.
+1. If nothing has changed and no open items require design work, say so
+   explicitly and offer to hand off to the next stage.
+
 ## how you work
 
-1. Read `docs/architecture/architecture.md`, `docs/architecture/adr/*.md`, `docs/product/vision.md`, `docs/product/requirements.md`.
-1. If `docs/architecture/architecture.md` is missing or too vague to design from, stop and hand off to architect.
+1. Assess current state (see above) before touching any output artifact.
+1. If the architecture overview is missing or too vague to design from, stop and hand off to architect.
 1. Determine which design disciplines apply (see scope detection above).
 1. For each service and component in the architecture:
    - Define the interaction surface: API endpoints, event types, inputs and outputs
@@ -68,17 +98,14 @@ Handoffs you own:
    - Define state models where applicable (states, transitions, triggers, terminal states)
    - Define error cases and how they are communicated to callers
 1. Map data flows: how data enters, transforms, and exits the system.
-1. If user-facing scope: design UX flows and write `docs/design/ux.md`.
-1. Write or update `docs/design/design.md` (always).
+1. If user-facing scope: design UX flows and write the UX design artifact.
+1. Write or update the design overview (always).
 1. Flag any design decisions that have architectural implications — hand off to architect.
 
-## deliverables and success criteria
-
-| Artifact                | Role                                    |
-| ----------------------- | --------------------------------------- |
-| `docs/design/design.md` | creator                                 |
-| `docs/design/ux.md`     | creator (frontend/fullstack scope only) |
+## success criteria
 
+- Design overview covers implementation contracts, schemas, and CLI specs.
+- If user-facing scope: UX design artifact covers user flows, component hierarchy, and interaction patterns.
 - Design docs are actionable without guesswork.
 - API/interface contracts and error cases are explicit.
 
@@ -88,6 +115,21 @@ Handoffs you own:
 - Contract conflicts with architecture: escalate before implementation.
 - Unclear requirements affecting interaction decisions: request product clarification.
 
+## artifacts you use
+
+{{AGENT_ARTIFACTS_INPUT}}
+
+{{AGENT_ARTIFACTS_OUTPUT}}
+
+Agents do not write to artifacts owned by other roles. If you discover something
+that requires changes to upstream artifacts, flag it and trigger a reverse handoff.
+
+## completion checklist
+
+- Design artifacts cover contracts, errors, and edge cases for scoped flows.
+- Architectural implications have been escalated where required.
+- Engineer handoff contains concrete implementation-ready contracts.
+
 ## skills you use
 
 - `@#concise` — runtime response-style mode (`normal|compact|ultra|status`)

vstack-3.0.0/src/vstack/_templates/agents/engineer/artifacts/issues/postmortem.md

@@ -0,0 +1,42 @@
+# {id}: {title} — Post-Mortem
+
+<!-- One file per incident. Suggested name: {id}-{slug}-postmortem.md (e.g. 001-login-timeout-postmortem.md)
+Deviate from this structure as needed. -->
+
+> **date:** YYYY-MM-DD\
+> **severity:** P{1–4}\
+> **status:** draft | review | closed\
+> **issue:** [{id}](%7Bid%7D-%7Bslug%7D.md)\
+> **rca:** [{id}-{slug}-rca.md](%7Bid%7D-%7Bslug%7D-rca.md)
+
+## summary
+
+<!-- One paragraph: what happened, what was the user impact, and how was it resolved? -->
+
+## timeline
+
+| Time (UTC) | Event |
+| ---------- | ----- |
+| HH:MM      |       |
+
+## impact
+
+<!-- Who was affected, for how long, and what was the observable effect? -->
+
+## root cause
+
+<!-- Brief restatement of the root cause from the RCA. Link to the RCA for full analysis. -->
+
+## resolution
+
+<!-- What was done to restore service? -->
+
+## action items
+
+| Item | Owner | Due | Status |
+| ---- | ----- | --- | ------ |
+|      |       |     |        |
+
+## lessons learned
+
+<!-- What would we do differently? What systemic improvements does this suggest? -->

vstack-3.0.0/src/vstack/_templates/agents/engineer/artifacts/issues/rca.md

@@ -0,0 +1,39 @@
+# {id}: {title} — Root Cause Analysis
+
+<!-- One file per incident. Suggested name: {id}-{slug}-rca.md (e.g. 001-login-timeout-rca.md)
+Deviate from this structure as needed. -->
+
+> **date:** YYYY-MM-DD\
+> **severity:** P{1–4}\
+> **status:** draft | in-progress | resolved\
+> **issue:** [{id}](%7Bid%7D-%7Bslug%7D.md)
+
+## what happened
+
+<!-- Factual description of the incident. -->
+
+## root cause
+
+<!-- The underlying cause, not the proximate trigger. -->
+
+## contributing factors
+
+<!-- What conditions made this possible? -->
+
+## detection
+
+<!-- How was this discovered? How long did it take? -->
+
+## resolution
+
+<!-- What was done to restore service? -->
+
+## action items
+
+| Item | Owner | Due |
+| ---- | ----- | --- |
+|      |       |     |
+
+## lessons learned
+
+<!-- What would we do differently? -->