Feature/workflow dag validation - #55
Merged
Merged
Conversation
Each role agent now documents when and how it may fan out to subagents or same-role variants within a single turn. Rules cover valid split candidates, merge requirements, and audit obligations. - architect: separate ADRs, failure-mode analyses, boundary decisions - product: vision, requirements, roadmap, release-scope analysis - designer: API contracts, event schemas, state models, module boundaries - engineer: fullstack/integration styles (existing), boundary clarified - tester: security, performance, functional correctness, compatibility - release: baseline checks, artifact validation, role-perspective reviews - planner: fan-out orchestration and variant invocation policy Updated agent-skill-boundary partial with subagent constraint. Aligned ADR-029 and workflow.md with generalised self-decomposition rule.
Sets the canonical DAG for new and existing vstack projects: product → architect, designer (parallel) architect + designer → engineer engineer → tester tester → release Applied to: - src/vstack/_templates/project/.vstack/config.yaml (seeded template) - .vstack/config.yaml (this project's own config) - .vstack/vstack.json (manifest checksum update) - .github/** (regenerated artifacts)
Add _nearest_semver_tag() using 'git describe --tags --abbrev=0' as an intermediate resolution step between the exact-HEAD tag check and the importlib.metadata fallback. Resolution order is now: 1. Exact semver tag at HEAD (release commits in source checkout) 2. Nearest reachable semver tag via git describe (dev branches) 3. importlib.metadata (built distributions via pip install) 4. Hard-coded '0.0.0' (shallow clones, untagged, no metadata) poetry-dynamic-versioning only writes the version at build time and does not update editable installs, so 'git describe' is the only reliable source in development environments. Added 4 new tests; updated 3 existing resolve-version tests to also stub _nearest_semver_tag.
README and README-pypi now document: - depends_on as the mechanism for parallel stage execution - The canonical six-role DAG seeded by vstack install - Planner as the primary entry point in agentic mode - What planner does at runtime (stages, depends_on, hitl, parallel branches) - Valid role names planner can invoke
Planner now fully understands the dependency graph: - Evaluates depends_on before each stage; a stage is ready when all its predecessors are ready or skipped - Runs all ready stages before advancing past a gate boundary - Invokes independent branches in parallel - Treats missing depends_on as implicit dependency on the previous stage - Treats depends_on: [] as an explicit root stage Updated: responsibilities, working principles, execution model, success criteria, and completion checklist. The generated .github/agents/planner.agent.md is regenerated accordingly.
Adds a copy/paste planner runbook (5 prompts) and an explicit troubleshooting section for cases where planner does not run stages in parallel. Covers concrete checks for workflow.mode, depends_on semantics, validation, optional-stage skips, blockers, hybrid mixed-path usage, and planner entry-point usage.
Regenerated managed .github artifacts to update VSTACK-META footer version fields from 0.0.0 to 3.2.0.
Contributor
There was a problem hiding this comment.
Pull request overview
This PR tightens workflow DAG handling by validating workflow.stages[*].depends_on during parsing and stage-graph validation, updating handoff resolution to be DAG-aware, and aligning docs/templates with the current planner + DAG semantics. It also improves runtime version resolution in source checkouts by falling back to the nearest reachable SemVer tag when HEAD is untagged.
Changes:
- Add strict parsing + validation for
depends_on(reject scalars/mixed types, validate references/self-deps/duplicates, detect cycles) and make worker handoff resolution follow DAG dependents. - Add regression tests covering depends_on parsing/validation and DAG handoff fallback behavior.
- Update templates + docs (README/ADR/design/roadmap/test report) to reflect DAG semantics and parallel delegation guidance; regenerate installed
.github/artifacts and update manifest.
Reviewed changes
Copilot reviewed 98 out of 98 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| tests/vstack/test_constants.py | Adds coverage for nearest reachable SemVer tag lookup and version resolution order. |
| tests/vstack/cli/test_interface.py | Adds tests for depends_on parsing failures, role validation, unknown targets, and cycle detection. |
| tests/vstack/agents/test_generator.py | Adds tests for DAG-aware fallback handoffs and implicit-target selection. |
| src/vstack/constants.py | Adds _nearest_semver_tag() and updates version resolution to use it before package metadata. |
| src/vstack/cli/interface.py | Normalizes roles, parses/normalizes depends_on, and validates a DAG-safe workflow graph. |
| src/vstack/agents/generator.py | Makes handoff resolution depend on DAG dependents (branching + primary dependent semantics). |
| src/vstack/_templates/project/.vstack/config.yaml | Updates the seeded project config comments + example stages to include depends_on. |
| src/vstack/_templates/agents/tester/template.md | Adds parallel delegation guidance to the tester role template. |
| src/vstack/_templates/agents/release/template.md | Adds parallel delegation guidance to the release role template. |
| src/vstack/_templates/agents/product/template.md | Adds parallel delegation guidance to the product role template. |
| src/vstack/_templates/agents/planner/template.md | Updates planner responsibilities/flow for DAG readiness + parallel orchestration guidance. |
| src/vstack/_templates/agents/designer/template.md | Adds parallel delegation guidance to the designer role template. |
| src/vstack/_templates/agents/architect/template.md | Adds parallel delegation guidance to the architect role template. |
| src/vstack/_templates/agents/_partials/agent-skill-boundary.md | Clarifies “subagents” as scoped parallel work with a required merge point. |
| README.md | Documents depends_on DAG semantics, planner parallelism expectations, and updated runbook guidance. |
| README-pypi.md | Updates PyPI README workflow section to mention DAG semantics and planner-first usage. |
| docs/reports/test-report.md | Updates the test report to reflect current branch scope and results. |
| docs/product/vision.md | Updates vision text to reflect current planner/DAG orchestration reality. |
| docs/product/roadmap.md | Updates roadmap feature status language and DAG milestone framing. |
| docs/product/requirements.md | Updates requirements to reflect 42-skill set, PyYAML dependency, and adds DAG semantics FR. |
| docs/design/workflow.md | Documents depends_on semantics, branching handoff behavior, and references new ADRs. |
| docs/design/agents.md | Documents planner DAG awareness and updates the agent generation overview diagram. |
| docs/architecture/overview.md | Adds explicit workflow dependency semantics and updates ADR index to include ADR-028/029. |
| docs/architecture/adr/029-multi-agentic-execution-model.md | New ADR selecting DAG as the primary coordination model and explaining alternatives. |
| docs/architecture/adr/028-dag-dependency-semantics.md | New ADR specifying depends_on semantics, validation rules, and backward compatibility. |
| CHANGELOG.md | Formats existing 3.2.0 entries as consistent Markdown lists. |
| .vstack/vstack.json | Updates installed manifest metadata (vstack version, timestamps, checksums) after regeneration. |
| .vstack/config.yaml | Updates repo config workflow stages to include explicit depends_on DAG. |
| .github/skills/vision/SKILL.md | Regenerated installed skill artifact metadata for vstack 3.2.0. |
| .github/skills/verify/SKILL.md | Regenerated installed skill artifact metadata for vstack 3.2.0. |
| .github/skills/threat-model/SKILL.md | Regenerated installed skill artifact metadata for vstack 3.2.0. |
| .github/skills/terragrunt/SKILL.md | Regenerated installed skill artifact metadata for vstack 3.2.0. |
| .github/skills/terraform/SKILL.md | Regenerated installed skill artifact metadata for vstack 3.2.0. |
| .github/skills/security/SKILL.md | Regenerated installed skill artifact metadata for vstack 3.2.0. |
| .github/skills/secret-scan/SKILL.md | Regenerated installed skill artifact metadata for vstack 3.2.0. |
| .github/skills/requirements/SKILL.md | Regenerated installed skill artifact metadata for vstack 3.2.0. |
| .github/skills/release-notes/SKILL.md | Regenerated installed skill artifact metadata for vstack 3.2.0. |
| .github/skills/refactor/SKILL.md | Regenerated installed skill artifact metadata for vstack 3.2.0. |
| .github/skills/rca/SKILL.md | Regenerated installed skill artifact metadata for vstack 3.2.0. |
| .github/skills/rancher/SKILL.md | Regenerated installed skill artifact metadata for vstack 3.2.0. |
| .github/skills/pr/SKILL.md | Regenerated installed skill artifact metadata for vstack 3.2.0. |
| .github/skills/postmortem/SKILL.md | Regenerated installed skill artifact metadata for vstack 3.2.0. |
| .github/skills/performance/SKILL.md | Regenerated installed skill artifact metadata for vstack 3.2.0. |
| .github/skills/openapi/SKILL.md | Regenerated installed skill artifact metadata for vstack 3.2.0. |
| .github/skills/onboard/SKILL.md | Regenerated installed skill artifact metadata for vstack 3.2.0. |
| .github/skills/migrate/SKILL.md | Regenerated installed skill artifact metadata for vstack 3.2.0. |
| .github/skills/k8s/SKILL.md | Regenerated installed skill artifact metadata for vstack 3.2.0. |
| .github/skills/inspect/SKILL.md | Regenerated installed skill artifact metadata for vstack 3.2.0. |
| .github/skills/incident/SKILL.md | Regenerated installed skill artifact metadata for vstack 3.2.0. |
| .github/skills/helm/SKILL.md | Regenerated installed skill artifact metadata for vstack 3.2.0. |
| .github/skills/guardrails/SKILL.md | Regenerated installed skill artifact metadata for vstack 3.2.0. |
| .github/skills/gh-release/SKILL.md | Regenerated installed skill artifact metadata for vstack 3.2.0. |
| .github/skills/gh-issues/SKILL.md | Regenerated installed skill artifact metadata for vstack 3.2.0. |
| .github/skills/gdpr/SKILL.md | Regenerated installed skill artifact metadata for vstack 3.2.0. |
| .github/skills/explore/SKILL.md | Regenerated installed skill artifact metadata for vstack 3.2.0. |
| .github/skills/docs/SKILL.md | Regenerated installed skill artifact metadata for vstack 3.2.0. |
| .github/skills/design/SKILL.md | Regenerated installed skill artifact metadata for vstack 3.2.0. |
| .github/skills/dependency/SKILL.md | Regenerated installed skill artifact metadata for vstack 3.2.0. |
| .github/skills/dependabot/SKILL.md | Regenerated installed skill artifact metadata for vstack 3.2.0. |
| .github/skills/debug/SKILL.md | Regenerated installed skill artifact metadata for vstack 3.2.0. |
| .github/skills/conventional-commit/SKILL.md | Regenerated installed skill artifact metadata for vstack 3.2.0. |
| .github/skills/container/SKILL.md | Regenerated installed skill artifact metadata for vstack 3.2.0. |
| .github/skills/consult/SKILL.md | Regenerated installed skill artifact metadata for vstack 3.2.0. |
| .github/skills/concise/SKILL.md | Regenerated installed skill artifact metadata for vstack 3.2.0. |
| .github/skills/codeql/SKILL.md | Regenerated installed skill artifact metadata for vstack 3.2.0. |
| .github/skills/code-review/SKILL.md | Regenerated installed skill artifact metadata for vstack 3.2.0. |
| .github/skills/cloudformation/SKILL.md | Regenerated installed skill artifact metadata for vstack 3.2.0. |
| .github/skills/cicd/SKILL.md | Regenerated installed skill artifact metadata for vstack 3.2.0. |
| .github/skills/aws-cli/SKILL.md | Regenerated installed skill artifact metadata for vstack 3.2.0. |
| .github/skills/architecture/SKILL.md | Regenerated installed skill artifact metadata for vstack 3.2.0. |
| .github/skills/analyse/SKILL.md | Regenerated installed skill artifact metadata for vstack 3.2.0. |
| .github/skills/adr/SKILL.md | Regenerated installed skill artifact metadata for vstack 3.2.0. |
| .github/prompts/release-readiness.prompt.md | Regenerated installed prompt artifact metadata for vstack 3.2.0. |
| .github/prompts/migration-safety.prompt.md | Regenerated installed prompt artifact metadata for vstack 3.2.0. |
| .github/prompts/incident-timeline.prompt.md | Regenerated installed prompt artifact metadata for vstack 3.2.0. |
| .github/prompts/dependency-audit.prompt.md | Regenerated installed prompt artifact metadata for vstack 3.2.0. |
| .github/prompts/code-review.prompt.md | Regenerated installed prompt artifact metadata for vstack 3.2.0. |
| .github/prompts/architecture-risk.prompt.md | Regenerated installed prompt artifact metadata for vstack 3.2.0. |
| .github/prompts/api-design-review.prompt.md | Regenerated installed prompt artifact metadata for vstack 3.2.0. |
| .github/instructions/typescript.instructions.md | Regenerated installed instruction artifact metadata for vstack 3.2.0. |
| .github/instructions/testing.instructions.md | Regenerated installed instruction artifact metadata for vstack 3.2.0. |
| .github/instructions/terragrunt.instructions.md | Regenerated installed instruction artifact metadata for vstack 3.2.0. |
| .github/instructions/terraform.instructions.md | Regenerated installed instruction artifact metadata for vstack 3.2.0. |
| .github/instructions/security.instructions.md | Regenerated installed instruction artifact metadata for vstack 3.2.0. |
| .github/instructions/rancher.instructions.md | Regenerated installed instruction artifact metadata for vstack 3.2.0. |
| .github/instructions/python.instructions.md | Regenerated installed instruction artifact metadata for vstack 3.2.0. |
| .github/instructions/markdown.instructions.md | Regenerated installed instruction artifact metadata for vstack 3.2.0. |
| .github/instructions/k8s.instructions.md | Regenerated installed instruction artifact metadata for vstack 3.2.0. |
| .github/instructions/java.instructions.md | Regenerated installed instruction artifact metadata for vstack 3.2.0. |
| .github/instructions/helm.instructions.md | Regenerated installed instruction artifact metadata for vstack 3.2.0. |
| .github/instructions/git.instructions.md | Regenerated installed instruction artifact metadata for vstack 3.2.0. |
| .github/agents/tester.agent.md | Regenerated installed agent artifact metadata and content from updated templates. |
| .github/agents/release.agent.md | Regenerated installed agent artifact metadata and content from updated templates. |
| .github/agents/product.agent.md | Regenerated installed agent artifact metadata and content from updated templates. |
| .github/agents/planner.agent.md | Regenerated installed planner agent artifact to reflect DAG + parallel orchestration guidance. |
| .github/agents/engineer.agent.md | Regenerated installed agent artifact (subagent boundary guidance). |
| .github/agents/designer.agent.md | Regenerated installed agent artifact metadata and content from updated templates. |
| .github/agents/architect.agent.md | Regenerated installed agent artifact metadata and content from updated templates. |
Comments suppressed due to low confidence (2)
README.md:627
- This section says that when
handoffs.agentis omitted the target defaults to the next role inworkflow.stages, but the updated generator behavior is DAG-aware and defaults to the primary downstream dependent role (based ondepends_on/ sequential fallback). Please update these bullets to match the current handoff resolution semantics, especially for branching DAGs.
README-pypi.md:271 - This section says that when
handoffs.agentis omitted the target defaults to the next role inworkflow.stages, but the updated generator behavior is DAG-aware and defaults to the primary downstream dependent role (based ondepends_on/ sequential fallback). Please update these bullets so the PyPI README matches the shipped behavior.
eschaar
force-pushed
the
feature/workflow-dag-validation
branch
from
May 12, 2026 22:33
5ddb81c to
4bee54f
Compare
Clarify that IntelliJ and other IDE support is a later major update, not a near-term roadmap item. The roadmap now explains the rationale: VS Code-first focus, added maintenance burden, IDE-specific schemas, more breaking-change surface, and uncertainty in the AI tooling market.
Reorder the feature status table to follow the release tags: - v3.1.0: workflow contract source-of-truth - v3.2.0: agent hooks support and optional orchestrated role pipeline - v3.3.0: DAG workflow model Also fill in the shipped version numbers for the affected section headings so the roadmap stays aligned with the git-tag-based release history.
eschaar
force-pushed
the
feature/workflow-dag-validation
branch
from
May 12, 2026 22:51
6e2f29b to
e970a5e
Compare
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
workflow.stages[*].depends_onvalues during workflow parsing and validation.depends_oninputs.Why
depends_oninputs were previously treated too leniently, which could hide workflow configuration errors.Version impact