Skip to content

feat(vstack): add changedoc/lazy/simplify skills, introduce reasoning prompt+advise, and tighten agent guardrails - #81

Merged
eschaar merged 8 commits into
mainfrom
feature/changedoc-skill-governance
Jun 27, 2026
Merged

feat(vstack): add changedoc/lazy/simplify skills, introduce reasoning prompt+advise, and tighten agent guardrails#81
eschaar merged 8 commits into
mainfrom
feature/changedoc-skill-governance

Conversation

@eschaar

@eschaar eschaar commented Jun 25, 2026

Copy link
Copy Markdown
Owner

Summary

  • Add three new reusable skills: changedoc, lazy, and simplify (templates, config, generated skill artifacts, and docs alignment).
  • Introduce adversarial review capability via skill/advise and move reasoning from instruction semantics to prompt semantics (prompt/reasoning) for opt-in one-shot use.
  • Strengthen shared agent safety behavior with compact guardrails in the shared boundary partial, then regenerate all role agents.
  • Add planner handoff cache support and related documentation/ADR updates.
  • Update CLI/constants/install flows and related tests/fixtures to reflect new artifacts and generation behavior.
  • Regenerate installed artifacts and sync golden fixtures for planner/product agents.

Why

  • Improve reuse and consistency for common execution patterns:
    • changedoc for structured pre-implementation change docs,
    • lazy/simplify for minimal safe delivery and scope reduction,
    • advise + reasoning for evidence-based, adversarial decision quality.
  • Correct artifact semantics: reasoning is an on-demand evaluation frame, not an always-on instruction.
  • Raise baseline operational safety across all role agents through shared compact guardrails.
  • Keep generated outputs, fixtures, docs, and tests in sync so downstream installs remain deterministic and auditable.

Version impact

  • None
  • Patch
  • Minor
  • Major

eschaar added 7 commits June 25, 2026 23:00
@eschaar
feat(skills): add changedoc, lazy, and simplify workflows
eec8dec
@eschaar
docs(skills): document changedoc ownership and usage
a6561b5
@eschaar
docs(roadmap): add configurable skill output paths candidate
b28672f
@eschaar
chore(generate): sync installed artifacts after template updates
335b93d
@eschaar
test(artifacts): sync planner and product golden fixtures
2420e7d
@eschaar
feat(artifacts): convert reasoning to prompt type, add advise skill
82b15ff 
- Migrate reasoning from Instruction to Prompt artifact type for correct
  one-shot evaluation semantics and opt-in behavior
- Add skill/advise for structured adversarial review workflows
- Update CLI constants EXPECTED_PROMPT_NAMES and EXPECTED_INPUT_NAMES
- Update copilot-instructions.md with reasoning framework section
- Remove obsolete reasoning.instructions.md after prune
- All tests passing: 672 passed, 100% coverage
@eschaar
docs: clarify vstack installation for downstream users
4725de8 
Update downstream user guidance for prompt/reasoning: use vstack manifest +
vstack install instead of manual file copying. This aligns with vstack's
template-driven install model where all artifacts are generated automatically.
@eschaar
eschaar requested a review from Copilot June 25, 2026 22:33
Copilot AI reviewed Jun 25, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR expands vstack’s reusable skill/prompt library (changedoc/lazy/simplify + advise/reasoning), introduces a planner-run handoff cache under .vstack/memories/session/, tightens shared agent guardrails via partials, and then regenerates artifacts while syncing docs, fixtures, CLI constants, and install behavior.

Changes:

  • Add new skills (changedoc, lazy, simplify) plus advise and prompt/reasoning, and update skill catalogs/docs accordingly.
  • Introduce planner/run handoff cache protocol (.vstack/memories/session/<RUN_ID>/) and ensure it’s gitignored via install and templates.
  • Regenerate installed artifacts and update tests + golden fixtures to reflect new templates/partials/constants.

Reviewed changes

Copilot reviewed 133 out of 134 changed files in this pull request and generated 5 comments.

Show a summary per file
File Description
tests/vstack/cli/test_install.py Assert session cache is gitignored.
tests/vstack/cli/test_constants.py Update expected skill name set.
tests/_fixtures/golden/agents/product.agent.md Sync regenerated product agent golden.
tests/_fixtures/golden/agents/planner.agent.md Sync regenerated planner agent golden.
src/vstack/cli/install.py Add memories/session/ to generated .vstack/.gitignore.
src/vstack/cli/constants.py Add new skills + reasoning prompt to expected names.
src/vstack/agents/generator.py Adjust baseline docs section wording.
src/vstack/agents/config.py Register new agent placeholders/partials.
src/vstack/_templates/skills/simplify/template.md Add simplify skill template.
src/vstack/_templates/skills/simplify/config.yaml Add simplify skill metadata.
src/vstack/_templates/skills/lazy/template.md Add lazy skill template.
src/vstack/_templates/skills/lazy/config.yaml Add lazy skill metadata.
src/vstack/_templates/skills/changedoc/template.md Add changedoc skill template.
src/vstack/_templates/skills/changedoc/config.yaml Add changedoc skill metadata.
src/vstack/_templates/skills/advise/template.md Add advise skill template.
src/vstack/_templates/skills/advise/config.yaml Add advise skill metadata.
src/vstack/_templates/prompts/reasoning/template.md Add reasoning prompt template.
src/vstack/_templates/prompts/reasoning/config.yaml Add reasoning prompt metadata.
src/vstack/_templates/project/.vstack/memories/README.md Seed project memory-cache README.
src/vstack/_templates/agents/tester/template.md Include memory-cache partial + skill list trim.
src/vstack/_templates/agents/release/template.md Include memory-cache partial + skill list trim.
src/vstack/_templates/agents/product/template.md Add changedoc-first guidance + memory-cache partial.
src/vstack/_templates/agents/product/artifacts/changes/changedoc.md Add changedoc starter artifact template.
src/vstack/_templates/agents/product/artifacts/changes/change-request.md Remove obsolete change-request artifact.
src/vstack/_templates/agents/planner/template.md Add changedoc gating + memory-cache guidance.
src/vstack/_templates/agents/engineer/template.md Include memory-cache partial + add lazy/simplify.
src/vstack/_templates/agents/designer/template.md Include memory-cache partial + add simplify.
src/vstack/_templates/agents/architect/template.md Include memory-cache partial + add simplify.
src/vstack/_templates/agents/_partials/stage-report-contract.md Update planner_run_id description; trim example.
src/vstack/_templates/agents/_partials/memory-cache.md New shared handoff-cache protocol partial.
src/vstack/_templates/agents/_partials/agent-skill-boundary.md Add compact guardrails to shared boundary.
docs/user/reference/skills-overview.md Document new skills in overview table.
docs/product/roadmap.md Add candidate item for configurable outputs.
docs/design/workflow.md Document handoff-cache semantics.
docs/design/skills.md Update skills catalog + changedoc ownership model.
docs/design/overview.md Mention disposable handoff cache.
docs/architecture/overview.md Add .vstack/memories/ to repo structure docs.
docs/architecture/adr/031-planner-handoff-cache.md New ADR for handoff cache protocol.
CHANGELOG.md Reformat 3.6.0 bullets for consistency.
.vstack/templates/product/artifacts/changes/changedoc.md Install-time changedoc template.
.vstack/templates/product/artifacts/changes/change-request.md Remove obsolete installed change-request template.
.vstack/memories/README.md Add repo memory-cache README.
.vstack/.gitignore Ignore .vstack/memories/session/.
.pre-commit-config.yaml Bump commit-check + ruff hook revisions.
.github/skills/vision/SKILL.md Regen footer version bump.
.github/skills/verify/SKILL.md Regen footer version bump.
.github/skills/threat-model/SKILL.md Regen footer version bump.
.github/skills/terragrunt/SKILL.md Regen footer version bump.
.github/skills/terraform/SKILL.md Regen footer version bump.
.github/skills/space-setup/SKILL.md Regen footer version bump.
.github/skills/simplify/SKILL.md New generated simplify skill artifact.
.github/skills/security/SKILL.md Regen footer version bump.
.github/skills/secret-scan/SKILL.md Regen footer version bump.
.github/skills/requirements/SKILL.md Regen footer version bump.
.github/skills/release-notes/SKILL.md Regen footer version bump.
.github/skills/refactor/SKILL.md Regen footer version bump.
.github/skills/rca/SKILL.md Regen footer version bump.
.github/skills/rancher/SKILL.md Regen footer version bump.
.github/skills/pr/SKILL.md Regen footer version bump.
.github/skills/postmortem/SKILL.md Regen footer version bump.
.github/skills/performance/SKILL.md Regen footer version bump.
.github/skills/openapi/SKILL.md Regen footer version bump.
.github/skills/onboard/SKILL.md Regen footer version bump.
.github/skills/migrate/SKILL.md Regen footer version bump.
.github/skills/lazy/SKILL.md New generated lazy skill artifact.
.github/skills/k8s/SKILL.md Regen footer version bump.
.github/skills/inspect/SKILL.md Regen footer version bump.
.github/skills/incident/SKILL.md Regen footer version bump.
.github/skills/helm/SKILL.md Regen footer version bump.
.github/skills/guardrails/SKILL.md Regen footer version bump.
.github/skills/gh-release/SKILL.md Regen footer version bump.
.github/skills/gh-issues/SKILL.md Regen footer version bump.
.github/skills/gdpr/SKILL.md Regen footer version bump.
.github/skills/explore/SKILL.md Regen footer version bump.
.github/skills/docs/SKILL.md Regen footer version bump.
.github/skills/design/SKILL.md Regen footer version bump.
.github/skills/dependency/SKILL.md Regen footer version bump.
.github/skills/dependabot/SKILL.md Regen footer version bump.
.github/skills/debug/SKILL.md Regen footer version bump.
.github/skills/copilot-ops/SKILL.md Regen footer version bump.
.github/skills/conventional-commit/SKILL.md Regen footer version bump.
.github/skills/container/SKILL.md Regen footer version bump.
.github/skills/consult/SKILL.md Regen footer version bump.
.github/skills/concise/SKILL.md Regen footer version bump.
.github/skills/codeql/SKILL.md Regen footer version bump.
.github/skills/code-review/SKILL.md Regen footer version bump.
.github/skills/cloudformation/SKILL.md Regen footer version bump.
.github/skills/cicd/SKILL.md Regen footer version bump.
.github/skills/changedoc/SKILL.md New generated changedoc skill artifact.
.github/skills/aws-cli/SKILL.md Regen footer version bump.
.github/skills/ask/SKILL.md Regen footer version bump.
.github/skills/architecture/SKILL.md Regen footer version bump.
.github/skills/analyse/SKILL.md Regen footer version bump.
.github/skills/advise/SKILL.md New generated advise skill artifact.
.github/skills/adr/SKILL.md Regen footer version bump.
.github/prompts/workflow-check.prompt.md Regen footer version bump.
.github/prompts/upgrade-plan.prompt.md Regen footer version bump.
.github/prompts/test-gaps.prompt.md Regen footer version bump.
.github/prompts/template-impact.prompt.md Regen footer version bump.
.github/prompts/repo-assessment.prompt.md Regen footer version bump.
.github/prompts/release-check.prompt.md Regen footer version bump.
.github/prompts/reasoning.prompt.md New generated reasoning prompt artifact.
.github/prompts/quick-review.prompt.md Regen footer version bump.
.github/prompts/ops-readiness.prompt.md Regen footer version bump.
.github/prompts/migration-safety.prompt.md Regen footer version bump.
.github/prompts/migration-plan.prompt.md Regen footer version bump.
.github/prompts/incident-timeline.prompt.md Regen footer version bump.
.github/prompts/dependency-audit.prompt.md Regen footer version bump.
.github/prompts/ci-triage.prompt.md Regen footer version bump.
.github/prompts/artifact-integrity.prompt.md Regen footer version bump.
.github/prompts/architecture-risk.prompt.md Regen footer version bump.
.github/prompts/api-design-review.prompt.md Regen footer version bump.
.github/instructions/typescript.instructions.md Regen footer version bump.
.github/instructions/testing.instructions.md Regen footer version bump.
.github/instructions/terragrunt.instructions.md Regen footer version bump.
.github/instructions/terraform.instructions.md Regen footer version bump.
.github/instructions/security.instructions.md Regen footer version bump.
.github/instructions/rancher.instructions.md Regen footer version bump.
.github/instructions/python.instructions.md Regen footer version bump.
.github/instructions/markdown.instructions.md Regen footer version bump.
.github/instructions/k8s.instructions.md Regen footer version bump.
.github/instructions/java.instructions.md Regen footer version bump.
.github/instructions/helm.instructions.md Regen footer version bump.
.github/instructions/git.instructions.md Regen footer version bump.
.github/copilot-instructions.md Add reasoning/advise guidance to repo instructions.
.github/agents/tester.agent.md Regen agent guardrails + memory-cache section.
.github/agents/release.agent.md Regen agent guardrails + memory-cache section.
.github/agents/product.agent.md Regen agent guardrails + changedoc guidance.
.github/agents/planner.agent.md Regen agent guardrails + changedoc gating.
.github/agents/engineer.agent.md Regen agent guardrails + lazy/simplify.
.github/agents/designer.agent.md Regen agent guardrails + simplify.
.github/agents/architect.agent.md Regen agent guardrails + simplify.

Comment thread src/vstack/_templates/skills/advise/template.md Outdated
Comment thread src/vstack/_templates/prompts/reasoning/template.md Outdated
Comment thread .github/copilot-instructions.md Outdated
Comment thread src/vstack/_templates/skills/advise/template.md Outdated
Comment thread src/vstack/_templates/prompts/reasoning/template.md Outdated
@eschaar
eschaar force-pushed the feature/changedoc-skill-governance branch 2 times, most recently from 87116bc to 22546a3 Compare June 27, 2026 13:42
@eschaar
feat(agents): add compact shared safety guardrails
d9fec68 
- Add compact guardrail block to shared AGENT_SKILL_BOUNDARY partial
- Regenerate all agent artifacts to inherit the guardrails
- Sync planner/product agent golden fixtures with generated output
@eschaar
eschaar force-pushed the feature/changedoc-skill-governance branch from 22546a3 to d9fec68 Compare June 27, 2026 13:48
@eschaar
eschaar merged commit 0d57aa0 into main Jun 27, 2026
17 checks passed
@eschaar
eschaar deleted the feature/changedoc-skill-governance branch June 27, 2026 13:51
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot
Copilot review effort, defaults to Lite
Applies to this pull request for everyone.Learn more about Copilot code review.
Copilot left review comments

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@eschaar