vstack 3.5.2__tar.gz → 3.6.0__tar.gz

{vstack-3.5.2 → vstack-3.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vstack
-Version: 3.5.2
+Version: 3.6.0
 Summary: VS Code-native AI engineering workflow system for microservices, libraries, and backend systems.
 License-Expression: MIT
 License-File: LICENSE
@@ -19,7 +19,7 @@ Classifier: Topic :: Software Development :: Build Tools
 Classifier: Topic :: Software Development :: Code Generators
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Topic :: Utilities
-Requires-Dist: pyyaml (>=6.0)
+Requires-Dist: pyyaml (>=6.0.3)
 Project-URL: Changelog, https://github.com/eschaar/vstack/blob/main/CHANGELOG.md
 Project-URL: Documentation, https://github.com/eschaar/vstack/blob/main/README.md
 Project-URL: Discussions, https://github.com/eschaar/vstack/discussions

{vstack-3.5.2 → vstack-3.6.0}/pyproject.toml

@@ -5,7 +5,7 @@ description = "VS Code-native AI engineering workflow system for microservices,
 license = "MIT"
 readme = "README-pypi.md"
 requires-python = ">=3.11,<3.15"
-dependencies = ["pyyaml>=6.0"]
+dependencies = ["pyyaml>=6.0.3"]
 keywords = [
     "github-copilot",
     "vscode",
@@ -45,7 +45,7 @@ classifiers = [
     "Topic :: Software Development :: Libraries :: Python Modules",
     "Topic :: Utilities",
 ]
-version = "3.5.2"
+version = "3.6.0"
 
 [project.urls]
 Homepage = "https://github.com/eschaar/vstack"
@@ -77,7 +77,7 @@ include = [
 poetry-dynamic-versioning = { version = ">=1.10.0,<2.0.0", extras = ["plugin"] }
 
 [tool.poetry.group.dev.dependencies]
-pytest = ">=9.0.3"
+pytest = ">=9.1.1"
 pytest-cov = ">=7.1.0"
 ruff = ">=0.15.16"
 mypy = ">=2.1.0"

vstack-3.6.0/src/vstack/_templates/agents/_partials/stage-report-contract.md

@@ -0,0 +1,25 @@
+Use this exact stage report schema at the end of your response. Keep values short and deterministic.
+
+- `status`: `ready` or `blocked`
+- `changes_made`: `yes` or `no`
+- `updated_items`: list of paths or `none`
+- `plan_delta`: short list of plan updates or `none`
+- `blockers`: list or `none`
+- `token_usage_summary`: `input_tokens`, `output_tokens`, `total_tokens`, and `budget_status` (`within` or `exceeded`)
+- `next_handoff_summary`: one short paragraph
+- `planner_run_id`: value from `PLANNER_RUN_ID` or `none`
+- `model_used`: model identifier or `unknown`
+- `subagents_invoked`: list of delegated subagents or `none`
+
+Example:
+
+- `status`: `ready`
+- `changes_made`: `yes`
+- `updated_items`: `docs/architecture/overview.md`
+- `plan_delta`: `none`
+- `blockers`: `none`
+- `token_usage_summary`: `input_tokens=1200, output_tokens=420, total_tokens=1620, budget_status=within`
+- `next_handoff_summary`: `Architecture baseline updated and aligned with current requirements. Ready for designer handoff.`
+- `planner_run_id`: `20260611T101500Z-a1b2`
+- `model_used`: `GPT-5.3-Codex (copilot)`
+- `subagents_invoked`: `none`

{vstack-3.5.2 → vstack-3.6.0}/src/vstack/_templates/agents/architect/config.yaml

@@ -16,11 +16,6 @@ tools:
   - vscode
   - todo
   - agent
-model:
-  - auto
-  - Claude Sonnet 4.6 (copilot)
-  - GPT-5.3-Codex (copilot)
-  - Claude Opus 4.7 (copilot)
 agents:
   - product
   - architect

{vstack-3.5.2 → vstack-3.6.0}/src/vstack/_templates/agents/designer/config.yaml

@@ -15,10 +15,6 @@ tools:
   - vscode
   - todo
   - agent
-model:
-  - auto
-  - Claude Sonnet 4.6 (copilot)
-  - GPT-5.3-Codex (copilot)
 agents:
   - product
   - architect

{vstack-3.5.2 → vstack-3.6.0}/src/vstack/_templates/agents/engineer/config.yaml

@@ -15,10 +15,6 @@ tools:
   - vscode
   - todo
   - agent
-model:
-  - auto
-  - GPT-5.3-Codex (copilot)
-  - Claude Sonnet 4.6 (copilot)
 agents:
   - product
   - architect

{vstack-3.5.2 → vstack-3.6.0}/src/vstack/_templates/agents/planner/config.yaml

@@ -10,10 +10,6 @@ tools:
   - search
   - todo
   - agent
-model:
-  - auto
-  - GPT-5.3-Codex (copilot)
-  - Claude Sonnet 4.6 (copilot)
 agents:
   - product
   - architect

{vstack-3.5.2 → vstack-3.6.0}/src/vstack/_templates/agents/planner/template.md

@@ -74,6 +74,23 @@ Signs a request is a focused task (not a pipeline run):
 
 When in doubt, ask: "Does this need more than one role to complete?" If not, route directly.
 
+## collaborative planning with user approval
+
+Before dispatching worker agents for a full pipeline, create a short execution plan with the user.
+
+1. Propose the initial plan as a compact stage list with: objective, owning role, and dependencies.
+1. Ask for confirmation or edits when sequencing, scope, or ownership is ambiguous.
+1. Apply user feedback and freeze the plan baseline for this run.
+1. Start delegation only after the plan is accepted.
+
+During execution, the plan may change only when new facts appear. When replanning is needed:
+
+1. Explain what changed and why the current plan is no longer valid.
+1. Propose the minimal plan delta.
+1. Ask for approval before continuing with the updated plan.
+
+The planner owns planning and orchestration decisions. Worker agents execute scoped tasks from the accepted plan.
+
 ## working principles
 
 - **Classify before orchestrating.** Determine whether the request is a full pipeline run or a focused task before starting any stage. Starting the pipeline for a focused task is overhead without benefit.
@@ -101,6 +118,71 @@ For every ready stage or domain question:
 
 If a domain question surfaces mid-orchestration that no stage report has answered, route it to the relevant specialist instead of answering it yourself.
 
+## token efficiency and delegation budget
+
+Use subagents by default for substantive work, but keep delegation payloads minimal and deterministic.
+
+1. Set a concise run budget up front: expected number of stages, candidate parallel branches, and escalation points.
+1. Delegate only the minimum context needed for the stage:
+
+- stage objective
+- accepted plan slice for this stage
+- relevant predecessor outputs only
+- explicit done criteria
+
+1. Prefer delta handoffs. If a stage reruns, pass only what changed since the last attempt.
+1. Avoid duplicate calls. Do not invoke a worker again with the same objective and unchanged inputs.
+1. Use focused specialist routing instead of broad multi-role fan-out when one role can complete the task.
+1. Keep stage reports compact and structured so downstream prompts can reference fields instead of replaying prose.
+
+Parallelization rule:
+
+- Run in parallel only when dependencies are fully satisfied and merge criteria are explicit.
+- If merge criteria are unclear, run sequentially to avoid rework and token waste.
+
+Escalation rule:
+
+- If required context is missing, ask one targeted question before dispatching.
+- If uncertainty remains high after one question, pause and request user decision instead of speculative delegation.
+
+## plan state and persistence
+
+The execution plan is operational state, not a domain deliverable.
+
+Planner-run state schema (keep this shape stable across the run):
+
+```yaml
+planner_run_state:
+  planner_run_id: <string>
+  plan_version: <integer>
+  stage_status_map:
+    <stage_id>: ready|blocked|skipped|pending
+  blockers:
+    - <short blocker>
+```
+
+State update protocol:
+
+1. Initialize `planner_run_state` before first delegation.
+
+1. Increment `plan_version` only when plan structure or sequencing changes.
+
+1. Update only the affected keys after each stage (delta update), especially `stage_status_map` and `blockers`.
+
+1. Keep `planner_run_id` stable for the full run and propagate it to every delegated prompt.
+
+1. On replan, record a short rationale and changed stages before dispatch continues.
+
+1. Do not write planner run plans to project docs output paths (for example, docs releases or role-owned artifacts) unless explicitly requested.
+
+1. Keep active plan state in session-level coordination context and stage execution logs.
+
+1. If repository memory is available, persist only concise run metadata there (plan version, stage status map, blocker list, planner run id).
+
+1. Persist plan state updates as deltas, not full rewrites.
+
+1. Treat persisted plan state as coordination data only; worker artifacts remain owned by worker agents.
+
 ## decision guidelines
 
 - If workflow config is missing or invalid, stop and report exactly what is wrong.

{vstack-3.5.2 → vstack-3.6.0}/src/vstack/_templates/agents/product/config.yaml

@@ -15,11 +15,6 @@ tools:
   - vscode
   - todo
   - agent
-model:
-  - auto
-  - Claude Sonnet 4.6 (copilot)
-  - GPT-5.3-Codex (copilot)
-  - Claude Opus 4.7 (copilot)
 agents:
   - product
   - architect

{vstack-3.5.2 → vstack-3.6.0}/src/vstack/_templates/agents/release/config.yaml

@@ -15,10 +15,6 @@ tools:
   - vscode
   - todo
   - agent
-model:
-  - auto
-  - Claude Sonnet 4.6 (copilot)
-  - GPT-5.3-Codex (copilot)
 agents:
   - product
   - architect

{vstack-3.5.2 → vstack-3.6.0}/src/vstack/_templates/agents/tester/config.yaml

@@ -14,10 +14,6 @@ tools:
   - vscode
   - todo
   - agent
-model:
-  - auto
-  - Claude Sonnet 4.6 (copilot)
-  - GPT-5.3-Codex (copilot)
 agents:
   - product
   - architect

vstack-3.6.0/src/vstack/_templates/instructions/git/template.md

@@ -0,0 +1,36 @@
+Use these Git and release hygiene conventions.
+
+## Branch naming
+
+1. Use `type/short-description` branch names.
+1. Keep names lowercase and hyphenated.
+1. Use one of these branch types when validation is enabled:
+   `feature`, `bugfix`, `hotfix`, `release`, `chore`, `feat`, `fix`, `docs`,
+   `refactor`, `perf`, `test`, `ci`, `build`, `style`, `opt`, `patch`, `dependabot`.
+
+## Commit messages
+
+1. Use Conventional Commits: `type(optional-scope)!: short summary`.
+1. Keep subjects clear, imperative, and within repository limits.
+1. Keep commit subjects at 100 characters or fewer when policy CI enforces that limit.
+1. Add `!` or a `BREAKING CHANGE:` footer for breaking behavior.
+1. Match type and scope to repository policy.
+
+## SemVer alignment
+
+1. Treat commit messages as release inputs when semantic version automation is in use.
+1. Reflect major, minor, and patch intent in the commit type and breaking markers.
+1. Do not merge release-impacting changes with ambiguous commit messages.
+
+## Security and credentials
+
+1. Never ask users to paste passphrases, tokens, API keys, or private keys into chat.
+1. Never echo or log secrets from prompts, command output, or environment variables.
+1. Never place credentials in commit messages, source files, workflow files, or documentation.
+1. Prefer existing secure auth flows such as SSH agent, OS keychain, or `gh auth`.
+
+## Safe Git operations
+
+1. Avoid force pushes and destructive history rewrites unless explicitly requested and approved.
+1. Keep commits focused and reviewable.
+1. Prefer local verification before pushing release-impacting changes.

{vstack-3.5.2 → vstack-3.6.0}/src/vstack/_templates/instructions/helm/template.md

@@ -1,4 +1,4 @@
-Use these Helm conventions in this project.
+Use these Helm conventions.
 
 ## Chart structure
 
@@ -8,10 +8,10 @@ Use these Helm conventions in this project.
 
 ## 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. Quote string values where ambiguity may cause rendering or type errors.
+1. Guard optional blocks with conditionals to avoid invalid YAML.
 1. Keep names and labels deterministic via helper templates.
-1. Avoid embedding large opaque blobs in templates; externalize where possible.
+1. Avoid embedding large opaque blobs; externalize where possible.
 
 ## Values and secrets
 
@@ -34,7 +34,7 @@ Use these Helm conventions in this project.
 
 ## References
 
-> Always use the official documentation for the exact Helm and Kubernetes versions in use - chart schema, flags, and behavior evolve between releases.
+> 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/)

{vstack-3.5.2 → vstack-3.6.0}/src/vstack/_templates/instructions/java/template.md

@@ -1,10 +1,10 @@
-Use these Java conventions in this project.
+Use these Java conventions.
 
 ## 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 explicit, domain-meaningful names over abbreviations.
+1. Keep methods focused.
+1. Prefer immutable objects; make fields `final` by default.
 1. Prefer straightforward control flow over clever one-liners.
 
 ## Types and APIs
@@ -12,13 +12,13 @@ Use these Java conventions in this project.
 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.
+1. Prefer `Optional` as a return type for absent values; 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.
+1. Fail fast on unexpected nulls at system boundaries.
 
 ## Exception handling
 

{vstack-3.5.2 → vstack-3.6.0}/src/vstack/_templates/instructions/k8s/template.md

@@ -1,4 +1,4 @@
-Use these Kubernetes conventions in this project.
+Use these Kubernetes conventions.
 
 ## API and versioning
 
@@ -9,7 +9,7 @@ Use these Kubernetes conventions in this project.
 ## 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. Define 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.
 
@@ -30,7 +30,7 @@ Use these Kubernetes conventions in this project.
 
 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.
+1. Add resource annotations or labels needed by observability and runtime policies.
 
 ## Validation
 
@@ -40,7 +40,7 @@ Use these Kubernetes conventions in this project.
 
 ## References
 
-> Always use the official documentation for the exact Kubernetes version in use - API versions and defaults change between releases.
+> 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/)

vstack-3.6.0/src/vstack/_templates/instructions/markdown/template.md

@@ -0,0 +1,46 @@
+Use these Markdown conventions.
+
+## Structure and headings
+
+1. Keep heading levels sequential.
+1. Prefer flat heading structures; rarely go deeper than `####`.
+1. Keep headings short and descriptive.
+
+## Prose and tone
+
+1. Write in clear, direct language with active voice.
+1. Keep sentences short.
+1. Be consistent with terminology throughout the file.
+1. Avoid filler phrases such as "please note", "it is important to", and "simply".
+
+## Lists and tables
+
+1. Use numbered lists for ordered steps and unordered lists for non-ordered items.
+1. Keep list items parallel.
+1. Prefer tables over nested lists for structured comparisons.
+1. Keep tables lean.
+
+## Code blocks and inline code
+
+1. Specify a language identifier on fenced code blocks when possible.
+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.
+1. Prefer relative links for documents within the same repository.
+1. Verify that section anchors match actual heading text.
+
+## Diagrams
+
+1. Use Mermaid for process, flow, interaction, lifecycle, and decision diagrams when the target environment renders it.
+1. Fall back to ASCII or plain text when Mermaid cannot be guaranteed.
+1. Use ASCII or text trees for directory layouts and file hierarchies.
+1. Do not embed a diagram where a simple sentence or table communicates the same information.
+
+## Maintenance
+
+1. Update documentation with the behavior or interface it describes.
+1. Remove outdated content rather than leaving a TODO.
+1. Keep examples accurate and runnable.

{vstack-3.5.2 → vstack-3.6.0}/src/vstack/_templates/instructions/python/template.md

@@ -1,23 +1,23 @@
-Use these Python conventions in this project.
+Use these Python conventions.
 
 ## 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. Raise precise exceptions with actionable error messages.
+1. Keep functions focused.
+1. Prefer straightforward control flow.
+1. Raise precise exceptions with actionable messages.
 
 ## Typing and APIs
 
 1. Add type hints to public functions, methods, and module-level constants.
-1. Keep public interfaces stable and backward compatible unless the task explicitly allows breaking changes.
-1. Use dataclasses or TypedDict for structured data instead of untyped dicts when shape is known.
+1. Keep public interfaces stable and backward compatible unless breaking changes are explicitly allowed.
+1. Use dataclasses or TypedDict for structured data.
 
 ## Imports and dependencies
 
 1. Group imports as standard library, third-party, and local modules.
 1. Keep imports minimal and remove unused imports.
-1. Avoid adding runtime dependencies unless there is a clear benefit over stdlib or existing project dependencies.
+1. Avoid adding runtime dependencies unless there is a clear benefit over stdlib or existing dependencies.
 
 ## Testing and verification
 

{vstack-3.5.2 → vstack-3.6.0}/src/vstack/_templates/instructions/rancher/template.md

@@ -1,10 +1,10 @@
-Use these Rancher conventions in this project.
+Use these Rancher conventions.
 
 ## 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.
+1. Document expected project and namespace scope for each config set.
 
 ## Fleet and GitOps hygiene
 
@@ -23,17 +23,17 @@ Use these Rancher conventions in this project.
 
 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.
+1. Keep auditability for cluster and project configuration changes.
 
 ## Operations
 
-1. Validate target clusters/projects before applying any change.
+1. Validate target clusters and 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.
+> 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/)

vstack-3.6.0/src/vstack/_templates/instructions/security/template.md

@@ -0,0 +1,37 @@
+Use these security policies.
+
+## Secrets and credentials
+
+1. Never hardcode secrets, tokens, passwords, or private keys in source code, config files, tests, or commit messages.
+1. Read secrets from environment variables or a secret store at runtime; document required variables.
+1. Treat accidental exposure as a revocation event; rotate immediately.
+
+## 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.
+1. Reject or escape input before it reaches queries, shell commands, template engines, or logs.
+
+## Authentication and authorization
+
+1. Default to deny; require explicit grants for protected resources or operations.
+1. Verify identity and permission separately.
+1. Use established, maintained libraries; do not implement custom cryptography or auth schemes.
+
+## Dependencies and supply chain
+
+1. Pin dependency versions in manifests; do not use unbounded version ranges in production code.
+1. Minimise the dependency surface.
+1. Treat updates that add 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.
+
+## Destructive and privileged operations
+
+1. Require explicit confirmation before irreversible or destructive operations.
+1. Apply least privilege.
+1. Keep privileged logic minimal, auditable, and separate from business logic.

vstack-3.6.0/src/vstack/_templates/instructions/terraform/template.md

@@ -0,0 +1,55 @@
+Use these Terraform conventions.
+
+## Structure and file layout
+
+1. Split config into `main.tf`, `variables.tf`, `outputs.tf`, `providers.tf`, `versions.tf`, and `locals.tf`.
+1. Keep one module per directory.
+1. Put reusable logic in `modules/<name>/` with its own `variables.tf` and `outputs.tf`.
+
+## Versioning and pinning
+
+1. Pin the Terraform version with `required_version = "~> X.Y"` in `versions.tf`.
+1. Pin each 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 locking for all non-local work.
+1. Enable versioning on the S3 state bucket.
+1. Never expose secrets via outputs; mark sensitive outputs with `sensitive = true`.
+
+## Variables and outputs
+
+1. Add `type`, `description`, and a sensible `default` for every variable.
+1. Add validation blocks for constrained variables.
+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 build 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 and 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/CRITICAL findings before merging.
+
+## References
+
+> Use official docs for the provider and Terraform version in use; resource arguments and defaults change between 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/)

vstack-3.6.0/src/vstack/_templates/instructions/terragrunt/template.md

@@ -0,0 +1,52 @@
+Use these Terragrunt conventions.
+
+## 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 repo root or top-level `infra/`; 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 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 keep tagging consistent across 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 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 root config.
+
+## DRY inputs
+
+1. Extract shared inputs for an ecosystem 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
+
+> Use official docs for the Terragrunt version in use; built-in functions and CLI flags evolve between releases.
+
+- [Terragrunt documentation](https://terragrunt.gruntwork.io/docs/)
+- [Terragrunt CLI reference](https://terragrunt.gruntwork.io/docs/reference/cli-options/)