Feat/workflow update - #41
Merged
Merged
Conversation
…enericity - Remove hardcoded paths from release-notes and threat-model skill templates - Update product agent to show explore/analyse/debug as skill invocations - Convert ADR-009 and ADR-010 artifact tables to per-role lists - Convert workflow.md required-reads table to per-role list - Remove delta workflow templates row from roadmap feature table - Update ADR-018 status to reflect ADR-021 artifact path decision - Add ADRs 019-021 (vstack project dir, init semantics, config-driven paths) - Add postmortem and rca skill definitions and generated artifacts - Regenerate all .github/ skill, agent, instruction, and prompt artifacts
Store vstack.json in .vstack/vstack.json instead of .github/vstack.json
to separate vstack state from generated GitHub artifacts.
- Add VSTACK_DIR_NAME constant (".vstack")
- Redirect manifest_for() to .vstack/ when install_dir is named .github
- Update status command error message to reference .vstack/vstack.json
- Update README CLI reference table and conservative-install description
- Update copilot-instructions.md system structure diagram
- Update all affected tests (test_service, test_integration, test_store)
- Add unit tests for both manifest_for() branches
BREAKING CHANGE: vstack.json moves from .github/vstack.json to .vstack/vstack.json; run `vstack manifest upgrade` to migrate existing projects
… command - Remove .github/vstack.json from tracking (manifest now lives at .vstack/vstack.json per E1) - Add InitCommand and its tests (missed in previous commit staging)
Introduce four new placeholder tokens resolved at install time:
- {{AGENT_ARTIFACTS_INPUT}} — rendered Markdown table of input artifacts
- {{AGENT_ARTIFACTS_OUTPUT}} — rendered Markdown table of output artifacts
- {{AGENT_ARTIFACTS_INPUT_COMMENTS}} — optional free-text comment for input
- {{AGENT_ARTIFACTS_OUTPUT_COMMENTS}} — optional free-text comment for output
Agent config.yaml files now declare an artifacts block with a dir key
(subdirectory only) and input/output lists. The global ARTIFACTS_DOCS_ROOT
constant (default: docs) is applied at render time; individual agents never
embed the root path.
Output items prefixed with ./ bypass the dir prefix and are used verbatim,
enabling engineer-role paths like src/**/* and tests/**/* to resolve correctly.
The base GenericArtifactGenerator gains a template_partials() hook that
subclasses override to inject per-template placeholder resolvers. AgentGenerator
overrides this hook to drive the artifacts-section rendering.
CommandService is updated to use AgentGenerator for the agent artifact type
so that the custom placeholders are resolved during install.
All six agent config.yaml and template.md files updated. 401 tests, 100%
coverage across py311-py314.
…OCS_ROOT design Update docs/design/agents.md and ADR-021 to match the implemented schema: - Replace target field with dir (subdirectory only, no root prefix) - Document ARTIFACTS_DOCS_ROOT global constant and resolution rules - Add ./ prefix convention for verbatim output paths - Add dict form for output items with optional notes annotation - Document the four generated template tokens: AGENT_ARTIFACTS_INPUT, AGENT_ARTIFACTS_OUTPUT, AGENT_ARTIFACTS_INPUT_COMMENTS, AGENT_ARTIFACTS_OUTPUT_COMMENTS - Update per-role values table with current paths for all six agents - Align canonical template structure section to use artifacts you use - Align minimal shape example to use placeholder tokens
vstack install now writes (or overwrites) .vstack/.gitignore with a generated ignore file that: - Ignores everything under .vstack/ by default (*). - Explicitly un-ignores the three tracked files: .gitignore, config.yaml, and vstack.json. This keeps generated/temporary paths (templates/, tmp/) out of version control automatically without manual .gitignore maintenance. The file is always regenerated on each install so it stays current. Unlike seed files it is never skipped for pre-existing content. Remove the previously hand-placed tmp/.gitignore from the project seed template — the top-level .vstack/.gitignore now covers tmp/ as well. Untrack .vstack/templates/ from git; the new .gitignore excludes it going forward. The files remain on disk but are no longer committed. 7 new tests added. 407 tests, 100% coverage across py311-py314.
Add configurable artifacts root directory so consumers can relocate agent artifact paths from the default 'docs' to any other directory. - AgentGenerator: accept artifacts_root kwarg (default ARTIFACTS_DOCS_ROOT) - CommandService: accept artifacts_root kwarg, forward to AgentGenerator - CommandLineInterface: reorder run() to resolve install_dir before constructing service; add _read_artifacts_root() which reads the value from .vstack/config.yaml and falls back to the constant when absent - .vstack/config.yaml (template + project copy): add commented-out artifacts_root key with explanation - 8 new tests across AgentGenerator, CommandService, CommandLineInterface
Use nested key artifacts: root: instead of the flat artifacts_root: for better structure and consistency with other grouped config keys.
Add exclude: support to .vstack/config.yaml so projects can skip specific artifact types or individual artifact names during generation. - CommandContext gains excluded_names: dict[str, list[str]] | None - CommandLineInterface._read_exclude() parses exclude: from config.yaml; plural config keys (skills, agents, instructions, prompts) are mapped to singular internal type names - Type-level exclusion (exclude: type: all) is applied to effective_only before command dispatch; name-level exclusion is threaded as excluded_names through InitCommand.execute() and InstallCommand.run() - Excluded artifacts are printed with a dim arrow symbol and 'excluded by config' label; they are not written to disk and not recorded in the manifest - Both .vstack/config.yaml files updated with preamble explaining the install vs init flow and when each command should be used - 12 new tests covering _read_exclude edge cases, type exclusion in run(), and name exclusion in execute()
…schema - README: add vstack init to CLI table; add 'install vs init' explanation table; add .vstack/config.yaml section covering exclude: and artifacts: root: with usage examples - README-pypi: sync install vs init distinction and exclude: example - ADR-019: add artifacts: root: to config.yaml schema and update exclude: block with install vs init preamble
- Run vstack init --force to register all 69 artifacts in .vstack/vstack.json - Update generated artifacts to current vstack_version - Remove stale 'future release' placeholder from agent artifacts sections - Normalize Markdown table alignment in rca, postmortem, incident, release-notes skills docs: ADR-022 selective exclude filter docs: rename Option A/B to direct execution / orchestrated pipeline in ADRs 017, 018, 020, 021, 022 docs: split roadmap row into selective install (shipped) and template overlays (candidate)
…to overview - _read_exclude() now raises ValueError with ADR-022 reference when exclude: agents is configured, enforcing the documented constraint that the six-role agent chain cannot be partially excluded - Add test covering the new validation path (428 tests, 100% coverage) - Add ADR-021 and ADR-022 to the decision records table in docs/architecture/overview.md
- Remove Copilot code review support (no installable artifact) - Remove GitHub tasks MCP-first mode (implemented directly in gh-issues skill) - Consolidate 5 Copilot governance items into two new skills: spaces and copilot-admin - Merge template overlays into team customization layer (one item, two aspects) - Add version column to feature table; t.b.d. for candidates, version tags for shipped - Reorder: shipped chronological (v1 -> v3), candidates by priority, not-planned last - Add missing detail sections for v2.1.0 and v3.0.0 shipped items - Update gh-issues skill: MCP-first with gh CLI fallback
…6-05-06 - Update docs/reports/: branch, date, 428 tests, 2058 measured lines, 51 mypy source files; scope extended to cover all v3.0.0 changes - Rename docs/releases/2026-05-04.md -> docs/releases/2026-05-06.md - Expand release notes: What's new (exclude filter, artifacts.root, .gitignore seeding, agent artifacts section), Improvements (ADR-019-022, terminology, roadmap, gh-issues skill), Internal (428 tests, 2058 lines) - Fill Artifacts reviewed table (11 rows) and Sign-offs for all 6 roles - Add CHANGELOG.md v3.0.0 entry (breaking changes, features, docs, tests) - Correct gh-issues checksum in vstack.json after install re-run
Contributor
There was a problem hiding this comment.
Pull request overview
This PR updates vstack’s workflow model and installation layout by introducing a project-scoped .vstack/ directory (with the manifest moved to .vstack/vstack.json), adding an idempotent vstack init command, and generating agent “artifacts you use” sections from structured agent config.
Changes:
- Add
.vstack/as project-scope state/config and relocate the manifest to.vstack/vstack.json. - Introduce
vstack init, plus config-driven install filtering (exclude:) and docs-root override (artifacts.root). - Extend agent generation to inject per-agent artifacts tables; add new
rcaandpostmortemskills; update templates/docs/tests accordingly.
Reviewed changes
Copilot reviewed 128 out of 128 changed files in this pull request and generated 7 comments.
Show a summary per file
| File | Description |
|---|---|
| tests/vstack/test_integration.py | Update manifest-upgrade integration tests to use .vstack/vstack.json. |
| tests/vstack/manifest/test_store.py | Read manifest from .vstack/ in store tests. |
| tests/vstack/cli/test_parser.py | Expect new init subcommand in CLI parser. |
| tests/vstack/cli/test_interface.py | Add tests for reading .vstack/config.yaml (artifacts.root, exclude:) and plumbing into context/service. |
| tests/vstack/cli/test_constants.py | Update expected canonical skill names to include rca and postmortem. |
| tests/vstack/cli/test_catalog.py | Expect init in command catalog. |
| tests/vstack/artifacts/test_generator.py | Add coverage for template_partials() and partial-merging in render. |
| tests/vstack/agents/test_template_structure.py | Update canonical section heading to “## artifacts you use”. |
| tests/vstack/agents/test_role_wiring.py | Enforce forward-handoff policy (release terminal). |
| tests/vstack/agents/test_generation.py | Loosen handoff prompt assertion; verify generated agents include artifacts section and resolve placeholders. |
| src/vstack/constants.py | Add ARTIFACTS_DOCS_ROOT and VSTACK_DIR_NAME. |
| src/vstack/cli/status.py | Update missing-manifest error message for .vstack/vstack.json. |
| src/vstack/cli/service.py | Wire AgentGenerator and relocate manifest resolution to .vstack/ for project installs. |
| src/vstack/cli/parser.py | Add init subcommand and flags. |
| src/vstack/cli/interface.py | Read .vstack/config.yaml for exclude: and artifacts.root; pass excluded_names via CommandContext. |
| src/vstack/cli/constants.py | Add rca and postmortem to canonical skill list. |
| src/vstack/cli/catalog.py | Register init command and update install help text/semantics. |
| src/vstack/cli/base.py | Extend CommandContext with excluded_names. |
| src/vstack/artifacts/generator.py | Add per-template partial injection (template_partials) and merge with global partials during render. |
| src/vstack/agents/generator.py | Implement agent-specific placeholder injection for artifacts tables/notes. |
| src/vstack/_templates/skills/vision/template.md | Remove delta-workflow language; tighten deliverable guidance. |
| src/vstack/_templates/skills/verify/template.md | Move reports under docs/reports/; remove delta-workflow language. |
| src/vstack/_templates/skills/threat-model/template.md | Make output path role-owned/agent-decided; adjust evidence file search. |
| src/vstack/_templates/skills/security/template.md | Move security report under docs/reports/; remove delta-workflow language. |
| src/vstack/_templates/skills/requirements/template.md | Remove delta-workflow language. |
| src/vstack/_templates/skills/release-notes/template.md | Make evidence checks path-agnostic; add explicit file-existence check snippet. |
| src/vstack/_templates/skills/rca/template.md | Add new RCA skill template. |
| src/vstack/_templates/skills/rca/config.yaml | Add RCA skill metadata/config. |
| src/vstack/_templates/skills/postmortem/template.md | Add new postmortem skill template. |
| src/vstack/_templates/skills/postmortem/config.yaml | Add postmortem skill metadata/config. |
| src/vstack/_templates/skills/performance/template.md | Move perf baseline under docs/reports/; remove delta-workflow language. |
| src/vstack/_templates/skills/onboard/template.md | Update architecture link to docs/architecture/overview.md. |
| src/vstack/_templates/skills/inspect/template.md | Move test report under docs/reports/; remove delta-workflow language. |
| src/vstack/_templates/skills/incident/template.md | Reframe incident skill as coordination; delegate writing to rca/postmortem. |
| src/vstack/_templates/skills/incident/config.yaml | Update incident skill description/version/argument-hint to match new behavior. |
| src/vstack/_templates/skills/gh-issues/template.md | Prefer MCP tools first; fall back to gh CLI. |
| src/vstack/_templates/skills/docs/template.md | Remove delta-workflow language. |
| src/vstack/_templates/skills/design/template.md | Rename primary design deliverable to docs/design/overview.md; remove delta-workflow language. |
| src/vstack/_templates/skills/cicd/template.md | Update architecture doc reference to docs/architecture/overview.md. |
| src/vstack/_templates/skills/architecture/template.md | Rename primary architecture deliverable to docs/architecture/overview.md; remove delta-workflow language. |
| src/vstack/_templates/skills/adr/template.md | Update architecture doc reference to docs/architecture/overview.md. |
| src/vstack/_templates/project/.vstack/config.yaml | Add seed template for project .vstack/config.yaml with exclude and artifacts.root examples. |
| src/vstack/_templates/agents/tester/template.md | Replace “artifacts you own” section with generated artifacts placeholders and updated workflow text. |
| src/vstack/_templates/agents/tester/config.yaml | Add artifacts: block (dir/input/output) and update handoff policy. |
| src/vstack/_templates/agents/tester/artifacts/test-report.md | Add seeded report stub under tester artifacts. |
| src/vstack/_templates/agents/tester/artifacts/security-report.md | Add seeded report stub under tester artifacts. |
| src/vstack/_templates/agents/tester/artifacts/performance-baseline.md | Add seeded perf baseline stub under tester artifacts. |
| src/vstack/_templates/agents/release/template.md | Update sign-off model, artifacts section placeholders, and handoff policy (release terminal). |
| src/vstack/_templates/agents/release/config.yaml | Add artifacts: block and remove release handoffs. |
| src/vstack/_templates/agents/release/artifacts/release-summary.md | Add seeded release summary/sign-off record stub. |
| src/vstack/_templates/agents/product/template.md | Update handoff policy and switch to generated artifacts placeholders. |
| src/vstack/_templates/agents/product/config.yaml | Add artifacts: block and update handoff prompt text. |
| src/vstack/_templates/agents/product/artifacts/vision.md | Add seeded product vision stub. |
| src/vstack/_templates/agents/product/artifacts/roadmap.md | Add seeded product roadmap stub. |
| src/vstack/_templates/agents/product/artifacts/requirements.md | Add seeded product requirements stub. |
| src/vstack/_templates/agents/product/artifacts/issues/issue.md | Add seeded issue template stub. |
| src/vstack/_templates/agents/product/artifacts/changes/change-request.md | Add seeded change-request template stub. |
| src/vstack/_templates/agents/engineer/template.md | Update workflow text, add “assess current state”, and switch to generated artifacts placeholders. |
| src/vstack/_templates/agents/engineer/config.yaml | Add artifacts: output entries for code/tests/issues templates; update handoff prompt. |
| src/vstack/_templates/agents/engineer/artifacts/issues/rca.md | Add seeded issue RCA stub. |
| src/vstack/_templates/agents/engineer/artifacts/issues/postmortem.md | Add seeded issue postmortem stub. |
| src/vstack/_templates/agents/designer/template.md | Update references to architecture/design overview and switch to generated artifacts placeholders. |
| src/vstack/_templates/agents/designer/config.yaml | Add artifacts: block for design outputs and update handoff prompt. |
| src/vstack/_templates/agents/designer/artifacts/overview.md | Add seeded design overview stub. |
| src/vstack/_templates/agents/architect/template.md | Update workflow text to use architecture overview and generated artifacts placeholders. |
| src/vstack/_templates/agents/architect/config.yaml | Add artifacts: block for architecture outputs and update handoff prompt. |
| src/vstack/_templates/agents/architect/artifacts/overview.md | Add seeded architecture overview stub. |
| src/vstack/_templates/agents/architect/artifacts/adr/NNN-template.md | Add seeded ADR template stub. |
| README.md | Document install/init split, .vstack/ manifest path, and config options; update links. |
| README-pypi.md | Add install/init overview and config snippet for PyPI docs. |
| docs/reports/test-report.md | Update verification report for this PR’s scope and new report paths. |
| docs/reports/security-report.md | Update security report header/scope for this PR. |
| docs/reports/performance-baseline.md | Update perf baseline header/scope for this PR. |
| docs/releases/2026-05-06.md | Add release notes for v3.0.0 workflow/config changes. |
| docs/releases/2026-04-26.md | Update artifact path references to new overview/report locations. |
| docs/design/skills.md | Update skill deliverables/paths for overview/report changes. |
| docs/design/overview.md | Update architecture doc reference and add schema cross-links. |
| docs/design/agents.md | Document new artifacts: schema and handoff policy. |
| docs/architecture/overview.md | Update repo layout, manifest location, CLI component list, and pipeline/gate model. |
| docs/architecture/adr/022-selective-exclude-filter.md | Add ADR for config-driven exclude behavior. |
| docs/architecture/adr/021-config-driven-artifact-paths.md | Add ADR for agent artifacts: block and path resolution. |
| docs/architecture/adr/020-install-init-command-semantics.md | Add ADR defining install vs init responsibilities. |
| docs/architecture/adr/019-vstack-project-directory.md | Add ADR introducing .vstack/ directory and ownership rules. |
| docs/architecture/adr/018-skill-genericity-boundary.md | Update ADR status/wording and references to new report paths/terminology. |
| docs/architecture/adr/017-checksum-backfill-on-upgrade.md | Update wording around orchestrated pipeline terminology. |
| docs/architecture/adr/015-conservative-install-by-default.md | Mark ADR as superseded by ADR-020. |
| docs/architecture/adr/014-manifest-schema-versioning.md | Document new manifest file location and migration path. |
| docs/architecture/adr/012-flat-templates-install-time-generation.md | Update doc for two-command install/init model and new template dirs. |
| docs/architecture/adr/010-artifact-flow.md | Update artifact flow to stage-gated model, happy-path handoffs, and sign-off consolidation. |
| docs/architecture/adr/009-role-model.md | Convert role table to per-role lists; add RCA/postmortem ownership notes and ADR-021 reference. |
| .vstack/config.yaml | Add repo’s seeded project config file. |
| .vstack/.gitignore | Add .vstack ignore rules. |
| .markdownlint.yaml | Disable MD012 to accommodate CHANGELOG formatting. |
| .github/skills/vision/SKILL.md | Regenerate installed skill artifact from updated template. |
| .github/skills/verify/SKILL.md | Regenerate installed skill artifact from updated template. |
| .github/skills/threat-model/SKILL.md | Regenerate installed skill artifact from updated template. |
| .github/skills/security/SKILL.md | Regenerate installed skill artifact from updated template. |
| .github/skills/requirements/SKILL.md | Regenerate installed skill artifact from updated template. |
| .github/skills/release-notes/SKILL.md | Regenerate installed skill artifact from updated template. |
| .github/skills/rca/SKILL.md | Add generated installed RCA skill artifact. |
| .github/skills/postmortem/SKILL.md | Add generated installed postmortem skill artifact. |
| .github/skills/performance/SKILL.md | Regenerate installed skill artifact from updated template. |
| .github/skills/onboard/SKILL.md | Regenerate installed skill artifact from updated template. |
| .github/skills/inspect/SKILL.md | Regenerate installed skill artifact from updated template. |
| .github/skills/incident/SKILL.md | Regenerate installed skill artifact from updated template. |
| .github/skills/gh-issues/SKILL.md | Regenerate installed skill artifact from updated template. |
| .github/skills/docs/SKILL.md | Regenerate installed skill artifact from updated template. |
| .github/skills/design/SKILL.md | Regenerate installed skill artifact from updated template. |
| .github/skills/cicd/SKILL.md | Regenerate installed skill artifact from updated template. |
| .github/skills/architecture/SKILL.md | Regenerate installed skill artifact from updated template. |
| .github/skills/adr/SKILL.md | Regenerate installed skill artifact from updated template. |
| .github/copilot-instructions.md | Update repo structure pointers to new overview/docs locations and .vstack/. |
| .github/agents/tester.agent.md | Regenerate installed tester agent with artifacts section injection and updated handoff policy. |
| .github/agents/release.agent.md | Regenerate installed release agent with artifacts section injection and updated policy. |
| .github/agents/product.agent.md | Regenerate installed product agent with artifacts section injection and updated policy. |
| .github/agents/engineer.agent.md | Regenerate installed engineer agent with artifacts section injection and updated policy. |
| .github/agents/designer.agent.md | Regenerate installed designer agent with artifacts section injection and updated policy. |
| .github/agents/architect.agent.md | Regenerate installed architect agent with artifacts section injection and updated policy. |
Comments suppressed due to low confidence (1)
docs/architecture/overview.md:101
- This role-ownership table lists
docs/releases/YYYYMMDDNN.md, but the release docs added/updated in this PR usedocs/releases/YYYY-MM-DD.md(e.g.2026-05-06.md). Please make the naming convention consistent across docs and the actual release files/templates.
- constants.py: update ARTIFACTS_DOCS_ROOT comment; override is available now via artifacts.root in .vstack/config.yaml - agents/generator.py: fix docstring — artifacts_root: -> artifacts.root - cli/service.py: fix docstring — artifacts_root: -> artifacts.root - cli/install.py: fix .vstack/.gitignore content; ignore only tmp/ instead of everything; templates/ is project-owned and must be committed (ADR-019) - tests/test_install.py: align gitignore assertions with new content - docs/design/agents.md: update ARTIFACTS_DOCS_ROOT note; override is current behavior, not a future release - docs/design/skills.md: fix release-notes output path; YYYY-MM-DD.md not YYYYMMDDNN.md - README-pypi.md: update vstack.json reference to .vstack/vstack.json - .vstack/.gitignore: regenerate with new content (tmp/ only)
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
vstack 3.0.0 is a breaking release that introduces a dedicated
.vstack/project-scopedirectory, splits the
install/initcommand semantics, relocates the install manifest,and delivers a comprehensive set of config-driven install controls. All six agent templates
and fifteen skill templates have been regenerated. The test suite expands from 373 to 428
tests at 100% statement coverage across py311–py314.
Breaking changes
vstack.jsonmoves from.github/vstack.jsonto.vstack/vstack.json.Run
vstack manifest upgradeto migrate. Any CI step or tooling that reads.github/vstack.jsondirectly must be updated.
vstack install/vstack initsemantics split:installis now first-run projectsetup (run once);
initis the idempotent regeneration command for CI pipelines andpip install --upgradeworkflows. CI pipelines must switch fromvstack installtovstack init..vstack/directory introduced:vstack installcreates.vstack/on first run,seeding
config.yaml,vstack.json, and role-scoped doc templates (ADR-019).New features
exclude:filter (ADR-022): per-type and per-name exclusion via.vstack/config.yaml. Agents cannot be excluded.artifacts.rootoverride (ADR-021): projects with non-standard doc roots setartifacts: root: <path>in.vstack/config.yaml..vstack/.gitignoreseeded on every run: always written astmp/only —templates/and other project-owned files are now correctly tracked by Git.artifacts:section generated fromconfig.yaml(ADR-021): resolves{{AGENT_ARTIFACTS_INPUT}}/{{AGENT_ARTIFACTS_OUTPUT}}tokens at install time.@architect/@designerwithout triggering a full gate cycle.ghCLI as fallback.Architecture decisions added
ADR-019 (
.vstack/project directory), ADR-020 (install/init semantics), ADR-021 (config-driven artifact paths), ADR-022 (selective exclude filter) — all accepted.Documentation and improvements
copilot-admin+spaces.docs/delta/concept fully removed from all agent and skill templates.Verification
Why
The
install/initsplit and.vstack/directory resolve the ambiguity betweenfirst-time setup and CI regeneration. The
exclude:filter andartifacts.rootoverrideaddress the two most common adoption friction points without requiring repeated CLI flags.
Version impact