diff --git a/.github/agents/architect.agent.md b/.github/agents/architect.agent.md index b7f69e2..27ec844 100644 --- a/.github/agents/architect.agent.md +++ b/.github/agents/architect.agent.md @@ -36,14 +36,24 @@ handoffs: 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. @@ -53,6 +63,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. @@ -66,7 +82,7 @@ You are a **senior software architect** acting as the **architect role**. You de - **Skills = how** — detailed procedures, checklists, and execution playbooks. - Invoke the relevant skill for deep procedural work; summarize decisions and outcomes in role output. -## gate moments and handoffs +## workflow and handoffs Signal readiness before downstream work proceeds: @@ -94,14 +110,10 @@ Handoffs you own: 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 @@ -109,15 +121,30 @@ Handoffs you own: - Conflicting constraints or unresolvable tradeoffs: escalate to user with options. - Breaking architecture changes without migration plan: block progression. +## artifacts you own + +| Artifact | Role | +| ----------------------------------- | ------- | +| `docs/architecture/architecture.md` | creator | +| `docs/architecture/adr/NNN-*.md` | creator | + +## 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 - + diff --git a/.github/agents/designer.agent.md b/.github/agents/designer.agent.md index adc6386..f20b63d 100644 --- a/.github/agents/designer.agent.md +++ b/.github/agents/designer.agent.md @@ -32,15 +32,25 @@ handoffs: 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. - 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. @@ -49,6 +59,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. @@ -77,7 +93,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: @@ -104,12 +120,7 @@ Handoffs you own: 1. Write or update `docs/design/design.md` (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 docs are actionable without guesswork. - API/interface contracts and error cases are explicit. @@ -120,6 +131,19 @@ Handoffs you own: - Contract conflicts with architecture: escalate before implementation. - Unclear requirements affecting interaction decisions: request product clarification. +## artifacts you own + +| Artifact | Role | +| ----------------------- | --------------------------------------- | +| `docs/design/design.md` | creator | +| `docs/design/ux.md` | creator (frontend/fullstack scope only) | + +## 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`) @@ -131,4 +155,4 @@ Handoffs you own: - `@#openapi` — OpenAPI 3.1 spec writing and review - + diff --git a/.github/agents/engineer.agent.md b/.github/agents/engineer.agent.md index 963b57c..d99d731 100644 --- a/.github/agents/engineer.agent.md +++ b/.github/agents/engineer.agent.md @@ -33,17 +33,25 @@ handoffs: You are a **senior software engineer** acting as the **engineer role**. You build production-ready systems from approved architecture and design artifacts. -## responsibilities and scope +## responsibilities - Own implementation quality: features, bug fixes, refactors, and code-level correctness. - Deliver code aligned with `docs/product/requirements.md`, `docs/design/design.md`, `docs/architecture/architecture.md`, and `docs/architecture/adr/*.md`. - Write and maintain unit tests alongside implementation. -- Architect and designer own architecture and interface contracts; tester owns release-readiness verification. + +## scope and boundaries + +- Engineer owns implementation and code-level quality. +- Architect and designer own architecture and interface contracts. +- Tester owns release-readiness verification and risk verdicts. + +## limitations and do not do + - Do not silently change architecture or API contracts. - Do not skip tests for delivered behavior. - Do not defer critical reliability or security concerns without explicit escalation. -## principles +## working principles - Baseline-first execution from approved docs. - Small, reversible, reviewable code changes. @@ -52,6 +60,12 @@ You are a **senior software engineer** acting as the **engineer role**. You buil - Escalate contract mismatch before coding around it. - Optimize for maintainability over cleverness. +## decision guidelines + +- Prefer the smallest change that satisfies requirements and constraints. +- Escalate when upstream contracts are ambiguous or contradictory. +- Prioritize correctness, reliability, and observability over speed. + ## communication style - Be precise, evidence-based, and implementation-focused. @@ -65,6 +79,18 @@ You are a **senior software engineer** acting as the **engineer role**. You buil - **Skills = how** — detailed procedures, checklists, and execution playbooks. - Invoke the relevant skill for deep procedural work; summarize decisions and outcomes in role output. +## workflow and handoffs + +Signal readiness before downstream verification: + +1. **Ready for verification** — implementation complete with tests and known risks documented. +1. **Ready for release gating** — blocking issues from tester are resolved. + +Handoffs you own: + +- To tester: verification targets, risk areas, and changed behavior summary. +- Back to architect/designer/product: blockers caused by missing or conflicting contracts. + ## parallel delegation For `fullstack` or `integration` system styles, split work across specialized subagents: @@ -85,12 +111,7 @@ Only delegate when workstreams are genuinely independent. 1. Handoff to tester with explicit verification targets and risk areas. 1. For debugging paths, use root-cause-first investigation before proposing fixes. -## deliverables and success criteria - -| Artifact | Role | -| ----------- | ------- | -| source code | creator | -| unit tests | creator | +## success criteria - Implementation matches approved architecture and design intent. - Tests cover core paths and regressions. @@ -102,6 +123,19 @@ Only delegate when workstreams are genuinely independent. - High-risk defects discovered: escalate immediately with mitigation options. - Blocked dependencies or migration risk: notify product and architect early. +## artifacts you own + +| Artifact | Role | +| ----------- | ------- | +| source code | creator | +| unit tests | creator | + +## completion checklist + +- Required upstream artifacts were read before coding. +- Implementation and tests were updated together. +- Tester handoff includes explicit verification targets and risk areas. + ## skills you use - `@#concise` — runtime response-style mode (`normal|compact|ultra|status`) @@ -109,8 +143,10 @@ Only delegate when workstreams are genuinely independent. - `@#analyse` — impact analysis, tradeoffs, feasibility - `@#docs` — keep implementation and technical documentation accurate when behavior changes - `@#verify` — run tests, fix issues, re-verify loop +- `@#conventional-commit` — prepare policy-aligned Conventional Commit messages - `@#code-review` — pre-merge review - `@#debug` — root-cause debugging +- `@#threat-model` — threat model updates when design or attack surface changes - `@#performance` — performance investigation - `@#container` — Dockerfile and docker-compose authoring - `@#cicd` — GitHub Actions CI/CD workflow configuration @@ -119,6 +155,16 @@ Only delegate when workstreams are genuinely independent. - `@#openapi` — OpenAPI 3.1 spec writing and review - `@#dependency` — dependency health audit - `@#incident` — incident analysis and post-mortem writing +- `@#dependabot` — configure automated dependency updates +- `@#secret-scan` — configure GitHub secret scanning and push protection +- `@#gdpr` — GDPR engineering practices for data models, APIs, logging, and retention +- `@#terraform` — Terraform IaC authoring and review +- `@#terragrunt` — Terragrunt DRY multi-environment IaC configuration +- `@#cloudformation` — AWS CloudFormation template writing and review +- `@#aws-cli` — AWS CLI operations and scripting +- `@#k8s` — Kubernetes manifest authoring, rollout operations, and troubleshooting +- `@#helm` — Helm chart authoring and release lifecycle operations +- `@#rancher` — Rancher and Fleet multi-cluster operations and governance - + diff --git a/.github/agents/product.agent.md b/.github/agents/product.agent.md index d74a59f..07f8bf0 100644 --- a/.github/agents/product.agent.md +++ b/.github/agents/product.agent.md @@ -35,22 +35,38 @@ handoffs: You are a **senior product manager** acting as the **product role**. You define what gets built, why it matters, and when it is accepted. -## responsibilities and scope +## responsibilities - Define and refine scope for new products, features, and major scope changes. - Own acceptance criteria and release-acceptance decisions. - Orchestrate role handoffs and gate progression through the pipeline. - Ensure product baseline artifacts are current before release. -- Architect, designer, engineer, tester, and release each own their respective artifacts and decisions — do not override them. -## principles +## scope and boundaries + +- Product owns requirements, scope decisions, and acceptance. +- Architect, designer, engineer, tester, and release own their role artifacts and technical decisions. +- Product coordinates progression across gates; it does not replace role-specific execution. + +## limitations and do not do + +- Do not implement code changes. +- Do not override role-owned technical decisions without explicit escalation. +- Do not hand off to release when acceptance criteria are not met. + +## working principles - Baseline-first: keep canonical docs updated as work evolves on the feature branch. - Prefer explicit acceptance criteria over vague intent. - Keep scope decisions reversible until architecture/design gates are approved. - Choose the smallest scope that still achieves measurable outcomes. - Escalate ambiguity early; require architecture and design evidence before implementation starts. -- Do not implement code changes; do not hand off to release when acceptance criteria are not met. + +## decision guidelines + +- Block progression when required upstream artifacts are missing or stale. +- Prefer small, reviewable scope slices over broad ambiguous deliveries. +- Escalate unresolved cross-role conflicts before approving the next gate. ## communication style @@ -66,7 +82,7 @@ You are a **senior product manager** acting as the **product role**. You define - **Skills = how** — detailed procedures, checklists, and execution playbooks. - Invoke the relevant skill for deep procedural work; summarize decisions and outcomes in role output. -## gate moments and handoffs +## workflow and handoffs You pause the pipeline at key moments and wait for explicit user confirmation: @@ -91,14 +107,7 @@ Handoffs you own: 1. **Gate:** Confirm with user at each transition before proceeding. 1. **Summarize:** Report decisions, gate status, changed artifacts, and next steps. -## deliverables and success criteria - -| Artifact | Role | -| ------------------------------------ | ------- | -| `docs/product/vision.md` | creator | -| `docs/product/requirements.md` | creator | -| `docs/product/roadmap.md` | creator | -| gate decisions and acceptance record | creator | +## success criteria - Gate decisions are explicit and traceable at each transition. - Acceptance is confirmed against requirements before release handoff. @@ -110,6 +119,21 @@ Handoffs you own: - If tester reports unresolved blockers: do not release. - If required product artifacts are stale or missing: block progression until corrected. +## artifacts you own + +| Artifact | Role | +| ------------------------------------ | ------- | +| `docs/product/vision.md` | creator | +| `docs/product/requirements.md` | creator | +| `docs/product/roadmap.md` | creator | +| gate decisions and acceptance record | creator | + +## completion checklist + +- Requirements and acceptance criteria are current and explicit. +- Gate status and owner decisions are recorded. +- Handoff prompt to the next role is actionable and scoped. + ## skills you use - `@#concise` — runtime response-style mode (`normal|compact|ultra|status`) @@ -120,6 +144,7 @@ Handoffs you own: - `@#analyse` — impact analysis, tradeoffs, feasibility - `@#adr` — architecture decision record writing (if significant decisions) - `@#onboard` — contributor onboarding guide generation +- `@#gh-issues` — create and manage GitHub Issues for requirements, tasks, and user stories - + diff --git a/.github/agents/release.agent.md b/.github/agents/release.agent.md index d712d1e..4a1899f 100644 --- a/.github/agents/release.agent.md +++ b/.github/agents/release.agent.md @@ -32,17 +32,25 @@ handoffs: You are a **senior platform and release engineer** acting as the **release role**. You gate final release readiness and execute PR handoff. -## responsibilities and scope +## responsibilities - Own release gating, artifact checks, and PR creation. - Collect explicit sign-offs from tester and product. - Produce `docs/releases/{date}.md`, update `CHANGELOG.md`, and open the release PR. -- Tester owns verification evidence; product owns requirements acceptance. + +## scope and boundaries + +- Release owns gating, artifact checks, and PR handoff. +- Tester owns verification evidence. +- Product owns requirements acceptance and final business sign-off. + +## limitations and do not do + - Do not proceed if required artifacts are missing or stale. - Do not override NOK sign-offs. - Do not perform ad-hoc production changes in place of the release process. -## principles +## working principles - Evidence-first release decisions. - Explicit sign-offs from tester and product. @@ -51,6 +59,12 @@ You are a **senior platform and release engineer** acting as the **release role* - If any blocker exists, stop and route to owning role. - Prefer clear release notes over minimal notes. +## decision guidelines + +- Enforce required-for-scope evidence before requesting sign-off. +- Treat contradictory evidence as a blocker until reconciled. +- Prioritize auditability and deterministic release records. + ## communication style - Gate-oriented and explicit about pass/fail state. @@ -64,7 +78,7 @@ You are a **senior platform and release engineer** acting as the **release role* - **Skills = how** — detailed procedures, checklists, and execution playbooks. - Invoke the relevant skill for deep procedural work; summarize decisions and outcomes in role output. -## gate moments and handoffs +## workflow and handoffs Signal readiness at each release gate: @@ -88,14 +102,7 @@ Handoffs you own: 1. If both are `OK`, invoke `@#release-notes` to produce `docs/releases/{date}.md` and finalize `CHANGELOG.md`. 1. Invoke `@#pr` to push and open the PR with release notes as the body. -## deliverables and success criteria - -| Artifact | Role | -| -------------------------------- | ------- | -| `docs/releases/{date}.md` | creator | -| `CHANGELOG.md` updates | creator | -| release PR | creator | -| sign-off record (tester/product) | creator | +## success criteria - Required-for-scope artifacts are present and current before sign-off. - Tester and product sign-offs are explicit and recorded. @@ -107,15 +114,33 @@ Handoffs you own: - Any NOK sign-off: stop and hand back with rationale. - Contradictory evidence between reports: escalate for reconciliation before proceeding. +## artifacts you own + +| Artifact | Role | +| -------------------------------- | ------- | +| `docs/releases/{date}.md` | creator | +| `CHANGELOG.md` updates | creator | +| release PR | creator | +| sign-off record (tester/product) | creator | + +## completion checklist + +- Required evidence and sign-offs are explicitly recorded. +- Release artifacts are current and traceable. +- PR handoff includes final scope summary and residual risks. + ## skills you use - `@#concise` — runtime response-style mode (`normal|compact|ultra|status`) - `@#release-notes` — write `docs/releases/{date}.md` and update `CHANGELOG.md` +- `@#conventional-commit` — produce compliant Conventional Commit messages before PR - `@#pr` — commit, push, and open pull request +- `@#gh-release` — create or update GitHub Release with `gh` CLI - `@#docs` — update README/API docs consistency after release packaging - `@#cicd` — write GitHub Actions CI/CD workflows - `@#explore` — codebase discovery and mapping - `@#code-review` — final review before PR is opened +- `@#gh-issues` — create and manage GitHub Issues for tracking work and bug reports - + diff --git a/.github/agents/tester.agent.md b/.github/agents/tester.agent.md index 53076ac..be669e7 100644 --- a/.github/agents/tester.agent.md +++ b/.github/agents/tester.agent.md @@ -36,18 +36,26 @@ handoffs: You are a **senior QA, security, and reliability engineer** acting as the **tester role**. You verify that delivered changes work correctly, safely, and reliably. -## responsibilities and scope +## responsibilities - Own verification evidence and release-readiness findings. - Run functional, security, performance, and reliability verification for delivered scope. - Produce `docs/test-report.md` and `docs/security-report.md`; add `docs/performance-baseline.md` when performance validation is in scope. - Write or update tests required to validate behavior (unit/integration/contract/smoke) where applicable. -- Engineer owns implementation fixes; product owns acceptance and release decision. + +## scope and boundaries + +- Tester owns verification execution, findings, and readiness verdicts. +- Engineer owns implementation fixes. +- Product and release own acceptance and release decisions. + +## limitations and do not do + - Do not merge or release based on assumptions. - Do not hide blocking findings. - Do not bypass baseline reports with temporary-only notes. -## principles +## working principles - Baseline-first verification reports on branch. - Risk-based depth: prioritize high-impact paths and failure modes. @@ -56,6 +64,12 @@ You are a **senior QA, security, and reliability engineer** acting as the **test - Escalate ambiguous requirements that undermine test verdicts. - Prefer deterministic checks and explicit acceptance criteria. +## decision guidelines + +- Prioritize checks by severity and user impact. +- Escalate immediately when required evidence cannot be produced. +- Use explicit go/no-go language for release readiness. + ## communication style - Clear verdicts with severity and reproduction steps. @@ -69,7 +83,7 @@ You are a **senior QA, security, and reliability engineer** acting as the **test - **Skills = how** — detailed procedures, checklists, and execution playbooks. - Invoke the relevant skill for deep procedural work; summarize decisions and outcomes in role output. -## gate moments and handoffs +## workflow and handoffs Signal readiness before release proceeds: @@ -91,14 +105,7 @@ Handoffs you own: 1. Write baseline reports: `docs/test-report.md`, `docs/security-report.md`, and `docs/performance-baseline.md` when performance validation is in scope. Include observability evidence in `docs/test-report.md` unless a dedicated observability report is used. 1. Publish verdict and hand off blockers or release-readiness status. -## deliverables and success criteria - -| Artifact | Role | -| ------------------------------ | ------------------------------------------------- | -| `docs/test-report.md` | creator | -| `docs/security-report.md` | creator | -| `docs/performance-baseline.md` | creator (when performance validation is in scope) | -| test files | creator | +## success criteria - Verification coverage matches scope and risk. - Blocking issues are clearly identified with severity and reproducible evidence. @@ -110,11 +117,27 @@ Handoffs you own: - Security-critical issue found: escalate immediately and block release. - Missing or stale required-for-scope artifacts: stop and report owners. +## artifacts you own + +| Artifact | Role | +| ------------------------------ | ------------------------------------------------- | +| `docs/test-report.md` | creator | +| `docs/security-report.md` | creator | +| `docs/performance-baseline.md` | creator (when performance validation is in scope) | +| test files | creator | + +## completion checklist + +- Functional, security, and required-for-scope checks are complete. +- Reports include reproducible findings and explicit verdicts. +- Release handoff includes blockers, residual risk, and readiness status. + ## skills you use - `@#concise` — runtime response-style mode (`normal|compact|ultra|status`) - `@#inspect` — read-only verification audit, produces findings report - `@#security` — security audit +- `@#threat-model` — structured threat analysis and mitigation prioritization - `@#performance` — performance review - `@#docs` — keep verification and audit documentation complete and current - `@#guardrails` — reliability and observability review @@ -124,6 +147,14 @@ Handoffs you own: - `@#migrate` — database migration safety review - `@#dependency` — dependency vulnerability and health audit - `@#incident` — incident analysis and post-mortem writing +- `@#codeql` — CodeQL code scanning setup and alert triage +- `@#secret-scan` — GitHub secret scanning configuration and alert triage +- `@#dependabot` — review and validate dependency update configuration +- `@#gdpr` — GDPR compliance review for data handling and privacy controls +- `@#aws-cli` — AWS resource inspection and observability queries +- `@#k8s` — Kubernetes workload validation, deployment safety, and runtime diagnostics +- `@#helm` — Helm chart and release validation with rollback safety checks +- `@#rancher` — Rancher/Fleet configuration and multi-cluster governance review - + diff --git a/.github/instructions/git.instructions.md b/.github/instructions/git.instructions.md index ac98449..ee0ecde 100644 --- a/.github/instructions/git.instructions.md +++ b/.github/instructions/git.instructions.md @@ -1,7 +1,7 @@ --- name: git description: 'Git and release hygiene conventions. Use when creating commits, branches, or release-related changes.' -applyTo: **/* +applyTo: '**/*' --- Use these Git and release hygiene conventions in this project. @@ -41,4 +41,4 @@ Use these Git and release hygiene conventions in this project. 1. Prefer local verification before pushing release-impacting changes. - + diff --git a/.github/instructions/helm.instructions.md b/.github/instructions/helm.instructions.md new file mode 100644 index 0000000..1b37194 --- /dev/null +++ b/.github/instructions/helm.instructions.md @@ -0,0 +1,48 @@ +--- +name: helm +description: 'Helm chart conventions. Use when writing or reviewing Helm charts, templates, and values files.' +applyTo: '**/charts/**/*.{yaml,yml,tpl}' +--- +Use these Helm conventions in this project. + +## Chart structure + +1. Keep chart metadata in `Chart.yaml`; do not duplicate metadata in templates. +1. Keep reusable template logic in `templates/_helpers.tpl`. +1. Keep defaults in `values.yaml` and environment overrides in separate values files. + +## Templating quality + +1. Quote string values where ambiguity may cause rendering/type errors. +1. Guard optional blocks with conditionals to avoid emitting invalid YAML. +1. Keep names and labels deterministic via helper templates. +1. Avoid embedding large opaque blobs in templates; externalize where possible. + +## Values and secrets + +1. Document key values in chart README or comments. +1. Do not hardcode secrets in `values.yaml`; use external secret mechanisms or secure value injection. +1. Keep production overrides minimal and explicit. + +## Dependencies and versioning + +1. Pin dependency versions in `Chart.yaml`; avoid floating versions. +1. Update dependencies with `helm dependency update` as part of chart changes. +1. Track breaking changes in chart `version` and `appVersion` updates. + +## Validation and release safety + +1. Run `helm lint` for every chart change. +1. Render templates with `helm template` and validate generated manifests before deployment. +1. Use `helm upgrade --atomic` for safer upgrades where applicable. +1. Keep rollback paths available and verify `helm history` in production workflows. + +## References + +> Always use the official documentation for the exact Helm and Kubernetes versions in use - chart schema, flags, and behavior evolve between releases. + +- [Helm docs](https://helm.sh/docs/) +- [Helm chart best practices](https://helm.sh/docs/chart_best_practices/) + + + diff --git a/.github/instructions/java.instructions.md b/.github/instructions/java.instructions.md new file mode 100644 index 0000000..98a498a --- /dev/null +++ b/.github/instructions/java.instructions.md @@ -0,0 +1,59 @@ +--- +name: java +description: 'Java coding conventions for projects. Use when writing or reviewing Java source files, tests, and build configuration.' +applyTo: '**/*.java' +--- +Use these Java conventions in this project. + +## Design and readability + +1. Prefer explicit, domain-meaningful names over abbreviations; follow standard Java naming conventions. +1. Keep methods focused; split methods that mix parsing, I/O, and business rules. +1. Prefer immutable objects; make fields `final` by default and expose mutation only where required. +1. Prefer straightforward control flow over clever one-liners. + +## Types and APIs + +1. Keep public APIs minimal and stable; mark implementation details `package-private` or `private`. +1. Program to interfaces, not implementations, for dependencies that may change. +1. Use records for simple value types where the Java version supports them. +1. Prefer `Optional` as a return type for values that may be absent; do not use it for fields or parameters. + +## Null safety + +1. Annotate method parameters and return types with `@NonNull` or `@Nullable` where nullability is meaningful. +1. Never return `null` from a public method that could return `Optional` instead. +1. Fail fast on unexpected nulls at system boundaries using explicit precondition checks. + +## Exception handling + +1. Use checked exceptions only for conditions the caller can reasonably recover from. +1. Prefer unchecked exceptions for programming errors and unrecoverable states. +1. Never swallow exceptions silently; log or rethrow with meaningful context. +1. Close resources with try-with-resources rather than manual `finally` blocks. + +## Concurrency + +1. Prefer high-level concurrency abstractions (`ExecutorService`, `CompletableFuture`) over raw threads. +1. Minimize shared mutable state; document thread-safety guarantees explicitly. +1. Do not use `synchronized` on publicly visible objects unless the locking strategy is documented. + +## Dependencies and imports + +1. Keep imports minimal; remove unused imports. +1. Avoid wildcard imports (`import foo.*`) in production code. +1. Do not add a library dependency when the standard library suffices. + +## Testing and verification + +1. Add or update tests for every behavioral change. +1. Keep unit tests independent of implementation details; test observable behavior. +1. Cover success paths, edge cases, and expected failures. + +## Tooling alignment + +1. Keep code compatible with the repository's checkstyle, PMD, or linting configuration. +1. Do not suppress static analysis warnings without a documented, task-specific reason. + + + diff --git a/.github/instructions/k8s.instructions.md b/.github/instructions/k8s.instructions.md new file mode 100644 index 0000000..5bcc17e --- /dev/null +++ b/.github/instructions/k8s.instructions.md @@ -0,0 +1,54 @@ +--- +name: k8s +description: 'Kubernetes manifest conventions. Use when writing or reviewing Kubernetes workload and service manifests.' +applyTo: '**/{k8s,kubernetes,manifests}/**/*.{yaml,yml}' +--- +Use these Kubernetes conventions in this project. + +## API and versioning + +1. Prefer stable APIs (`apps/v1`, `networking.k8s.io/v1`) and avoid deprecated versions. +1. Set `kind` and `metadata.name` deterministically; avoid generated names for long-lived workloads. +1. Keep one primary resource per file where possible to simplify review and rollback. + +## Workload safety + +1. Set CPU and memory `requests` and `limits` for every container. +1. Define both readiness and liveness probes for long-running services. +1. Avoid mutable image tags (`:latest`); use pinned tags or immutable digests. +1. Set rollout strategy explicitly for Deployments handling production traffic. + +## Namespace and labels + +1. Explicitly set `metadata.namespace` unless the deployment tooling injects it by design. +1. Use consistent labels: `app.kubernetes.io/name`, `app.kubernetes.io/instance`, `app.kubernetes.io/managed-by`. +1. Keep Service selectors aligned with pod template labels. + +## Security + +1. Run containers as non-root when feasible. +1. Avoid privileged mode and broad Linux capabilities unless required and documented. +1. Do not hardcode secrets in manifests; reference Secrets or external secret providers. +1. Restrict RBAC to least privilege; avoid broad `cluster-admin` grants. + +## Reliability and operations + +1. Use PodDisruptionBudgets for critical workloads. +1. Configure `terminationGracePeriodSeconds` and preStop hooks where graceful shutdown is required. +1. Add resource annotations/labels needed by observability and runtime policies. + +## Validation + +1. Validate manifests with `kubectl apply --dry-run=client` before merge. +1. Use `kubectl apply --dry-run=server` where API server validation is available. +1. Treat warnings for deprecated APIs as release blockers. + +## References + +> Always use the official documentation for the exact Kubernetes version in use - API versions and defaults change between releases. + +- [Kubernetes docs](https://kubernetes.io/docs/) +- [Kubernetes API reference](https://kubernetes.io/docs/reference/kubernetes-api/) + + + diff --git a/.github/instructions/markdown.instructions.md b/.github/instructions/markdown.instructions.md new file mode 100644 index 0000000..64b29d5 --- /dev/null +++ b/.github/instructions/markdown.instructions.md @@ -0,0 +1,54 @@ +--- +name: markdown +description: 'Markdown authoring conventions for documentation, README files, ADRs, and other hand-authored prose. Use when writing or reviewing any Markdown file.' +applyTo: '**/*.md' +--- +Use these Markdown conventions in this project. + +## Structure and headings + +1. Keep heading levels sequential — do not skip levels (e.g. from `##` to `####`). +1. Prefer flat heading structures; rarely go deeper than `####`. +1. Keep headings short and descriptive. + +## Prose and tone + +1. Write in clear, direct language — prefer active voice over passive voice. +1. Keep sentences short; split complex ideas across multiple sentences rather than commas and semicolons. +1. Be consistent with terminology throughout the file; introduce a term once and reuse it. +1. Avoid filler phrases such as "please note", "it is important to", and "simply". + +## Lists and tables + +1. Use numbered lists for ordered steps; use unordered lists for non-ordered items. +1. Keep list items parallel in grammar and structure. +1. Prefer a table over nested unordered lists when presenting structured comparisons. +1. Keep table columns to what is necessary; remove columns with no meaningful content. + +## Code blocks and inline code + +1. Specify a language identifier on fenced code blocks where a language can be determined. +1. Use inline code for file names, paths, commands, identifiers, and literal values. +1. Do not put prose in a code block; reserve code blocks for commands, source code, and literal output. + +## Links and references + +1. Use descriptive link text — avoid bare URLs and text like "click here" or "this link". +1. Prefer relative links for documents within the same repository. +1. Verify that section anchors match actual heading text before committing. + +## Diagrams + +1. Use Mermaid for process, flow, interaction, lifecycle, and decision diagrams when the target environment renders it (GitHub, VS Code, compatible docs tools). +1. Fall back to ASCII or plain-text descriptions when Mermaid rendering cannot be guaranteed (e.g. PyPI, email, plain-text viewers). +1. Use ASCII or text trees for directory layouts and file hierarchies regardless of environment. +1. Do not embed a diagram where a simple sentence or table communicates the same information. + +## Maintenance + +1. Update documentation in the same change as the behavior or interface it describes. +1. Remove outdated content rather than leaving it with a "TODO: update" comment. +1. Keep examples accurate and runnable — a broken example is worse than no example. + + + diff --git a/.github/instructions/python.instructions.md b/.github/instructions/python.instructions.md index de5263a..a9a809c 100644 --- a/.github/instructions/python.instructions.md +++ b/.github/instructions/python.instructions.md @@ -1,7 +1,7 @@ --- name: python description: 'Python coding conventions for projects. Use when writing or reviewing Python modules, tests, CLI code, and package internals.' -applyTo: **/*.py +applyTo: '**/*.py' --- Use these Python conventions in this project. @@ -42,4 +42,4 @@ Use these Python conventions in this project. 1. Do not silence lint/type errors unless there is a documented, task-specific reason. - + diff --git a/.github/instructions/rancher.instructions.md b/.github/instructions/rancher.instructions.md new file mode 100644 index 0000000..3f52dd8 --- /dev/null +++ b/.github/instructions/rancher.instructions.md @@ -0,0 +1,47 @@ +--- +name: rancher +description: 'Rancher and Fleet conventions. Use when writing or reviewing Rancher/Fleet configuration files and cluster governance manifests.' +applyTo: '**/{rancher,fleet}/**/*.{yaml,yml}' +--- +Use these Rancher conventions in this project. + +## Scope and environment + +1. Keep environment and cluster targeting explicit; avoid wildcard targeting for production bundles. +1. Separate dev, staging, and production policies and rollout paths. +1. Document expected project/namespace scope for each config set. + +## Fleet and GitOps hygiene + +1. Keep Fleet bundle structure deterministic and easy to review. +1. Pin chart and app versions in GitOps definitions; avoid floating versions. +1. Keep per-environment overrides small and explicit. +1. Use pull-request review for all production-bound Fleet changes. + +## Access and governance + +1. Apply least privilege for Rancher roles and project membership. +1. Avoid broad administrative grants outside platform owner groups. +1. Review role bindings and project-level permissions regularly. + +## Secrets and security + +1. Do not hardcode credentials or tokens in Rancher/Fleet config files. +1. Reference secrets from approved secret management paths. +1. Keep auditability for cluster/project configuration changes. + +## Operations + +1. Validate target clusters/projects before applying any change. +1. Include rollback guidance for application and bundle updates. +1. Treat drift and failed bundle rollout as operational incidents with follow-up remediation. + +## References + +> Always use the official documentation for the exact Rancher and Fleet versions in use - features and defaults vary between releases. + +- [Rancher docs](https://ranchermanager.docs.rancher.com/) +- [Fleet docs](https://fleet.rancher.io/) + + + diff --git a/.github/instructions/security.instructions.md b/.github/instructions/security.instructions.md new file mode 100644 index 0000000..dd02e2c --- /dev/null +++ b/.github/instructions/security.instructions.md @@ -0,0 +1,45 @@ +--- +name: security +description: 'Security policy for all code, configuration, and infrastructure. Use when writing or reviewing any code, configuration, or workflow file.' +applyTo: '**/*' +--- +Apply these security policies in this project. + +## Secrets and credentials + +1. Never hardcode secrets, tokens, passwords, or private keys in source code, configuration files, tests, or commit messages. +1. Read secrets from environment variables or a secret store at runtime; document which variables are required. +1. Treat any accidental secret exposure as a revocation event — rotate immediately, do not just delete the value. + +## Input and trust boundaries + +1. Validate and sanitize all input that crosses a trust boundary: HTTP requests, CLI arguments, environment variables, files, and inter-service messages. +1. Never trust client-supplied values for authorization decisions; enforce access control server-side. +1. Reject or escape input before it reaches queries, shell commands, template engines, or log sinks. + +## Authentication and authorization + +1. Default to deny; require explicit grants for every protected resource or operation. +1. Verify identity and permission separately; do not conflate authentication with authorization. +1. Do not implement custom cryptography or authentication schemes; use established, maintained libraries. + +## Dependencies and supply chain + +1. Pin dependency versions in manifests; do not use unbounded version ranges in production code. +1. Minimise the dependency surface — do not add a library when the standard library suffices. +1. Treat dependency updates that introduce new transitive dependencies as requiring explicit review. + +## Error handling and observability + +1. Never expose internal stack traces, system paths, or configuration details to external callers. +1. Do not log sensitive data: passwords, tokens, PII, or session identifiers. +1. Fail closed on security errors — deny access when the policy cannot be evaluated, rather than defaulting to allow. + +## Destructive and privileged operations + +1. Require explicit confirmation before executing irreversible or destructive operations. +1. Apply least privilege: request only the permissions a component actually needs. +1. Isolate privileged logic; keep it minimal, auditable, and separate from business logic. + + + diff --git a/.github/instructions/terraform.instructions.md b/.github/instructions/terraform.instructions.md new file mode 100644 index 0000000..da8fe19 --- /dev/null +++ b/.github/instructions/terraform.instructions.md @@ -0,0 +1,63 @@ +--- +name: terraform +description: 'Terraform coding conventions for projects. Use when writing or reviewing Terraform modules, root configurations, variable files, and state configuration.' +applyTo: '**/*.tf' +--- +Use these Terraform conventions in this project. + +## Structure and file layout + +1. Split configuration into `main.tf`, `variables.tf`, `outputs.tf`, `providers.tf`, `versions.tf`, and `locals.tf` — do not put everything in one file. +1. Keep one module per directory; avoid multi-purpose root modules. +1. Place reusable logic in `modules//` with its own `variables.tf` and `outputs.tf`. + +## Versioning and pinning + +1. Pin the Terraform binary version with `required_version = "~> X.Y"` in a `versions.tf` file. +1. Pin every provider with `version = "~> X.Y"` in `required_providers` — never use unbounded ranges in production. +1. Commit `.terraform.lock.hcl` to source control. +1. Pin external module sources to a specific git ref or registry semver tag — never `?ref=main`. + +## State management + +1. Use a remote backend with encryption and state locking for all non-local work. +1. Enable versioning on the S3 state bucket. +1. Never store secrets in state outputs — mark sensitive outputs with `sensitive = true`. + +## Variables and outputs + +1. Add `type`, `description`, and a sensible `default` to every variable. +1. Add validation blocks for constrained variables (`AllowedValues` equivalents). +1. Mark secret variables with `sensitive = true` — never hardcode them in `.tf` files or committed `.tfvars`. +1. Add `description` to every output; mark secret outputs `sensitive = true`. + +## Naming and tagging + +1. Use `locals` to construct name prefixes and centralise tag maps. +1. Name physical resources with `"${local.name_prefix}-"` to ensure cross-stack uniqueness. +1. Apply a common tag map (`local.common_tags`) to every taggable resource; include at minimum `Environment` and `ManagedBy = "terraform"`. + +## Security + +1. Block public access on all S3 buckets unless intentionally public; document the exception. +1. Enable `storage_encrypted = true` and `deletion_protection = true` on all RDS instances. +1. Restrict security group rules — avoid `0.0.0.0/0` on management ports; add a comment when HTTPS/443 is open. +1. Apply least-privilege IAM policies — no `*` actions on `*` resources. +1. Enable KMS key rotation (`enable_key_rotation = true`). + +## Tooling + +1. Run `terraform fmt -check -recursive` in CI and auto-format locally. +1. Run `terraform validate` before every plan. +1. Run `tfsec` or `checkov` on all changes; fix HIGH and CRITICAL findings before merging. + +## References + +> Always use the official documentation for the provider and Terraform version in use — resource arguments and defaults change between provider releases. + +- [Terraform documentation](https://developer.hashicorp.com/terraform/docs) +- [Terraform provider registry](https://registry.terraform.io/) +- [tfsec](https://aquasecurity.github.io/tfsec/) · [checkov](https://www.checkov.io/) + + + diff --git a/.github/instructions/terragrunt.instructions.md b/.github/instructions/terragrunt.instructions.md new file mode 100644 index 0000000..9770cb6 --- /dev/null +++ b/.github/instructions/terragrunt.instructions.md @@ -0,0 +1,60 @@ +--- +name: terragrunt +description: 'Terragrunt coding conventions for projects. Use when writing or reviewing Terragrunt HCL configurations, root configs, unit modules, and dependency blocks.' +applyTo: '**/terragrunt.hcl' +--- +Use these Terragrunt conventions in this project. + +## Structure and hierarchy + +1. Maintain a strict directory hierarchy that maps to deployment topology: `infra///terragrunt.hcl`. +1. Keep one root `terragrunt.hcl` at the repository root or top-level `infra/` directory; inherit it in all units via `include "root" { path = find_in_parent_folders() }`. +1. Use `account.hcl` files at the account/environment level for account ID, region, and environment name — read them with `read_terragrunt_config(find_in_parent_folders("account.hcl"))`. + +## Remote state and backend generation + +1. Generate `backend.tf` from the root `remote_state` block — never hand-write backend files in units. +1. Use `path_relative_to_include()` as the state key so each unit gets a unique, auto-named state file. +1. Enable encryption and state locking on the S3 backend; enable versioning on the state bucket. + +## Provider generation + +1. Generate `provider.tf` from the root `generate "provider"` block — never duplicate provider configuration across units. +1. Include `default_tags` in the generated provider block to ensure consistent tagging across all resources. + +## Module sources and pinning + +1. Pin all module sources to a specific git ref or registry semver tag — never `?ref=main` or floating tags. +1. Prefer sourcing from a versioned internal registry or tagged git commit over local paths in shared modules. + +## Dependency blocks + +1. Add `mock_outputs` to every `dependency` block for the `validate` and `plan` commands — this allows planning without deploying dependencies first. +1. Declare only the outputs you actually use from a dependency; do not expose the full output set. +1. Keep `dependency` blocks at unit level — do not express dependencies in the root config. + +## DRY inputs + +1. Extract shared inputs for an ecosystem (e.g. RDS defaults) into `_envcommon/.hcl`; load with `read_terragrunt_config`. +1. Use `merge(local.common.inputs, { ... })` to override defaults per environment — do not copy-paste full input maps. + +## CI/CD + +1. Always pass `--terragrunt-non-interactive` in automated pipelines to prevent interactive prompts. +1. Use `--terragrunt-parallelism` to control concurrency; start with 4 and adjust to pipeline resource limits. +1. Add `.terragrunt-cache/` to `.gitignore`. + +## Secrets + +1. Never hardcode secrets in `.hcl` files — supply them via environment variables (`TF_VAR_*`) or a secrets manager data source. +1. Do not commit `.tfvars` files containing real secrets. + +## References + +> Always use the official documentation for the Terragrunt version in use — built-in functions and CLI flags evolve with each release. + +- [Terragrunt documentation](https://terragrunt.gruntwork.io/docs/) +- [Terragrunt CLI reference](https://terragrunt.gruntwork.io/docs/reference/cli-options/) + + + diff --git a/.github/instructions/testing.instructions.md b/.github/instructions/testing.instructions.md new file mode 100644 index 0000000..e673737 --- /dev/null +++ b/.github/instructions/testing.instructions.md @@ -0,0 +1,46 @@ +--- +name: testing +description: 'Test authoring conventions for any language or framework. Use when writing or reviewing tests, test plans, or test coverage decisions.' +applyTo: '**/*' +--- +Use these testing conventions in this project. + +## Scope and intent + +1. Write tests to verify observable behavior, not internal implementation details. +1. A test that passes when behavior is wrong, or fails when behavior is correct, has negative value. +1. Tests are documentation — a reader should understand what the system does by reading the test. + +## Naming and structure + +1. Name tests to describe what they verify: what the subject does, under what condition, and what the expected outcome is. +1. Keep each test focused on one behavior; avoid asserting unrelated outcomes in a single test. +1. Group related tests together; separate unrelated test concerns into distinct test units. + +## Coverage and completeness + +1. Cover the success path, expected failure paths, and boundary conditions for every behavioral change. +1. Treat missing tests for changed behavior as a defect — a change without tests is not complete. +1. Do not chase a coverage number; cover behaviors that matter rather than lines that exist. + +## Test quality + +1. Make tests deterministic — a test that passes or fails non-deterministically is unreliable and must be fixed. +1. Keep tests independent; no test should depend on execution order or shared mutable state. +1. Prefer clear, direct assertions over indirect checks; assert the outcome, not the path to it. +1. Avoid logic (loops, conditionals) in tests; if a test needs logic, split it into multiple focused tests. + +## Test boundaries + +1. Use unit tests for isolated logic; use integration tests when behavior crosses component or service boundaries. +1. Mock or stub only what is necessary to isolate the subject; avoid over-mocking that disconnects the test from real behavior. +1. Test contracts and interfaces, not just internal units — what the caller observes is what matters. + +## Maintenance + +1. Update tests in the same change as the behavior they cover. +1. Remove tests that no longer reflect real behavior rather than commenting them out. +1. Treat flaky tests as bugs; do not merge code with known test reliability issues. + + + diff --git a/.github/instructions/typescript.instructions.md b/.github/instructions/typescript.instructions.md new file mode 100644 index 0000000..adb935d --- /dev/null +++ b/.github/instructions/typescript.instructions.md @@ -0,0 +1,52 @@ +--- +name: typescript +description: 'TypeScript coding conventions for projects. Use when writing or reviewing TypeScript or JavaScript modules, components, and package internals.' +applyTo: '**/*.{ts,tsx,js,jsx,mts,cts,mjs,cjs}' +--- +Use these TypeScript conventions in this project. + +## Type safety + +1. Enable and respect strict mode; do not disable strictness per-file without a documented reason. +1. Avoid `any`; prefer `unknown` when the type is genuinely unknown and narrow it explicitly. +1. Prefer `interface` for object shapes that may be extended; use `type` for unions, intersections, and aliases. +1. Do not use type assertions (`as`) to silence type errors; fix the type instead. + +## Design and readability + +1. Prefer explicit, domain-meaningful names over abbreviations. +1. Keep functions focused; split functions that mix parsing, I/O, and business rules. +1. Prefer straightforward control flow over clever one-liners. +1. Use `const` by default; use `let` only when reassignment is required; never use `var`. + +## Null and undefined + +1. Prefer `undefined` over `null` for absent optional values unless an API contract requires `null`. +1. Use optional chaining (`?.`) and nullish coalescing (`??`) rather than manual null guards. +1. Do not suppress non-null assertions (`!`) unless the value is provably non-null and the reason is documented. + +## Modules and imports + +1. Use named exports by default; use default exports only when the module clearly has a single entry point. +1. Keep imports minimal and remove unused imports. +1. Avoid circular dependencies; if they appear, treat them as a structural design problem. + +## Async and error handling + +1. Prefer `async/await` over raw promise chains for readability. +1. Always handle or propagate rejected promises; never silently swallow errors. +1. Use typed error boundaries where the runtime supports them. + +## Testing and verification + +1. Add or update tests for every behavioral change. +1. Keep tests independent of implementation details; test observable behavior. +1. Cover success paths, edge cases, and expected failures. + +## Tooling alignment + +1. Keep code compatible with the repository's linting and type-checking configuration. +1. Do not suppress lint or type errors with inline disable comments unless there is a documented, task-specific reason. + + + diff --git a/.github/prompts/api-design-review.prompt.md b/.github/prompts/api-design-review.prompt.md new file mode 100644 index 0000000..70e505c --- /dev/null +++ b/.github/prompts/api-design-review.prompt.md @@ -0,0 +1,58 @@ +--- +description: 'Review an API design or OpenAPI spec for correctness, completeness, and consistency.' +name: api-design-review +argument-hint: '[OpenAPI spec file, design doc, or endpoint scope]' +agent: designer +model: GPT-5.3-Codex (copilot) +tools: + - read + - search +--- +Review the provided API design or OpenAPI specification for correctness, completeness, and consistency. + +Focus on issues that affect consumers: breaking contracts, ambiguous semantics, missing error cases, and inconsistent conventions. +Do not focus on implementation details or tooling preferences. + +Output exactly in this format: + +## Contract Issues + +List problems that would break or confuse consumers. + +For each item: + +- endpoint or field reference +- what the problem is in one sentence +- concrete fix + +## Naming and Consistency + +List naming violations, inconsistencies across endpoints, and deviations from REST conventions. + +## Missing Error Cases + +List expected error responses that are undocumented or missing status codes (400, 401, 403, 404, 409, 422, 500). + +## Schema Completeness + +List fields or objects that are missing required constraints, descriptions, or examples. + +## Versioning and Compatibility + +- versioning strategy present: yes | no | partial +- breaking changes relative to previous version: yes | no | unknown +- backward compatibility risk: low | medium | high + +## Security Scheme Check + +- authentication documented: yes | no +- authorization scopes documented where relevant: yes | no | partial +- sensitive fields handled appropriately: yes | no | partial + +## Verdict + +- approve | approve-with-conditions | reject +- top priority fix in one sentence + + + diff --git a/.github/prompts/architecture-risk.prompt.md b/.github/prompts/architecture-risk.prompt.md new file mode 100644 index 0000000..9d9f919 --- /dev/null +++ b/.github/prompts/architecture-risk.prompt.md @@ -0,0 +1,55 @@ +--- +description: 'Identify architectural risks, tradeoffs, and mitigation priorities for a proposed design.' +name: architecture-risk +argument-hint: '[design doc, ADR, or architecture scope]' +agent: architect +model: GPT-5.3-Codex (copilot) +tools: + - read + - search +--- +Evaluate the provided architecture for delivery and runtime risk. + +Prioritize issues that could cause outages, data loss, severe operability pain, or major rework. +Do not focus on stylistic preferences. + +Output exactly in this format: + +## High-Severity Risks + +List risks that can materially fail production or block safe delivery. + +For each risk: + +- impacted boundary (service, data, contract, deployment, observability, security) +- why it is risky in one sentence +- mitigation with smallest viable change +- owner role + +## Medium Risks + +List important but non-blocking risks. + +## Tradeoff Notes + +List major tradeoffs and what is being optimized. + +## Missing Decisions + +List decisions that should become ADRs before implementation. + +## Recommended Sequence + +Provide an ordered mitigation sequence (step 1..N). + +## Security Considerations + +List security-specific risks not covered above: auth boundaries, sensitive data exposure, trust model assumptions, supply chain concerns. + +## Go/No-Go + +- go | conditional-go | no-go +- one-sentence rationale + + + diff --git a/.github/prompts/code-review.prompt.md b/.github/prompts/code-review.prompt.md index 86774d6..4f6287e 100644 --- a/.github/prompts/code-review.prompt.md +++ b/.github/prompts/code-review.prompt.md @@ -18,6 +18,7 @@ Focus only on issues with real impact: - performance and scalability - maintainability and ownership boundaries - missing tests for changed behavior +- API contract changes: breaking changes, schema drift, missing versioning Ignore: @@ -50,4 +51,4 @@ End with: - Biggest remaining risk: one sentence - + diff --git a/.github/prompts/dependency-audit.prompt.md b/.github/prompts/dependency-audit.prompt.md new file mode 100644 index 0000000..d8744b5 --- /dev/null +++ b/.github/prompts/dependency-audit.prompt.md @@ -0,0 +1,63 @@ +--- +description: 'Audit dependencies for vulnerabilities, outdated versions, licence risks, and supply chain hygiene.' +name: dependency-audit +argument-hint: '[dependency manifest, lockfile, or package scope]' +agent: tester +model: GPT-5.3-Codex (copilot) +tools: + - read + - search +--- +Audit the provided dependency manifest or lockfile for vulnerabilities, outdated packages, licence risks, and supply chain hygiene. + +Prefer evidence from the manifest itself; flag items that require external verification. + +Output exactly in this format: + +## Vulnerabilities + +List dependencies with known CVEs or security advisories. + +For each item: + +- package name and version +- CVE or advisory reference if known +- severity: critical | high | medium | low +- recommended action (upgrade, replace, or accept with rationale) + +## Outdated Packages + +List dependencies that are significantly behind their latest stable release and carry meaningful risk. +Do not list minor version differences without impact. + +For each item: + +- package name: current version → latest stable +- risk of staying on current version in one sentence + +## Licence Risks + +List licences that may conflict with the project's distribution model. + +For each item: + +- package name +- licence identifier +- conflict or concern in one sentence + +## Pinning and Version Policy + +- all direct dependencies pinned: yes | no | partial +- unpinned transitive dependencies with risk: list or none +- version ranges that allow breaking upgrades: list or none + +## Supply Chain Hygiene + +List packages with unusual provenance concerns: abandoned maintainers, single-maintainer with no backup, recent ownership transfers, or typosquatting risk. + +## Recommended Actions + +Ordered list of actions by priority (critical first). + + + diff --git a/.github/prompts/incident-timeline.prompt.md b/.github/prompts/incident-timeline.prompt.md new file mode 100644 index 0000000..ebe3980 --- /dev/null +++ b/.github/prompts/incident-timeline.prompt.md @@ -0,0 +1,60 @@ +--- +description: 'Build a structured, evidence-based incident timeline and action-oriented postmortem summary.' +name: incident-timeline +argument-hint: '[logs, alerts, timeline notes, or incident ID]' +agent: tester +model: GPT-5.3-Codex (copilot) +tools: + - read + - search +--- +Construct a blameless incident timeline from the provided evidence. + +Anchor claims to available logs, alerts, traces, and change events. +If evidence is missing, explicitly mark uncertainty. + +Output exactly in this format: + +## Incident Snapshot + +- incident title +- impact window +- affected systems/users +- current status + +## Timeline (UTC) + +List timestamped events in order. + +For each event: + +- time +- event description +- evidence source +- confidence: high | medium | low + +## Root Cause Analysis + +- primary cause +- contributing factors +- what made detection/recovery slower + +## What Worked / What Failed + +Two short lists. + +## Corrective Actions + +For each action: + +- action description +- owner role +- priority: P0 | P1 | P2 +- due expectation (short horizon) + +## Prevention Check + +List the minimum controls needed to reduce repeat probability. + + + diff --git a/.github/prompts/migration-safety.prompt.md b/.github/prompts/migration-safety.prompt.md new file mode 100644 index 0000000..e602ce8 --- /dev/null +++ b/.github/prompts/migration-safety.prompt.md @@ -0,0 +1,55 @@ +--- +description: 'Review database migration safety, rollback strategy, and zero-downtime risk.' +name: migration-safety +argument-hint: '[migration files, schema, or rollout plan]' +agent: engineer +model: GPT-5.3-Codex (copilot) +tools: + - read + - search + - edit +--- +Review the selected migration plan and code for production safety. + +Focus on forward compatibility, rollback feasibility, data integrity, and operational risk. +Assume a live system with concurrent reads/writes. + +Output exactly in this format: + +## Must Fix Before Apply + +List migration blockers. + +For each item: + +- file/section +- failure mode in one sentence +- concrete safe fix + +## Should Fix Soon + +List non-blocking risks with meaningful impact. + +## Rollback Plan Check + +- rollback feasible: yes | no | partial +- missing rollback prerequisites +- specific rollback procedure recommendation + +## Zero-Downtime Check + +- compatible with old and new app versions: yes | no | partial +- lock/contention risk: low | medium | high +- required phased rollout steps + +## Test Gaps + +List missing migration tests (forward, backward, data invariants, load-sensitive paths). + +## Final Recommendation + +- apply now | apply after fixes +- biggest remaining risk in one sentence + + + diff --git a/.github/prompts/release-readiness.prompt.md b/.github/prompts/release-readiness.prompt.md new file mode 100644 index 0000000..8552f4f --- /dev/null +++ b/.github/prompts/release-readiness.prompt.md @@ -0,0 +1,49 @@ +--- +description: 'Evaluate release readiness from reports, risks, and unresolved blockers.' +name: release-readiness +argument-hint: '[scope, release date, or branch]' +agent: release +model: GPT-5.3-Codex (copilot) +tools: + - read + - search +--- +Assess whether this change set is ready to release. + +Review product, architecture, design, test, security, and performance evidence. +Prefer evidence-based findings tied to concrete artifacts. + +Output exactly in this format: + +## Release Gate Verdict + +- Verdict: READY | READY-WITH-CONDITIONS | NOT-READY +- Confidence: high | medium | low +- Scope assessed: one sentence + +## Blocking Issues + +List only release-blocking items. + +For each item: + +- artifact or file reference +- why this blocks release in one sentence +- concrete unblock action +- owner role (product | architect | designer | engineer | tester | release) + +## Conditions Before Release + +List non-blocking but mandatory follow-ups to ship safely. + +## Evidence Reviewed + +List the exact artifacts checked (reports, docs, CI evidence, manifests). +For each expected artifact that is missing, flag it explicitly as: MISSING — [artifact name]. + +## Recommended Next Action + +One clear next step for the team. + + + diff --git a/.github/skills/adr/SKILL.md b/.github/skills/adr/SKILL.md index e043b44..d08af26 100644 --- a/.github/skills/adr/SKILL.md +++ b/.github/skills/adr/SKILL.md @@ -44,8 +44,6 @@ what was decided, why, and what alternatives were considered. - Implementation (engineering role) - Running analysis to inform the decision (use `analyse`) -______________________________________________________________________ - ## Step 0: Context Gathering Read existing ADRs and architecture docs: @@ -59,8 +57,6 @@ ls docs/architecture/adr/*.md 2>/dev/null | grep -oE '[0-9]+' | sort -n | tail - Determine the next ADR number (pad to 3 digits: 001, 002, ...). -______________________________________________________________________ - ## Step 1: Understand the Decision > **Question:** What decision are we recording? @@ -75,8 +71,6 @@ Status: proposed | accepted | rejected | deprecated | superseded Date: YYYY-MM-DD ``` -______________________________________________________________________ - ## Step 2: Context Why does this decision need to be made? What forces are at play? @@ -93,8 +87,6 @@ Include: [2-4 paragraphs explaining the situation, constraints, and why this matters] ``` -______________________________________________________________________ - ## Step 3: Alternatives Considered List all serious options that were evaluated. For each: @@ -111,8 +103,6 @@ List all serious options that were evaluated. For each: Include at least 2-3 alternatives. Including a "do nothing" option is recommended. -______________________________________________________________________ - ## Step 4: Decision State the chosen option clearly: @@ -124,8 +114,6 @@ We will [chosen option]. [1-2 sentences on why this option was selected over alternatives] ``` -______________________________________________________________________ - ## Step 5: Rationale Explain the reasoning in depth: @@ -136,8 +124,6 @@ Explain the reasoning in depth: Reference specific cons from rejected options and explain why they were acceptable tradeoffs.] ``` -______________________________________________________________________ - ## Step 6: Consequences & Impact ```markdown @@ -153,8 +139,6 @@ ______________________________________________________________________ - [What could go wrong, and how we'd detect or mitigate it] ``` -______________________________________________________________________ - ## Step 7: Related Decisions ```markdown @@ -162,8 +146,6 @@ ______________________________________________________________________ - ADR-NNN: [title] — [relationship: supersedes / related to / depends on] ``` -______________________________________________________________________ - ## Output: ADR file Write to `docs/architecture/adr/NNN-.md` where NNN is the next available number and slug @@ -196,7 +178,5 @@ is a kebab-case title. After writing, state the file path and summary so the architect or product role can review. -______________________________________________________________________ - - + diff --git a/.github/skills/analyse/SKILL.md b/.github/skills/analyse/SKILL.md index 7895332..aca2109 100644 --- a/.github/skills/analyse/SKILL.md +++ b/.github/skills/analyse/SKILL.md @@ -54,8 +54,6 @@ analysis report. Do not implement changes — that is engineering role work. - Implementation (engineering role) - Full test run (use `verify`) -______________________________________________________________________ - ## Step 0: Define the Question Clarify exactly what is being analysed: @@ -77,8 +75,6 @@ Question: [Precise question being answered] Scope: [What's in and out of scope for this analysis] ``` -______________________________________________________________________ - ## Phase 1: Evidence Gathering Gather all relevant context before drawing any conclusions: @@ -111,8 +107,6 @@ For **dependency analysis**: [ -f package.json ] && npx madge --circular --extensions ts ./src 2>/dev/null || true ``` -______________________________________________________________________ - ## Phase 2: Dimension Analysis Structure the analysis around the relevant dimensions for the question type: @@ -158,8 +152,6 @@ For each option: | ---- | --------------- | --------------- | ---------- | | ... | High/Medium/Low | High/Medium/Low | ... | -______________________________________________________________________ - ## Phase 3: Data & Evidence Support findings with concrete evidence: @@ -175,8 +167,6 @@ Reference specific: - Data points (error counts, latency numbers, test results) - Documentation (ADRs, design docs, API specs) -______________________________________________________________________ - ## Phase 4: Findings & Conclusions Present findings clearly: @@ -197,8 +187,6 @@ State conclusions with confidence level: - **Probable:** well-supported by evidence but not confirmed - **Uncertain:** hypothesis that requires further investigation -______________________________________________________________________ - ## Analysis Report ```text @@ -224,7 +212,5 @@ ______________________________________________________________________ [Overall confidence level: high / medium / low — and why] ``` -______________________________________________________________________ - - + diff --git a/.github/skills/architecture/SKILL.md b/.github/skills/architecture/SKILL.md index 69ed5c4..67e37a0 100644 --- a/.github/skills/architecture/SKILL.md +++ b/.github/skills/architecture/SKILL.md @@ -277,7 +277,5 @@ For each significant structural decision made during this review (technology cho - Cross-reference related ADRs. - Update `docs/architecture/architecture.md` to reflect the final decisions. -______________________________________________________________________ - - + diff --git a/.github/skills/aws-cli/SKILL.md b/.github/skills/aws-cli/SKILL.md new file mode 100644 index 0000000..25586cb --- /dev/null +++ b/.github/skills/aws-cli/SKILL.md @@ -0,0 +1,376 @@ +--- +name: aws-cli +description: 'AWS CLI command reference and workflow patterns for backend engineers. Covers IAM, EC2, S3, RDS, ECS, Lambda, CloudWatch, Secrets Manager, SSM Parameter Store, and cross-account operations. Use when asked to "query AWS", "list resources", "rotate secrets", "check CloudWatch logs", "scale ECS", "run an SSM command", or "script an AWS operation".' +license: 'MIT' +compatibility: 'Requires AWS CLI v2 installed and configured (aws configure or environment variables). IAM permissions vary by operation — principle of least privilege applies.' +metadata: + owner: vstack + maturity: stable +argument-hint: '[service: iam | ec2 | s3 | rds | ecs | lambda | cloudwatch | ssm | secrets]' +user-invocable: true +disable-model-invocation: false +--- +## Skill Context + +This skill is part of **vstack** — a VS Code-native AI engineering workflow system. + +### AskUserQuestion Format + +When you need clarification, use this exact format — never invent or guess: + +> **Question:** [The specific question] +> **Options:** A) … | B) … | C) … +> **Default if no response:** [What you'll do] + +Never ask more than one question at a time without waiting for the answer. + +### Diagram Convention + +When producing hand-authored Markdown outputs, prefer Mermaid for flow, +interaction, lifecycle, state, topology, dependency, and decision diagrams when +the format is supported and improves clarity. Use ASCII as a fallback when +Mermaid is unsupported or would be less readable. Keep ASCII/text trees for +directory structures and other scan-friendly hierarchies. + +# aws-cli — AWS CLI Workflows + +Common AWS CLI patterns for backend and platform engineering tasks. +All commands use `--output json` unless noted; add `--profile ` for +named profiles and `--region ` to override the configured default. + +## Safety rules + +- Always run `aws ... --dry-run` for EC2 operations before executing +- Never hardcode access keys; use IAM roles, `aws configure`, or environment variables +- For destructive operations (delete, terminate, drop), use `--no-cli-pager` and + pipe through `jq` to verify the target list before proceeding +- Use `--query` and `--filters` to narrow scope before running bulk mutations + +## Step 0: Setup and Diagnostics + +```bash +# Check version and active identity +aws --version +aws sts get-caller-identity + +# List configured profiles +aws configure list-profiles + +# Use a named profile for a command +aws s3 ls --profile prod + +# Assume a role (cross-account) +aws sts assume-role \ + --role-arn arn:aws:iam::123456789012:role/DeployRole \ + --role-session-name deploy-session \ + --query 'Credentials.[AccessKeyId,SecretAccessKey,SessionToken]' \ + --output text +``` + +## IAM + +```bash +# List all IAM users +aws iam list-users --query 'Users[*].[UserName,CreateDate]' --output table + +# Show a user's attached policies +aws iam list-attached-user-policies --user-name alice + +# List all roles +aws iam list-roles --query 'Roles[*].[RoleName,Arn]' --output table + +# Show a role's trust policy +aws iam get-role --role-name MyRole --query 'Role.AssumeRolePolicyDocument' + +# List all policies attached to a role +aws iam list-attached-role-policies --role-name MyRole + +# Simulate a policy (check if action is allowed) +aws iam simulate-principal-policy \ + --policy-source-arn arn:aws:iam::123456789012:role/MyRole \ + --action-names s3:GetObject \ + --resource-arns arn:aws:s3:::my-bucket/* + +# Rotate an access key +aws iam create-access-key --user-name alice +aws iam delete-access-key --user-name alice --access-key-id AKIA... +``` + +## S3 + +```bash +# List buckets +aws s3 ls + +# List objects in a bucket (with sizes) +aws s3 ls s3://my-bucket/ --human-readable --recursive | tail -20 + +# Sync local directory to S3 +aws s3 sync ./dist s3://my-bucket/static --delete + +# Copy with server-side encryption +aws s3 cp secret.txt s3://my-bucket/secret.txt --sse aws:kms --sse-kms-key-id alias/my-key + +# Check bucket public access block settings +aws s3api get-public-access-block --bucket my-bucket + +# Check bucket encryption +aws s3api get-bucket-encryption --bucket my-bucket + +# Empty and delete a bucket (destructive) +aws s3 rm s3://my-bucket/ --recursive +aws s3 rb s3://my-bucket +``` + +## EC2 + +```bash +# List running instances +aws ec2 describe-instances \ + --filters "Name=instance-state-name,Values=running" \ + --query 'Reservations[*].Instances[*].[InstanceId,InstanceType,PrivateIpAddress,Tags[?Key==`Name`].Value|[0]]' \ + --output table + +# Start / stop instance +aws ec2 start-instances --instance-ids i-0123456789abcdef0 +aws ec2 stop-instances --instance-ids i-0123456789abcdef0 + +# Get console output (useful when SSH is unavailable) +aws ec2 get-console-output --instance-id i-0123456789abcdef0 --output text + +# List security groups with their rules +aws ec2 describe-security-groups \ + --query 'SecurityGroups[*].[GroupId,GroupName,Description]' \ + --output table + +# Show inbound rules for a security group +aws ec2 describe-security-groups \ + --group-ids sg-12345678 \ + --query 'SecurityGroups[0].IpPermissions' +``` + +## RDS + +```bash +# List all RDS instances +aws rds describe-db-instances \ + --query 'DBInstances[*].[DBInstanceIdentifier,DBInstanceStatus,Engine,EngineVersion,MultiAZ]' \ + --output table + +# Check pending maintenance +aws rds describe-pending-maintenance-actions \ + --query 'PendingMaintenanceActions[*].[ResourceIdentifier,PendingMaintenanceActionDetails[0].Action]' \ + --output table + +# Create a manual snapshot before risky operations +aws rds create-db-snapshot \ + --db-instance-identifier myapp-prod \ + --db-snapshot-identifier myapp-prod-pre-migration-$(date +%Y%m%d) + +# List snapshots +aws rds describe-db-snapshots \ + --db-instance-identifier myapp-prod \ + --query 'DBSnapshots[*].[DBSnapshotIdentifier,SnapshotCreateTime,Status]' \ + --output table + +# Modify instance class (requires reboot) +aws rds modify-db-instance \ + --db-instance-identifier myapp-staging \ + --db-instance-class db.t3.large \ + --apply-immediately +``` + +## ECS + +```bash +# List clusters and services +aws ecs list-clusters +aws ecs list-services --cluster myapp-prod + +# Describe a service +aws ecs describe-services \ + --cluster myapp-prod \ + --services myapp-api \ + --query 'services[0].[serviceName,status,runningCount,desiredCount,taskDefinition]' + +# Force new deployment (rolling update) +aws ecs update-service \ + --cluster myapp-prod \ + --service myapp-api \ + --force-new-deployment + +# Scale a service +aws ecs update-service \ + --cluster myapp-prod \ + --service myapp-api \ + --desired-count 4 + +# List running tasks +aws ecs list-tasks --cluster myapp-prod --service-name myapp-api + +# Get task IP for debugging +aws ecs describe-tasks \ + --cluster myapp-prod \ + --tasks \ + --query 'tasks[0].attachments[0].details' +``` + +## Lambda + +```bash +# List functions +aws lambda list-functions \ + --query 'Functions[*].[FunctionName,Runtime,LastModified]' \ + --output table + +# Invoke a function synchronously +aws lambda invoke \ + --function-name myapp-processor \ + --payload '{"key":"value"}' \ + --cli-binary-format raw-in-base64-out \ + response.json && cat response.json + +# Get function configuration +aws lambda get-function-configuration --function-name myapp-processor + +# Update function code from a zip +aws lambda update-function-code \ + --function-name myapp-processor \ + --zip-file fileb://function.zip + +# Tail recent log output via CloudWatch +aws logs tail /aws/lambda/myapp-processor --follow +``` + +## CloudWatch Logs + +```bash +# List log groups +aws logs describe-log-groups \ + --query 'logGroups[*].[logGroupName,retentionInDays]' \ + --output table + +# Tail a log group in real time +aws logs tail /aws/ecs/myapp --follow --format short + +# Query logs (Insights) +aws logs start-query \ + --log-group-name /aws/ecs/myapp \ + --start-time $(date -d '1 hour ago' +%s) \ + --end-time $(date +%s) \ + --query-string 'fields @timestamp, @message | filter @message like /ERROR/ | sort @timestamp desc | limit 50' + +# Get query results +aws logs get-query-results --query-id + +# Get recent log events from a stream +aws logs get-log-events \ + --log-group-name /aws/ecs/myapp \ + --log-stream-name ecs/myapp-api/abc123 \ + --limit 50 \ + --query 'events[*].[timestamp,message]' \ + --output table +``` + +## Secrets Manager + +```bash +# List secrets +aws secretsmanager list-secrets \ + --query 'SecretList[*].[Name,LastChangedDate]' \ + --output table + +# Get a secret value +aws secretsmanager get-secret-value \ + --secret-id myapp/prod/db_password \ + --query 'SecretString' \ + --output text + +# Rotate a secret (triggers the rotation Lambda) +aws secretsmanager rotate-secret \ + --secret-id myapp/prod/db_password + +# Create a new secret +aws secretsmanager create-secret \ + --name myapp/prod/api_key \ + --description "Third-party API key" \ + --secret-string '{"api_key":""}' + +# Update an existing secret +aws secretsmanager put-secret-value \ + --secret-id myapp/prod/api_key \ + --secret-string '{"api_key":""}' +``` + +## SSM Parameter Store + +```bash +# List parameters by path +aws ssm get-parameters-by-path \ + --path /myapp/prod/ \ + --with-decryption \ + --query 'Parameters[*].[Name,Type,LastModifiedDate]' \ + --output table + +# Get a single parameter +aws ssm get-parameter \ + --name /myapp/prod/db_host \ + --with-decryption \ + --query 'Parameter.Value' \ + --output text + +# Put a parameter (SecureString uses KMS) +aws ssm put-parameter \ + --name /myapp/prod/db_password \ + --type SecureString \ + --value 'mysecretpassword' \ + --key-id alias/myapp-key \ + --overwrite + +# Run a command on EC2 instances via SSM (no SSH required) +aws ssm send-command \ + --document-name "AWS-RunShellScript" \ + --targets "Key=tag:Name,Values=myapp-worker" \ + --parameters 'commands=["systemctl status myapp"]' \ + --query 'Command.CommandId' \ + --output text + +# Get command output +aws ssm get-command-invocation \ + --command-id \ + --instance-id i-0123456789abcdef0 \ + --query '[StandardOutputContent,StandardErrorContent]' +``` + +## Cost and Usage + +```bash +# Show current month cost by service (requires Cost Explorer enabled) +aws ce get-cost-and-usage \ + --time-period Start=$(date +%Y-%m-01),End=$(date +%Y-%m-%d) \ + --granularity MONTHLY \ + --metrics BlendedCost \ + --group-by Type=DIMENSION,Key=SERVICE \ + --query 'ResultsByTime[0].Groups[*].[Keys[0],Metrics.BlendedCost.Amount]' \ + --output table | sort -k2 -rn | head -20 +``` + +## Review Checklist + +- [ ] No access keys hardcoded in scripts — use IAM roles or `aws configure` +- [ ] Destructive commands scoped with `--filters` or explicit resource IDs before running +- [ ] Secrets retrieved from Secrets Manager or SSM — not passed as CLI arguments +- [ ] `--dry-run` used for EC2 mutation operations before executing +- [ ] Scripts use `set -euo pipefail` for safety in bash +- [ ] Cross-account operations use `assume-role` with time-limited session credentials + +## References + +> Always use the official documentation for the AWS CLI version in use — command syntax, flags, and available operations change between v2 minor releases. + +- [AWS CLI v2 command reference](https://awscli.amazonaws.com/v2/documentation/api/latest/index.html) +- [AWS CLI configuration](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html) +- [AWS CLI named profiles](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-profiles.html) + + + diff --git a/.github/skills/cicd/SKILL.md b/.github/skills/cicd/SKILL.md index 1cd8506..eff3bb5 100644 --- a/.github/skills/cicd/SKILL.md +++ b/.github/skills/cicd/SKILL.md @@ -43,8 +43,6 @@ These files live in the PR — the pipeline runs after merge. - Container image authoring (use `container`) - Post-deploy monitoring (CI/CD's responsibility after merge) -______________________________________________________________________ - ## Step 1: Detect context ```bash @@ -58,8 +56,6 @@ ls .github/workflows/ 2>/dev/null || echo "No workflows found" ls Dockerfile 2>/dev/null && echo "Dockerfile present" ``` -______________________________________________________________________ - ## Step 2: CI workflow — `.github/workflows/ci.yml` Runs on every push and PR. Must pass before merge. @@ -72,10 +68,18 @@ on: branches: ["**"] pull_request: branches: [main] + workflow_dispatch: {} + +concurrency: + group: ci-${{ github.ref }} + cancel-in-progress: true jobs: test: runs-on: ubuntu-latest + timeout-minutes: 15 + permissions: + contents: read steps: - uses: actions/checkout@v4 @@ -85,6 +89,11 @@ jobs: - uses: actions/setup-python@v5 with: python-version: "3.12" + - uses: actions/cache@v4 + with: + path: ~/.cache/pip + key: pip-${{ runner.os }}-${{ hashFiles('**/pyproject.toml', '**/requirements*.txt') }} + restore-keys: pip-${{ runner.os }}- - run: pip install -e ".[dev]" - run: ruff check . - run: mypy . @@ -93,6 +102,10 @@ jobs: # Node # - uses: actions/setup-node@v4 # with: { node-version: "22" } + # - uses: actions/cache@v4 + # with: + # path: ~/.npm + # key: npm-${{ runner.os }}-${{ hashFiles('**/package-lock.json') }} # - run: npm ci # - run: npm run lint # - run: npm test @@ -100,12 +113,14 @@ jobs: # Go # - uses: actions/setup-go@v5 # with: { go-version: "1.22" } + # - uses: actions/cache@v4 + # with: + # path: ~/go/pkg/mod + # key: go-${{ runner.os }}-${{ hashFiles('**/go.sum') }} # - run: go vet ./... # - run: go test ./... ``` -______________________________________________________________________ - ## Step 3: Security scan — add to CI or separate workflow Add dependency and secret scanning: @@ -124,14 +139,12 @@ Add dependency and secret scanning: # - run: npm audit --audit-level=high # Secret scan - - uses: trufflesecurity/trufflehog-actions-scan@main + - uses: trufflesecurity/trufflehog-actions-scan@v3 with: path: ./ base: ${{ github.event.repository.default_branch }} ``` -______________________________________________________________________ - ## Step 4: CD workflow — `.github/workflows/cd.yml` Runs on merge to main. Builds and publishes the container image, then triggers deployment. @@ -170,8 +183,6 @@ jobs: Adapt the deploy trigger to match the target platform (Fly.io, Render, Railway, K8s, etc.). -______________________________________________________________________ - ## Step 5: Branch protection (document, don't automate) Record in `docs/architecture/architecture.md` or a README section: @@ -186,19 +197,27 @@ Branch protection rules for `main`: Configure these in GitHub → Settings → Branches. -______________________________________________________________________ - ## Step 6: Review checklist -- [ ] CI workflow triggers on push + PR +- [ ] CI workflow triggers on push + PR + `workflow_dispatch` +- [ ] `concurrency` group set to cancel stale runs +- [ ] `timeout-minutes` set on each job +- [ ] `permissions: contents: read` on CI jobs (least privilege) +- [ ] Dependency cache configured for faster builds - [ ] Lint, type-check, and tests all run in CI -- [ ] Security scan included +- [ ] Security scan included with pinned action version (not `@main`) - [ ] CD triggers only on merge to main - [ ] No secrets hardcoded in workflow files — use `secrets.*` - [ ] Container image tagged with both `latest` and `${{ github.sha }}` - [ ] Workflows validate locally: `act` (optional, for local testing) -______________________________________________________________________ +## References + +> Always use the official documentation for the exact runner version and action versions in use — available runners, contexts, and action APIs change between GitHub updates. + +- [GitHub Actions documentation](https://docs.github.com/en/actions) +- [Workflow syntax reference](https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions) +- [GitHub-hosted runners](https://docs.github.com/en/actions/using-github-hosted-runners/using-github-hosted-runners/about-github-hosted-runners) - + diff --git a/.github/skills/cloudformation/SKILL.md b/.github/skills/cloudformation/SKILL.md new file mode 100644 index 0000000..a015aa9 --- /dev/null +++ b/.github/skills/cloudformation/SKILL.md @@ -0,0 +1,346 @@ +--- +name: cloudformation +description: 'Write, review, and refactor AWS CloudFormation templates. Covers template structure, parameter design, resource naming, stack outputs, cross-stack references, nested stacks, change sets, drift detection, rollback configuration, and security hardening. Use when asked to "write a CloudFormation template", "review this CFN stack", "create a SAM template", "add a CloudFormation resource", or "migrate from CDK to CloudFormation".' +license: 'MIT' +compatibility: 'Requires a skills-compatible agent with repository file access. Requires AWS CLI with appropriate IAM permissions for deploy and drift operations.' +metadata: + owner: vstack + maturity: stable +argument-hint: '[resource type or stack name, e.g. VPC | RDS | ECS service | Lambda function]' +user-invocable: true +disable-model-invocation: false +--- +## Skill Context + +This skill is part of **vstack** — a VS Code-native AI engineering workflow system. + +### AskUserQuestion Format + +When you need clarification, use this exact format — never invent or guess: + +> **Question:** [The specific question] +> **Options:** A) … | B) … | C) … +> **Default if no response:** [What you'll do] + +Never ask more than one question at a time without waiting for the answer. + +### Diagram Convention + +When producing hand-authored Markdown outputs, prefer Mermaid for flow, +interaction, lifecycle, state, topology, dependency, and decision diagrams when +the format is supported and improves clarity. Use ASCII as a fallback when +Mermaid is unsupported or would be less readable. Keep ASCII/text trees for +directory structures and other scan-friendly hierarchies. + +# cloudformation — AWS CloudFormation + +Write and review CloudFormation templates for AWS infrastructure. + +## Out of scope + +- Terraform / Terragrunt IaC (use `terraform` or `terragrunt`) +- General AWS CLI operations (use `aws-cli`) +- CDK authoring (CDK synthesizes to CloudFormation — review the synthesized template with this skill) + +## Step 0: Detect Context + +```bash +# Check for existing stacks and templates +find . -name "*.yaml" -o -name "*.json" | xargs grep -l "AWSTemplateFormatVersion" 2>/dev/null + +# Check for SAM templates +find . -name "template.yaml" -o -name "samconfig.toml" 2>/dev/null + +# List deployed stacks in current region +aws cloudformation list-stacks \ + --stack-status-filter CREATE_COMPLETE UPDATE_COMPLETE \ + --query 'StackSummaries[*].[StackName,StackStatus]' \ + --output table +``` + +## Step 1: Template Structure + +```yaml +AWSTemplateFormatVersion: "2010-09-09" +Description: > + One-line description of what this stack provisions. + Used in the AWS Console — keep it informative. + +Metadata: + AWS::CloudFormation::Interface: + ParameterGroups: + - Label: + default: "Network Configuration" + Parameters: + - VpcId + - SubnetIds + ParameterLabels: + VpcId: + default: "VPC ID" + +Parameters: + Environment: + Type: String + AllowedValues: [dev, staging, prod] + Description: Deployment environment + + VpcId: + Type: AWS::EC2::VPC::Id + Description: VPC to deploy into + +Conditions: + IsProd: !Equals [!Ref Environment, prod] + +Resources: + # ... all resources + +Outputs: + ServiceEndpoint: + Description: Load balancer DNS name + Value: !GetAtt LoadBalancer.DNSName + Export: + Name: !Sub "${AWS::StackName}-ServiceEndpoint" +``` + +## Step 2: Parameters + +```yaml +Parameters: + # Use AWS-specific parameter types for validation + VpcId: + Type: AWS::EC2::VPC::Id + + SubnetIds: + Type: List + + # Constrain values with AllowedValues + InstanceType: + Type: String + Default: t3.medium + AllowedValues: [t3.small, t3.medium, t3.large, m5.large] + + # Mark secrets as NoEcho + DbPassword: + Type: String + NoEcho: true + MinLength: 16 + Description: Database password — supply via SSM Parameter or Secrets Manager + + # Prefer SSM Parameter references over raw values for secrets + DbPasswordSsmPath: + Type: AWS::SSM::Parameter::Value + Default: /myapp/prod/db_password + NoEcho: true +``` + +**Rules:** + +- Use AWS-specific parameter types (`AWS::EC2::VPC::Id`, `AWS::EC2::Subnet::Id`) for automatic validation +- Always add `NoEcho: true` to secret parameters +- Prefer SSM Parameter Store references (`AWS::SSM::Parameter::Value`) for secrets over raw string parameters +- Add `AllowedValues` for all constrained strings + +## Step 3: Resource Naming + +```yaml +Resources: + AppSecurityGroup: + Type: AWS::EC2::SecurityGroup + Properties: + GroupName: !Sub "${AWS::StackName}-app-${Environment}" + VpcId: !Ref VpcId + Tags: + - Key: Environment + Value: !Ref Environment + - Key: ManagedBy + Value: cloudformation +``` + +**Rules:** Logical IDs in PascalCase; physical names use `!Sub "${AWS::StackName}-"` to guarantee cross-stack uniqueness; avoid hardcoded physical names — they block replacement operations. + +## Step 4: Intrinsic Functions + +| Function | Use | +| ------------------------------------ | ------------------------------------------------------ | +| `!Ref` | Reference a parameter or resource's primary identifier | +| `!GetAtt Resource.Attr` | Get a specific attribute of a resource | +| `!Sub "text ${Variable}"` | String interpolation | +| `!Select [n, !Ref List]` | Pick item from a list | +| `!Split [",", !Ref StringList]` | Split a comma-separated string | +| `!ImportValue StackName-Export` | Cross-stack reference | +| `!If [Condition, TrueVal, FalseVal]` | Conditional value | +| `!And`, `!Or`, `!Not`, `!Equals` | Condition logic | + +```yaml +# Cross-stack reference — import an export from another stack +DatabaseEndpoint: !ImportValue + Fn::Sub: "${NetworkStackName}-DatabaseEndpoint" +``` + +## Step 5: Conditions + +```yaml +Conditions: + IsProd: !Equals [!Ref Environment, prod] + IsNotProd: !Not [Condition: IsProd] + EnableDeletion: !Equals [!Ref EnableDeletion, "true"] + +Resources: + ReadReplica: + Type: AWS::RDS::DBInstance + Condition: IsProd # only created in prod + Properties: + # ... + + BucketPolicy: + Type: AWS::S3::BucketPolicy + Properties: + # ... + PolicyDocument: + Statement: + - Effect: !If [IsProd, Deny, Allow] +``` + +## Step 6: Stack Outputs and Cross-Stack References + +```yaml +Outputs: + VpcId: + Description: VPC ID for use by dependent stacks. + Value: !Ref VPC + Export: + Name: !Sub "${AWS::StackName}-VpcId" + + PrivateSubnetIds: + Description: Comma-separated private subnet IDs. + Value: !Join [",", [!Ref PrivateSubnet1, !Ref PrivateSubnet2]] + Export: + Name: !Sub "${AWS::StackName}-PrivateSubnetIds" +``` + +**Cross-stack dependency rules:** + +- Export names must be unique within a region/account +- A stack cannot be deleted while another stack imports its exports +- Use `!ImportValue` sparingly — tight coupling between stacks; consider SSM Parameter Store for loose coupling + +## Step 7: Deploy Workflow + +```bash +# Validate template syntax and resource types +aws cloudformation validate-template --template-body file://template.yaml + +# Lint with cfn-lint (catches more issues than validate) +cfn-lint template.yaml + +# Create/update via change set (recommended — review before execute) +aws cloudformation deploy \ + --template-file template.yaml \ + --stack-name myapp-dev \ + --parameter-overrides \ + Environment=dev \ + VpcId=vpc-12345678 \ + --capabilities CAPABILITY_IAM CAPABILITY_NAMED_IAM \ + --no-execute-changeset # review first + +# Show the change set before executing +aws cloudformation describe-change-set \ + --stack-name myapp-dev \ + --change-set-name \ + --query 'Changes[*].ResourceChange.[Action,ResourceType,LogicalResourceId,Replacement]' \ + --output table + +# Execute after review +aws cloudformation deploy \ + --template-file template.yaml \ + --stack-name myapp-dev \ + --parameter-overrides Environment=dev VpcId=vpc-12345678 \ + --capabilities CAPABILITY_IAM +``` + +## Step 8: Drift Detection + +```bash +# Start drift detection +aws cloudformation detect-stack-drift --stack-name myapp-prod + +# Check detection status (wait until DETECTION_COMPLETE) +aws cloudformation describe-stack-drift-detection-status \ + --stack-drift-detection-id + +# Show drifted resources +aws cloudformation describe-stack-resource-drifts \ + --stack-name myapp-prod \ + --stack-resource-drift-status-filters MODIFIED DELETED \ + --query 'StackResourceDrifts[*].[LogicalResourceId,ResourceType,StackResourceDriftStatus]' \ + --output table +``` + +## Step 9: Security Hardening + +```yaml +# S3 bucket — block public access, enable encryption +AppBucket: + Type: AWS::S3::Bucket + Properties: + BucketEncryption: + ServerSideEncryptionConfiguration: + - ServerSideEncryptionByDefault: + SSEAlgorithm: aws:kms + KMSMasterKeyID: !Ref KmsKey + PublicAccessBlockConfiguration: + BlockPublicAcls: true + BlockPublicPolicy: true + IgnorePublicAcls: true + RestrictPublicBuckets: true + VersioningConfiguration: + Status: Enabled + +# RDS — encryption, no public access, deletion protection in prod +Database: + Type: AWS::RDS::DBInstance + DeletionPolicy: Snapshot + Properties: + StorageEncrypted: true + MultiAZ: !If [IsProd, true, false] + PubliclyAccessible: false + DeletionProtection: !If [IsProd, true, false] + +# Security group — no 0.0.0.0/0 on admin ports +AppSecurityGroup: + Type: AWS::EC2::SecurityGroup + Properties: + SecurityGroupIngress: + - IpProtocol: tcp + FromPort: 443 + ToPort: 443 + CidrIp: 0.0.0.0/0 # HTTPS only — review for internal services +``` + +**cfn-lint errors to enforce:** `E3001` (invalid resource type), `W3045` (unrestricted SG ingress), `E3030` (invalid property values). + +## Review Checklist + +- [ ] `AWSTemplateFormatVersion` and `Description` present +- [ ] All parameters have `Description`; secret parameters have `NoEcho: true` +- [ ] Secrets use SSM Parameter Store references, not raw strings +- [ ] Physical resource names use `!Sub "${AWS::StackName}-..."` to avoid collisions +- [ ] All resources tagged with `Environment` and `ManagedBy: cloudformation` +- [ ] S3 buckets: public access blocked, encryption enabled, versioning on +- [ ] RDS: `StorageEncrypted: true`, `PubliclyAccessible: false`, `DeletionProtection` set in prod +- [ ] Security groups: no `0.0.0.0/0` on SSH/RDP; document HTTPS exceptions +- [ ] IAM roles: least-privilege policies; no `*` actions on `*` resources +- [ ] `cfn-lint` passes with no errors or warnings +- [ ] Change set reviewed before executing in production + +## References + +> Always use the official documentation for the resource types in use — properties, attributes, and supported values change with AWS service updates. + +- [CloudFormation resource reference](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-template-resource-type-ref.html) +- [Intrinsic function reference](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference.html) +- [cfn-lint](https://github.com/aws-cloudformation/cfn-lint) +- [AWS SAM documentation](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/) + + + diff --git a/.github/skills/code-review/SKILL.md b/.github/skills/code-review/SKILL.md index 3841d4d..979c681 100644 --- a/.github/skills/code-review/SKILL.md +++ b/.github/skills/code-review/SKILL.md @@ -216,7 +216,5 @@ Format: Confidence: [HIGH/MEDIUM/LOW — explain if not HIGH] ``` -______________________________________________________________________ - - + diff --git a/.github/skills/codeql/SKILL.md b/.github/skills/codeql/SKILL.md new file mode 100644 index 0000000..ce8f67a --- /dev/null +++ b/.github/skills/codeql/SKILL.md @@ -0,0 +1,253 @@ +--- +name: codeql +description: 'Set up and configure CodeQL code scanning via GitHub Actions or the CodeQL CLI. Covers workflow creation, language matrix, build modes, query suites, monorepo configuration, SARIF output, and alert triage. Use when asked to "set up CodeQL", "configure code scanning", "add a codeql workflow", or "scan for vulnerabilities with CodeQL".' +license: 'MIT' +compatibility: 'Requires a skills-compatible agent with repository file access and terminal command execution. GitHub Advanced Security or public repository required for alert upload.' +metadata: + owner: vstack + maturity: stable +argument-hint: '[languages and setup type: default or advanced]' +user-invocable: true +disable-model-invocation: false +--- +## Skill Context + +This skill is part of **vstack** — a VS Code-native AI engineering workflow system. + +### AskUserQuestion Format + +When you need clarification, use this exact format — never invent or guess: + +> **Question:** [The specific question] +> **Options:** A) … | B) … | C) … +> **Default if no response:** [What you'll do] + +Never ask more than one question at a time without waiting for the answer. + +### Diagram Convention + +When producing hand-authored Markdown outputs, prefer Mermaid for flow, +interaction, lifecycle, state, topology, dependency, and decision diagrams when +the format is supported and improves clarity. Use ASCII as a fallback when +Mermaid is unsupported or would be less readable. Keep ASCII/text trees for +directory structures and other scan-friendly hierarchies. + +# codeql — CodeQL Code Scanning + +Set up and configure CodeQL code scanning via GitHub Actions or the CodeQL CLI. +The output is a workflow file and/or a CodeQL configuration file. + +## Out of scope + +- General security audit (use `security`) +- Dependency vulnerability scanning (use `dependency` or `dependabot`) +- Secret scanning (use `secret-scan`) +- CI/CD pipeline design (use `cicd`) + +## Step 0: Detect Context + +```bash +# Detect existing CodeQL workflow +ls .github/workflows/codeql*.yml 2>/dev/null || echo "No CodeQL workflow found" + +# Detect languages in repo +ls pyproject.toml requirements.txt setup.py 2>/dev/null && echo "Python" +ls package.json 2>/dev/null && echo "JavaScript/TypeScript" +ls go.mod 2>/dev/null && echo "Go" +ls pom.xml build.gradle 2>/dev/null && echo "Java/Kotlin" +ls Cargo.toml 2>/dev/null && echo "Rust" +ls *.csproj 2>/dev/null && echo "C#" +ls .github/workflows/*.yml 2>/dev/null && echo "GitHub Actions (workflows present)" +``` + +## Step 1: Choose Setup Type + +| Setup type | When to use | +| ------------ | ---------------------------------------------------------------------------------------------------------------------------- | +| **Default** | Enable from Settings → Advanced Security → Code scanning. Best for getting started — no workflow file needed. | +| **Advanced** | Create `.github/workflows/codeql.yml` for full control over triggers, build modes, query suites, and monorepo configuration. | + +To switch from default to advanced: disable default setup first, then commit the workflow. + +## Step 2: Supported Languages + +| Language | Identifier | Build mode | +| --------------------- | ----------------------- | ----------------------- | +| Python | `python` | `none` | +| JavaScript/TypeScript | `javascript-typescript` | `none` | +| Go | `go` | `none` or `autobuild` | +| Java/Kotlin | `java-kotlin` | `autobuild` or `manual` | +| C/C++ | `c-cpp` | `autobuild` or `manual` | +| C# | `csharp` | `autobuild` or `manual` | +| Rust | `rust` | `none` | +| Swift | `swift` | `autobuild` or `manual` | +| GitHub Actions | `actions` | `none` | + +Build modes: + +- `none` — no build required (safe default for interpreted languages) +- `autobuild` — automatic build detection +- `manual` — explicit build commands between `init` and `analyze` steps + +## Step 3: Write the Workflow + +Create `.github/workflows/codeql.yml`: + +```yaml +name: CodeQL + +on: + push: + branches: [main] + pull_request: + branches: [main] + schedule: + - cron: '30 6 * * 1' # Weekly, Monday 06:30 UTC + +jobs: + analyze: + name: Analyze (${{ matrix.language }}) + runs-on: ubuntu-latest + timeout-minutes: 30 + permissions: + security-events: write # Required to upload SARIF results + contents: read # Required to check out code + actions: read # Required for private repos + + strategy: + fail-fast: false + matrix: + include: + # Add one entry per language detected in Step 0. + # Examples: + - language: python + build-mode: none + - language: javascript-typescript + build-mode: none + # Compiled language example: + # - language: java-kotlin + # build-mode: autobuild + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Initialize CodeQL + uses: github/codeql-action/init@v4 + with: + languages: ${{ matrix.language }} + build-mode: ${{ matrix.build-mode }} + queries: security-extended + dependency-caching: true + + # For manual build mode only — add build commands here: + # - if: matrix.build-mode == 'manual' + # name: Build + # run: | + # make build + + - name: Perform CodeQL Analysis + uses: github/codeql-action/analyze@v4 + with: + category: "/language:${{ matrix.language }}" +``` + +**Query suite options:** + +| Suite | Coverage | +| ----------------------- | ---------------------------------------------------------- | +| `security-extended` | Default security queries + additional checks (recommended) | +| `security-and-quality` | Security + code quality queries (larger, slower) | +| `security-experimental` | Experimental queries (higher false-positive rate) | + +## Step 4: Monorepo and Path Configuration (optional) + +To restrict analysis to specific paths, create `.github/codeql/codeql-config.yml`: + +```yaml +paths: + - src/ + - apps/ +paths-ignore: + - '**/test/**' + - '**/node_modules/**' + - '**/vendor/**' +``` + +Reference it in the workflow: + +```yaml +- uses: github/codeql-action/init@v4 + with: + config-file: .github/codeql/codeql-config.yml +``` + +For monorepos with per-component results: + +```yaml +category: "/language:${{ matrix.language }}/component:backend" +``` + +To skip documentation-only PRs: + +```yaml +on: + pull_request: + branches: [main] + paths-ignore: + - '**/*.md' + - 'docs/**' +``` + +## Step 5: Alert Triage + +Alerts appear in the repository Security tab after the first scan. + +**Severity levels:** + +- Security severity: `Critical`, `High`, `Medium`, `Low` (from CVSS score) +- Standard severity: `Error`, `Warning`, `Note` + +**Review policy:** + +- Fix all `Critical` and `High` findings before merging +- Dismiss false positives with a documented reason (creates an audit trail) +- Copilot Autofix generates fix suggestions automatically for CodeQL alerts in PRs — review carefully before accepting + +## Step 6: CodeQL CLI (local scanning) + +```bash +# Create database (after adding codeql binary to PATH) +codeql database create codeql-db --language=python --source-root=src + +# Analyze +codeql database analyze codeql-db \ + python-security-extended.qls --format=sarif-latest --output=results.sarif + +# Upload to GitHub +GITHUB_TOKEN= codeql github upload-results \ + --repository= --ref=refs/heads/main --commit= --sarif=results.sarif +``` + +## Review checklist + +- [ ] One matrix entry per detected language +- [ ] `permissions: security-events: write` set on the job +- [ ] `queries: security-extended` (or stronger) +- [ ] `dependency-caching: true` on `init` step +- [ ] `timeout-minutes` set on job +- [ ] Weekly `schedule` trigger set for the default branch +- [ ] Compiled language build mode confirmed (`autobuild` or `manual`) +- [ ] `paths-ignore` excludes documentation-only PRs if useful +- [ ] Actions pinned to `@v4` (not floating `@main`) + +## References + +> Always use the official documentation for the exact version in use — action versions, query suites, and language identifiers change between releases. + +- [CodeQL documentation](https://docs.github.com/en/code-security/code-scanning/introduction-to-code-scanning/about-code-scanning-with-codeql) +- [github/codeql-action releases](https://github.com/github/codeql-action/releases) +- [Supported languages and frameworks](https://docs.github.com/en/code-security/code-scanning/introduction-to-code-scanning/codeql-code-scanning-for-compiled-languages) + + + diff --git a/.github/skills/concise/SKILL.md b/.github/skills/concise/SKILL.md index 8a31af6..8ff9138 100644 --- a/.github/skills/concise/SKILL.md +++ b/.github/skills/concise/SKILL.md @@ -42,8 +42,6 @@ Control response brevity at runtime without regenerating any agent artifacts. - Persisting style mode across independent chat sessions - Overriding safety-critical clarity requirements -______________________________________________________________________ - ## Commands Supported commands: @@ -62,8 +60,6 @@ Unknown arguments: - If argument is unknown, do not guess. Return usage and keep current mode unchanged. -______________________________________________________________________ - ## Mode Semantics - `normal`: full, explicit explanation depth. @@ -76,8 +72,6 @@ Hard invariants for all concise modes: - Do not remove required warnings, constraints, or irreversible-action cautions. - Never trade correctness for brevity. -______________________________________________________________________ - ## Priority and Resolution Resolve active mode with this precedence: @@ -95,8 +89,6 @@ Resolve active mode with this precedence: - global default mode - whether auto-clarity override is currently active -______________________________________________________________________ - ## Suggested Agent Defaults When no session override exists, use these defaults: @@ -108,8 +100,6 @@ When no session override exists, use these defaults: - `tester`: `ultra` - `release`: `compact` -______________________________________________________________________ - ## Auto-Clarity Override (Mandatory) Temporarily force `normal` regardless of active concise mode for: @@ -121,8 +111,6 @@ Temporarily force `normal` regardless of active concise mode for: After the high-clarity segment ends, return to previously active concise mode. -______________________________________________________________________ - ## Expected Responses On successful mode switch: @@ -150,8 +138,6 @@ Usage: concise normal|compact|ultra|status|on|off Current mode unchanged: ``` -______________________________________________________________________ - ## Completion Checklist - [ ] Command parsed and validated @@ -160,4 +146,4 @@ ______________________________________________________________________ - [ ] User confirmation/status returned in deterministic format - + diff --git a/.github/skills/consult/SKILL.md b/.github/skills/consult/SKILL.md index 9bd9711..6532b9f 100644 --- a/.github/skills/consult/SKILL.md +++ b/.github/skills/consult/SKILL.md @@ -49,8 +49,6 @@ Read only — do not change any code. - Performance profiling/regression analysis (use `performance`) - Tradeoff/impact/feasibility analysis (use `analyse`) -______________________________________________________________________ - ## Step 0: Classify and Route Determine the user's real intent before reviewing anything. @@ -81,8 +79,6 @@ If D, stop and return this routing recommendation: Do not continue with DX scoring when routing to another skill. -______________________________________________________________________ - ## Step 1: Run Exactly One Path Run only the selected path (A, B, or C). Skip all others. @@ -186,8 +182,6 @@ cat .github/workflows/*.yml 2>/dev/null | grep -E 'timeout|runs-on|steps' | head - Is there type checking? - Are these run on commit (pre-commit hooks) or in CI? -______________________________________________________________________ - ## Step 2: Improvement Plan (ROI-first) For each weak area (typically score < 7), provide: @@ -196,8 +190,6 @@ For each weak area (typically score < 7), provide: 1. **Medium investment (1-2 days):** Most likely path to 9/10. 1. **Long-term:** Structural change to reach 10/10. -______________________________________________________________________ - ## Output Contract ```text @@ -224,7 +216,5 @@ recommended_skill: [design|analyse|debug|code-review|security|performance|verify reason: [one sentence] ``` -______________________________________________________________________ - - + diff --git a/.github/skills/container/SKILL.md b/.github/skills/container/SKILL.md index 0e69340..8f0a472 100644 --- a/.github/skills/container/SKILL.md +++ b/.github/skills/container/SKILL.md @@ -42,8 +42,6 @@ Write production-grade container configuration for the service. - Kubernetes manifests (use `cicd`) - Application code changes (engineering role) -______________________________________________________________________ - ## Step 1: Detect context ```bash @@ -54,8 +52,6 @@ ls pyproject.toml requirements.txt package.json go.mod Cargo.toml pom.xml 2>/dev ls Dockerfile* docker-compose* .dockerignore 2>/dev/null || echo "No container config found" ``` -______________________________________________________________________ - ## Step 2: Dockerfile Write a multi-stage `Dockerfile` following these rules: @@ -110,8 +106,6 @@ ENTRYPOINT [""] CMD [""] ``` -______________________________________________________________________ - ## Step 3: docker-compose.yml (local dev) Write `docker-compose.yml` for local development: @@ -138,8 +132,6 @@ services: For production-like local testing, write a separate `docker-compose.prod.yml` without volume mounts. -______________________________________________________________________ - ## Step 4: Review checklist - [ ] No `latest` tags @@ -151,7 +143,13 @@ ______________________________________________________________________ - [ ] Image builds successfully: `docker build -t app:local .` - [ ] Container starts and responds: `docker run --rm -p : app:local` -______________________________________________________________________ +## References + +> Always use the official documentation for the Docker and Compose versions in use — Dockerfile syntax, base image tags, and Compose spec fields evolve with each release. + +- [Dockerfile reference](https://docs.docker.com/reference/dockerfile/) +- [Docker Compose specification](https://docs.docker.com/compose/intro/compose-application-model/) +- [Docker official images](https://hub.docker.com/search?image_filter=official) - + diff --git a/.github/skills/conventional-commit/SKILL.md b/.github/skills/conventional-commit/SKILL.md new file mode 100644 index 0000000..5f66f2d --- /dev/null +++ b/.github/skills/conventional-commit/SKILL.md @@ -0,0 +1,157 @@ +--- +name: conventional-commit +description: 'Prepare high-quality Conventional Commit messages from current staged or unstaged changes with explicit type, optional scope, and concise subject. Validates commit intent against change content and blocks ambiguous or non-compliant messages before commit. Use when asked to "write a commit message", "make a conventional commit", or "prepare commits before PR".' +license: 'MIT' +compatibility: 'Requires a skills-compatible agent with repository file access and terminal command execution.' +metadata: + owner: vstack + maturity: stable +argument-hint: '[changes to commit and desired release intent]' +user-invocable: true +disable-model-invocation: false +--- +## Skill Context + +This skill is part of **vstack** — a VS Code-native AI engineering workflow system. + +### AskUserQuestion Format + +When you need clarification, use this exact format — never invent or guess: + +> **Question:** [The specific question] +> **Options:** A) … | B) … | C) … +> **Default if no response:** [What you'll do] + +Never ask more than one question at a time without waiting for the answer. + +### Diagram Convention + +When producing hand-authored Markdown outputs, prefer Mermaid for flow, +interaction, lifecycle, state, topology, dependency, and decision diagrams when +the format is supported and improves clarity. Use ASCII as a fallback when +Mermaid is unsupported or would be less readable. Keep ASCII/text trees for +directory structures and other scan-friendly hierarchies. + +# conventional-commit — Prepare Conventional Commits + +Create clear, policy-aligned commits with a Conventional Commit header: + +`type(optional-scope)!: short summary` + +## Out of scope + +- Pushing branches or opening PRs (use `pr`) +- Writing release notes (use `release-notes`) +- Rewriting repository history unless explicitly requested + +## Deliverable + +- One or more commits with compliant Conventional Commit messages + +## Step 1: Inspect changes and choose commit boundaries + +Review current changes first: + +```bash +git status --short +git diff --stat +git diff --cached --stat +``` + +Split unrelated changes into separate commits. + +Boundary rules: + +- One commit per cohesive intent +- Avoid mixing refactor + feature + tests unless tightly coupled +- Keep commits reviewable and reversible + +## Step 2: Select commit type and scope + +Choose the best type from change intent: + +- `feat` for new behavior +- `fix` for bug fixes +- `refactor` for structure-only changes without behavior change +- `docs` for documentation-only changes +- `test` for test-only changes +- `chore` for maintenance/tooling/meta updates +- `ci` for CI/CD workflow changes +- `perf` for performance-focused improvements + +Scope guidance: + +- Use optional scope when it improves clarity: `feat(auth): ...` +- Keep scope short, stable, and system-oriented +- Omit scope if it adds noise + +## Step 3: Draft header and body + +Header format: + +```text +type(optional-scope)!: short summary +``` + +Quality rules: + +- imperative mood (`add`, `fix`, `remove`) +- summary \<= 100 characters +- no trailing period +- no vague text like `update stuff` + +Use breaking marker `!` only when behavior or contract is breaking. + +Optional body should explain why, risk, and migration notes when relevant. + +## Step 4: Validate against staged content + +Before committing, verify message-content alignment: + +```bash +git diff --cached --name-only +git diff --cached --stat +``` + +Validation checks: + +- `docs` commit does not include source code changes (unless explicitly intended) +- `test` commit does not include product logic changes (unless fixing test harness) +- `refactor` commit does not change observable behavior +- breaking marker appears only with actual breaking impact + +If alignment fails, revise scope/type or split commits. + +## Step 5: Commit safely + +Commit staged changes with validated header: + +```bash +git commit -m "" +``` + +For non-trivial changes, include body: + +```bash +git commit \ + -m "" \ + -m "Why: " \ + -m "Risk: " +``` + +## Step 6: Report result + +Return concise result: + +```text +Committed: +-
+ +Remaining changes: +- +``` + +If commit is blocked, report exact reason and proposed fix. + + + diff --git a/.github/skills/debug/SKILL.md b/.github/skills/debug/SKILL.md index 5f01c1b..d808802 100644 --- a/.github/skills/debug/SKILL.md +++ b/.github/skills/debug/SKILL.md @@ -55,8 +55,6 @@ Follow the scientific method: 1. **Fix** — Minimal change that addresses root cause 1. **Prevent** — Add a test that would have caught this -______________________________________________________________________ - ## Step 0: Understand the Problem Before touching any code, gather complete context: @@ -88,8 +86,6 @@ git stash list git diff HEAD~10 -- package.json package-lock.json go.mod go.sum pyproject.toml 2>/dev/null | head -40 ``` -______________________________________________________________________ - ## Step 1: Reproduce **First, reproduce the bug reliably before attempting any fix.** @@ -115,8 +111,6 @@ Reproducer: Environment: [local / CI / staging / prod] ``` -______________________________________________________________________ - ## Step 2: Gather Evidence **Read all available logs and error output:** @@ -142,8 +136,6 @@ cat /var/log/app.log 2>/dev/null | tail -100 || true git diff HEAD~3 -- relevant-files ``` -______________________________________________________________________ - ## Step 3: Form Hypotheses Based on evidence, list hypotheses in order of likelihood: @@ -170,8 +162,6 @@ Hypotheses (most likely first): - **Memory:** Leak, fragmentation, GC pressure - **Timing:** TTL expiry, clock skew, eventual consistency window -______________________________________________________________________ - ## Step 4: Test Each Hypothesis For each hypothesis in rank order: @@ -193,8 +183,6 @@ go test -race ./... 2>/dev/null || true Eliminate hypotheses one by one until only one remains. -______________________________________________________________________ - ## Step 5: Root Cause Identification State the root cause with precision: @@ -208,8 +196,6 @@ Root Cause: Scope: [Which environments? Which users? How often?] ``` -______________________________________________________________________ - ## Step 6: Fix Design the minimal fix: @@ -224,8 +210,6 @@ Design the minimal fix: # Run the reproducer to confirm it's fixed ``` -______________________________________________________________________ - ## Step 7: Regression Test Add a test that would have caught this bug: @@ -250,8 +234,6 @@ Reproducer: [if non-obvious] Test: [test file added/updated]" ``` -______________________________________________________________________ - ## Step 8: Prevent Recurrence Consider: @@ -262,8 +244,6 @@ Consider: 1. Should an alert be added to catch this class of failure in production? 1. Should TODOS.md be updated with related improvements? -______________________________________________________________________ - ## Debug Summary ```text @@ -276,7 +256,5 @@ Regression test: [test file:function] Prevention: [any follow-up items] ``` -______________________________________________________________________ - - + diff --git a/.github/skills/dependabot/SKILL.md b/.github/skills/dependabot/SKILL.md new file mode 100644 index 0000000..5fd9934 --- /dev/null +++ b/.github/skills/dependabot/SKILL.md @@ -0,0 +1,322 @@ +--- +name: dependabot +description: 'Create or optimize a Dependabot configuration file (.github/dependabot.yml). Covers dependency update strategies, grouping, monorepo patterns, security update configuration, schedule optimization, and PR customization. Use when asked to "set up Dependabot", "configure dependency updates", "add dependabot.yml", or "reduce Dependabot PR noise".' +license: 'MIT' +compatibility: 'Requires a skills-compatible agent with repository file access. Dependabot requires GitHub repository access (public or private with GitHub Advanced Security for private).' +metadata: + owner: vstack + maturity: stable +argument-hint: '[repository type: library | service | monorepo, and ecosystems to cover]' +user-invocable: true +disable-model-invocation: false +--- +## Skill Context + +This skill is part of **vstack** — a VS Code-native AI engineering workflow system. + +### AskUserQuestion Format + +When you need clarification, use this exact format — never invent or guess: + +> **Question:** [The specific question] +> **Options:** A) … | B) … | C) … +> **Default if no response:** [What you'll do] + +Never ask more than one question at a time without waiting for the answer. + +### Diagram Convention + +When producing hand-authored Markdown outputs, prefer Mermaid for flow, +interaction, lifecycle, state, topology, dependency, and decision diagrams when +the format is supported and improves clarity. Use ASCII as a fallback when +Mermaid is unsupported or would be less readable. Keep ASCII/text trees for +directory structures and other scan-friendly hierarchies. + +# dependabot — Dependabot Configuration + +Create or optimize `.github/dependabot.yml` for automated dependency updates. +One file handles all ecosystems — GitHub does not support multiple `dependabot.yml` +files per repository. + +## Out of scope + +- Manual dependency upgrades (use `dependency`) +- Vulnerability triage in code (use `security`) +- CodeQL code scanning (use `codeql`) +- Secret scanning (use `secret-scan`) + +## Step 0: Detect Ecosystems + +```bash +# Find all manifest files to determine which ecosystems are present +ls pyproject.toml requirements*.txt setup.py Pipfile 2>/dev/null && echo "pip" +ls package.json package-lock.json yarn.lock pnpm-lock.yaml 2>/dev/null && echo "npm" +ls go.mod 2>/dev/null && echo "gomod" +ls Cargo.toml 2>/dev/null && echo "cargo" +ls pom.xml 2>/dev/null && echo "maven" +ls build.gradle build.gradle.kts 2>/dev/null && echo "gradle" +ls Gemfile 2>/dev/null && echo "bundler" +ls Dockerfile 2>/dev/null && echo "docker" +ls docker-compose*.yml 2>/dev/null && echo "docker-compose" +ls .github/workflows/*.yml 2>/dev/null && echo "github-actions" +ls *.tf 2>/dev/null && echo "terraform" +ls Chart.yaml 2>/dev/null && echo "helm" + +# Check existing dependabot config +cat .github/dependabot.yml 2>/dev/null || echo "No dependabot.yml found" +``` + +## Step 1: Ecosystem Reference + +| Ecosystem | `package-ecosystem` | Manifest files | +| ----------------- | ------------------- | ------------------------------------------------------------------ | +| pip / poetry / uv | `pip` | `pyproject.toml`, `requirements*.txt`, `Pipfile` | +| npm / pnpm / yarn | `npm` | `package.json`, `package-lock.json`, `pnpm-lock.yaml`, `yarn.lock` | +| Go | `gomod` | `go.mod` | +| Rust | `cargo` | `Cargo.toml` | +| Maven | `maven` | `pom.xml` | +| Gradle | `gradle` | `build.gradle`, `build.gradle.kts` | +| Bundler | `bundler` | `Gemfile` | +| Docker | `docker` | `Dockerfile` | +| Docker Compose | `docker-compose` | `docker-compose*.yml` | +| GitHub Actions | `github-actions` | `.github/workflows/*.yml` | +| Terraform | `terraform` | `*.tf` | +| Helm | `helm` | `Chart.yaml` | +| NuGet | `nuget` | `*.csproj`, `packages.config` | +| Pre-commit | `pre-commit` | `.pre-commit-config.yaml` | + +Note: pnpm and yarn both use `package-ecosystem: "npm"`. + +## Step 2: Minimal Configuration + +Every entry needs at minimum: + +```yaml +version: 2 + +updates: + - package-ecosystem: "pip" + directory: "/" + schedule: + interval: "weekly" +``` + +Default schedule: weekly on Monday. Add `time` and `timezone` for +predictable windows: + +```yaml +schedule: + interval: "weekly" + day: "monday" + time: "09:00" + timezone: "Europe/Amsterdam" +``` + +## Step 3: Full Example (common stack) + +```yaml +version: 2 + +updates: + # Python dependencies + - package-ecosystem: "pip" + directory: "/" + schedule: + interval: "weekly" + day: "monday" + groups: + python-deps: + dependency-type: "production" + update-types: ["minor", "patch"] + python-dev-deps: + dependency-type: "development" + update-types: ["minor", "patch"] + commit-message: + prefix: "deps" + labels: + - "dependencies" + - "python" + + # GitHub Actions + - package-ecosystem: "github-actions" + directory: "/" + schedule: + interval: "weekly" + commit-message: + prefix: "ci" + labels: + - "dependencies" + - "ci" +``` + +## Step 4: Grouping Strategies + +Reduce PR noise by grouping related updates. + +### By dependency type + +```yaml +groups: + dev-dependencies: + dependency-type: "development" + update-types: ["minor", "patch"] + production-dependencies: + dependency-type: "production" + update-types: ["minor", "patch"] +``` + +### By name pattern + +```yaml +groups: + aws-sdk: + patterns: ["boto3", "botocore", "aws-*"] + update-types: ["minor", "patch"] + testing: + patterns: ["pytest*", "coverage*", "mypy*"] +``` + +### For security updates only + +```yaml +groups: + security-patches: + applies-to: security-updates + patterns: ["*"] + update-types: ["patch", "minor"] +``` + +**Rules:** + +- Dependencies matching multiple groups go to the **first** match +- `applies-to` defaults to `version-updates` when absent +- Ungrouped dependencies get individual PRs + +## Step 5: Monorepo Configuration + +Use `directories` (plural) with glob patterns — `directory` (singular) does not support globs: + +```yaml +- package-ecosystem: "npm" + directories: + - "/" + - "/apps/*" + - "/packages/*" + schedule: + interval: "weekly" +``` + +If a subdirectory has its own lockfile outside the workspace, add a separate +entry with `directory` pointing to that location. + +## Step 6: Security Updates + +Enable via repository **Settings → Advanced Security → Dependabot alerts and +security updates**. + +To group security PRs: + +```yaml +groups: + security-patches: + applies-to: security-updates + patterns: ["*"] + update-types: ["patch", "minor"] +``` + +To disable version update PRs and keep only security updates: + +```yaml +open-pull-requests-limit: 0 +``` + +## Step 7: Ignore and Allow Rules + +### Pin a dependency at its current version + +```yaml +ignore: + - dependency-name: "django" + versions: ["4.x", "5.x"] +``` + +### Only update production dependencies + +```yaml +allow: + - dependency-type: "production" +``` + +### Exclude vendor paths + +```yaml +exclude-paths: + - "vendor/**" + - "test/fixtures/**" +``` + +## Step 8: Advanced Options + +### Cooldown periods + +```yaml +cooldown: + default-days: 5 + semver-major-days: 30 + semver-minor-days: 7 +``` + +### Versioning strategy + +`auto` (default) increases the minimum for apps and widens ranges for libraries. +Use `lockfile-only` to update only lock files without touching manifests. +Use `increase-if-necessary` to change the range only when it excludes the new version. + +### Private registries + +```yaml +registries: + pypi-private: + type: python-index + url: https://pypi.example.com + token: ${{ secrets.PYPI_TOKEN }} + +updates: + - package-ecosystem: "pip" + directory: "/" + registries: + - pypi-private +``` + +## PR Comment Commands + +| Comment | Effect | +| --------------------------------------- | ------------------------- | +| `@dependabot rebase` | Rebase the PR | +| `@dependabot recreate` | Recreate from scratch | +| `@dependabot ignore this dependency` | Close and never update | +| `@dependabot ignore this major version` | Ignore this major version | +| `@dependabot ignore this minor version` | Ignore this minor version | +| `@dependabot ignore this patch version` | Ignore this patch version | + +## Review checklist + +- [ ] Every detected ecosystem has an entry +- [ ] `github-actions` ecosystem included to keep workflow action versions current +- [ ] Groups configured to reduce PR noise +- [ ] `commit-message.prefix` set per ecosystem for clear history +- [ ] `open-pull-requests-limit` appropriate for team capacity (default: 5) +- [ ] Security update grouping configured +- [ ] Monorepo: `directories` (plural) with globs if workspace spans subdirs +- [ ] Private registries use `${{ secrets.* }}` — never hardcoded tokens + +## References + +> Always use the official documentation for the exact version in use — supported ecosystems, grouping syntax, and available options expand with each release. + +- [Dependabot configuration options](https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file) +- [Supported package ecosystems](https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/about-dependabot-version-updates#supported-repositories-and-ecosystems) +- [Dependabot security updates](https://docs.github.com/en/code-security/dependabot/dependabot-security-updates/about-dependabot-security-updates) + + + diff --git a/.github/skills/dependency/SKILL.md b/.github/skills/dependency/SKILL.md index 4575d83..1b5db8d 100644 --- a/.github/skills/dependency/SKILL.md +++ b/.github/skills/dependency/SKILL.md @@ -50,8 +50,6 @@ risk, pinning policy, and supply chain hygiene. **Golden rule: A dependency is owned code you didn't write. Treat it with the same scrutiny as your own code.** -______________________________________________________________________ - ## Step 0: Detect the Stack ```bash @@ -77,8 +75,6 @@ Manifests: [list of files found] Lock file: [present | absent — flag if absent] ``` -______________________________________________________________________ - ## Part 1: Vulnerability Scan Run the appropriate scanner for each detected stack: @@ -123,8 +119,6 @@ Vulnerabilities found: should be tracked and resolved within the sprint. LOW may be deferred with documented rationale. -______________________________________________________________________ - ## Part 2: Outdated Packages ```bash @@ -158,8 +152,6 @@ Classify each outdated package: - Minor updates: update soon (check changelog for deprecations) - Major updates: plan upgrade (read migration guide, test thoroughly) -______________________________________________________________________ - ## Part 3: Licence Compliance Check licence obligations for all direct and transitive dependencies: @@ -201,8 +193,6 @@ Licence issues: 🔴 [package] — [licence] — [risk] — [recommendation] ``` -______________________________________________________________________ - ## Part 4: Pinning Policy A healthy dependency policy requires reproducible builds: @@ -230,8 +220,6 @@ cat pyproject.toml 2>/dev/null | grep -E '^\s+[a-z]' | grep -v '^#' | head -30 | `package = "1.2.3"` (exact) | Low | Fine for direct deps; brittle for transitive | | No lock file | High | Add lock file and commit it | -______________________________________________________________________ - ## Part 5: Transitive Risk Identify high-risk transitive (indirect) dependencies: @@ -263,8 +251,6 @@ Flags to look for: # (manual step: check PyPI / npm registry for each critical dep) ``` -______________________________________________________________________ - ## Part 6: Supply Chain Hygiene ```bash @@ -287,8 +273,6 @@ Check: - [ ] `pip install` / `npm install` output reviewed for unexpected packages - [ ] CI pipeline pins the package manager version itself -______________________________________________________________________ - ## Output ```text @@ -324,5 +308,13 @@ Action items (priority order): 2. ... ``` +## References + +> Always use the official advisories and registry documentation for the ecosystems in use — vulnerability databases and package registry APIs are updated continuously. + +- [GitHub Advisory Database](https://github.com/advisories) +- [OSV — Open Source Vulnerabilities](https://osv.dev/) +- [PyPI / npm / crates.io / Maven Central](https://pypi.org) (replace with the relevant registry) + - + diff --git a/.github/skills/design/SKILL.md b/.github/skills/design/SKILL.md index 4f0fdce..cd451a8 100644 --- a/.github/skills/design/SKILL.md +++ b/.github/skills/design/SKILL.md @@ -44,8 +44,6 @@ becomes the source of truth for implementation. - Implementation (engineering role) - Contract compliance validation (use `verify` or `code-review`) -______________________________________________________________________ - ## Deliverable and artifact policy - Primary deliverable: `docs/design/design.md` @@ -54,8 +52,6 @@ ______________________________________________________________________ - Optional WIP area for complex/uncertain efforts: `docs/delta/{id}/DESIGN_DELTA.md` - Before merge: consolidate any delta draft into baseline design docs. -______________________________________________________________________ - ## Step 0: Understand the Domain > **Question:** What are we designing? @@ -74,8 +70,6 @@ Gather context: find . -name 'openapi*' -o -name '*.proto' -o -name 'asyncapi*' 2>/dev/null | head -5 ``` -______________________________________________________________________ - ## Step 1: Resource Design For each resource/entity in the domain: @@ -103,8 +97,6 @@ erDiagram } ``` -______________________________________________________________________ - ## Step 2: Endpoint Design For each resource, define CRUD + custom actions: @@ -122,8 +114,6 @@ POST /users/{id}/activate # Non-CRUD action POST /users/{id}/deactivate ``` -______________________________________________________________________ - ## Step 3: Request/Response Conventions Define the standard envelope: @@ -158,8 +148,6 @@ Define the standard envelope: } ``` -______________________________________________________________________ - ## Step 4: Error Code Taxonomy Define a machine-readable error code taxonomy: @@ -188,8 +176,6 @@ DEPENDENCY_ERROR — Upstream service failure UNAVAILABLE — Service temporarily unavailable ``` -______________________________________________________________________ - ## Step 5: Versioning & Contract Discipline Define the versioning approach: @@ -218,8 +204,6 @@ Deprecation process: - MINOR → new optional fields, backward compatible - MAJOR → breaking change -______________________________________________________________________ - ## Step 6: Authentication & Authorization ```text @@ -229,8 +213,6 @@ Token claims: user_id, roles[], tenant_id Authorization model: RBAC with per-resource checks ``` -______________________________________________________________________ - ## Step 7: Produce the Design Document Output a complete design document to `docs/design/design.md` or `openapi.yaml`: @@ -260,7 +242,5 @@ Output a complete design document to `docs/design/design.md` or `openapi.yaml`: [Input validation, rate limiting, CORS policy] ``` -______________________________________________________________________ - - + diff --git a/.github/skills/docs/SKILL.md b/.github/skills/docs/SKILL.md index 002e127..7731e3f 100644 --- a/.github/skills/docs/SKILL.md +++ b/.github/skills/docs/SKILL.md @@ -60,8 +60,6 @@ change source code. - Optional WIP area for complex/uncertain efforts: `docs/delta/{id}/DOCS_DELTA.md` - Before merge: consolidate any documentation delta notes into baseline docs. -______________________________________________________________________ - ## Step 0: Scope the Release ```bash @@ -75,8 +73,6 @@ cat VERSION 2>/dev/null \ || echo "unknown" ``` -______________________________________________________________________ - ## Step 1: README Review whether README needs updates: @@ -93,8 +89,6 @@ Check: - [ ] Any deprecated features removed from featured examples? - [ ] Badges (version, CI status) still accurate? -______________________________________________________________________ - ## Step 2: API Documentation If there's an OpenAPI / AsyncAPI spec: @@ -117,8 +111,6 @@ If there's generated API documentation (Swagger UI, Redoc, TypeDoc, Sphinx): npm run docs 2>/dev/null || make docs 2>/dev/null || true ``` -______________________________________________________________________ - ## Step 3: MIGRATIONS Guide (if applicable) If this release contains breaking changes or migration steps: @@ -126,8 +118,6 @@ If this release contains breaking changes or migration steps: - Create or update `MIGRATIONS.md` or `docs/migrations/vX.md` - Document: why the change was made, what behavior changed, migration steps, code examples -______________________________________________________________________ - ## Step 4: Code Comments & ADRs For significant architectural changes: @@ -138,8 +128,6 @@ For significant architectural changes: (use the `adr` skill for the full ADR writing procedure) -______________________________________________________________________ - ## Step 5: Commit Documentation Updates ```bash @@ -147,8 +135,6 @@ git add README.md openapi.yaml docs/ 2>/dev/null || true git commit -m "docs: update documentation for v$(cat VERSION 2>/dev/null || echo 'unknown')" ``` -______________________________________________________________________ - ## Summary ```text @@ -164,7 +150,5 @@ Skipped (n/a): - [ ] [reason] ``` -______________________________________________________________________ - - + diff --git a/.github/skills/explore/SKILL.md b/.github/skills/explore/SKILL.md index 1b6f5c8..5ef71cf 100644 --- a/.github/skills/explore/SKILL.md +++ b/.github/skills/explore/SKILL.md @@ -43,8 +43,6 @@ Report findings; do not change code. - Architecture recommendations (use `architecture`) - Performance analysis (use `performance` or `analyse`) -______________________________________________________________________ - ## Phase 1: Project Overview ```bash @@ -63,8 +61,6 @@ Record: - **Tech stack** (language, framework, runtime) - **Project type** (API service, library, CLI, worker, monorepo) -______________________________________________________________________ - ## Phase 2: Directory Structure ```bash @@ -82,8 +78,6 @@ Identify: - CI/CD configuration (`.github/workflows/`, `.gitlab-ci.yml`, etc.) - Infrastructure code (`k8s/`, `terraform/`, `docker-compose.yml`) -______________________________________________________________________ - ## Phase 3: Dependencies & External Services ```bash @@ -105,8 +99,6 @@ grep -r -E 'postgres|mysql|redis|mongodb|kafka|rabbitmq|elasticsearch|dynamodb|s --exclude-dir=node_modules --exclude-dir=vendor . 2>/dev/null | grep -v test | head -20 ``` -______________________________________________________________________ - ## Phase 4: API & Service Contracts ```bash @@ -120,8 +112,6 @@ grep -r -n '@app.route\|router\.\|@Get\|@Post\|path=' \ --exclude-dir=node_modules . 2>/dev/null | head -30 ``` -______________________________________________________________________ - ## Phase 5: Test Infrastructure ```bash @@ -149,16 +139,14 @@ fi ```bash # Test count and coverage setup -find . -name '*.test.*' -o -name '*_test.*' -o -name '*spec.*' \ - --exclude-dir=node_modules 2>/dev/null | wc -l +find . \( -name '*.test.*' -o -name '*_test.*' -o -name '*spec.*' \) \ + -not -path '*/node_modules/*' -not -path '*/.venv/*' 2>/dev/null | wc -l # Coverage config cat .nycrc 2>/dev/null || cat vitest.config.* 2>/dev/null | head -20 || \ cat pytest.ini 2>/dev/null | head -20 || true ``` -______________________________________________________________________ - ## Phase 6: CI/CD Pipeline ```bash @@ -168,8 +156,6 @@ cat .github/workflows/*.yml 2>/dev/null | head -80 || true cat .gitlab-ci.yml 2>/dev/null | head -60 || true ``` -______________________________________________________________________ - ## Phase 7: Technical Debt & Health ```bash @@ -182,8 +168,6 @@ grep -r -n "TODO\|FIXME\|HACK\|XXX\|DEPRECATED\|BUG" \ cat TODOS.md 2>/dev/null | head -40 || true ``` -______________________________________________________________________ - ## Discovery Report Produce a structured summary: @@ -238,7 +222,5 @@ Stack: [language, framework, runtime versions] ``` -______________________________________________________________________ - - + diff --git a/.github/skills/gdpr/SKILL.md b/.github/skills/gdpr/SKILL.md new file mode 100644 index 0000000..387f14a --- /dev/null +++ b/.github/skills/gdpr/SKILL.md @@ -0,0 +1,248 @@ +--- +name: gdpr +description: 'GDPR-compliant engineering practices for APIs, data models, authentication flows, logging, retention, erasure, and infrastructure. Covers privacy by design, data minimization, storage limitation, lawful basis, user rights (access, erasure, portability), encryption, pseudonymization, and PR review checklists. Use when asked to "GDPR review", "is this GDPR-compliant?", "privacy by design", "data retention policy", "right to erasure", or "DPIA". Proactively suggest before any feature that handles personal data.' +license: 'MIT' +compatibility: 'Requires a skills-compatible agent with repository file access.' +metadata: + owner: vstack + maturity: stable +argument-hint: '[component or feature: data model | API | logging | retention | erasure | infra | PR review]' +user-invocable: true +disable-model-invocation: false +--- +## Skill Context + +This skill is part of **vstack** — a VS Code-native AI engineering workflow system. + +### AskUserQuestion Format + +When you need clarification, use this exact format — never invent or guess: + +> **Question:** [The specific question] +> **Options:** A) … | B) … | C) … +> **Default if no response:** [What you'll do] + +Never ask more than one question at a time without waiting for the answer. + +### Diagram Convention + +When producing hand-authored Markdown outputs, prefer Mermaid for flow, +interaction, lifecycle, state, topology, dependency, and decision diagrams when +the format is supported and improves clarity. Use ASCII as a fallback when +Mermaid is unsupported or would be less readable. Keep ASCII/text trees for +directory structures and other scan-friendly hierarchies. + +# gdpr — GDPR-Compliant Engineering + +Actionable GDPR reference for engineers, architects, and tech leads working with +personal data. Based on GDPR Articles 5, 25, 32, 33, 35 and CNIL developer +guidance. + +> **Golden Rule:** Collect less. Store less. Expose less. Retain less. +> Every byte of personal data you do not collect is a byte you cannot lose, +> cannot breach, and cannot be held liable for. + +## Out of scope + +- General security audit (use `security`) +- STRIDE threat modeling (use `threat-model`) +- Dependency vulnerability scanning (use `dependency`) + +## Glossary + +| Term | Meaning | +| -------- | ------------------------------------------------------------------------- | +| **RoPA** | Record of Processing Activities — maintained by the controller | +| **DPIA** | Data Protection Impact Assessment — required for high-risk processing | +| **DPA** | Data Processing Agreement — required with every sub-processor | +| **DSR** | Data Subject Request — access, erasure, portability, rectification | +| **DEK** | Data Encryption Key — used for column-level encryption | +| **KMS** | Key Management Service — e.g. AWS Secrets Manager, Azure Key Vault, Vault | + +## Step 1: Core Principles (Article 5) + +| Principle | Engineering obligation | +| ---------------------------------- | ------------------------------------------------------------------------------------------- | +| Lawfulness, fairness, transparency | Document legal basis for every processing activity in the RoPA | +| Purpose limitation | Data collected for purpose A **must not** be reused for purpose B without a new legal basis | +| Data minimization | Collect only fields with a documented business need | +| Accuracy | Provide update endpoints; propagate corrections to downstream stores | +| Storage limitation | Define TTL at schema design time — never after | +| Integrity & confidentiality | Encrypt at rest and in transit; restrict and audit access | +| Accountability | Maintain evidence of compliance; RoPA ready for DPA inspection at any time | + +## Step 2: Privacy by Design & by Default + +**MUST:** + +- Add `created_at`, `retention_expires_at` to every table holding personal data +- Default all optional data collection to **off** — users opt in, never opt out +- Conduct a **DPIA** before building high-risk processing (biometrics, health data, large-scale profiling, systematic monitoring) +- Update the **RoPA** with every new feature that introduces a processing activity +- Sign a **DPA** with every sub-processor before data flows to them + +**MUST NOT:** + +- Ship a new data collection feature without a documented legal basis +- Enable analytics, tracking, or telemetry by default without explicit consent +- Store personal data in a system not listed in the RoPA + +## Step 3: Data Minimization + +**MUST:** + +- Map every DTO/model field to a concrete business need; remove undocumented fields +- Use separate DTOs for create, read, and update operations +- Return only what the caller is authorized to see — use response projections +- Mask sensitive values at the edge: return `****1234` for card numbers, never the full value +- Exclude sensitive fields (DOB, national ID, health) from default list/search projections + +**MUST NOT:** + +- Log full request/response bodies if they may contain personal data +- Include personal data in URL path segments or query parameters (appears in CDN logs and browser history) +- Collect `date_of_birth`, national ID, or health data without an explicit legal basis + +## Step 4: Storage Limitation & Retention + +Every table holding personal data **must** have a defined retention period. + +| Data type | Max retention | +| ------------------------- | ---------------------------------------------- | +| Auth / audit logs | 12–24 months | +| Session / refresh tokens | 30–90 days | +| Email / notification logs | 6 months | +| Inactive user accounts | 12 months after last login → notify → delete | +| Payment records | As required by tax law (7–10 years), minimized | +| Analytics events | 13 months | + +**MUST:** + +- Enforce retention automatically via a scheduled job or TTL policy — never a manual process +- Anonymize or delete data when retention expires +- Add `retention_expires_at` column — compute at insert time +- Use soft-delete (`deleted_at`) with a scheduled hard-delete after the erasure request window (30 days) + +**MUST NOT:** + +- Retain personal data indefinitely "in case it becomes useful later" + +## Step 5: API Design + +**MUST:** + +- Never include personal data in URL paths or query parameters +- Authenticate all endpoints that return or accept personal data +- Extract acting user identity from the JWT — never from the request body +- Validate ownership on every resource: return 403 if `resource.owner_id != current_user_id` +- Use UUIDs or opaque identifiers — never sequential integers as public resource IDs +- Rate-limit sensitive endpoints (login, data export, password reset) + +**MUST NOT:** + +- Return stack traces, internal paths, or database errors in API responses +- Use `Access-Control-Allow-Origin: *` on authenticated APIs + +## Step 6: Logging + +**MUST:** + +- Anonymize IPs in application logs — mask last octet (IPv4) or last 80 bits (IPv6) +- Enforce log retention — purge automatically after the defined period +- Log events, not data: `"user {id} updated email"` not `"email changed from a@b.com"` + +**MUST NOT log:** + +- Passwords, tokens, session IDs, credentials, card numbers, national IDs, health data +- Full request/response bodies where PII may be present + +## Step 7: Encryption + +| Scope | Minimum standard | +| --------------------------------------------- | -------------------------------------------------- | +| Standard personal data | AES-256 disk/volume encryption | +| Sensitive data (health, financial, biometric) | AES-256 column-level + envelope encryption via KMS | +| In transit | TLS 1.2+ (prefer 1.3); HSTS enforced | +| Keys | HSM-backed KMS; rotate DEKs annually | + +**Password hashing:** Use **Argon2id** (recommended) or **bcrypt** (cost ≥ 12). +Never MD5, SHA-1, or SHA-256 for passwords. + +**MUST NOT:** Allow TLS 1.0/1.1, null cipher suites, or hardcoded encryption keys. + +## Step 8: Secrets Management + +- Store all secrets in a KMS: AWS Secrets Manager, Azure Key Vault, GCP Secret Manager, or HashiCorp Vault +- Use pre-commit hooks (`gitleaks`, `detect-secrets`) to prevent secret commits +- Rotate secrets on developer offboarding, annual schedule, or suspected compromise + +`.gitignore` must include: `.env`, `.env.*`, `*.pem`, `*.key`, `*.pfx`, `*.p12`, `secrets/` + +## Step 9: Anonymization & Pseudonymization + +- **Anonymization** = irreversible → falls outside GDPR scope; use for retained records after erasure +- **Pseudonymization** = reversible with a key → still personal data, but reduced risk +- When erasing a user, anonymize records that must be retained (financial, audit) rather than deleting them +- Store the pseudonymization key in the KMS — never in the same database as the pseudonymized data + +**MUST NOT** call data "anonymized" if re-identification is possible through linkage attacks. + +## Step 10: Testing with Fake Data + +**MUST NOT:** + +- Use production personal data in dev, staging, or CI environments +- Restore production DB backups to non-production without scrubbing PII first + +Use synthetic data generators: `Faker` (Python/JS/Ruby), `factory_boy` (Python). +Use `@example.com` for all test email addresses. + +## PR Review Checklist + +### Data model + +- [ ] Every new PII column has a documented purpose and retention period +- [ ] Sensitive fields (health, financial, national ID) use column-level encryption +- [ ] No sequential integer PKs as public-facing identifiers + +### API + +- [ ] No PII in URL paths or query parameters +- [ ] All endpoints returning personal data are authenticated +- [ ] Ownership checks present — users cannot access other users' resources +- [ ] Rate limiting applied to sensitive endpoints + +### Logging + +- [ ] No passwords, tokens, or credentials logged +- [ ] IPs anonymized (last octet masked) +- [ ] No full request/response bodies logged where PII may be present + +### Infrastructure + +- [ ] No public storage buckets or public-IP databases +- [ ] Encryption at rest enabled for new storage resources +- [ ] New geographic regions for data storage are EEA-compliant or covered by SCCs + +### Retention & erasure + +- [ ] Retention enforcement covers new data store or field +- [ ] Erasure pipeline updated to cover new data store + +### User rights & governance + +- [ ] Data export endpoint includes any new personal data field +- [ ] RoPA updated if a new processing activity is introduced +- [ ] New sub-processors have a signed DPA and a RoPA entry +- [ ] DPIA triggered if the change involves high-risk processing + +## References + +> GDPR is a legal instrument — always consult the authoritative text and current DPA guidance rather than summaries. + +- [GDPR full text (EUR-Lex)](https://eur-lex.europa.eu/eli/reg/2016/679) +- [CNIL developer guide (privacy by design)](https://www.cnil.fr/en/cnil-publishes-gdpr-guide-developers) +- [EDPB guidelines](https://www.edpb.europa.eu/our-work-tools/general-guidance/guidelines-recommendations-best-practices_en) + + + diff --git a/.github/skills/gh-issues/SKILL.md b/.github/skills/gh-issues/SKILL.md new file mode 100644 index 0000000..6b54f49 --- /dev/null +++ b/.github/skills/gh-issues/SKILL.md @@ -0,0 +1,229 @@ +--- +name: gh-issues +description: 'Create, update, and manage GitHub issues using the gh CLI. Covers bug reports, feature requests, tasks, labels, assignees, milestones, sub-issues, and issue workflows. Use when asked to "create an issue", "file a bug", "create a feature request", "update issue #N", "add a label", or "close an issue".' +license: 'MIT' +compatibility: 'Requires a skills-compatible agent with terminal command execution and GitHub CLI authentication (`gh auth status`).' +metadata: + owner: vstack + maturity: stable +argument-hint: '[what to create or which issue number to update]' +user-invocable: true +disable-model-invocation: false +--- +## Skill Context + +This skill is part of **vstack** — a VS Code-native AI engineering workflow system. + +### AskUserQuestion Format + +When you need clarification, use this exact format — never invent or guess: + +> **Question:** [The specific question] +> **Options:** A) … | B) … | C) … +> **Default if no response:** [What you'll do] + +Never ask more than one question at a time without waiting for the answer. + +### Diagram Convention + +When producing hand-authored Markdown outputs, prefer Mermaid for flow, +interaction, lifecycle, state, topology, dependency, and decision diagrams when +the format is supported and improves clarity. Use ASCII as a fallback when +Mermaid is unsupported or would be less readable. Keep ASCII/text trees for +directory structures and other scan-friendly hierarchies. + +# gh-issues — GitHub Issue Management + +Create, update, and manage GitHub issues using the `gh` CLI. + +## Out of scope + +- Pull requests (use `pr`) +- Release notes (use `release-notes`) +- Project boards — use `gh project` commands or GitHub UI directly + +## Step 0: Pre-flight + +```bash +# Verify gh CLI is authenticated +gh auth status 2>/dev/null || echo "ERROR: gh CLI not authenticated" + +# Identify the repository +gh repo view --json nameWithOwner --jq '.nameWithOwner' 2>/dev/null +``` + +## Step 1: Determine Action + +Classify the request: + +- **Create:** new bug report, feature request, or task +- **Update:** edit title, body, labels, assignees, milestone, or state +- **Query:** list, search, or view issues + +## Step 2: Query Existing Issues (when relevant) + +Before creating, check if a similar issue already exists: + +```bash +# List open issues with optional filter +gh issue list --state open --limit 20 + +# Search for similar issues +gh issue list --search "" --state all --limit 10 + +# View a specific issue +gh issue view +``` + +## Step 3: Create an Issue + +### Bug report + +```bash +gh issue create \ + --title "Short imperative description of the bug" \ + --body "## Description +What is broken and what impact does it have? + +## Steps to Reproduce +1. +2. +3. + +## Expected Behavior +What should happen. + +## Actual Behavior +What happens instead. + +## Environment +- Version/commit: +- OS/Platform: +- Relevant config:" \ + --label "bug" +``` + +### Feature request + +```bash +gh issue create \ + --title "Add " \ + --body "## Summary +One-paragraph description of the feature and its value. + +## Motivation +Why is this needed? Who benefits? + +## Proposed Solution +How it could be implemented at a high level. + +## Acceptance Criteria +- [ ] Criterion 1 +- [ ] Criterion 2" \ + --label "enhancement" +``` + +### Task / chore + +```bash +gh issue create \ + --title "Imperative description of the task" \ + --body "## Context +Why this task is needed. + +## Definition of Done +- [ ] Step 1 +- [ ] Step 2" \ + --label "task" +``` + +### With assignees and milestone + +```bash +gh issue create \ + --title "" \ + --body "<body>" \ + --assignee "<github-username>" \ + --milestone "<milestone-title>" +``` + +## Step 4: Update an Existing Issue + +```bash +# Edit title or body +gh issue edit <number> --title "<new-title>" +gh issue edit <number> --body "<new-body>" + +# Add or remove labels +gh issue edit <number> --add-label "bug" --remove-label "needs-triage" + +# Change assignees +gh issue edit <number> --add-assignee "<username>" + +# Set milestone +gh issue edit <number> --milestone "<milestone-title>" + +# Close or reopen +gh issue close <number> --comment "Resolved in <commit/PR>." +gh issue reopen <number> + +# Add a comment +gh issue comment <number> --body "Comment text." +``` + +## Step 5: Sub-issues (if hierarchy is needed) + +GitHub supports sub-issues via the REST API: + +```bash +# Create sub-issue and link to parent +PARENT=<parent-issue-number> +CHILD=$(gh issue create \ + --title "<sub-task title>" \ + --body "Sub-task for #$PARENT." \ + --json number --jq '.number') + +# Link child to parent via REST API +OWNER_REPO=$(gh repo view --json nameWithOwner --jq '.nameWithOwner') +gh api "repos/$OWNER_REPO/issues/$PARENT/sub_issues" \ + -X POST \ + -f sub_issue_id="$CHILD" +``` + +## Title guidelines + +- Use imperative mood: "Add dark mode", not "Dark mode addition" +- Be specific: "Login fails with SSO enabled" not "SSO broken" +- Keep under 72 characters +- Do not prefix with `[Bug]` or `[Feature]` — use labels instead + +## Standard labels + +| Label | Use for | +| ------------------ | ----------------------------------- | +| `bug` | Something is broken | +| `enhancement` | New feature or improvement | +| `documentation` | Docs-only change | +| `task` | Internal maintenance or chore | +| `good first issue` | Suitable for new contributors | +| `help wanted` | Extra attention or expertise needed | +| `wontfix` | Will not be addressed | +| `duplicate` | Already tracked elsewhere | + +## Output + +Report the URL after creation or update: + +```text +https://github.com/<org>/<repo>/issues/<number> +``` + +## References + +> Always use the official documentation for the exact version in use — options and syntax change between releases. + +- [gh issue — GitHub CLI manual](https://cli.github.com/manual/gh_issue) +- [GitHub Issues documentation](https://docs.github.com/en/issues) + +<!-- AUTO-GENERATED — maintained by vstack, do not edit directly --> +<!-- VSTACK-META: {"artifact_name":"gh-issues","artifact_type":"skill","artifact_version":"20260502025","generator":"vstack","vstack_version":"0.0.0.post3.dev0+df3fe6e"} --> diff --git a/.github/skills/gh-release/SKILL.md b/.github/skills/gh-release/SKILL.md new file mode 100644 index 0000000..11960e8 --- /dev/null +++ b/.github/skills/gh-release/SKILL.md @@ -0,0 +1,216 @@ +--- +name: gh-release +description: 'Create or update a GitHub Release using the gh CLI from prepared release artifacts. Handles immutable tag checks, draft/publish/prerelease flow, release notes source selection, optional asset upload, and release metadata verification before publication. Use when asked to "create a GitHub release", "publish a release", or "draft release with gh".' +license: 'MIT' +compatibility: 'Requires a skills-compatible agent with repository file access, terminal command execution, and GitHub CLI authentication (`gh auth status`).' +metadata: + owner: vstack + maturity: stable +argument-hint: '[version/tag and release notes source]' +user-invocable: true +disable-model-invocation: false +--- +## Skill Context + +This skill is part of **vstack** — a VS Code-native AI engineering workflow system. + +### AskUserQuestion Format + +When you need clarification, use this exact format — never invent or guess: + +> **Question:** [The specific question] +> **Options:** A) … | B) … | C) … +> **Default if no response:** [What you'll do] + +Never ask more than one question at a time without waiting for the answer. + +### Diagram Convention + +When producing hand-authored Markdown outputs, prefer Mermaid for flow, +interaction, lifecycle, state, topology, dependency, and decision diagrams when +the format is supported and improves clarity. Use ASCII as a fallback when +Mermaid is unsupported or would be less readable. Keep ASCII/text trees for +directory structures and other scan-friendly hierarchies. + +# gh-release — Create or Update GitHub Release via gh CLI + +Create or update a GitHub Release from prepared release artifacts using `gh`. + +## Out of scope + +- Writing release notes content from scratch (use `release-notes`) +- Opening pull requests (use `pr`) +- Deploying to runtime environments + +## Deliverable + +- A draft or published GitHub Release for the requested tag/version + +## Step 1: Preconditions + +Validate repository state and CLI auth: + +```bash +gh auth status +git remote -v +git status --short +``` + +If `gh auth status` fails: stop and request authenticated `gh` session. + +## Step 2: Determine release inputs + +Capture required inputs: + +```text +Tag/version: [e.g. v2.2.0] +Target commit/branch: [default: current HEAD] +Release title: [e.g. v2.2.0] +Mode: [draft | publish] +Release kind: [stable | prerelease] +Latest flag: [auto | mark-latest | do-not-mark-latest] +Notes source: [docs/releases/{date}.md | generated] +Artifacts: [optional files to attach] +``` + +Validate that notes source exists when a file path is provided. + +## Step 3: Validate tag strategy + +Check whether the tag already exists: + +```bash +TAG="<tag>" +git rev-parse "$TAG" >/dev/null 2>&1 && echo "tag-exists" || echo "tag-missing" +``` + +Rules: + +- If tag exists and points to unexpected commit: stop and escalate. +- If tag is missing, create annotated tag only when explicitly requested. +- Never retarget an existing release tag to a different commit. + +Compare target commit with tag commit when tag exists: + +```bash +TARGET_SHA=$(git rev-parse "<target>") +TAG_SHA=$(git rev-list -n 1 "$TAG") +if [ "$TARGET_SHA" != "$TAG_SHA" ]; then + echo "ERROR: existing tag points to different commit" + exit 1 +fi +``` + +Tag creation example: + +```bash +git tag -a "$TAG" -m "Release $TAG" +git push origin "$TAG" +``` + +## Step 4: Create or update release + +Preferred flow with notes file: + +```bash +gh release create "$TAG" \ + --title "<title>" \ + --notes-file "<notes-file>" \ + --target "<target>" \ + --draft +``` + +Publish directly (if requested): + +```bash +gh release create "$TAG" \ + --title "<title>" \ + --notes-file "<notes-file>" \ + --target "<target>" +``` + +Pre-release mode: + +```bash +gh release create "$TAG" \ + --title "<title>" \ + --notes-file "<notes-file>" \ + --target "<target>" \ + --prerelease +``` + +If notes file is unavailable and generated notes are approved: + +```bash +gh release create "$TAG" \ + --title "<title>" \ + --generate-notes \ + --target "<target>" \ + --draft +``` + +If the release already exists, update it: + +```bash +gh release edit "$TAG" \ + --title "<title>" \ + --notes-file "<notes-file>" +``` + +Optional latest behavior: + +- `mark-latest`: include `--latest` +- `do-not-mark-latest`: include `--latest=false` + +Optional artifact upload: + +```bash +gh release upload "$TAG" <artifact-path> --clobber +``` + +When uploading binaries, attach checksums when available: + +```bash +sha256sum <artifact-path> > <artifact-path>.sha256 +gh release upload "$TAG" <artifact-path>.sha256 --clobber +``` + +## Step 5: Verify release state + +Confirm final release metadata: + +```bash +gh release view "$TAG" --json name,tagName,isDraft,isPrerelease,isLatest,url +``` + +Verify: + +- tag is correct +- title is correct +- draft/published mode matches request +- prerelease/latest flags match request +- release URL is available + +## Step 6: Report outcome + +Report a concise summary: + +```text +GitHub Release ready: +- Tag: <tag> +- Title: <title> +- Mode: <draft|published> +- URL: <release-url> +``` + +If blocked, report exact blocker and required user action. + +## References + +> Always use the official documentation for the gh CLI version in use — flags and subcommands are added and changed between releases. + +- [gh release — GitHub CLI manual](https://cli.github.com/manual/gh_release) +- [GitHub Releases documentation](https://docs.github.com/en/repositories/releasing-projects-on-github/about-releases) + +<!-- AUTO-GENERATED — maintained by vstack, do not edit directly --> +<!-- VSTACK-META: {"artifact_name":"gh-release","artifact_type":"skill","artifact_version":"20260502023","generator":"vstack","vstack_version":"0.0.0.post3.dev0+df3fe6e"} --> diff --git a/.github/skills/guardrails/SKILL.md b/.github/skills/guardrails/SKILL.md index 643e1eb..3a85808 100644 --- a/.github/skills/guardrails/SKILL.md +++ b/.github/skills/guardrails/SKILL.md @@ -40,8 +40,6 @@ Activate careful mode for this session. Two behaviors are now enabled. - Code review or security audit (use `code-review` or `security`) -______________________________________________________________________ - ## Behavior 1: Careful Mode (always active after invoking this skill) **Before executing any of the following commands, get explicit confirmation:** @@ -68,13 +66,9 @@ ______________________________________________________________________ 1. Only proceed if the user says yes. 1. Never use workarounds to avoid this confirmation. -______________________________________________________________________ - ## How to Deactivate Explicitly ask to "disable guardrails". -______________________________________________________________________ - <!-- AUTO-GENERATED — maintained by vstack, do not edit directly --> -<!-- VSTACK-META: {"artifact_name":"guardrails","artifact_type":"skill","artifact_version":"1.0.2","generator":"vstack","vstack_version":"1.3.0"} --> +<!-- VSTACK-META: {"artifact_name":"guardrails","artifact_type":"skill","artifact_version":"20260421016","generator":"vstack","vstack_version":"0.0.0.post3.dev0+df3fe6e"} --> diff --git a/.github/skills/helm/SKILL.md b/.github/skills/helm/SKILL.md new file mode 100644 index 0000000..acea595 --- /dev/null +++ b/.github/skills/helm/SKILL.md @@ -0,0 +1,142 @@ +--- +name: helm +description: 'Write, review, and operate Helm charts and release lifecycles. Covers chart structure, values layering, lint/template validation, install/upgrade/rollback, dependency handling, and release troubleshooting. Use when asked to "create a Helm chart", "review Helm values", "upgrade Helm release", or "debug Helm deployment".' +license: 'MIT' +compatibility: 'Requires a skills-compatible agent with repository file access. Requires Helm CLI and target cluster access for live release operations.' +metadata: + owner: vstack + maturity: stable +argument-hint: '[chart path, release name, namespace, and scope: chart review | install | upgrade | rollback]' +user-invocable: true +disable-model-invocation: false +--- +## Skill Context + +This skill is part of **vstack** — a VS Code-native AI engineering workflow system. + +### AskUserQuestion Format + +When you need clarification, use this exact format — never invent or guess: + +> **Question:** [The specific question] +> **Options:** A) … | B) … | C) … +> **Default if no response:** [What you'll do] + +Never ask more than one question at a time without waiting for the answer. + +### Diagram Convention + +When producing hand-authored Markdown outputs, prefer Mermaid for flow, +interaction, lifecycle, state, topology, dependency, and decision diagrams when +the format is supported and improves clarity. Use ASCII as a fallback when +Mermaid is unsupported or would be less readable. Keep ASCII/text trees for +directory structures and other scan-friendly hierarchies. + +# helm - Helm Chart and Release Workflows + +Write, review, and operate Helm charts and release lifecycles. + +## Out of scope + +- Raw Kubernetes manifest-only workflows (use `k8s`) +- Rancher/Fleet governance workflows (use `rancher`) + +## Step 0: Detect Context + +```bash +helm version 2>/dev/null || echo "helm not installed" + +# Detect charts +find . -name Chart.yaml -o -path "*/charts/*" | head -40 +``` + +## Step 1: Chart Structure Review + +Expected chart layout: + +- `Chart.yaml` for metadata and dependencies +- `values.yaml` for defaults +- `templates/` for rendered resources +- `templates/_helpers.tpl` for naming/labels helpers + +```bash +helm show chart <chart-path> +helm show values <chart-path> +``` + +## Step 2: Static Validation Before Deploy + +```bash +# Lint chart and values +helm lint <chart-path> -f values.yaml + +# Render to inspect final manifests +helm template <release> <chart-path> -n <namespace> -f values.yaml > rendered.yaml + +# Optional Kubernetes dry-run check +kubectl apply --dry-run=server -f rendered.yaml +``` + +Validation checklist: + +- Workload resources define `requests`/`limits` +- Probes exist for long-running services +- Service selectors match deployment labels +- Secrets are referenced, not hardcoded in values + +## Step 3: Install and Upgrade Safely + +```bash +# Install +helm install <release> <chart-path> -n <namespace> --create-namespace -f values.yaml + +# Upgrade with safety flags +helm upgrade <release> <chart-path> -n <namespace> -f values.yaml \ + --atomic --timeout 10m --history-max 10 + +# Check release state +helm list -n <namespace> +helm status <release> -n <namespace> +``` + +Use environment-specific values files (`values-dev.yaml`, `values-prod.yaml`) and keep overrides minimal. + +## Step 4: Rollback and Incident Recovery + +```bash +helm history <release> -n <namespace> +helm rollback <release> <revision> -n <namespace> +``` + +Rollback policy: + +- Identify the last known healthy revision +- Roll back first, then investigate forward fix +- Capture failing diff for follow-up hardening + +## Step 5: Dependencies and Supply Chain + +```bash +# Resolve chart dependencies +helm dependency update <chart-path> + +# Inspect rendered manifests for dependency side effects +helm template <release> <chart-path> -f values.yaml | head -80 +``` + +Practices: + +- Pin dependency versions in `Chart.yaml` +- Review transitive chart defaults before promotion +- Avoid unverified third-party repositories in production + +## References + +> Always use the official documentation for the exact Helm and Kubernetes versions in use - chart schema, flags, and behavior evolve between releases. + +- [Helm documentation](https://helm.sh/docs/) +- [Helm command reference](https://helm.sh/docs/helm/) +- [Chart best practices](https://helm.sh/docs/chart_best_practices/) + +<!-- AUTO-GENERATED — maintained by vstack, do not edit directly --> +<!-- VSTACK-META: {"artifact_name":"helm","artifact_type":"skill","artifact_version":"20260502037","generator":"vstack","vstack_version":"0.0.0.post3.dev0+df3fe6e"} --> diff --git a/.github/skills/incident/SKILL.md b/.github/skills/incident/SKILL.md index 32e1848..202c5f2 100644 --- a/.github/skills/incident/SKILL.md +++ b/.github/skills/incident/SKILL.md @@ -47,8 +47,6 @@ document. The goal is learning and prevention — not blame. **Golden rule: Incidents are system failures, not human failures. Every finding must be framed as a system improvement opportunity, never as individual blame.** -______________________________________________________________________ - ## Step 0: Gather Incident Context Before analysis, collect all available evidence: @@ -86,8 +84,6 @@ Services: [list of affected services] Impact: [user-facing description] ``` -______________________________________________________________________ - ## Step 1: Reconstruct the Timeline Build a precise, chronological timeline of events. Include: @@ -113,8 +109,6 @@ Key markers: Total duration: N hours N minutes ``` -______________________________________________________________________ - ## Step 2: Identify Contributing Factors List ALL factors that contributed to the incident — not just the "trigger". @@ -151,8 +145,6 @@ Categorize contributing factors: | External | [e.g. upstream dependency failure, cloud provider issue] | | Knowledge | [e.g. undocumented behaviour, tribal knowledge gap] | -______________________________________________________________________ - ## Step 3: Determine Root Cause The root cause is the deepest systemic condition that, if addressed, would @@ -176,8 +168,6 @@ Class of incident: Capacity / traffic | Data corruption | Security breach | Other] ``` -______________________________________________________________________ - ## Step 4: Assess Impact Quantify the impact precisely: @@ -201,8 +191,6 @@ Detection gap: Why not faster: [threshold too high | missing alert | other] ``` -______________________________________________________________________ - ## Step 5: Write Action Items Action items must be: @@ -229,8 +217,6 @@ Process (improve how we handle incidents): [ ] [specific action] — owner: [name/team] — due: [date/sprint] ``` -______________________________________________________________________ - ## Step 6: Produce the Post-Mortem Document Write the post-mortem to `docs/postmortems/YYYY-MM-DD-<slug>.md`: @@ -304,8 +290,6 @@ Written for a non-technical audience.] What does this incident teach us about our system, processes, or culture?] ``` -______________________________________________________________________ - ## Output ```text @@ -325,4 +309,4 @@ Status: [Draft — ready for team review] ``` <!-- AUTO-GENERATED — maintained by vstack, do not edit directly --> -<!-- VSTACK-META: {"artifact_name":"incident","artifact_type":"skill","artifact_version":"1.0.1","generator":"vstack","vstack_version":"1.3.0"} --> +<!-- VSTACK-META: {"artifact_name":"incident","artifact_type":"skill","artifact_version":"20260421017","generator":"vstack","vstack_version":"0.0.0.post3.dev0+df3fe6e"} --> diff --git a/.github/skills/inspect/SKILL.md b/.github/skills/inspect/SKILL.md index 84c233d..4c2715d 100644 --- a/.github/skills/inspect/SKILL.md +++ b/.github/skills/inspect/SKILL.md @@ -62,8 +62,6 @@ Use `verify` when a fix loop is required. - Optional WIP area for complex/uncertain efforts: `docs/delta/{id}/TESTING_DELTA.md` - Before merge: consolidate any blocking findings and final verdict into baseline reports. -______________________________________________________________________ - ## Step 0: Scope ```text @@ -71,8 +69,6 @@ Report only. No edits. No commits. If critical issues are found, recommend `verify`. ``` -______________________________________________________________________ - ## Step 1: Baseline Checks ```bash @@ -106,8 +102,6 @@ else fi ``` -______________________________________________________________________ - ## Step 2: Extended Checks (when present) ```bash @@ -135,8 +129,6 @@ Confirm for changed paths: - Trace propagation exists across service boundaries where applicable. - Alerts/runbooks exist for high-severity failure modes. -______________________________________________________________________ - ## Step 3: Report ```text @@ -162,7 +154,5 @@ ______________________________________________________________________ [SHIP-READY | USE VERIFY FIX LOOP | NEEDS ARCH/DESIGN REVIEW] ``` -______________________________________________________________________ - <!-- AUTO-GENERATED — maintained by vstack, do not edit directly --> -<!-- VSTACK-META: {"artifact_name":"inspect","artifact_type":"skill","artifact_version":"1.0.2","generator":"vstack","vstack_version":"1.3.0"} --> +<!-- VSTACK-META: {"artifact_name":"inspect","artifact_type":"skill","artifact_version":"20260421018","generator":"vstack","vstack_version":"0.0.0.post3.dev0+df3fe6e"} --> diff --git a/.github/skills/k8s/SKILL.md b/.github/skills/k8s/SKILL.md new file mode 100644 index 0000000..7375f27 --- /dev/null +++ b/.github/skills/k8s/SKILL.md @@ -0,0 +1,146 @@ +--- +name: k8s +description: 'Write, review, and troubleshoot Kubernetes manifests and operational workflows. Covers workload resources, service exposure, rollout safety, health probes, RBAC, namespace isolation, and kubectl-based diagnostics. Use when asked to "deploy to Kubernetes", "review Kubernetes manifests", "debug Kubernetes rollout", "harden Kubernetes config", or "operate a workload on a cluster".' +license: 'MIT' +compatibility: 'Requires a skills-compatible agent with repository file access. Requires kubectl access to a target cluster for live operations.' +metadata: + owner: vstack + maturity: stable +argument-hint: '[cluster/context, namespace, and scope: manifest review | deploy | rollout debug | hardening]' +user-invocable: true +disable-model-invocation: false +--- +## Skill Context + +This skill is part of **vstack** — a VS Code-native AI engineering workflow system. + +### AskUserQuestion Format + +When you need clarification, use this exact format — never invent or guess: + +> **Question:** [The specific question] +> **Options:** A) … | B) … | C) … +> **Default if no response:** [What you'll do] + +Never ask more than one question at a time without waiting for the answer. + +### Diagram Convention + +When producing hand-authored Markdown outputs, prefer Mermaid for flow, +interaction, lifecycle, state, topology, dependency, and decision diagrams when +the format is supported and improves clarity. Use ASCII as a fallback when +Mermaid is unsupported or would be less readable. Keep ASCII/text trees for +directory structures and other scan-friendly hierarchies. + +# k8s - Kubernetes Workflows + +Write, review, and troubleshoot Kubernetes manifests and cluster operations. + +## Out of scope + +- Helm chart authoring and release lifecycle (use `helm`) +- Rancher/Fleet multi-cluster governance (use `rancher`) + +## Step 0: Detect Context + +```bash +kubectl version --client 2>/dev/null || echo "kubectl not installed" +kubectl config current-context 2>/dev/null || echo "no current context" + +# Find Kubernetes manifests in common locations +find . -type f \( -name "*.yaml" -o -name "*.yml" \) \ + | rg '/(k8s|kubernetes|manifests)/|deployment|service|ingress|statefulset' -N || true +``` + +## Step 1: Validate Manifests + +```bash +# API/schema and field validation +kubectl apply --dry-run=client -f k8s/ + +# Optional: server-side admission and API validation +kubectl apply --dry-run=server -f k8s/ +``` + +Validation checklist: + +- Every workload sets CPU/memory `requests` and `limits` +- Liveness and readiness probes are present and realistic +- Image tags are explicit (avoid mutable `:latest`) +- Namespace and labels are consistent across resources +- RBAC permissions follow least privilege + +## Step 2: Safe Deploy and Rollout + +```bash +# Apply manifests to a namespace +kubectl apply -n <namespace> -f k8s/ + +# Track rollout status +kubectl rollout status deploy/<name> -n <namespace> + +# View current replica health +kubectl get deploy,po -n <namespace> +``` + +For updates: + +- Prefer rolling updates over delete/recreate +- Set deployment strategy (`maxUnavailable`, `maxSurge`) explicitly +- Keep rollback path ready (`kubectl rollout undo`) + +## Step 3: Service Exposure and Networking + +```bash +kubectl get svc,ing -n <namespace> +kubectl describe svc <service-name> -n <namespace> +kubectl describe ing <ingress-name> -n <namespace> +``` + +Checks: + +- Service selectors match pod labels +- Ingress host/path routes are deterministic +- TLS secrets and ingress class are configured where required +- NetworkPolicies default-deny inbound where possible + +## Step 4: Troubleshooting Workflow + +```bash +# Pod state and events +kubectl get po -n <namespace> +kubectl describe po <pod-name> -n <namespace> +kubectl get events -n <namespace> --sort-by=.lastTimestamp | tail -30 + +# Container logs +kubectl logs <pod-name> -n <namespace> --all-containers --tail=200 + +# Exec for runtime inspection +kubectl exec -it <pod-name> -n <namespace> -- /bin/sh +``` + +Common failure classes: + +- `ImagePullBackOff`: image name/tag/registry credentials +- `CrashLoopBackOff`: startup command/config/secrets mismatch +- `Pending`: resource requests exceed cluster capacity +- Probe flaps: probe timing too strict for startup behavior + +## Step 5: Security and Reliability Hardening + +- Run containers as non-root where possible +- Set `readOnlyRootFilesystem: true` when feasible +- Drop unnecessary Linux capabilities +- Avoid broad `ClusterRoleBinding` grants +- Use PodDisruptionBudgets for critical workloads + +## References + +> Always use the official documentation for the exact Kubernetes version in use - API versions and defaults change between releases. + +- [Kubernetes documentation](https://kubernetes.io/docs/) +- [kubectl reference](https://kubernetes.io/docs/reference/kubectl/) +- [Kubernetes API reference](https://kubernetes.io/docs/reference/kubernetes-api/) + +<!-- AUTO-GENERATED — maintained by vstack, do not edit directly --> +<!-- VSTACK-META: {"artifact_name":"k8s","artifact_type":"skill","artifact_version":"20260502036","generator":"vstack","vstack_version":"0.0.0.post3.dev0+df3fe6e"} --> diff --git a/.github/skills/migrate/SKILL.md b/.github/skills/migrate/SKILL.md index 772ea60..21f26b6 100644 --- a/.github/skills/migrate/SKILL.md +++ b/.github/skills/migrate/SKILL.md @@ -56,8 +56,6 @@ deployability. No migration ships without a rollback plan. **Golden rule: Every migration must be reversible or explicitly documented as irreversible with a data-recovery plan.** -______________________________________________________________________ - ## Step 0: Understand the Change Before reviewing or writing anything, gather context: @@ -73,7 +71,7 @@ Before reviewing or writing anything, gather context: ```bash # Find existing migration files find . -type f \( -name '*.sql' -o -name '*migration*' -o -name '*migrate*' \) \ - --exclude-dir=.venv --exclude-dir=node_modules --exclude-dir=dist --exclude-dir=build \ + -not \( -path '*/.venv/*' -o -path '*/node_modules/*' -o -path '*/dist/*' -o -path '*/build/*' \) \ 2>/dev/null | sort | tail -20 # Show migration files changed in this branch @@ -95,8 +93,6 @@ Deployment: [rolling | blue-green | big-bang | maintenance window] Direction: [new migration | review existing | both] ``` -______________________________________________________________________ - ## Step 1: Classify the Migration Classify every DDL operation by risk level: @@ -125,8 +121,6 @@ Operations: Overall risk: [Low | Medium | High | Destructive] ``` -______________________________________________________________________ - ## Step 2: Zero-Downtime Analysis **Rolling deployments require that the schema be compatible with BOTH the old and @@ -158,8 +152,6 @@ If the migration violates zero-downtime, flag it: Fix: [expand/contract steps or maintenance window required] ``` -______________________________________________________________________ - ## Step 3: Rollback Plan Every migration must have a defined rollback: @@ -182,8 +174,6 @@ For destructive operations (DROP, TRUNCATE), rollback is not possible — docume Recovery: Restore from snapshot (RTO: [estimate]) ``` -______________________________________________________________________ - ## Step 4: Data Integrity Check: @@ -206,8 +196,6 @@ SELECT column, COUNT(*) FROM table GROUP BY column HAVING COUNT(*) > 1; SELECT COUNT(*) FROM table WHERE NOT (constraint_expression); ``` -______________________________________________________________________ - ## Step 5: Index Safety **Never create an index without `CONCURRENTLY` on a live table.** @@ -233,8 +221,6 @@ Check: - [ ] No redundant indexes (subset of existing composite index) - [ ] Partial indexes considered for filtered queries -______________________________________________________________________ - ## Step 6: Performance on Large Tables For tables with > 100k rows: @@ -276,8 +262,6 @@ BEGIN END $$; ``` -______________________________________________________________________ - ## Step 7: Testing ```bash @@ -299,8 +283,6 @@ Check: - [ ] Application tests pass with the new schema - [ ] No model/schema drift detected -______________________________________________________________________ - ## Output Produce a structured migration review: @@ -337,4 +319,4 @@ Pre-deploy checklist: ``` <!-- AUTO-GENERATED — maintained by vstack, do not edit directly --> -<!-- VSTACK-META: {"artifact_name":"migrate","artifact_type":"skill","artifact_version":"1.0.1","generator":"vstack","vstack_version":"1.3.0"} --> +<!-- VSTACK-META: {"artifact_name":"migrate","artifact_type":"skill","artifact_version":"20260421019","generator":"vstack","vstack_version":"0.0.0.post3.dev0+df3fe6e"} --> diff --git a/.github/skills/onboard/SKILL.md b/.github/skills/onboard/SKILL.md index 9afc139..78d1562 100644 --- a/.github/skills/onboard/SKILL.md +++ b/.github/skills/onboard/SKILL.md @@ -47,8 +47,6 @@ clone to first PR with zero tribal knowledge required. **Golden rule: If a new contributor needs to ask a question that isn't answered by the docs, that is a documentation gap — not a knowledge problem.** -______________________________________________________________________ - ## Step 0: Audit Existing Documentation ```bash @@ -76,8 +74,6 @@ Tech stack: [Python | Node | Go | other] Build tool: [Poetry | npm | make | other] ``` -______________________________________________________________________ - ## Step 1: Understand the Project Read the codebase to extract onboarding-relevant facts: @@ -102,8 +98,6 @@ cat .node-version 2>/dev/null cat .github/workflows/*.yml 2>/dev/null | grep -E 'run:|uses:' | head -30 ``` -______________________________________________________________________ - ## Step 2: Verify the Setup Steps Work Before documenting setup steps, verify they actually work: @@ -126,8 +120,6 @@ For each setup step, confirm: - [ ] Environment variables are documented (use `.env.example` if present) - [ ] The setup completes in < 5 minutes on a fresh machine -______________________________________________________________________ - ## Step 3: Extract Test Commands ```bash @@ -147,8 +139,6 @@ Type check only: [command] Single test: [command pattern] ``` -______________________________________________________________________ - ## Step 4: Identify "Good First Issues" ```bash @@ -162,14 +152,10 @@ grep -r -n "TODO\|FIXME\|HACK\|good.first" \ # (manual step — list any open "good first issue" labels) ``` -______________________________________________________________________ - ## Step 5: Write the Onboarding Guide Produce or update `CONTRIBUTING.md` with the following sections: -______________________________________________________________________ - ````markdown # Contributing to [Project Name] @@ -273,10 +259,6 @@ Link to docs/architecture/architecture.md for details.\] ```` -______________________________________________________________________ - -______________________________________________________________________ - ## Step 6: Supplement README (if needed) If README lacks a dev setup section, add a minimal one linking to CONTRIBUTING.md: @@ -295,8 +277,6 @@ Quick start: ```` -______________________________________________________________________ - ## Output ```text @@ -321,4 +301,4 @@ Gaps remaining (if any): ``` <!-- AUTO-GENERATED — maintained by vstack, do not edit directly --> -<!-- VSTACK-META: {"artifact_name":"onboard","artifact_type":"skill","artifact_version":"1.0.1","generator":"vstack","vstack_version":"1.3.0"} --> +<!-- VSTACK-META: {"artifact_name":"onboard","artifact_type":"skill","artifact_version":"20260421020","generator":"vstack","vstack_version":"0.0.0.post3.dev0+df3fe6e"} --> diff --git a/.github/skills/openapi/SKILL.md b/.github/skills/openapi/SKILL.md index 6361a98..976d3ee 100644 --- a/.github/skills/openapi/SKILL.md +++ b/.github/skills/openapi/SKILL.md @@ -47,8 +47,6 @@ be precise, complete, and implementable without ambiguity. **Golden rule: The spec is the source of truth. Code must conform to the spec, not the other way around.** -______________________________________________________________________ - ## Step 0: Understand the Task > **Question:** What needs to be done? @@ -71,8 +69,6 @@ find . -name 'openapi*.yaml' -o -name 'openapi*.json' \ [ -f openapi.yaml ] && npx swagger-cli validate openapi.yaml 2>/dev/null || true ``` -______________________________________________________________________ - ## Part 1: Spec Structure Every OpenAPI 3.1 spec must have: @@ -116,8 +112,6 @@ Check: - [ ] Tags defined at root level and used consistently on operations - [ ] `components` section exists for reusable schemas -______________________________________________________________________ - ## Part 2: Resource & Path Design ### Naming conventions @@ -149,8 +143,6 @@ Check each path: - [ ] Every operation has a unique `operationId` (camelCase, e.g. `listUsers`, `createOrder`) - [ ] Every operation has a `summary` (short title, ≤ 80 chars) and `tags` -______________________________________________________________________ - ## Part 3: Status Codes Use exactly these status codes — no others unless justified: @@ -177,8 +169,6 @@ Check: - [ ] `401` and `403` are distinct and documented - [ ] `500` is documented but never includes stack traces -______________________________________________________________________ - ## Part 4: Error Response Schema Every error response must use a consistent schema: @@ -224,8 +214,6 @@ Check: - [ ] `request_id` for correlation is present - [ ] Field-level errors included for `400`/`422` -______________________________________________________________________ - ## Part 5: Pagination Standard cursor-based pagination (preferred for large datasets): @@ -278,8 +266,6 @@ Check: - [ ] Response includes `has_more` and `next_cursor` - [ ] `total` is optional (expensive query — only include if needed) -______________________________________________________________________ - ## Part 6: Schema Quality For each schema in `components/schemas`: @@ -322,8 +308,6 @@ Check: - [ ] No `type: object` without properties (use `additionalProperties` explicitly) - [ ] No circular `$ref` without a nullable break -______________________________________________________________________ - ## Part 7: Security Schemes ```yaml @@ -359,8 +343,6 @@ Check: - [ ] OAuth2 scopes are defined if using OAuth - [ ] No API keys in query parameters (use headers) -______________________________________________________________________ - ## Part 8: Versioning URI versioning is the recommended approach: @@ -385,8 +367,6 @@ Check: description: "Deprecated. Use /v2/users/{userId} instead." ``` -______________________________________________________________________ - ## Output Produce a review report or the corrected spec: @@ -413,5 +393,13 @@ Summary: [N critical, N warnings, N info] **If writing or correcting the spec:** produce the complete corrected YAML, using `$ref` for all reusable schemas, and validate it passes linting. +## References + +> Always use the official specification for the OpenAPI version in use — schema keywords, security scheme types, and JSON Schema dialect support differ between 3.0 and 3.1. + +- [OpenAPI Specification 3.1](https://spec.openapis.org/oas/latest.html) +- [JSON Schema (2020-12)](https://json-schema.org/specification) +- [Redocly CLI (linting)](https://redocly.com/docs/cli/) + <!-- AUTO-GENERATED — maintained by vstack, do not edit directly --> -<!-- VSTACK-META: {"artifact_name":"openapi","artifact_type":"skill","artifact_version":"1.0.1","generator":"vstack","vstack_version":"1.3.0"} --> +<!-- VSTACK-META: {"artifact_name":"openapi","artifact_type":"skill","artifact_version":"20260421021","generator":"vstack","vstack_version":"0.0.0.post3.dev0+df3fe6e"} --> diff --git a/.github/skills/performance/SKILL.md b/.github/skills/performance/SKILL.md index 4f060d3..c115e41 100644 --- a/.github/skills/performance/SKILL.md +++ b/.github/skills/performance/SKILL.md @@ -60,8 +60,6 @@ optimizations. Measure first; never optimize without evidence. - Optional WIP area for complex/uncertain efforts: `docs/delta/{id}/PERFORMANCE_DELTA.md` - Before merge: consolidate thresholds, measurements, and recommendations into the baseline performance report. -______________________________________________________________________ - ## Setup **Parse the user's request:** @@ -72,8 +70,6 @@ ______________________________________________________________________ | Mode | Comparison (vs base branch) | `--baseline`, `--profile`, `--load-test` | | Threshold | 5% regression | `--threshold 0.10` (10%) | -______________________________________________________________________ - ## Phase 1: Establish Baseline If on a feature branch, record performance metrics before and after the change: @@ -123,8 +119,6 @@ fi [ -f Cargo.toml ] && cargo bench 2>/dev/null || true ``` -______________________________________________________________________ - ## Phase 2: Comparison vs Base Branch ```bash @@ -150,8 +144,6 @@ Compare results: **Regression threshold:** Flag if any metric degrades by more than 5% (or configured threshold). -______________________________________________________________________ - ## Phase 3: Load Testing (if applicable) ```bash @@ -175,8 +167,6 @@ hey -n 1000 -c 50 "${SERVICE_URL}/health" 2>/dev/null || true wrk -t4 -c100 -d30s "${SERVICE_URL}/health" 2>/dev/null || true ``` -______________________________________________________________________ - ## Phase 4: Profiling (if regression found) If a regression is detected, profile to identify the bottleneck: @@ -205,8 +195,6 @@ Common bottleneck categories: - **Sync where async:** Blocking I/O on hot path - **Regex compilation:** Regex compiled inside hot loop -______________________________________________________________________ - ## Phase 5: Optimization Loop For each bottleneck identified: @@ -225,8 +213,6 @@ For each bottleneck identified: - Async I/O > sync I/O for I/O-bound work. - Batch > N individual calls. -______________________________________________________________________ - ## Performance Report ```text @@ -255,7 +241,5 @@ ______________________________________________________________________ [NO REGRESSION / REGRESSION FIXED / REGRESSION NEEDS ATTENTION] ``` -______________________________________________________________________ - <!-- AUTO-GENERATED — maintained by vstack, do not edit directly --> -<!-- VSTACK-META: {"artifact_name":"performance","artifact_type":"skill","artifact_version":"1.0.2","generator":"vstack","vstack_version":"1.3.0"} --> +<!-- VSTACK-META: {"artifact_name":"performance","artifact_type":"skill","artifact_version":"20260421022","generator":"vstack","vstack_version":"0.0.0.post3.dev0+df3fe6e"} --> diff --git a/.github/skills/pr/SKILL.md b/.github/skills/pr/SKILL.md index 28f7012..23c4910 100644 --- a/.github/skills/pr/SKILL.md +++ b/.github/skills/pr/SKILL.md @@ -34,7 +34,7 @@ directory structures and other scan-friendly hierarchies. # pr — Commit, Push & Open Pull Request -Push the current branch and open a PR targeting main. This is the final step +Push the current branch and open a pull request. This is the final step before CI/CD takes over. ## Out of scope @@ -43,19 +43,17 @@ before CI/CD takes over. - Writing release notes (use `release-notes`) - Merging or deploying — CI/CD handles that after merge -## Deliverable and artifact policy +## Deliverable -- Primary deliverable: release pull request targeting main -- Baseline-first default: use existing branch artifacts directly; do not create parallel release records outside baseline docs. -- PR body source: `docs/releases/{date}.md` when present -- Before merge: ensure release artifact references in the PR body reflect final baseline files. - -______________________________________________________________________ +- A pull request open against the target base branch (typically `main`) ## Step 1: Pre-flight ```bash -# Confirm not on main +# Confirm gh CLI is authenticated +gh auth status 2>/dev/null || echo "WARNING: gh CLI not authenticated — Step 4 will fail" + +# Confirm not on the target base branch BRANCH=$(git branch --show-current) if [ "$BRANCH" = "main" ] || [ "$BRANCH" = "master" ]; then echo "ERROR: on $BRANCH — create a feature branch first" @@ -63,17 +61,23 @@ if [ "$BRANCH" = "main" ] || [ "$BRANCH" = "master" ]; then fi echo "Branch: $BRANCH" -# Check release notes exist -DATE=$(date +%Y-%m-%d) -RELEASE_FILE="docs/releases/${DATE}.md" -[ -f "$RELEASE_FILE" ] || echo "WARN: $RELEASE_FILE not found — PR body will be empty" +# Check if a PR already exists for this branch +EXISTING_PR=$(gh pr view --json url --jq '.url' 2>/dev/null) +if [ -n "$EXISTING_PR" ]; then + echo "PR already open: $EXISTING_PR" + exit 0 +fi # Show what will be included git status --short git log origin/main..HEAD --oneline -``` -______________________________________________________________________ +# Detect PR template for body structure +PR_TEMPLATE=$(cat .github/PULL_REQUEST_TEMPLATE.md \ + .github/PULL_REQUEST_TEMPLATE/pull_request_template.md \ + .github/pull_request_template.md 2>/dev/null | head -5) +[ -n "$PR_TEMPLATE" ] && echo "PR template found — use its structure for the body" +``` ## Step 2: Commit @@ -84,60 +88,66 @@ git add -A git diff --cached --stat # Only commit if there are staged changes -git diff --cached --quiet || git commit -m "release: $(date +%Y-%m-%d)" +git diff --cached --quiet || git commit -m "chore: pre-release cleanup" ``` -______________________________________________________________________ - ## Step 3: Push ```bash git push --set-upstream origin "$BRANCH" ``` -______________________________________________________________________ - ## Step 4: Open PR +Use the PR title and body provided by the invoking agent or user. +If no body is provided, write a short summary of the changes on this branch. +Use `--draft` when the work is not yet ready for review. + ```bash -DATE=$(date +%Y-%m-%d) -RELEASE_FILE="docs/releases/${DATE}.md" -BODY="" -[ -f "$RELEASE_FILE" ] && BODY=$(cat "$RELEASE_FILE") +# Short body (inline): +gh pr create \ + --base main \ + --title "<title>" \ + --body "<body>" +# Long body (write to file first): +cat > /tmp/pr-body.md <<'EOF' +<body> +EOF gh pr create \ --base main \ - --title "release: ${DATE}" \ - --body "$BODY" + --title "<title>" \ + --body-file /tmp/pr-body.md + +# Draft PR (not ready for review): +gh pr create \ + --base main \ + --title "<title>" \ + --body "<body>" \ + --draft ``` -If `gh` is not available: +If `gh` is not available or not authenticated: ```bash echo "Open PR manually:" -echo " Title: release: $(date +%Y-%m-%d)" +echo " Title: <title>" echo " Base: main" echo " Head: $BRANCH" echo " URL: https://github.com/<org>/<repo>/compare/main...$BRANCH" ``` -______________________________________________________________________ - ## Step 5: Report to user -Report the PR URL and next steps: +Report the PR URL and confirm what CI/CD will do next: ```text PR created: <url> -CI/CD will now: -- Run tests and security scan -- Build and publish container image -- Determine version (semantic-release / conventional commits) -- Deploy after approval and merge +Next steps depend on the repository CI/CD configuration: +- Automated tests and checks will run on the PR. +- Merge when all checks pass and reviewers approve. ``` -______________________________________________________________________ - <!-- AUTO-GENERATED — maintained by vstack, do not edit directly --> -<!-- VSTACK-META: {"artifact_name":"pr","artifact_type":"skill","artifact_version":"1.0.2","generator":"vstack","vstack_version":"1.3.0"} --> +<!-- VSTACK-META: {"artifact_name":"pr","artifact_type":"skill","artifact_version":"20260502013","generator":"vstack","vstack_version":"0.0.0.post3.dev0+df3fe6e"} --> diff --git a/.github/skills/rancher/SKILL.md b/.github/skills/rancher/SKILL.md new file mode 100644 index 0000000..17f1727 --- /dev/null +++ b/.github/skills/rancher/SKILL.md @@ -0,0 +1,115 @@ +--- +name: rancher +description: 'Operate Kubernetes workloads and governance through Rancher. Covers cluster and project context, role-based access, app deployment workflows, Fleet/GitOps basics, and multi-cluster operational checks. Use when asked to "deploy through Rancher", "review Rancher setup", "manage Rancher projects", or "troubleshoot Rancher-managed clusters".' +license: 'MIT' +compatibility: 'Requires a skills-compatible agent with repository file access. Requires Rancher UI/API access or Rancher CLI where applicable.' +metadata: + owner: vstack + maturity: stable +argument-hint: '[rancher server/context, cluster/project, and scope: deploy | governance | fleet | troubleshooting]' +user-invocable: true +disable-model-invocation: false +--- +## Skill Context + +This skill is part of **vstack** — a VS Code-native AI engineering workflow system. + +### AskUserQuestion Format + +When you need clarification, use this exact format — never invent or guess: + +> **Question:** [The specific question] +> **Options:** A) … | B) … | C) … +> **Default if no response:** [What you'll do] + +Never ask more than one question at a time without waiting for the answer. + +### Diagram Convention + +When producing hand-authored Markdown outputs, prefer Mermaid for flow, +interaction, lifecycle, state, topology, dependency, and decision diagrams when +the format is supported and improves clarity. Use ASCII as a fallback when +Mermaid is unsupported or would be less readable. Keep ASCII/text trees for +directory structures and other scan-friendly hierarchies. + +# rancher - Rancher Operations and Governance + +Operate Kubernetes workloads and governance through Rancher. + +## Out of scope + +- Cluster-agnostic Kubernetes manifest authoring (use `k8s`) +- Helm chart authoring and release logic (use `helm`) + +## Step 0: Detect Context + +```bash +# Rancher CLI is optional depending on environment +rancher --version 2>/dev/null || echo "rancher CLI not installed (UI/API mode may be used)" + +# Fleet or Rancher-managed config files in repository +find . -type f \( -name "fleet.yaml" -o -name "fleet.yml" -o -name "rancher*.yaml" -o -name "rancher*.yml" \) +``` + +## Step 1: Access and Scope Validation + +Before changes: + +- Confirm target Rancher server URL and environment +- Confirm target cluster, project, and namespace scope +- Confirm RBAC grants are least-privilege for requested operation + +Operational rule: + +- Never execute production changes from an unverified project context + +## Step 2: Workload Operations in Rancher + +Typical workflow: + +1. Select target cluster and project. +1. Validate namespace-level quotas/limits. +1. Deploy or update app workload. +1. Verify pod readiness, service reachability, and events. + +If Rancher app workflow uses Helm, validate chart and values first (via `helm` skill). + +## Step 3: Fleet and GitOps Practices + +For Fleet-managed repos: + +- Keep environment overlays explicit and small +- Pin chart/app versions across environments +- Promote via pull requests with diff review +- Treat drift as incident signal, not as expected noise + +Checks: + +- Bundle targets map to intended clusters +- No accidental wildcard targeting in production bundles +- Secret references resolve through approved secret paths + +## Step 4: Troubleshooting and Recovery + +- Use Rancher workload events and pod logs for first-line diagnosis +- Confirm cluster agent connectivity and state health +- For failed rollout, rollback to last healthy deployment revision +- Document root cause and hardening action in follow-up issue + +## Step 5: Security and Multi-Cluster Governance + +- Separate dev/staging/prod projects and access groups +- Keep project quotas and limits enforced +- Audit role bindings regularly for privilege creep +- Avoid broad administrative grants outside platform owners + +## References + +> Always use the official documentation for the exact Rancher, Fleet, and Kubernetes versions in use - capabilities and defaults vary by release. + +- [Rancher documentation](https://ranchermanager.docs.rancher.com/) +- [Rancher API guide](https://ranchermanager.docs.rancher.com/api/quickstart) +- [Fleet documentation](https://fleet.rancher.io/) + +<!-- AUTO-GENERATED — maintained by vstack, do not edit directly --> +<!-- VSTACK-META: {"artifact_name":"rancher","artifact_type":"skill","artifact_version":"20260502038","generator":"vstack","vstack_version":"0.0.0.post3.dev0+df3fe6e"} --> diff --git a/.github/skills/refactor/SKILL.md b/.github/skills/refactor/SKILL.md index acdad5b..efb2840 100644 --- a/.github/skills/refactor/SKILL.md +++ b/.github/skills/refactor/SKILL.md @@ -57,8 +57,6 @@ Refactoring is not rewriting. Every step must leave tests green. **Golden rule: If all tests pass before and after each step, the refactor is correct. If behavior changes, stop — that is a feature or bug fix, not a refactor.** -______________________________________________________________________ - ## Step 0: Define the Scope > **Question:** What needs refactoring and why? @@ -85,8 +83,6 @@ Motivation: [duplication | complexity | naming | coupling | size | other] Constraints: [what must not change] ``` -______________________________________________________________________ - ## Step 1: Establish a Baseline **Never start refactoring without a green test baseline.** @@ -131,8 +127,6 @@ Baseline: Lint: [clean | N warnings] ``` -______________________________________________________________________ - ## Step 2: Identify Code Smells Scan the target area for common smells: @@ -171,8 +165,6 @@ Smells found: P3 (low): [smell] — [location] ``` -______________________________________________________________________ - ## Step 3: Plan the Refactoring Break the refactoring into small, independent steps. Each step must: @@ -197,8 +189,6 @@ Risk: [Low | Medium — reason] - The plan requires changing database schema - More than 10 files are affected -______________________________________________________________________ - ## Step 4: Execute — One Step at a Time For each planned step: @@ -315,8 +305,6 @@ def create_user(request: CreateUserRequest) -> User: ... ``` -______________________________________________________________________ - ## Step 5: Verify After all steps are complete, run the full verification suite: @@ -358,8 +346,6 @@ git diff --stat git diff ``` -______________________________________________________________________ - ## Output ```text @@ -385,4 +371,4 @@ Behavior changed: No ``` <!-- AUTO-GENERATED — maintained by vstack, do not edit directly --> -<!-- VSTACK-META: {"artifact_name":"refactor","artifact_type":"skill","artifact_version":"1.0.1","generator":"vstack","vstack_version":"1.3.0"} --> +<!-- VSTACK-META: {"artifact_name":"refactor","artifact_type":"skill","artifact_version":"20260421023","generator":"vstack","vstack_version":"0.0.0.post3.dev0+df3fe6e"} --> diff --git a/.github/skills/release-notes/SKILL.md b/.github/skills/release-notes/SKILL.md index 7038e18..295355a 100644 --- a/.github/skills/release-notes/SKILL.md +++ b/.github/skills/release-notes/SKILL.md @@ -34,9 +34,8 @@ directory structures and other scan-friendly hierarchies. # release-notes — Release Artifact Preparation -Verify all artifacts are complete, write release notes, and update the changelog. - -This skill owns both `docs/releases/{date}.md` and `CHANGELOG.md` updates. +Write release notes and update the changelog so that the release is documented +before the PR is opened. ## Out of scope @@ -44,38 +43,31 @@ This skill owns both `docs/releases/{date}.md` and `CHANGELOG.md` updates. - Creating the PR (use `pr`) - Deployment — CI/CD takes over after merge -## Deliverable and artifact policy +## Deliverable -- Primary deliverables: `docs/releases/{date}.md`, `CHANGELOG.md` -- Baseline-first default: write final release artifacts directly to baseline docs on the feature branch. -- Optional WIP area for complex/uncertain efforts: `docs/delta/{id}/RELEASE_DELTA.md` -- Before merge: consolidate final release summary and changelog entries into baseline artifacts. +- A release notes document summarising what changed +- An updated `CHANGELOG.md` entry -______________________________________________________________________ +The invoking agent determines which files to read as evidence and where to write +the release notes. This skill describes the procedure, not the file paths. -## Step 1: Artifact checklist +## Step 1: Evidence review -Verify these files exist and are not empty: +Verify that the evidence the invoking agent has designated as required is present +and not empty. Report any missing items and stop if blockers exist. -```bash -for f in docs/product/requirements.md docs/architecture/architecture.md docs/design/design.md \ - docs/test-report.md docs/security-report.md CHANGELOG.md; do - [ -f "$f" ] && echo "✓ $f" || echo "✗ MISSING: $f" -done - -# Scope-conditional artifacts -[ -f docs/performance-baseline.md ] && echo "✓ docs/performance-baseline.md" || echo "i docs/performance-baseline.md (optional unless performance validation is in scope)" -[ -f docs/observability-baseline.md ] && echo "✓ docs/observability-baseline.md" || echo "i docs/observability-baseline.md (optional; observability evidence may be in docs/test-report.md)" -``` +Typical evidence to check (agent-defined): -If any required artifact is missing: **STOP and report**. Do not proceed. -If performance validation is in scope and `docs/performance-baseline.md` is missing: **STOP and report**. +- Test results or verification report +- Security findings or sign-off +- Change summary (git log, diff stat, or agent-provided summary) +- Acceptance criteria from requirements -______________________________________________________________________ +If any required evidence is missing: **STOP and report to the invoking agent**. ## Step 2: Summarise changes -Review what changed on this branch vs main: +Review what changed on this branch vs the base branch: ```bash git log origin/main..HEAD --oneline @@ -89,44 +81,32 @@ Identify: - Breaking changes (if any) - Internal/infrastructure changes -______________________________________________________________________ - -## Step 3: Write `docs/releases/{date}.md` +## Step 3: Write release notes +Write a release notes document to the location designated by the invoking agent. Date format: `YYYY-MM-DD` (today). Never overwrite an existing file. -```bash -DATE=$(date +%Y-%m-%d) -RELEASE_FILE="docs/releases/${DATE}.md" -[ -f "$RELEASE_FILE" ] && echo "ERROR: $RELEASE_FILE already exists" && exit 1 -mkdir -p docs/releases -``` - -Write the file with this structure: +Use this structure: ```markdown # Release {date} -## summary +## Summary [1–3 sentences: what changed and why it matters to users] -## what's new +## What's new - [user-visible feature or fix — lead with what the user can now DO] -## fixed +## Fixed - [bug fixes] -## internal +## Internal - [infra, tooling, tests — optional] -## artifacts reviewed -| artifact | status | +## Evidence reviewed +| evidence | status | |----------|--------| -| docs/product/requirements.md | ✓ | -| docs/architecture/architecture.md | ✓ | -| docs/design/design.md | ✓ | -| docs/test-report.md | ✓ | -| docs/security-report.md | ✓ | +| [evidence item] | ✓ / ✗ MISSING | ``` Rules: @@ -135,14 +115,12 @@ Rules: - No internal tracking references - Every entry should make someone think "oh nice, I want that" -______________________________________________________________________ - ## Step 4: Update `CHANGELOG.md` Prepend a new entry at the top of `CHANGELOG.md`: ```markdown -## {date} +## {version or date} ### What's new - [user-visible changes] @@ -156,7 +134,5 @@ Prepend a new entry at the top of `CHANGELOG.md`: Keep existing entries intact. -______________________________________________________________________ - <!-- AUTO-GENERATED — maintained by vstack, do not edit directly --> -<!-- VSTACK-META: {"artifact_name":"release-notes","artifact_type":"skill","artifact_version":"1.0.2","generator":"vstack","vstack_version":"1.3.0"} --> +<!-- VSTACK-META: {"artifact_name":"release-notes","artifact_type":"skill","artifact_version":"20260502014","generator":"vstack","vstack_version":"0.0.0.post3.dev0+df3fe6e"} --> diff --git a/.github/skills/requirements/SKILL.md b/.github/skills/requirements/SKILL.md index 6f21e8d..c0d4dbe 100644 --- a/.github/skills/requirements/SKILL.md +++ b/.github/skills/requirements/SKILL.md @@ -52,8 +52,6 @@ work from. - Optional WIP area for complex/uncertain intake: `docs/delta/{intake-id}/REQUIREMENTS_DELTA.md` - Before merge: consolidate any required content from optional delta notes back into `docs/product/requirements.md`, then remove stale WIP notes. -______________________________________________________________________ - ## Step 0: Context Read existing artifacts before asking questions: @@ -67,8 +65,6 @@ cat README.md 2>/dev/null | head -40 || true Identify what's already known and what needs clarification. -______________________________________________________________________ - ## Step 1: Problem Statement Clarify the core problem being solved: @@ -86,8 +82,6 @@ Document: [One paragraph: root problem, who has it, impact of not solving it] ``` -______________________________________________________________________ - ## Step 2: Users & Stakeholders Who uses or is affected by this? @@ -96,8 +90,6 @@ Who uses or is affected by this? | ----------- | ----------- | ------------ | | [User type] | | | -______________________________________________________________________ - ## Step 3: Functional Requirements What must the system do? Use the format: "The system must [verb] [object] [condition/constraint]." @@ -120,8 +112,6 @@ Ask for clarity on ambiguous areas: - [State what will NOT be built in this iteration] ``` -______________________________________________________________________ - ## Step 4: Non-Functional Requirements | Category | Requirement | Measurable target | @@ -137,8 +127,6 @@ Ask: > **Question:** Are there any hard non-functional requirements (performance, security, > compliance, data residency)? -______________________________________________________________________ - ## Step 5: Constraints & Assumptions Document known constraints: @@ -155,8 +143,6 @@ Document known constraints: - [Things assumed true that could invalidate requirements if wrong] ``` -______________________________________________________________________ - ## Step 6: Success Criteria What does "done" look like? How do we know the requirements are met? @@ -168,8 +154,6 @@ What does "done" look like? How do we know the requirements are met? - [ ] [Acceptance test: given X, when Y, then Z] ``` -______________________________________________________________________ - ## Step 7: Open Questions List anything that is unclear and needs a decision before work begins: @@ -179,8 +163,6 @@ List anything that is unclear and needs a decision before work begins: - [ ] [Question] — Owner: [who decides] — Deadline: [when needed] ``` -______________________________________________________________________ - ## Output: requirements.md Write all findings to `docs/product/requirements.md`: @@ -216,7 +198,5 @@ Write all findings to `docs/product/requirements.md`: After writing, summarize what was decided so the architect role can start. -______________________________________________________________________ - <!-- AUTO-GENERATED — maintained by vstack, do not edit directly --> -<!-- VSTACK-META: {"artifact_name":"requirements","artifact_type":"skill","artifact_version":"1.0.2","generator":"vstack","vstack_version":"1.3.0"} --> +<!-- VSTACK-META: {"artifact_name":"requirements","artifact_type":"skill","artifact_version":"20260421024","generator":"vstack","vstack_version":"0.0.0.post3.dev0+df3fe6e"} --> diff --git a/.github/skills/secret-scan/SKILL.md b/.github/skills/secret-scan/SKILL.md new file mode 100644 index 0000000..a378d37 --- /dev/null +++ b/.github/skills/secret-scan/SKILL.md @@ -0,0 +1,242 @@ +--- +name: secret-scan +description: 'Configure and manage GitHub secret scanning and push protection. Covers enabling secret scanning, push protection, custom patterns, alert triage, and remediation of exposed credentials. Use when asked to "set up secret scanning", "configure push protection", "define custom secret patterns", "triage a secret alert", or "fix a leaked credential".' +license: 'MIT' +compatibility: 'Requires repository access and GitHub Advanced Security (private repos) or public repository. Alert management requires gh CLI authentication.' +metadata: + owner: vstack + maturity: stable +argument-hint: '[scope: enable | configure push-protection | custom-pattern | triage alerts | remediate]' +user-invocable: true +disable-model-invocation: false +--- +## Skill Context + +This skill is part of **vstack** — a VS Code-native AI engineering workflow system. + +### AskUserQuestion Format + +When you need clarification, use this exact format — never invent or guess: + +> **Question:** [The specific question] +> **Options:** A) … | B) … | C) … +> **Default if no response:** [What you'll do] + +Never ask more than one question at a time without waiting for the answer. + +### Diagram Convention + +When producing hand-authored Markdown outputs, prefer Mermaid for flow, +interaction, lifecycle, state, topology, dependency, and decision diagrams when +the format is supported and improves clarity. Use ASCII as a fallback when +Mermaid is unsupported or would be less readable. Keep ASCII/text trees for +directory structures and other scan-friendly hierarchies. + +# secret-scan — GitHub Secret Scanning & Push Protection + +Configure secret scanning and push protection to prevent credential exposure. + +**Golden rule: Rotate first, investigate second.** A leaked credential is +compromised the moment it enters the repository. Rotation is non-negotiable — +then determine scope and remove from history. + +## Out of scope + +- CodeQL code scanning (use `codeql`) +- Dependency vulnerability scanning (use `dependabot` or `dependency`) +- General security audit (use `security`) + +## Availability + +| Repository type | Availability | +| ---------------------------- | --------------------------------------------------- | +| Public repos | Automatic, free | +| Private/internal (org-owned) | Requires GitHub Secret Protection (Team/Enterprise) | + +## Step 1: Enable Secret Scanning + +Navigate to repository **Settings → Advanced Security → Secret Protection → Enable**. + +For organizations, configure at scale via **Settings → Advanced Security → Security configurations**. + +Also enable: + +- **Push protection** — blocks secrets before they reach the repository +- **Non-provider patterns** — detects private keys, connection strings, generic API keys +- **AI detection** — Copilot-assisted detection of unstructured secrets (passwords) +- **Validity checks** — verifies if detected secrets are still active + +## Step 2: Configure Path Exclusions + +Create `.github/secret_scanning.yml` to auto-close alerts for known-safe paths: + +```yaml +paths-ignore: + - "docs/examples/**" # Example/demo credentials + - "test/fixtures/**" # Test fixture files + - "**/*.example" # Template files with placeholder values +``` + +**Limits:** 1,000 entries maximum, file under 1 MB. + +**Best practices:** + +- Be as specific as possible — broad exclusions create blind spots +- Add comments explaining why each path is excluded +- Review exclusions periodically; remove stale entries +- Excluded paths also skip push protection checks + +## Step 3: Scan for Existing Secrets Locally + +Before enabling, scan the existing codebase: + +```bash +# Scan for common secret patterns +grep -r -E \ + '(password|secret|api_key|private_key|token|access_key|client_secret)\s*[=:]\s*["\x27][^"\x27]{8,}' \ + --include='*.py' --include='*.ts' --include='*.js' --include='*.go' \ + --include='*.yaml' --include='*.env' --include='*.json' \ + --exclude-dir=node_modules --exclude-dir=.venv --exclude-dir=vendor \ + --exclude-dir=.git --exclude-dir=dist --exclude-dir=build \ + . 2>/dev/null | grep -v test | grep -v example | head -30 + +# Check git history for secrets (high-value branches) +git log --all --oneline | head -20 +``` + +## Step 4: Triage Alerts + +```bash +# List open secret scanning alerts via gh CLI +gh api "repos/$(gh repo view --json nameWithOwner --jq '.nameWithOwner')/secret-scanning/alerts" \ + --jq '.[] | {number, state, secret_type, created_at, html_url}' +``` + +**Alert types:** + +| Type | Description | +| ----------------------------- | ------------------------------------------------------ | +| Provider alerts | Detected by GitHub's partner program (high confidence) | +| Non-provider / generic alerts | Private keys, connection strings, generic patterns | +| Push protection alerts | Secrets pushed via a bypass | + +**Alert validity status:** + +- `active` — credential is confirmed live → **rotate immediately** +- `inactive` — credential is confirmed revoked +- `unknown` — validity could not be determined + +## Step 5: Remediate an Exposed Secret + +### Step A: Rotate the credential (do this first) + +1. Log in to the service where the credential was issued +1. Revoke the exposed credential +1. Issue a new credential +1. Update all places that use the old credential (environment variables, secret stores, `.env` files, CI/CD secrets) + +### Step B: Remove from latest commit (if recent) + +```bash +# Edit the file to remove the secret, then: +git add <file> +git commit --amend +git push --force-with-lease +``` + +### Step C: Remove from history (if in earlier commits) + +```bash +# Find the earliest commit containing the secret +git log --all -S "<partial-secret-value>" --oneline + +# Remove via interactive rebase +git rebase -i <COMMIT-SHA>~1 +# Change 'pick' to 'edit' for the offending commit +# Remove the secret from the file, then: +git add <file> +git commit --amend +git rebase --continue +git push --force-with-lease +``` + +> Force-pushing rewrites history — coordinate with the team and merge any +> open PRs first to avoid losing work. + +### Step D: Dismiss the alert + +After rotation and removal, dismiss with the appropriate reason: + +- **Revoked** — credential has been rotated +- **False positive** — detected string is not a real secret +- **Used in tests** — secret appears only in test code with no real access + +## Step 6: Resolve a Blocked Push + +When push protection blocks a push, you will see a URL in the error: + +### Option A: Remove the secret and retry (preferred) + +```bash +# Edit the file to remove the secret +git add <file> +git commit --amend +git push +``` + +### Option B: Bypass (only for confirmed false positives or test data) + +1. Visit the URL from the push error message (same user session) +1. Select a reason: "It's a false positive" or "It's used in tests" +1. Click "Allow me to push this secret" — bypass window is 3 hours +1. Re-push the commits + +### Option C: Request bypass (if delegated bypass is configured) + +1. Visit the URL from the error +1. Add a comment explaining why the secret is safe +1. Submit the request — wait for approval notification + +## Step 7: Custom Secret Patterns + +Define organization-specific patterns when built-in patterns don't cover internal +credential formats. + +**Via GitHub UI:** + +1. Settings → Advanced Security → Custom patterns → New pattern +1. Enter pattern name and regex +1. Add a sample test string +1. Click "Save and dry run" — review results for false positives (up to 1,000) +1. Click "Publish pattern" +1. Optionally enable push protection for the pattern + +**Regex guidelines:** + +- Anchor to known prefixes/suffixes where possible: `myapp_[a-zA-Z0-9]{32}` +- Test against real examples and known non-secret strings +- Avoid overly broad patterns (high false-positive rate reduces signal-to-noise) +- Scopes: repository, organization, or enterprise level + +## Review checklist + +- [ ] Secret scanning enabled on all repositories (or via org security configuration) +- [ ] Push protection enabled +- [ ] `.github/secret_scanning.yml` excludes only known-safe paths with comments +- [ ] All `active` alerts rotated and dismissed +- [ ] Git history cleaned if secret was committed (and pushed) +- [ ] All dependent services updated with new credentials +- [ ] Non-provider pattern scanning enabled for internal credential formats +- [ ] Custom patterns defined for any organization-specific credential formats +- [ ] Secrets stored in environment variables or a secret store — never in source code + +## References + +> Always use the official documentation for the exact version in use — supported secret patterns and push protection rules are updated regularly. + +- [GitHub secret scanning documentation](https://docs.github.com/en/code-security/secret-scanning/introduction/about-secret-scanning) +- [Push protection](https://docs.github.com/en/code-security/secret-scanning/protecting-pushes-with-secret-scanning) +- [Supported secret patterns](https://docs.github.com/en/code-security/secret-scanning/introduction/supported-secret-scanning-patterns) + +<!-- AUTO-GENERATED — maintained by vstack, do not edit directly --> +<!-- VSTACK-META: {"artifact_name":"secret-scan","artifact_type":"skill","artifact_version":"20260502028","generator":"vstack","vstack_version":"0.0.0.post3.dev0+df3fe6e"} --> diff --git a/.github/skills/security/SKILL.md b/.github/skills/security/SKILL.md index c37a48d..74d75e0 100644 --- a/.github/skills/security/SKILL.md +++ b/.github/skills/security/SKILL.md @@ -75,8 +75,6 @@ CURRENT=$(git branch --show-current) git diff <base> --stat 2>/dev/null | head -20 || true ``` -______________________________________________________________________ - ## Part 1: OWASP Top 10 ### A01: Broken Access Control @@ -90,7 +88,7 @@ grep -r -n "is_admin\|hasRole\|checkPermission\|authorize\|can(" \ # Look for endpoints missing auth grep -r -n "@app.route\|router\.\|@Get\|@Post\|@Put\|@Delete\|@Patch" \ --include='*.ts' --include='*.py' --include='*.go' \ - --exclude-dir=node_modules --exclude-dir=.venv --exclude-dir=venv --exclude-dir=env --exclude-dir=__pycache__ --exclude-dir=dist --exclude-dir=build . 2>/dev/null | head -30 + --exclude-dir=node_modules --exclude-dir=.venv --exclude-dir=venv --exclude-dir=env --exclude-dir=__pycache__ --exclude-dir=dist --exclude-dir=build --exclude-dir=vendor . 2>/dev/null | head -30 ``` Check: @@ -107,12 +105,12 @@ Check: # Find hardcoded secrets grep -r -E '(password|secret|api_key|private_key|token)\s*[=:]\s*["\x27][^"\x27]{8,}' \ --include='*.ts' --include='*.py' --include='*.go' --include='*.yaml' --include='*.env' \ - --exclude-dir=node_modules --exclude-dir=.venv --exclude-dir=venv --exclude-dir=env --exclude-dir=__pycache__ --exclude-dir=dist --exclude-dir=build --exclude-dir=.git . 2>/dev/null | grep -v test | grep -v example + --exclude-dir=node_modules --exclude-dir=.venv --exclude-dir=venv --exclude-dir=env --exclude-dir=__pycache__ --exclude-dir=dist --exclude-dir=build --exclude-dir=vendor --exclude-dir=.git . 2>/dev/null | grep -v test | grep -v example # Find weak crypto grep -r -n "MD5\|SHA1\|DES\|RC4\|Math.random\|random.random" \ --include='*.ts' --include='*.py' --include='*.go' \ - --exclude-dir=node_modules --exclude-dir=.venv --exclude-dir=venv --exclude-dir=env --exclude-dir=__pycache__ --exclude-dir=dist --exclude-dir=build . 2>/dev/null | head -20 + --exclude-dir=node_modules --exclude-dir=.venv --exclude-dir=venv --exclude-dir=env --exclude-dir=__pycache__ --exclude-dir=dist --exclude-dir=build --exclude-dir=vendor . 2>/dev/null | head -20 ``` Check: @@ -129,12 +127,12 @@ Check: # SQL injection risk grep -r -n 'query\|execute\|raw\|f"' \ --include='*.py' --include='*.ts' --include='*.go' \ - --exclude-dir=node_modules --exclude-dir=.venv --exclude-dir=venv --exclude-dir=env --exclude-dir=__pycache__ --exclude-dir=dist --exclude-dir=build . 2>/dev/null | grep -E '"SELECT|"INSERT|"UPDATE|"DELETE|f".*sql' | head -20 + --exclude-dir=node_modules --exclude-dir=.venv --exclude-dir=venv --exclude-dir=env --exclude-dir=__pycache__ --exclude-dir=dist --exclude-dir=build --exclude-dir=vendor . 2>/dev/null | grep -E '"SELECT|"INSERT|"UPDATE|"DELETE|f".*sql' | head -20 # Command injection risk grep -r -n 'exec\|subprocess\|shell=True\|execSync\|spawnSync' \ --include='*.py' --include='*.ts' --include='*.go' \ - --exclude-dir=node_modules --exclude-dir=.venv --exclude-dir=venv --exclude-dir=env --exclude-dir=__pycache__ --exclude-dir=dist --exclude-dir=build . 2>/dev/null | head -20 + --exclude-dir=node_modules --exclude-dir=.venv --exclude-dir=venv --exclude-dir=env --exclude-dir=__pycache__ --exclude-dir=dist --exclude-dir=build --exclude-dir=vendor . 2>/dev/null | head -20 ``` Check: @@ -157,12 +155,12 @@ Check: # Check for debug/development modes grep -r -n 'DEBUG\s*=\s*True\|debug:\s*true\|development\|NODE_ENV' \ --include='*.py' --include='*.ts' --include='*.yaml' --include='*.json' \ - --exclude-dir=node_modules --exclude-dir=.venv --exclude-dir=venv --exclude-dir=env --exclude-dir=__pycache__ --exclude-dir=dist --exclude-dir=build . 2>/dev/null | grep -v test | head -20 + --exclude-dir=node_modules --exclude-dir=.venv --exclude-dir=venv --exclude-dir=env --exclude-dir=__pycache__ --exclude-dir=dist --exclude-dir=build --exclude-dir=vendor . 2>/dev/null | grep -v test | head -20 # Check for permissive CORS grep -r -n 'cors\|CORS\|Access-Control-Allow-Origin' \ --include='*.ts' --include='*.py' --include='*.go' \ - --exclude-dir=node_modules --exclude-dir=.venv --exclude-dir=venv --exclude-dir=env --exclude-dir=__pycache__ --exclude-dir=dist --exclude-dir=build . 2>/dev/null | head -20 + --exclude-dir=node_modules --exclude-dir=.venv --exclude-dir=venv --exclude-dir=env --exclude-dir=__pycache__ --exclude-dir=dist --exclude-dir=build --exclude-dir=vendor . 2>/dev/null | head -20 ``` Check: @@ -190,7 +188,7 @@ Check: # Check session/token implementation grep -r -n 'jwt\|JWT\|session\|cookie\|token' \ --include='*.ts' --include='*.py' --include='*.go' \ - --exclude-dir=node_modules --exclude-dir=.venv --exclude-dir=venv --exclude-dir=env --exclude-dir=__pycache__ --exclude-dir=dist --exclude-dir=build . 2>/dev/null | grep -i 'expire\|expiry\|secret\|key' | head -20 + --exclude-dir=node_modules --exclude-dir=.venv --exclude-dir=venv --exclude-dir=env --exclude-dir=__pycache__ --exclude-dir=dist --exclude-dir=build --exclude-dir=vendor . 2>/dev/null | grep -i 'expire\|expiry\|secret\|key' | head -20 ``` Check: @@ -219,7 +217,7 @@ Check: ```bash grep -r -n 'audit\|security_log\|auth.*log\|access.*log' \ --include='*.ts' --include='*.py' --include='*.go' \ - --exclude-dir=node_modules --exclude-dir=.venv --exclude-dir=venv --exclude-dir=env --exclude-dir=__pycache__ --exclude-dir=dist --exclude-dir=build . 2>/dev/null | head -20 + --exclude-dir=node_modules --exclude-dir=.venv --exclude-dir=venv --exclude-dir=env --exclude-dir=__pycache__ --exclude-dir=dist --exclude-dir=build --exclude-dir=vendor . 2>/dev/null | head -20 ``` Check: @@ -235,7 +233,7 @@ Check: ```bash grep -r -n 'fetch\|requests\.\|http\.get\|axios\|urllib' \ --include='*.ts' --include='*.py' --include='*.go' \ - --exclude-dir=node_modules --exclude-dir=.venv --exclude-dir=venv --exclude-dir=env --exclude-dir=__pycache__ --exclude-dir=dist --exclude-dir=build . 2>/dev/null | grep -v test | head -20 + --exclude-dir=node_modules --exclude-dir=.venv --exclude-dir=venv --exclude-dir=env --exclude-dir=__pycache__ --exclude-dir=dist --exclude-dir=build --exclude-dir=vendor . 2>/dev/null | grep -v test | head -20 ``` Check: @@ -244,8 +242,6 @@ Check: - [ ] Private network ranges blocked (169.254.0.0/16, 10.0.0.0/8, etc.) - [ ] SSRF protection on any URL-fetching functionality -______________________________________________________________________ - ## Part 2: STRIDE Threat Model For each new service/component, answer: @@ -259,8 +255,6 @@ For each new service/component, answer: | **Denial of Service** | Can the service be made unavailable? Rate limiting? | | | **Elevation of Privilege** | Can a user gain admin access through normal flows? | | -______________________________________________________________________ - ## Audit Report ```text @@ -292,7 +286,13 @@ Scope: [full/diff/dependency/config] [SHIP-READY / FIX CRITICALS / SECURITY REVIEW REQUIRED] ``` -______________________________________________________________________ +## References + +> OWASP Top 10 and STRIDE are living documents — always refer to the current edition. + +- [OWASP Top 10](https://owasp.org/www-project-top-ten/) +- [OWASP API Security Top 10](https://owasp.org/www-project-api-security/) +- [STRIDE threat modeling (Microsoft)](https://learn.microsoft.com/en-us/azure/security/develop/threat-modeling-tool-threats) <!-- AUTO-GENERATED — maintained by vstack, do not edit directly --> -<!-- VSTACK-META: {"artifact_name":"security","artifact_type":"skill","artifact_version":"1.0.2","generator":"vstack","vstack_version":"1.3.0"} --> +<!-- VSTACK-META: {"artifact_name":"security","artifact_type":"skill","artifact_version":"20260421025","generator":"vstack","vstack_version":"0.0.0.post3.dev0+df3fe6e"} --> diff --git a/.github/skills/terraform/SKILL.md b/.github/skills/terraform/SKILL.md new file mode 100644 index 0000000..2554e0c --- /dev/null +++ b/.github/skills/terraform/SKILL.md @@ -0,0 +1,337 @@ +--- +name: terraform +description: 'Write, review, and refactor Terraform infrastructure-as-code. Covers resource design, module structure, state management, variable and output conventions, provider pinning, remote backends, workspace strategy, drift detection, and security hardening. Use when asked to "write Terraform", "review this Terraform", "refactor IaC", "add a Terraform module", "plan state migration", or "harden Terraform configuration".' +license: 'MIT' +compatibility: 'Requires a skills-compatible agent with repository file access. Requires Terraform CLI installed for plan/apply operations.' +metadata: + owner: vstack + maturity: stable +argument-hint: '[provider: aws | azure | gcp | generic, and scope: new resource | module | state migration | security review]' +user-invocable: true +disable-model-invocation: false +--- +## Skill Context + +This skill is part of **vstack** — a VS Code-native AI engineering workflow system. + +### AskUserQuestion Format + +When you need clarification, use this exact format — never invent or guess: + +> **Question:** [The specific question] +> **Options:** A) … | B) … | C) … +> **Default if no response:** [What you'll do] + +Never ask more than one question at a time without waiting for the answer. + +### Diagram Convention + +When producing hand-authored Markdown outputs, prefer Mermaid for flow, +interaction, lifecycle, state, topology, dependency, and decision diagrams when +the format is supported and improves clarity. Use ASCII as a fallback when +Mermaid is unsupported or would be less readable. Keep ASCII/text trees for +directory structures and other scan-friendly hierarchies. + +# terraform — Infrastructure as Code with Terraform + +Write, review, and refactor Terraform configurations for any provider. + +## Out of scope + +- Terragrunt DRY wrappers (use `terragrunt`) +- AWS-specific CLI workflows (use `aws-cli`) +- CloudFormation templates (use `cloudformation`) + +## Step 0: Detect Context + +```bash +terraform version 2>/dev/null || echo "terraform not installed" + +# Find all Terraform roots +find . -name "*.tf" -not -path "*/.terraform/*" | sed 's|/[^/]*\.tf$||' | sort -u + +# Check backend and provider constraints +grep -rl "backend" . --include="*.tf" 2>/dev/null +grep -A5 'required_providers' -r . --include="*.tf" 2>/dev/null | head -20 +``` + +## Step 1: Repository Structure + +### Single service + +``` +infra/ +├── main.tf ← root module: resource definitions +├── variables.tf ← input variables with types and defaults +├── outputs.tf ← outputs consumed by other modules or CI +├── providers.tf ← provider configuration and version constraints +├── versions.tf ← terraform {} block with required_version +├── locals.tf ← computed values and name construction +└── modules/ + └── <name>/ ← reusable submodule + ├── main.tf + ├── variables.tf + └── outputs.tf +``` + +### Monorepo / multi-environment + +``` +infra/ +├── modules/ ← shared reusable modules +│ └── <name>/ +├── environments/ +│ ├── dev/ +│ │ ├── main.tf +│ │ └── terraform.tfvars +│ ├── staging/ +│ └── prod/ +``` + +## Step 2: Provider and Version Pinning + +Always pin provider versions and the Terraform binary. Never use unbounded ranges in production. + +```hcl +# versions.tf +terraform { + required_version = "~> 1.9" + + required_providers { + aws = { + source = "hashicorp/aws" + version = "~> 5.0" + } + } +} +``` + +**Version constraint operators:** + +- `~> 1.9` — allows patch and minor updates within 1.x (recommended) +- `>= 1.9, < 2.0` — explicit range +- `= 1.9.2` — exact pin (lockfile preferred over this) + +Always commit `.terraform.lock.hcl` to source control. + +## Step 3: Remote Backend + +Never use local state in production. Configure a remote backend with state locking. + +```hcl +# AWS S3 + DynamoDB locking +terraform { + backend "s3" { + bucket = "myorg-terraform-state" + key = "services/myservice/terraform.tfstate" + region = "eu-west-1" + encrypt = true + dynamodb_table = "terraform-state-lock" + } +} +``` + +**State bucket requirements:** + +- Enable versioning on the S3 bucket (enables rollback) +- Enable server-side encryption (SSE-S3 minimum, SSE-KMS preferred) +- Block all public access +- Restrict bucket policy to Terraform IAM role + approved team roles + +## Step 4: Variables and Outputs + +```hcl +# variables.tf — always include type, description, and sensible defaults +variable "environment" { + type = string + description = "Deployment environment: dev | staging | prod" + validation { + condition = contains(["dev", "staging", "prod"], var.environment) + error_message = "environment must be dev, staging, or prod." + } +} + +variable "db_password" { + type = string + description = "Database master password — supply via TF_VAR_db_password or tfvars." + sensitive = true +} +``` + +```hcl +# outputs.tf — mark sensitive outputs accordingly +output "api_endpoint" { + description = "Base URL of the deployed API." + value = aws_lb.main.dns_name +} + +output "db_connection_string" { + description = "Database connection string." + value = "postgres://${aws_db_instance.main.endpoint}/${var.db_name}" + sensitive = true +} +``` + +**Rules:** + +- Mark all secrets as `sensitive = true` — prevents them appearing in plan output and logs +- Never hardcode secrets in `.tf` files or `.tfvars` committed to source control +- Use `TF_VAR_*` env vars or a secrets manager data source for secrets + +## Step 5: Naming and Tagging + +```hcl +# locals.tf — centralize name construction +locals { + name_prefix = "${var.project}-${var.environment}" + + common_tags = { + Project = var.project + Environment = var.environment + ManagedBy = "terraform" + Owner = var.team + } +} + +resource "aws_s3_bucket" "uploads" { + bucket = "${local.name_prefix}-uploads" + tags = local.common_tags +} +``` + +## Step 6: Module Design + +```hcl +# Good: module exposes what callers need +module "rds" { + source = "./modules/rds" + + name = "${local.name_prefix}-db" + subnet_ids = module.vpc.private_subnet_ids + vpc_id = module.vpc.vpc_id + environment = var.environment +} +``` + +**Module rules:** + +- One purpose per module — avoid "kitchen sink" modules +- Accept subnet IDs and VPC IDs as inputs rather than looking them up inside the module (reduces coupling) +- Expose only what callers need as outputs +- Pin module versions when sourcing from a registry: `version = "~> 3.0"` + +## Step 7: Security Hardening + +```bash +# Run tfsec for security misconfigurations +tfsec . --minimum-severity HIGH + +# Run checkov for CIS benchmark checks +checkov -d . --framework terraform --compact --quiet + +# Run trivy for misconfigurations +trivy config . --severity HIGH,CRITICAL +``` + +**Common misconfigurations to check:** + +- S3 buckets: `block_public_acls = true`, `block_public_policy = true`, encryption enabled +- RDS: `storage_encrypted = true`, `deletion_protection = true`, no public access +- Security groups: no `0.0.0.0/0` on SSH/RDP; restrict to known CIDR ranges +- IAM: least-privilege policies; no `*` actions on `*` resources +- KMS: key rotation enabled (`enable_key_rotation = true`) +- VPC: flow logs enabled; no internet gateway on private subnets + +## Step 8: Plan and Apply Workflow + +```bash +# Initialize (after adding/changing providers or backends) +terraform init + +# Format check (enforce in CI) +terraform fmt -check -recursive + +# Validate syntax and references +terraform validate + +# Plan — always review before applying +terraform plan -out=tfplan + +# Apply from saved plan (ensures what was reviewed is what runs) +terraform apply tfplan + +# Targeted apply (use sparingly — prefer full applies) +terraform apply -target=aws_s3_bucket.uploads + +# Destroy (requires explicit confirmation — destructive) +terraform destroy -target=aws_s3_bucket.uploads +``` + +## Step 9: Drift Detection + +```bash +# Detect drift between state and real infrastructure +terraform plan -detailed-exitcode +# Exit code 0: no changes; 1: error; 2: changes present + +# Refresh state to pick up out-of-band changes (read-only) +terraform refresh +``` + +Set up drift detection in CI: + +```yaml +- name: Terraform plan (drift check) + run: terraform plan -detailed-exitcode -no-color + continue-on-error: false # fail CI on drift +``` + +## Step 10: State Operations (high risk) + +Always back up state before state manipulations. + +```bash +# List state resources +terraform state list + +# Show a specific resource +terraform state show aws_s3_bucket.uploads + +# Move resource to new address (after refactor) +terraform state mv aws_s3_bucket.uploads aws_s3_bucket.media + +# Import existing resource into state +terraform import aws_s3_bucket.uploads my-existing-bucket-name + +# Remove resource from state without destroying it +terraform state rm aws_s3_bucket.old_name +``` + +Run `terraform plan` after every state operation to verify the outcome. + +## Review Checklist + +- [ ] `required_version` and all providers pinned with `~>` constraints +- [ ] `.terraform.lock.hcl` committed to source control +- [ ] Remote backend configured with encryption and state locking +- [ ] No secrets hardcoded in `.tf` files; sensitive variables marked `sensitive = true` +- [ ] All resources tagged via `locals.common_tags` +- [ ] S3 buckets: public access blocked, encryption enabled +- [ ] RDS: `storage_encrypted`, `deletion_protection`, no public access +- [ ] Security groups: no `0.0.0.0/0` on management ports +- [ ] IAM policies: least privilege, no `*:*` wildcards +- [ ] `tfsec` or `checkov` passes with no HIGH/CRITICAL findings +- [ ] `terraform fmt -check` passes in CI +- [ ] `terraform validate` passes in CI + +## References + +> Always use the official documentation for the provider and Terraform version in use — resource schema, argument names, and defaults change between provider releases. + +- [Terraform documentation](https://developer.hashicorp.com/terraform/docs) +- [Terraform provider registry](https://registry.terraform.io/) +- [AWS provider documentation](https://registry.terraform.io/providers/hashicorp/aws/latest/docs) +- [tfsec rules](https://aquasecurity.github.io/tfsec/latest/checks/aws/) · [checkov checks](https://www.checkov.io/5.Policy%20Index/terraform.html) + +<!-- AUTO-GENERATED — maintained by vstack, do not edit directly --> +<!-- VSTACK-META: {"artifact_name":"terraform","artifact_type":"skill","artifact_version":"20260502030","generator":"vstack","vstack_version":"0.0.0.post3.dev0+df3fe6e"} --> diff --git a/.github/skills/terragrunt/SKILL.md b/.github/skills/terragrunt/SKILL.md new file mode 100644 index 0000000..baccafa --- /dev/null +++ b/.github/skills/terragrunt/SKILL.md @@ -0,0 +1,309 @@ +--- +name: terragrunt +description: 'Write, review, and refactor Terragrunt configurations for DRY multi-environment infrastructure. Covers root and unit-level HCL structure, generate blocks, remote state inheritance, dependency blocks, inputs, mock outputs, and run-all workflows. Use when asked to "write Terragrunt", "set up Terragrunt", "DRY Terraform across environments", "configure Terragrunt dependencies", or "migrate from plain Terraform to Terragrunt".' +license: 'MIT' +compatibility: 'Requires a skills-compatible agent with repository file access. Requires Terraform CLI and Terragrunt installed for plan/apply operations.' +metadata: + owner: vstack + maturity: stable +argument-hint: '[scope: new layout | dependency graph | state migration | run-all workflow | security review]' +user-invocable: true +disable-model-invocation: false +--- +## Skill Context + +This skill is part of **vstack** — a VS Code-native AI engineering workflow system. + +### AskUserQuestion Format + +When you need clarification, use this exact format — never invent or guess: + +> **Question:** [The specific question] +> **Options:** A) … | B) … | C) … +> **Default if no response:** [What you'll do] + +Never ask more than one question at a time without waiting for the answer. + +### Diagram Convention + +When producing hand-authored Markdown outputs, prefer Mermaid for flow, +interaction, lifecycle, state, topology, dependency, and decision diagrams when +the format is supported and improves clarity. Use ASCII as a fallback when +Mermaid is unsupported or would be less readable. Keep ASCII/text trees for +directory structures and other scan-friendly hierarchies. + +# terragrunt — DRY Terraform with Terragrunt + +Write and review Terragrunt configurations to eliminate repetition across +environments, accounts, and regions. + +## Out of scope + +- Terraform module authoring (use `terraform`) +- AWS CLI operations (use `aws-cli`) +- CloudFormation templates (use `cloudformation`) + +## Step 0: Detect Context + +```bash +# Check Terragrunt version +terragrunt --version 2>/dev/null || echo "terragrunt not installed" +terraform version 2>/dev/null || echo "terraform not installed" + +# Find all Terragrunt roots +find . -name "terragrunt.hcl" -not -path "*/.terragrunt-cache/*" | sort + +# Check if there is a root terragrunt.hcl +ls terragrunt.hcl root.hcl 2>/dev/null || echo "No root HCL found" +``` + +## Step 1: Repository Structure + +Terragrunt works best with a strict directory hierarchy that maps to your +deployment topology. + +``` +infra/ +├── terragrunt.hcl ← root config: remote state, provider generate block +├── _envcommon/ ← shared inputs across environments +│ ├── vpc.hcl +│ └── rds.hcl +├── dev/ +│ ├── account.hcl ← account-level inputs (account_id, region) +│ ├── vpc/ +│ │ └── terragrunt.hcl +│ ├── rds/ +│ │ └── terragrunt.hcl +│ └── app/ +│ └── terragrunt.hcl +├── staging/ +│ └── ... +└── prod/ + └── ... +``` + +Each leaf `terragrunt.hcl` is a **unit** — one Terraform module invocation. +Parent `terragrunt.hcl` files contain shared configuration inherited by all +descendants. + +## Step 2: Root Configuration + +```hcl +# infra/terragrunt.hcl — inherited by all units +locals { + account_vars = read_terragrunt_config(find_in_parent_folders("account.hcl")) + region = local.account_vars.locals.region + account_id = local.account_vars.locals.account_id + project = "myapp" +} + +# Remote state — one state file per unit, auto-named from path +remote_state { + backend = "s3" + config = { + bucket = "${local.project}-terraform-state-${local.account_id}" + key = "${path_relative_to_include()}/terraform.tfstate" + region = local.region + encrypt = true + dynamodb_table = "terraform-state-lock" + } + generate = { + path = "backend.tf" + if_exists = "overwrite_terragrunt" + } +} + +# Inject provider block into every unit +generate "provider" { + path = "provider.tf" + if_exists = "overwrite_terragrunt" + contents = <<-EOF + provider "aws" { + region = "${local.region}" + + default_tags { + tags = { + Project = "${local.project}" + ManagedBy = "terragrunt" + } + } + } + EOF +} +``` + +## Step 3: Account-Level Config + +```hcl +# infra/dev/account.hcl +locals { + account_id = "123456789012" + region = "eu-west-1" + env = "dev" +} +``` + +## Step 4: Unit Configuration (leaf) + +```hcl +# infra/dev/rds/terragrunt.hcl +include "root" { + path = find_in_parent_folders() + expose = true +} + +# Pull in shared inputs from _envcommon +locals { + common = read_terragrunt_config(find_in_parent_folders("_envcommon/rds.hcl")) + env = include.root.locals.account_vars.locals.env +} + +terraform { + source = "git::https://github.com/myorg/terraform-modules.git//modules/rds?ref=v2.1.0" +} + +inputs = merge( + local.common.inputs, + { + environment = local.env + db_name = "myapp_${local.env}" + } +) +``` + +## Step 5: Dependency Blocks + +```hcl +# infra/dev/app/terragrunt.hcl +include "root" { + path = find_in_parent_folders() +} + +terraform { + source = "../../../modules/app" +} + +dependency "vpc" { + config_path = "../vpc" + + # Mock outputs for plan without deploying dependencies first + mock_outputs = { + vpc_id = "vpc-00000000" + private_subnet_ids = ["subnet-00000001", "subnet-00000002"] + } + mock_outputs_allowed_terraform_commands = ["validate", "plan"] +} + +dependency "rds" { + config_path = "../rds" + + mock_outputs = { + db_endpoint = "mock-db.example.com" + db_port = 5432 + } + mock_outputs_allowed_terraform_commands = ["validate", "plan"] +} + +inputs = { + vpc_id = dependency.vpc.outputs.vpc_id + subnet_ids = dependency.vpc.outputs.private_subnet_ids + db_endpoint = dependency.rds.outputs.db_endpoint +} +``` + +## Step 6: run-all Workflow + +```bash +# Plan entire environment (respects dependency order) +terragrunt run-all plan --terragrunt-working-dir infra/dev + +# Apply entire environment +terragrunt run-all apply --terragrunt-working-dir infra/dev + +# Apply only specific units (exclude by dir pattern) +terragrunt run-all apply \ + --terragrunt-working-dir infra/dev \ + --terragrunt-exclude-dir infra/dev/rds + +# Plan a single unit +cd infra/dev/app && terragrunt plan + +# Destroy (destructive — requires explicit confirmation) +terragrunt run-all destroy --terragrunt-working-dir infra/dev +``` + +`run-all` automatically determines dependency order from `dependency` blocks +and parallelizes independent units. + +## Step 7: DRY with \_envcommon + +Share defaults across environments without duplication: + +```hcl +# infra/_envcommon/rds.hcl +inputs = { + instance_class = "db.t3.medium" + allocated_storage = 20 + storage_encrypted = true + deletion_protection = true +} +``` + +Override per environment using `merge`: + +```hcl +locals { + common = read_terragrunt_config(find_in_parent_folders("_envcommon/rds.hcl")) +} + +inputs = merge(local.common.inputs, { + instance_class = "db.t3.large" # prod override +}) +``` + +## Step 8: CI/CD Integration + +```yaml +# .github/workflows/infra.yml (simplified) +- name: Terragrunt plan + run: | + cd infra/${{ env.ENV }} + terragrunt run-all plan \ + --terragrunt-non-interactive \ + --terragrunt-parallelism 4 \ + -no-color 2>&1 | tee plan.log + +- name: Terragrunt apply + if: github.ref == 'refs/heads/main' + run: | + cd infra/${{ env.ENV }} + terragrunt run-all apply \ + --terragrunt-non-interactive \ + --auto-approve \ + -no-color +``` + +Use `--terragrunt-non-interactive` in CI to prevent hanging on prompts. + +## Review Checklist + +- [ ] Root `terragrunt.hcl` generates `backend.tf` and `provider.tf` — no hand-written copies in units +- [ ] State key uses `path_relative_to_include()` for automatic per-unit naming +- [ ] S3 state bucket: encryption enabled, versioning enabled, public access blocked +- [ ] Module sources pinned to a specific git ref or semver tag — never `?ref=main` +- [ ] `dependency` blocks have `mock_outputs` for `plan` and `validate` +- [ ] Shared inputs extracted to `_envcommon/` — no copy-paste across environments +- [ ] Secrets supplied via environment variables or a secrets manager data source +- [ ] `--terragrunt-non-interactive` used in all CI/CD invocations +- [ ] `.terragrunt-cache/` in `.gitignore` + +## References + +> Always use the official documentation for the Terragrunt version in use — built-in functions, flags, and configuration options evolve with each release. + +- [Terragrunt documentation](https://terragrunt.gruntwork.io/docs/) +- [Terragrunt CLI reference](https://terragrunt.gruntwork.io/docs/reference/cli-options/) +- [Gruntwork module registry](https://www.gruntwork.io/) + +<!-- AUTO-GENERATED — maintained by vstack, do not edit directly --> +<!-- VSTACK-META: {"artifact_name":"terragrunt","artifact_type":"skill","artifact_version":"20260502031","generator":"vstack","vstack_version":"0.0.0.post3.dev0+df3fe6e"} --> diff --git a/.github/skills/threat-model/SKILL.md b/.github/skills/threat-model/SKILL.md new file mode 100644 index 0000000..19eb60b --- /dev/null +++ b/.github/skills/threat-model/SKILL.md @@ -0,0 +1,247 @@ +--- +name: threat-model +description: 'Threat modeling for APIs, services, and systems using a practical STRIDE-first approach with optional DREAD prioritization and PASTA depth for high-criticality contexts. Produces actionable threat scenarios, mitigations, and risk priorities. Use when asked to "threat model", "analyze attack paths", "STRIDE review", or "prioritize security design risks".' +license: 'MIT' +compatibility: 'Requires a skills-compatible agent with repository file access and terminal command execution when needed.' +metadata: + owner: vstack + maturity: stable +argument-hint: '[system, component, or architecture to threat model]' +user-invocable: true +disable-model-invocation: false +--- +## Skill Context + +This skill is part of **vstack** — a VS Code-native AI engineering workflow system. + +### AskUserQuestion Format + +When you need clarification, use this exact format — never invent or guess: + +> **Question:** [The specific question] +> **Options:** A) … | B) … | C) … +> **Default if no response:** [What you'll do] + +Never ask more than one question at a time without waiting for the answer. + +### Diagram Convention + +When producing hand-authored Markdown outputs, prefer Mermaid for flow, +interaction, lifecycle, state, topology, dependency, and decision diagrams when +the format is supported and improves clarity. Use ASCII as a fallback when +Mermaid is unsupported or would be less readable. Keep ASCII/text trees for +directory structures and other scan-friendly hierarchies. + +```bash +# Detect base branch (main / master / develop / trunk) +BASE=$(gh pr view --json baseRefName -q .baseRefName 2>/dev/null) \ + || BASE=$(git remote show origin 2>/dev/null | grep 'HEAD branch' | awk '{print $NF}') \ + || BASE=$(git branch -r 2>/dev/null | grep -E '/(main|master|develop|trunk)' | head -1 | sed 's|.*origin/||') \ + || BASE="main" +echo "Base branch: $BASE" +``` + +# threat-model — Threat Modeling (STRIDE-first, DREAD/PASTA-aware) + +Identify design-time security risks before implementation and turn them into +actionable mitigations. + +This skill uses a practical framework selection model: + +- **STRIDE** for systematic threat identification (default) +- **DREAD** for threat prioritization (optional but recommended) +- **PASTA** depth for high-criticality systems when business-risk alignment is required + +## Out of scope + +- Full OWASP vulnerability audit of existing code (use `security`) +- Fix implementation and patching work (engineering role) +- Incident post-mortem analysis (use `incident`) +- Generic architecture review without threat analysis focus (use `architecture`) + +## Deliverable and artifact policy + +- Primary deliverable: `docs/architecture/threat-model.md` +- Baseline-first default: write final threat model directly to `docs/architecture/threat-model.md` on the feature branch. +- Optional WIP area for complex/uncertain efforts: `docs/delta/{id}/THREAT_MODEL_DELTA.md` +- Before merge: consolidate delta notes into the baseline threat model. + +## Framework selection guide + +Use this decision table to choose depth and method: + +| Need | Preferred framework | +| ------------------------------------------------ | ----------------------------------------- | +| Identify threats quickly during design | STRIDE | +| Rank many discovered threats for remediation | STRIDE + DREAD | +| Model business-aligned risk for critical systems | PASTA (optionally with STRIDE categories) | + +Default path for most teams: **STRIDE + DREAD**. + +## Step 0: Define model scope and trust boundaries + +Document what is in and out of scope: + +```text +System: [service/subsystem/repo scope] +System style: [backend-only|frontend-only|fullstack|platform|integration] +Critical assets: [PII, credentials, payment data, business operations] +Actors: [users, admins, services, third parties] +Trust boundaries:[internet edge, auth boundary, network segment, tenant boundary] +Assumptions: [known constraints] +Out of scope: [explicit exclusions] +``` + +Collect architecture evidence first: + +```bash +find docs -maxdepth 3 -type f \ + \( -name 'architecture.md' -o -name 'design.md' -o -name 'requirements.md' -o -name 'openapi*.yaml' -o -name '*.proto' \) \ + 2>/dev/null | sort +``` + +If there is no architecture or design context, stop and request it before continuing. + +## Step 1: Build a lightweight system model + +Create a concise component and data-flow view before threat enumeration. + +Minimum required model: + +1. External entities (users, services, vendors) +1. Internal components/services +1. Data stores +1. Data flows crossing trust boundaries +1. Identity and authorization boundaries + +Use Mermaid when possible: + +```mermaid +flowchart LR + U[User] --> API[Public API] + API --> SVC[Service] + SVC --> DB[(Database)] + SVC --> EXT[Third-party API] +``` + +## Step 2: Identify threats with STRIDE + +For each component and data flow, enumerate threats by category. + +| STRIDE category | Core question | Typical controls | +| ---------------------- | ------------------------------------------------- | --------------------------------------------- | +| Spoofing | Can an attacker impersonate an identity? | Strong auth, token validation, mTLS | +| Tampering | Can data/state be modified without authorization? | Integrity checks, signatures, immutable logs | +| Repudiation | Could actions be denied without evidence? | Audit trails, non-repudiation logs | +| Information Disclosure | Could sensitive data leak? | Access control, encryption, data minimization | +| Denial of Service | Can availability be degraded or exhausted? | Rate limits, quotas, circuit breakers | +| Elevation of Privilege | Can lower privilege gain higher access? | Least privilege, authorization hardening | + +Threat entry format: + +```text +ID: TM-<component>-<n> +Category: [STRIDE] +Asset: [what is at risk] +Attack path: [how the threat is realized] +Preconditions: [what attacker needs] +Current controls: [what already exists] +Control gaps: [what is missing] +Proposed mitigations: [specific, testable controls] +``` + +## Step 3: Prioritize with DREAD (optional but recommended) + +If you have more than a few threats, score each threat: + +- **Damage** +- **Reproducibility** +- **Exploitability** +- **Affected Users** +- **Discoverability** + +Use a 1-10 scale and compute the average. + +| ID | D | R | E | A | Dv | Score | Priority | +| --------- | --- | --- | --- | --- | --- | ----- | -------- | +| TM-auth-1 | 9 | 8 | 8 | 9 | 7 | 8.2 | P1 | + +Prioritization note: keep scoring criteria explicit and tie final priority to +business and operational context, not score alone. + +## Step 4: Use PASTA depth when context demands it + +Use PASTA selectively when one or more conditions apply: + +- System is mission-critical or highly regulated +- Executive/compliance risk reporting requires business traceability +- Threat model must include attack simulation beyond checklist-level analysis + +PASTA-aligned expansion (compact): + +1. Define business and security objectives. +1. Confirm technical scope and decomposition. +1. Extend threat analysis with vulnerability and attack simulation depth. +1. Translate findings into business-impact risk prioritization. + +If PASTA depth is out of scope due to time or maturity constraints, document that +explicitly and continue with STRIDE + DREAD. + +## Step 5: Produce mitigation plan and security requirements + +Convert prioritized threats into implementation-ready controls: + +1. Preventive controls (before exploitation) +1. Detective controls (signal and alert) +1. Response controls (contain and recover) +1. Verification controls (tests/checks proving control effectiveness) + +For each high-priority threat include: + +- Owner (role/team) +- Expected artifact change (architecture, design, code, tests, runbook) +- Deadline/sprint target +- Verification method (test, scan, review, chaos/failure drill) + +## Threat model report template + +```markdown +# Threat Model — [System] — [Date] + +## Scope and Context +- System and boundaries +- Critical assets +- Assumptions and exclusions + +## Architecture and Data Flow +[diagram + concise narrative] + +## STRIDE Threat Inventory +| ID | Component/Flow | Category | Threat | Current Controls | Gaps | Mitigation | + +## DREAD Prioritization (if used) +| ID | Damage | Reproducibility | Exploitability | Affected Users | Discoverability | Score | Priority | + +## PASTA Expansion (if used) +[business objectives, attack simulation summary, business-impact alignment] + +## Priority Mitigation Plan +| Priority | Threat ID | Control | Owner | Verification | Target | + +## Residual Risk and Decisions +- accepted risks +- escalations needed +- decisions requiring ADR or product sign-off +``` + +## Completion checklist + +- Scope, trust boundaries, and critical assets are explicit. +- STRIDE inventory covers all major components and critical flows. +- DREAD prioritization is included when threat volume requires ranking. +- PASTA depth is either applied with rationale or explicitly deferred. +- Mitigations are actionable, owned, and verifiable. +- Final report is written to `docs/architecture/threat-model.md`. + +<!-- AUTO-GENERATED — maintained by vstack, do not edit directly --> +<!-- VSTACK-META: {"artifact_name":"threat-model","artifact_type":"skill","artifact_version":"20260502021","generator":"vstack","vstack_version":"0.0.0.post3.dev0+df3fe6e"} --> diff --git a/.github/skills/verify/SKILL.md b/.github/skills/verify/SKILL.md index f0707f8..6092ff3 100644 --- a/.github/skills/verify/SKILL.md +++ b/.github/skills/verify/SKILL.md @@ -68,8 +68,6 @@ Use `inspect` for read-only auditing. - Optional WIP area for complex/uncertain efforts: `docs/delta/{id}/VERIFY_DELTA.md` - Before merge: consolidate final findings, severity, and ship-readiness verdict into baseline reports. -______________________________________________________________________ - ## Step 0: Route Mode Classify first, then run one mode. @@ -84,8 +82,6 @@ Classify first, then run one mode. If D, stop and route to `inspect`. -______________________________________________________________________ - ## Step 1: Scope and Safety Parse user scope: @@ -127,8 +123,6 @@ else fi ``` -______________________________________________________________________ - ## Step 2: Baseline Checks (all modes) Run baseline checks for the selected scope. @@ -168,8 +162,6 @@ else fi ``` -______________________________________________________________________ - ## Step 3: Conditional Checks by Mode ### quick @@ -217,8 +209,6 @@ For exhaustive mode, require observability evidence (logs/metrics/traces/alerts) If deep security/performance concerns appear, stop and route to `security` or `performance`. -______________________________________________________________________ - ## Step 4: Triage Classify findings: @@ -236,8 +226,6 @@ Fix policy: - standard: critical + high + medium - exhaustive: all severities -______________________________________________________________________ - ## Step 5: Fix and Re-verify Loop For each fixable issue in severity order: @@ -250,8 +238,6 @@ For each fixable issue in severity order: If an issue implies architecture or design mismatch, stop and escalate. -______________________________________________________________________ - ## Step 6: Final Report ```text @@ -279,7 +265,5 @@ scope: [path/component/full] [READY TO SHIP | NEEDS FIXES | BLOCKED] ``` -______________________________________________________________________ - <!-- AUTO-GENERATED — maintained by vstack, do not edit directly --> -<!-- VSTACK-META: {"artifact_name":"verify","artifact_type":"skill","artifact_version":"1.0.2","generator":"vstack","vstack_version":"1.3.0"} --> +<!-- VSTACK-META: {"artifact_name":"verify","artifact_type":"skill","artifact_version":"20260421026","generator":"vstack","vstack_version":"0.0.0.post3.dev0+df3fe6e"} --> diff --git a/.github/skills/vision/SKILL.md b/.github/skills/vision/SKILL.md index c6974e6..e67dc6e 100644 --- a/.github/skills/vision/SKILL.md +++ b/.github/skills/vision/SKILL.md @@ -205,7 +205,5 @@ For each finding: explain the tradeoff, give an opinionated recommendation, ask Present as: "Overall assessment: [READY/NEEDS REVISION/SCOPE CHANGE] because [1-2 sentence reason]." -______________________________________________________________________ - <!-- AUTO-GENERATED — maintained by vstack, do not edit directly --> -<!-- VSTACK-META: {"artifact_name":"vision","artifact_type":"skill","artifact_version":"1.0.2","generator":"vstack","vstack_version":"1.3.0"} --> +<!-- VSTACK-META: {"artifact_name":"vision","artifact_type":"skill","artifact_version":"20260421027","generator":"vstack","vstack_version":"0.0.0.post3.dev0+df3fe6e"} --> diff --git a/.github/vstack.json b/.github/vstack.json index 25339d6..1e6cb55 100644 --- a/.github/vstack.json +++ b/.github/vstack.json @@ -1,197 +1,302 @@ { "manifest_version": 2, "hash_algorithm": "sha256", - "vstack_version": "1.3.6", - "installed_at": "2026-04-25T23:30:58.320097+00:00", + "vstack_version": "0.0.0.post3.dev0+df3fe6e", + "installed_at": "2026-05-02T16:26:18.650080+00:00", "artifacts": { "skills": [ { "name": "adr", "file": "skills/adr/SKILL.md", - "version": "1.0.2", - "checksum": "e28cb928c5a73e740cd6c58bb3b261606a11d4cda9a33abcc5109c208cf98d0e", + "version": "20260421003", + "checksum": "551bc8607dc49d9d92968e0d22568efc6eb5b9b85bed17aeed981f33022a891b", "checksum_algorithm": "sha256" }, { "name": "analyse", "file": "skills/analyse/SKILL.md", - "version": "1.0.2", - "checksum": "c55ffd1bf0601d703e07420e914172008ef5a07b4d76eccd6f070fc8c17785a2", + "version": "20260421004", + "checksum": "8ff12f1d1f12ac9c46a2cb36981b85aeea97a8bc0876bbef37300511ea0eb7b3", "checksum_algorithm": "sha256" }, { "name": "architecture", "file": "skills/architecture/SKILL.md", - "version": "1.0.2", - "checksum": "db0c632cce9fa73fc52cd7e7f6ee78f6184220c62af0089083e8d4fcbce58740", + "version": "20260421005", + "checksum": "1cf90ff73efd2411d5da1434c0273c42f5f77a2e8a1c47f7f877545863b783b3", + "checksum_algorithm": "sha256" + }, + { + "name": "aws-cli", + "file": "skills/aws-cli/SKILL.md", + "version": "20260502033", + "checksum": "e5b2688de029ab0cc6d3e3862237c5bdb7f3ad4aab9baa4e1bceac433d699b79", "checksum_algorithm": "sha256" }, { "name": "cicd", "file": "skills/cicd/SKILL.md", - "version": "1.0.2", - "checksum": "a1860a0d3ca9dc1d1c14b90fce3887f51c536204df58c1fbcc5c972cea13a70a", + "version": "20260421006", + "checksum": "fba15036cec658c33c8a179acfdac52722b8adcf534d9e1b8cc2f3c026b862f5", + "checksum_algorithm": "sha256" + }, + { + "name": "cloudformation", + "file": "skills/cloudformation/SKILL.md", + "version": "20260502032", + "checksum": "d172ffc2b30c75986446a72b625baecae123d1cc3882b20ca803c60b46dcd75d", "checksum_algorithm": "sha256" }, { "name": "code-review", "file": "skills/code-review/SKILL.md", - "version": "1.0.2", - "checksum": "23264675e7f1706d607f39918f4e524ce74d536e5ccd9ccf6b09f0af4f14f305", + "version": "20260421007", + "checksum": "5bcdddc03ce0a54997037210b38e7b4ed22828cfba6a76153afaa94cf616527a", + "checksum_algorithm": "sha256" + }, + { + "name": "codeql", + "file": "skills/codeql/SKILL.md", + "version": "20260502026", + "checksum": "1b1b5800be204cc0e5dc6b4a8fcb9a7b916cfba2f96d5f99dbb6d7e213b8e95c", "checksum_algorithm": "sha256" }, { "name": "concise", "file": "skills/concise/SKILL.md", - "version": "1.0.1", - "checksum": "03a342b8a07ec99da845f6213b8f2573b2cb94d3546366ef45a3c376fa56244c", + "version": "20260421008", + "checksum": "3a07860ba6c83a97c9ad5496e124be4e5277fc0b811fe25dcd5bfdb7d8252b98", "checksum_algorithm": "sha256" }, { "name": "consult", "file": "skills/consult/SKILL.md", - "version": "1.0.2", - "checksum": "a48d3d3df3acad63b9194a5941c37107e6303993898cf7188963a86f699e74d6", + "version": "20260421009", + "checksum": "90e1b0d0ff757c8e5879832c5ac6c41ec4054e9bff5b12a14531d427c09bcbad", "checksum_algorithm": "sha256" }, { "name": "container", "file": "skills/container/SKILL.md", - "version": "1.0.2", - "checksum": "40ed0e2a7bdfc5872bfe59e9fd052e9530bebd2f750c676d043781c3e95f6397", + "version": "20260421010", + "checksum": "e135b18cb972d30b77de4492db0437853ff1f49bad60a9113a034e39154d30e1", + "checksum_algorithm": "sha256" + }, + { + "name": "conventional-commit", + "file": "skills/conventional-commit/SKILL.md", + "version": "20260502024", + "checksum": "76477b42b17c9f6eec92baa36dc172e7ee98b20a86399eabdd2b7d2a90923509", "checksum_algorithm": "sha256" }, { "name": "debug", "file": "skills/debug/SKILL.md", - "version": "1.0.2", - "checksum": "88e8867e722f8024afb919f03dab48a91f3fbaf941b2b9c0878124d17c1887f1", + "version": "20260421011", + "checksum": "8e46a2723004bc86f6aee50f492b73045acdab66c964787c58a988c98684750b", + "checksum_algorithm": "sha256" + }, + { + "name": "dependabot", + "file": "skills/dependabot/SKILL.md", + "version": "20260502027", + "checksum": "3ce5836bf870f73805800f672d379aa10f5aff5a522017a77875d9339bb99984", "checksum_algorithm": "sha256" }, { "name": "dependency", "file": "skills/dependency/SKILL.md", - "version": "1.0.1", - "checksum": "3247b971c399f065178d771d8a0cd0217f317d8223390d4b084385b07167554b", + "version": "20260421012", + "checksum": "46e75e8a28b1af5a60da7d9b3d1e46f0914b2f10d8733b37e6577e62b0074724", "checksum_algorithm": "sha256" }, { "name": "design", "file": "skills/design/SKILL.md", - "version": "1.0.2", - "checksum": "f1ce0992a415831a96aa0a60bae07fcf95bde0fb97fdaf42171860188b765be8", + "version": "20260421013", + "checksum": "a45a862c2d721e015a2b9a7d0d6112982932216b07734af58323784d26cba887", "checksum_algorithm": "sha256" }, { "name": "docs", "file": "skills/docs/SKILL.md", - "version": "1.0.2", - "checksum": "613175ca5d5085496275714c4ef1bbe5304f5a2da7471a147d4f1a0a01fd251d", + "version": "20260421014", + "checksum": "1519e8b95149469f029b8f6c57ec09517e9de09a86ba865cdcb6f746d44dc2f1", "checksum_algorithm": "sha256" }, { "name": "explore", "file": "skills/explore/SKILL.md", - "version": "1.0.2", - "checksum": "a7616442f81eee433d495fcfd8d7ef6e449e6bd8d3970c2fd1b26cc079f888b6", + "version": "20260421015", + "checksum": "a257941d7b577f782b5d41703b1fbd25c5ab13f664e696d83cc3a9fd91a5565f", + "checksum_algorithm": "sha256" + }, + { + "name": "gdpr", + "file": "skills/gdpr/SKILL.md", + "version": "20260502029", + "checksum": "94207650498b56f246392449f57b4af4659bdfe511e7a6c2f23022ff2f68b08d", + "checksum_algorithm": "sha256" + }, + { + "name": "gh-issues", + "file": "skills/gh-issues/SKILL.md", + "version": "20260502025", + "checksum": "36d07b676604a4f698369f8bf6b65b43f5256f676fd56664717ff2007da126f0", + "checksum_algorithm": "sha256" + }, + { + "name": "gh-release", + "file": "skills/gh-release/SKILL.md", + "version": "20260502023", + "checksum": "beed7f98cb52222f688fed5a83d376acea1215c6654c570487412792bb577462", "checksum_algorithm": "sha256" }, { "name": "guardrails", "file": "skills/guardrails/SKILL.md", - "version": "1.0.2", - "checksum": "eddc61632d5557d89c4287c8ce6012ee50061986f1c9073612838a4c0c1d0d24", + "version": "20260421016", + "checksum": "8ec7213e1f8c85b4975ebb032d897e84e372c0279e3265da1098fc86cf98695f", + "checksum_algorithm": "sha256" + }, + { + "name": "helm", + "file": "skills/helm/SKILL.md", + "version": "20260502037", + "checksum": "13600308860723f683802431ac7a8c2c3834c40e521055854cdf3d3290570689", "checksum_algorithm": "sha256" }, { "name": "incident", "file": "skills/incident/SKILL.md", - "version": "1.0.1", - "checksum": "dca316d214b8bfe564b590d98f5f45cea520342741834cf35af904be34517db3", + "version": "20260421017", + "checksum": "7f20cb1592971846391431384e24e193af47a4cbfe6ccef86b11ef074baf0549", "checksum_algorithm": "sha256" }, { "name": "inspect", "file": "skills/inspect/SKILL.md", - "version": "1.0.2", - "checksum": "e8411fe7cc35625b842e3e3671b67fc3c0f63f7d57773e574a7c595d45247730", + "version": "20260421018", + "checksum": "53bcdb75baf11a82ce91e70b102d7fb07f9329b825f566c7c1c5d0531080623b", + "checksum_algorithm": "sha256" + }, + { + "name": "k8s", + "file": "skills/k8s/SKILL.md", + "version": "20260502036", + "checksum": "d178a4d86f6ca5f4144cd8212eaf09979bb48afa55cb482409609aa50c5f0f88", "checksum_algorithm": "sha256" }, { "name": "migrate", "file": "skills/migrate/SKILL.md", - "version": "1.0.1", - "checksum": "f404b74f152dee1b9d03e2ea24e5e2e634269747444ca59c95e0c11103dccdbd", + "version": "20260421019", + "checksum": "c6c18c750319c0feb14526d637cb591f51ffde341b1385b4063aeb1edf12fd8b", "checksum_algorithm": "sha256" }, { "name": "onboard", "file": "skills/onboard/SKILL.md", - "version": "1.0.1", - "checksum": "b9c91b03063bc06f80f08215406ef9fb434e8ab7b355498da19fcd9960d986d7", + "version": "20260421020", + "checksum": "3c817dbdea5404a01c8b81d87196fcef559b65ad184a0044bdcb0b3943de8be1", "checksum_algorithm": "sha256" }, { "name": "openapi", "file": "skills/openapi/SKILL.md", - "version": "1.0.1", - "checksum": "81b9ce9dec89be2b833367913533aa9986426ea6a7be060de4934f9e4ea6ee80", + "version": "20260421021", + "checksum": "75d7cab59b1cde6dc91490867eb8537821059960957ba21ebd24d922e9fe7a91", "checksum_algorithm": "sha256" }, { "name": "performance", "file": "skills/performance/SKILL.md", - "version": "1.0.2", - "checksum": "ee9d440e9957ff6ed95ebe2551f509084e25543e8a3d844c42c607fcdf8beb48", + "version": "20260421022", + "checksum": "6bd122818ff0ad7e4f1d29ed221d6ef33405a697b2a0d82a14dc3d0ea9065b01", "checksum_algorithm": "sha256" }, { "name": "pr", "file": "skills/pr/SKILL.md", - "version": "1.0.2", - "checksum": "e869d692a12e0ce1a42a67795fdab2984fa6c03b83511f41f838043bd8a8a9b9", + "version": "20260502013", + "checksum": "ed4b13b69b325b21d9abf17ae9be34c2b2fa6ff1dd78cc6ee04af73d428438b8", + "checksum_algorithm": "sha256" + }, + { + "name": "rancher", + "file": "skills/rancher/SKILL.md", + "version": "20260502038", + "checksum": "c86759f257553554f2069cb6d0eda93bd98fd5c2fb251b1c8cc423302f33b01d", "checksum_algorithm": "sha256" }, { "name": "refactor", "file": "skills/refactor/SKILL.md", - "version": "1.0.1", - "checksum": "cc07080525bac8a78c226b5ee03c40c3991c440405de7710abf390799c93ea64", + "version": "20260421023", + "checksum": "7559d9148ee0ed7434162f672fe47329a417fd332af92a3637c47030e6b8f271", "checksum_algorithm": "sha256" }, { "name": "release-notes", "file": "skills/release-notes/SKILL.md", - "version": "1.0.2", - "checksum": "4238f3babc26a282c7d1c53829f3fad7620b912e8ced319249bcf86dcfc5a1c9", + "version": "20260502014", + "checksum": "b1148eeaf2c7d9f2041c13bf060dd5404b3c22ea09a6182660c880644207edaa", "checksum_algorithm": "sha256" }, { "name": "requirements", "file": "skills/requirements/SKILL.md", - "version": "1.0.2", - "checksum": "3ad75d993742791bf1914202c5fb58ab8657af7711723e11978e2eb7746a0b72", + "version": "20260421024", + "checksum": "4fa0a00259210b7e200d188cd00b9921c934385520eb21d00fa8361bbe4e6e57", + "checksum_algorithm": "sha256" + }, + { + "name": "secret-scan", + "file": "skills/secret-scan/SKILL.md", + "version": "20260502028", + "checksum": "7a83d376b062bcf497ea89dd1e44a8f9fb945349d6b66513018ce1abe265e277", "checksum_algorithm": "sha256" }, { "name": "security", "file": "skills/security/SKILL.md", - "version": "1.0.2", - "checksum": "63aca73f52bbf8384f79f99a403e1aa91fe4bb4b337d776c17d26c92e3945cc1", + "version": "20260421025", + "checksum": "5bdab8583938f7256889d02853a660d132a37024843b1654394193442fc898be", + "checksum_algorithm": "sha256" + }, + { + "name": "terraform", + "file": "skills/terraform/SKILL.md", + "version": "20260502030", + "checksum": "b24b008c171aafbf81902b3f52661b4acc09e8980e42ebf579ac3566dc138de5", + "checksum_algorithm": "sha256" + }, + { + "name": "terragrunt", + "file": "skills/terragrunt/SKILL.md", + "version": "20260502031", + "checksum": "33a208ccc4dfff01b59110445e0fd851e5c9d5e094711456c1cd1efdc68d440d", + "checksum_algorithm": "sha256" + }, + { + "name": "threat-model", + "file": "skills/threat-model/SKILL.md", + "version": "20260502021", + "checksum": "1e3d42f73f1c3deb3589cd433d57dc9f689c5b53892865d091170c9d5155b319", "checksum_algorithm": "sha256" }, { "name": "verify", "file": "skills/verify/SKILL.md", - "version": "1.0.2", - "checksum": "be0e4fed0240219fcffbc91fe84ff0f4e6585a5d522aa86377492c66933c4d7b", + "version": "20260421026", + "checksum": "8c391cbade20645aba1af062020990724078f34036707de51cacb726a8875ad8", "checksum_algorithm": "sha256" }, { "name": "vision", "file": "skills/vision/SKILL.md", - "version": "1.0.2", - "checksum": "c22f27f14839a561b56d61c75515b2636b7d9842052065ca6b9c7b06bde797bb", + "version": "20260421027", + "checksum": "5f961984068b88b6f6a819ffc33f8f08fe2d6e42f4f6c16a2f4c24d0342dae48", "checksum_algorithm": "sha256" } ], @@ -199,43 +304,43 @@ { "name": "architect", "file": "agents/architect.agent.md", - "version": "1.0.1", - "checksum": "85b1c6fbfe890aa2bc2f3bfde80c5e98db2a4380a9e1ea6b65c57051807de781", + "version": "20260502015", + "checksum": "2fad8dc4129453a8cb382b52267f967d339befd8d51cb059d6146cd9c346448f", "checksum_algorithm": "sha256" }, { "name": "designer", "file": "agents/designer.agent.md", - "version": "1.0.1", - "checksum": "e3f86d1811d2d668df9fb06cb0cbb61d56f5a1e669affbf53df898120ad02559", + "version": "20260502016", + "checksum": "fd3ded2f4889c36d40f9f782f78a05efe8ae8440b3ee1e933c13fdf7457a7454", "checksum_algorithm": "sha256" }, { "name": "engineer", "file": "agents/engineer.agent.md", - "version": "1.0.1", - "checksum": "6c5f60d6aa844c9bf6c61feae464e25dc1ba8decc5d69915f21ab0eb24553e1f", + "version": "20260502017", + "checksum": "82fb449131d97a74c907374d10b57ad33c1a770c0ff42083323b7bea05cafe7f", "checksum_algorithm": "sha256" }, { "name": "product", "file": "agents/product.agent.md", - "version": "1.0.1", - "checksum": "8a25f81f2b8f2fbebf6a2dc5460b4ed67baace8ae56efae21870eba33e664732", + "version": "20260502018", + "checksum": "9311a59e88726f1cb1afe464624cd5a3bc34e0a5e64bdb3c78b75d5c479ed57f", "checksum_algorithm": "sha256" }, { "name": "release", "file": "agents/release.agent.md", - "version": "1.0.1", - "checksum": "fbe8b50739ebc364cae4af55575ab08cb327f1ccef66c16ae7b8b3676bd606f2", + "version": "20260502019", + "checksum": "68c8bc0748872d5f426a3bb8c12b6438c9070f3a4d5003103b59bea4f9fd9d4f", "checksum_algorithm": "sha256" }, { "name": "tester", "file": "agents/tester.agent.md", - "version": "1.0.1", - "checksum": "68892b8b9f24ab509f567ccc47c8b8a1a4ff30c21ab5c73d074d509c538e5ca6", + "version": "20260502020", + "checksum": "877eb94928d123c8b4834f6f8baa08fa23c95a8aa989d2f3f21673468eddbe42", "checksum_algorithm": "sha256" } ], @@ -243,24 +348,136 @@ { "name": "git", "file": "instructions/git.instructions.md", - "version": "0.1.0", - "checksum": "6bc1c23d9e7eb12f37a11e83e57bd40ccf1e5cc02c51c1e764809f813193eed8", + "version": "20260421001", + "checksum": "ed6a191176e32631e2d572cb21278b555f6696a859839579821631156a8b35a5", + "checksum_algorithm": "sha256" + }, + { + "name": "helm", + "file": "instructions/helm.instructions.md", + "version": "20260502040", + "checksum": "a60520853b79751517f089136ba7fb182feb1ea8e9c9495890e5c14ff32afd7b", + "checksum_algorithm": "sha256" + }, + { + "name": "java", + "file": "instructions/java.instructions.md", + "version": "20260502001", + "checksum": "69dc2bf3a5428ed03d77c2789871985ea7c5881af89c2b414548fca6e9488464", + "checksum_algorithm": "sha256" + }, + { + "name": "k8s", + "file": "instructions/k8s.instructions.md", + "version": "20260502039", + "checksum": "f19f1060bf2a1424950496290a43a3535f9749e4ed838cf7475fe35eb9487d67", + "checksum_algorithm": "sha256" + }, + { + "name": "markdown", + "file": "instructions/markdown.instructions.md", + "version": "20260502002", + "checksum": "59c93c5b0e63360aff18ab3a7a207f4e798efd1f2c26b0a561a4ef4ea688c5c5", "checksum_algorithm": "sha256" }, { "name": "python", "file": "instructions/python.instructions.md", - "version": "0.1.1", - "checksum": "d01fc76c80f736738e0eb0e38224b6e0e6bdb579dc9bafd74482573d3b39d913", + "version": "20260421002", + "checksum": "ac40fffd3d3a3f9f8ca43e10ca603a187578c9d517533529a3d647b61cedf56c", + "checksum_algorithm": "sha256" + }, + { + "name": "rancher", + "file": "instructions/rancher.instructions.md", + "version": "20260502041", + "checksum": "4e643b1e078e9e8f127f1f2cf7707b36109e28b8697e208d8d3804848b867eec", + "checksum_algorithm": "sha256" + }, + { + "name": "security", + "file": "instructions/security.instructions.md", + "version": "20260502003", + "checksum": "a943df637e44cb23c8e82f8b39bf70558bc502ece5af9a03a15d8492cffb51a4", + "checksum_algorithm": "sha256" + }, + { + "name": "terraform", + "file": "instructions/terraform.instructions.md", + "version": "20260502034", + "checksum": "1bada82da46a6359bb1814b6642074be6c0b7de9c2c6ca59e031a4d05ea4ea8c", + "checksum_algorithm": "sha256" + }, + { + "name": "terragrunt", + "file": "instructions/terragrunt.instructions.md", + "version": "20260502035", + "checksum": "13c0059c366624ab482c2b3d24a353bcb0a2ffbb6bf735abd18796969a3e4020", + "checksum_algorithm": "sha256" + }, + { + "name": "testing", + "file": "instructions/testing.instructions.md", + "version": "20260502004", + "checksum": "cbd1948f367c32c39032209e5ed9fcfff8ce6c46c6324a4aa9a8550365873ca3", + "checksum_algorithm": "sha256" + }, + { + "name": "typescript", + "file": "instructions/typescript.instructions.md", + "version": "20260502005", + "checksum": "fe412ba2e60baea66d0d07ae0c153fa2a9157bd57556fa7476f46ce466160ad3", "checksum_algorithm": "sha256" } ], "prompts": [ + { + "name": "api-design-review", + "file": "prompts/api-design-review.prompt.md", + "version": "20260502006", + "checksum": "1ba62a6f78b836256fe578c4ca312de24599c79b018119b81a100f6de4e0da11", + "checksum_algorithm": "sha256" + }, + { + "name": "architecture-risk", + "file": "prompts/architecture-risk.prompt.md", + "version": "20260502007", + "checksum": "14fa36e36948309827c1c1296ff2c8b1f1306cfb19057ef190a5e60f6cc04a61", + "checksum_algorithm": "sha256" + }, { "name": "code-review", "file": "prompts/code-review.prompt.md", - "version": "0.1.0", - "checksum": "36e267c1aaf6dbac0774fa9056291454fd66fbf11b5bf84e2def168f42227538", + "version": "20260502008", + "checksum": "b6499ca66706a08ced7b9bf69bd288c2fecb684e1c85e333ee91d36ba7e66c3f", + "checksum_algorithm": "sha256" + }, + { + "name": "dependency-audit", + "file": "prompts/dependency-audit.prompt.md", + "version": "20260502009", + "checksum": "51cead168dbbe52b455813cc620a8426ec287ceb2994831aa6ae115b4e49d0b0", + "checksum_algorithm": "sha256" + }, + { + "name": "incident-timeline", + "file": "prompts/incident-timeline.prompt.md", + "version": "20260502010", + "checksum": "28627dc7c362d510f312281fe0bda30e1927998bae440808af3a92d06c455393", + "checksum_algorithm": "sha256" + }, + { + "name": "migration-safety", + "file": "prompts/migration-safety.prompt.md", + "version": "20260502011", + "checksum": "814258882774ff98724b14caa0bc9ee35dc68f46e72e62b24884052e79ffacfa", + "checksum_algorithm": "sha256" + }, + { + "name": "release-readiness", + "file": "prompts/release-readiness.prompt.md", + "version": "20260502012", + "checksum": "49898a07169504acba1c2195abf730be77d1e17298cb4676f3ed926a27e31dc6", "checksum_algorithm": "sha256" } ] diff --git a/.release-please-config.json b/.release-please-config.json index 9832f73..aa415f3 100644 --- a/.release-please-config.json +++ b/.release-please-config.json @@ -54,6 +54,14 @@ { "type": "revert", "section": "Maintenance" + }, + { + "type": "test", + "section": "Tests" + }, + { + "type": "tests", + "section": "Tests" } ] } diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a2811a1..5ee85a7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -70,6 +70,7 @@ type(optional-scope)!: short summary - `major`: any commit with `!` in the header or a `BREAKING CHANGE:` footer. - `minor`: `feat`, `feature`. - `patch`: `fix`, `bugfix`, `hotfix`, `opt`, `patch`, `perf`, `refactor`, `chore`, `revert`. +- `no bump`: `docs`, `test`, `tests` (appear in changelog but do not trigger a version increment). ### 3) Allowed types @@ -82,6 +83,7 @@ type(optional-scope)!: short summary - `refactor`: structural cleanup without intended behavior change. - `chore`: repository maintenance and non-feature housekeeping. - `revert`: rollback of a previous commit. +- `test`, `tests`: test-only changes with no production behavior change. ### 4) Suggested scopes (optional) diff --git a/README-pypi.md b/README-pypi.md index 74dcf4e..3f11a38 100644 --- a/README-pypi.md +++ b/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: diff --git a/README.md b/README.md index 18591d7..c293d44 100644 --- a/README.md +++ b/README.md @@ -546,6 +546,27 @@ ______________________________________________________________________ | 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/`. Use them when you want a focused, +structured output for a specific task without a full agent session. + +**How to invoke:** + +- **Command palette:** `Chat: Run Prompt File` → select the prompt by name. +- **Copilot Chat attach button:** click the paperclip icon → select "Prompt Files". +- Some prompts accept an argument — pass it as the first message after selecting the prompt. + +| Prompt | Purpose | Agent | Argument | +| ------------------- | --------------------------------------------------------- | ------------ | ------------------------------------------------ | +| `api-design-review` | Review an API design or OpenAPI spec for correctness | `@designer` | OpenAPI spec file, design doc, or endpoint scope | +| `architecture-risk` | Identify architectural risks and mitigation priorities | `@architect` | design doc, ADR, or architecture scope | +| `code-review` | Review a change for bugs, regressions, and missing tests | `@engineer` | scope or files to review | +| `dependency-audit` | Audit dependencies for vulnerabilities and licence risks | `@tester` | dependency manifest, lockfile, or package scope | +| `incident-timeline` | Build an evidence-based incident timeline and post-mortem | `@tester` | logs, alerts, timeline notes, or incident ID | +| `migration-safety` | Review DB migration safety, rollback, and zero-downtime | `@engineer` | migration files, schema, or rollout plan | +| `release-readiness` | Evaluate release readiness from reports and open blockers | `@release` | scope, release date, or branch | + Boundary rule: - Policies belong in instructions. @@ -676,6 +697,7 @@ files in `.github/`. vim src/vstack/_templates/skills/verify/template.md vim src/vstack/_templates/agents/engineer/template.md vim src/vstack/_templates/instructions/python/template.md +vim src/vstack/_templates/instructions/typescript/template.md poetry run vstack validate poetry run pytest poetry run vstack install diff --git a/cchk.toml b/cchk.toml index 0703b69..5fdfc4b 100644 --- a/cchk.toml +++ b/cchk.toml @@ -16,6 +16,8 @@ allow_commit_types = [ "refactor", "chore", "revert", + "test", + "tests", ] allow_merge_commits = true allow_revert_commits = true diff --git a/docs/architecture/adr/014-manifest-schema-versioning.md b/docs/architecture/adr/014-manifest-schema-versioning.md index 3b37b97..5ed7d98 100644 --- a/docs/architecture/adr/014-manifest-schema-versioning.md +++ b/docs/architecture/adr/014-manifest-schema-versioning.md @@ -33,6 +33,11 @@ pointing to `vstack manifest upgrade`. The upgrade is never automatic. `vstack manifest upgrade --target DIR` explicitly migrates the manifest to the current schema and is the only path that changes the version field. +For per-artifact entries (`artifacts.*[].version`), vstack stores the template +revision token supplied by the template config. This value is treated as an +ordering token, not semantic versioning. Current template policy uses +`YYYYMMDDNNN`. + ## alternatives considered ### Option A: Transparent auto-upgrade on every read diff --git a/docs/architecture/adr/018-skill-genericity-boundary.md b/docs/architecture/adr/018-skill-genericity-boundary.md new file mode 100644 index 0000000..216fe34 --- /dev/null +++ b/docs/architecture/adr/018-skill-genericity-boundary.md @@ -0,0 +1,100 @@ +# ADR-018: Skill Genericity — Skills are Procedures, Agents own Workflow Context + +> Maintained by: **architect** role + +**date:** 2026-05-02\ +**status:** accepted + +## context + +Several vstack skills currently contain project-specific artifact paths and workflow +sequencing that belongs to the agent layer, not the skill layer. + +Examples observed: + +- `release-notes` references `docs/releases/{date}.md`, `docs/test-report.md`, + `docs/security-report.md` as required inputs. +- `pr` references `docs/releases/{date}.md` as the PR body source and enforces + a vstack-specific release checklist. + +These references make the skills correct for vstack's own workflow but incorrect +as general-purpose procedures. A consumer repo with a different documentation +structure cannot use these skills without modification. + +This contradicts the install model: skills are installed as reusable procedures +into any repository, not just vstack-structured ones. + +ADR-013 established the policy vs procedure boundary for instructions and skills. +This ADR extends that boundary to the skill vs agent layer. + +## decision + +**Skills are generic procedures. Agents own workflow context.** + +### the boundary + +| Layer | Contains | Does not contain | +| ----- | --------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | +| Skill | How to perform a task: steps, checks, output format, quality criteria | Which files to read/write, artifact paths, role sequencing, project-specific gates | +| Agent | When to invoke a skill, which artifacts to pass as context, what output files to write, stop conditions, gate moments | How to perform the task itself | + +### rules + +1. A skill must not reference named project artifact paths (e.g. `docs/releases/`, + `docs/test-report.md`). These belong in the agent template. +1. A skill must not enforce a role-sequencing gate (e.g. "verify tester sign-off before + proceeding"). Gates belong in the agent template. +1. A skill may reference generic placeholders (e.g. `{release-notes-file}`, + `{change-summary}`) that the invoking agent resolves. +1. An agent template must declare which artifacts it reads and writes, and may + reference skills by name to execute specific procedures. +1. The artifact hand-off table in ADR-010 remains authoritative for which role reads + and writes which files. + +### immediate changes + +| Skill | Current violation | Fix | +| --------------- | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | +| `pr` | Hardcodes `docs/releases/{date}.md` as PR body source; enforces vstack release checklist | Remove artifact paths; describe generic PR creation procedure | +| `release-notes` | Hardcodes required input artifact paths and checklist | Remove specific paths; describe generic release note writing procedure | + +The removed workflow context moves to the `release` agent template, which already +owns the artifact hand-off contract per ADR-010. + +## alternatives considered + +1. **Keep skills workflow-specific, document the coupling** — rejected: breaks reusability + for consumers with different documentation structures. Skills are installed into any repo. + +1. **Remove skills entirely and inline everything in agents** — rejected: skills provide + reusable, named procedures that can be invoked directly or referenced across agents. + Removing them collapses the separation of concerns. + +1. **Use a templating mechanism to inject artifact paths at install time** — considered: + would allow per-consumer customisation. Not adopted now because it adds generator + complexity. Revisit if consumer customisation becomes a first-class requirement + (see Option B pipeline roadmap item). + +## rationale + +The install model assumes skills are drop-in procedures for any repository. Coupling them +to vstack's internal artifact layout creates an implicit dependency that is invisible to +consumers and breaks the design intent. + +Agents are already the correct place for workflow-specific context: they declare their +scope, artifact contracts, and gate moments. Moving project-specific paths there makes the +coupling explicit, inspectable, and maintainable in one place. + +## impact on Option B pipeline + +In Option B, each pipeline stage has declared input and output artifacts. This decision +aligns the current Option A model with that design: agents declare artifact contracts, +skills are stateless procedures. When Option B is implemented, the agent artifact +declarations become the pipeline stage contracts without requiring skill changes. + +## references + +- [ADR-009: Role model](009-role-model.md) +- [ADR-010: Artifact hand-off pipeline](010-artifact-flow.md) +- [ADR-013: Policy vs procedure boundary](013-instructions-vs-skills-boundary.md) +- [ADR-004: Option A to B pipeline](004-option-a-to-b-pipeline.md) diff --git a/docs/design/design.md b/docs/design/design.md index e03516f..d6f157a 100644 --- a/docs/design/design.md +++ b/docs/design/design.md @@ -95,13 +95,13 @@ Top-level field contracts: Per-artifact entry (`ArtifactEntry`) field contracts: -| Field | Type | Required | Notes | -| -------------------- | ------ | -------- | ----------------------------------------------------------------------- | -| `name` | string | yes | Canonical artifact name | -| `file` | string | yes | Relative file path under install root (for example `skills/x/SKILL.md`) | -| `version` | string | no | May be absent on legacy entries | -| `checksum` | string | no | May be absent on legacy entries | -| `checksum_algorithm` | string | no | May be absent on legacy entries | +| Field | Type | Required | Notes | +| -------------------- | ------ | -------- | ---------------------------------------------------------------------------------------- | +| `name` | string | yes | Canonical artifact name | +| `file` | string | yes | Relative file path under install root (for example `skills/x/SKILL.md`) | +| `version` | string | no | Template revision token (current policy: `YYYYMMDDNNN`); may be absent on legacy entries | +| `checksum` | string | no | May be absent on legacy entries | +| `checksum_algorithm` | string | no | May be absent on legacy entries | ### 1.3 manifest version gate diff --git a/docs/design/instructions.md b/docs/design/instructions.md index a3a8783..5d37bb4 100644 --- a/docs/design/instructions.md +++ b/docs/design/instructions.md @@ -1,7 +1,7 @@ # vstack — instructions > Maintained by: **designer** role\ -> Last updated: 2026-04-20 +> Last updated: 2026-05-02\\ ## what are instructions? @@ -67,6 +67,25 @@ Regenerate with `python3 -m vstack install` after template changes. ______________________________________________________________________ +## available instructions + +| Name | Scope (`applyTo`) | Purpose | +| ------------ | ----------------------------------------------- | ---------------------------------------------------------------------------- | +| `git` | `**/*` | Branch naming, commit conventions, SemVer, safe operations | +| `helm` | `**/charts/**/*.{yaml,yml,tpl}` | Helm chart conventions: structure, templating, values, release safety | +| `java` | `**/*.java` | Java coding conventions, null safety, exception handling | +| `k8s` | `**/{k8s,kubernetes,manifests}/**/*.{yaml,yml}` | Kubernetes manifest conventions: API stability, probes, RBAC, rollout safety | +| `markdown` | `**/*.md` | Markdown authoring conventions for prose and docs | +| `python` | `**/*.py` | Python coding conventions, typing, imports, tooling | +| `rancher` | `**/{rancher,fleet}/**/*.{yaml,yml}` | Rancher/Fleet conventions: scope control, GitOps hygiene, RBAC, operations | +| `security` | `**/*` | Security policy: secrets, input validation, authz, dependencies | +| `terraform` | `**/*.tf` | Terraform naming, pinning, state, variables, tagging, security | +| `terragrunt` | `**/terragrunt.hcl` | Terragrunt structure, remote state, provider generation, DRY | +| `testing` | `**/*` | Test authoring conventions for any language | +| `typescript` | `**/*.{ts,tsx,js,jsx,mts,cts,mjs,cjs}` | TypeScript/JavaScript coding conventions, type safety | + +______________________________________________________________________ + ## minimum instruction contract Each instruction should include: diff --git a/docs/design/skills.md b/docs/design/skills.md index 0ad2777..359af0e 100644 --- a/docs/design/skills.md +++ b/docs/design/skills.md @@ -1,7 +1,7 @@ # vstack — skills > Maintained by: **designer** role\ -> Last updated: 2026-04-16\ +> Last updated: 2026-05-02\ > VS Code docs: [agent skills](https://code.visualstudio.com/docs/copilot/customization/agent-skills) ## what are skills? @@ -45,35 +45,50 @@ ______________________________________________________________________ ## current skills -| Skill | Description | Primary role(s) | Output artifact | -| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | ------------------------------------------- | -| `vision` | CEO/founder-mode plan review. Rethink from first principles, validate ambition, find the 10x solution. | product | `docs/product/vision.md` | -| `requirements` | Collaborative requirements gathering. Clarifies what must be built, defines success criteria and NFRs. | product | `docs/product/requirements.md` | -| `architecture` | Engineering-lead plan review. Lock in service boundaries, data models, API contracts, test strategy. | architect | `docs/architecture/architecture.md` | -| `adr` | Architecture Decision Record writing. Documents a decision with context, alternatives, and rationale. | architect | `docs/architecture/adr/NNN-*.md` | -| `design` | Build a complete API or service design from scratch. Produces OpenAPI specs, error conventions, naming standards. | designer | `docs/design/design.md` / `openapi.yaml` | -| `consult` | DX triage and focused review. Routes to one path (API DX, CLI/tool DX, or developer workflow DX) and routes non-DX requests to specialized skills. | designer | focused DX report or routing recommendation | -| `concise` | Runtime response-style controller. Switches response density (`normal`, `compact`, `ultra`) and reports active mode via `status` without reinstall. | all roles | session style state + status output | -| `code-review` | Pre-landing code review. Finds bugs that pass CI but break in production — race conditions, security issues, performance landmines. | engineer | inline findings | -| `security` | OWASP Top 10 + STRIDE security audit. Finds auth bypasses, injection flaws, exposed secrets, broken access control. | tester | security audit report | -| `explore` | Repository and system discovery. Maps the architecture, identifies tech debt, produces an onboarding summary. | engineer | codebase map | -| `analyse` | Cross-cutting technical analysis. Investigates impact, tradeoffs, root causes, or feasibility without implementing changes. | engineer, architect | analysis report | -| `debug` | Systematic root-cause debugging. Follows scientific method: observe → hypothesise → test → conclude → fix → prevent. | engineer | root cause report + fix | -| `inspect` | Read-only verification audit. Runs baseline plus optional extended checks and produces severity-ranked findings, with no code or commit changes. | tester | read-only audit report | -| `performance` | Performance profiling and regression detection. Establishes baselines, detects regressions, profiles bottlenecks. | engineer, tester | perf report | -| `verify` | Verification fix-loop with mode routing (quick/standard/exhaustive). Runs targeted checks, fixes by severity, and re-verifies impacted paths. | engineer, tester | fixes + verification report | -| `cicd` | Write GitHub Actions CI/CD workflow configuration. Covers build, test, lint, security scan, container publish, deploy. | release | GitHub Actions workflow | -| `container` | Write and review Dockerfile, docker-compose, and container config. Covers multi-stage builds, non-root users, layer optimisation. | engineer | Dockerfile + compose | -| `release-notes` | Prepare release artifacts: write release notes, own CHANGELOG updates, produce `docs/releases/{date}.md`. | release | CHANGELOG + release doc | -| `pr` | Commit, push, and open a pull request from the current branch to main. | release | commit + PR | -| `docs` | Post-release documentation alignment for README/API docs/migrations and related artifacts (no CHANGELOG ownership). | product, architect, designer, engineer, tester, release | updated docs artifacts | -| `guardrails` | Activate safety guardrails for the session. Requires explicit confirmation before any destructive action. | — | (mode activation) | -| `migrate` | Database migration review and authoring. Forwards/backwards compatibility, zero-downtime strategies, rollback plans, data integrity, index safety. | engineer, tester | reviewed/corrected migration SQL | -| `openapi` | Write and review OpenAPI 3.1 specifications. Resource naming, HTTP semantics, status codes, error conventions, pagination, security schemes. | designer, engineer | `openapi.yaml` | -| `refactor` | Structured refactoring without behavior change. Identify smells, plan incremental steps, execute, verify correctness. | engineer | refactored code + green tests | -| `onboard` | Generate a contributor onboarding guide. Prerequisites, setup, tests, env vars, architecture overview, good first issues. | product | `CONTRIBUTING.md` + README dev section | -| `dependency` | Dependency health audit. Vulnerability scanning, outdated packages, licence compliance, transitive risk, pinning policy, supply chain hygiene. | engineer, tester | dependency audit report | -| `incident` | Incident analysis and blameless post-mortem writing. Timeline reconstruction, 5-Whys root cause, contributing factors, action items. | tester, engineer | `docs/postmortems/YYYY-MM-DD-*.md` | +| Skill | Description | Primary role(s) | Output artifact | +| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | ------------------------------------------- | +| `vision` | CEO/founder-mode plan review. Rethink from first principles, validate ambition, find the 10x solution. | product | `docs/product/vision.md` | +| `requirements` | Collaborative requirements gathering. Clarifies what must be built, defines success criteria and NFRs. | product | `docs/product/requirements.md` | +| `architecture` | Engineering-lead plan review. Lock in service boundaries, data models, API contracts, test strategy. | architect | `docs/architecture/architecture.md` | +| `adr` | Architecture Decision Record writing. Documents a decision with context, alternatives, and rationale. | architect | `docs/architecture/adr/NNN-*.md` | +| `design` | Build a complete API or service design from scratch. Produces OpenAPI specs, error conventions, naming standards. | designer | `docs/design/design.md` / `openapi.yaml` | +| `consult` | DX triage and focused review. Routes to one path (API DX, CLI/tool DX, or developer workflow DX) and routes non-DX requests to specialized skills. | designer | focused DX report or routing recommendation | +| `concise` | Runtime response-style controller. Switches response density (`normal`, `compact`, `ultra`) and reports active mode via `status` without reinstall. | all roles | session style state + status output | +| `conventional-commit` | Prepare and validate Conventional Commit messages from current changes, with type/scope selection and commit-intent checks before commit. | engineer, release | compliant commit message(s) + commit(s) | +| `code-review` | Pre-landing code review. Finds bugs that pass CI but break in production — race conditions, security issues, performance landmines. | engineer | inline findings | +| `security` | OWASP Top 10 + STRIDE security audit. Finds auth bypasses, injection flaws, exposed secrets, broken access control. | tester | security audit report | +| `explore` | Repository and system discovery. Maps the architecture, identifies tech debt, produces an onboarding summary. | engineer | codebase map | +| `analyse` | Cross-cutting technical analysis. Investigates impact, tradeoffs, root causes, or feasibility without implementing changes. | engineer, architect | analysis report | +| `debug` | Systematic root-cause debugging. Follows scientific method: observe → hypothesise → test → conclude → fix → prevent. | engineer | root cause report + fix | +| `inspect` | Read-only verification audit. Runs baseline plus optional extended checks and produces severity-ranked findings, with no code or commit changes. | tester | read-only audit report | +| `performance` | Performance profiling and regression detection. Establishes baselines, detects regressions, profiles bottlenecks. | engineer, tester | perf report | +| `verify` | Verification fix-loop with mode routing (quick/standard/exhaustive). Runs targeted checks, fixes by severity, and re-verifies impacted paths. | engineer, tester | fixes + verification report | +| `cicd` | Write GitHub Actions CI/CD workflow configuration. Covers build, test, lint, security scan, container publish, deploy. | release | GitHub Actions workflow | +| `container` | Write and review Dockerfile, docker-compose, and container config. Covers multi-stage builds, non-root users, layer optimisation. | engineer | Dockerfile + compose | +| `threat-model` | Threat modeling with STRIDE-first identification, optional DREAD prioritization, and selective PASTA depth for critical systems. | architect, tester, engineer, designer | `docs/architecture/threat-model.md` | +| `release-notes` | Prepare release artifacts: write release notes, own CHANGELOG updates, produce `docs/releases/{date}.md`. | release | CHANGELOG + release doc | +| `pr` | Commit, push, and open a pull request from the current branch to main. | release | commit + PR | +| `gh-release` | Create or update a GitHub Release using gh CLI with tag validation, draft/publish mode, and release notes file integration. | release | GitHub Release | +| `docs` | Post-release documentation alignment for README/API docs/migrations and related artifacts (no CHANGELOG ownership). | product, architect, designer, engineer, tester, release | updated docs artifacts | +| `guardrails` | Activate safety guardrails for the session. Requires explicit confirmation before any destructive action. | — | (mode activation) | +| `migrate` | Database migration review and authoring. Forwards/backwards compatibility, zero-downtime strategies, rollback plans, data integrity, index safety. | engineer, tester | reviewed/corrected migration SQL | +| `openapi` | Write and review OpenAPI 3.1 specifications. Resource naming, HTTP semantics, status codes, error conventions, pagination, security schemes. | designer, engineer | `openapi.yaml` | +| `refactor` | Structured refactoring without behavior change. Identify smells, plan incremental steps, execute, verify correctness. | engineer | refactored code + green tests | +| `onboard` | Generate a contributor onboarding guide. Prerequisites, setup, tests, env vars, architecture overview, good first issues. | product | `CONTRIBUTING.md` + README dev section | +| `dependency` | Dependency health audit. Vulnerability scanning, outdated packages, licence compliance, transitive risk, pinning policy, supply chain hygiene. | engineer, tester | dependency audit report | +| `incident` | Incident analysis and blameless post-mortem writing. Timeline reconstruction, 5-Whys root cause, contributing factors, action items. | tester, engineer | `docs/postmortems/YYYY-MM-DD-*.md` | +| `gh-issues` | Create, update, and manage GitHub Issues via gh CLI. Covers bug/feature/task templates, labels, assignees, milestones, and sub-issues. | release, product | GitHub Issues | +| `codeql` | Set up CodeQL code scanning via GitHub Actions or CLI. Language matrix, query suites, monorepo config, alert triage. | tester | `.github/workflows/codeql.yml` | +| `dependabot` | Create or optimize `.github/dependabot.yml`. Ecosystem detection, grouping strategies, monorepo patterns, schedule, and PR customization. | engineer, tester | `.github/dependabot.yml` | +| `secret-scan` | Configure GitHub secret scanning and push protection. Path exclusions, custom patterns, alert triage, and credential remediation. | tester, engineer | `.github/secret_scanning.yml` | +| `gdpr` | GDPR-compliant engineering practices. Privacy by design, data minimization, storage limitation, erasure, encryption, and PR review checklist. | engineer, architect, tester | checklist / PR findings | +| `terraform` | Write, review, and refactor Terraform IaC. Module structure, state management, variable conventions, provider pinning, and security hardening. | engineer | Terraform config files | +| `terragrunt` | Write, review, and refactor Terragrunt DRY multi-environment IaC. Root config, dependency blocks, `_envcommon`, and run-all workflows. | engineer | `terragrunt.hcl` files | +| `cloudformation` | Write and review AWS CloudFormation templates. Parameters, conditions, cross-stack references, change sets, drift detection, and security hardening. | engineer | CFN template `.yaml` | +| `aws-cli` | AWS CLI workflows for IAM, S3, EC2, RDS, ECS, Lambda, CloudWatch, Secrets Manager, and SSM Parameter Store. | engineer, tester | — | +| `k8s` | Write, review, and troubleshoot Kubernetes manifests and operations. Covers rollout safety, probes, RBAC, namespace isolation, and diagnostics. | engineer, tester | Kubernetes manifests | +| `helm` | Write, review, and operate Helm charts and release lifecycles. Covers lint/template validation, upgrades, rollbacks, and dependencies. | engineer, tester | Helm charts + release config | +| `rancher` | Operate Kubernetes workloads and governance through Rancher. Covers project scope, RBAC, Fleet/GitOps basics, and multi-cluster checks. | engineer, tester | Rancher/Fleet config | ______________________________________________________________________ @@ -155,6 +170,12 @@ ______________________________________________________________________ `version` is maintained in `config.yaml` for vstack install/update tracking and is not emitted into generated `SKILL.md` frontmatter. +Template revision format is `YYYYMMDDNNN` (for example `20260502001`): + +1. `YYYYMMDD` is the template file modified date used for the update. +1. `NNN` is a zero-padded sequence for multiple updates on the same day. +1. The value is treated as an opaque, monotonically increasing revision token (not semantic versioning). + `allowed-tools` is currently not emitted by vstack because support is inconsistent across target agents. `name` must satisfy the Agent Skills naming rules enforced by vstack: lowercase kebab-case, no leading/trailing hyphen, max 64 characters. @@ -208,6 +229,11 @@ Recommended skill directory layout: This aligns with progressive disclosure: keep `SKILL.md` focused (instructions body under about 5000 tokens; target under 500 lines), and move detailed material into `references/`, `scripts/`, or `assets/`. +Token-efficiency guidance: + +- Prefer heading hierarchy and concise transition text over decorative separator lines. +- Avoid long horizontal ruler lines made from repeated characters (for example `_____`) in skill bodies. + ## search and context hygiene Skill templates should avoid scanning dependency/generated trees unless explicitly requested. diff --git a/docs/product/roadmap.md b/docs/product/roadmap.md index 59670bb..d49b952 100644 --- a/docs/product/roadmap.md +++ b/docs/product/roadmap.md @@ -7,27 +7,39 @@ ______________________________________________________________________ ## feature status table -| Feature | Status | Notes | -| ---------------------------------------- | ----------- | --------------------------------------------------------------------------------- | -| foundation | shipped | Core template-driven install model is in place | -| backend-first verification | shipped | Verify/inspect focus on contracts, observability, security | -| VS Code agent migration | shipped | Native agent output format implemented | -| role model + doc restructure | shipped | 6-role model and docs baseline established | -| new skill scaffolding | shipped | 27-skill set with canonical naming | -| agent skill wiring | shipped | Role-to-skill mapping and handoffs are present | -| CLI modularisation (v2.0.0) | shipped | 12 focused CLI modules; BaseCommand + CommandContext contract | -| manifest package (v2.0.0) | shipped | Dedicated `manifest/` package; atomic writes (ADR-016) | -| mypy type checking (v2.0.0) | shipped | Full mypy coverage enforced in CI; 100% test coverage gate | -| manifest schema versioning (v2.0.0) | shipped | `manifest_version: 2`; upgrade path via `manifest upgrade` (ADR-014) | -| checksum backfill (v2.0.0) | shipped | `manifest upgrade --backfill` adds SHA-256 for VSTACK-META-tagged files (ADR-017) | -| conservative install (v2.0.0) | shipped | Untracked files never overwritten; checksum-gated update (ADR-015) | -| dry-run install | shipped | `vstack install --dry-run` previews actions; type/name selectors in summary | -| optional orchestrated role pipeline | candidate | Optional future model, only if coordination bottlenecks appear | -| multi-IDE support (IntelliJ first) | candidate | Not planned before v1 stabilization | -| heavy agent runtime framework | not planned | Keeps runtime lightweight and transparent | -| cloud control plane dependency | not planned | Keeps operation local/offline-capable | -| VS Code extension packaging | not planned | Not required for current install model | -| browser automation as default dependency | not planned | Backend/microservice-first remains default | +| Feature | Status | Notes | +| ---------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------- | +| foundation | shipped | Core template-driven install model is in place | +| backend-first verification | shipped | Verify/inspect focus on contracts, observability, security | +| VS Code agent migration | shipped | Native agent output format implemented | +| role model + doc restructure | shipped | 6-role model and docs baseline established | +| new skill scaffolding | shipped | 42-skill set with canonical naming | +| agent skill wiring | shipped | Role-to-skill mapping and handoffs are present | +| CLI modularisation (v2.0.0) | shipped | 12 focused CLI modules; BaseCommand + CommandContext contract | +| manifest package (v2.0.0) | shipped | Dedicated `manifest/` package; atomic writes (ADR-016) | +| mypy type checking (v2.0.0) | shipped | Full mypy coverage enforced in CI; 100% test coverage gate | +| manifest schema versioning (v2.0.0) | shipped | `manifest_version: 2`; upgrade path via `manifest upgrade` (ADR-014) | +| checksum backfill (v2.0.0) | shipped | `manifest upgrade --backfill` adds SHA-256 for VSTACK-META-tagged files (ADR-017) | +| conservative install (v2.0.0) | shipped | Untracked files never overwritten; checksum-gated update (ADR-015) | +| dry-run install | shipped | `vstack install --dry-run` previews actions; type/name selectors in summary | +| workflow contract source-of-truth | candidate | Defer until current template expansion is complete; then add machine-readable role workflow contract | +| agent hooks support | candidate | Generate `.github/hooks/<name>.json` from vstack templates; enforce quality gates at session boundaries | +| Copilot code review support | candidate | Add templates and policy defaults for requesting/configuring Copilot code review | +| GitHub tasks MCP-first mode | candidate | Add task profile for issues/PR/branch operations with MCP-first execution and safe fallback | +| Copilot Spaces context pack | candidate | Add structured context packaging and refresh workflow for Copilot Spaces | +| content exclusion baseline | candidate | Ship policy templates/checklists for Copilot content exclusion at repo/org/enterprise scope | +| MCP governance baseline | candidate | Standardize MCP registry allowlist and server-access policy defaults | +| Copilot Memory governance | candidate | Add memory enablement, review, and curation policy guidance for teams | +| usage-based billing guardrails | candidate | Add budget/allowance/monitoring playbooks for Copilot metered usage | +| Copilot admin observability pack | candidate | Define operational KPI and reporting cadence for adoption and usage dashboards | +| VS Code customization starter pack | candidate | Add installable templates for custom agents, instructions, prompts, and agent customization workflow | +| template overlays + selective install | candidate | Combine upstream and company templates with source-priority rules and install by artifact type | +| optional orchestrated role pipeline | candidate | Optional future model, only if coordination bottlenecks appear | +| multi-IDE support (IntelliJ first) | candidate | Not planned before v1 stabilization | +| heavy agent runtime framework | not planned | Keeps runtime lightweight and transparent | +| cloud control plane dependency | not planned | Keeps operation local/offline-capable | +| VS Code extension packaging | not planned | Not required for current install model | +| browser automation as default dependency | not planned | Backend/microservice-first remains default | ______________________________________________________________________ @@ -38,7 +50,7 @@ Legend: shipped = implemented and available; candidate = optional future feature ### foundation [shipped] - template-driven generation with source under `src/vstack/_templates/` and install output under `.github/` -- 27 backend-oriented skills +- 42 backend-oriented skills - generated install manifest (`.github/vstack.json`) tracking installed artifacts - VS Code prompt file (`.prompt.md`) support - global install workflow (`vstack install --global`) @@ -66,9 +78,11 @@ Legend: shipped = implemented and available; candidate = optional future feature ### new skill scaffolding [shipped] -27 skills across 6 roles. New additions: +39 skills across 6 roles. Representative additions: - `requirements`, `adr`, `analyse` (new) +- `gh-issues`, `codeql`, `dependabot`, `secret-scan` +- `gdpr`, `terraform`, `terragrunt`, `cloudformation`, `aws-cli` - Renames: `experience` → `consult`, `design-consult` → `design`, `docs-release` → `docs`, `discovery` → `explore` - All templates: WHO→HOW (removed role persona preamble, added out-of-scope sections) - `guardrails` retained as a per-project installable safety skill @@ -121,10 +135,212 @@ Possible future workflow with explicit orchestration (only if real coordination See `docs/design/workflow.md` for current execution and the orchestrated future model. +### workflow contract source-of-truth [candidate] + +Deferred until the current templates expansion is complete. + +Planned direction: + +- Keep one machine-readable workflow contract describing role inputs, outputs, gates, and handoffs. +- Use that contract to keep agent workflow sections and checks aligned. +- Keep `docs/design/workflow.md` as the human-readable explanation layer. + +This reduces drift risk between agent behavior and workflow documentation while keeping skills and instructions generic. + ### multi-IDE support [candidate] IntelliJ is the first candidate beyond VS Code. Not planned until after v1 stabilization. +### agent hooks support [candidate] + +GitHub Copilot agents support a repository-level hooks mechanism: shell commands defined in `.github/hooks/<name>.json` +that execute at key points during an agent session — `sessionStart`, `sessionEnd`, `userPromptSubmitted`, +`preToolUse`, `postToolUse`, and `errorOccurred`. + +vstack is well-positioned to provide curated, installable hook templates for common quality-gate patterns: + +- **Pre-tool safety gate** (`preToolUse`) — block or log destructive operations before they run +- **Session audit log** (`sessionStart` / `sessionEnd`) — record session boundaries with timestamp and working directory +- **Auto-format on edit** (`postToolUse`) — trigger `ruff format`, `terraform fmt`, `mdformat` after file edits +- **Commit policy check** (`postToolUse`) — run `cchk` or commit-message lint after `git commit` tool calls +- **Security scan on push** (`postToolUse`) — run `gitleaks` or `detect-secrets` after repository mutations + +Planned direction: + +- Add a `hooks` artifact type to the vstack generator, parallel to `skills` and `instructions` +- Templates live in `src/vstack/_templates/hooks/<name>/hook.json` (source of truth) +- Generated output written to `.github/hooks/<name>.json` at install time +- Register hooks in `vstack.json` manifest and track them with checksums like other artifact types +- Note: the per-agent `hooks` frontmatter field (already supported) is separate — it scopes hooks to one agent; repository hooks apply to all agent sessions + +Ref: [GitHub — Customize agent workflows with hooks](https://docs.github.com/en/copilot/how-tos/copilot-on-github/customize-copilot/customize-cloud-agent/use-hooks) + +### Copilot code review support [candidate] + +Relevance: + +- Copilot code review is now a dedicated workflow with setup and configuration needs. +- Teams need clear defaults for when review is advisory versus blocking. +- Runner and policy setup should be documented as reusable project artifacts. + +Planned direction: + +- Add templates/checklists for enabling and configuring Copilot code review. +- Add policy defaults for review severity handling and escalation paths. +- Add runner guidance for repository/org-level rollout. + +Ref: [GitHub — Code review](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/request-a-code-review) + +### GitHub tasks MCP-first mode [candidate] + +Relevance: + +- Copilot can perform GitHub tasks directly (issues, PRs, branches) with MCP integration. +- Teams need predictable, safe defaults for operational GitHub actions in agent workflows. +- MCP-first task execution can reduce glue scripting while preserving auditable actions. + +Planned direction: + +- Add a GitHub-tasks profile/skill with MCP-first behavior. +- Add safe fallback to `gh` CLI when MCP capability is unavailable. +- Add guardrails for sensitive actions (merge/close/delete) with explicit confirmation rules. + +Ref: [GitHub — Copilot for GitHub tasks](https://docs.github.com/en/copilot/how-tos/copilot-on-github/copilot-for-github-tasks) + +### Copilot Spaces context pack [candidate] + +Relevance: + +- Copilot Spaces provides curated context for higher-quality responses. +- Teams need a repeatable way to map project artifacts into Space-friendly context bundles. +- Without a packaging pattern, context quality drifts across repositories and teams. + +Planned direction: + +- Add a context-pack template that maps core docs/artifacts into a stable Space feed. +- Add refresh procedures so context remains synchronized with baseline docs and releases. +- Add quality checks for stale or missing context entries. + +Ref: [GitHub — Copilot Spaces](https://docs.github.com/en/copilot/how-tos/copilot-on-github/customize-copilot/copilot-spaces) + +### content exclusion baseline [candidate] + +Relevance: + +- Copilot content exclusion is now a first-class admin control at repository, organization, and enterprise scope. +- Teams need consistent patterns for excluding sensitive paths (for example: secrets, generated artifacts, legal-restricted data). +- A policy baseline prevents ad hoc exclusions and avoids accidental over-exclusion that harms developer experience. + +Planned direction: + +- Add installable content-exclusion policy templates and review checklist artifacts. +- Provide path-pattern conventions and anti-patterns for repository and org scope. +- Add validation guidance and rollout checks to avoid silent misconfiguration. + +Ref: [GitHub — Excluding content from GitHub Copilot](https://docs.github.com/en/copilot/how-tos/configure-content-exclusion/exclude-content-from-copilot) + +### MCP governance baseline [candidate] + +Relevance: + +- MCP server usage now has organization/enterprise governance controls. +- Without governance defaults, teams can connect inconsistent or untrusted MCP servers. +- A baseline improves security posture and keeps tool access predictable across repositories. + +Planned direction: + +- Add a governance-focused instruction/template pack for MCP registry and access policy. +- Define default allowlist/denylist patterns and review ownership. +- Include onboarding checks for newly proposed MCP servers. + +Ref: [GitHub — Managing MCP usage in your company](https://docs.github.com/en/copilot/how-tos/administer-copilot/manage-mcp-usage) + +### Copilot Memory governance [candidate] + +Relevance: + +- Copilot Memory affects cloud agent, code review, and CLI behavior quality. +- Feature is preview and policy-sensitive, so teams need explicit enablement and curation rules. +- Memory hygiene avoids stale, misleading, or sensitive memories degrading output quality. + +Planned direction: + +- Add memory policy templates (enablement defaults, owners, and review cadence). +- Add curation guidance for viewing/deleting repository memories. +- Add short operational guidance for teams with mixed org/enterprise policy inheritance. + +Ref: [GitHub — Managing and curating Copilot Memory](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/copilot-memory) + +### usage-based billing guardrails [candidate] + +Relevance: + +- Copilot billing is moving to usage-based models; teams need predictable spend controls. +- Without guardrails, premium-request usage can spike unexpectedly. +- Operational usage visibility is required for sustainable adoption. + +Planned direction: + +- Add spend-control playbooks (budgets, allowance policies, and alert thresholds). +- Add monthly usage review checklist and optimization guidance for model/task selection. +- Add references for organization vs enterprise ownership boundaries. + +Ref: [GitHub — Monitoring your GitHub Copilot usage and entitlements](https://docs.github.com/en/copilot/how-tos/manage-and-track-spending/monitor-premium-requests) + +### Copilot admin observability pack [candidate] + +Relevance: + +- Copilot adoption at scale needs explicit operational KPIs and recurring review loops. +- Admin dashboards and reports exist, but teams need standardized interpretation and actions. +- Consistent observability improves rollout quality and policy compliance. + +Planned direction: + +- Add an admin operations pack for usage/adoption KPI definitions and cadence. +- Add a standard reporting checklist for org and enterprise owners. +- Add escalation triggers for unusual usage patterns and policy drift. + +Ref: [GitHub — Administer GitHub Copilot for your team](https://docs.github.com/en/copilot/how-tos/administer-copilot) + +### VS Code customization starter pack [candidate] + +Relevance: + +- Teams repeatedly ask how to create custom agents, custom instructions, prompts, and skills in VS Code. +- vstack already generates these artifact types, but onboarding the customization model can be clearer. +- A starter pack lowers adoption friction and keeps customization patterns consistent. + +Planned direction: + +- Add a dedicated starter package with guided templates for custom agents, custom instructions, prompts, and skills. +- Include step-by-step examples for common workflows (domain agent, policy instruction, task prompt). +- Add a focused skill/instruction pair that teaches and validates Copilot customization patterns inside VS Code. + +Ref: [GitHub — Customize Copilot for your project](https://docs.github.com/en/copilot/how-tos/copilot-on-github/customize-copilot/customize-copilot-overview) + +### template overlays + selective install [candidate] + +Relevance: + +- Teams often need a company-specific Copilot stack rather than the default vstack set. +- A practical model is: keep upstream vstack as baseline, then layer private templates and extensions on top. +- Adoption is blocked when teams cannot control which artifact types are installed (`agents`, `skills`, `prompts`, `instructions`) or which source wins on conflicts. + +Planned direction: + +- Add support for multiple template sources in priority order (for example: upstream vstack first, company repo second). +- Define deterministic conflict resolution rules: `prefer-local`, `prefer-upstream`, and explicit `replace`/`extend` behavior per artifact. +- Add install selectors for coarse-grained artifact types (`--types agents,skills,prompts,instructions`) and optional fine-grained name selectors. +- Add install profiles in config/manifest (for example: `baseline`, `company`, `minimal`) to make repeat installs deterministic. +- Keep checksum/manifests source-aware so updates can be applied safely per origin. + +Initial UX target: + +- `vstack install --source upstream=... --source company=... --prefer company` +- `vstack install --types agents,skills` +- `vstack install --profile company` + ### heavy agent runtime framework [not planned] Not included to keep execution lightweight and transparent in VS Code native workflows. diff --git a/src/vstack/_templates/agents/architect/config.yaml b/src/vstack/_templates/agents/architect/config.yaml index 11b11d8..0e15fe1 100644 --- a/src/vstack/_templates/agents/architect/config.yaml +++ b/src/vstack/_templates/agents/architect/config.yaml @@ -1,5 +1,5 @@ name: architect -version: 1.0.1 +version: 20260502015 description: > Senior software architect. Sets the system blueprint: service decomposition, technology direction, standards, NFRs, and organizational constraints. diff --git a/src/vstack/_templates/agents/architect/template.md b/src/vstack/_templates/agents/architect/template.md index c700eae..29d07d3 100644 --- a/src/vstack/_templates/agents/architect/template.md +++ b/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: @@ -58,14 +74,10 @@ Handoffs you own: 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 +85,27 @@ Handoffs you own: - Conflicting constraints or unresolvable tradeoffs: escalate to user with options. - Breaking architecture changes without migration plan: block progression. +## artifacts you own + +| Artifact | Role | +| ----------------------------------- | ------- | +| `docs/architecture/architecture.md` | creator | +| `docs/architecture/adr/NNN-*.md` | creator | + +## 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 diff --git a/src/vstack/_templates/agents/designer/config.yaml b/src/vstack/_templates/agents/designer/config.yaml index d2417e3..a77756a 100644 --- a/src/vstack/_templates/agents/designer/config.yaml +++ b/src/vstack/_templates/agents/designer/config.yaml @@ -1,5 +1,5 @@ name: designer -version: 1.0.1 +version: 20260502016 description: > Senior interaction designer. Translates architecture blueprint into developer-ready specifications: API contracts, event schemas, data flows, diff --git a/src/vstack/_templates/agents/designer/template.md b/src/vstack/_templates/agents/designer/template.md index 993ad69..b514868 100644 --- a/src/vstack/_templates/agents/designer/template.md +++ b/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. - 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. @@ -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: @@ -72,12 +88,7 @@ Handoffs you own: 1. Write or update `docs/design/design.md` (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 docs are actionable without guesswork. - API/interface contracts and error cases are explicit. @@ -88,6 +99,19 @@ Handoffs you own: - Contract conflicts with architecture: escalate before implementation. - Unclear requirements affecting interaction decisions: request product clarification. +## artifacts you own + +| Artifact | Role | +| ----------------------- | --------------------------------------- | +| `docs/design/design.md` | creator | +| `docs/design/ux.md` | creator (frontend/fullstack scope only) | + +## 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`) diff --git a/src/vstack/_templates/agents/engineer/config.yaml b/src/vstack/_templates/agents/engineer/config.yaml index c546092..dbdd673 100644 --- a/src/vstack/_templates/agents/engineer/config.yaml +++ b/src/vstack/_templates/agents/engineer/config.yaml @@ -1,5 +1,5 @@ name: engineer -version: 1.0.1 +version: 20260502017 description: > Senior software engineer. Implements features, bug fixes, and unit tests based on docs/design/design.md, docs/architecture/architecture.md, and ADRs. diff --git a/src/vstack/_templates/agents/engineer/template.md b/src/vstack/_templates/agents/engineer/template.md index 461606b..c10e33c 100644 --- a/src/vstack/_templates/agents/engineer/template.md +++ b/src/vstack/_templates/agents/engineer/template.md @@ -4,17 +4,25 @@ You are a **senior software engineer** acting as the **engineer role**. You build production-ready systems from approved architecture and design artifacts. -## responsibilities and scope +## responsibilities - Own implementation quality: features, bug fixes, refactors, and code-level correctness. - Deliver code aligned with `docs/product/requirements.md`, `docs/design/design.md`, `docs/architecture/architecture.md`, and `docs/architecture/adr/*.md`. - Write and maintain unit tests alongside implementation. -- Architect and designer own architecture and interface contracts; tester owns release-readiness verification. + +## scope and boundaries + +- Engineer owns implementation and code-level quality. +- Architect and designer own architecture and interface contracts. +- Tester owns release-readiness verification and risk verdicts. + +## limitations and do not do + - Do not silently change architecture or API contracts. - Do not skip tests for delivered behavior. - Do not defer critical reliability or security concerns without explicit escalation. -## principles +## working principles - Baseline-first execution from approved docs. - Small, reversible, reviewable code changes. @@ -23,6 +31,12 @@ You are a **senior software engineer** acting as the **engineer role**. You buil - Escalate contract mismatch before coding around it. - Optimize for maintainability over cleverness. +## decision guidelines + +- Prefer the smallest change that satisfies requirements and constraints. +- Escalate when upstream contracts are ambiguous or contradictory. +- Prioritize correctness, reliability, and observability over speed. + ## communication style - Be precise, evidence-based, and implementation-focused. @@ -32,6 +46,18 @@ You are a **senior software engineer** acting as the **engineer role**. You buil {{AGENT_SKILL_BOUNDARY}} +## workflow and handoffs + +Signal readiness before downstream verification: + +1. **Ready for verification** — implementation complete with tests and known risks documented. +1. **Ready for release gating** — blocking issues from tester are resolved. + +Handoffs you own: + +- To tester: verification targets, risk areas, and changed behavior summary. +- Back to architect/designer/product: blockers caused by missing or conflicting contracts. + ## parallel delegation For `fullstack` or `integration` system styles, split work across specialized subagents: @@ -52,12 +78,7 @@ Only delegate when workstreams are genuinely independent. 1. Handoff to tester with explicit verification targets and risk areas. 1. For debugging paths, use root-cause-first investigation before proposing fixes. -## deliverables and success criteria - -| Artifact | Role | -| ----------- | ------- | -| source code | creator | -| unit tests | creator | +## success criteria - Implementation matches approved architecture and design intent. - Tests cover core paths and regressions. @@ -69,6 +90,19 @@ Only delegate when workstreams are genuinely independent. - High-risk defects discovered: escalate immediately with mitigation options. - Blocked dependencies or migration risk: notify product and architect early. +## artifacts you own + +| Artifact | Role | +| ----------- | ------- | +| source code | creator | +| unit tests | creator | + +## completion checklist + +- Required upstream artifacts were read before coding. +- Implementation and tests were updated together. +- Tester handoff includes explicit verification targets and risk areas. + ## skills you use - `@#concise` — runtime response-style mode (`normal|compact|ultra|status`) @@ -76,8 +110,10 @@ Only delegate when workstreams are genuinely independent. - `@#analyse` — impact analysis, tradeoffs, feasibility - `@#docs` — keep implementation and technical documentation accurate when behavior changes - `@#verify` — run tests, fix issues, re-verify loop +- `@#conventional-commit` — prepare policy-aligned Conventional Commit messages - `@#code-review` — pre-merge review - `@#debug` — root-cause debugging +- `@#threat-model` — threat model updates when design or attack surface changes - `@#performance` — performance investigation - `@#container` — Dockerfile and docker-compose authoring - `@#cicd` — GitHub Actions CI/CD workflow configuration @@ -86,3 +122,13 @@ Only delegate when workstreams are genuinely independent. - `@#openapi` — OpenAPI 3.1 spec writing and review - `@#dependency` — dependency health audit - `@#incident` — incident analysis and post-mortem writing +- `@#dependabot` — configure automated dependency updates +- `@#secret-scan` — configure GitHub secret scanning and push protection +- `@#gdpr` — GDPR engineering practices for data models, APIs, logging, and retention +- `@#terraform` — Terraform IaC authoring and review +- `@#terragrunt` — Terragrunt DRY multi-environment IaC configuration +- `@#cloudformation` — AWS CloudFormation template writing and review +- `@#aws-cli` — AWS CLI operations and scripting +- `@#k8s` — Kubernetes manifest authoring, rollout operations, and troubleshooting +- `@#helm` — Helm chart authoring and release lifecycle operations +- `@#rancher` — Rancher and Fleet multi-cluster operations and governance diff --git a/src/vstack/_templates/agents/product/config.yaml b/src/vstack/_templates/agents/product/config.yaml index 88ac033..93f1851 100644 --- a/src/vstack/_templates/agents/product/config.yaml +++ b/src/vstack/_templates/agents/product/config.yaml @@ -1,5 +1,5 @@ name: product -version: 1.0.1 +version: 20260502018 description: > Senior product manager. Defines vision, requirements, and roadmap for new products, new features, and major scope changes. Baseline-first on branch: diff --git a/src/vstack/_templates/agents/product/template.md b/src/vstack/_templates/agents/product/template.md index e0fe599..abd0050 100644 --- a/src/vstack/_templates/agents/product/template.md +++ b/src/vstack/_templates/agents/product/template.md @@ -4,22 +4,38 @@ You are a **senior product manager** acting as the **product role**. You define what gets built, why it matters, and when it is accepted. -## responsibilities and scope +## responsibilities - Define and refine scope for new products, features, and major scope changes. - Own acceptance criteria and release-acceptance decisions. - Orchestrate role handoffs and gate progression through the pipeline. - Ensure product baseline artifacts are current before release. -- Architect, designer, engineer, tester, and release each own their respective artifacts and decisions — do not override them. -## principles +## scope and boundaries + +- Product owns requirements, scope decisions, and acceptance. +- Architect, designer, engineer, tester, and release own their role artifacts and technical decisions. +- Product coordinates progression across gates; it does not replace role-specific execution. + +## limitations and do not do + +- Do not implement code changes. +- Do not override role-owned technical decisions without explicit escalation. +- Do not hand off to release when acceptance criteria are not met. + +## working principles - Baseline-first: keep canonical docs updated as work evolves on the feature branch. - Prefer explicit acceptance criteria over vague intent. - Keep scope decisions reversible until architecture/design gates are approved. - Choose the smallest scope that still achieves measurable outcomes. - Escalate ambiguity early; require architecture and design evidence before implementation starts. -- Do not implement code changes; do not hand off to release when acceptance criteria are not met. + +## decision guidelines + +- Block progression when required upstream artifacts are missing or stale. +- Prefer small, reviewable scope slices over broad ambiguous deliveries. +- Escalate unresolved cross-role conflicts before approving the next gate. ## communication style @@ -31,7 +47,7 @@ You are a **senior product manager** acting as the **product role**. You define {{AGENT_SKILL_BOUNDARY}} -## gate moments and handoffs +## workflow and handoffs You pause the pipeline at key moments and wait for explicit user confirmation: @@ -56,14 +72,7 @@ Handoffs you own: 1. **Gate:** Confirm with user at each transition before proceeding. 1. **Summarize:** Report decisions, gate status, changed artifacts, and next steps. -## deliverables and success criteria - -| Artifact | Role | -| ------------------------------------ | ------- | -| `docs/product/vision.md` | creator | -| `docs/product/requirements.md` | creator | -| `docs/product/roadmap.md` | creator | -| gate decisions and acceptance record | creator | +## success criteria - Gate decisions are explicit and traceable at each transition. - Acceptance is confirmed against requirements before release handoff. @@ -75,6 +84,21 @@ Handoffs you own: - If tester reports unresolved blockers: do not release. - If required product artifacts are stale or missing: block progression until corrected. +## artifacts you own + +| Artifact | Role | +| ------------------------------------ | ------- | +| `docs/product/vision.md` | creator | +| `docs/product/requirements.md` | creator | +| `docs/product/roadmap.md` | creator | +| gate decisions and acceptance record | creator | + +## completion checklist + +- Requirements and acceptance criteria are current and explicit. +- Gate status and owner decisions are recorded. +- Handoff prompt to the next role is actionable and scoped. + ## skills you use - `@#concise` — runtime response-style mode (`normal|compact|ultra|status`) @@ -85,3 +109,4 @@ Handoffs you own: - `@#analyse` — impact analysis, tradeoffs, feasibility - `@#adr` — architecture decision record writing (if significant decisions) - `@#onboard` — contributor onboarding guide generation +- `@#gh-issues` — create and manage GitHub Issues for requirements, tasks, and user stories diff --git a/src/vstack/_templates/agents/release/config.yaml b/src/vstack/_templates/agents/release/config.yaml index 149b826..07e6917 100644 --- a/src/vstack/_templates/agents/release/config.yaml +++ b/src/vstack/_templates/agents/release/config.yaml @@ -1,5 +1,5 @@ name: release -version: 1.0.1 +version: 20260502019 description: > Senior platform and release engineer. Acts as release gatekeeper: verifies baseline artifacts are complete (docs/product, docs/architecture, diff --git a/src/vstack/_templates/agents/release/template.md b/src/vstack/_templates/agents/release/template.md index dcc9945..75d8ab1 100644 --- a/src/vstack/_templates/agents/release/template.md +++ b/src/vstack/_templates/agents/release/template.md @@ -4,17 +4,25 @@ You are a **senior platform and release engineer** acting as the **release role**. You gate final release readiness and execute PR handoff. -## responsibilities and scope +## responsibilities - Own release gating, artifact checks, and PR creation. - Collect explicit sign-offs from tester and product. - Produce `docs/releases/{date}.md`, update `CHANGELOG.md`, and open the release PR. -- Tester owns verification evidence; product owns requirements acceptance. + +## scope and boundaries + +- Release owns gating, artifact checks, and PR handoff. +- Tester owns verification evidence. +- Product owns requirements acceptance and final business sign-off. + +## limitations and do not do + - Do not proceed if required artifacts are missing or stale. - Do not override NOK sign-offs. - Do not perform ad-hoc production changes in place of the release process. -## principles +## working principles - Evidence-first release decisions. - Explicit sign-offs from tester and product. @@ -23,6 +31,12 @@ You are a **senior platform and release engineer** acting as the **release role* - If any blocker exists, stop and route to owning role. - Prefer clear release notes over minimal notes. +## decision guidelines + +- Enforce required-for-scope evidence before requesting sign-off. +- Treat contradictory evidence as a blocker until reconciled. +- Prioritize auditability and deterministic release records. + ## communication style - Gate-oriented and explicit about pass/fail state. @@ -32,7 +46,7 @@ You are a **senior platform and release engineer** acting as the **release role* {{AGENT_SKILL_BOUNDARY}} -## gate moments and handoffs +## workflow and handoffs Signal readiness at each release gate: @@ -56,14 +70,7 @@ Handoffs you own: 1. If both are `OK`, invoke `@#release-notes` to produce `docs/releases/{date}.md` and finalize `CHANGELOG.md`. 1. Invoke `@#pr` to push and open the PR with release notes as the body. -## deliverables and success criteria - -| Artifact | Role | -| -------------------------------- | ------- | -| `docs/releases/{date}.md` | creator | -| `CHANGELOG.md` updates | creator | -| release PR | creator | -| sign-off record (tester/product) | creator | +## success criteria - Required-for-scope artifacts are present and current before sign-off. - Tester and product sign-offs are explicit and recorded. @@ -75,12 +82,30 @@ Handoffs you own: - Any NOK sign-off: stop and hand back with rationale. - Contradictory evidence between reports: escalate for reconciliation before proceeding. +## artifacts you own + +| Artifact | Role | +| -------------------------------- | ------- | +| `docs/releases/{date}.md` | creator | +| `CHANGELOG.md` updates | creator | +| release PR | creator | +| sign-off record (tester/product) | creator | + +## completion checklist + +- Required evidence and sign-offs are explicitly recorded. +- Release artifacts are current and traceable. +- PR handoff includes final scope summary and residual risks. + ## skills you use - `@#concise` — runtime response-style mode (`normal|compact|ultra|status`) - `@#release-notes` — write `docs/releases/{date}.md` and update `CHANGELOG.md` +- `@#conventional-commit` — produce compliant Conventional Commit messages before PR - `@#pr` — commit, push, and open pull request +- `@#gh-release` — create or update GitHub Release with `gh` CLI - `@#docs` — update README/API docs consistency after release packaging - `@#cicd` — write GitHub Actions CI/CD workflows - `@#explore` — codebase discovery and mapping - `@#code-review` — final review before PR is opened +- `@#gh-issues` — create and manage GitHub Issues for tracking work and bug reports diff --git a/src/vstack/_templates/agents/tester/config.yaml b/src/vstack/_templates/agents/tester/config.yaml index a614758..6d08f7b 100644 --- a/src/vstack/_templates/agents/tester/config.yaml +++ b/src/vstack/_templates/agents/tester/config.yaml @@ -1,5 +1,5 @@ name: tester -version: 1.0.1 +version: 20260502020 description: > Senior QA, security, and reliability engineer. Runs functional, security, and performance tests. Produces docs/test-report.md, docs/security-report.md, diff --git a/src/vstack/_templates/agents/tester/template.md b/src/vstack/_templates/agents/tester/template.md index 786be8b..0358055 100644 --- a/src/vstack/_templates/agents/tester/template.md +++ b/src/vstack/_templates/agents/tester/template.md @@ -4,18 +4,26 @@ You are a **senior QA, security, and reliability engineer** acting as the **tester role**. You verify that delivered changes work correctly, safely, and reliably. -## responsibilities and scope +## responsibilities - Own verification evidence and release-readiness findings. - Run functional, security, performance, and reliability verification for delivered scope. - Produce `docs/test-report.md` and `docs/security-report.md`; add `docs/performance-baseline.md` when performance validation is in scope. - Write or update tests required to validate behavior (unit/integration/contract/smoke) where applicable. -- Engineer owns implementation fixes; product owns acceptance and release decision. + +## scope and boundaries + +- Tester owns verification execution, findings, and readiness verdicts. +- Engineer owns implementation fixes. +- Product and release own acceptance and release decisions. + +## limitations and do not do + - Do not merge or release based on assumptions. - Do not hide blocking findings. - Do not bypass baseline reports with temporary-only notes. -## principles +## working principles - Baseline-first verification reports on branch. - Risk-based depth: prioritize high-impact paths and failure modes. @@ -24,6 +32,12 @@ You are a **senior QA, security, and reliability engineer** acting as the **test - Escalate ambiguous requirements that undermine test verdicts. - Prefer deterministic checks and explicit acceptance criteria. +## decision guidelines + +- Prioritize checks by severity and user impact. +- Escalate immediately when required evidence cannot be produced. +- Use explicit go/no-go language for release readiness. + ## communication style - Clear verdicts with severity and reproduction steps. @@ -33,7 +47,7 @@ You are a **senior QA, security, and reliability engineer** acting as the **test {{AGENT_SKILL_BOUNDARY}} -## gate moments and handoffs +## workflow and handoffs Signal readiness before release proceeds: @@ -55,14 +69,7 @@ Handoffs you own: 1. Write baseline reports: `docs/test-report.md`, `docs/security-report.md`, and `docs/performance-baseline.md` when performance validation is in scope. Include observability evidence in `docs/test-report.md` unless a dedicated observability report is used. 1. Publish verdict and hand off blockers or release-readiness status. -## deliverables and success criteria - -| Artifact | Role | -| ------------------------------ | ------------------------------------------------- | -| `docs/test-report.md` | creator | -| `docs/security-report.md` | creator | -| `docs/performance-baseline.md` | creator (when performance validation is in scope) | -| test files | creator | +## success criteria - Verification coverage matches scope and risk. - Blocking issues are clearly identified with severity and reproducible evidence. @@ -74,11 +81,27 @@ Handoffs you own: - Security-critical issue found: escalate immediately and block release. - Missing or stale required-for-scope artifacts: stop and report owners. +## artifacts you own + +| Artifact | Role | +| ------------------------------ | ------------------------------------------------- | +| `docs/test-report.md` | creator | +| `docs/security-report.md` | creator | +| `docs/performance-baseline.md` | creator (when performance validation is in scope) | +| test files | creator | + +## completion checklist + +- Functional, security, and required-for-scope checks are complete. +- Reports include reproducible findings and explicit verdicts. +- Release handoff includes blockers, residual risk, and readiness status. + ## skills you use - `@#concise` — runtime response-style mode (`normal|compact|ultra|status`) - `@#inspect` — read-only verification audit, produces findings report - `@#security` — security audit +- `@#threat-model` — structured threat analysis and mitigation prioritization - `@#performance` — performance review - `@#docs` — keep verification and audit documentation complete and current - `@#guardrails` — reliability and observability review @@ -88,3 +111,11 @@ Handoffs you own: - `@#migrate` — database migration safety review - `@#dependency` — dependency vulnerability and health audit - `@#incident` — incident analysis and post-mortem writing +- `@#codeql` — CodeQL code scanning setup and alert triage +- `@#secret-scan` — GitHub secret scanning configuration and alert triage +- `@#dependabot` — review and validate dependency update configuration +- `@#gdpr` — GDPR compliance review for data handling and privacy controls +- `@#aws-cli` — AWS resource inspection and observability queries +- `@#k8s` — Kubernetes workload validation, deployment safety, and runtime diagnostics +- `@#helm` — Helm chart and release validation with rollback safety checks +- `@#rancher` — Rancher/Fleet configuration and multi-cluster governance review diff --git a/src/vstack/_templates/instructions/git/config.yaml b/src/vstack/_templates/instructions/git/config.yaml index eac2055..bceee52 100644 --- a/src/vstack/_templates/instructions/git/config.yaml +++ b/src/vstack/_templates/instructions/git/config.yaml @@ -1,4 +1,4 @@ name: git description: Git and release hygiene conventions. Use when creating commits, branches, or release-related changes. applyTo: "**/*" -version: 0.1.0 +version: 20260421001 diff --git a/src/vstack/_templates/instructions/helm/config.yaml b/src/vstack/_templates/instructions/helm/config.yaml new file mode 100644 index 0000000..5764c55 --- /dev/null +++ b/src/vstack/_templates/instructions/helm/config.yaml @@ -0,0 +1,4 @@ +name: helm +description: Helm chart conventions. Use when writing or reviewing Helm charts, templates, and values files. +applyTo: "**/charts/**/*.{yaml,yml,tpl}" +version: 20260502040 diff --git a/src/vstack/_templates/instructions/helm/template.md b/src/vstack/_templates/instructions/helm/template.md new file mode 100644 index 0000000..81a20ee --- /dev/null +++ b/src/vstack/_templates/instructions/helm/template.md @@ -0,0 +1,40 @@ +Use these Helm conventions in this project. + +## Chart structure + +1. Keep chart metadata in `Chart.yaml`; do not duplicate metadata in templates. +1. Keep reusable template logic in `templates/_helpers.tpl`. +1. Keep defaults in `values.yaml` and environment overrides in separate values files. + +## Templating quality + +1. Quote string values where ambiguity may cause rendering/type errors. +1. Guard optional blocks with conditionals to avoid emitting invalid YAML. +1. Keep names and labels deterministic via helper templates. +1. Avoid embedding large opaque blobs in templates; externalize where possible. + +## Values and secrets + +1. Document key values in chart README or comments. +1. Do not hardcode secrets in `values.yaml`; use external secret mechanisms or secure value injection. +1. Keep production overrides minimal and explicit. + +## Dependencies and versioning + +1. Pin dependency versions in `Chart.yaml`; avoid floating versions. +1. Update dependencies with `helm dependency update` as part of chart changes. +1. Track breaking changes in chart `version` and `appVersion` updates. + +## Validation and release safety + +1. Run `helm lint` for every chart change. +1. Render templates with `helm template` and validate generated manifests before deployment. +1. Use `helm upgrade --atomic` for safer upgrades where applicable. +1. Keep rollback paths available and verify `helm history` in production workflows. + +## References + +> Always use the official documentation for the exact Helm and Kubernetes versions in use - chart schema, flags, and behavior evolve between releases. + +- [Helm docs](https://helm.sh/docs/) +- [Helm chart best practices](https://helm.sh/docs/chart_best_practices/) diff --git a/src/vstack/_templates/instructions/java/config.yaml b/src/vstack/_templates/instructions/java/config.yaml new file mode 100644 index 0000000..e58e1ee --- /dev/null +++ b/src/vstack/_templates/instructions/java/config.yaml @@ -0,0 +1,4 @@ +name: java +description: Java coding conventions for projects. Use when writing or reviewing Java source files, tests, and build configuration. +applyTo: "**/*.java" +version: 20260502001 diff --git a/src/vstack/_templates/instructions/java/template.md b/src/vstack/_templates/instructions/java/template.md new file mode 100644 index 0000000..47c62b1 --- /dev/null +++ b/src/vstack/_templates/instructions/java/template.md @@ -0,0 +1,51 @@ +Use these Java conventions in this project. + +## Design and readability + +1. Prefer explicit, domain-meaningful names over abbreviations; follow standard Java naming conventions. +1. Keep methods focused; split methods that mix parsing, I/O, and business rules. +1. Prefer immutable objects; make fields `final` by default and expose mutation only where required. +1. Prefer straightforward control flow over clever one-liners. + +## Types and APIs + +1. Keep public APIs minimal and stable; mark implementation details `package-private` or `private`. +1. Program to interfaces, not implementations, for dependencies that may change. +1. Use records for simple value types where the Java version supports them. +1. Prefer `Optional` as a return type for values that may be absent; do not use it for fields or parameters. + +## Null safety + +1. Annotate method parameters and return types with `@NonNull` or `@Nullable` where nullability is meaningful. +1. Never return `null` from a public method that could return `Optional` instead. +1. Fail fast on unexpected nulls at system boundaries using explicit precondition checks. + +## Exception handling + +1. Use checked exceptions only for conditions the caller can reasonably recover from. +1. Prefer unchecked exceptions for programming errors and unrecoverable states. +1. Never swallow exceptions silently; log or rethrow with meaningful context. +1. Close resources with try-with-resources rather than manual `finally` blocks. + +## Concurrency + +1. Prefer high-level concurrency abstractions (`ExecutorService`, `CompletableFuture`) over raw threads. +1. Minimize shared mutable state; document thread-safety guarantees explicitly. +1. Do not use `synchronized` on publicly visible objects unless the locking strategy is documented. + +## Dependencies and imports + +1. Keep imports minimal; remove unused imports. +1. Avoid wildcard imports (`import foo.*`) in production code. +1. Do not add a library dependency when the standard library suffices. + +## Testing and verification + +1. Add or update tests for every behavioral change. +1. Keep unit tests independent of implementation details; test observable behavior. +1. Cover success paths, edge cases, and expected failures. + +## Tooling alignment + +1. Keep code compatible with the repository's checkstyle, PMD, or linting configuration. +1. Do not suppress static analysis warnings without a documented, task-specific reason. diff --git a/src/vstack/_templates/instructions/k8s/config.yaml b/src/vstack/_templates/instructions/k8s/config.yaml new file mode 100644 index 0000000..8767d6b --- /dev/null +++ b/src/vstack/_templates/instructions/k8s/config.yaml @@ -0,0 +1,4 @@ +name: k8s +description: Kubernetes manifest conventions. Use when writing or reviewing Kubernetes workload and service manifests. +applyTo: "**/{k8s,kubernetes,manifests}/**/*.{yaml,yml}" +version: 20260502039 diff --git a/src/vstack/_templates/instructions/k8s/template.md b/src/vstack/_templates/instructions/k8s/template.md new file mode 100644 index 0000000..a43c8b3 --- /dev/null +++ b/src/vstack/_templates/instructions/k8s/template.md @@ -0,0 +1,46 @@ +Use these Kubernetes conventions in this project. + +## API and versioning + +1. Prefer stable APIs (`apps/v1`, `networking.k8s.io/v1`) and avoid deprecated versions. +1. Set `kind` and `metadata.name` deterministically; avoid generated names for long-lived workloads. +1. Keep one primary resource per file where possible to simplify review and rollback. + +## Workload safety + +1. Set CPU and memory `requests` and `limits` for every container. +1. Define both readiness and liveness probes for long-running services. +1. Avoid mutable image tags (`:latest`); use pinned tags or immutable digests. +1. Set rollout strategy explicitly for Deployments handling production traffic. + +## Namespace and labels + +1. Explicitly set `metadata.namespace` unless the deployment tooling injects it by design. +1. Use consistent labels: `app.kubernetes.io/name`, `app.kubernetes.io/instance`, `app.kubernetes.io/managed-by`. +1. Keep Service selectors aligned with pod template labels. + +## Security + +1. Run containers as non-root when feasible. +1. Avoid privileged mode and broad Linux capabilities unless required and documented. +1. Do not hardcode secrets in manifests; reference Secrets or external secret providers. +1. Restrict RBAC to least privilege; avoid broad `cluster-admin` grants. + +## Reliability and operations + +1. Use PodDisruptionBudgets for critical workloads. +1. Configure `terminationGracePeriodSeconds` and preStop hooks where graceful shutdown is required. +1. Add resource annotations/labels needed by observability and runtime policies. + +## Validation + +1. Validate manifests with `kubectl apply --dry-run=client` before merge. +1. Use `kubectl apply --dry-run=server` where API server validation is available. +1. Treat warnings for deprecated APIs as release blockers. + +## References + +> Always use the official documentation for the exact Kubernetes version in use - API versions and defaults change between releases. + +- [Kubernetes docs](https://kubernetes.io/docs/) +- [Kubernetes API reference](https://kubernetes.io/docs/reference/kubernetes-api/) diff --git a/src/vstack/_templates/instructions/markdown/config.yaml b/src/vstack/_templates/instructions/markdown/config.yaml new file mode 100644 index 0000000..6688690 --- /dev/null +++ b/src/vstack/_templates/instructions/markdown/config.yaml @@ -0,0 +1,4 @@ +name: markdown +description: Markdown authoring conventions for documentation, README files, ADRs, and other hand-authored prose. Use when writing or reviewing any Markdown file. +applyTo: "**/*.md" +version: 20260502002 diff --git a/src/vstack/_templates/instructions/markdown/template.md b/src/vstack/_templates/instructions/markdown/template.md new file mode 100644 index 0000000..b10327f --- /dev/null +++ b/src/vstack/_templates/instructions/markdown/template.md @@ -0,0 +1,46 @@ +Use these Markdown conventions in this project. + +## Structure and headings + +1. Keep heading levels sequential — do not skip levels (e.g. from `##` to `####`). +1. Prefer flat heading structures; rarely go deeper than `####`. +1. Keep headings short and descriptive. + +## Prose and tone + +1. Write in clear, direct language — prefer active voice over passive voice. +1. Keep sentences short; split complex ideas across multiple sentences rather than commas and semicolons. +1. Be consistent with terminology throughout the file; introduce a term once and reuse it. +1. Avoid filler phrases such as "please note", "it is important to", and "simply". + +## Lists and tables + +1. Use numbered lists for ordered steps; use unordered lists for non-ordered items. +1. Keep list items parallel in grammar and structure. +1. Prefer a table over nested unordered lists when presenting structured comparisons. +1. Keep table columns to what is necessary; remove columns with no meaningful content. + +## Code blocks and inline code + +1. Specify a language identifier on fenced code blocks where a language can be determined. +1. Use inline code for file names, paths, commands, identifiers, and literal values. +1. Do not put prose in a code block; reserve code blocks for commands, source code, and literal output. + +## Links and references + +1. Use descriptive link text — avoid bare URLs and text like "click here" or "this link". +1. Prefer relative links for documents within the same repository. +1. Verify that section anchors match actual heading text before committing. + +## Diagrams + +1. Use Mermaid for process, flow, interaction, lifecycle, and decision diagrams when the target environment renders it (GitHub, VS Code, compatible docs tools). +1. Fall back to ASCII or plain-text descriptions when Mermaid rendering cannot be guaranteed (e.g. PyPI, email, plain-text viewers). +1. Use ASCII or text trees for directory layouts and file hierarchies regardless of environment. +1. Do not embed a diagram where a simple sentence or table communicates the same information. + +## Maintenance + +1. Update documentation in the same change as the behavior or interface it describes. +1. Remove outdated content rather than leaving it with a "TODO: update" comment. +1. Keep examples accurate and runnable — a broken example is worse than no example. diff --git a/src/vstack/_templates/instructions/python/config.yaml b/src/vstack/_templates/instructions/python/config.yaml index 3d978dd..9d5d94f 100644 --- a/src/vstack/_templates/instructions/python/config.yaml +++ b/src/vstack/_templates/instructions/python/config.yaml @@ -1,4 +1,4 @@ name: python description: Python coding conventions for projects. Use when writing or reviewing Python modules, tests, CLI code, and package internals. applyTo: "**/*.py" -version: 0.1.1 +version: 20260421002 diff --git a/src/vstack/_templates/instructions/rancher/config.yaml b/src/vstack/_templates/instructions/rancher/config.yaml new file mode 100644 index 0000000..1d6c725 --- /dev/null +++ b/src/vstack/_templates/instructions/rancher/config.yaml @@ -0,0 +1,4 @@ +name: rancher +description: Rancher and Fleet conventions. Use when writing or reviewing Rancher/Fleet configuration files and cluster governance manifests. +applyTo: "**/{rancher,fleet}/**/*.{yaml,yml}" +version: 20260502041 diff --git a/src/vstack/_templates/instructions/rancher/template.md b/src/vstack/_templates/instructions/rancher/template.md new file mode 100644 index 0000000..ba1072c --- /dev/null +++ b/src/vstack/_templates/instructions/rancher/template.md @@ -0,0 +1,39 @@ +Use these Rancher conventions in this project. + +## Scope and environment + +1. Keep environment and cluster targeting explicit; avoid wildcard targeting for production bundles. +1. Separate dev, staging, and production policies and rollout paths. +1. Document expected project/namespace scope for each config set. + +## Fleet and GitOps hygiene + +1. Keep Fleet bundle structure deterministic and easy to review. +1. Pin chart and app versions in GitOps definitions; avoid floating versions. +1. Keep per-environment overrides small and explicit. +1. Use pull-request review for all production-bound Fleet changes. + +## Access and governance + +1. Apply least privilege for Rancher roles and project membership. +1. Avoid broad administrative grants outside platform owner groups. +1. Review role bindings and project-level permissions regularly. + +## Secrets and security + +1. Do not hardcode credentials or tokens in Rancher/Fleet config files. +1. Reference secrets from approved secret management paths. +1. Keep auditability for cluster/project configuration changes. + +## Operations + +1. Validate target clusters/projects before applying any change. +1. Include rollback guidance for application and bundle updates. +1. Treat drift and failed bundle rollout as operational incidents with follow-up remediation. + +## References + +> Always use the official documentation for the exact Rancher and Fleet versions in use - features and defaults vary between releases. + +- [Rancher docs](https://ranchermanager.docs.rancher.com/) +- [Fleet docs](https://fleet.rancher.io/) diff --git a/src/vstack/_templates/instructions/security/config.yaml b/src/vstack/_templates/instructions/security/config.yaml new file mode 100644 index 0000000..9c27168 --- /dev/null +++ b/src/vstack/_templates/instructions/security/config.yaml @@ -0,0 +1,4 @@ +name: security +description: Security policy for all code, configuration, and infrastructure. Use when writing or reviewing any code, configuration, or workflow file. +applyTo: "**/*" +version: 20260502003 diff --git a/src/vstack/_templates/instructions/security/template.md b/src/vstack/_templates/instructions/security/template.md new file mode 100644 index 0000000..6e9a117 --- /dev/null +++ b/src/vstack/_templates/instructions/security/template.md @@ -0,0 +1,37 @@ +Apply these security policies in this project. + +## Secrets and credentials + +1. Never hardcode secrets, tokens, passwords, or private keys in source code, configuration files, tests, or commit messages. +1. Read secrets from environment variables or a secret store at runtime; document which variables are required. +1. Treat any accidental secret exposure as a revocation event — rotate immediately, do not just delete the value. + +## Input and trust boundaries + +1. Validate and sanitize all input that crosses a trust boundary: HTTP requests, CLI arguments, environment variables, files, and inter-service messages. +1. Never trust client-supplied values for authorization decisions; enforce access control server-side. +1. Reject or escape input before it reaches queries, shell commands, template engines, or log sinks. + +## Authentication and authorization + +1. Default to deny; require explicit grants for every protected resource or operation. +1. Verify identity and permission separately; do not conflate authentication with authorization. +1. Do not implement custom cryptography or authentication schemes; use established, maintained libraries. + +## Dependencies and supply chain + +1. Pin dependency versions in manifests; do not use unbounded version ranges in production code. +1. Minimise the dependency surface — do not add a library when the standard library suffices. +1. Treat dependency updates that introduce new transitive dependencies as requiring explicit review. + +## Error handling and observability + +1. Never expose internal stack traces, system paths, or configuration details to external callers. +1. Do not log sensitive data: passwords, tokens, PII, or session identifiers. +1. Fail closed on security errors — deny access when the policy cannot be evaluated, rather than defaulting to allow. + +## Destructive and privileged operations + +1. Require explicit confirmation before executing irreversible or destructive operations. +1. Apply least privilege: request only the permissions a component actually needs. +1. Isolate privileged logic; keep it minimal, auditable, and separate from business logic. diff --git a/src/vstack/_templates/instructions/terraform/config.yaml b/src/vstack/_templates/instructions/terraform/config.yaml new file mode 100644 index 0000000..53f94e9 --- /dev/null +++ b/src/vstack/_templates/instructions/terraform/config.yaml @@ -0,0 +1,4 @@ +name: terraform +description: Terraform coding conventions for projects. Use when writing or reviewing Terraform modules, root configurations, variable files, and state configuration. +applyTo: "**/*.tf" +version: 20260502034 diff --git a/src/vstack/_templates/instructions/terraform/template.md b/src/vstack/_templates/instructions/terraform/template.md new file mode 100644 index 0000000..3fbeabb --- /dev/null +++ b/src/vstack/_templates/instructions/terraform/template.md @@ -0,0 +1,55 @@ +Use these Terraform conventions in this project. + +## Structure and file layout + +1. Split configuration into `main.tf`, `variables.tf`, `outputs.tf`, `providers.tf`, `versions.tf`, and `locals.tf` — do not put everything in one file. +1. Keep one module per directory; avoid multi-purpose root modules. +1. Place reusable logic in `modules/<name>/` with its own `variables.tf` and `outputs.tf`. + +## Versioning and pinning + +1. Pin the Terraform binary version with `required_version = "~> X.Y"` in a `versions.tf` file. +1. Pin every provider with `version = "~> X.Y"` in `required_providers` — never use unbounded ranges in production. +1. Commit `.terraform.lock.hcl` to source control. +1. Pin external module sources to a specific git ref or registry semver tag — never `?ref=main`. + +## State management + +1. Use a remote backend with encryption and state locking for all non-local work. +1. Enable versioning on the S3 state bucket. +1. Never store secrets in state outputs — mark sensitive outputs with `sensitive = true`. + +## Variables and outputs + +1. Add `type`, `description`, and a sensible `default` to every variable. +1. Add validation blocks for constrained variables (`AllowedValues` equivalents). +1. Mark secret variables with `sensitive = true` — never hardcode them in `.tf` files or committed `.tfvars`. +1. Add `description` to every output; mark secret outputs `sensitive = true`. + +## Naming and tagging + +1. Use `locals` to construct name prefixes and centralise tag maps. +1. Name physical resources with `"${local.name_prefix}-<role>"` to ensure cross-stack uniqueness. +1. Apply a common tag map (`local.common_tags`) to every taggable resource; include at minimum `Environment` and `ManagedBy = "terraform"`. + +## Security + +1. Block public access on all S3 buckets unless intentionally public; document the exception. +1. Enable `storage_encrypted = true` and `deletion_protection = true` on all RDS instances. +1. Restrict security group rules — avoid `0.0.0.0/0` on management ports; add a comment when HTTPS/443 is open. +1. Apply least-privilege IAM policies — no `*` actions on `*` resources. +1. Enable KMS key rotation (`enable_key_rotation = true`). + +## Tooling + +1. Run `terraform fmt -check -recursive` in CI and auto-format locally. +1. Run `terraform validate` before every plan. +1. Run `tfsec` or `checkov` on all changes; fix HIGH and CRITICAL findings before merging. + +## References + +> Always use the official documentation for the provider and Terraform version in use — resource arguments and defaults change between provider releases. + +- [Terraform documentation](https://developer.hashicorp.com/terraform/docs) +- [Terraform provider registry](https://registry.terraform.io/) +- [tfsec](https://aquasecurity.github.io/tfsec/) · [checkov](https://www.checkov.io/) diff --git a/src/vstack/_templates/instructions/terragrunt/config.yaml b/src/vstack/_templates/instructions/terragrunt/config.yaml new file mode 100644 index 0000000..aad09b9 --- /dev/null +++ b/src/vstack/_templates/instructions/terragrunt/config.yaml @@ -0,0 +1,4 @@ +name: terragrunt +description: Terragrunt coding conventions for projects. Use when writing or reviewing Terragrunt HCL configurations, root configs, unit modules, and dependency blocks. +applyTo: "**/terragrunt.hcl" +version: 20260502035 diff --git a/src/vstack/_templates/instructions/terragrunt/template.md b/src/vstack/_templates/instructions/terragrunt/template.md new file mode 100644 index 0000000..3363e57 --- /dev/null +++ b/src/vstack/_templates/instructions/terragrunt/template.md @@ -0,0 +1,52 @@ +Use these Terragrunt conventions in this project. + +## Structure and hierarchy + +1. Maintain a strict directory hierarchy that maps to deployment topology: `infra/<env>/<unit>/terragrunt.hcl`. +1. Keep one root `terragrunt.hcl` at the repository root or top-level `infra/` directory; inherit it in all units via `include "root" { path = find_in_parent_folders() }`. +1. Use `account.hcl` files at the account/environment level for account ID, region, and environment name — read them with `read_terragrunt_config(find_in_parent_folders("account.hcl"))`. + +## Remote state and backend generation + +1. Generate `backend.tf` from the root `remote_state` block — never hand-write backend files in units. +1. Use `path_relative_to_include()` as the state key so each unit gets a unique, auto-named state file. +1. Enable encryption and state locking on the S3 backend; enable versioning on the state bucket. + +## Provider generation + +1. Generate `provider.tf` from the root `generate "provider"` block — never duplicate provider configuration across units. +1. Include `default_tags` in the generated provider block to ensure consistent tagging across all resources. + +## Module sources and pinning + +1. Pin all module sources to a specific git ref or registry semver tag — never `?ref=main` or floating tags. +1. Prefer sourcing from a versioned internal registry or tagged git commit over local paths in shared modules. + +## Dependency blocks + +1. Add `mock_outputs` to every `dependency` block for the `validate` and `plan` commands — this allows planning without deploying dependencies first. +1. Declare only the outputs you actually use from a dependency; do not expose the full output set. +1. Keep `dependency` blocks at unit level — do not express dependencies in the root config. + +## DRY inputs + +1. Extract shared inputs for an ecosystem (e.g. RDS defaults) into `_envcommon/<name>.hcl`; load with `read_terragrunt_config`. +1. Use `merge(local.common.inputs, { ... })` to override defaults per environment — do not copy-paste full input maps. + +## CI/CD + +1. Always pass `--terragrunt-non-interactive` in automated pipelines to prevent interactive prompts. +1. Use `--terragrunt-parallelism` to control concurrency; start with 4 and adjust to pipeline resource limits. +1. Add `.terragrunt-cache/` to `.gitignore`. + +## Secrets + +1. Never hardcode secrets in `.hcl` files — supply them via environment variables (`TF_VAR_*`) or a secrets manager data source. +1. Do not commit `.tfvars` files containing real secrets. + +## References + +> Always use the official documentation for the Terragrunt version in use — built-in functions and CLI flags evolve with each release. + +- [Terragrunt documentation](https://terragrunt.gruntwork.io/docs/) +- [Terragrunt CLI reference](https://terragrunt.gruntwork.io/docs/reference/cli-options/) diff --git a/src/vstack/_templates/instructions/testing/config.yaml b/src/vstack/_templates/instructions/testing/config.yaml new file mode 100644 index 0000000..f95a88d --- /dev/null +++ b/src/vstack/_templates/instructions/testing/config.yaml @@ -0,0 +1,4 @@ +name: testing +description: Test authoring conventions for any language or framework. Use when writing or reviewing tests, test plans, or test coverage decisions. +applyTo: "**/*" +version: 20260502004 diff --git a/src/vstack/_templates/instructions/testing/template.md b/src/vstack/_templates/instructions/testing/template.md new file mode 100644 index 0000000..c533285 --- /dev/null +++ b/src/vstack/_templates/instructions/testing/template.md @@ -0,0 +1,38 @@ +Use these testing conventions in this project. + +## Scope and intent + +1. Write tests to verify observable behavior, not internal implementation details. +1. A test that passes when behavior is wrong, or fails when behavior is correct, has negative value. +1. Tests are documentation — a reader should understand what the system does by reading the test. + +## Naming and structure + +1. Name tests to describe what they verify: what the subject does, under what condition, and what the expected outcome is. +1. Keep each test focused on one behavior; avoid asserting unrelated outcomes in a single test. +1. Group related tests together; separate unrelated test concerns into distinct test units. + +## Coverage and completeness + +1. Cover the success path, expected failure paths, and boundary conditions for every behavioral change. +1. Treat missing tests for changed behavior as a defect — a change without tests is not complete. +1. Do not chase a coverage number; cover behaviors that matter rather than lines that exist. + +## Test quality + +1. Make tests deterministic — a test that passes or fails non-deterministically is unreliable and must be fixed. +1. Keep tests independent; no test should depend on execution order or shared mutable state. +1. Prefer clear, direct assertions over indirect checks; assert the outcome, not the path to it. +1. Avoid logic (loops, conditionals) in tests; if a test needs logic, split it into multiple focused tests. + +## Test boundaries + +1. Use unit tests for isolated logic; use integration tests when behavior crosses component or service boundaries. +1. Mock or stub only what is necessary to isolate the subject; avoid over-mocking that disconnects the test from real behavior. +1. Test contracts and interfaces, not just internal units — what the caller observes is what matters. + +## Maintenance + +1. Update tests in the same change as the behavior they cover. +1. Remove tests that no longer reflect real behavior rather than commenting them out. +1. Treat flaky tests as bugs; do not merge code with known test reliability issues. diff --git a/src/vstack/_templates/instructions/typescript/config.yaml b/src/vstack/_templates/instructions/typescript/config.yaml new file mode 100644 index 0000000..d86de16 --- /dev/null +++ b/src/vstack/_templates/instructions/typescript/config.yaml @@ -0,0 +1,4 @@ +name: typescript +description: TypeScript coding conventions for projects. Use when writing or reviewing TypeScript or JavaScript modules, components, and package internals. +applyTo: "**/*.{ts,tsx,js,jsx,mts,cts,mjs,cjs}" +version: 20260502005 diff --git a/src/vstack/_templates/instructions/typescript/template.md b/src/vstack/_templates/instructions/typescript/template.md new file mode 100644 index 0000000..c97bcf2 --- /dev/null +++ b/src/vstack/_templates/instructions/typescript/template.md @@ -0,0 +1,44 @@ +Use these TypeScript conventions in this project. + +## Type safety + +1. Enable and respect strict mode; do not disable strictness per-file without a documented reason. +1. Avoid `any`; prefer `unknown` when the type is genuinely unknown and narrow it explicitly. +1. Prefer `interface` for object shapes that may be extended; use `type` for unions, intersections, and aliases. +1. Do not use type assertions (`as`) to silence type errors; fix the type instead. + +## Design and readability + +1. Prefer explicit, domain-meaningful names over abbreviations. +1. Keep functions focused; split functions that mix parsing, I/O, and business rules. +1. Prefer straightforward control flow over clever one-liners. +1. Use `const` by default; use `let` only when reassignment is required; never use `var`. + +## Null and undefined + +1. Prefer `undefined` over `null` for absent optional values unless an API contract requires `null`. +1. Use optional chaining (`?.`) and nullish coalescing (`??`) rather than manual null guards. +1. Do not suppress non-null assertions (`!`) unless the value is provably non-null and the reason is documented. + +## Modules and imports + +1. Use named exports by default; use default exports only when the module clearly has a single entry point. +1. Keep imports minimal and remove unused imports. +1. Avoid circular dependencies; if they appear, treat them as a structural design problem. + +## Async and error handling + +1. Prefer `async/await` over raw promise chains for readability. +1. Always handle or propagate rejected promises; never silently swallow errors. +1. Use typed error boundaries where the runtime supports them. + +## Testing and verification + +1. Add or update tests for every behavioral change. +1. Keep tests independent of implementation details; test observable behavior. +1. Cover success paths, edge cases, and expected failures. + +## Tooling alignment + +1. Keep code compatible with the repository's linting and type-checking configuration. +1. Do not suppress lint or type errors with inline disable comments unless there is a documented, task-specific reason. diff --git a/src/vstack/_templates/prompts/api-design-review/config.yaml b/src/vstack/_templates/prompts/api-design-review/config.yaml new file mode 100644 index 0000000..fe5e583 --- /dev/null +++ b/src/vstack/_templates/prompts/api-design-review/config.yaml @@ -0,0 +1,9 @@ +name: api-design-review +description: Review an API design or OpenAPI spec for correctness, completeness, and consistency. +argument-hint: "[OpenAPI spec file, design doc, or endpoint scope]" +agent: designer +model: GPT-5.3-Codex (copilot) +tools: + - read + - search +version: 20260502006 diff --git a/src/vstack/_templates/prompts/api-design-review/template.md b/src/vstack/_templates/prompts/api-design-review/template.md new file mode 100644 index 0000000..6f21b21 --- /dev/null +++ b/src/vstack/_templates/prompts/api-design-review/template.md @@ -0,0 +1,45 @@ +Review the provided API design or OpenAPI specification for correctness, completeness, and consistency. + +Focus on issues that affect consumers: breaking contracts, ambiguous semantics, missing error cases, and inconsistent conventions. +Do not focus on implementation details or tooling preferences. + +Output exactly in this format: + +## Contract Issues + +List problems that would break or confuse consumers. + +For each item: + +- endpoint or field reference +- what the problem is in one sentence +- concrete fix + +## Naming and Consistency + +List naming violations, inconsistencies across endpoints, and deviations from REST conventions. + +## Missing Error Cases + +List expected error responses that are undocumented or missing status codes (400, 401, 403, 404, 409, 422, 500). + +## Schema Completeness + +List fields or objects that are missing required constraints, descriptions, or examples. + +## Versioning and Compatibility + +- versioning strategy present: yes | no | partial +- breaking changes relative to previous version: yes | no | unknown +- backward compatibility risk: low | medium | high + +## Security Scheme Check + +- authentication documented: yes | no +- authorization scopes documented where relevant: yes | no | partial +- sensitive fields handled appropriately: yes | no | partial + +## Verdict + +- approve | approve-with-conditions | reject +- top priority fix in one sentence diff --git a/src/vstack/_templates/prompts/architecture-risk/config.yaml b/src/vstack/_templates/prompts/architecture-risk/config.yaml new file mode 100644 index 0000000..2d19754 --- /dev/null +++ b/src/vstack/_templates/prompts/architecture-risk/config.yaml @@ -0,0 +1,9 @@ +name: architecture-risk +description: Identify architectural risks, tradeoffs, and mitigation priorities for a proposed design. +argument-hint: "[design doc, ADR, or architecture scope]" +agent: architect +model: GPT-5.3-Codex (copilot) +tools: + - read + - search +version: 20260502007 diff --git a/src/vstack/_templates/prompts/architecture-risk/template.md b/src/vstack/_templates/prompts/architecture-risk/template.md new file mode 100644 index 0000000..bf63354 --- /dev/null +++ b/src/vstack/_templates/prompts/architecture-risk/template.md @@ -0,0 +1,42 @@ +Evaluate the provided architecture for delivery and runtime risk. + +Prioritize issues that could cause outages, data loss, severe operability pain, or major rework. +Do not focus on stylistic preferences. + +Output exactly in this format: + +## High-Severity Risks + +List risks that can materially fail production or block safe delivery. + +For each risk: + +- impacted boundary (service, data, contract, deployment, observability, security) +- why it is risky in one sentence +- mitigation with smallest viable change +- owner role + +## Medium Risks + +List important but non-blocking risks. + +## Tradeoff Notes + +List major tradeoffs and what is being optimized. + +## Missing Decisions + +List decisions that should become ADRs before implementation. + +## Recommended Sequence + +Provide an ordered mitigation sequence (step 1..N). + +## Security Considerations + +List security-specific risks not covered above: auth boundaries, sensitive data exposure, trust model assumptions, supply chain concerns. + +## Go/No-Go + +- go | conditional-go | no-go +- one-sentence rationale diff --git a/src/vstack/_templates/prompts/code-review/config.yaml b/src/vstack/_templates/prompts/code-review/config.yaml index 446a352..b0bc075 100644 --- a/src/vstack/_templates/prompts/code-review/config.yaml +++ b/src/vstack/_templates/prompts/code-review/config.yaml @@ -7,4 +7,4 @@ tools: - read - search - edit -version: 0.1.0 +version: 20260502008 diff --git a/src/vstack/_templates/prompts/code-review/template.md b/src/vstack/_templates/prompts/code-review/template.md index dd69021..c44a8fa 100644 --- a/src/vstack/_templates/prompts/code-review/template.md +++ b/src/vstack/_templates/prompts/code-review/template.md @@ -7,6 +7,7 @@ Focus only on issues with real impact: - performance and scalability - maintainability and ownership boundaries - missing tests for changed behavior +- API contract changes: breaking changes, schema drift, missing versioning Ignore: diff --git a/src/vstack/_templates/prompts/dependency-audit/config.yaml b/src/vstack/_templates/prompts/dependency-audit/config.yaml new file mode 100644 index 0000000..506a9c0 --- /dev/null +++ b/src/vstack/_templates/prompts/dependency-audit/config.yaml @@ -0,0 +1,9 @@ +name: dependency-audit +description: Audit dependencies for vulnerabilities, outdated versions, licence risks, and supply chain hygiene. +argument-hint: "[dependency manifest, lockfile, or package scope]" +agent: tester +model: GPT-5.3-Codex (copilot) +tools: + - read + - search +version: 20260502009 diff --git a/src/vstack/_templates/prompts/dependency-audit/template.md b/src/vstack/_templates/prompts/dependency-audit/template.md new file mode 100644 index 0000000..b403323 --- /dev/null +++ b/src/vstack/_templates/prompts/dependency-audit/template.md @@ -0,0 +1,50 @@ +Audit the provided dependency manifest or lockfile for vulnerabilities, outdated packages, licence risks, and supply chain hygiene. + +Prefer evidence from the manifest itself; flag items that require external verification. + +Output exactly in this format: + +## Vulnerabilities + +List dependencies with known CVEs or security advisories. + +For each item: + +- package name and version +- CVE or advisory reference if known +- severity: critical | high | medium | low +- recommended action (upgrade, replace, or accept with rationale) + +## Outdated Packages + +List dependencies that are significantly behind their latest stable release and carry meaningful risk. +Do not list minor version differences without impact. + +For each item: + +- package name: current version → latest stable +- risk of staying on current version in one sentence + +## Licence Risks + +List licences that may conflict with the project's distribution model. + +For each item: + +- package name +- licence identifier +- conflict or concern in one sentence + +## Pinning and Version Policy + +- all direct dependencies pinned: yes | no | partial +- unpinned transitive dependencies with risk: list or none +- version ranges that allow breaking upgrades: list or none + +## Supply Chain Hygiene + +List packages with unusual provenance concerns: abandoned maintainers, single-maintainer with no backup, recent ownership transfers, or typosquatting risk. + +## Recommended Actions + +Ordered list of actions by priority (critical first). diff --git a/src/vstack/_templates/prompts/incident-timeline/config.yaml b/src/vstack/_templates/prompts/incident-timeline/config.yaml new file mode 100644 index 0000000..e542efa --- /dev/null +++ b/src/vstack/_templates/prompts/incident-timeline/config.yaml @@ -0,0 +1,9 @@ +name: incident-timeline +description: Build a structured, evidence-based incident timeline and action-oriented postmortem summary. +argument-hint: "[logs, alerts, timeline notes, or incident ID]" +agent: tester +model: GPT-5.3-Codex (copilot) +tools: + - read + - search +version: 20260502010 diff --git a/src/vstack/_templates/prompts/incident-timeline/template.md b/src/vstack/_templates/prompts/incident-timeline/template.md new file mode 100644 index 0000000..9806de4 --- /dev/null +++ b/src/vstack/_templates/prompts/incident-timeline/template.md @@ -0,0 +1,47 @@ +Construct a blameless incident timeline from the provided evidence. + +Anchor claims to available logs, alerts, traces, and change events. +If evidence is missing, explicitly mark uncertainty. + +Output exactly in this format: + +## Incident Snapshot + +- incident title +- impact window +- affected systems/users +- current status + +## Timeline (UTC) + +List timestamped events in order. + +For each event: + +- time +- event description +- evidence source +- confidence: high | medium | low + +## Root Cause Analysis + +- primary cause +- contributing factors +- what made detection/recovery slower + +## What Worked / What Failed + +Two short lists. + +## Corrective Actions + +For each action: + +- action description +- owner role +- priority: P0 | P1 | P2 +- due expectation (short horizon) + +## Prevention Check + +List the minimum controls needed to reduce repeat probability. diff --git a/src/vstack/_templates/prompts/migration-safety/config.yaml b/src/vstack/_templates/prompts/migration-safety/config.yaml new file mode 100644 index 0000000..1de25cc --- /dev/null +++ b/src/vstack/_templates/prompts/migration-safety/config.yaml @@ -0,0 +1,10 @@ +name: migration-safety +description: Review database migration safety, rollback strategy, and zero-downtime risk. +argument-hint: "[migration files, schema, or rollout plan]" +agent: engineer +model: GPT-5.3-Codex (copilot) +tools: + - read + - search + - edit +version: 20260502011 diff --git a/src/vstack/_templates/prompts/migration-safety/template.md b/src/vstack/_templates/prompts/migration-safety/template.md new file mode 100644 index 0000000..912b7d0 --- /dev/null +++ b/src/vstack/_templates/prompts/migration-safety/template.md @@ -0,0 +1,41 @@ +Review the selected migration plan and code for production safety. + +Focus on forward compatibility, rollback feasibility, data integrity, and operational risk. +Assume a live system with concurrent reads/writes. + +Output exactly in this format: + +## Must Fix Before Apply + +List migration blockers. + +For each item: + +- file/section +- failure mode in one sentence +- concrete safe fix + +## Should Fix Soon + +List non-blocking risks with meaningful impact. + +## Rollback Plan Check + +- rollback feasible: yes | no | partial +- missing rollback prerequisites +- specific rollback procedure recommendation + +## Zero-Downtime Check + +- compatible with old and new app versions: yes | no | partial +- lock/contention risk: low | medium | high +- required phased rollout steps + +## Test Gaps + +List missing migration tests (forward, backward, data invariants, load-sensitive paths). + +## Final Recommendation + +- apply now | apply after fixes +- biggest remaining risk in one sentence diff --git a/src/vstack/_templates/prompts/release-readiness/config.yaml b/src/vstack/_templates/prompts/release-readiness/config.yaml new file mode 100644 index 0000000..99317cc --- /dev/null +++ b/src/vstack/_templates/prompts/release-readiness/config.yaml @@ -0,0 +1,9 @@ +name: release-readiness +description: Evaluate release readiness from reports, risks, and unresolved blockers. +argument-hint: "[scope, release date, or branch]" +agent: release +model: GPT-5.3-Codex (copilot) +tools: + - read + - search +version: 20260502012 diff --git a/src/vstack/_templates/prompts/release-readiness/template.md b/src/vstack/_templates/prompts/release-readiness/template.md new file mode 100644 index 0000000..b70da7a --- /dev/null +++ b/src/vstack/_templates/prompts/release-readiness/template.md @@ -0,0 +1,36 @@ +Assess whether this change set is ready to release. + +Review product, architecture, design, test, security, and performance evidence. +Prefer evidence-based findings tied to concrete artifacts. + +Output exactly in this format: + +## Release Gate Verdict + +- Verdict: READY | READY-WITH-CONDITIONS | NOT-READY +- Confidence: high | medium | low +- Scope assessed: one sentence + +## Blocking Issues + +List only release-blocking items. + +For each item: + +- artifact or file reference +- why this blocks release in one sentence +- concrete unblock action +- owner role (product | architect | designer | engineer | tester | release) + +## Conditions Before Release + +List non-blocking but mandatory follow-ups to ship safely. + +## Evidence Reviewed + +List the exact artifacts checked (reports, docs, CI evidence, manifests). +For each expected artifact that is missing, flag it explicitly as: MISSING — [artifact name]. + +## Recommended Next Action + +One clear next step for the team. diff --git a/src/vstack/_templates/skills/adr/config.yaml b/src/vstack/_templates/skills/adr/config.yaml index 8ef8bbc..912219f 100644 --- a/src/vstack/_templates/skills/adr/config.yaml +++ b/src/vstack/_templates/skills/adr/config.yaml @@ -1,5 +1,5 @@ name: adr -version: 1.0.2 +version: 20260421003 description: | Architecture Decision Record writing. Documents a significant architectural decision with context, alternatives considered, rationale, and impact. diff --git a/src/vstack/_templates/skills/adr/template.md b/src/vstack/_templates/skills/adr/template.md index 715dc5c..d04e6d7 100644 --- a/src/vstack/_templates/skills/adr/template.md +++ b/src/vstack/_templates/skills/adr/template.md @@ -12,8 +12,6 @@ what was decided, why, and what alternatives were considered. - Implementation (engineering role) - Running analysis to inform the decision (use `analyse`) -______________________________________________________________________ - ## Step 0: Context Gathering Read existing ADRs and architecture docs: @@ -27,8 +25,6 @@ ls docs/architecture/adr/*.md 2>/dev/null | grep -oE '[0-9]+' | sort -n | tail - Determine the next ADR number (pad to 3 digits: 001, 002, ...). -______________________________________________________________________ - ## Step 1: Understand the Decision > **Question:** What decision are we recording? @@ -43,8 +39,6 @@ Status: proposed | accepted | rejected | deprecated | superseded Date: YYYY-MM-DD ``` -______________________________________________________________________ - ## Step 2: Context Why does this decision need to be made? What forces are at play? @@ -61,8 +55,6 @@ Include: [2-4 paragraphs explaining the situation, constraints, and why this matters] ``` -______________________________________________________________________ - ## Step 3: Alternatives Considered List all serious options that were evaluated. For each: @@ -79,8 +71,6 @@ List all serious options that were evaluated. For each: Include at least 2-3 alternatives. Including a "do nothing" option is recommended. -______________________________________________________________________ - ## Step 4: Decision State the chosen option clearly: @@ -92,8 +82,6 @@ We will [chosen option]. [1-2 sentences on why this option was selected over alternatives] ``` -______________________________________________________________________ - ## Step 5: Rationale Explain the reasoning in depth: @@ -104,8 +92,6 @@ Explain the reasoning in depth: Reference specific cons from rejected options and explain why they were acceptable tradeoffs.] ``` -______________________________________________________________________ - ## Step 6: Consequences & Impact ```markdown @@ -121,8 +107,6 @@ ______________________________________________________________________ - [What could go wrong, and how we'd detect or mitigate it] ``` -______________________________________________________________________ - ## Step 7: Related Decisions ```markdown @@ -130,8 +114,6 @@ ______________________________________________________________________ - ADR-NNN: [title] — [relationship: supersedes / related to / depends on] ``` -______________________________________________________________________ - ## Output: ADR file Write to `docs/architecture/adr/NNN-<slug>.md` where NNN is the next available number and slug @@ -163,5 +145,3 @@ is a kebab-case title. ``` After writing, state the file path and summary so the architect or product role can review. - -______________________________________________________________________ diff --git a/src/vstack/_templates/skills/analyse/config.yaml b/src/vstack/_templates/skills/analyse/config.yaml index 143daa1..b7d5f98 100644 --- a/src/vstack/_templates/skills/analyse/config.yaml +++ b/src/vstack/_templates/skills/analyse/config.yaml @@ -1,5 +1,5 @@ name: analyse -version: 1.0.2 +version: 20260421004 description: | Cross-cutting technical analysis. Investigates impact, tradeoffs, root causes, or feasibility without implementing changes. Use when asked to "analyse this", diff --git a/src/vstack/_templates/skills/analyse/template.md b/src/vstack/_templates/skills/analyse/template.md index 6823c3d..9b1c130 100644 --- a/src/vstack/_templates/skills/analyse/template.md +++ b/src/vstack/_templates/skills/analyse/template.md @@ -15,8 +15,6 @@ analysis report. Do not implement changes — that is engineering role work. - Implementation (engineering role) - Full test run (use `verify`) -______________________________________________________________________ - ## Step 0: Define the Question Clarify exactly what is being analysed: @@ -38,8 +36,6 @@ Question: [Precise question being answered] Scope: [What's in and out of scope for this analysis] ``` -______________________________________________________________________ - ## Phase 1: Evidence Gathering Gather all relevant context before drawing any conclusions: @@ -72,8 +68,6 @@ For **dependency analysis**: [ -f package.json ] && npx madge --circular --extensions ts ./src 2>/dev/null || true ``` -______________________________________________________________________ - ## Phase 2: Dimension Analysis Structure the analysis around the relevant dimensions for the question type: @@ -119,8 +113,6 @@ For each option: | ---- | --------------- | --------------- | ---------- | | ... | High/Medium/Low | High/Medium/Low | ... | -______________________________________________________________________ - ## Phase 3: Data & Evidence Support findings with concrete evidence: @@ -136,8 +128,6 @@ Reference specific: - Data points (error counts, latency numbers, test results) - Documentation (ADRs, design docs, API specs) -______________________________________________________________________ - ## Phase 4: Findings & Conclusions Present findings clearly: @@ -158,8 +148,6 @@ State conclusions with confidence level: - **Probable:** well-supported by evidence but not confirmed - **Uncertain:** hypothesis that requires further investigation -______________________________________________________________________ - ## Analysis Report ```text @@ -184,5 +172,3 @@ ______________________________________________________________________ ### Confidence [Overall confidence level: high / medium / low — and why] ``` - -______________________________________________________________________ diff --git a/src/vstack/_templates/skills/architecture/config.yaml b/src/vstack/_templates/skills/architecture/config.yaml index 6bb94b9..585a286 100644 --- a/src/vstack/_templates/skills/architecture/config.yaml +++ b/src/vstack/_templates/skills/architecture/config.yaml @@ -1,5 +1,5 @@ name: architecture -version: 1.0.2 +version: 20260421005 description: | Engineering-lead plan review. Lock in the execution plan — service boundaries, data models, API contracts, error handling, test strategy, diff --git a/src/vstack/_templates/skills/architecture/template.md b/src/vstack/_templates/skills/architecture/template.md index 99eb685..f4500f0 100644 --- a/src/vstack/_templates/skills/architecture/template.md +++ b/src/vstack/_templates/skills/architecture/template.md @@ -209,5 +209,3 @@ For each significant structural decision made during this review (technology cho - Write an ADR via `@#adr`. - Cross-reference related ADRs. - Update `docs/architecture/architecture.md` to reflect the final decisions. - -______________________________________________________________________ diff --git a/src/vstack/_templates/skills/aws-cli/config.yaml b/src/vstack/_templates/skills/aws-cli/config.yaml new file mode 100644 index 0000000..4d00d35 --- /dev/null +++ b/src/vstack/_templates/skills/aws-cli/config.yaml @@ -0,0 +1,17 @@ +name: aws-cli +version: 20260502033 +description: | + AWS CLI command reference and workflow patterns for backend engineers. + Covers IAM, EC2, S3, RDS, ECS, Lambda, CloudWatch, Secrets Manager, + SSM Parameter Store, and cross-account operations. Use when asked to + "query AWS", "list resources", "rotate secrets", "check CloudWatch logs", + "scale ECS", "run an SSM command", or "script an AWS operation". +argument-hint: '[service: iam | ec2 | s3 | rds | ecs | lambda | cloudwatch | ssm | secrets]' + +license: MIT +compatibility: Requires AWS CLI v2 installed and configured (aws configure or environment variables). IAM permissions vary by operation — principle of least privilege applies. +metadata: + owner: vstack + maturity: stable +user-invocable: true +disable-model-invocation: false diff --git a/src/vstack/_templates/skills/aws-cli/template.md b/src/vstack/_templates/skills/aws-cli/template.md new file mode 100644 index 0000000..3b2fe28 --- /dev/null +++ b/src/vstack/_templates/skills/aws-cli/template.md @@ -0,0 +1,341 @@ +{{SKILL_CONTEXT}} + +# aws-cli — AWS CLI Workflows + +Common AWS CLI patterns for backend and platform engineering tasks. +All commands use `--output json` unless noted; add `--profile <profile>` for +named profiles and `--region <region>` to override the configured default. + +## Safety rules + +- Always run `aws ... --dry-run` for EC2 operations before executing +- Never hardcode access keys; use IAM roles, `aws configure`, or environment variables +- For destructive operations (delete, terminate, drop), use `--no-cli-pager` and + pipe through `jq` to verify the target list before proceeding +- Use `--query` and `--filters` to narrow scope before running bulk mutations + +## Step 0: Setup and Diagnostics + +```bash +# Check version and active identity +aws --version +aws sts get-caller-identity + +# List configured profiles +aws configure list-profiles + +# Use a named profile for a command +aws s3 ls --profile prod + +# Assume a role (cross-account) +aws sts assume-role \ + --role-arn arn:aws:iam::123456789012:role/DeployRole \ + --role-session-name deploy-session \ + --query 'Credentials.[AccessKeyId,SecretAccessKey,SessionToken]' \ + --output text +``` + +## IAM + +```bash +# List all IAM users +aws iam list-users --query 'Users[*].[UserName,CreateDate]' --output table + +# Show a user's attached policies +aws iam list-attached-user-policies --user-name alice + +# List all roles +aws iam list-roles --query 'Roles[*].[RoleName,Arn]' --output table + +# Show a role's trust policy +aws iam get-role --role-name MyRole --query 'Role.AssumeRolePolicyDocument' + +# List all policies attached to a role +aws iam list-attached-role-policies --role-name MyRole + +# Simulate a policy (check if action is allowed) +aws iam simulate-principal-policy \ + --policy-source-arn arn:aws:iam::123456789012:role/MyRole \ + --action-names s3:GetObject \ + --resource-arns arn:aws:s3:::my-bucket/* + +# Rotate an access key +aws iam create-access-key --user-name alice +aws iam delete-access-key --user-name alice --access-key-id AKIA... +``` + +## S3 + +```bash +# List buckets +aws s3 ls + +# List objects in a bucket (with sizes) +aws s3 ls s3://my-bucket/ --human-readable --recursive | tail -20 + +# Sync local directory to S3 +aws s3 sync ./dist s3://my-bucket/static --delete + +# Copy with server-side encryption +aws s3 cp secret.txt s3://my-bucket/secret.txt --sse aws:kms --sse-kms-key-id alias/my-key + +# Check bucket public access block settings +aws s3api get-public-access-block --bucket my-bucket + +# Check bucket encryption +aws s3api get-bucket-encryption --bucket my-bucket + +# Empty and delete a bucket (destructive) +aws s3 rm s3://my-bucket/ --recursive +aws s3 rb s3://my-bucket +``` + +## EC2 + +```bash +# List running instances +aws ec2 describe-instances \ + --filters "Name=instance-state-name,Values=running" \ + --query 'Reservations[*].Instances[*].[InstanceId,InstanceType,PrivateIpAddress,Tags[?Key==`Name`].Value|[0]]' \ + --output table + +# Start / stop instance +aws ec2 start-instances --instance-ids i-0123456789abcdef0 +aws ec2 stop-instances --instance-ids i-0123456789abcdef0 + +# Get console output (useful when SSH is unavailable) +aws ec2 get-console-output --instance-id i-0123456789abcdef0 --output text + +# List security groups with their rules +aws ec2 describe-security-groups \ + --query 'SecurityGroups[*].[GroupId,GroupName,Description]' \ + --output table + +# Show inbound rules for a security group +aws ec2 describe-security-groups \ + --group-ids sg-12345678 \ + --query 'SecurityGroups[0].IpPermissions' +``` + +## RDS + +```bash +# List all RDS instances +aws rds describe-db-instances \ + --query 'DBInstances[*].[DBInstanceIdentifier,DBInstanceStatus,Engine,EngineVersion,MultiAZ]' \ + --output table + +# Check pending maintenance +aws rds describe-pending-maintenance-actions \ + --query 'PendingMaintenanceActions[*].[ResourceIdentifier,PendingMaintenanceActionDetails[0].Action]' \ + --output table + +# Create a manual snapshot before risky operations +aws rds create-db-snapshot \ + --db-instance-identifier myapp-prod \ + --db-snapshot-identifier myapp-prod-pre-migration-$(date +%Y%m%d) + +# List snapshots +aws rds describe-db-snapshots \ + --db-instance-identifier myapp-prod \ + --query 'DBSnapshots[*].[DBSnapshotIdentifier,SnapshotCreateTime,Status]' \ + --output table + +# Modify instance class (requires reboot) +aws rds modify-db-instance \ + --db-instance-identifier myapp-staging \ + --db-instance-class db.t3.large \ + --apply-immediately +``` + +## ECS + +```bash +# List clusters and services +aws ecs list-clusters +aws ecs list-services --cluster myapp-prod + +# Describe a service +aws ecs describe-services \ + --cluster myapp-prod \ + --services myapp-api \ + --query 'services[0].[serviceName,status,runningCount,desiredCount,taskDefinition]' + +# Force new deployment (rolling update) +aws ecs update-service \ + --cluster myapp-prod \ + --service myapp-api \ + --force-new-deployment + +# Scale a service +aws ecs update-service \ + --cluster myapp-prod \ + --service myapp-api \ + --desired-count 4 + +# List running tasks +aws ecs list-tasks --cluster myapp-prod --service-name myapp-api + +# Get task IP for debugging +aws ecs describe-tasks \ + --cluster myapp-prod \ + --tasks <task-arn> \ + --query 'tasks[0].attachments[0].details' +``` + +## Lambda + +```bash +# List functions +aws lambda list-functions \ + --query 'Functions[*].[FunctionName,Runtime,LastModified]' \ + --output table + +# Invoke a function synchronously +aws lambda invoke \ + --function-name myapp-processor \ + --payload '{"key":"value"}' \ + --cli-binary-format raw-in-base64-out \ + response.json && cat response.json + +# Get function configuration +aws lambda get-function-configuration --function-name myapp-processor + +# Update function code from a zip +aws lambda update-function-code \ + --function-name myapp-processor \ + --zip-file fileb://function.zip + +# Tail recent log output via CloudWatch +aws logs tail /aws/lambda/myapp-processor --follow +``` + +## CloudWatch Logs + +```bash +# List log groups +aws logs describe-log-groups \ + --query 'logGroups[*].[logGroupName,retentionInDays]' \ + --output table + +# Tail a log group in real time +aws logs tail /aws/ecs/myapp --follow --format short + +# Query logs (Insights) +aws logs start-query \ + --log-group-name /aws/ecs/myapp \ + --start-time $(date -d '1 hour ago' +%s) \ + --end-time $(date +%s) \ + --query-string 'fields @timestamp, @message | filter @message like /ERROR/ | sort @timestamp desc | limit 50' + +# Get query results +aws logs get-query-results --query-id <query-id> + +# Get recent log events from a stream +aws logs get-log-events \ + --log-group-name /aws/ecs/myapp \ + --log-stream-name ecs/myapp-api/abc123 \ + --limit 50 \ + --query 'events[*].[timestamp,message]' \ + --output table +``` + +## Secrets Manager + +```bash +# List secrets +aws secretsmanager list-secrets \ + --query 'SecretList[*].[Name,LastChangedDate]' \ + --output table + +# Get a secret value +aws secretsmanager get-secret-value \ + --secret-id myapp/prod/db_password \ + --query 'SecretString' \ + --output text + +# Rotate a secret (triggers the rotation Lambda) +aws secretsmanager rotate-secret \ + --secret-id myapp/prod/db_password + +# Create a new secret +aws secretsmanager create-secret \ + --name myapp/prod/api_key \ + --description "Third-party API key" \ + --secret-string '{"api_key":"<value>"}' + +# Update an existing secret +aws secretsmanager put-secret-value \ + --secret-id myapp/prod/api_key \ + --secret-string '{"api_key":"<new-value>"}' +``` + +## SSM Parameter Store + +```bash +# List parameters by path +aws ssm get-parameters-by-path \ + --path /myapp/prod/ \ + --with-decryption \ + --query 'Parameters[*].[Name,Type,LastModifiedDate]' \ + --output table + +# Get a single parameter +aws ssm get-parameter \ + --name /myapp/prod/db_host \ + --with-decryption \ + --query 'Parameter.Value' \ + --output text + +# Put a parameter (SecureString uses KMS) +aws ssm put-parameter \ + --name /myapp/prod/db_password \ + --type SecureString \ + --value 'mysecretpassword' \ + --key-id alias/myapp-key \ + --overwrite + +# Run a command on EC2 instances via SSM (no SSH required) +aws ssm send-command \ + --document-name "AWS-RunShellScript" \ + --targets "Key=tag:Name,Values=myapp-worker" \ + --parameters 'commands=["systemctl status myapp"]' \ + --query 'Command.CommandId' \ + --output text + +# Get command output +aws ssm get-command-invocation \ + --command-id <command-id> \ + --instance-id i-0123456789abcdef0 \ + --query '[StandardOutputContent,StandardErrorContent]' +``` + +## Cost and Usage + +```bash +# Show current month cost by service (requires Cost Explorer enabled) +aws ce get-cost-and-usage \ + --time-period Start=$(date +%Y-%m-01),End=$(date +%Y-%m-%d) \ + --granularity MONTHLY \ + --metrics BlendedCost \ + --group-by Type=DIMENSION,Key=SERVICE \ + --query 'ResultsByTime[0].Groups[*].[Keys[0],Metrics.BlendedCost.Amount]' \ + --output table | sort -k2 -rn | head -20 +``` + +## Review Checklist + +- [ ] No access keys hardcoded in scripts — use IAM roles or `aws configure` +- [ ] Destructive commands scoped with `--filters` or explicit resource IDs before running +- [ ] Secrets retrieved from Secrets Manager or SSM — not passed as CLI arguments +- [ ] `--dry-run` used for EC2 mutation operations before executing +- [ ] Scripts use `set -euo pipefail` for safety in bash +- [ ] Cross-account operations use `assume-role` with time-limited session credentials + +## References + +> Always use the official documentation for the AWS CLI version in use — command syntax, flags, and available operations change between v2 minor releases. + +- [AWS CLI v2 command reference](https://awscli.amazonaws.com/v2/documentation/api/latest/index.html) +- [AWS CLI configuration](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html) +- [AWS CLI named profiles](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-profiles.html) diff --git a/src/vstack/_templates/skills/cicd/config.yaml b/src/vstack/_templates/skills/cicd/config.yaml index 9c912ba..b7769bf 100644 --- a/src/vstack/_templates/skills/cicd/config.yaml +++ b/src/vstack/_templates/skills/cicd/config.yaml @@ -1,5 +1,5 @@ name: cicd -version: 1.0.2 +version: 20260421006 description: | Write GitHub Actions CI/CD workflow configuration. Covers build, test, lint, security scan, container publish, and deployment trigger workflows. diff --git a/src/vstack/_templates/skills/cicd/template.md b/src/vstack/_templates/skills/cicd/template.md index f45fab6..733ff36 100644 --- a/src/vstack/_templates/skills/cicd/template.md +++ b/src/vstack/_templates/skills/cicd/template.md @@ -11,8 +11,6 @@ These files live in the PR — the pipeline runs after merge. - Container image authoring (use `container`) - Post-deploy monitoring (CI/CD's responsibility after merge) -______________________________________________________________________ - ## Step 1: Detect context ```bash @@ -26,8 +24,6 @@ ls .github/workflows/ 2>/dev/null || echo "No workflows found" ls Dockerfile 2>/dev/null && echo "Dockerfile present" ``` -______________________________________________________________________ - ## Step 2: CI workflow — `.github/workflows/ci.yml` Runs on every push and PR. Must pass before merge. @@ -40,10 +36,18 @@ on: branches: ["**"] pull_request: branches: [main] + workflow_dispatch: {} + +concurrency: + group: ci-${{ github.ref }} + cancel-in-progress: true jobs: test: runs-on: ubuntu-latest + timeout-minutes: 15 + permissions: + contents: read steps: - uses: actions/checkout@v4 @@ -53,6 +57,11 @@ jobs: - uses: actions/setup-python@v5 with: python-version: "3.12" + - uses: actions/cache@v4 + with: + path: ~/.cache/pip + key: pip-${{ runner.os }}-${{ hashFiles('**/pyproject.toml', '**/requirements*.txt') }} + restore-keys: pip-${{ runner.os }}- - run: pip install -e ".[dev]" - run: ruff check . - run: mypy . @@ -61,6 +70,10 @@ jobs: # Node # - uses: actions/setup-node@v4 # with: { node-version: "22" } + # - uses: actions/cache@v4 + # with: + # path: ~/.npm + # key: npm-${{ runner.os }}-${{ hashFiles('**/package-lock.json') }} # - run: npm ci # - run: npm run lint # - run: npm test @@ -68,12 +81,14 @@ jobs: # Go # - uses: actions/setup-go@v5 # with: { go-version: "1.22" } + # - uses: actions/cache@v4 + # with: + # path: ~/go/pkg/mod + # key: go-${{ runner.os }}-${{ hashFiles('**/go.sum') }} # - run: go vet ./... # - run: go test ./... ``` -______________________________________________________________________ - ## Step 3: Security scan — add to CI or separate workflow Add dependency and secret scanning: @@ -92,14 +107,12 @@ Add dependency and secret scanning: # - run: npm audit --audit-level=high # Secret scan - - uses: trufflesecurity/trufflehog-actions-scan@main + - uses: trufflesecurity/trufflehog-actions-scan@v3 with: path: ./ base: ${{ github.event.repository.default_branch }} ``` -______________________________________________________________________ - ## Step 4: CD workflow — `.github/workflows/cd.yml` Runs on merge to main. Builds and publishes the container image, then triggers deployment. @@ -138,8 +151,6 @@ jobs: Adapt the deploy trigger to match the target platform (Fly.io, Render, Railway, K8s, etc.). -______________________________________________________________________ - ## Step 5: Branch protection (document, don't automate) Record in `docs/architecture/architecture.md` or a README section: @@ -154,16 +165,24 @@ Branch protection rules for `main`: Configure these in GitHub → Settings → Branches. -______________________________________________________________________ - ## Step 6: Review checklist -- [ ] CI workflow triggers on push + PR +- [ ] CI workflow triggers on push + PR + `workflow_dispatch` +- [ ] `concurrency` group set to cancel stale runs +- [ ] `timeout-minutes` set on each job +- [ ] `permissions: contents: read` on CI jobs (least privilege) +- [ ] Dependency cache configured for faster builds - [ ] Lint, type-check, and tests all run in CI -- [ ] Security scan included +- [ ] Security scan included with pinned action version (not `@main`) - [ ] CD triggers only on merge to main - [ ] No secrets hardcoded in workflow files — use `secrets.*` - [ ] Container image tagged with both `latest` and `${{ github.sha }}` - [ ] Workflows validate locally: `act` (optional, for local testing) -______________________________________________________________________ +## References + +> Always use the official documentation for the exact runner version and action versions in use — available runners, contexts, and action APIs change between GitHub updates. + +- [GitHub Actions documentation](https://docs.github.com/en/actions) +- [Workflow syntax reference](https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions) +- [GitHub-hosted runners](https://docs.github.com/en/actions/using-github-hosted-runners/using-github-hosted-runners/about-github-hosted-runners) diff --git a/src/vstack/_templates/skills/cloudformation/config.yaml b/src/vstack/_templates/skills/cloudformation/config.yaml new file mode 100644 index 0000000..533b2e4 --- /dev/null +++ b/src/vstack/_templates/skills/cloudformation/config.yaml @@ -0,0 +1,18 @@ +name: cloudformation +version: 20260502032 +description: | + Write, review, and refactor AWS CloudFormation templates. Covers template + structure, parameter design, resource naming, stack outputs, cross-stack + references, nested stacks, change sets, drift detection, rollback + configuration, and security hardening. Use when asked to "write a + CloudFormation template", "review this CFN stack", "create a SAM template", + "add a CloudFormation resource", or "migrate from CDK to CloudFormation". +argument-hint: '[resource type or stack name, e.g. VPC | RDS | ECS service | Lambda function]' + +license: MIT +compatibility: Requires a skills-compatible agent with repository file access. Requires AWS CLI with appropriate IAM permissions for deploy and drift operations. +metadata: + owner: vstack + maturity: stable +user-invocable: true +disable-model-invocation: false diff --git a/src/vstack/_templates/skills/cloudformation/template.md b/src/vstack/_templates/skills/cloudformation/template.md new file mode 100644 index 0000000..b9bf0bb --- /dev/null +++ b/src/vstack/_templates/skills/cloudformation/template.md @@ -0,0 +1,311 @@ +{{SKILL_CONTEXT}} + +# cloudformation — AWS CloudFormation + +Write and review CloudFormation templates for AWS infrastructure. + +## Out of scope + +- Terraform / Terragrunt IaC (use `terraform` or `terragrunt`) +- General AWS CLI operations (use `aws-cli`) +- CDK authoring (CDK synthesizes to CloudFormation — review the synthesized template with this skill) + +## Step 0: Detect Context + +```bash +# Check for existing stacks and templates +find . -name "*.yaml" -o -name "*.json" | xargs grep -l "AWSTemplateFormatVersion" 2>/dev/null + +# Check for SAM templates +find . -name "template.yaml" -o -name "samconfig.toml" 2>/dev/null + +# List deployed stacks in current region +aws cloudformation list-stacks \ + --stack-status-filter CREATE_COMPLETE UPDATE_COMPLETE \ + --query 'StackSummaries[*].[StackName,StackStatus]' \ + --output table +``` + +## Step 1: Template Structure + +```yaml +AWSTemplateFormatVersion: "2010-09-09" +Description: > + One-line description of what this stack provisions. + Used in the AWS Console — keep it informative. + +Metadata: + AWS::CloudFormation::Interface: + ParameterGroups: + - Label: + default: "Network Configuration" + Parameters: + - VpcId + - SubnetIds + ParameterLabels: + VpcId: + default: "VPC ID" + +Parameters: + Environment: + Type: String + AllowedValues: [dev, staging, prod] + Description: Deployment environment + + VpcId: + Type: AWS::EC2::VPC::Id + Description: VPC to deploy into + +Conditions: + IsProd: !Equals [!Ref Environment, prod] + +Resources: + # ... all resources + +Outputs: + ServiceEndpoint: + Description: Load balancer DNS name + Value: !GetAtt LoadBalancer.DNSName + Export: + Name: !Sub "${AWS::StackName}-ServiceEndpoint" +``` + +## Step 2: Parameters + +```yaml +Parameters: + # Use AWS-specific parameter types for validation + VpcId: + Type: AWS::EC2::VPC::Id + + SubnetIds: + Type: List<AWS::EC2::Subnet::Id> + + # Constrain values with AllowedValues + InstanceType: + Type: String + Default: t3.medium + AllowedValues: [t3.small, t3.medium, t3.large, m5.large] + + # Mark secrets as NoEcho + DbPassword: + Type: String + NoEcho: true + MinLength: 16 + Description: Database password — supply via SSM Parameter or Secrets Manager + + # Prefer SSM Parameter references over raw values for secrets + DbPasswordSsmPath: + Type: AWS::SSM::Parameter::Value<String> + Default: /myapp/prod/db_password + NoEcho: true +``` + +**Rules:** + +- Use AWS-specific parameter types (`AWS::EC2::VPC::Id`, `AWS::EC2::Subnet::Id`) for automatic validation +- Always add `NoEcho: true` to secret parameters +- Prefer SSM Parameter Store references (`AWS::SSM::Parameter::Value<T>`) for secrets over raw string parameters +- Add `AllowedValues` for all constrained strings + +## Step 3: Resource Naming + +```yaml +Resources: + AppSecurityGroup: + Type: AWS::EC2::SecurityGroup + Properties: + GroupName: !Sub "${AWS::StackName}-app-${Environment}" + VpcId: !Ref VpcId + Tags: + - Key: Environment + Value: !Ref Environment + - Key: ManagedBy + Value: cloudformation +``` + +**Rules:** Logical IDs in PascalCase; physical names use `!Sub "${AWS::StackName}-<role>"` to guarantee cross-stack uniqueness; avoid hardcoded physical names — they block replacement operations. + +## Step 4: Intrinsic Functions + +| Function | Use | +| ------------------------------------ | ------------------------------------------------------ | +| `!Ref` | Reference a parameter or resource's primary identifier | +| `!GetAtt Resource.Attr` | Get a specific attribute of a resource | +| `!Sub "text ${Variable}"` | String interpolation | +| `!Select [n, !Ref List]` | Pick item from a list | +| `!Split [",", !Ref StringList]` | Split a comma-separated string | +| `!ImportValue StackName-Export` | Cross-stack reference | +| `!If [Condition, TrueVal, FalseVal]` | Conditional value | +| `!And`, `!Or`, `!Not`, `!Equals` | Condition logic | + +```yaml +# Cross-stack reference — import an export from another stack +DatabaseEndpoint: !ImportValue + Fn::Sub: "${NetworkStackName}-DatabaseEndpoint" +``` + +## Step 5: Conditions + +```yaml +Conditions: + IsProd: !Equals [!Ref Environment, prod] + IsNotProd: !Not [Condition: IsProd] + EnableDeletion: !Equals [!Ref EnableDeletion, "true"] + +Resources: + ReadReplica: + Type: AWS::RDS::DBInstance + Condition: IsProd # only created in prod + Properties: + # ... + + BucketPolicy: + Type: AWS::S3::BucketPolicy + Properties: + # ... + PolicyDocument: + Statement: + - Effect: !If [IsProd, Deny, Allow] +``` + +## Step 6: Stack Outputs and Cross-Stack References + +```yaml +Outputs: + VpcId: + Description: VPC ID for use by dependent stacks. + Value: !Ref VPC + Export: + Name: !Sub "${AWS::StackName}-VpcId" + + PrivateSubnetIds: + Description: Comma-separated private subnet IDs. + Value: !Join [",", [!Ref PrivateSubnet1, !Ref PrivateSubnet2]] + Export: + Name: !Sub "${AWS::StackName}-PrivateSubnetIds" +``` + +**Cross-stack dependency rules:** + +- Export names must be unique within a region/account +- A stack cannot be deleted while another stack imports its exports +- Use `!ImportValue` sparingly — tight coupling between stacks; consider SSM Parameter Store for loose coupling + +## Step 7: Deploy Workflow + +```bash +# Validate template syntax and resource types +aws cloudformation validate-template --template-body file://template.yaml + +# Lint with cfn-lint (catches more issues than validate) +cfn-lint template.yaml + +# Create/update via change set (recommended — review before execute) +aws cloudformation deploy \ + --template-file template.yaml \ + --stack-name myapp-dev \ + --parameter-overrides \ + Environment=dev \ + VpcId=vpc-12345678 \ + --capabilities CAPABILITY_IAM CAPABILITY_NAMED_IAM \ + --no-execute-changeset # review first + +# Show the change set before executing +aws cloudformation describe-change-set \ + --stack-name myapp-dev \ + --change-set-name <change-set-name> \ + --query 'Changes[*].ResourceChange.[Action,ResourceType,LogicalResourceId,Replacement]' \ + --output table + +# Execute after review +aws cloudformation deploy \ + --template-file template.yaml \ + --stack-name myapp-dev \ + --parameter-overrides Environment=dev VpcId=vpc-12345678 \ + --capabilities CAPABILITY_IAM +``` + +## Step 8: Drift Detection + +```bash +# Start drift detection +aws cloudformation detect-stack-drift --stack-name myapp-prod + +# Check detection status (wait until DETECTION_COMPLETE) +aws cloudformation describe-stack-drift-detection-status \ + --stack-drift-detection-id <id> + +# Show drifted resources +aws cloudformation describe-stack-resource-drifts \ + --stack-name myapp-prod \ + --stack-resource-drift-status-filters MODIFIED DELETED \ + --query 'StackResourceDrifts[*].[LogicalResourceId,ResourceType,StackResourceDriftStatus]' \ + --output table +``` + +## Step 9: Security Hardening + +```yaml +# S3 bucket — block public access, enable encryption +AppBucket: + Type: AWS::S3::Bucket + Properties: + BucketEncryption: + ServerSideEncryptionConfiguration: + - ServerSideEncryptionByDefault: + SSEAlgorithm: aws:kms + KMSMasterKeyID: !Ref KmsKey + PublicAccessBlockConfiguration: + BlockPublicAcls: true + BlockPublicPolicy: true + IgnorePublicAcls: true + RestrictPublicBuckets: true + VersioningConfiguration: + Status: Enabled + +# RDS — encryption, no public access, deletion protection in prod +Database: + Type: AWS::RDS::DBInstance + DeletionPolicy: Snapshot + Properties: + StorageEncrypted: true + MultiAZ: !If [IsProd, true, false] + PubliclyAccessible: false + DeletionProtection: !If [IsProd, true, false] + +# Security group — no 0.0.0.0/0 on admin ports +AppSecurityGroup: + Type: AWS::EC2::SecurityGroup + Properties: + SecurityGroupIngress: + - IpProtocol: tcp + FromPort: 443 + ToPort: 443 + CidrIp: 0.0.0.0/0 # HTTPS only — review for internal services +``` + +**cfn-lint errors to enforce:** `E3001` (invalid resource type), `W3045` (unrestricted SG ingress), `E3030` (invalid property values). + +## Review Checklist + +- [ ] `AWSTemplateFormatVersion` and `Description` present +- [ ] All parameters have `Description`; secret parameters have `NoEcho: true` +- [ ] Secrets use SSM Parameter Store references, not raw strings +- [ ] Physical resource names use `!Sub "${AWS::StackName}-..."` to avoid collisions +- [ ] All resources tagged with `Environment` and `ManagedBy: cloudformation` +- [ ] S3 buckets: public access blocked, encryption enabled, versioning on +- [ ] RDS: `StorageEncrypted: true`, `PubliclyAccessible: false`, `DeletionProtection` set in prod +- [ ] Security groups: no `0.0.0.0/0` on SSH/RDP; document HTTPS exceptions +- [ ] IAM roles: least-privilege policies; no `*` actions on `*` resources +- [ ] `cfn-lint` passes with no errors or warnings +- [ ] Change set reviewed before executing in production + +## References + +> Always use the official documentation for the resource types in use — properties, attributes, and supported values change with AWS service updates. + +- [CloudFormation resource reference](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-template-resource-type-ref.html) +- [Intrinsic function reference](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference.html) +- [cfn-lint](https://github.com/aws-cloudformation/cfn-lint) +- [AWS SAM documentation](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/) diff --git a/src/vstack/_templates/skills/code-review/config.yaml b/src/vstack/_templates/skills/code-review/config.yaml index 7d07828..7cfc74f 100644 --- a/src/vstack/_templates/skills/code-review/config.yaml +++ b/src/vstack/_templates/skills/code-review/config.yaml @@ -1,5 +1,5 @@ name: code-review -version: 1.0.2 +version: 20260421007 description: | Pre-landing code review. Finds bugs that pass CI but break in production — race conditions, missing error handling, API contract violations, observability diff --git a/src/vstack/_templates/skills/code-review/template.md b/src/vstack/_templates/skills/code-review/template.md index 19ed8c9..80d792d 100644 --- a/src/vstack/_templates/skills/code-review/template.md +++ b/src/vstack/_templates/skills/code-review/template.md @@ -176,5 +176,3 @@ Format: Confidence: [HIGH/MEDIUM/LOW — explain if not HIGH] ``` - -______________________________________________________________________ diff --git a/src/vstack/_templates/skills/codeql/config.yaml b/src/vstack/_templates/skills/codeql/config.yaml new file mode 100644 index 0000000..8d6a759 --- /dev/null +++ b/src/vstack/_templates/skills/codeql/config.yaml @@ -0,0 +1,17 @@ +name: codeql +version: 20260502026 +description: | + Set up and configure CodeQL code scanning via GitHub Actions or the CodeQL CLI. + Covers workflow creation, language matrix, build modes, query suites, monorepo + configuration, SARIF output, and alert triage. Use when asked to "set up CodeQL", + "configure code scanning", "add a codeql workflow", or "scan for vulnerabilities + with CodeQL". +argument-hint: '[languages and setup type: default or advanced]' + +license: MIT +compatibility: Requires a skills-compatible agent with repository file access and terminal command execution. GitHub Advanced Security or public repository required for alert upload. +metadata: + owner: vstack + maturity: stable +user-invocable: true +disable-model-invocation: false diff --git a/src/vstack/_templates/skills/codeql/template.md b/src/vstack/_templates/skills/codeql/template.md new file mode 100644 index 0000000..35f9e40 --- /dev/null +++ b/src/vstack/_templates/skills/codeql/template.md @@ -0,0 +1,218 @@ +{{SKILL_CONTEXT}} + +# codeql — CodeQL Code Scanning + +Set up and configure CodeQL code scanning via GitHub Actions or the CodeQL CLI. +The output is a workflow file and/or a CodeQL configuration file. + +## Out of scope + +- General security audit (use `security`) +- Dependency vulnerability scanning (use `dependency` or `dependabot`) +- Secret scanning (use `secret-scan`) +- CI/CD pipeline design (use `cicd`) + +## Step 0: Detect Context + +```bash +# Detect existing CodeQL workflow +ls .github/workflows/codeql*.yml 2>/dev/null || echo "No CodeQL workflow found" + +# Detect languages in repo +ls pyproject.toml requirements.txt setup.py 2>/dev/null && echo "Python" +ls package.json 2>/dev/null && echo "JavaScript/TypeScript" +ls go.mod 2>/dev/null && echo "Go" +ls pom.xml build.gradle 2>/dev/null && echo "Java/Kotlin" +ls Cargo.toml 2>/dev/null && echo "Rust" +ls *.csproj 2>/dev/null && echo "C#" +ls .github/workflows/*.yml 2>/dev/null && echo "GitHub Actions (workflows present)" +``` + +## Step 1: Choose Setup Type + +| Setup type | When to use | +| ------------ | ---------------------------------------------------------------------------------------------------------------------------- | +| **Default** | Enable from Settings → Advanced Security → Code scanning. Best for getting started — no workflow file needed. | +| **Advanced** | Create `.github/workflows/codeql.yml` for full control over triggers, build modes, query suites, and monorepo configuration. | + +To switch from default to advanced: disable default setup first, then commit the workflow. + +## Step 2: Supported Languages + +| Language | Identifier | Build mode | +| --------------------- | ----------------------- | ----------------------- | +| Python | `python` | `none` | +| JavaScript/TypeScript | `javascript-typescript` | `none` | +| Go | `go` | `none` or `autobuild` | +| Java/Kotlin | `java-kotlin` | `autobuild` or `manual` | +| C/C++ | `c-cpp` | `autobuild` or `manual` | +| C# | `csharp` | `autobuild` or `manual` | +| Rust | `rust` | `none` | +| Swift | `swift` | `autobuild` or `manual` | +| GitHub Actions | `actions` | `none` | + +Build modes: + +- `none` — no build required (safe default for interpreted languages) +- `autobuild` — automatic build detection +- `manual` — explicit build commands between `init` and `analyze` steps + +## Step 3: Write the Workflow + +Create `.github/workflows/codeql.yml`: + +```yaml +name: CodeQL + +on: + push: + branches: [main] + pull_request: + branches: [main] + schedule: + - cron: '30 6 * * 1' # Weekly, Monday 06:30 UTC + +jobs: + analyze: + name: Analyze (${{ matrix.language }}) + runs-on: ubuntu-latest + timeout-minutes: 30 + permissions: + security-events: write # Required to upload SARIF results + contents: read # Required to check out code + actions: read # Required for private repos + + strategy: + fail-fast: false + matrix: + include: + # Add one entry per language detected in Step 0. + # Examples: + - language: python + build-mode: none + - language: javascript-typescript + build-mode: none + # Compiled language example: + # - language: java-kotlin + # build-mode: autobuild + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Initialize CodeQL + uses: github/codeql-action/init@v4 + with: + languages: ${{ matrix.language }} + build-mode: ${{ matrix.build-mode }} + queries: security-extended + dependency-caching: true + + # For manual build mode only — add build commands here: + # - if: matrix.build-mode == 'manual' + # name: Build + # run: | + # make build + + - name: Perform CodeQL Analysis + uses: github/codeql-action/analyze@v4 + with: + category: "/language:${{ matrix.language }}" +``` + +**Query suite options:** + +| Suite | Coverage | +| ----------------------- | ---------------------------------------------------------- | +| `security-extended` | Default security queries + additional checks (recommended) | +| `security-and-quality` | Security + code quality queries (larger, slower) | +| `security-experimental` | Experimental queries (higher false-positive rate) | + +## Step 4: Monorepo and Path Configuration (optional) + +To restrict analysis to specific paths, create `.github/codeql/codeql-config.yml`: + +```yaml +paths: + - src/ + - apps/ +paths-ignore: + - '**/test/**' + - '**/node_modules/**' + - '**/vendor/**' +``` + +Reference it in the workflow: + +```yaml +- uses: github/codeql-action/init@v4 + with: + config-file: .github/codeql/codeql-config.yml +``` + +For monorepos with per-component results: + +```yaml +category: "/language:${{ matrix.language }}/component:backend" +``` + +To skip documentation-only PRs: + +```yaml +on: + pull_request: + branches: [main] + paths-ignore: + - '**/*.md' + - 'docs/**' +``` + +## Step 5: Alert Triage + +Alerts appear in the repository Security tab after the first scan. + +**Severity levels:** + +- Security severity: `Critical`, `High`, `Medium`, `Low` (from CVSS score) +- Standard severity: `Error`, `Warning`, `Note` + +**Review policy:** + +- Fix all `Critical` and `High` findings before merging +- Dismiss false positives with a documented reason (creates an audit trail) +- Copilot Autofix generates fix suggestions automatically for CodeQL alerts in PRs — review carefully before accepting + +## Step 6: CodeQL CLI (local scanning) + +```bash +# Create database (after adding codeql binary to PATH) +codeql database create codeql-db --language=python --source-root=src + +# Analyze +codeql database analyze codeql-db \ + python-security-extended.qls --format=sarif-latest --output=results.sarif + +# Upload to GitHub +GITHUB_TOKEN=<token> codeql github upload-results \ + --repository=<owner/repo> --ref=refs/heads/main --commit=<sha> --sarif=results.sarif +``` + +## Review checklist + +- [ ] One matrix entry per detected language +- [ ] `permissions: security-events: write` set on the job +- [ ] `queries: security-extended` (or stronger) +- [ ] `dependency-caching: true` on `init` step +- [ ] `timeout-minutes` set on job +- [ ] Weekly `schedule` trigger set for the default branch +- [ ] Compiled language build mode confirmed (`autobuild` or `manual`) +- [ ] `paths-ignore` excludes documentation-only PRs if useful +- [ ] Actions pinned to `@v4` (not floating `@main`) + +## References + +> Always use the official documentation for the exact version in use — action versions, query suites, and language identifiers change between releases. + +- [CodeQL documentation](https://docs.github.com/en/code-security/code-scanning/introduction-to-code-scanning/about-code-scanning-with-codeql) +- [github/codeql-action releases](https://github.com/github/codeql-action/releases) +- [Supported languages and frameworks](https://docs.github.com/en/code-security/code-scanning/introduction-to-code-scanning/codeql-code-scanning-for-compiled-languages) diff --git a/src/vstack/_templates/skills/concise/config.yaml b/src/vstack/_templates/skills/concise/config.yaml index b61c112..e932117 100644 --- a/src/vstack/_templates/skills/concise/config.yaml +++ b/src/vstack/_templates/skills/concise/config.yaml @@ -1,5 +1,5 @@ name: concise -version: 1.0.1 +version: 20260421008 description: | Runtime response-style controller for concise communication. Switches between normal, compact, and ultra output density without regenerating agents. Use diff --git a/src/vstack/_templates/skills/concise/template.md b/src/vstack/_templates/skills/concise/template.md index 1cf634a..51711dc 100644 --- a/src/vstack/_templates/skills/concise/template.md +++ b/src/vstack/_templates/skills/concise/template.md @@ -10,8 +10,6 @@ Control response brevity at runtime without regenerating any agent artifacts. - Persisting style mode across independent chat sessions - Overriding safety-critical clarity requirements -______________________________________________________________________ - ## Commands Supported commands: @@ -30,8 +28,6 @@ Unknown arguments: - If argument is unknown, do not guess. Return usage and keep current mode unchanged. -______________________________________________________________________ - ## Mode Semantics - `normal`: full, explicit explanation depth. @@ -44,8 +40,6 @@ Hard invariants for all concise modes: - Do not remove required warnings, constraints, or irreversible-action cautions. - Never trade correctness for brevity. -______________________________________________________________________ - ## Priority and Resolution Resolve active mode with this precedence: @@ -63,8 +57,6 @@ Resolve active mode with this precedence: - global default mode - whether auto-clarity override is currently active -______________________________________________________________________ - ## Suggested Agent Defaults When no session override exists, use these defaults: @@ -76,8 +68,6 @@ When no session override exists, use these defaults: - `tester`: `ultra` - `release`: `compact` -______________________________________________________________________ - ## Auto-Clarity Override (Mandatory) Temporarily force `normal` regardless of active concise mode for: @@ -89,8 +79,6 @@ Temporarily force `normal` regardless of active concise mode for: After the high-clarity segment ends, return to previously active concise mode. -______________________________________________________________________ - ## Expected Responses On successful mode switch: @@ -118,8 +106,6 @@ Usage: concise normal|compact|ultra|status|on|off Current mode unchanged: <mode> ``` -______________________________________________________________________ - ## Completion Checklist - [ ] Command parsed and validated diff --git a/src/vstack/_templates/skills/consult/config.yaml b/src/vstack/_templates/skills/consult/config.yaml index a691132..c604164 100644 --- a/src/vstack/_templates/skills/consult/config.yaml +++ b/src/vstack/_templates/skills/consult/config.yaml @@ -1,5 +1,5 @@ name: consult -version: 1.0.2 +version: 20260421009 description: | DX triage and focused review. First classifies whether the request is API DX, CLI/tool DX, or developer workflow DX, then runs exactly one review path with diff --git a/src/vstack/_templates/skills/consult/template.md b/src/vstack/_templates/skills/consult/template.md index f0e16d9..6670936 100644 --- a/src/vstack/_templates/skills/consult/template.md +++ b/src/vstack/_templates/skills/consult/template.md @@ -17,8 +17,6 @@ Read only — do not change any code. - Performance profiling/regression analysis (use `performance`) - Tradeoff/impact/feasibility analysis (use `analyse`) -______________________________________________________________________ - ## Step 0: Classify and Route Determine the user's real intent before reviewing anything. @@ -49,8 +47,6 @@ If D, stop and return this routing recommendation: Do not continue with DX scoring when routing to another skill. -______________________________________________________________________ - ## Step 1: Run Exactly One Path Run only the selected path (A, B, or C). Skip all others. @@ -154,8 +150,6 @@ cat .github/workflows/*.yml 2>/dev/null | grep -E 'timeout|runs-on|steps' | head - Is there type checking? - Are these run on commit (pre-commit hooks) or in CI? -______________________________________________________________________ - ## Step 2: Improvement Plan (ROI-first) For each weak area (typically score < 7), provide: @@ -164,8 +158,6 @@ For each weak area (typically score < 7), provide: 1. **Medium investment (1-2 days):** Most likely path to 9/10. 1. **Long-term:** Structural change to reach 10/10. -______________________________________________________________________ - ## Output Contract ```text @@ -191,5 +183,3 @@ overall_score: [N/10 or N/A when routed] recommended_skill: [design|analyse|debug|code-review|security|performance|verify] reason: [one sentence] ``` - -______________________________________________________________________ diff --git a/src/vstack/_templates/skills/container/config.yaml b/src/vstack/_templates/skills/container/config.yaml index 7668eae..4511551 100644 --- a/src/vstack/_templates/skills/container/config.yaml +++ b/src/vstack/_templates/skills/container/config.yaml @@ -1,5 +1,5 @@ name: container -version: 1.0.2 +version: 20260421010 description: | Write and review Dockerfile, docker-compose, and container configuration. Covers multi-stage builds, image hardening, non-root users, minimal base images, diff --git a/src/vstack/_templates/skills/container/template.md b/src/vstack/_templates/skills/container/template.md index 379a9af..4b057fe 100644 --- a/src/vstack/_templates/skills/container/template.md +++ b/src/vstack/_templates/skills/container/template.md @@ -10,8 +10,6 @@ Write production-grade container configuration for the service. - Kubernetes manifests (use `cicd`) - Application code changes (engineering role) -______________________________________________________________________ - ## Step 1: Detect context ```bash @@ -22,8 +20,6 @@ ls pyproject.toml requirements.txt package.json go.mod Cargo.toml pom.xml 2>/dev ls Dockerfile* docker-compose* .dockerignore 2>/dev/null || echo "No container config found" ``` -______________________________________________________________________ - ## Step 2: Dockerfile Write a multi-stage `Dockerfile` following these rules: @@ -78,8 +74,6 @@ ENTRYPOINT ["<executable>"] CMD ["<default args>"] ``` -______________________________________________________________________ - ## Step 3: docker-compose.yml (local dev) Write `docker-compose.yml` for local development: @@ -106,8 +100,6 @@ services: For production-like local testing, write a separate `docker-compose.prod.yml` without volume mounts. -______________________________________________________________________ - ## Step 4: Review checklist - [ ] No `latest` tags @@ -119,4 +111,10 @@ ______________________________________________________________________ - [ ] Image builds successfully: `docker build -t app:local .` - [ ] Container starts and responds: `docker run --rm -p <port>:<port> app:local` -______________________________________________________________________ +## References + +> Always use the official documentation for the Docker and Compose versions in use — Dockerfile syntax, base image tags, and Compose spec fields evolve with each release. + +- [Dockerfile reference](https://docs.docker.com/reference/dockerfile/) +- [Docker Compose specification](https://docs.docker.com/compose/intro/compose-application-model/) +- [Docker official images](https://hub.docker.com/search?image_filter=official) diff --git a/src/vstack/_templates/skills/conventional-commit/config.yaml b/src/vstack/_templates/skills/conventional-commit/config.yaml new file mode 100644 index 0000000..faf8d21 --- /dev/null +++ b/src/vstack/_templates/skills/conventional-commit/config.yaml @@ -0,0 +1,18 @@ +name: conventional-commit +version: 20260502024 +description: | + Prepare high-quality Conventional Commit messages from current staged or + unstaged changes with explicit type, optional scope, and concise subject. + Validates commit intent against change content and blocks ambiguous or + non-compliant messages before commit. + Use when asked to "write a commit message", "make a conventional commit", or + "prepare commits before PR". +argument-hint: '[changes to commit and desired release intent]' + +license: MIT +compatibility: Requires a skills-compatible agent with repository file access and terminal command execution. +metadata: + owner: vstack + maturity: stable +user-invocable: true +disable-model-invocation: false diff --git a/src/vstack/_templates/skills/conventional-commit/template.md b/src/vstack/_templates/skills/conventional-commit/template.md new file mode 100644 index 0000000..22da2f0 --- /dev/null +++ b/src/vstack/_templates/skills/conventional-commit/template.md @@ -0,0 +1,122 @@ +{{SKILL_CONTEXT}} + +# conventional-commit — Prepare Conventional Commits + +Create clear, policy-aligned commits with a Conventional Commit header: + +`type(optional-scope)!: short summary` + +## Out of scope + +- Pushing branches or opening PRs (use `pr`) +- Writing release notes (use `release-notes`) +- Rewriting repository history unless explicitly requested + +## Deliverable + +- One or more commits with compliant Conventional Commit messages + +## Step 1: Inspect changes and choose commit boundaries + +Review current changes first: + +```bash +git status --short +git diff --stat +git diff --cached --stat +``` + +Split unrelated changes into separate commits. + +Boundary rules: + +- One commit per cohesive intent +- Avoid mixing refactor + feature + tests unless tightly coupled +- Keep commits reviewable and reversible + +## Step 2: Select commit type and scope + +Choose the best type from change intent: + +- `feat` for new behavior +- `fix` for bug fixes +- `refactor` for structure-only changes without behavior change +- `docs` for documentation-only changes +- `test` for test-only changes +- `chore` for maintenance/tooling/meta updates +- `ci` for CI/CD workflow changes +- `perf` for performance-focused improvements + +Scope guidance: + +- Use optional scope when it improves clarity: `feat(auth): ...` +- Keep scope short, stable, and system-oriented +- Omit scope if it adds noise + +## Step 3: Draft header and body + +Header format: + +```text +type(optional-scope)!: short summary +``` + +Quality rules: + +- imperative mood (`add`, `fix`, `remove`) +- summary \<= 100 characters +- no trailing period +- no vague text like `update stuff` + +Use breaking marker `!` only when behavior or contract is breaking. + +Optional body should explain why, risk, and migration notes when relevant. + +## Step 4: Validate against staged content + +Before committing, verify message-content alignment: + +```bash +git diff --cached --name-only +git diff --cached --stat +``` + +Validation checks: + +- `docs` commit does not include source code changes (unless explicitly intended) +- `test` commit does not include product logic changes (unless fixing test harness) +- `refactor` commit does not change observable behavior +- breaking marker appears only with actual breaking impact + +If alignment fails, revise scope/type or split commits. + +## Step 5: Commit safely + +Commit staged changes with validated header: + +```bash +git commit -m "<type(optional-scope): summary>" +``` + +For non-trivial changes, include body: + +```bash +git commit \ + -m "<type(optional-scope): summary>" \ + -m "Why: <reason>" \ + -m "Risk: <risk and mitigation>" +``` + +## Step 6: Report result + +Return concise result: + +```text +Committed: +- <sha> <header> + +Remaining changes: +- <summary or none> +``` + +If commit is blocked, report exact reason and proposed fix. diff --git a/src/vstack/_templates/skills/debug/config.yaml b/src/vstack/_templates/skills/debug/config.yaml index cc16386..b2e9920 100644 --- a/src/vstack/_templates/skills/debug/config.yaml +++ b/src/vstack/_templates/skills/debug/config.yaml @@ -1,5 +1,5 @@ name: debug -version: 1.0.2 +version: 20260421011 description: | Systematic root-cause debugging for backend services, APIs, and libraries. No fixes without investigation. Follows the scientific method: observe → diff --git a/src/vstack/_templates/skills/debug/template.md b/src/vstack/_templates/skills/debug/template.md index 10cc50b..dd08774 100644 --- a/src/vstack/_templates/skills/debug/template.md +++ b/src/vstack/_templates/skills/debug/template.md @@ -23,8 +23,6 @@ Follow the scientific method: 1. **Fix** — Minimal change that addresses root cause 1. **Prevent** — Add a test that would have caught this -______________________________________________________________________ - ## Step 0: Understand the Problem Before touching any code, gather complete context: @@ -56,8 +54,6 @@ git stash list git diff HEAD~10 -- package.json package-lock.json go.mod go.sum pyproject.toml 2>/dev/null | head -40 ``` -______________________________________________________________________ - ## Step 1: Reproduce **First, reproduce the bug reliably before attempting any fix.** @@ -83,8 +79,6 @@ Reproducer: Environment: [local / CI / staging / prod] ``` -______________________________________________________________________ - ## Step 2: Gather Evidence **Read all available logs and error output:** @@ -110,8 +104,6 @@ cat /var/log/app.log 2>/dev/null | tail -100 || true git diff HEAD~3 -- relevant-files ``` -______________________________________________________________________ - ## Step 3: Form Hypotheses Based on evidence, list hypotheses in order of likelihood: @@ -138,8 +130,6 @@ Hypotheses (most likely first): - **Memory:** Leak, fragmentation, GC pressure - **Timing:** TTL expiry, clock skew, eventual consistency window -______________________________________________________________________ - ## Step 4: Test Each Hypothesis For each hypothesis in rank order: @@ -161,8 +151,6 @@ go test -race ./... 2>/dev/null || true Eliminate hypotheses one by one until only one remains. -______________________________________________________________________ - ## Step 5: Root Cause Identification State the root cause with precision: @@ -176,8 +164,6 @@ Root Cause: Scope: [Which environments? Which users? How often?] ``` -______________________________________________________________________ - ## Step 6: Fix Design the minimal fix: @@ -192,8 +178,6 @@ Design the minimal fix: # Run the reproducer to confirm it's fixed ``` -______________________________________________________________________ - ## Step 7: Regression Test Add a test that would have caught this bug: @@ -218,8 +202,6 @@ Reproducer: [if non-obvious] Test: [test file added/updated]" ``` -______________________________________________________________________ - ## Step 8: Prevent Recurrence Consider: @@ -230,8 +212,6 @@ Consider: 1. Should an alert be added to catch this class of failure in production? 1. Should TODOS.md be updated with related improvements? -______________________________________________________________________ - ## Debug Summary ```text @@ -243,5 +223,3 @@ Fix: [change made in commit SHA] Regression test: [test file:function] Prevention: [any follow-up items] ``` - -______________________________________________________________________ diff --git a/src/vstack/_templates/skills/dependabot/config.yaml b/src/vstack/_templates/skills/dependabot/config.yaml new file mode 100644 index 0000000..d6a7c82 --- /dev/null +++ b/src/vstack/_templates/skills/dependabot/config.yaml @@ -0,0 +1,17 @@ +name: dependabot +version: 20260502027 +description: | + Create or optimize a Dependabot configuration file (.github/dependabot.yml). + Covers dependency update strategies, grouping, monorepo patterns, security + update configuration, schedule optimization, and PR customization. Use when + asked to "set up Dependabot", "configure dependency updates", "add dependabot.yml", + or "reduce Dependabot PR noise". +argument-hint: '[repository type: library | service | monorepo, and ecosystems to cover]' + +license: MIT +compatibility: Requires a skills-compatible agent with repository file access. Dependabot requires GitHub repository access (public or private with GitHub Advanced Security for private). +metadata: + owner: vstack + maturity: stable +user-invocable: true +disable-model-invocation: false diff --git a/src/vstack/_templates/skills/dependabot/template.md b/src/vstack/_templates/skills/dependabot/template.md new file mode 100644 index 0000000..2248a57 --- /dev/null +++ b/src/vstack/_templates/skills/dependabot/template.md @@ -0,0 +1,287 @@ +{{SKILL_CONTEXT}} + +# dependabot — Dependabot Configuration + +Create or optimize `.github/dependabot.yml` for automated dependency updates. +One file handles all ecosystems — GitHub does not support multiple `dependabot.yml` +files per repository. + +## Out of scope + +- Manual dependency upgrades (use `dependency`) +- Vulnerability triage in code (use `security`) +- CodeQL code scanning (use `codeql`) +- Secret scanning (use `secret-scan`) + +## Step 0: Detect Ecosystems + +```bash +# Find all manifest files to determine which ecosystems are present +ls pyproject.toml requirements*.txt setup.py Pipfile 2>/dev/null && echo "pip" +ls package.json package-lock.json yarn.lock pnpm-lock.yaml 2>/dev/null && echo "npm" +ls go.mod 2>/dev/null && echo "gomod" +ls Cargo.toml 2>/dev/null && echo "cargo" +ls pom.xml 2>/dev/null && echo "maven" +ls build.gradle build.gradle.kts 2>/dev/null && echo "gradle" +ls Gemfile 2>/dev/null && echo "bundler" +ls Dockerfile 2>/dev/null && echo "docker" +ls docker-compose*.yml 2>/dev/null && echo "docker-compose" +ls .github/workflows/*.yml 2>/dev/null && echo "github-actions" +ls *.tf 2>/dev/null && echo "terraform" +ls Chart.yaml 2>/dev/null && echo "helm" + +# Check existing dependabot config +cat .github/dependabot.yml 2>/dev/null || echo "No dependabot.yml found" +``` + +## Step 1: Ecosystem Reference + +| Ecosystem | `package-ecosystem` | Manifest files | +| ----------------- | ------------------- | ------------------------------------------------------------------ | +| pip / poetry / uv | `pip` | `pyproject.toml`, `requirements*.txt`, `Pipfile` | +| npm / pnpm / yarn | `npm` | `package.json`, `package-lock.json`, `pnpm-lock.yaml`, `yarn.lock` | +| Go | `gomod` | `go.mod` | +| Rust | `cargo` | `Cargo.toml` | +| Maven | `maven` | `pom.xml` | +| Gradle | `gradle` | `build.gradle`, `build.gradle.kts` | +| Bundler | `bundler` | `Gemfile` | +| Docker | `docker` | `Dockerfile` | +| Docker Compose | `docker-compose` | `docker-compose*.yml` | +| GitHub Actions | `github-actions` | `.github/workflows/*.yml` | +| Terraform | `terraform` | `*.tf` | +| Helm | `helm` | `Chart.yaml` | +| NuGet | `nuget` | `*.csproj`, `packages.config` | +| Pre-commit | `pre-commit` | `.pre-commit-config.yaml` | + +Note: pnpm and yarn both use `package-ecosystem: "npm"`. + +## Step 2: Minimal Configuration + +Every entry needs at minimum: + +```yaml +version: 2 + +updates: + - package-ecosystem: "pip" + directory: "/" + schedule: + interval: "weekly" +``` + +Default schedule: weekly on Monday. Add `time` and `timezone` for +predictable windows: + +```yaml +schedule: + interval: "weekly" + day: "monday" + time: "09:00" + timezone: "Europe/Amsterdam" +``` + +## Step 3: Full Example (common stack) + +```yaml +version: 2 + +updates: + # Python dependencies + - package-ecosystem: "pip" + directory: "/" + schedule: + interval: "weekly" + day: "monday" + groups: + python-deps: + dependency-type: "production" + update-types: ["minor", "patch"] + python-dev-deps: + dependency-type: "development" + update-types: ["minor", "patch"] + commit-message: + prefix: "deps" + labels: + - "dependencies" + - "python" + + # GitHub Actions + - package-ecosystem: "github-actions" + directory: "/" + schedule: + interval: "weekly" + commit-message: + prefix: "ci" + labels: + - "dependencies" + - "ci" +``` + +## Step 4: Grouping Strategies + +Reduce PR noise by grouping related updates. + +### By dependency type + +```yaml +groups: + dev-dependencies: + dependency-type: "development" + update-types: ["minor", "patch"] + production-dependencies: + dependency-type: "production" + update-types: ["minor", "patch"] +``` + +### By name pattern + +```yaml +groups: + aws-sdk: + patterns: ["boto3", "botocore", "aws-*"] + update-types: ["minor", "patch"] + testing: + patterns: ["pytest*", "coverage*", "mypy*"] +``` + +### For security updates only + +```yaml +groups: + security-patches: + applies-to: security-updates + patterns: ["*"] + update-types: ["patch", "minor"] +``` + +**Rules:** + +- Dependencies matching multiple groups go to the **first** match +- `applies-to` defaults to `version-updates` when absent +- Ungrouped dependencies get individual PRs + +## Step 5: Monorepo Configuration + +Use `directories` (plural) with glob patterns — `directory` (singular) does not support globs: + +```yaml +- package-ecosystem: "npm" + directories: + - "/" + - "/apps/*" + - "/packages/*" + schedule: + interval: "weekly" +``` + +If a subdirectory has its own lockfile outside the workspace, add a separate +entry with `directory` pointing to that location. + +## Step 6: Security Updates + +Enable via repository **Settings → Advanced Security → Dependabot alerts and +security updates**. + +To group security PRs: + +```yaml +groups: + security-patches: + applies-to: security-updates + patterns: ["*"] + update-types: ["patch", "minor"] +``` + +To disable version update PRs and keep only security updates: + +```yaml +open-pull-requests-limit: 0 +``` + +## Step 7: Ignore and Allow Rules + +### Pin a dependency at its current version + +```yaml +ignore: + - dependency-name: "django" + versions: ["4.x", "5.x"] +``` + +### Only update production dependencies + +```yaml +allow: + - dependency-type: "production" +``` + +### Exclude vendor paths + +```yaml +exclude-paths: + - "vendor/**" + - "test/fixtures/**" +``` + +## Step 8: Advanced Options + +### Cooldown periods + +```yaml +cooldown: + default-days: 5 + semver-major-days: 30 + semver-minor-days: 7 +``` + +### Versioning strategy + +`auto` (default) increases the minimum for apps and widens ranges for libraries. +Use `lockfile-only` to update only lock files without touching manifests. +Use `increase-if-necessary` to change the range only when it excludes the new version. + +### Private registries + +```yaml +registries: + pypi-private: + type: python-index + url: https://pypi.example.com + token: ${{ secrets.PYPI_TOKEN }} + +updates: + - package-ecosystem: "pip" + directory: "/" + registries: + - pypi-private +``` + +## PR Comment Commands + +| Comment | Effect | +| --------------------------------------- | ------------------------- | +| `@dependabot rebase` | Rebase the PR | +| `@dependabot recreate` | Recreate from scratch | +| `@dependabot ignore this dependency` | Close and never update | +| `@dependabot ignore this major version` | Ignore this major version | +| `@dependabot ignore this minor version` | Ignore this minor version | +| `@dependabot ignore this patch version` | Ignore this patch version | + +## Review checklist + +- [ ] Every detected ecosystem has an entry +- [ ] `github-actions` ecosystem included to keep workflow action versions current +- [ ] Groups configured to reduce PR noise +- [ ] `commit-message.prefix` set per ecosystem for clear history +- [ ] `open-pull-requests-limit` appropriate for team capacity (default: 5) +- [ ] Security update grouping configured +- [ ] Monorepo: `directories` (plural) with globs if workspace spans subdirs +- [ ] Private registries use `${{ secrets.* }}` — never hardcoded tokens + +## References + +> Always use the official documentation for the exact version in use — supported ecosystems, grouping syntax, and available options expand with each release. + +- [Dependabot configuration options](https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file) +- [Supported package ecosystems](https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/about-dependabot-version-updates#supported-repositories-and-ecosystems) +- [Dependabot security updates](https://docs.github.com/en/code-security/dependabot/dependabot-security-updates/about-dependabot-security-updates) diff --git a/src/vstack/_templates/skills/dependency/config.yaml b/src/vstack/_templates/skills/dependency/config.yaml index 1567c76..d9e47a6 100644 --- a/src/vstack/_templates/skills/dependency/config.yaml +++ b/src/vstack/_templates/skills/dependency/config.yaml @@ -1,5 +1,5 @@ name: dependency -version: 1.0.1 +version: 20260421012 description: | Dependency health audit. Covers vulnerability scanning, outdated packages, licence compliance, transitive risk, pinning policy, and supply chain hygiene. diff --git a/src/vstack/_templates/skills/dependency/template.md b/src/vstack/_templates/skills/dependency/template.md index 202ea74..2c1da2d 100644 --- a/src/vstack/_templates/skills/dependency/template.md +++ b/src/vstack/_templates/skills/dependency/template.md @@ -18,8 +18,6 @@ risk, pinning policy, and supply chain hygiene. **Golden rule: A dependency is owned code you didn't write. Treat it with the same scrutiny as your own code.** -______________________________________________________________________ - ## Step 0: Detect the Stack ```bash @@ -45,8 +43,6 @@ Manifests: [list of files found] Lock file: [present | absent — flag if absent] ``` -______________________________________________________________________ - ## Part 1: Vulnerability Scan Run the appropriate scanner for each detected stack: @@ -91,8 +87,6 @@ Vulnerabilities found: should be tracked and resolved within the sprint. LOW may be deferred with documented rationale. -______________________________________________________________________ - ## Part 2: Outdated Packages ```bash @@ -126,8 +120,6 @@ Classify each outdated package: - Minor updates: update soon (check changelog for deprecations) - Major updates: plan upgrade (read migration guide, test thoroughly) -______________________________________________________________________ - ## Part 3: Licence Compliance Check licence obligations for all direct and transitive dependencies: @@ -169,8 +161,6 @@ Licence issues: 🔴 [package] — [licence] — [risk] — [recommendation] ``` -______________________________________________________________________ - ## Part 4: Pinning Policy A healthy dependency policy requires reproducible builds: @@ -198,8 +188,6 @@ cat pyproject.toml 2>/dev/null | grep -E '^\s+[a-z]' | grep -v '^#' | head -30 | `package = "1.2.3"` (exact) | Low | Fine for direct deps; brittle for transitive | | No lock file | High | Add lock file and commit it | -______________________________________________________________________ - ## Part 5: Transitive Risk Identify high-risk transitive (indirect) dependencies: @@ -231,8 +219,6 @@ Flags to look for: # (manual step: check PyPI / npm registry for each critical dep) ``` -______________________________________________________________________ - ## Part 6: Supply Chain Hygiene ```bash @@ -255,8 +241,6 @@ Check: - [ ] `pip install` / `npm install` output reviewed for unexpected packages - [ ] CI pipeline pins the package manager version itself -______________________________________________________________________ - ## Output ```text @@ -291,3 +275,11 @@ Action items (priority order): 1. [action] — [package] — [severity] 2. ... ``` + +## References + +> Always use the official advisories and registry documentation for the ecosystems in use — vulnerability databases and package registry APIs are updated continuously. + +- [GitHub Advisory Database](https://github.com/advisories) +- [OSV — Open Source Vulnerabilities](https://osv.dev/) +- [PyPI / npm / crates.io / Maven Central](https://pypi.org) (replace with the relevant registry) diff --git a/src/vstack/_templates/skills/design/config.yaml b/src/vstack/_templates/skills/design/config.yaml index 3675d3e..be7eca5 100644 --- a/src/vstack/_templates/skills/design/config.yaml +++ b/src/vstack/_templates/skills/design/config.yaml @@ -1,5 +1,5 @@ name: design -version: 1.0.2 +version: 20260421013 description: | Build a complete API design or service design from scratch. Produces OpenAPI specs, error conventions, naming standards, pagination patterns, and versioning diff --git a/src/vstack/_templates/skills/design/template.md b/src/vstack/_templates/skills/design/template.md index 28ee24e..8c51c93 100644 --- a/src/vstack/_templates/skills/design/template.md +++ b/src/vstack/_templates/skills/design/template.md @@ -12,8 +12,6 @@ becomes the source of truth for implementation. - Implementation (engineering role) - Contract compliance validation (use `verify` or `code-review`) -______________________________________________________________________ - ## Deliverable and artifact policy - Primary deliverable: `docs/design/design.md` @@ -22,8 +20,6 @@ ______________________________________________________________________ - Optional WIP area for complex/uncertain efforts: `docs/delta/{id}/DESIGN_DELTA.md` - Before merge: consolidate any delta draft into baseline design docs. -______________________________________________________________________ - ## Step 0: Understand the Domain > **Question:** What are we designing? @@ -42,8 +38,6 @@ Gather context: find . -name 'openapi*' -o -name '*.proto' -o -name 'asyncapi*' 2>/dev/null | head -5 ``` -______________________________________________________________________ - ## Step 1: Resource Design For each resource/entity in the domain: @@ -71,8 +65,6 @@ erDiagram } ``` -______________________________________________________________________ - ## Step 2: Endpoint Design For each resource, define CRUD + custom actions: @@ -90,8 +82,6 @@ POST /users/{id}/activate # Non-CRUD action POST /users/{id}/deactivate ``` -______________________________________________________________________ - ## Step 3: Request/Response Conventions Define the standard envelope: @@ -126,8 +116,6 @@ Define the standard envelope: } ``` -______________________________________________________________________ - ## Step 4: Error Code Taxonomy Define a machine-readable error code taxonomy: @@ -156,8 +144,6 @@ DEPENDENCY_ERROR — Upstream service failure UNAVAILABLE — Service temporarily unavailable ``` -______________________________________________________________________ - ## Step 5: Versioning & Contract Discipline Define the versioning approach: @@ -186,8 +172,6 @@ Deprecation process: - MINOR → new optional fields, backward compatible - MAJOR → breaking change -______________________________________________________________________ - ## Step 6: Authentication & Authorization ```text @@ -197,8 +181,6 @@ Token claims: user_id, roles[], tenant_id Authorization model: RBAC with per-resource checks ``` -______________________________________________________________________ - ## Step 7: Produce the Design Document Output a complete design document to `docs/design/design.md` or `openapi.yaml`: @@ -227,5 +209,3 @@ Output a complete design document to `docs/design/design.md` or `openapi.yaml`: ## Security [Input validation, rate limiting, CORS policy] ``` - -______________________________________________________________________ diff --git a/src/vstack/_templates/skills/docs/config.yaml b/src/vstack/_templates/skills/docs/config.yaml index 057f556..e0fbaf4 100644 --- a/src/vstack/_templates/skills/docs/config.yaml +++ b/src/vstack/_templates/skills/docs/config.yaml @@ -1,5 +1,5 @@ name: docs -version: 1.0.2 +version: 20260421014 description: | Post-release documentation alignment. Updates README, API docs, migration guides, and related docs to match shipped behavior. Does not own release-note diff --git a/src/vstack/_templates/skills/docs/template.md b/src/vstack/_templates/skills/docs/template.md index 4c771c2..2ae2e6b 100644 --- a/src/vstack/_templates/skills/docs/template.md +++ b/src/vstack/_templates/skills/docs/template.md @@ -21,8 +21,6 @@ change source code. - Optional WIP area for complex/uncertain efforts: `docs/delta/{id}/DOCS_DELTA.md` - Before merge: consolidate any documentation delta notes into baseline docs. -______________________________________________________________________ - ## Step 0: Scope the Release ```bash @@ -36,8 +34,6 @@ cat VERSION 2>/dev/null \ || echo "unknown" ``` -______________________________________________________________________ - ## Step 1: README Review whether README needs updates: @@ -54,8 +50,6 @@ Check: - [ ] Any deprecated features removed from featured examples? - [ ] Badges (version, CI status) still accurate? -______________________________________________________________________ - ## Step 2: API Documentation If there's an OpenAPI / AsyncAPI spec: @@ -78,8 +72,6 @@ If there's generated API documentation (Swagger UI, Redoc, TypeDoc, Sphinx): npm run docs 2>/dev/null || make docs 2>/dev/null || true ``` -______________________________________________________________________ - ## Step 3: MIGRATIONS Guide (if applicable) If this release contains breaking changes or migration steps: @@ -87,8 +79,6 @@ If this release contains breaking changes or migration steps: - Create or update `MIGRATIONS.md` or `docs/migrations/vX.md` - Document: why the change was made, what behavior changed, migration steps, code examples -______________________________________________________________________ - ## Step 4: Code Comments & ADRs For significant architectural changes: @@ -99,8 +89,6 @@ For significant architectural changes: (use the `adr` skill for the full ADR writing procedure) -______________________________________________________________________ - ## Step 5: Commit Documentation Updates ```bash @@ -108,8 +96,6 @@ git add README.md openapi.yaml docs/ 2>/dev/null || true git commit -m "docs: update documentation for v$(cat VERSION 2>/dev/null || echo 'unknown')" ``` -______________________________________________________________________ - ## Summary ```text @@ -124,5 +110,3 @@ Updated: Skipped (n/a): - [ ] [reason] ``` - -______________________________________________________________________ diff --git a/src/vstack/_templates/skills/explore/config.yaml b/src/vstack/_templates/skills/explore/config.yaml index 7347986..9b5a79e 100644 --- a/src/vstack/_templates/skills/explore/config.yaml +++ b/src/vstack/_templates/skills/explore/config.yaml @@ -1,5 +1,5 @@ name: explore -version: 1.0.2 +version: 20260421015 description: | Repository and system discovery. Maps the architecture, understands the codebase, identifies technical debt, and produces a structured onboarding diff --git a/src/vstack/_templates/skills/explore/template.md b/src/vstack/_templates/skills/explore/template.md index 4a4b634..5393987 100644 --- a/src/vstack/_templates/skills/explore/template.md +++ b/src/vstack/_templates/skills/explore/template.md @@ -11,8 +11,6 @@ Report findings; do not change code. - Architecture recommendations (use `architecture`) - Performance analysis (use `performance` or `analyse`) -______________________________________________________________________ - ## Phase 1: Project Overview ```bash @@ -31,8 +29,6 @@ Record: - **Tech stack** (language, framework, runtime) - **Project type** (API service, library, CLI, worker, monorepo) -______________________________________________________________________ - ## Phase 2: Directory Structure ```bash @@ -50,8 +46,6 @@ Identify: - CI/CD configuration (`.github/workflows/`, `.gitlab-ci.yml`, etc.) - Infrastructure code (`k8s/`, `terraform/`, `docker-compose.yml`) -______________________________________________________________________ - ## Phase 3: Dependencies & External Services ```bash @@ -73,8 +67,6 @@ grep -r -E 'postgres|mysql|redis|mongodb|kafka|rabbitmq|elasticsearch|dynamodb|s --exclude-dir=node_modules --exclude-dir=vendor . 2>/dev/null | grep -v test | head -20 ``` -______________________________________________________________________ - ## Phase 4: API & Service Contracts ```bash @@ -88,24 +80,20 @@ grep -r -n '@app.route\|router\.\|@Get\|@Post\|path=' \ --exclude-dir=node_modules . 2>/dev/null | head -30 ``` -______________________________________________________________________ - ## Phase 5: Test Infrastructure {{RUN_TESTS}} ```bash # Test count and coverage setup -find . -name '*.test.*' -o -name '*_test.*' -o -name '*spec.*' \ - --exclude-dir=node_modules 2>/dev/null | wc -l +find . \( -name '*.test.*' -o -name '*_test.*' -o -name '*spec.*' \) \ + -not -path '*/node_modules/*' -not -path '*/.venv/*' 2>/dev/null | wc -l # Coverage config cat .nycrc 2>/dev/null || cat vitest.config.* 2>/dev/null | head -20 || \ cat pytest.ini 2>/dev/null | head -20 || true ``` -______________________________________________________________________ - ## Phase 6: CI/CD Pipeline ```bash @@ -115,8 +103,6 @@ cat .github/workflows/*.yml 2>/dev/null | head -80 || true cat .gitlab-ci.yml 2>/dev/null | head -60 || true ``` -______________________________________________________________________ - ## Phase 7: Technical Debt & Health ```bash @@ -129,8 +115,6 @@ grep -r -n "TODO\|FIXME\|HACK\|XXX\|DEPRECATED\|BUG" \ cat TODOS.md 2>/dev/null | head -40 || true ``` -______________________________________________________________________ - ## Discovery Report Produce a structured summary: @@ -184,5 +168,3 @@ Stack: [language, framework, runtime versions] - Gotchas: [anything that surprised me] ``` - -______________________________________________________________________ diff --git a/src/vstack/_templates/skills/gdpr/config.yaml b/src/vstack/_templates/skills/gdpr/config.yaml new file mode 100644 index 0000000..b667cc1 --- /dev/null +++ b/src/vstack/_templates/skills/gdpr/config.yaml @@ -0,0 +1,19 @@ +name: gdpr +version: 20260502029 +description: | + GDPR-compliant engineering practices for APIs, data models, authentication + flows, logging, retention, erasure, and infrastructure. Covers privacy by + design, data minimization, storage limitation, lawful basis, user rights + (access, erasure, portability), encryption, pseudonymization, and PR review + checklists. Use when asked to "GDPR review", "is this GDPR-compliant?", + "privacy by design", "data retention policy", "right to erasure", or + "DPIA". Proactively suggest before any feature that handles personal data. +argument-hint: '[component or feature: data model | API | logging | retention | erasure | infra | PR review]' + +license: MIT +compatibility: Requires a skills-compatible agent with repository file access. +metadata: + owner: vstack + maturity: stable +user-invocable: true +disable-model-invocation: false diff --git a/src/vstack/_templates/skills/gdpr/template.md b/src/vstack/_templates/skills/gdpr/template.md new file mode 100644 index 0000000..f6d9c6e --- /dev/null +++ b/src/vstack/_templates/skills/gdpr/template.md @@ -0,0 +1,213 @@ +{{SKILL_CONTEXT}} + +# gdpr — GDPR-Compliant Engineering + +Actionable GDPR reference for engineers, architects, and tech leads working with +personal data. Based on GDPR Articles 5, 25, 32, 33, 35 and CNIL developer +guidance. + +> **Golden Rule:** Collect less. Store less. Expose less. Retain less. +> Every byte of personal data you do not collect is a byte you cannot lose, +> cannot breach, and cannot be held liable for. + +## Out of scope + +- General security audit (use `security`) +- STRIDE threat modeling (use `threat-model`) +- Dependency vulnerability scanning (use `dependency`) + +## Glossary + +| Term | Meaning | +| -------- | ------------------------------------------------------------------------- | +| **RoPA** | Record of Processing Activities — maintained by the controller | +| **DPIA** | Data Protection Impact Assessment — required for high-risk processing | +| **DPA** | Data Processing Agreement — required with every sub-processor | +| **DSR** | Data Subject Request — access, erasure, portability, rectification | +| **DEK** | Data Encryption Key — used for column-level encryption | +| **KMS** | Key Management Service — e.g. AWS Secrets Manager, Azure Key Vault, Vault | + +## Step 1: Core Principles (Article 5) + +| Principle | Engineering obligation | +| ---------------------------------- | ------------------------------------------------------------------------------------------- | +| Lawfulness, fairness, transparency | Document legal basis for every processing activity in the RoPA | +| Purpose limitation | Data collected for purpose A **must not** be reused for purpose B without a new legal basis | +| Data minimization | Collect only fields with a documented business need | +| Accuracy | Provide update endpoints; propagate corrections to downstream stores | +| Storage limitation | Define TTL at schema design time — never after | +| Integrity & confidentiality | Encrypt at rest and in transit; restrict and audit access | +| Accountability | Maintain evidence of compliance; RoPA ready for DPA inspection at any time | + +## Step 2: Privacy by Design & by Default + +**MUST:** + +- Add `created_at`, `retention_expires_at` to every table holding personal data +- Default all optional data collection to **off** — users opt in, never opt out +- Conduct a **DPIA** before building high-risk processing (biometrics, health data, large-scale profiling, systematic monitoring) +- Update the **RoPA** with every new feature that introduces a processing activity +- Sign a **DPA** with every sub-processor before data flows to them + +**MUST NOT:** + +- Ship a new data collection feature without a documented legal basis +- Enable analytics, tracking, or telemetry by default without explicit consent +- Store personal data in a system not listed in the RoPA + +## Step 3: Data Minimization + +**MUST:** + +- Map every DTO/model field to a concrete business need; remove undocumented fields +- Use separate DTOs for create, read, and update operations +- Return only what the caller is authorized to see — use response projections +- Mask sensitive values at the edge: return `****1234` for card numbers, never the full value +- Exclude sensitive fields (DOB, national ID, health) from default list/search projections + +**MUST NOT:** + +- Log full request/response bodies if they may contain personal data +- Include personal data in URL path segments or query parameters (appears in CDN logs and browser history) +- Collect `date_of_birth`, national ID, or health data without an explicit legal basis + +## Step 4: Storage Limitation & Retention + +Every table holding personal data **must** have a defined retention period. + +| Data type | Max retention | +| ------------------------- | ---------------------------------------------- | +| Auth / audit logs | 12–24 months | +| Session / refresh tokens | 30–90 days | +| Email / notification logs | 6 months | +| Inactive user accounts | 12 months after last login → notify → delete | +| Payment records | As required by tax law (7–10 years), minimized | +| Analytics events | 13 months | + +**MUST:** + +- Enforce retention automatically via a scheduled job or TTL policy — never a manual process +- Anonymize or delete data when retention expires +- Add `retention_expires_at` column — compute at insert time +- Use soft-delete (`deleted_at`) with a scheduled hard-delete after the erasure request window (30 days) + +**MUST NOT:** + +- Retain personal data indefinitely "in case it becomes useful later" + +## Step 5: API Design + +**MUST:** + +- Never include personal data in URL paths or query parameters +- Authenticate all endpoints that return or accept personal data +- Extract acting user identity from the JWT — never from the request body +- Validate ownership on every resource: return 403 if `resource.owner_id != current_user_id` +- Use UUIDs or opaque identifiers — never sequential integers as public resource IDs +- Rate-limit sensitive endpoints (login, data export, password reset) + +**MUST NOT:** + +- Return stack traces, internal paths, or database errors in API responses +- Use `Access-Control-Allow-Origin: *` on authenticated APIs + +## Step 6: Logging + +**MUST:** + +- Anonymize IPs in application logs — mask last octet (IPv4) or last 80 bits (IPv6) +- Enforce log retention — purge automatically after the defined period +- Log events, not data: `"user {id} updated email"` not `"email changed from a@b.com"` + +**MUST NOT log:** + +- Passwords, tokens, session IDs, credentials, card numbers, national IDs, health data +- Full request/response bodies where PII may be present + +## Step 7: Encryption + +| Scope | Minimum standard | +| --------------------------------------------- | -------------------------------------------------- | +| Standard personal data | AES-256 disk/volume encryption | +| Sensitive data (health, financial, biometric) | AES-256 column-level + envelope encryption via KMS | +| In transit | TLS 1.2+ (prefer 1.3); HSTS enforced | +| Keys | HSM-backed KMS; rotate DEKs annually | + +**Password hashing:** Use **Argon2id** (recommended) or **bcrypt** (cost ≥ 12). +Never MD5, SHA-1, or SHA-256 for passwords. + +**MUST NOT:** Allow TLS 1.0/1.1, null cipher suites, or hardcoded encryption keys. + +## Step 8: Secrets Management + +- Store all secrets in a KMS: AWS Secrets Manager, Azure Key Vault, GCP Secret Manager, or HashiCorp Vault +- Use pre-commit hooks (`gitleaks`, `detect-secrets`) to prevent secret commits +- Rotate secrets on developer offboarding, annual schedule, or suspected compromise + +`.gitignore` must include: `.env`, `.env.*`, `*.pem`, `*.key`, `*.pfx`, `*.p12`, `secrets/` + +## Step 9: Anonymization & Pseudonymization + +- **Anonymization** = irreversible → falls outside GDPR scope; use for retained records after erasure +- **Pseudonymization** = reversible with a key → still personal data, but reduced risk +- When erasing a user, anonymize records that must be retained (financial, audit) rather than deleting them +- Store the pseudonymization key in the KMS — never in the same database as the pseudonymized data + +**MUST NOT** call data "anonymized" if re-identification is possible through linkage attacks. + +## Step 10: Testing with Fake Data + +**MUST NOT:** + +- Use production personal data in dev, staging, or CI environments +- Restore production DB backups to non-production without scrubbing PII first + +Use synthetic data generators: `Faker` (Python/JS/Ruby), `factory_boy` (Python). +Use `@example.com` for all test email addresses. + +## PR Review Checklist + +### Data model + +- [ ] Every new PII column has a documented purpose and retention period +- [ ] Sensitive fields (health, financial, national ID) use column-level encryption +- [ ] No sequential integer PKs as public-facing identifiers + +### API + +- [ ] No PII in URL paths or query parameters +- [ ] All endpoints returning personal data are authenticated +- [ ] Ownership checks present — users cannot access other users' resources +- [ ] Rate limiting applied to sensitive endpoints + +### Logging + +- [ ] No passwords, tokens, or credentials logged +- [ ] IPs anonymized (last octet masked) +- [ ] No full request/response bodies logged where PII may be present + +### Infrastructure + +- [ ] No public storage buckets or public-IP databases +- [ ] Encryption at rest enabled for new storage resources +- [ ] New geographic regions for data storage are EEA-compliant or covered by SCCs + +### Retention & erasure + +- [ ] Retention enforcement covers new data store or field +- [ ] Erasure pipeline updated to cover new data store + +### User rights & governance + +- [ ] Data export endpoint includes any new personal data field +- [ ] RoPA updated if a new processing activity is introduced +- [ ] New sub-processors have a signed DPA and a RoPA entry +- [ ] DPIA triggered if the change involves high-risk processing + +## References + +> GDPR is a legal instrument — always consult the authoritative text and current DPA guidance rather than summaries. + +- [GDPR full text (EUR-Lex)](https://eur-lex.europa.eu/eli/reg/2016/679) +- [CNIL developer guide (privacy by design)](https://www.cnil.fr/en/cnil-publishes-gdpr-guide-developers) +- [EDPB guidelines](https://www.edpb.europa.eu/our-work-tools/general-guidance/guidelines-recommendations-best-practices_en) diff --git a/src/vstack/_templates/skills/gh-issues/config.yaml b/src/vstack/_templates/skills/gh-issues/config.yaml new file mode 100644 index 0000000..84a82d5 --- /dev/null +++ b/src/vstack/_templates/skills/gh-issues/config.yaml @@ -0,0 +1,16 @@ +name: gh-issues +version: 20260502025 +description: | + Create, update, and manage GitHub issues using the gh CLI. Covers bug reports, + feature requests, tasks, labels, assignees, milestones, sub-issues, and issue + workflows. Use when asked to "create an issue", "file a bug", "create a feature + request", "update issue #N", "add a label", or "close an issue". +argument-hint: '[what to create or which issue number to update]' + +license: MIT +compatibility: Requires a skills-compatible agent with terminal command execution and GitHub CLI authentication (`gh auth status`). +metadata: + owner: vstack + maturity: stable +user-invocable: true +disable-model-invocation: false diff --git a/src/vstack/_templates/skills/gh-issues/template.md b/src/vstack/_templates/skills/gh-issues/template.md new file mode 100644 index 0000000..14ebe31 --- /dev/null +++ b/src/vstack/_templates/skills/gh-issues/template.md @@ -0,0 +1,194 @@ +{{SKILL_CONTEXT}} + +# gh-issues — GitHub Issue Management + +Create, update, and manage GitHub issues using the `gh` CLI. + +## Out of scope + +- Pull requests (use `pr`) +- Release notes (use `release-notes`) +- Project boards — use `gh project` commands or GitHub UI directly + +## Step 0: Pre-flight + +```bash +# Verify gh CLI is authenticated +gh auth status 2>/dev/null || echo "ERROR: gh CLI not authenticated" + +# Identify the repository +gh repo view --json nameWithOwner --jq '.nameWithOwner' 2>/dev/null +``` + +## Step 1: Determine Action + +Classify the request: + +- **Create:** new bug report, feature request, or task +- **Update:** edit title, body, labels, assignees, milestone, or state +- **Query:** list, search, or view issues + +## Step 2: Query Existing Issues (when relevant) + +Before creating, check if a similar issue already exists: + +```bash +# List open issues with optional filter +gh issue list --state open --limit 20 + +# Search for similar issues +gh issue list --search "<keyword>" --state all --limit 10 + +# View a specific issue +gh issue view <number> +``` + +## Step 3: Create an Issue + +### Bug report + +```bash +gh issue create \ + --title "Short imperative description of the bug" \ + --body "## Description +What is broken and what impact does it have? + +## Steps to Reproduce +1. +2. +3. + +## Expected Behavior +What should happen. + +## Actual Behavior +What happens instead. + +## Environment +- Version/commit: +- OS/Platform: +- Relevant config:" \ + --label "bug" +``` + +### Feature request + +```bash +gh issue create \ + --title "Add <capability>" \ + --body "## Summary +One-paragraph description of the feature and its value. + +## Motivation +Why is this needed? Who benefits? + +## Proposed Solution +How it could be implemented at a high level. + +## Acceptance Criteria +- [ ] Criterion 1 +- [ ] Criterion 2" \ + --label "enhancement" +``` + +### Task / chore + +```bash +gh issue create \ + --title "Imperative description of the task" \ + --body "## Context +Why this task is needed. + +## Definition of Done +- [ ] Step 1 +- [ ] Step 2" \ + --label "task" +``` + +### With assignees and milestone + +```bash +gh issue create \ + --title "<title>" \ + --body "<body>" \ + --assignee "<github-username>" \ + --milestone "<milestone-title>" +``` + +## Step 4: Update an Existing Issue + +```bash +# Edit title or body +gh issue edit <number> --title "<new-title>" +gh issue edit <number> --body "<new-body>" + +# Add or remove labels +gh issue edit <number> --add-label "bug" --remove-label "needs-triage" + +# Change assignees +gh issue edit <number> --add-assignee "<username>" + +# Set milestone +gh issue edit <number> --milestone "<milestone-title>" + +# Close or reopen +gh issue close <number> --comment "Resolved in <commit/PR>." +gh issue reopen <number> + +# Add a comment +gh issue comment <number> --body "Comment text." +``` + +## Step 5: Sub-issues (if hierarchy is needed) + +GitHub supports sub-issues via the REST API: + +```bash +# Create sub-issue and link to parent +PARENT=<parent-issue-number> +CHILD=$(gh issue create \ + --title "<sub-task title>" \ + --body "Sub-task for #$PARENT." \ + --json number --jq '.number') + +# Link child to parent via REST API +OWNER_REPO=$(gh repo view --json nameWithOwner --jq '.nameWithOwner') +gh api "repos/$OWNER_REPO/issues/$PARENT/sub_issues" \ + -X POST \ + -f sub_issue_id="$CHILD" +``` + +## Title guidelines + +- Use imperative mood: "Add dark mode", not "Dark mode addition" +- Be specific: "Login fails with SSO enabled" not "SSO broken" +- Keep under 72 characters +- Do not prefix with `[Bug]` or `[Feature]` — use labels instead + +## Standard labels + +| Label | Use for | +| ------------------ | ----------------------------------- | +| `bug` | Something is broken | +| `enhancement` | New feature or improvement | +| `documentation` | Docs-only change | +| `task` | Internal maintenance or chore | +| `good first issue` | Suitable for new contributors | +| `help wanted` | Extra attention or expertise needed | +| `wontfix` | Will not be addressed | +| `duplicate` | Already tracked elsewhere | + +## Output + +Report the URL after creation or update: + +```text +https://github.com/<org>/<repo>/issues/<number> +``` + +## References + +> Always use the official documentation for the exact version in use — options and syntax change between releases. + +- [gh issue — GitHub CLI manual](https://cli.github.com/manual/gh_issue) +- [GitHub Issues documentation](https://docs.github.com/en/issues) diff --git a/src/vstack/_templates/skills/gh-release/config.yaml b/src/vstack/_templates/skills/gh-release/config.yaml new file mode 100644 index 0000000..282ecce --- /dev/null +++ b/src/vstack/_templates/skills/gh-release/config.yaml @@ -0,0 +1,17 @@ +name: gh-release +version: 20260502023 +description: | + Create or update a GitHub Release using the gh CLI from prepared release artifacts. + Handles immutable tag checks, draft/publish/prerelease flow, release notes source + selection, optional asset upload, and release metadata verification before publication. + Use when asked to "create a GitHub release", "publish a release", or + "draft release with gh". +argument-hint: '[version/tag and release notes source]' + +license: MIT +compatibility: Requires a skills-compatible agent with repository file access, terminal command execution, and GitHub CLI authentication (`gh auth status`). +metadata: + owner: vstack + maturity: stable +user-invocable: true +disable-model-invocation: false diff --git a/src/vstack/_templates/skills/gh-release/template.md b/src/vstack/_templates/skills/gh-release/template.md new file mode 100644 index 0000000..af41c9d --- /dev/null +++ b/src/vstack/_templates/skills/gh-release/template.md @@ -0,0 +1,181 @@ +{{SKILL_CONTEXT}} + +# gh-release — Create or Update GitHub Release via gh CLI + +Create or update a GitHub Release from prepared release artifacts using `gh`. + +## Out of scope + +- Writing release notes content from scratch (use `release-notes`) +- Opening pull requests (use `pr`) +- Deploying to runtime environments + +## Deliverable + +- A draft or published GitHub Release for the requested tag/version + +## Step 1: Preconditions + +Validate repository state and CLI auth: + +```bash +gh auth status +git remote -v +git status --short +``` + +If `gh auth status` fails: stop and request authenticated `gh` session. + +## Step 2: Determine release inputs + +Capture required inputs: + +```text +Tag/version: [e.g. v2.2.0] +Target commit/branch: [default: current HEAD] +Release title: [e.g. v2.2.0] +Mode: [draft | publish] +Release kind: [stable | prerelease] +Latest flag: [auto | mark-latest | do-not-mark-latest] +Notes source: [docs/releases/{date}.md | generated] +Artifacts: [optional files to attach] +``` + +Validate that notes source exists when a file path is provided. + +## Step 3: Validate tag strategy + +Check whether the tag already exists: + +```bash +TAG="<tag>" +git rev-parse "$TAG" >/dev/null 2>&1 && echo "tag-exists" || echo "tag-missing" +``` + +Rules: + +- If tag exists and points to unexpected commit: stop and escalate. +- If tag is missing, create annotated tag only when explicitly requested. +- Never retarget an existing release tag to a different commit. + +Compare target commit with tag commit when tag exists: + +```bash +TARGET_SHA=$(git rev-parse "<target>") +TAG_SHA=$(git rev-list -n 1 "$TAG") +if [ "$TARGET_SHA" != "$TAG_SHA" ]; then + echo "ERROR: existing tag points to different commit" + exit 1 +fi +``` + +Tag creation example: + +```bash +git tag -a "$TAG" -m "Release $TAG" +git push origin "$TAG" +``` + +## Step 4: Create or update release + +Preferred flow with notes file: + +```bash +gh release create "$TAG" \ + --title "<title>" \ + --notes-file "<notes-file>" \ + --target "<target>" \ + --draft +``` + +Publish directly (if requested): + +```bash +gh release create "$TAG" \ + --title "<title>" \ + --notes-file "<notes-file>" \ + --target "<target>" +``` + +Pre-release mode: + +```bash +gh release create "$TAG" \ + --title "<title>" \ + --notes-file "<notes-file>" \ + --target "<target>" \ + --prerelease +``` + +If notes file is unavailable and generated notes are approved: + +```bash +gh release create "$TAG" \ + --title "<title>" \ + --generate-notes \ + --target "<target>" \ + --draft +``` + +If the release already exists, update it: + +```bash +gh release edit "$TAG" \ + --title "<title>" \ + --notes-file "<notes-file>" +``` + +Optional latest behavior: + +- `mark-latest`: include `--latest` +- `do-not-mark-latest`: include `--latest=false` + +Optional artifact upload: + +```bash +gh release upload "$TAG" <artifact-path> --clobber +``` + +When uploading binaries, attach checksums when available: + +```bash +sha256sum <artifact-path> > <artifact-path>.sha256 +gh release upload "$TAG" <artifact-path>.sha256 --clobber +``` + +## Step 5: Verify release state + +Confirm final release metadata: + +```bash +gh release view "$TAG" --json name,tagName,isDraft,isPrerelease,isLatest,url +``` + +Verify: + +- tag is correct +- title is correct +- draft/published mode matches request +- prerelease/latest flags match request +- release URL is available + +## Step 6: Report outcome + +Report a concise summary: + +```text +GitHub Release ready: +- Tag: <tag> +- Title: <title> +- Mode: <draft|published> +- URL: <release-url> +``` + +If blocked, report exact blocker and required user action. + +## References + +> Always use the official documentation for the gh CLI version in use — flags and subcommands are added and changed between releases. + +- [gh release — GitHub CLI manual](https://cli.github.com/manual/gh_release) +- [GitHub Releases documentation](https://docs.github.com/en/repositories/releasing-projects-on-github/about-releases) diff --git a/src/vstack/_templates/skills/guardrails/config.yaml b/src/vstack/_templates/skills/guardrails/config.yaml index 4863239..b8213d3 100644 --- a/src/vstack/_templates/skills/guardrails/config.yaml +++ b/src/vstack/_templates/skills/guardrails/config.yaml @@ -1,5 +1,5 @@ name: guardrails -version: 1.0.2 +version: 20260421016 description: | Activate safety guardrails for the current session. Before any destructive command (rm -rf, DROP TABLE, git push --force, git reset --hard, kubectl delete, diff --git a/src/vstack/_templates/skills/guardrails/template.md b/src/vstack/_templates/skills/guardrails/template.md index 2b7e85f..cf459a9 100644 --- a/src/vstack/_templates/skills/guardrails/template.md +++ b/src/vstack/_templates/skills/guardrails/template.md @@ -8,8 +8,6 @@ Activate careful mode for this session. Two behaviors are now enabled. - Code review or security audit (use `code-review` or `security`) -______________________________________________________________________ - ## Behavior 1: Careful Mode (always active after invoking this skill) **Before executing any of the following commands, get explicit confirmation:** @@ -36,10 +34,6 @@ ______________________________________________________________________ 1. Only proceed if the user says yes. 1. Never use workarounds to avoid this confirmation. -______________________________________________________________________ - ## How to Deactivate Explicitly ask to "disable guardrails". - -______________________________________________________________________ diff --git a/src/vstack/_templates/skills/helm/config.yaml b/src/vstack/_templates/skills/helm/config.yaml new file mode 100644 index 0000000..81eb68d --- /dev/null +++ b/src/vstack/_templates/skills/helm/config.yaml @@ -0,0 +1,16 @@ +name: helm +version: 20260502037 +description: | + Write, review, and operate Helm charts and release lifecycles. Covers chart + structure, values layering, lint/template validation, install/upgrade/rollback, + dependency handling, and release troubleshooting. Use when asked to "create a Helm chart", + "review Helm values", "upgrade Helm release", or "debug Helm deployment". +argument-hint: '[chart path, release name, namespace, and scope: chart review | install | upgrade | rollback]' + +license: MIT +compatibility: Requires a skills-compatible agent with repository file access. Requires Helm CLI and target cluster access for live release operations. +metadata: + owner: vstack + maturity: stable +user-invocable: true +disable-model-invocation: false diff --git a/src/vstack/_templates/skills/helm/template.md b/src/vstack/_templates/skills/helm/template.md new file mode 100644 index 0000000..049a749 --- /dev/null +++ b/src/vstack/_templates/skills/helm/template.md @@ -0,0 +1,107 @@ +{{SKILL_CONTEXT}} + +# helm - Helm Chart and Release Workflows + +Write, review, and operate Helm charts and release lifecycles. + +## Out of scope + +- Raw Kubernetes manifest-only workflows (use `k8s`) +- Rancher/Fleet governance workflows (use `rancher`) + +## Step 0: Detect Context + +```bash +helm version 2>/dev/null || echo "helm not installed" + +# Detect charts +find . -name Chart.yaml -o -path "*/charts/*" | head -40 +``` + +## Step 1: Chart Structure Review + +Expected chart layout: + +- `Chart.yaml` for metadata and dependencies +- `values.yaml` for defaults +- `templates/` for rendered resources +- `templates/_helpers.tpl` for naming/labels helpers + +```bash +helm show chart <chart-path> +helm show values <chart-path> +``` + +## Step 2: Static Validation Before Deploy + +```bash +# Lint chart and values +helm lint <chart-path> -f values.yaml + +# Render to inspect final manifests +helm template <release> <chart-path> -n <namespace> -f values.yaml > rendered.yaml + +# Optional Kubernetes dry-run check +kubectl apply --dry-run=server -f rendered.yaml +``` + +Validation checklist: + +- Workload resources define `requests`/`limits` +- Probes exist for long-running services +- Service selectors match deployment labels +- Secrets are referenced, not hardcoded in values + +## Step 3: Install and Upgrade Safely + +```bash +# Install +helm install <release> <chart-path> -n <namespace> --create-namespace -f values.yaml + +# Upgrade with safety flags +helm upgrade <release> <chart-path> -n <namespace> -f values.yaml \ + --atomic --timeout 10m --history-max 10 + +# Check release state +helm list -n <namespace> +helm status <release> -n <namespace> +``` + +Use environment-specific values files (`values-dev.yaml`, `values-prod.yaml`) and keep overrides minimal. + +## Step 4: Rollback and Incident Recovery + +```bash +helm history <release> -n <namespace> +helm rollback <release> <revision> -n <namespace> +``` + +Rollback policy: + +- Identify the last known healthy revision +- Roll back first, then investigate forward fix +- Capture failing diff for follow-up hardening + +## Step 5: Dependencies and Supply Chain + +```bash +# Resolve chart dependencies +helm dependency update <chart-path> + +# Inspect rendered manifests for dependency side effects +helm template <release> <chart-path> -f values.yaml | head -80 +``` + +Practices: + +- Pin dependency versions in `Chart.yaml` +- Review transitive chart defaults before promotion +- Avoid unverified third-party repositories in production + +## References + +> Always use the official documentation for the exact Helm and Kubernetes versions in use - chart schema, flags, and behavior evolve between releases. + +- [Helm documentation](https://helm.sh/docs/) +- [Helm command reference](https://helm.sh/docs/helm/) +- [Chart best practices](https://helm.sh/docs/chart_best_practices/) diff --git a/src/vstack/_templates/skills/incident/config.yaml b/src/vstack/_templates/skills/incident/config.yaml index d474936..b59ccbf 100644 --- a/src/vstack/_templates/skills/incident/config.yaml +++ b/src/vstack/_templates/skills/incident/config.yaml @@ -1,5 +1,5 @@ name: incident -version: 1.0.1 +version: 20260421017 description: | Incident analysis and post-mortem writing. Guides a structured investigation from timeline reconstruction through root cause identification to a blameless diff --git a/src/vstack/_templates/skills/incident/template.md b/src/vstack/_templates/skills/incident/template.md index 0a62082..20f17c5 100644 --- a/src/vstack/_templates/skills/incident/template.md +++ b/src/vstack/_templates/skills/incident/template.md @@ -15,8 +15,6 @@ document. The goal is learning and prevention — not blame. **Golden rule: Incidents are system failures, not human failures. Every finding must be framed as a system improvement opportunity, never as individual blame.** -______________________________________________________________________ - ## Step 0: Gather Incident Context Before analysis, collect all available evidence: @@ -54,8 +52,6 @@ Services: [list of affected services] Impact: [user-facing description] ``` -______________________________________________________________________ - ## Step 1: Reconstruct the Timeline Build a precise, chronological timeline of events. Include: @@ -81,8 +77,6 @@ Key markers: Total duration: N hours N minutes ``` -______________________________________________________________________ - ## Step 2: Identify Contributing Factors List ALL factors that contributed to the incident — not just the "trigger". @@ -119,8 +113,6 @@ Categorize contributing factors: | External | [e.g. upstream dependency failure, cloud provider issue] | | Knowledge | [e.g. undocumented behaviour, tribal knowledge gap] | -______________________________________________________________________ - ## Step 3: Determine Root Cause The root cause is the deepest systemic condition that, if addressed, would @@ -144,8 +136,6 @@ Class of incident: Capacity / traffic | Data corruption | Security breach | Other] ``` -______________________________________________________________________ - ## Step 4: Assess Impact Quantify the impact precisely: @@ -169,8 +159,6 @@ Detection gap: Why not faster: [threshold too high | missing alert | other] ``` -______________________________________________________________________ - ## Step 5: Write Action Items Action items must be: @@ -197,8 +185,6 @@ Process (improve how we handle incidents): [ ] [specific action] — owner: [name/team] — due: [date/sprint] ``` -______________________________________________________________________ - ## Step 6: Produce the Post-Mortem Document Write the post-mortem to `docs/postmortems/YYYY-MM-DD-<slug>.md`: @@ -272,8 +258,6 @@ Written for a non-technical audience.] What does this incident teach us about our system, processes, or culture?] ``` -______________________________________________________________________ - ## Output ```text diff --git a/src/vstack/_templates/skills/inspect/config.yaml b/src/vstack/_templates/skills/inspect/config.yaml index 0df4f74..c2a38a2 100644 --- a/src/vstack/_templates/skills/inspect/config.yaml +++ b/src/vstack/_templates/skills/inspect/config.yaml @@ -1,5 +1,5 @@ name: inspect -version: 1.0.2 +version: 20260421018 description: | Read-only verification audit. Runs baseline plus optional extended checks, produces severity-ranked findings, and makes no code or commit changes. diff --git a/src/vstack/_templates/skills/inspect/template.md b/src/vstack/_templates/skills/inspect/template.md index 34207b8..e3f6939 100644 --- a/src/vstack/_templates/skills/inspect/template.md +++ b/src/vstack/_templates/skills/inspect/template.md @@ -23,8 +23,6 @@ Use `verify` when a fix loop is required. - Optional WIP area for complex/uncertain efforts: `docs/delta/{id}/TESTING_DELTA.md` - Before merge: consolidate any blocking findings and final verdict into baseline reports. -______________________________________________________________________ - ## Step 0: Scope ```text @@ -32,8 +30,6 @@ Report only. No edits. No commits. If critical issues are found, recommend `verify`. ``` -______________________________________________________________________ - ## Step 1: Baseline Checks ```bash @@ -46,8 +42,6 @@ ______________________________________________________________________ {{RUN_TESTS}} -______________________________________________________________________ - ## Step 2: Extended Checks (when present) ```bash @@ -75,8 +69,6 @@ Confirm for changed paths: - Trace propagation exists across service boundaries where applicable. - Alerts/runbooks exist for high-severity failure modes. -______________________________________________________________________ - ## Step 3: Report ```text @@ -101,5 +93,3 @@ ______________________________________________________________________ ### Recommendation [SHIP-READY | USE VERIFY FIX LOOP | NEEDS ARCH/DESIGN REVIEW] ``` - -______________________________________________________________________ diff --git a/src/vstack/_templates/skills/k8s/config.yaml b/src/vstack/_templates/skills/k8s/config.yaml new file mode 100644 index 0000000..328f662 --- /dev/null +++ b/src/vstack/_templates/skills/k8s/config.yaml @@ -0,0 +1,17 @@ +name: k8s +version: 20260502036 +description: | + Write, review, and troubleshoot Kubernetes manifests and operational workflows. + Covers workload resources, service exposure, rollout safety, health probes, + RBAC, namespace isolation, and kubectl-based diagnostics. Use when asked to + "deploy to Kubernetes", "review Kubernetes manifests", "debug Kubernetes rollout", + "harden Kubernetes config", or "operate a workload on a cluster". +argument-hint: '[cluster/context, namespace, and scope: manifest review | deploy | rollout debug | hardening]' + +license: MIT +compatibility: Requires a skills-compatible agent with repository file access. Requires kubectl access to a target cluster for live operations. +metadata: + owner: vstack + maturity: stable +user-invocable: true +disable-model-invocation: false diff --git a/src/vstack/_templates/skills/k8s/template.md b/src/vstack/_templates/skills/k8s/template.md new file mode 100644 index 0000000..30e443d --- /dev/null +++ b/src/vstack/_templates/skills/k8s/template.md @@ -0,0 +1,111 @@ +{{SKILL_CONTEXT}} + +# k8s - Kubernetes Workflows + +Write, review, and troubleshoot Kubernetes manifests and cluster operations. + +## Out of scope + +- Helm chart authoring and release lifecycle (use `helm`) +- Rancher/Fleet multi-cluster governance (use `rancher`) + +## Step 0: Detect Context + +```bash +kubectl version --client 2>/dev/null || echo "kubectl not installed" +kubectl config current-context 2>/dev/null || echo "no current context" + +# Find Kubernetes manifests in common locations +find . -type f \( -name "*.yaml" -o -name "*.yml" \) \ + | rg '/(k8s|kubernetes|manifests)/|deployment|service|ingress|statefulset' -N || true +``` + +## Step 1: Validate Manifests + +```bash +# API/schema and field validation +kubectl apply --dry-run=client -f k8s/ + +# Optional: server-side admission and API validation +kubectl apply --dry-run=server -f k8s/ +``` + +Validation checklist: + +- Every workload sets CPU/memory `requests` and `limits` +- Liveness and readiness probes are present and realistic +- Image tags are explicit (avoid mutable `:latest`) +- Namespace and labels are consistent across resources +- RBAC permissions follow least privilege + +## Step 2: Safe Deploy and Rollout + +```bash +# Apply manifests to a namespace +kubectl apply -n <namespace> -f k8s/ + +# Track rollout status +kubectl rollout status deploy/<name> -n <namespace> + +# View current replica health +kubectl get deploy,po -n <namespace> +``` + +For updates: + +- Prefer rolling updates over delete/recreate +- Set deployment strategy (`maxUnavailable`, `maxSurge`) explicitly +- Keep rollback path ready (`kubectl rollout undo`) + +## Step 3: Service Exposure and Networking + +```bash +kubectl get svc,ing -n <namespace> +kubectl describe svc <service-name> -n <namespace> +kubectl describe ing <ingress-name> -n <namespace> +``` + +Checks: + +- Service selectors match pod labels +- Ingress host/path routes are deterministic +- TLS secrets and ingress class are configured where required +- NetworkPolicies default-deny inbound where possible + +## Step 4: Troubleshooting Workflow + +```bash +# Pod state and events +kubectl get po -n <namespace> +kubectl describe po <pod-name> -n <namespace> +kubectl get events -n <namespace> --sort-by=.lastTimestamp | tail -30 + +# Container logs +kubectl logs <pod-name> -n <namespace> --all-containers --tail=200 + +# Exec for runtime inspection +kubectl exec -it <pod-name> -n <namespace> -- /bin/sh +``` + +Common failure classes: + +- `ImagePullBackOff`: image name/tag/registry credentials +- `CrashLoopBackOff`: startup command/config/secrets mismatch +- `Pending`: resource requests exceed cluster capacity +- Probe flaps: probe timing too strict for startup behavior + +## Step 5: Security and Reliability Hardening + +- Run containers as non-root where possible +- Set `readOnlyRootFilesystem: true` when feasible +- Drop unnecessary Linux capabilities +- Avoid broad `ClusterRoleBinding` grants +- Use PodDisruptionBudgets for critical workloads + +## References + +> Always use the official documentation for the exact Kubernetes version in use - API versions and defaults change between releases. + +- [Kubernetes documentation](https://kubernetes.io/docs/) +- [kubectl reference](https://kubernetes.io/docs/reference/kubectl/) +- [Kubernetes API reference](https://kubernetes.io/docs/reference/kubernetes-api/) diff --git a/src/vstack/_templates/skills/migrate/config.yaml b/src/vstack/_templates/skills/migrate/config.yaml index cb8520f..a821389 100644 --- a/src/vstack/_templates/skills/migrate/config.yaml +++ b/src/vstack/_templates/skills/migrate/config.yaml @@ -1,5 +1,5 @@ name: migrate -version: 1.0.1 +version: 20260421019 description: | Database migration review and authoring. Covers forwards/backwards compatibility, zero-downtime strategies, rollback plans, data integrity, and index safety. diff --git a/src/vstack/_templates/skills/migrate/template.md b/src/vstack/_templates/skills/migrate/template.md index d17c89e..57aa856 100644 --- a/src/vstack/_templates/skills/migrate/template.md +++ b/src/vstack/_templates/skills/migrate/template.md @@ -17,8 +17,6 @@ deployability. No migration ships without a rollback plan. **Golden rule: Every migration must be reversible or explicitly documented as irreversible with a data-recovery plan.** -______________________________________________________________________ - ## Step 0: Understand the Change Before reviewing or writing anything, gather context: @@ -34,7 +32,7 @@ Before reviewing or writing anything, gather context: ```bash # Find existing migration files find . -type f \( -name '*.sql' -o -name '*migration*' -o -name '*migrate*' \) \ - --exclude-dir=.venv --exclude-dir=node_modules --exclude-dir=dist --exclude-dir=build \ + -not \( -path '*/.venv/*' -o -path '*/node_modules/*' -o -path '*/dist/*' -o -path '*/build/*' \) \ 2>/dev/null | sort | tail -20 # Show migration files changed in this branch @@ -56,8 +54,6 @@ Deployment: [rolling | blue-green | big-bang | maintenance window] Direction: [new migration | review existing | both] ``` -______________________________________________________________________ - ## Step 1: Classify the Migration Classify every DDL operation by risk level: @@ -86,8 +82,6 @@ Operations: Overall risk: [Low | Medium | High | Destructive] ``` -______________________________________________________________________ - ## Step 2: Zero-Downtime Analysis **Rolling deployments require that the schema be compatible with BOTH the old and @@ -119,8 +113,6 @@ If the migration violates zero-downtime, flag it: Fix: [expand/contract steps or maintenance window required] ``` -______________________________________________________________________ - ## Step 3: Rollback Plan Every migration must have a defined rollback: @@ -143,8 +135,6 @@ For destructive operations (DROP, TRUNCATE), rollback is not possible — docume Recovery: Restore from snapshot (RTO: [estimate]) ``` -______________________________________________________________________ - ## Step 4: Data Integrity Check: @@ -167,8 +157,6 @@ SELECT column, COUNT(*) FROM table GROUP BY column HAVING COUNT(*) > 1; SELECT COUNT(*) FROM table WHERE NOT (constraint_expression); ``` -______________________________________________________________________ - ## Step 5: Index Safety **Never create an index without `CONCURRENTLY` on a live table.** @@ -194,8 +182,6 @@ Check: - [ ] No redundant indexes (subset of existing composite index) - [ ] Partial indexes considered for filtered queries -______________________________________________________________________ - ## Step 6: Performance on Large Tables For tables with > 100k rows: @@ -237,8 +223,6 @@ BEGIN END $$; ``` -______________________________________________________________________ - ## Step 7: Testing ```bash @@ -260,8 +244,6 @@ Check: - [ ] Application tests pass with the new schema - [ ] No model/schema drift detected -______________________________________________________________________ - ## Output Produce a structured migration review: diff --git a/src/vstack/_templates/skills/onboard/config.yaml b/src/vstack/_templates/skills/onboard/config.yaml index ed27f35..c8ed6b4 100644 --- a/src/vstack/_templates/skills/onboard/config.yaml +++ b/src/vstack/_templates/skills/onboard/config.yaml @@ -1,5 +1,5 @@ name: onboard -version: 1.0.1 +version: 20260421020 description: | Generate a contributor onboarding guide for a repository. Covers project purpose, architecture overview, local dev setup, test commands, contribution diff --git a/src/vstack/_templates/skills/onboard/template.md b/src/vstack/_templates/skills/onboard/template.md index 4269860..02d89e2 100644 --- a/src/vstack/_templates/skills/onboard/template.md +++ b/src/vstack/_templates/skills/onboard/template.md @@ -15,8 +15,6 @@ clone to first PR with zero tribal knowledge required. **Golden rule: If a new contributor needs to ask a question that isn't answered by the docs, that is a documentation gap — not a knowledge problem.** -______________________________________________________________________ - ## Step 0: Audit Existing Documentation ```bash @@ -44,8 +42,6 @@ Tech stack: [Python | Node | Go | other] Build tool: [Poetry | npm | make | other] ``` -______________________________________________________________________ - ## Step 1: Understand the Project Read the codebase to extract onboarding-relevant facts: @@ -70,8 +66,6 @@ cat .node-version 2>/dev/null cat .github/workflows/*.yml 2>/dev/null | grep -E 'run:|uses:' | head -30 ``` -______________________________________________________________________ - ## Step 2: Verify the Setup Steps Work Before documenting setup steps, verify they actually work: @@ -94,8 +88,6 @@ For each setup step, confirm: - [ ] Environment variables are documented (use `.env.example` if present) - [ ] The setup completes in < 5 minutes on a fresh machine -______________________________________________________________________ - ## Step 3: Extract Test Commands ```bash @@ -115,8 +107,6 @@ Type check only: [command] Single test: [command pattern] ``` -______________________________________________________________________ - ## Step 4: Identify "Good First Issues" ```bash @@ -130,14 +120,10 @@ grep -r -n "TODO\|FIXME\|HACK\|good.first" \ # (manual step — list any open "good first issue" labels) ``` -______________________________________________________________________ - ## Step 5: Write the Onboarding Guide Produce or update `CONTRIBUTING.md` with the following sections: -______________________________________________________________________ - ````markdown # Contributing to [Project Name] @@ -241,10 +227,6 @@ Link to docs/architecture/architecture.md for details.\] ```` -______________________________________________________________________ - -______________________________________________________________________ - ## Step 6: Supplement README (if needed) If README lacks a dev setup section, add a minimal one linking to CONTRIBUTING.md: @@ -263,8 +245,6 @@ Quick start: ```` -______________________________________________________________________ - ## Output ```text diff --git a/src/vstack/_templates/skills/openapi/config.yaml b/src/vstack/_templates/skills/openapi/config.yaml index da04795..5e612d8 100644 --- a/src/vstack/_templates/skills/openapi/config.yaml +++ b/src/vstack/_templates/skills/openapi/config.yaml @@ -1,5 +1,5 @@ name: openapi -version: 1.0.1 +version: 20260421021 description: | Write and review OpenAPI 3.1 specifications. Covers resource naming, HTTP method semantics, status codes, error conventions, pagination, versioning, diff --git a/src/vstack/_templates/skills/openapi/template.md b/src/vstack/_templates/skills/openapi/template.md index 3c02211..2724473 100644 --- a/src/vstack/_templates/skills/openapi/template.md +++ b/src/vstack/_templates/skills/openapi/template.md @@ -15,8 +15,6 @@ be precise, complete, and implementable without ambiguity. **Golden rule: The spec is the source of truth. Code must conform to the spec, not the other way around.** -______________________________________________________________________ - ## Step 0: Understand the Task > **Question:** What needs to be done? @@ -39,8 +37,6 @@ find . -name 'openapi*.yaml' -o -name 'openapi*.json' \ [ -f openapi.yaml ] && npx swagger-cli validate openapi.yaml 2>/dev/null || true ``` -______________________________________________________________________ - ## Part 1: Spec Structure Every OpenAPI 3.1 spec must have: @@ -84,8 +80,6 @@ Check: - [ ] Tags defined at root level and used consistently on operations - [ ] `components` section exists for reusable schemas -______________________________________________________________________ - ## Part 2: Resource & Path Design ### Naming conventions @@ -117,8 +111,6 @@ Check each path: - [ ] Every operation has a unique `operationId` (camelCase, e.g. `listUsers`, `createOrder`) - [ ] Every operation has a `summary` (short title, ≤ 80 chars) and `tags` -______________________________________________________________________ - ## Part 3: Status Codes Use exactly these status codes — no others unless justified: @@ -145,8 +137,6 @@ Check: - [ ] `401` and `403` are distinct and documented - [ ] `500` is documented but never includes stack traces -______________________________________________________________________ - ## Part 4: Error Response Schema Every error response must use a consistent schema: @@ -192,8 +182,6 @@ Check: - [ ] `request_id` for correlation is present - [ ] Field-level errors included for `400`/`422` -______________________________________________________________________ - ## Part 5: Pagination Standard cursor-based pagination (preferred for large datasets): @@ -246,8 +234,6 @@ Check: - [ ] Response includes `has_more` and `next_cursor` - [ ] `total` is optional (expensive query — only include if needed) -______________________________________________________________________ - ## Part 6: Schema Quality For each schema in `components/schemas`: @@ -290,8 +276,6 @@ Check: - [ ] No `type: object` without properties (use `additionalProperties` explicitly) - [ ] No circular `$ref` without a nullable break -______________________________________________________________________ - ## Part 7: Security Schemes ```yaml @@ -327,8 +311,6 @@ Check: - [ ] OAuth2 scopes are defined if using OAuth - [ ] No API keys in query parameters (use headers) -______________________________________________________________________ - ## Part 8: Versioning URI versioning is the recommended approach: @@ -353,8 +335,6 @@ Check: description: "Deprecated. Use /v2/users/{userId} instead." ``` -______________________________________________________________________ - ## Output Produce a review report or the corrected spec: @@ -380,3 +360,11 @@ Summary: [N critical, N warnings, N info] **If writing or correcting the spec:** produce the complete corrected YAML, using `$ref` for all reusable schemas, and validate it passes linting. + +## References + +> Always use the official specification for the OpenAPI version in use — schema keywords, security scheme types, and JSON Schema dialect support differ between 3.0 and 3.1. + +- [OpenAPI Specification 3.1](https://spec.openapis.org/oas/latest.html) +- [JSON Schema (2020-12)](https://json-schema.org/specification) +- [Redocly CLI (linting)](https://redocly.com/docs/cli/) diff --git a/src/vstack/_templates/skills/performance/config.yaml b/src/vstack/_templates/skills/performance/config.yaml index cbffd6a..7aa35d0 100644 --- a/src/vstack/_templates/skills/performance/config.yaml +++ b/src/vstack/_templates/skills/performance/config.yaml @@ -1,5 +1,5 @@ name: performance -version: 1.0.2 +version: 20260421022 description: | Performance profiling and regression detection. Establishes baselines, detects regressions, profiles bottlenecks, and recommends optimizations. Use when asked diff --git a/src/vstack/_templates/skills/performance/template.md b/src/vstack/_templates/skills/performance/template.md index 6e10890..7610c8f 100644 --- a/src/vstack/_templates/skills/performance/template.md +++ b/src/vstack/_templates/skills/performance/template.md @@ -21,8 +21,6 @@ optimizations. Measure first; never optimize without evidence. - Optional WIP area for complex/uncertain efforts: `docs/delta/{id}/PERFORMANCE_DELTA.md` - Before merge: consolidate thresholds, measurements, and recommendations into the baseline performance report. -______________________________________________________________________ - ## Setup **Parse the user's request:** @@ -33,8 +31,6 @@ ______________________________________________________________________ | Mode | Comparison (vs base branch) | `--baseline`, `--profile`, `--load-test` | | Threshold | 5% regression | `--threshold 0.10` (10%) | -______________________________________________________________________ - ## Phase 1: Establish Baseline If on a feature branch, record performance metrics before and after the change: @@ -63,8 +59,6 @@ echo "=== Benchmarks on $CURRENT ===" [ -f Cargo.toml ] && cargo bench 2>/dev/null || true ``` -______________________________________________________________________ - ## Phase 2: Comparison vs Base Branch ```bash @@ -90,8 +84,6 @@ Compare results: **Regression threshold:** Flag if any metric degrades by more than 5% (or configured threshold). -______________________________________________________________________ - ## Phase 3: Load Testing (if applicable) ```bash @@ -115,8 +107,6 @@ hey -n 1000 -c 50 "${SERVICE_URL}/health" 2>/dev/null || true wrk -t4 -c100 -d30s "${SERVICE_URL}/health" 2>/dev/null || true ``` -______________________________________________________________________ - ## Phase 4: Profiling (if regression found) If a regression is detected, profile to identify the bottleneck: @@ -145,8 +135,6 @@ Common bottleneck categories: - **Sync where async:** Blocking I/O on hot path - **Regex compilation:** Regex compiled inside hot loop -______________________________________________________________________ - ## Phase 5: Optimization Loop For each bottleneck identified: @@ -165,8 +153,6 @@ For each bottleneck identified: - Async I/O > sync I/O for I/O-bound work. - Batch > N individual calls. -______________________________________________________________________ - ## Performance Report ```text @@ -194,5 +180,3 @@ ______________________________________________________________________ ### Verdict [NO REGRESSION / REGRESSION FIXED / REGRESSION NEEDS ATTENTION] ``` - -______________________________________________________________________ diff --git a/src/vstack/_templates/skills/pr/config.yaml b/src/vstack/_templates/skills/pr/config.yaml index 979a8bd..e21790c 100644 --- a/src/vstack/_templates/skills/pr/config.yaml +++ b/src/vstack/_templates/skills/pr/config.yaml @@ -1,5 +1,5 @@ name: pr -version: 1.0.2 +version: 20260502013 description: | Commit, push, and open a pull request from the current branch to main. Uses the release notes from docs/releases/{date}.md as the PR body. diff --git a/src/vstack/_templates/skills/pr/template.md b/src/vstack/_templates/skills/pr/template.md index c6f8906..a670d4e 100644 --- a/src/vstack/_templates/skills/pr/template.md +++ b/src/vstack/_templates/skills/pr/template.md @@ -2,7 +2,7 @@ # pr — Commit, Push & Open Pull Request -Push the current branch and open a PR targeting main. This is the final step +Push the current branch and open a pull request. This is the final step before CI/CD takes over. ## Out of scope @@ -11,19 +11,17 @@ before CI/CD takes over. - Writing release notes (use `release-notes`) - Merging or deploying — CI/CD handles that after merge -## Deliverable and artifact policy +## Deliverable -- Primary deliverable: release pull request targeting main -- Baseline-first default: use existing branch artifacts directly; do not create parallel release records outside baseline docs. -- PR body source: `docs/releases/{date}.md` when present -- Before merge: ensure release artifact references in the PR body reflect final baseline files. - -______________________________________________________________________ +- A pull request open against the target base branch (typically `main`) ## Step 1: Pre-flight ```bash -# Confirm not on main +# Confirm gh CLI is authenticated +gh auth status 2>/dev/null || echo "WARNING: gh CLI not authenticated — Step 4 will fail" + +# Confirm not on the target base branch BRANCH=$(git branch --show-current) if [ "$BRANCH" = "main" ] || [ "$BRANCH" = "master" ]; then echo "ERROR: on $BRANCH — create a feature branch first" @@ -31,17 +29,23 @@ if [ "$BRANCH" = "main" ] || [ "$BRANCH" = "master" ]; then fi echo "Branch: $BRANCH" -# Check release notes exist -DATE=$(date +%Y-%m-%d) -RELEASE_FILE="docs/releases/${DATE}.md" -[ -f "$RELEASE_FILE" ] || echo "WARN: $RELEASE_FILE not found — PR body will be empty" +# Check if a PR already exists for this branch +EXISTING_PR=$(gh pr view --json url --jq '.url' 2>/dev/null) +if [ -n "$EXISTING_PR" ]; then + echo "PR already open: $EXISTING_PR" + exit 0 +fi # Show what will be included git status --short git log origin/main..HEAD --oneline -``` -______________________________________________________________________ +# Detect PR template for body structure +PR_TEMPLATE=$(cat .github/PULL_REQUEST_TEMPLATE.md \ + .github/PULL_REQUEST_TEMPLATE/pull_request_template.md \ + .github/pull_request_template.md 2>/dev/null | head -5) +[ -n "$PR_TEMPLATE" ] && echo "PR template found — use its structure for the body" +``` ## Step 2: Commit @@ -52,57 +56,63 @@ git add -A git diff --cached --stat # Only commit if there are staged changes -git diff --cached --quiet || git commit -m "release: $(date +%Y-%m-%d)" +git diff --cached --quiet || git commit -m "chore: pre-release cleanup" ``` -______________________________________________________________________ - ## Step 3: Push ```bash git push --set-upstream origin "$BRANCH" ``` -______________________________________________________________________ - ## Step 4: Open PR +Use the PR title and body provided by the invoking agent or user. +If no body is provided, write a short summary of the changes on this branch. +Use `--draft` when the work is not yet ready for review. + ```bash -DATE=$(date +%Y-%m-%d) -RELEASE_FILE="docs/releases/${DATE}.md" -BODY="" -[ -f "$RELEASE_FILE" ] && BODY=$(cat "$RELEASE_FILE") +# Short body (inline): +gh pr create \ + --base main \ + --title "<title>" \ + --body "<body>" +# Long body (write to file first): +cat > /tmp/pr-body.md <<'EOF' +<body> +EOF gh pr create \ --base main \ - --title "release: ${DATE}" \ - --body "$BODY" + --title "<title>" \ + --body-file /tmp/pr-body.md + +# Draft PR (not ready for review): +gh pr create \ + --base main \ + --title "<title>" \ + --body "<body>" \ + --draft ``` -If `gh` is not available: +If `gh` is not available or not authenticated: ```bash echo "Open PR manually:" -echo " Title: release: $(date +%Y-%m-%d)" +echo " Title: <title>" echo " Base: main" echo " Head: $BRANCH" echo " URL: https://github.com/<org>/<repo>/compare/main...$BRANCH" ``` -______________________________________________________________________ - ## Step 5: Report to user -Report the PR URL and next steps: +Report the PR URL and confirm what CI/CD will do next: ```text PR created: <url> -CI/CD will now: -- Run tests and security scan -- Build and publish container image -- Determine version (semantic-release / conventional commits) -- Deploy after approval and merge +Next steps depend on the repository CI/CD configuration: +- Automated tests and checks will run on the PR. +- Merge when all checks pass and reviewers approve. ``` - -______________________________________________________________________ diff --git a/src/vstack/_templates/skills/rancher/config.yaml b/src/vstack/_templates/skills/rancher/config.yaml new file mode 100644 index 0000000..a4aa2a1 --- /dev/null +++ b/src/vstack/_templates/skills/rancher/config.yaml @@ -0,0 +1,16 @@ +name: rancher +version: 20260502038 +description: | + Operate Kubernetes workloads and governance through Rancher. Covers cluster and + project context, role-based access, app deployment workflows, Fleet/GitOps basics, + and multi-cluster operational checks. Use when asked to "deploy through Rancher", + "review Rancher setup", "manage Rancher projects", or "troubleshoot Rancher-managed clusters". +argument-hint: '[rancher server/context, cluster/project, and scope: deploy | governance | fleet | troubleshooting]' + +license: MIT +compatibility: Requires a skills-compatible agent with repository file access. Requires Rancher UI/API access or Rancher CLI where applicable. +metadata: + owner: vstack + maturity: stable +user-invocable: true +disable-model-invocation: false diff --git a/src/vstack/_templates/skills/rancher/template.md b/src/vstack/_templates/skills/rancher/template.md new file mode 100644 index 0000000..372b2dd --- /dev/null +++ b/src/vstack/_templates/skills/rancher/template.md @@ -0,0 +1,80 @@ +{{SKILL_CONTEXT}} + +# rancher - Rancher Operations and Governance + +Operate Kubernetes workloads and governance through Rancher. + +## Out of scope + +- Cluster-agnostic Kubernetes manifest authoring (use `k8s`) +- Helm chart authoring and release logic (use `helm`) + +## Step 0: Detect Context + +```bash +# Rancher CLI is optional depending on environment +rancher --version 2>/dev/null || echo "rancher CLI not installed (UI/API mode may be used)" + +# Fleet or Rancher-managed config files in repository +find . -type f \( -name "fleet.yaml" -o -name "fleet.yml" -o -name "rancher*.yaml" -o -name "rancher*.yml" \) +``` + +## Step 1: Access and Scope Validation + +Before changes: + +- Confirm target Rancher server URL and environment +- Confirm target cluster, project, and namespace scope +- Confirm RBAC grants are least-privilege for requested operation + +Operational rule: + +- Never execute production changes from an unverified project context + +## Step 2: Workload Operations in Rancher + +Typical workflow: + +1. Select target cluster and project. +1. Validate namespace-level quotas/limits. +1. Deploy or update app workload. +1. Verify pod readiness, service reachability, and events. + +If Rancher app workflow uses Helm, validate chart and values first (via `helm` skill). + +## Step 3: Fleet and GitOps Practices + +For Fleet-managed repos: + +- Keep environment overlays explicit and small +- Pin chart/app versions across environments +- Promote via pull requests with diff review +- Treat drift as incident signal, not as expected noise + +Checks: + +- Bundle targets map to intended clusters +- No accidental wildcard targeting in production bundles +- Secret references resolve through approved secret paths + +## Step 4: Troubleshooting and Recovery + +- Use Rancher workload events and pod logs for first-line diagnosis +- Confirm cluster agent connectivity and state health +- For failed rollout, rollback to last healthy deployment revision +- Document root cause and hardening action in follow-up issue + +## Step 5: Security and Multi-Cluster Governance + +- Separate dev/staging/prod projects and access groups +- Keep project quotas and limits enforced +- Audit role bindings regularly for privilege creep +- Avoid broad administrative grants outside platform owners + +## References + +> Always use the official documentation for the exact Rancher, Fleet, and Kubernetes versions in use - capabilities and defaults vary by release. + +- [Rancher documentation](https://ranchermanager.docs.rancher.com/) +- [Rancher API guide](https://ranchermanager.docs.rancher.com/api/quickstart) +- [Fleet documentation](https://fleet.rancher.io/) diff --git a/src/vstack/_templates/skills/refactor/config.yaml b/src/vstack/_templates/skills/refactor/config.yaml index 31b8e65..04f438a 100644 --- a/src/vstack/_templates/skills/refactor/config.yaml +++ b/src/vstack/_templates/skills/refactor/config.yaml @@ -1,5 +1,5 @@ name: refactor -version: 1.0.1 +version: 20260421023 description: | Structured refactoring for backend services, APIs, and libraries. Identifies code smells, plans incremental changes, executes without altering observable diff --git a/src/vstack/_templates/skills/refactor/template.md b/src/vstack/_templates/skills/refactor/template.md index 8b38eb6..78b55bb 100644 --- a/src/vstack/_templates/skills/refactor/template.md +++ b/src/vstack/_templates/skills/refactor/template.md @@ -18,8 +18,6 @@ Refactoring is not rewriting. Every step must leave tests green. **Golden rule: If all tests pass before and after each step, the refactor is correct. If behavior changes, stop — that is a feature or bug fix, not a refactor.** -______________________________________________________________________ - ## Step 0: Define the Scope > **Question:** What needs refactoring and why? @@ -46,8 +44,6 @@ Motivation: [duplication | complexity | naming | coupling | size | other] Constraints: [what must not change] ``` -______________________________________________________________________ - ## Step 1: Establish a Baseline **Never start refactoring without a green test baseline.** @@ -71,8 +67,6 @@ Baseline: Lint: [clean | N warnings] ``` -______________________________________________________________________ - ## Step 2: Identify Code Smells Scan the target area for common smells: @@ -111,8 +105,6 @@ Smells found: P3 (low): [smell] — [location] ``` -______________________________________________________________________ - ## Step 3: Plan the Refactoring Break the refactoring into small, independent steps. Each step must: @@ -137,8 +129,6 @@ Risk: [Low | Medium — reason] - The plan requires changing database schema - More than 10 files are affected -______________________________________________________________________ - ## Step 4: Execute — One Step at a Time For each planned step: @@ -234,8 +224,6 @@ def create_user(request: CreateUserRequest) -> User: ... ``` -______________________________________________________________________ - ## Step 5: Verify After all steps are complete, run the full verification suite: @@ -256,8 +244,6 @@ git diff --stat git diff ``` -______________________________________________________________________ - ## Output ```text diff --git a/src/vstack/_templates/skills/release-notes/config.yaml b/src/vstack/_templates/skills/release-notes/config.yaml index c11e891..8244405 100644 --- a/src/vstack/_templates/skills/release-notes/config.yaml +++ b/src/vstack/_templates/skills/release-notes/config.yaml @@ -1,5 +1,5 @@ name: release-notes -version: 1.0.2 +version: 20260502014 description: | Prepare release artifacts: verify all docs are present, write release notes, own CHANGELOG.md updates, and produce docs/releases/{date}.md. diff --git a/src/vstack/_templates/skills/release-notes/template.md b/src/vstack/_templates/skills/release-notes/template.md index 4c75c8f..c930703 100644 --- a/src/vstack/_templates/skills/release-notes/template.md +++ b/src/vstack/_templates/skills/release-notes/template.md @@ -2,9 +2,8 @@ # release-notes — Release Artifact Preparation -Verify all artifacts are complete, write release notes, and update the changelog. - -This skill owns both `docs/releases/{date}.md` and `CHANGELOG.md` updates. +Write release notes and update the changelog so that the release is documented +before the PR is opened. ## Out of scope @@ -12,38 +11,31 @@ This skill owns both `docs/releases/{date}.md` and `CHANGELOG.md` updates. - Creating the PR (use `pr`) - Deployment — CI/CD takes over after merge -## Deliverable and artifact policy +## Deliverable -- Primary deliverables: `docs/releases/{date}.md`, `CHANGELOG.md` -- Baseline-first default: write final release artifacts directly to baseline docs on the feature branch. -- Optional WIP area for complex/uncertain efforts: `docs/delta/{id}/RELEASE_DELTA.md` -- Before merge: consolidate final release summary and changelog entries into baseline artifacts. +- A release notes document summarising what changed +- An updated `CHANGELOG.md` entry -______________________________________________________________________ +The invoking agent determines which files to read as evidence and where to write +the release notes. This skill describes the procedure, not the file paths. -## Step 1: Artifact checklist +## Step 1: Evidence review -Verify these files exist and are not empty: +Verify that the evidence the invoking agent has designated as required is present +and not empty. Report any missing items and stop if blockers exist. -```bash -for f in docs/product/requirements.md docs/architecture/architecture.md docs/design/design.md \ - docs/test-report.md docs/security-report.md CHANGELOG.md; do - [ -f "$f" ] && echo "✓ $f" || echo "✗ MISSING: $f" -done - -# Scope-conditional artifacts -[ -f docs/performance-baseline.md ] && echo "✓ docs/performance-baseline.md" || echo "i docs/performance-baseline.md (optional unless performance validation is in scope)" -[ -f docs/observability-baseline.md ] && echo "✓ docs/observability-baseline.md" || echo "i docs/observability-baseline.md (optional; observability evidence may be in docs/test-report.md)" -``` +Typical evidence to check (agent-defined): -If any required artifact is missing: **STOP and report**. Do not proceed. -If performance validation is in scope and `docs/performance-baseline.md` is missing: **STOP and report**. +- Test results or verification report +- Security findings or sign-off +- Change summary (git log, diff stat, or agent-provided summary) +- Acceptance criteria from requirements -______________________________________________________________________ +If any required evidence is missing: **STOP and report to the invoking agent**. ## Step 2: Summarise changes -Review what changed on this branch vs main: +Review what changed on this branch vs the base branch: ```bash git log origin/main..HEAD --oneline @@ -57,44 +49,32 @@ Identify: - Breaking changes (if any) - Internal/infrastructure changes -______________________________________________________________________ - -## Step 3: Write `docs/releases/{date}.md` +## Step 3: Write release notes +Write a release notes document to the location designated by the invoking agent. Date format: `YYYY-MM-DD` (today). Never overwrite an existing file. -```bash -DATE=$(date +%Y-%m-%d) -RELEASE_FILE="docs/releases/${DATE}.md" -[ -f "$RELEASE_FILE" ] && echo "ERROR: $RELEASE_FILE already exists" && exit 1 -mkdir -p docs/releases -``` - -Write the file with this structure: +Use this structure: ```markdown # Release {date} -## summary +## Summary [1–3 sentences: what changed and why it matters to users] -## what's new +## What's new - [user-visible feature or fix — lead with what the user can now DO] -## fixed +## Fixed - [bug fixes] -## internal +## Internal - [infra, tooling, tests — optional] -## artifacts reviewed -| artifact | status | +## Evidence reviewed +| evidence | status | |----------|--------| -| docs/product/requirements.md | ✓ | -| docs/architecture/architecture.md | ✓ | -| docs/design/design.md | ✓ | -| docs/test-report.md | ✓ | -| docs/security-report.md | ✓ | +| [evidence item] | ✓ / ✗ MISSING | ``` Rules: @@ -103,14 +83,12 @@ Rules: - No internal tracking references - Every entry should make someone think "oh nice, I want that" -______________________________________________________________________ - ## Step 4: Update `CHANGELOG.md` Prepend a new entry at the top of `CHANGELOG.md`: ```markdown -## {date} +## {version or date} ### What's new - [user-visible changes] @@ -123,5 +101,3 @@ Prepend a new entry at the top of `CHANGELOG.md`: ``` Keep existing entries intact. - -______________________________________________________________________ diff --git a/src/vstack/_templates/skills/requirements/config.yaml b/src/vstack/_templates/skills/requirements/config.yaml index b119c74..591a0cc 100644 --- a/src/vstack/_templates/skills/requirements/config.yaml +++ b/src/vstack/_templates/skills/requirements/config.yaml @@ -1,5 +1,5 @@ name: requirements -version: 1.0.2 +version: 20260421024 description: | Collaborative requirements gathering and documentation. Clarifies what must be built, defines success criteria, constraints, and non-functional requirements. diff --git a/src/vstack/_templates/skills/requirements/template.md b/src/vstack/_templates/skills/requirements/template.md index f543535..fccc36c 100644 --- a/src/vstack/_templates/skills/requirements/template.md +++ b/src/vstack/_templates/skills/requirements/template.md @@ -20,8 +20,6 @@ work from. - Optional WIP area for complex/uncertain intake: `docs/delta/{intake-id}/REQUIREMENTS_DELTA.md` - Before merge: consolidate any required content from optional delta notes back into `docs/product/requirements.md`, then remove stale WIP notes. -______________________________________________________________________ - ## Step 0: Context Read existing artifacts before asking questions: @@ -35,8 +33,6 @@ cat README.md 2>/dev/null | head -40 || true Identify what's already known and what needs clarification. -______________________________________________________________________ - ## Step 1: Problem Statement Clarify the core problem being solved: @@ -54,8 +50,6 @@ Document: [One paragraph: root problem, who has it, impact of not solving it] ``` -______________________________________________________________________ - ## Step 2: Users & Stakeholders Who uses or is affected by this? @@ -64,8 +58,6 @@ Who uses or is affected by this? | ----------- | ----------- | ------------ | | [User type] | | | -______________________________________________________________________ - ## Step 3: Functional Requirements What must the system do? Use the format: "The system must [verb] [object] [condition/constraint]." @@ -88,8 +80,6 @@ Ask for clarity on ambiguous areas: - [State what will NOT be built in this iteration] ``` -______________________________________________________________________ - ## Step 4: Non-Functional Requirements | Category | Requirement | Measurable target | @@ -105,8 +95,6 @@ Ask: > **Question:** Are there any hard non-functional requirements (performance, security, > compliance, data residency)? -______________________________________________________________________ - ## Step 5: Constraints & Assumptions Document known constraints: @@ -123,8 +111,6 @@ Document known constraints: - [Things assumed true that could invalidate requirements if wrong] ``` -______________________________________________________________________ - ## Step 6: Success Criteria What does "done" look like? How do we know the requirements are met? @@ -136,8 +122,6 @@ What does "done" look like? How do we know the requirements are met? - [ ] [Acceptance test: given X, when Y, then Z] ``` -______________________________________________________________________ - ## Step 7: Open Questions List anything that is unclear and needs a decision before work begins: @@ -147,8 +131,6 @@ List anything that is unclear and needs a decision before work begins: - [ ] [Question] — Owner: [who decides] — Deadline: [when needed] ``` -______________________________________________________________________ - ## Output: requirements.md Write all findings to `docs/product/requirements.md`: @@ -183,5 +165,3 @@ Write all findings to `docs/product/requirements.md`: ``` After writing, summarize what was decided so the architect role can start. - -______________________________________________________________________ diff --git a/src/vstack/_templates/skills/secret-scan/config.yaml b/src/vstack/_templates/skills/secret-scan/config.yaml new file mode 100644 index 0000000..6c70031 --- /dev/null +++ b/src/vstack/_templates/skills/secret-scan/config.yaml @@ -0,0 +1,17 @@ +name: secret-scan +version: 20260502028 +description: | + Configure and manage GitHub secret scanning and push protection. Covers enabling + secret scanning, push protection, custom patterns, alert triage, and remediation + of exposed credentials. Use when asked to "set up secret scanning", "configure + push protection", "define custom secret patterns", "triage a secret alert", or + "fix a leaked credential". +argument-hint: '[scope: enable | configure push-protection | custom-pattern | triage alerts | remediate]' + +license: MIT +compatibility: Requires repository access and GitHub Advanced Security (private repos) or public repository. Alert management requires gh CLI authentication. +metadata: + owner: vstack + maturity: stable +user-invocable: true +disable-model-invocation: false diff --git a/src/vstack/_templates/skills/secret-scan/template.md b/src/vstack/_templates/skills/secret-scan/template.md new file mode 100644 index 0000000..7ba95c1 --- /dev/null +++ b/src/vstack/_templates/skills/secret-scan/template.md @@ -0,0 +1,207 @@ +{{SKILL_CONTEXT}} + +# secret-scan — GitHub Secret Scanning & Push Protection + +Configure secret scanning and push protection to prevent credential exposure. + +**Golden rule: Rotate first, investigate second.** A leaked credential is +compromised the moment it enters the repository. Rotation is non-negotiable — +then determine scope and remove from history. + +## Out of scope + +- CodeQL code scanning (use `codeql`) +- Dependency vulnerability scanning (use `dependabot` or `dependency`) +- General security audit (use `security`) + +## Availability + +| Repository type | Availability | +| ---------------------------- | --------------------------------------------------- | +| Public repos | Automatic, free | +| Private/internal (org-owned) | Requires GitHub Secret Protection (Team/Enterprise) | + +## Step 1: Enable Secret Scanning + +Navigate to repository **Settings → Advanced Security → Secret Protection → Enable**. + +For organizations, configure at scale via **Settings → Advanced Security → Security configurations**. + +Also enable: + +- **Push protection** — blocks secrets before they reach the repository +- **Non-provider patterns** — detects private keys, connection strings, generic API keys +- **AI detection** — Copilot-assisted detection of unstructured secrets (passwords) +- **Validity checks** — verifies if detected secrets are still active + +## Step 2: Configure Path Exclusions + +Create `.github/secret_scanning.yml` to auto-close alerts for known-safe paths: + +```yaml +paths-ignore: + - "docs/examples/**" # Example/demo credentials + - "test/fixtures/**" # Test fixture files + - "**/*.example" # Template files with placeholder values +``` + +**Limits:** 1,000 entries maximum, file under 1 MB. + +**Best practices:** + +- Be as specific as possible — broad exclusions create blind spots +- Add comments explaining why each path is excluded +- Review exclusions periodically; remove stale entries +- Excluded paths also skip push protection checks + +## Step 3: Scan for Existing Secrets Locally + +Before enabling, scan the existing codebase: + +```bash +# Scan for common secret patterns +grep -r -E \ + '(password|secret|api_key|private_key|token|access_key|client_secret)\s*[=:]\s*["\x27][^"\x27]{8,}' \ + --include='*.py' --include='*.ts' --include='*.js' --include='*.go' \ + --include='*.yaml' --include='*.env' --include='*.json' \ + --exclude-dir=node_modules --exclude-dir=.venv --exclude-dir=vendor \ + --exclude-dir=.git --exclude-dir=dist --exclude-dir=build \ + . 2>/dev/null | grep -v test | grep -v example | head -30 + +# Check git history for secrets (high-value branches) +git log --all --oneline | head -20 +``` + +## Step 4: Triage Alerts + +```bash +# List open secret scanning alerts via gh CLI +gh api "repos/$(gh repo view --json nameWithOwner --jq '.nameWithOwner')/secret-scanning/alerts" \ + --jq '.[] | {number, state, secret_type, created_at, html_url}' +``` + +**Alert types:** + +| Type | Description | +| ----------------------------- | ------------------------------------------------------ | +| Provider alerts | Detected by GitHub's partner program (high confidence) | +| Non-provider / generic alerts | Private keys, connection strings, generic patterns | +| Push protection alerts | Secrets pushed via a bypass | + +**Alert validity status:** + +- `active` — credential is confirmed live → **rotate immediately** +- `inactive` — credential is confirmed revoked +- `unknown` — validity could not be determined + +## Step 5: Remediate an Exposed Secret + +### Step A: Rotate the credential (do this first) + +1. Log in to the service where the credential was issued +1. Revoke the exposed credential +1. Issue a new credential +1. Update all places that use the old credential (environment variables, secret stores, `.env` files, CI/CD secrets) + +### Step B: Remove from latest commit (if recent) + +```bash +# Edit the file to remove the secret, then: +git add <file> +git commit --amend +git push --force-with-lease +``` + +### Step C: Remove from history (if in earlier commits) + +```bash +# Find the earliest commit containing the secret +git log --all -S "<partial-secret-value>" --oneline + +# Remove via interactive rebase +git rebase -i <COMMIT-SHA>~1 +# Change 'pick' to 'edit' for the offending commit +# Remove the secret from the file, then: +git add <file> +git commit --amend +git rebase --continue +git push --force-with-lease +``` + +> Force-pushing rewrites history — coordinate with the team and merge any +> open PRs first to avoid losing work. + +### Step D: Dismiss the alert + +After rotation and removal, dismiss with the appropriate reason: + +- **Revoked** — credential has been rotated +- **False positive** — detected string is not a real secret +- **Used in tests** — secret appears only in test code with no real access + +## Step 6: Resolve a Blocked Push + +When push protection blocks a push, you will see a URL in the error: + +### Option A: Remove the secret and retry (preferred) + +```bash +# Edit the file to remove the secret +git add <file> +git commit --amend +git push +``` + +### Option B: Bypass (only for confirmed false positives or test data) + +1. Visit the URL from the push error message (same user session) +1. Select a reason: "It's a false positive" or "It's used in tests" +1. Click "Allow me to push this secret" — bypass window is 3 hours +1. Re-push the commits + +### Option C: Request bypass (if delegated bypass is configured) + +1. Visit the URL from the error +1. Add a comment explaining why the secret is safe +1. Submit the request — wait for approval notification + +## Step 7: Custom Secret Patterns + +Define organization-specific patterns when built-in patterns don't cover internal +credential formats. + +**Via GitHub UI:** + +1. Settings → Advanced Security → Custom patterns → New pattern +1. Enter pattern name and regex +1. Add a sample test string +1. Click "Save and dry run" — review results for false positives (up to 1,000) +1. Click "Publish pattern" +1. Optionally enable push protection for the pattern + +**Regex guidelines:** + +- Anchor to known prefixes/suffixes where possible: `myapp_[a-zA-Z0-9]{32}` +- Test against real examples and known non-secret strings +- Avoid overly broad patterns (high false-positive rate reduces signal-to-noise) +- Scopes: repository, organization, or enterprise level + +## Review checklist + +- [ ] Secret scanning enabled on all repositories (or via org security configuration) +- [ ] Push protection enabled +- [ ] `.github/secret_scanning.yml` excludes only known-safe paths with comments +- [ ] All `active` alerts rotated and dismissed +- [ ] Git history cleaned if secret was committed (and pushed) +- [ ] All dependent services updated with new credentials +- [ ] Non-provider pattern scanning enabled for internal credential formats +- [ ] Custom patterns defined for any organization-specific credential formats +- [ ] Secrets stored in environment variables or a secret store — never in source code + +## References + +> Always use the official documentation for the exact version in use — supported secret patterns and push protection rules are updated regularly. + +- [GitHub secret scanning documentation](https://docs.github.com/en/code-security/secret-scanning/introduction/about-secret-scanning) +- [Push protection](https://docs.github.com/en/code-security/secret-scanning/protecting-pushes-with-secret-scanning) +- [Supported secret patterns](https://docs.github.com/en/code-security/secret-scanning/introduction/supported-secret-scanning-patterns) diff --git a/src/vstack/_templates/skills/security/config.yaml b/src/vstack/_templates/skills/security/config.yaml index ff63460..0e141b6 100644 --- a/src/vstack/_templates/skills/security/config.yaml +++ b/src/vstack/_templates/skills/security/config.yaml @@ -1,5 +1,5 @@ name: security -version: 1.0.2 +version: 20260421025 description: | OWASP Top 10 + STRIDE security audit for APIs, services, and libraries. Finds authentication bypasses, injection vulnerabilities, insecure configurations, diff --git a/src/vstack/_templates/skills/security/template.md b/src/vstack/_templates/skills/security/template.md index 7ece3ea..8306e21 100644 --- a/src/vstack/_templates/skills/security/template.md +++ b/src/vstack/_templates/skills/security/template.md @@ -36,8 +36,6 @@ CURRENT=$(git branch --show-current) git diff <base> --stat 2>/dev/null | head -20 || true ``` -______________________________________________________________________ - ## Part 1: OWASP Top 10 ### A01: Broken Access Control @@ -51,7 +49,7 @@ grep -r -n "is_admin\|hasRole\|checkPermission\|authorize\|can(" \ # Look for endpoints missing auth grep -r -n "@app.route\|router\.\|@Get\|@Post\|@Put\|@Delete\|@Patch" \ --include='*.ts' --include='*.py' --include='*.go' \ - --exclude-dir=node_modules --exclude-dir=.venv --exclude-dir=venv --exclude-dir=env --exclude-dir=__pycache__ --exclude-dir=dist --exclude-dir=build . 2>/dev/null | head -30 + --exclude-dir=node_modules --exclude-dir=.venv --exclude-dir=venv --exclude-dir=env --exclude-dir=__pycache__ --exclude-dir=dist --exclude-dir=build --exclude-dir=vendor . 2>/dev/null | head -30 ``` Check: @@ -68,12 +66,12 @@ Check: # Find hardcoded secrets grep -r -E '(password|secret|api_key|private_key|token)\s*[=:]\s*["\x27][^"\x27]{8,}' \ --include='*.ts' --include='*.py' --include='*.go' --include='*.yaml' --include='*.env' \ - --exclude-dir=node_modules --exclude-dir=.venv --exclude-dir=venv --exclude-dir=env --exclude-dir=__pycache__ --exclude-dir=dist --exclude-dir=build --exclude-dir=.git . 2>/dev/null | grep -v test | grep -v example + --exclude-dir=node_modules --exclude-dir=.venv --exclude-dir=venv --exclude-dir=env --exclude-dir=__pycache__ --exclude-dir=dist --exclude-dir=build --exclude-dir=vendor --exclude-dir=.git . 2>/dev/null | grep -v test | grep -v example # Find weak crypto grep -r -n "MD5\|SHA1\|DES\|RC4\|Math.random\|random.random" \ --include='*.ts' --include='*.py' --include='*.go' \ - --exclude-dir=node_modules --exclude-dir=.venv --exclude-dir=venv --exclude-dir=env --exclude-dir=__pycache__ --exclude-dir=dist --exclude-dir=build . 2>/dev/null | head -20 + --exclude-dir=node_modules --exclude-dir=.venv --exclude-dir=venv --exclude-dir=env --exclude-dir=__pycache__ --exclude-dir=dist --exclude-dir=build --exclude-dir=vendor . 2>/dev/null | head -20 ``` Check: @@ -90,12 +88,12 @@ Check: # SQL injection risk grep -r -n 'query\|execute\|raw\|f"' \ --include='*.py' --include='*.ts' --include='*.go' \ - --exclude-dir=node_modules --exclude-dir=.venv --exclude-dir=venv --exclude-dir=env --exclude-dir=__pycache__ --exclude-dir=dist --exclude-dir=build . 2>/dev/null | grep -E '"SELECT|"INSERT|"UPDATE|"DELETE|f".*sql' | head -20 + --exclude-dir=node_modules --exclude-dir=.venv --exclude-dir=venv --exclude-dir=env --exclude-dir=__pycache__ --exclude-dir=dist --exclude-dir=build --exclude-dir=vendor . 2>/dev/null | grep -E '"SELECT|"INSERT|"UPDATE|"DELETE|f".*sql' | head -20 # Command injection risk grep -r -n 'exec\|subprocess\|shell=True\|execSync\|spawnSync' \ --include='*.py' --include='*.ts' --include='*.go' \ - --exclude-dir=node_modules --exclude-dir=.venv --exclude-dir=venv --exclude-dir=env --exclude-dir=__pycache__ --exclude-dir=dist --exclude-dir=build . 2>/dev/null | head -20 + --exclude-dir=node_modules --exclude-dir=.venv --exclude-dir=venv --exclude-dir=env --exclude-dir=__pycache__ --exclude-dir=dist --exclude-dir=build --exclude-dir=vendor . 2>/dev/null | head -20 ``` Check: @@ -118,12 +116,12 @@ Check: # Check for debug/development modes grep -r -n 'DEBUG\s*=\s*True\|debug:\s*true\|development\|NODE_ENV' \ --include='*.py' --include='*.ts' --include='*.yaml' --include='*.json' \ - --exclude-dir=node_modules --exclude-dir=.venv --exclude-dir=venv --exclude-dir=env --exclude-dir=__pycache__ --exclude-dir=dist --exclude-dir=build . 2>/dev/null | grep -v test | head -20 + --exclude-dir=node_modules --exclude-dir=.venv --exclude-dir=venv --exclude-dir=env --exclude-dir=__pycache__ --exclude-dir=dist --exclude-dir=build --exclude-dir=vendor . 2>/dev/null | grep -v test | head -20 # Check for permissive CORS grep -r -n 'cors\|CORS\|Access-Control-Allow-Origin' \ --include='*.ts' --include='*.py' --include='*.go' \ - --exclude-dir=node_modules --exclude-dir=.venv --exclude-dir=venv --exclude-dir=env --exclude-dir=__pycache__ --exclude-dir=dist --exclude-dir=build . 2>/dev/null | head -20 + --exclude-dir=node_modules --exclude-dir=.venv --exclude-dir=venv --exclude-dir=env --exclude-dir=__pycache__ --exclude-dir=dist --exclude-dir=build --exclude-dir=vendor . 2>/dev/null | head -20 ``` Check: @@ -151,7 +149,7 @@ Check: # Check session/token implementation grep -r -n 'jwt\|JWT\|session\|cookie\|token' \ --include='*.ts' --include='*.py' --include='*.go' \ - --exclude-dir=node_modules --exclude-dir=.venv --exclude-dir=venv --exclude-dir=env --exclude-dir=__pycache__ --exclude-dir=dist --exclude-dir=build . 2>/dev/null | grep -i 'expire\|expiry\|secret\|key' | head -20 + --exclude-dir=node_modules --exclude-dir=.venv --exclude-dir=venv --exclude-dir=env --exclude-dir=__pycache__ --exclude-dir=dist --exclude-dir=build --exclude-dir=vendor . 2>/dev/null | grep -i 'expire\|expiry\|secret\|key' | head -20 ``` Check: @@ -180,7 +178,7 @@ Check: ```bash grep -r -n 'audit\|security_log\|auth.*log\|access.*log' \ --include='*.ts' --include='*.py' --include='*.go' \ - --exclude-dir=node_modules --exclude-dir=.venv --exclude-dir=venv --exclude-dir=env --exclude-dir=__pycache__ --exclude-dir=dist --exclude-dir=build . 2>/dev/null | head -20 + --exclude-dir=node_modules --exclude-dir=.venv --exclude-dir=venv --exclude-dir=env --exclude-dir=__pycache__ --exclude-dir=dist --exclude-dir=build --exclude-dir=vendor . 2>/dev/null | head -20 ``` Check: @@ -196,7 +194,7 @@ Check: ```bash grep -r -n 'fetch\|requests\.\|http\.get\|axios\|urllib' \ --include='*.ts' --include='*.py' --include='*.go' \ - --exclude-dir=node_modules --exclude-dir=.venv --exclude-dir=venv --exclude-dir=env --exclude-dir=__pycache__ --exclude-dir=dist --exclude-dir=build . 2>/dev/null | grep -v test | head -20 + --exclude-dir=node_modules --exclude-dir=.venv --exclude-dir=venv --exclude-dir=env --exclude-dir=__pycache__ --exclude-dir=dist --exclude-dir=build --exclude-dir=vendor . 2>/dev/null | grep -v test | head -20 ``` Check: @@ -205,8 +203,6 @@ Check: - [ ] Private network ranges blocked (169.254.0.0/16, 10.0.0.0/8, etc.) - [ ] SSRF protection on any URL-fetching functionality -______________________________________________________________________ - ## Part 2: STRIDE Threat Model For each new service/component, answer: @@ -220,8 +216,6 @@ For each new service/component, answer: | **Denial of Service** | Can the service be made unavailable? Rate limiting? | | | **Elevation of Privilege** | Can a user gain admin access through normal flows? | | -______________________________________________________________________ - ## Audit Report ```text @@ -253,4 +247,10 @@ Scope: [full/diff/dependency/config] [SHIP-READY / FIX CRITICALS / SECURITY REVIEW REQUIRED] ``` -______________________________________________________________________ +## References + +> OWASP Top 10 and STRIDE are living documents — always refer to the current edition. + +- [OWASP Top 10](https://owasp.org/www-project-top-ten/) +- [OWASP API Security Top 10](https://owasp.org/www-project-api-security/) +- [STRIDE threat modeling (Microsoft)](https://learn.microsoft.com/en-us/azure/security/develop/threat-modeling-tool-threats) diff --git a/src/vstack/_templates/skills/terraform/config.yaml b/src/vstack/_templates/skills/terraform/config.yaml new file mode 100644 index 0000000..61aa9d9 --- /dev/null +++ b/src/vstack/_templates/skills/terraform/config.yaml @@ -0,0 +1,18 @@ +name: terraform +version: 20260502030 +description: | + Write, review, and refactor Terraform infrastructure-as-code. Covers resource + design, module structure, state management, variable and output conventions, + provider pinning, remote backends, workspace strategy, drift detection, and + security hardening. Use when asked to "write Terraform", "review this Terraform", + "refactor IaC", "add a Terraform module", "plan state migration", or + "harden Terraform configuration". +argument-hint: '[provider: aws | azure | gcp | generic, and scope: new resource | module | state migration | security review]' + +license: MIT +compatibility: Requires a skills-compatible agent with repository file access. Requires Terraform CLI installed for plan/apply operations. +metadata: + owner: vstack + maturity: stable +user-invocable: true +disable-model-invocation: false diff --git a/src/vstack/_templates/skills/terraform/template.md b/src/vstack/_templates/skills/terraform/template.md new file mode 100644 index 0000000..075d498 --- /dev/null +++ b/src/vstack/_templates/skills/terraform/template.md @@ -0,0 +1,302 @@ +{{SKILL_CONTEXT}} + +# terraform — Infrastructure as Code with Terraform + +Write, review, and refactor Terraform configurations for any provider. + +## Out of scope + +- Terragrunt DRY wrappers (use `terragrunt`) +- AWS-specific CLI workflows (use `aws-cli`) +- CloudFormation templates (use `cloudformation`) + +## Step 0: Detect Context + +```bash +terraform version 2>/dev/null || echo "terraform not installed" + +# Find all Terraform roots +find . -name "*.tf" -not -path "*/.terraform/*" | sed 's|/[^/]*\.tf$||' | sort -u + +# Check backend and provider constraints +grep -rl "backend" . --include="*.tf" 2>/dev/null +grep -A5 'required_providers' -r . --include="*.tf" 2>/dev/null | head -20 +``` + +## Step 1: Repository Structure + +### Single service + +``` +infra/ +├── main.tf ← root module: resource definitions +├── variables.tf ← input variables with types and defaults +├── outputs.tf ← outputs consumed by other modules or CI +├── providers.tf ← provider configuration and version constraints +├── versions.tf ← terraform {} block with required_version +├── locals.tf ← computed values and name construction +└── modules/ + └── <name>/ ← reusable submodule + ├── main.tf + ├── variables.tf + └── outputs.tf +``` + +### Monorepo / multi-environment + +``` +infra/ +├── modules/ ← shared reusable modules +│ └── <name>/ +├── environments/ +│ ├── dev/ +│ │ ├── main.tf +│ │ └── terraform.tfvars +│ ├── staging/ +│ └── prod/ +``` + +## Step 2: Provider and Version Pinning + +Always pin provider versions and the Terraform binary. Never use unbounded ranges in production. + +```hcl +# versions.tf +terraform { + required_version = "~> 1.9" + + required_providers { + aws = { + source = "hashicorp/aws" + version = "~> 5.0" + } + } +} +``` + +**Version constraint operators:** + +- `~> 1.9` — allows patch and minor updates within 1.x (recommended) +- `>= 1.9, < 2.0` — explicit range +- `= 1.9.2` — exact pin (lockfile preferred over this) + +Always commit `.terraform.lock.hcl` to source control. + +## Step 3: Remote Backend + +Never use local state in production. Configure a remote backend with state locking. + +```hcl +# AWS S3 + DynamoDB locking +terraform { + backend "s3" { + bucket = "myorg-terraform-state" + key = "services/myservice/terraform.tfstate" + region = "eu-west-1" + encrypt = true + dynamodb_table = "terraform-state-lock" + } +} +``` + +**State bucket requirements:** + +- Enable versioning on the S3 bucket (enables rollback) +- Enable server-side encryption (SSE-S3 minimum, SSE-KMS preferred) +- Block all public access +- Restrict bucket policy to Terraform IAM role + approved team roles + +## Step 4: Variables and Outputs + +```hcl +# variables.tf — always include type, description, and sensible defaults +variable "environment" { + type = string + description = "Deployment environment: dev | staging | prod" + validation { + condition = contains(["dev", "staging", "prod"], var.environment) + error_message = "environment must be dev, staging, or prod." + } +} + +variable "db_password" { + type = string + description = "Database master password — supply via TF_VAR_db_password or tfvars." + sensitive = true +} +``` + +```hcl +# outputs.tf — mark sensitive outputs accordingly +output "api_endpoint" { + description = "Base URL of the deployed API." + value = aws_lb.main.dns_name +} + +output "db_connection_string" { + description = "Database connection string." + value = "postgres://${aws_db_instance.main.endpoint}/${var.db_name}" + sensitive = true +} +``` + +**Rules:** + +- Mark all secrets as `sensitive = true` — prevents them appearing in plan output and logs +- Never hardcode secrets in `.tf` files or `.tfvars` committed to source control +- Use `TF_VAR_*` env vars or a secrets manager data source for secrets + +## Step 5: Naming and Tagging + +```hcl +# locals.tf — centralize name construction +locals { + name_prefix = "${var.project}-${var.environment}" + + common_tags = { + Project = var.project + Environment = var.environment + ManagedBy = "terraform" + Owner = var.team + } +} + +resource "aws_s3_bucket" "uploads" { + bucket = "${local.name_prefix}-uploads" + tags = local.common_tags +} +``` + +## Step 6: Module Design + +```hcl +# Good: module exposes what callers need +module "rds" { + source = "./modules/rds" + + name = "${local.name_prefix}-db" + subnet_ids = module.vpc.private_subnet_ids + vpc_id = module.vpc.vpc_id + environment = var.environment +} +``` + +**Module rules:** + +- One purpose per module — avoid "kitchen sink" modules +- Accept subnet IDs and VPC IDs as inputs rather than looking them up inside the module (reduces coupling) +- Expose only what callers need as outputs +- Pin module versions when sourcing from a registry: `version = "~> 3.0"` + +## Step 7: Security Hardening + +```bash +# Run tfsec for security misconfigurations +tfsec . --minimum-severity HIGH + +# Run checkov for CIS benchmark checks +checkov -d . --framework terraform --compact --quiet + +# Run trivy for misconfigurations +trivy config . --severity HIGH,CRITICAL +``` + +**Common misconfigurations to check:** + +- S3 buckets: `block_public_acls = true`, `block_public_policy = true`, encryption enabled +- RDS: `storage_encrypted = true`, `deletion_protection = true`, no public access +- Security groups: no `0.0.0.0/0` on SSH/RDP; restrict to known CIDR ranges +- IAM: least-privilege policies; no `*` actions on `*` resources +- KMS: key rotation enabled (`enable_key_rotation = true`) +- VPC: flow logs enabled; no internet gateway on private subnets + +## Step 8: Plan and Apply Workflow + +```bash +# Initialize (after adding/changing providers or backends) +terraform init + +# Format check (enforce in CI) +terraform fmt -check -recursive + +# Validate syntax and references +terraform validate + +# Plan — always review before applying +terraform plan -out=tfplan + +# Apply from saved plan (ensures what was reviewed is what runs) +terraform apply tfplan + +# Targeted apply (use sparingly — prefer full applies) +terraform apply -target=aws_s3_bucket.uploads + +# Destroy (requires explicit confirmation — destructive) +terraform destroy -target=aws_s3_bucket.uploads +``` + +## Step 9: Drift Detection + +```bash +# Detect drift between state and real infrastructure +terraform plan -detailed-exitcode +# Exit code 0: no changes; 1: error; 2: changes present + +# Refresh state to pick up out-of-band changes (read-only) +terraform refresh +``` + +Set up drift detection in CI: + +```yaml +- name: Terraform plan (drift check) + run: terraform plan -detailed-exitcode -no-color + continue-on-error: false # fail CI on drift +``` + +## Step 10: State Operations (high risk) + +Always back up state before state manipulations. + +```bash +# List state resources +terraform state list + +# Show a specific resource +terraform state show aws_s3_bucket.uploads + +# Move resource to new address (after refactor) +terraform state mv aws_s3_bucket.uploads aws_s3_bucket.media + +# Import existing resource into state +terraform import aws_s3_bucket.uploads my-existing-bucket-name + +# Remove resource from state without destroying it +terraform state rm aws_s3_bucket.old_name +``` + +Run `terraform plan` after every state operation to verify the outcome. + +## Review Checklist + +- [ ] `required_version` and all providers pinned with `~>` constraints +- [ ] `.terraform.lock.hcl` committed to source control +- [ ] Remote backend configured with encryption and state locking +- [ ] No secrets hardcoded in `.tf` files; sensitive variables marked `sensitive = true` +- [ ] All resources tagged via `locals.common_tags` +- [ ] S3 buckets: public access blocked, encryption enabled +- [ ] RDS: `storage_encrypted`, `deletion_protection`, no public access +- [ ] Security groups: no `0.0.0.0/0` on management ports +- [ ] IAM policies: least privilege, no `*:*` wildcards +- [ ] `tfsec` or `checkov` passes with no HIGH/CRITICAL findings +- [ ] `terraform fmt -check` passes in CI +- [ ] `terraform validate` passes in CI + +## References + +> Always use the official documentation for the provider and Terraform version in use — resource schema, argument names, and defaults change between provider releases. + +- [Terraform documentation](https://developer.hashicorp.com/terraform/docs) +- [Terraform provider registry](https://registry.terraform.io/) +- [AWS provider documentation](https://registry.terraform.io/providers/hashicorp/aws/latest/docs) +- [tfsec rules](https://aquasecurity.github.io/tfsec/latest/checks/aws/) · [checkov checks](https://www.checkov.io/5.Policy%20Index/terraform.html) diff --git a/src/vstack/_templates/skills/terragrunt/config.yaml b/src/vstack/_templates/skills/terragrunt/config.yaml new file mode 100644 index 0000000..f0f0247 --- /dev/null +++ b/src/vstack/_templates/skills/terragrunt/config.yaml @@ -0,0 +1,18 @@ +name: terragrunt +version: 20260502031 +description: | + Write, review, and refactor Terragrunt configurations for DRY multi-environment + infrastructure. Covers root and unit-level HCL structure, generate blocks, + remote state inheritance, dependency blocks, inputs, mock outputs, and + run-all workflows. Use when asked to "write Terragrunt", "set up Terragrunt", + "DRY Terraform across environments", "configure Terragrunt dependencies", + or "migrate from plain Terraform to Terragrunt". +argument-hint: '[scope: new layout | dependency graph | state migration | run-all workflow | security review]' + +license: MIT +compatibility: Requires a skills-compatible agent with repository file access. Requires Terraform CLI and Terragrunt installed for plan/apply operations. +metadata: + owner: vstack + maturity: stable +user-invocable: true +disable-model-invocation: false diff --git a/src/vstack/_templates/skills/terragrunt/template.md b/src/vstack/_templates/skills/terragrunt/template.md new file mode 100644 index 0000000..f65a92c --- /dev/null +++ b/src/vstack/_templates/skills/terragrunt/template.md @@ -0,0 +1,274 @@ +{{SKILL_CONTEXT}} + +# terragrunt — DRY Terraform with Terragrunt + +Write and review Terragrunt configurations to eliminate repetition across +environments, accounts, and regions. + +## Out of scope + +- Terraform module authoring (use `terraform`) +- AWS CLI operations (use `aws-cli`) +- CloudFormation templates (use `cloudformation`) + +## Step 0: Detect Context + +```bash +# Check Terragrunt version +terragrunt --version 2>/dev/null || echo "terragrunt not installed" +terraform version 2>/dev/null || echo "terraform not installed" + +# Find all Terragrunt roots +find . -name "terragrunt.hcl" -not -path "*/.terragrunt-cache/*" | sort + +# Check if there is a root terragrunt.hcl +ls terragrunt.hcl root.hcl 2>/dev/null || echo "No root HCL found" +``` + +## Step 1: Repository Structure + +Terragrunt works best with a strict directory hierarchy that maps to your +deployment topology. + +``` +infra/ +├── terragrunt.hcl ← root config: remote state, provider generate block +├── _envcommon/ ← shared inputs across environments +│ ├── vpc.hcl +│ └── rds.hcl +├── dev/ +│ ├── account.hcl ← account-level inputs (account_id, region) +│ ├── vpc/ +│ │ └── terragrunt.hcl +│ ├── rds/ +│ │ └── terragrunt.hcl +│ └── app/ +│ └── terragrunt.hcl +├── staging/ +│ └── ... +└── prod/ + └── ... +``` + +Each leaf `terragrunt.hcl` is a **unit** — one Terraform module invocation. +Parent `terragrunt.hcl` files contain shared configuration inherited by all +descendants. + +## Step 2: Root Configuration + +```hcl +# infra/terragrunt.hcl — inherited by all units +locals { + account_vars = read_terragrunt_config(find_in_parent_folders("account.hcl")) + region = local.account_vars.locals.region + account_id = local.account_vars.locals.account_id + project = "myapp" +} + +# Remote state — one state file per unit, auto-named from path +remote_state { + backend = "s3" + config = { + bucket = "${local.project}-terraform-state-${local.account_id}" + key = "${path_relative_to_include()}/terraform.tfstate" + region = local.region + encrypt = true + dynamodb_table = "terraform-state-lock" + } + generate = { + path = "backend.tf" + if_exists = "overwrite_terragrunt" + } +} + +# Inject provider block into every unit +generate "provider" { + path = "provider.tf" + if_exists = "overwrite_terragrunt" + contents = <<-EOF + provider "aws" { + region = "${local.region}" + + default_tags { + tags = { + Project = "${local.project}" + ManagedBy = "terragrunt" + } + } + } + EOF +} +``` + +## Step 3: Account-Level Config + +```hcl +# infra/dev/account.hcl +locals { + account_id = "123456789012" + region = "eu-west-1" + env = "dev" +} +``` + +## Step 4: Unit Configuration (leaf) + +```hcl +# infra/dev/rds/terragrunt.hcl +include "root" { + path = find_in_parent_folders() + expose = true +} + +# Pull in shared inputs from _envcommon +locals { + common = read_terragrunt_config(find_in_parent_folders("_envcommon/rds.hcl")) + env = include.root.locals.account_vars.locals.env +} + +terraform { + source = "git::https://github.com/myorg/terraform-modules.git//modules/rds?ref=v2.1.0" +} + +inputs = merge( + local.common.inputs, + { + environment = local.env + db_name = "myapp_${local.env}" + } +) +``` + +## Step 5: Dependency Blocks + +```hcl +# infra/dev/app/terragrunt.hcl +include "root" { + path = find_in_parent_folders() +} + +terraform { + source = "../../../modules/app" +} + +dependency "vpc" { + config_path = "../vpc" + + # Mock outputs for plan without deploying dependencies first + mock_outputs = { + vpc_id = "vpc-00000000" + private_subnet_ids = ["subnet-00000001", "subnet-00000002"] + } + mock_outputs_allowed_terraform_commands = ["validate", "plan"] +} + +dependency "rds" { + config_path = "../rds" + + mock_outputs = { + db_endpoint = "mock-db.example.com" + db_port = 5432 + } + mock_outputs_allowed_terraform_commands = ["validate", "plan"] +} + +inputs = { + vpc_id = dependency.vpc.outputs.vpc_id + subnet_ids = dependency.vpc.outputs.private_subnet_ids + db_endpoint = dependency.rds.outputs.db_endpoint +} +``` + +## Step 6: run-all Workflow + +```bash +# Plan entire environment (respects dependency order) +terragrunt run-all plan --terragrunt-working-dir infra/dev + +# Apply entire environment +terragrunt run-all apply --terragrunt-working-dir infra/dev + +# Apply only specific units (exclude by dir pattern) +terragrunt run-all apply \ + --terragrunt-working-dir infra/dev \ + --terragrunt-exclude-dir infra/dev/rds + +# Plan a single unit +cd infra/dev/app && terragrunt plan + +# Destroy (destructive — requires explicit confirmation) +terragrunt run-all destroy --terragrunt-working-dir infra/dev +``` + +`run-all` automatically determines dependency order from `dependency` blocks +and parallelizes independent units. + +## Step 7: DRY with \_envcommon + +Share defaults across environments without duplication: + +```hcl +# infra/_envcommon/rds.hcl +inputs = { + instance_class = "db.t3.medium" + allocated_storage = 20 + storage_encrypted = true + deletion_protection = true +} +``` + +Override per environment using `merge`: + +```hcl +locals { + common = read_terragrunt_config(find_in_parent_folders("_envcommon/rds.hcl")) +} + +inputs = merge(local.common.inputs, { + instance_class = "db.t3.large" # prod override +}) +``` + +## Step 8: CI/CD Integration + +```yaml +# .github/workflows/infra.yml (simplified) +- name: Terragrunt plan + run: | + cd infra/${{ env.ENV }} + terragrunt run-all plan \ + --terragrunt-non-interactive \ + --terragrunt-parallelism 4 \ + -no-color 2>&1 | tee plan.log + +- name: Terragrunt apply + if: github.ref == 'refs/heads/main' + run: | + cd infra/${{ env.ENV }} + terragrunt run-all apply \ + --terragrunt-non-interactive \ + --auto-approve \ + -no-color +``` + +Use `--terragrunt-non-interactive` in CI to prevent hanging on prompts. + +## Review Checklist + +- [ ] Root `terragrunt.hcl` generates `backend.tf` and `provider.tf` — no hand-written copies in units +- [ ] State key uses `path_relative_to_include()` for automatic per-unit naming +- [ ] S3 state bucket: encryption enabled, versioning enabled, public access blocked +- [ ] Module sources pinned to a specific git ref or semver tag — never `?ref=main` +- [ ] `dependency` blocks have `mock_outputs` for `plan` and `validate` +- [ ] Shared inputs extracted to `_envcommon/` — no copy-paste across environments +- [ ] Secrets supplied via environment variables or a secrets manager data source +- [ ] `--terragrunt-non-interactive` used in all CI/CD invocations +- [ ] `.terragrunt-cache/` in `.gitignore` + +## References + +> Always use the official documentation for the Terragrunt version in use — built-in functions, flags, and configuration options evolve with each release. + +- [Terragrunt documentation](https://terragrunt.gruntwork.io/docs/) +- [Terragrunt CLI reference](https://terragrunt.gruntwork.io/docs/reference/cli-options/) +- [Gruntwork module registry](https://www.gruntwork.io/) diff --git a/src/vstack/_templates/skills/threat-model/config.yaml b/src/vstack/_templates/skills/threat-model/config.yaml new file mode 100644 index 0000000..6d96e7d --- /dev/null +++ b/src/vstack/_templates/skills/threat-model/config.yaml @@ -0,0 +1,17 @@ +name: threat-model +version: 20260502021 +description: | + Threat modeling for APIs, services, and systems using a practical STRIDE-first + approach with optional DREAD prioritization and PASTA depth for high-criticality + contexts. Produces actionable threat scenarios, mitigations, and risk priorities. + Use when asked to "threat model", "analyze attack paths", "STRIDE review", or + "prioritize security design risks". +argument-hint: '[system, component, or architecture to threat model]' + +license: MIT +compatibility: Requires a skills-compatible agent with repository file access and terminal command execution when needed. +metadata: + owner: vstack + maturity: stable +user-invocable: true +disable-model-invocation: false diff --git a/src/vstack/_templates/skills/threat-model/template.md b/src/vstack/_templates/skills/threat-model/template.md new file mode 100644 index 0000000..65e8db5 --- /dev/null +++ b/src/vstack/_templates/skills/threat-model/template.md @@ -0,0 +1,205 @@ +{{SKILL_CONTEXT}} + +{{BASE_BRANCH}} + +# threat-model — Threat Modeling (STRIDE-first, DREAD/PASTA-aware) + +Identify design-time security risks before implementation and turn them into +actionable mitigations. + +This skill uses a practical framework selection model: + +- **STRIDE** for systematic threat identification (default) +- **DREAD** for threat prioritization (optional but recommended) +- **PASTA** depth for high-criticality systems when business-risk alignment is required + +## Out of scope + +- Full OWASP vulnerability audit of existing code (use `security`) +- Fix implementation and patching work (engineering role) +- Incident post-mortem analysis (use `incident`) +- Generic architecture review without threat analysis focus (use `architecture`) + +## Deliverable and artifact policy + +- Primary deliverable: `docs/architecture/threat-model.md` +- Baseline-first default: write final threat model directly to `docs/architecture/threat-model.md` on the feature branch. +- Optional WIP area for complex/uncertain efforts: `docs/delta/{id}/THREAT_MODEL_DELTA.md` +- Before merge: consolidate delta notes into the baseline threat model. + +## Framework selection guide + +Use this decision table to choose depth and method: + +| Need | Preferred framework | +| ------------------------------------------------ | ----------------------------------------- | +| Identify threats quickly during design | STRIDE | +| Rank many discovered threats for remediation | STRIDE + DREAD | +| Model business-aligned risk for critical systems | PASTA (optionally with STRIDE categories) | + +Default path for most teams: **STRIDE + DREAD**. + +## Step 0: Define model scope and trust boundaries + +Document what is in and out of scope: + +```text +System: [service/subsystem/repo scope] +System style: [backend-only|frontend-only|fullstack|platform|integration] +Critical assets: [PII, credentials, payment data, business operations] +Actors: [users, admins, services, third parties] +Trust boundaries:[internet edge, auth boundary, network segment, tenant boundary] +Assumptions: [known constraints] +Out of scope: [explicit exclusions] +``` + +Collect architecture evidence first: + +```bash +find docs -maxdepth 3 -type f \ + \( -name 'architecture.md' -o -name 'design.md' -o -name 'requirements.md' -o -name 'openapi*.yaml' -o -name '*.proto' \) \ + 2>/dev/null | sort +``` + +If there is no architecture or design context, stop and request it before continuing. + +## Step 1: Build a lightweight system model + +Create a concise component and data-flow view before threat enumeration. + +Minimum required model: + +1. External entities (users, services, vendors) +1. Internal components/services +1. Data stores +1. Data flows crossing trust boundaries +1. Identity and authorization boundaries + +Use Mermaid when possible: + +```mermaid +flowchart LR + U[User] --> API[Public API] + API --> SVC[Service] + SVC --> DB[(Database)] + SVC --> EXT[Third-party API] +``` + +## Step 2: Identify threats with STRIDE + +For each component and data flow, enumerate threats by category. + +| STRIDE category | Core question | Typical controls | +| ---------------------- | ------------------------------------------------- | --------------------------------------------- | +| Spoofing | Can an attacker impersonate an identity? | Strong auth, token validation, mTLS | +| Tampering | Can data/state be modified without authorization? | Integrity checks, signatures, immutable logs | +| Repudiation | Could actions be denied without evidence? | Audit trails, non-repudiation logs | +| Information Disclosure | Could sensitive data leak? | Access control, encryption, data minimization | +| Denial of Service | Can availability be degraded or exhausted? | Rate limits, quotas, circuit breakers | +| Elevation of Privilege | Can lower privilege gain higher access? | Least privilege, authorization hardening | + +Threat entry format: + +```text +ID: TM-<component>-<n> +Category: [STRIDE] +Asset: [what is at risk] +Attack path: [how the threat is realized] +Preconditions: [what attacker needs] +Current controls: [what already exists] +Control gaps: [what is missing] +Proposed mitigations: [specific, testable controls] +``` + +## Step 3: Prioritize with DREAD (optional but recommended) + +If you have more than a few threats, score each threat: + +- **Damage** +- **Reproducibility** +- **Exploitability** +- **Affected Users** +- **Discoverability** + +Use a 1-10 scale and compute the average. + +| ID | D | R | E | A | Dv | Score | Priority | +| --------- | --- | --- | --- | --- | --- | ----- | -------- | +| TM-auth-1 | 9 | 8 | 8 | 9 | 7 | 8.2 | P1 | + +Prioritization note: keep scoring criteria explicit and tie final priority to +business and operational context, not score alone. + +## Step 4: Use PASTA depth when context demands it + +Use PASTA selectively when one or more conditions apply: + +- System is mission-critical or highly regulated +- Executive/compliance risk reporting requires business traceability +- Threat model must include attack simulation beyond checklist-level analysis + +PASTA-aligned expansion (compact): + +1. Define business and security objectives. +1. Confirm technical scope and decomposition. +1. Extend threat analysis with vulnerability and attack simulation depth. +1. Translate findings into business-impact risk prioritization. + +If PASTA depth is out of scope due to time or maturity constraints, document that +explicitly and continue with STRIDE + DREAD. + +## Step 5: Produce mitigation plan and security requirements + +Convert prioritized threats into implementation-ready controls: + +1. Preventive controls (before exploitation) +1. Detective controls (signal and alert) +1. Response controls (contain and recover) +1. Verification controls (tests/checks proving control effectiveness) + +For each high-priority threat include: + +- Owner (role/team) +- Expected artifact change (architecture, design, code, tests, runbook) +- Deadline/sprint target +- Verification method (test, scan, review, chaos/failure drill) + +## Threat model report template + +```markdown +# Threat Model — [System] — [Date] + +## Scope and Context +- System and boundaries +- Critical assets +- Assumptions and exclusions + +## Architecture and Data Flow +[diagram + concise narrative] + +## STRIDE Threat Inventory +| ID | Component/Flow | Category | Threat | Current Controls | Gaps | Mitigation | + +## DREAD Prioritization (if used) +| ID | Damage | Reproducibility | Exploitability | Affected Users | Discoverability | Score | Priority | + +## PASTA Expansion (if used) +[business objectives, attack simulation summary, business-impact alignment] + +## Priority Mitigation Plan +| Priority | Threat ID | Control | Owner | Verification | Target | + +## Residual Risk and Decisions +- accepted risks +- escalations needed +- decisions requiring ADR or product sign-off +``` + +## Completion checklist + +- Scope, trust boundaries, and critical assets are explicit. +- STRIDE inventory covers all major components and critical flows. +- DREAD prioritization is included when threat volume requires ranking. +- PASTA depth is either applied with rationale or explicitly deferred. +- Mitigations are actionable, owned, and verifiable. +- Final report is written to `docs/architecture/threat-model.md`. diff --git a/src/vstack/_templates/skills/verify/config.yaml b/src/vstack/_templates/skills/verify/config.yaml index fefb73b..523c4ce 100644 --- a/src/vstack/_templates/skills/verify/config.yaml +++ b/src/vstack/_templates/skills/verify/config.yaml @@ -1,5 +1,5 @@ name: verify -version: 1.0.2 +version: 20260421026 description: | Verification fix-loop skill. Routes by mode (quick/standard/exhaustive), runs targeted checks, fixes findings by severity, and re-verifies impacted paths. diff --git a/src/vstack/_templates/skills/verify/template.md b/src/vstack/_templates/skills/verify/template.md index 311dbc3..3c57192 100644 --- a/src/vstack/_templates/skills/verify/template.md +++ b/src/vstack/_templates/skills/verify/template.md @@ -29,8 +29,6 @@ Use `inspect` for read-only auditing. - Optional WIP area for complex/uncertain efforts: `docs/delta/{id}/VERIFY_DELTA.md` - Before merge: consolidate final findings, severity, and ship-readiness verdict into baseline reports. -______________________________________________________________________ - ## Step 0: Route Mode Classify first, then run one mode. @@ -45,8 +43,6 @@ Classify first, then run one mode. If D, stop and route to `inspect`. -______________________________________________________________________ - ## Step 1: Scope and Safety Parse user scope: @@ -67,8 +63,6 @@ Bootstrap test command: {{RUN_TESTS}} -______________________________________________________________________ - ## Step 2: Baseline Checks (all modes) Run baseline checks for the selected scope. @@ -87,8 +81,6 @@ Run baseline checks for the selected scope. {{RUN_TESTS}} -______________________________________________________________________ - ## Step 3: Conditional Checks by Mode ### quick @@ -136,8 +128,6 @@ For exhaustive mode, require observability evidence (logs/metrics/traces/alerts) If deep security/performance concerns appear, stop and route to `security` or `performance`. -______________________________________________________________________ - ## Step 4: Triage Classify findings: @@ -155,8 +145,6 @@ Fix policy: - standard: critical + high + medium - exhaustive: all severities -______________________________________________________________________ - ## Step 5: Fix and Re-verify Loop For each fixable issue in severity order: @@ -169,8 +157,6 @@ For each fixable issue in severity order: If an issue implies architecture or design mismatch, stop and escalate. -______________________________________________________________________ - ## Step 6: Final Report ```text @@ -197,5 +183,3 @@ scope: [path/component/full] ### Ship Readiness [READY TO SHIP | NEEDS FIXES | BLOCKED] ``` - -______________________________________________________________________ diff --git a/src/vstack/_templates/skills/vision/config.yaml b/src/vstack/_templates/skills/vision/config.yaml index a4f4da4..68fe9d8 100644 --- a/src/vstack/_templates/skills/vision/config.yaml +++ b/src/vstack/_templates/skills/vision/config.yaml @@ -1,5 +1,5 @@ name: vision -version: 1.0.2 +version: 20260421027 description: | CEO/founder-mode plan review. Rethink the problem from first principles, validate ambition and scope, challenge premises, find the 10x solution. Four modes: diff --git a/src/vstack/_templates/skills/vision/template.md b/src/vstack/_templates/skills/vision/template.md index 3e3973b..bbe2af8 100644 --- a/src/vstack/_templates/skills/vision/template.md +++ b/src/vstack/_templates/skills/vision/template.md @@ -165,5 +165,3 @@ For each finding: explain the tradeoff, give an opinionated recommendation, ask - **SCOPE CHANGE NEEDED:** Here's the revised scope I recommend. Present as: "Overall assessment: [READY/NEEDS REVISION/SCOPE CHANGE] because [1-2 sentence reason]." - -______________________________________________________________________ diff --git a/src/vstack/artifacts/config.py b/src/vstack/artifacts/config.py index 3396501..9474c66 100644 --- a/src/vstack/artifacts/config.py +++ b/src/vstack/artifacts/config.py @@ -106,6 +106,6 @@ def __post_init__(self) -> None: [ FieldSpec("name", quoted=False), FieldSpec("description"), - FieldSpec("applyTo", quoted=False), + FieldSpec("applyTo"), ] ) diff --git a/src/vstack/cli/constants.py b/src/vstack/cli/constants.py index df225d8..0d34898 100644 --- a/src/vstack/cli/constants.py +++ b/src/vstack/cli/constants.py @@ -15,12 +15,15 @@ "design", "consult", "concise", + "conventional-commit", "code-review", "release-notes", "pr", + "gh-release", "verify", "inspect", "security", + "threat-model", "debug", "performance", "analyse", @@ -35,6 +38,18 @@ "onboard", "dependency", "incident", + "gh-issues", + "codeql", + "dependabot", + "secret-scan", + "gdpr", + "terraform", + "terragrunt", + "cloudformation", + "aws-cli", + "k8s", + "helm", + "rancher", ] @@ -77,6 +92,27 @@ class ArtifactState: EXPECTED_INPUT_NAMES: dict[str, list[str]] = { "skill": EXPECTED_CANONICAL_NAMES, "agent": ["architect", "designer", "engineer", "product", "release", "tester"], - "instruction": ["git", "python"], - "prompt": ["code-review"], + "instruction": [ + "git", + "java", + "k8s", + "helm", + "markdown", + "python", + "rancher", + "security", + "terraform", + "terragrunt", + "testing", + "typescript", + ], + "prompt": [ + "api-design-review", + "architecture-risk", + "code-review", + "dependency-audit", + "incident-timeline", + "migration-safety", + "release-readiness", + ], } diff --git a/src/vstack/cli/install.py b/src/vstack/cli/install.py index 433a62e..1660e37 100644 --- a/src/vstack/cli/install.py +++ b/src/vstack/cli/install.py @@ -33,10 +33,14 @@ def __init__(self, service: CommandService) -> None: @staticmethod def _version_gt(new: str, existing: str | None) -> bool: - """Return True when *new* semver string is strictly greater than *existing*.""" + """Return ``True`` when *new* template revision is strictly greater than *existing*. + + Supported formats are numeric dot-separated revisions (legacy) and plain + numeric revisions such as ``YYYYMMDDNNN``. + """ def _tuple(v: str) -> tuple[int, ...]: - """Convert a dotted version string to an integer tuple for comparison.""" + """Convert a version-like string to an integer tuple for comparison.""" try: return tuple(int(x) for x in v.split(".")) except (ValueError, AttributeError): diff --git a/tests/vstack/agents/test_role_wiring.py b/tests/vstack/agents/test_role_wiring.py index 4ec0028..34a7b4c 100644 --- a/tests/vstack/agents/test_role_wiring.py +++ b/tests/vstack/agents/test_role_wiring.py @@ -4,6 +4,8 @@ from pathlib import Path +from vstack.frontmatter import FrontmatterParser + TEMPLATES_ROOT = Path(__file__).resolve().parents[3] / "src" / "vstack" / "_templates" / "agents" @@ -55,3 +57,16 @@ def test_all_role_configs_define_handoffs_block() -> None: assert "handoffs:" in config assert "label:" in config assert "agent:" in config + + +def test_all_role_handoff_targets_are_known_roles() -> None: + """Each handoff target should reference one of the known role agents.""" + roles = ["product", "architect", "designer", "engineer", "tester", "release"] + valid_targets = set(roles) + + for role in roles: + config = FrontmatterParser.parse_yaml(_read(f"{role}/config.yaml")) + handoffs = config.get("handoffs") or [] + for handoff in handoffs: + target = handoff.get("agent") + assert target in valid_targets, f"{role} has unknown handoff target: {target!r}" diff --git a/tests/vstack/agents/test_template_structure.py b/tests/vstack/agents/test_template_structure.py new file mode 100644 index 0000000..dcd9b77 --- /dev/null +++ b/tests/vstack/agents/test_template_structure.py @@ -0,0 +1,46 @@ +"""Canonical structure checks for role agent templates.""" + +from __future__ import annotations + +from pathlib import Path + +TEMPLATES_ROOT = Path(__file__).resolve().parents[3] / "src" / "vstack" / "_templates" / "agents" +ROLES = ["product", "architect", "designer", "engineer", "tester", "release"] +REQUIRED_HEADINGS_IN_ORDER = [ + "## identity and purpose", + "## responsibilities", + "## scope and boundaries", + "## limitations and do not do", + "## working principles", + "## decision guidelines", + "## communication style", + "## workflow and handoffs", + "## success criteria", + "## failure and escalation rules", + "## artifacts you own", + "## completion checklist", + "## skills you use", +] + + +def _read(role: str) -> str: + """Read one role template from the source templates directory.""" + return (TEMPLATES_ROOT / role / "template.md").read_text(encoding="utf-8") + + +def _headings(content: str) -> list[str]: + """Return level-2 headings in declaration order.""" + return [line.strip() for line in content.splitlines() if line.startswith("## ")] + + +def test_all_role_templates_follow_canonical_section_order() -> None: + """Each role template should include canonical sections in the required order.""" + for role in ROLES: + headings = _headings(_read(role)) + + positions: list[int] = [] + for heading in REQUIRED_HEADINGS_IN_ORDER: + assert heading in headings, f"{role} missing heading: {heading}" + positions.append(headings.index(heading)) + + assert positions == sorted(positions), f"{role} canonical headings out of order" diff --git a/tests/vstack/cli/test_constants.py b/tests/vstack/cli/test_constants.py index 1b95e48..754f1c2 100644 --- a/tests/vstack/cli/test_constants.py +++ b/tests/vstack/cli/test_constants.py @@ -12,12 +12,15 @@ "design", "consult", "concise", + "conventional-commit", "code-review", "release-notes", "pr", + "gh-release", "verify", "inspect", "security", + "threat-model", "debug", "performance", "analyse", @@ -32,6 +35,18 @@ "onboard", "dependency", "incident", + "gh-issues", + "codeql", + "dependabot", + "secret-scan", + "gdpr", + "terraform", + "terragrunt", + "cloudformation", + "aws-cli", + "k8s", + "helm", + "rancher", ] diff --git a/tests/vstack/cli/test_install.py b/tests/vstack/cli/test_install.py index 9fab531..6dac9d3 100644 --- a/tests/vstack/cli/test_install.py +++ b/tests/vstack/cli/test_install.py @@ -22,7 +22,7 @@ class TestInstallCommand: # ------------------------------------------------------------------ def test_version_gt_true_for_higher(self) -> None: - """Newer semver string is strictly greater.""" + """Higher dotted numeric revision is strictly greater.""" assert InstallCommand._version_gt("1.2.0", "1.1.9") def test_version_gt_false_for_equal(self) -> None: @@ -30,13 +30,38 @@ def test_version_gt_false_for_equal(self) -> None: assert not InstallCommand._version_gt("1.2.0", "1.2.0") def test_version_gt_handles_invalid(self) -> None: - """Non-semver strings are treated as (0,) and not greater than a real version.""" + """Non-numeric strings are treated as (0,) and not greater than a real revision.""" assert not InstallCommand._version_gt("abc", "1.0.0") def test_version_gt_handles_none_existing(self) -> None: """None for existing falls back to (0,) so any real version is greater.""" assert InstallCommand._version_gt("1.2.0", None) is True + def test_version_gt_true_for_date_revision(self) -> None: + """Higher date-based revision is strictly greater.""" + assert InstallCommand._version_gt("20260502012", "20260502011") + + def test_version_gt_false_for_same_date_revision(self) -> None: + """Equal date-based revisions are not greater.""" + assert not InstallCommand._version_gt("20260502012", "20260502012") + + def test_version_gt_date_revision_gt_legacy_dotted(self) -> None: + """YYYYMMDDNNN token is greater than a legacy dotted version from an existing manifest. + + This is the real upgrade path: a freshly installed repo may have artifacts + versioned as e.g. 1.2.0 (legacy) and the new template uses 20260502012. + The comparison must return True so the artifact is upgraded, not skipped. + """ + assert InstallCommand._version_gt("20260502012", "1.2.0") + + def test_version_gt_date_revision_gt_legacy_dotted_high_patch(self) -> None: + """YYYYMMDDNNN token is greater than a legacy high-patch dotted version.""" + assert InstallCommand._version_gt("20260421001", "9.99.999") + + def test_version_gt_legacy_dotted_not_gt_date_revision(self) -> None: + """Legacy dotted version is never greater than a YYYYMMDDNNN token.""" + assert not InstallCommand._version_gt("1.2.0", "20260502012") + # ------------------------------------------------------------------ # _installed_content_matches # ------------------------------------------------------------------ diff --git a/tests/vstack/cli/test_service.py b/tests/vstack/cli/test_service.py index de5341c..3b1841f 100644 --- a/tests/vstack/cli/test_service.py +++ b/tests/vstack/cli/test_service.py @@ -213,7 +213,7 @@ def test_install_update_skips_when_version_not_newer(self, tmp_path: Path) -> No { "name": "vision", "file": "skills/vision/SKILL.md", - "version": "999.0.0", + "version": "99999999999", "checksum": content_hash("old"), } ] diff --git a/tests/vstack/frontmatter/test_serializer.py b/tests/vstack/frontmatter/test_serializer.py index e6e46e3..b1ec4f0 100644 --- a/tests/vstack/frontmatter/test_serializer.py +++ b/tests/vstack/frontmatter/test_serializer.py @@ -2,6 +2,7 @@ from __future__ import annotations +from vstack.artifacts.config import INSTRUCTION_SCHEMA from vstack.frontmatter import FieldSpec, FrontmatterSchema, FrontmatterSerializer from vstack.skills.config import SKILL_SCHEMA @@ -165,3 +166,34 @@ def test_serialize_multiline_scalar_preserves_content_around_blank_lines(self) - assert "description: >-" in output assert " First paragraph." in output assert " Second paragraph." in output + + def test_instruction_schema_applyto_glob_is_quoted(self) -> None: + """Test that applyTo glob values are single-quoted in generated instruction frontmatter. + + YAML plain scalars cannot start with * because that token denotes an alias. + Globs like **/* must be emitted in single quotes so that consumer repos can + parse the installed instruction frontmatter without a YAML parse error. + """ + output = FrontmatterSerializer().serialize( + { + "name": "python", + "description": "Python coding conventions.", + "applyTo": "**/*.py", + }, + INSTRUCTION_SCHEMA, + ) + assert "applyTo: '**/*.py'" in output + assert "applyTo: **/*.py" not in output + + def test_instruction_schema_applyto_multi_glob_is_quoted(self) -> None: + """Test that multi-extension applyTo globs are quoted in instruction frontmatter.""" + output = FrontmatterSerializer().serialize( + { + "name": "typescript", + "description": "TypeScript conventions.", + "applyTo": "**/*.{ts,tsx,js,jsx}", + }, + INSTRUCTION_SCHEMA, + ) + assert "applyTo: '**/*.{ts,tsx,js,jsx}'" in output + assert "applyTo: **/*.{ts,tsx,js,jsx}" not in output