feat(workflow): improve planner routing and stabilize artifact generation - #58
Merged
Conversation
Contributor
There was a problem hiding this comment.
Pull request overview
This PR updates vstack’s workflow and artifact-generation system to reduce drift between source templates, generated .github/ artifacts, and golden fixtures. It adds new reusable prompts/skills, introduces stricter agent-delegation validation, refreshes generated artifacts/fixtures, and extends docs + verification scaffolding to stabilize CI.
Changes:
- Add source-template verification policy for agent delegation (reject
agents: ["*"]and worker→planner delegation). - Expand the built-in catalog (new skills + prompts) and regenerate
.github/artifacts and golden fixtures. - Add verification tooling/docs updates (fixture-only CI job, drift guard, new
maketargets, expanded user docs).
Reviewed changes
Copilot reviewed 222 out of 223 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| tests/vstack/frontmatter/test_serializer.py | Adds coverage for YAML-quoting list items that start with special characters. |
| tests/vstack/cli/test_constants.py | Updates canonical artifact name expectations (skills + hooks). |
| tests/vstack/artifacts/conftest.py | Adds shared fixtures for golden-fixture artifact tests. |
| tests/vstack/agents/test_generator.py | Adds tests for new agent input-verification policies. |
| tests/vstack/agents/test_generation.py | Updates expected agent model list to include auto. |
| tests/vstack/agents/test_config.py | Updates agent schema tests for new model list behavior. |
| tests/_fixtures/golden/prompts/code-review.prompt.md | New golden prompt fixture for code-review. |
| tests/_fixtures/golden/prompts/api-design-review.prompt.md | New golden prompt fixture for api-design-review. |
| tests/_fixtures/golden/instructions/testing.instructions.md | New golden instruction fixture for testing. |
| tests/_fixtures/golden/instructions/security.instructions.md | New golden instruction fixture for security. |
| src/vstack/cli/constants.py | Extends built-in canonical catalogs (skills/prompts/hooks). |
| src/vstack/agents/generator.py | Adds verify_input policy checks for subagent delegation. |
| src/vstack/_templates/skills/space-setup/template.md | New space-setup skill template. |
| src/vstack/_templates/skills/space-setup/config.yaml | New space-setup skill metadata/config. |
| src/vstack/_templates/skills/copilot-ops/template.md | New copilot-ops skill template. |
| src/vstack/_templates/skills/copilot-ops/config.yaml | New copilot-ops skill metadata/config. |
| src/vstack/_templates/prompts/workflow-check/template.md | New workflow-check prompt template. |
| src/vstack/_templates/prompts/workflow-check/config.yaml | New workflow-check prompt config. |
| src/vstack/_templates/prompts/upgrade-plan/template.md | New upgrade-plan prompt template. |
| src/vstack/_templates/prompts/upgrade-plan/config.yaml | New upgrade-plan prompt config. |
| src/vstack/_templates/prompts/test-gaps/template.md | New test-gaps prompt template. |
| src/vstack/_templates/prompts/test-gaps/config.yaml | New test-gaps prompt config. |
| src/vstack/_templates/prompts/template-impact/template.md | New template-impact prompt template. |
| src/vstack/_templates/prompts/template-impact/config.yaml | New template-impact prompt config. |
| src/vstack/_templates/prompts/repo-assessment/template.md | New repo-assessment prompt template. |
| src/vstack/_templates/prompts/repo-assessment/config.yaml | New repo-assessment prompt config. |
| src/vstack/_templates/prompts/release-readiness/template.md | Removes deprecated release-readiness prompt template. |
| src/vstack/_templates/prompts/release-readiness/config.yaml | Removes deprecated release-readiness prompt config. |
| src/vstack/_templates/prompts/release-check/template.md | Adds replacement release-check prompt template. |
| src/vstack/_templates/prompts/release-check/config.yaml | Adds replacement release-check prompt config. |
| src/vstack/_templates/prompts/ops-readiness/template.md | New ops-readiness prompt template. |
| src/vstack/_templates/prompts/ops-readiness/config.yaml | New ops-readiness prompt config. |
| src/vstack/_templates/prompts/migration-plan/template.md | New migration-plan prompt template. |
| src/vstack/_templates/prompts/migration-plan/config.yaml | New migration-plan prompt config. |
| src/vstack/_templates/prompts/ci-triage/template.md | New ci-triage prompt template. |
| src/vstack/_templates/prompts/ci-triage/config.yaml | New ci-triage prompt config. |
| src/vstack/_templates/prompts/artifact-integrity/template.md | New artifact-integrity prompt template. |
| src/vstack/_templates/prompts/artifact-integrity/config.yaml | New artifact-integrity prompt config. |
| src/vstack/_templates/hooks/pre-tool-safety-gate/hook.yaml | Refactors hook logging to central helpers. |
| src/vstack/_templates/hooks/post-edit-markdown-quality/hook.yaml | Refactors hook logging and enforce-mode behavior. |
| src/vstack/_templates/hooks/post-edit-format/hook.yaml | Refactors hook logging and enforce-mode behavior. |
| src/vstack/_templates/hooks/post-commit-security-scan/hook.yaml | Refactors hook logging and enforce-mode behavior. |
| src/vstack/_templates/agents/tester/template.md | Switches to shared stage report contract partial. |
| src/vstack/_templates/agents/tester/config.yaml | Replaces wildcard delegation with explicit allowlist; adds auto model. |
| src/vstack/_templates/agents/release/template.md | Switches to shared stage report contract; adds skill reference. |
| src/vstack/_templates/agents/release/config.yaml | Replaces wildcard delegation with explicit allowlist; adds auto model. |
| src/vstack/_templates/agents/product/template.md | Switches to shared stage report contract; adds skill reference. |
| src/vstack/_templates/agents/product/config.yaml | Replaces wildcard delegation with explicit allowlist; adds auto model. |
| src/vstack/_templates/agents/planner/config.yaml | Adds auto to planner model list. |
| src/vstack/_templates/agents/engineer/template.md | Switches to shared stage report contract partial. |
| src/vstack/_templates/agents/engineer/config.yaml | Replaces wildcard delegation with explicit allowlist; adds auto model. |
| src/vstack/_templates/agents/designer/template.md | Switches to shared stage report contract partial. |
| src/vstack/_templates/agents/designer/config.yaml | Replaces wildcard delegation with explicit allowlist; adds auto model. |
| src/vstack/_templates/agents/architect/template.md | Switches to shared stage report contract partial. |
| src/vstack/_templates/agents/architect/config.yaml | Replaces wildcard delegation with explicit allowlist; adds auto model. |
| src/vstack/_templates/agents/_partials/stage-report-contract.md | Adds reusable stage report schema partial. |
| pyproject.toml | Adjusts pytest temp directory location. |
| Makefile | Adds fixture-only and layered verification targets (test-fixtures, verify-fast, verify-full). |
| docs/user/tutorials/upgrade-with-checks.md | New tutorial for upgrades with explicit checkpoints. |
| docs/user/tutorials/README.md | Adds tutorial index page. |
| docs/user/tutorials/first-time-using-vstack.md | New first-time user tutorial. |
| docs/user/tutorials/first-planner-run.md | New “first planner run” tutorial. |
| docs/user/start-here.md | Adds start-here navigation and quick command block. |
| docs/user/reference/work-items.md | New reference page describing work-item artifacts per role. |
| docs/user/reference/skills-overview.md | New reference page listing built-in skills. |
| docs/user/reference/README.md | Adds reference index page. |
| docs/user/reference/prompts-overview.md | New reference page listing built-in prompts. |
| docs/user/reference/instructions-overview.md | New reference page listing built-in instructions. |
| docs/user/reference/cli-commands.md | New CLI command reference page. |
| docs/user/reference/artifact-checks.md | New explanation of drift/ownership checks and recovery flow. |
| docs/user/README.md | Adds user-docs navigation index. |
| docs/user/how-to/upgrade.md | New operational upgrade how-to. |
| docs/user/how-to/update-managed-artifacts.md | New how-to for controlled regeneration/overwrite. |
| docs/user/how-to/uninstall.md | New uninstall guide. |
| docs/user/how-to/troubleshooting.md | New troubleshooting guide. |
| docs/user/how-to/reinitialize.md | New reinitialize guide. |
| docs/user/how-to/README.md | Adds how-to index page. |
| docs/user/how-to/partial-upgrade.md | New partial-upgrade guide. |
| docs/user/how-to/how-to-install-a-skill.md | New guide for enabling and regenerating skills. |
| docs/user/how-to/global-install.md | New global install guide. |
| docs/user/how-to/fresh-install.md | New fresh install guide. |
| docs/user/how-to/configure-workflow-modes.md | New how-to for workflow mode configuration. |
| docs/user/how-to/choose-agent-skill-or-prompt.md | New decision guide for choosing artifacts in Copilot Chat. |
| docs/user/explanation/workflow-modes.md | New conceptual explanation of workflow modes and planner routing. |
| docs/user/explanation/vstack-templates.md | New explanation for .vstack/templates/ purpose/ownership. |
| docs/user/explanation/README.md | Adds explanation index page. |
| docs/user/explanation/community-patterns.md | Introduces “community patterns” concept doc. |
| docs/releases/2026-05-10.md | Adds release note record (v3.1.1). |
| docs/releases/2026-05-09.md | Adds release note record (v3.1.0). |
| docs/releases/2026-05-06.md | Normalizes artifact table formatting. |
| docs/releases/2026-05-02.md | Adds historical release note record. |
| docs/releases/2026-04-28.md | Adds historical release note record. |
| docs/releases/2026-04-27.md | Adds historical release note record. |
| docs/releases/2026-04-26.md | Normalizes artifact paths/table formatting. |
| docs/releases/2026-04-22.md | Adds historical release note record. |
| docs/releases/2026-04-21.md | Adds historical release note record. |
| docs/releases/2026-04-20.md | Adds historical release note record. |
| docs/releases/2026-04-19.md | Adds historical release note record. |
| docs/releases/2026-04-17.md | Adds historical release note record. |
| docs/releases/2026-04-01.md | Adds historical release note record. |
| docs/product/vision.md | Updates last-updated date and runtime dependency statement. |
| docs/design/workflow.md | Updates workflow docs (planner entry point, correlation semantics, configurable gates). |
| docs/design/skills.md | Updates skill catalog and manifest path/allowed-tools statement. |
| docs/design/agents.md | Updates agent config documentation to match new policies and examples. |
| docs/architecture/overview.md | Updates example agent config and improves internal linking/ADR table. |
| docs/architecture/adr/017-checksum-backfill-on-upgrade.md | Removes now-irrelevant “designer handoff” appendix content. |
| CONTRIBUTING.md | Adds verify profiles, change-to-check matrix, and pytest temp guidance. |
| .pre-commit-config.yaml | Excludes golden fixtures from mdformat to avoid fixture drift. |
| .gitignore | Ignores .vstack/tmp/ directory. |
| .github/workflows/verify.yml | Adds fixture-only CI job and .github/ drift guard step. |
| .github/copilot-instructions.md | Adds artifact-choice policy guidance. |
| .github/skills/vision/SKILL.md | Regenerated skill artifact footer version bump. |
| .github/skills/verify/SKILL.md | Regenerated skill artifact footer version bump. |
| .github/skills/threat-model/SKILL.md | Regenerated skill artifact footer version bump. |
| .github/skills/terragrunt/SKILL.md | Regenerated skill artifact footer version bump. |
| .github/skills/terraform/SKILL.md | Regenerated skill artifact footer version bump. |
| .github/skills/space-setup/SKILL.md | New generated space-setup skill artifact. |
| .github/skills/security/SKILL.md | Regenerated skill artifact footer version bump. |
| .github/skills/secret-scan/SKILL.md | Regenerated skill artifact footer version bump. |
| .github/skills/requirements/SKILL.md | Regenerated skill artifact footer version bump. |
| .github/skills/release-notes/SKILL.md | Regenerated skill artifact footer version bump. |
| .github/skills/refactor/SKILL.md | Regenerated skill artifact footer version bump. |
| .github/skills/rca/SKILL.md | Regenerated skill artifact footer version bump. |
| .github/skills/rancher/SKILL.md | Regenerated skill artifact footer version bump. |
| .github/skills/pr/SKILL.md | Regenerated skill artifact footer version bump. |
| .github/skills/postmortem/SKILL.md | Regenerated skill artifact footer version bump. |
| .github/skills/performance/SKILL.md | Regenerated skill artifact footer version bump. |
| .github/skills/openapi/SKILL.md | Regenerated skill artifact footer version bump. |
| .github/skills/onboard/SKILL.md | Regenerated skill artifact footer version bump. |
| .github/skills/migrate/SKILL.md | Regenerated skill artifact footer version bump. |
| .github/skills/k8s/SKILL.md | Regenerated skill artifact footer version bump. |
| .github/skills/inspect/SKILL.md | Regenerated skill artifact footer version bump. |
| .github/skills/incident/SKILL.md | Regenerated skill artifact footer version bump. |
| .github/skills/helm/SKILL.md | Regenerated skill artifact footer version bump. |
| .github/skills/guardrails/SKILL.md | Regenerated skill artifact footer version bump. |
| .github/skills/gh-release/SKILL.md | Regenerated skill artifact footer version bump. |
| .github/skills/gh-issues/SKILL.md | Regenerated skill artifact footer version bump. |
| .github/skills/gdpr/SKILL.md | Regenerated skill artifact footer version bump. |
| .github/skills/explore/SKILL.md | Regenerated skill artifact footer version bump. |
| .github/skills/docs/SKILL.md | Regenerated skill artifact footer version bump. |
| .github/skills/design/SKILL.md | Regenerated skill artifact footer version bump. |
| .github/skills/dependency/SKILL.md | Regenerated skill artifact footer version bump. |
| .github/skills/dependabot/SKILL.md | Regenerated skill artifact footer version bump. |
| .github/skills/debug/SKILL.md | Regenerated skill artifact footer version bump. |
| .github/skills/copilot-ops/SKILL.md | New generated copilot-ops skill artifact. |
| .github/skills/conventional-commit/SKILL.md | Regenerated skill artifact footer version bump. |
| .github/skills/container/SKILL.md | Regenerated skill artifact footer version bump. |
| .github/skills/consult/SKILL.md | Regenerated skill artifact footer version bump. |
| .github/skills/concise/SKILL.md | Regenerated skill artifact footer version bump. |
| .github/skills/codeql/SKILL.md | Regenerated skill artifact footer version bump. |
| .github/skills/code-review/SKILL.md | Regenerated skill artifact footer version bump. |
| .github/skills/cloudformation/SKILL.md | Regenerated skill artifact footer version bump. |
| .github/skills/cicd/SKILL.md | Regenerated skill artifact footer version bump. |
| .github/skills/aws-cli/SKILL.md | Regenerated skill artifact footer version bump. |
| .github/skills/architecture/SKILL.md | Regenerated skill artifact footer version bump. |
| .github/skills/analyse/SKILL.md | Regenerated skill artifact footer version bump. |
| .github/skills/adr/SKILL.md | Regenerated skill artifact footer version bump. |
| .github/prompts/workflow-check.prompt.md | New generated workflow-check prompt artifact. |
| .github/prompts/upgrade-plan.prompt.md | New generated upgrade-plan prompt artifact. |
| .github/prompts/test-gaps.prompt.md | New generated test-gaps prompt artifact. |
| .github/prompts/template-impact.prompt.md | New generated template-impact prompt artifact. |
| .github/prompts/repo-assessment.prompt.md | New generated repo-assessment prompt artifact. |
| .github/prompts/release-readiness.prompt.md | Removes generated release-readiness prompt artifact. |
| .github/prompts/release-check.prompt.md | New generated release-check prompt artifact. |
| .github/prompts/ops-readiness.prompt.md | New generated ops-readiness prompt artifact. |
| .github/prompts/migration-safety.prompt.md | Regenerated prompt artifact footer version bump. |
| .github/prompts/migration-plan.prompt.md | New generated migration-plan prompt artifact. |
| .github/prompts/incident-timeline.prompt.md | Regenerated prompt artifact footer version bump. |
| .github/prompts/dependency-audit.prompt.md | Regenerated prompt artifact footer version bump. |
| .github/prompts/code-review.prompt.md | Regenerated prompt artifact footer version bump. |
| .github/prompts/ci-triage.prompt.md | New generated ci-triage prompt artifact. |
| .github/prompts/artifact-integrity.prompt.md | New generated artifact-integrity prompt artifact. |
| .github/prompts/architecture-risk.prompt.md | Regenerated prompt artifact footer version bump. |
| .github/prompts/api-design-review.prompt.md | Regenerated prompt artifact footer version bump. |
| .github/instructions/typescript.instructions.md | Regenerated instruction artifact footer version bump. |
| .github/instructions/testing.instructions.md | Regenerated instruction artifact footer version bump. |
| .github/instructions/terragrunt.instructions.md | Regenerated instruction artifact footer version bump. |
| .github/instructions/terraform.instructions.md | Regenerated instruction artifact footer version bump. |
| .github/instructions/security.instructions.md | Regenerated instruction artifact footer version bump. |
| .github/instructions/rancher.instructions.md | Regenerated instruction artifact footer version bump. |
| .github/instructions/python.instructions.md | Regenerated instruction artifact footer version bump. |
| .github/instructions/markdown.instructions.md | Regenerated instruction artifact footer version bump. |
| .github/instructions/k8s.instructions.md | Regenerated instruction artifact footer version bump. |
| .github/instructions/java.instructions.md | Regenerated instruction artifact footer version bump. |
| .github/instructions/helm.instructions.md | Regenerated instruction artifact footer version bump. |
| .github/instructions/git.instructions.md | Regenerated instruction artifact footer version bump. |
| .github/hooks/post-edit-markdown-quality.json | Regenerated installed hook JSON (logging refactor). |
| .github/hooks/post-edit-format.json | Regenerated installed hook JSON (logging refactor). |
| .github/agents/tester.agent.md | Regenerated agent artifact (explicit allowlist, stage-report contract, model list). |
| .github/agents/release.agent.md | Regenerated agent artifact (explicit allowlist, stage-report contract, model list). |
| .github/agents/product.agent.md | Regenerated agent artifact (explicit allowlist, stage-report contract, model list). |
| .github/agents/engineer.agent.md | Regenerated agent artifact (explicit allowlist, stage-report contract, model list). |
| .github/agents/designer.agent.md | Regenerated agent artifact (explicit allowlist, stage-report contract, model list). |
| .github/agents/architect.agent.md | Regenerated agent artifact (explicit allowlist, stage-report contract, model list). |
Comments suppressed due to low confidence (1)
pyproject.toml:105
- The new pytest base temp directory is set to
.pytest-tmp, but this path is not ignored in.gitignoreand it also conflicts with the CONTRIBUTING guidance that says pytest temps are standardized under.vstack/tmp/test. Pick one canonical temp root (and ignore it) to avoid dirty working trees after tests and to keep docs/config consistent.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR delivers a consolidated workflow and artifact-generation update across templates, generated artifacts, docs, and verification scaffolding.
It improves planner orchestration guidance and focused-task routing, adds new reusable prompts/skills/hooks, refreshes generated
.github/artifacts from template sources, and stabilizes CI behavior around generated markdown golden fixtures.Why
Recent workflow and template evolution introduced drift between generated output and expected fixture snapshots, causing repeated CI failures and noisy reruns.
This change aligns template-driven outputs end-to-end (templates → generated artifacts → fixtures/docs), prevents formatter interference on generated golden fixtures, and restores reliable test execution while keeping planner/user workflow documentation consistent with shipped behavior.
Version impact