Skip to content

instructions.md

Latest commit

 

History

History
96 lines (65 loc) · 4.7 KB

instructions.md

File metadata and controls

96 lines (65 loc) · 4.7 KB
Raw

vstack — instructions

Maintained by: designer role
Last updated: 2026-05-02\

what are instructions?

Instructions are repository guidance files (*.instructions.md) loaded by Copilot to apply baseline rules. They are policy-oriented and can be scoped with applyTo patterns.

Examples:

  • Global safety and credential handling policy.
  • Git and release hygiene policy.
  • Language-specific coding standards that should apply to all changes in that language.

policy vs procedure boundary

vstack uses an explicit split:

  • Instructions = policy (always-on rules and standards).
  • Skills = procedure (task execution workflows).

Canonical decision record: 013-instructions-vs-skills-boundary.md.

Use instructions when guidance is:

  • expected on every applicable change,
  • independent from a specific task flow,
  • naturally expressed as constraints and conventions.

Use skills when guidance is:

  • a step-by-step operational process,
  • optional or intent-driven,
  • specialized to one type of task (for example debug, migrate, performance).

applyTo patterns

applyTo scopes an instruction to matching files.

Examples:

  • **/*.py for Python policy.
  • **/* for repo-wide policy.

applyTo is for policy targeting, not for procedural automation.

file locations

Path Purpose
src/vstack/_templates/instructions/<name>/config.yaml Source of truth: instruction metadata and applyTo scope
src/vstack/_templates/instructions/<name>/template.md Source of truth: instruction body
.github/instructions/<name>.instructions.md Generated output loaded by Copilot

Never edit generated .github/instructions/ directly in the source repository. 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:

  1. Clear applicability and intent.
  2. Concrete rules, not broad aspirations.
  3. Safety constraints where relevant.
  4. Alignment with repository automation (CI, release policy, security policy).