feat(agents): upgrade ADR Planner with phased identity and adr-author skill#1554
feat(agents): upgrade ADR Planner with phased identity and adr-author skill#1554WilliamBerryiii wants to merge 11 commits into
Conversation
- add ADR consistency module, parser, CLI, rules JSON, schemas, and Pester tests - register schemas, markdownlint excludes, and 'templates' skill subdirectory - wire lint:adr-consistency npm script (excluded from lint:all) - extend cspell and frontmatter validator excludes; regenerate plugin outputs 🔍 - Generated by Copilot
WilliamBerryiii
force-pushed
the
feat/adr-planner-upgrade-v2
branch
from
ce3e49f to
79d8cd7
Compare
Dependency Review✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.OpenSSF ScorecardScorecard details
Scanned Files
|
![github-advanced-security[bot]](https://avatars.githubusercontent.com/in/57789?s=60&v=4){kind=small}
WilliamBerryiii
force-pushed
the
feat/adr-planner-upgrade-v2
branch
3 times, most recently
from
37fc46c to
827dc82
Compare
… skill - add adr-author skill with MADR v4 templates, scripts, tests - add ADR identity, standards, handoff, BYO template instructions - restructure ADR Planner into Frame/Decide/Govern phases - update peer planners and shared disclaimer for handoff - regenerate collection/plugin manifests; wire lint:adr-consistency 🚀 - Generated by Copilot
WilliamBerryiii
force-pushed
the
feat/adr-planner-upgrade-v2
branch
from
827dc82 to
6490a04
Compare
katriendg
left a comment
katriendg
left a comment
There was a problem hiding this comment.
Thanks for this thorough restructure! The phased Frame → Decide → Govern architecture is well-designed, and the alignment with peer planners is solid. Python scripts have proper path-traversal guards, the pyproject.toml meets all Coding Agent Environment requirements (ruff, pytest, fuzz harness, fuzz dependency group), and the atomic supersession lineage handling is clean.
A few prompt-builder convention and distribution portability items noted inline — mostly frontmatter alignment and replacing .github/ repo-root-relative paths with relative or semantic references so the artifacts resolve correctly when distributed via Extension or Plugin.
| handoffs: | ||
| - .github/agents/hve-core/task-planner.agent.md | ||
| - .github/agents/rai-planning/rai-planner.agent.md | ||
| - .github/agents/security/security-planner.agent.md |
There was a problem hiding this comment.
Prompt-builder frontmatter alignment (RI-01 through RI-06)
Several fields diverge from the conventions in prompt-builder.instructions.md and from peer planners (Security, RAI, SSSC):
-
name: ADR Creator— The H1 says# ADR Plannerandadr-identity.instructions.mdnames it "ADR Planner". Suggest aligning toADR Planner. -
description:— Attribution suffix should be- Brought to you by microsoft/hve-core(dash prefix, no trailing period). -
tools:— Uses legacy names (edit,search,runCommands, etc.). Peer planners use the newer granular names (read,edit/createFile,edit/editFiles,execute/runInTerminal,search,web,agent). -
agents:— Should use the human-readable name from the subagent’sname:frontmatter, not a glob path. All peer planners use- Researcher Subagent. -
handoffs:— Should use structured objects withlabel,agent, and optionallyprompt/send— not bare file paths. See RAI Planner and SSSC Planner for the pattern.
Suggested:
name: ADR Planner
description: 'ADR Planner: phase-gated planner producing standards-aligned Architecture Decision Records (Frame, Decide, Govern) - Brought to you by microsoft/hve-core'
tools:
- read
- edit/createFile
- edit/editFiles
- execute/runInTerminal
- search
- web
- agent
agents:
- Researcher Subagent
handoffs:
- label: "Task Planner"
agent: Task Planner
- label: "RAI Planner"
agent: RAI Planner
- label: "Security Planner"
agent: Security PlannerThere was a problem hiding this comment.
Thanks for the review. Item-by-item:
RI-01 (name → "ADR Planner") — Declined. Canonical name is "ADR Creator" across the codebase: H1 and name: line of .github/instructions/project-planning/adr-identity.instructions.md, this agent's H1, the Handoff Peers table in .github/instructions/project-planning/adr-handoff.instructions.md, .github/skills/project-planning/adr-author/SKILL.md, and ~20 other references. "ADR Planner" doesn't appear anywhere — happy to revisit if you can point at the source.
RI-02 (description suffix) — Applied. handoff. Brought to you by microsoft/hve-core. → handoff - Brought to you by microsoft/hve-core (dash prefix, no trailing period).
RI-03 (tools granular) — Already satisfied before this review (commit 8573a30d). Current frontmatter: read, edit/createFile, edit/createDirectory, edit/editFiles, execute/runInTerminal, execute/getTerminalOutput, search, web, agent. No legacy names remain.
RI-04 (agents human-readable) — Already satisfied: agents: - Researcher Subagent. No glob path present.
RI-05 (structured handoffs) — Applied. Added handoffs: frontmatter for the three documented Govern-phase peers (Task Planner, RAI Planner, Security Planner) per the Handoff Peers table in adr-handoff.instructions.md. Frontmatter declares availability; body text retains the instruction-driven language because dispatch is conditional on Govern-phase findings.
There was a problem hiding this comment.
Thanks for the review. Item-by-item:
RI-01 (name → "ADR Planner") — Declined. Canonical name is "ADR Creator" across the codebase: H1 and name: line of .github/instructions/project-planning/adr-identity.instructions.md, this agent's H1, the Handoff Peers table in .github/instructions/project-planning/adr-handoff.instructions.md, .github/skills/project-planning/adr-author/SKILL.md, and ~20 other references. "ADR Planner" doesn't appear anywhere — happy to revisit if you can point at the source.
RI-02 (description suffix) — Applied. handoff. Brought to you by microsoft/hve-core. → handoff - Brought to you by microsoft/hve-core (dash prefix, no trailing period).
RI-03 (tools granular) — Already satisfied before this review (commit 8573a30d). Current frontmatter: read, edit/createFile, edit/createDirectory, edit/editFiles, execute/runInTerminal, execute/getTerminalOutput, search, web, agent. No legacy names remain.
RI-04 (agents human-readable) — Already satisfied: agents: - Researcher Subagent. No glob path present.
RI-05 (structured handoffs) — Applied. Added handoffs: frontmatter for the three documented Govern-phase peers (Task Planner, RAI Planner, Security Planner) per the Handoff Peers table in adr-handoff.instructions.md. Frontmatter declares availability; body text retains the instruction-driven language because dispatch is conditional on Govern-phase findings.
…EADME Satisfies lint:frontmatter standard-footer check for the ADR Author fuzz corpus seed README, matching the pattern used in sibling skill corpora.
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
There was a problem hiding this comment.
Dependency Review
New Python Skill: adr-author (pyproject.toml)
All newly introduced Python dependencies were reviewed against the four dependency review dimensions.
New Dependencies
| Dependency | Group | Pinning | License | Assessment |
|---|---|---|---|---|
pyyaml>=6 |
runtime | floor-pinned | MIT | ✅ Widely used, actively maintained, no known CVEs at v6+. No existing YAML library in the repo skill surface to duplicate. |
jsonschema>=4 |
runtime | floor-pinned | MIT | ✅ Widely used, actively maintained. No existing JSON Schema library in the skill surface. |
ruff>=0.6 |
dev | floor-pinned | MIT | ✅ Already the repo-wide Python linter (npm run lint:py). Consistent choice. |
pytest>=8 |
dev | floor-pinned | MIT | ✅ Standard test framework, consistent with other Python skills in the repo. |
pytest-mock>=3 |
dev | floor-pinned | MIT | ✅ Standard mocking extension. |
pytest-cov>=5 |
dev | floor-pinned | MIT | ✅ Standard coverage extension. |
atheris>=3.0 |
fuzz (isolated) | floor-pinned | Apache-2.0 | ✅ Apache-2.0 is compatible with the project's MIT license. Correctly isolated in a separate fuzz dependency group (not installed by default, manylinux-only wheels excluded from macOS as noted). |
All runtime and dev licenses are MIT-compatible. No dependency duplicates existing skill functionality. No new top-level package.json runtime or dev dependencies were introduced.
Version Updates
No existing dependencies were bumped in this PR.
SHA Pinning Compliance
No GitHub Actions workflow files, .devcontainer/ files, or copilot-setup-steps.yml were modified by this PR. SHA pinning compliance is not in scope for this change.
Devcontainer / Setup Alignment
No devcontainer or copilot-setup-steps.yml changes were made. No synchronization review required.
Verdict: No issues found. All safety checks pass.
Note
🔒 Integrity filter blocked 1 item
The following item was blocked because it doesn't meet the GitHub integrity level.
- #1554
pull_request_read: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
To allow these resources, lower min-integrity in your GitHub frontmatter:
tools:
github:
min-integrity: approved # merged | approved | unapproved | noneGenerated by Dependabot PR Review for issue #1554 · ● 468.9K
- rename ADR Planner surfaces to ADR Creator - fix plugin generation ordering for refreshed overviews - add activation harness baseline update support 🏗️ - Generated by Copilot
…ff, and adr-author SKILL footer - replace repo-root .github/skills/... refs with ../../skills/... in adr-identity - replace repo-root .github/instructions/shared/... refs with ../shared/... in adr-handoff (renders correctly when work-item bodies post to ADO/GitHub) - remove self-referencing absolute path in adr-author SKILL.md and adopt standard 'Brought to you by microsoft/hve-core' footer 🔒 - Generated by Copilot
- add handoff frontmatter and source attribution - refresh activation baseline after agent changes - align tts test mock behavior 🛠️ - Generated by Copilot
🔧 - Generated by Copilot
🛠️ - Generated by Copilot
🛠️ - Generated by Copilot
4 participants
Pull Request
Description
This PR introduces a phase-gated ADR Planner alongside its execution surfaces — a new
adr-authorskill, anlint:adr-consistencyPowerShell module, four supporting instruction files, and the documentation, packaging, and validation plumbing required to ship them. The ADR Planner aligns with the repository's peer planners (RAI, Security, SSSC) by adopting a Frame → Decide → Govern phase model with deterministic state transitions, structured handoffs to backlog automation, and a reusable BYO-template contract.The change spans agent prompts, an executable skill (Python + PowerShell), a Pester-tested lint module, Docusaurus documentation, collection manifests, and generated plugin/extension outputs. Reviewers should pay particular attention to the
_safe_resolvepath-traversal hardening, atomic lineage operations in the skill, the closed-enum frontmatter schema (intentionally constrained), and the GHCP Maturity advisory in the section below.Security & Breaking Changes
adr-authorskill): added_safe_resolveto anchor every resolved path inside the configuredrepo_rootbefore any filesystem write, applied acrossadr_create.py,adr_advance.py,adr_update.py, andadr_render.py. Mitigates the canonical "../../../etc/passwd"-style traversal class for skill-issued I/O.os.replaceswap, eliminating partial-write corruption when interrupted mid-mutation.status,kind, plus requiredid,title,date,deciders): backwards-incompatible for hand-authored ADRs that previously used free-form values, but no pre-existing ADRs in this repository use the legacy shape — the seed ADR0001-record-architecture-decisions.mdis new in this PR.lint:adr-consistencyenforces the schema.subprocess.runcall uses argument-list form,check=True, and explicitcwd/env; no shell strings.New Features
.github/agents/project-planning/adr-creation.agent.md): restructured into Frame → Decide → Govern phases. Each phase has explicit entry/exit gates, a per-turn six-step protocol, and a deterministic state machine persisted to a session JSON document..github/instructions/project-planning/):adr-identity.instructions.md— phase machine, autonomy tiers, canonicalstate.jsonschema.adr-standards.instructions.md— embedded MADR v4.0.0 (CC0) template, Y-Statement formula (Zimmermann/Zdun, six-slot), status taxonomy, naming rules, ASR trigger schema, Microsoft-attributed paraphrases.adr-byo-template.instructions.md— two-layer config resolution,.adr-config.ymlschema, template frontmatter contract, adopt-template lifecycle.adr-handoff.instructions.md— Govern-phase handoff protocol, peer-agent routing heuristics, dual-format (ADO + GitHub) work item templates.adr-authorskill (.github/skills/project-planning/adr-author/): Python-first executable skill with five scripts (adr_create.py,adr_advance.py,adr_update.py,adr_render.py,adr_validate.py), four bundled templates (madr-v4 CC0, y-statement six-slot, diagram-ascii ~25 LOC, diagram-mermaid ~15 LOC, frontmatter-overlay 40 LOC), and JSON schemas for state/lineage validation. Includes pyproject.toml withpyyaml,jsonschema, andatheris(fuzz harness, isolated dependency group).lint:adr-consistencyPowerShell module (scripts/linting/AdrConsistency/): nine ADR-CONSISTENCY rules covering frontmatter completeness, status taxonomy compliance, lineage symmetry (supersedes/superseded-by, relates-to bidirectionality), filename-to-id parity, and ASR coverage. Three submodules (Parser,Rules,CLI), four JSON schemas, and a top-levelValidate-AdrConsistency.ps1entry point.Refactors
.github/instructions/shared/disclaimer-language.instructions.md): added the ADR Planner to the planning-agent disclaimer scope (applyToglob extended to**/.copilot-tracking/adr-plans/**and**/docs/planning/adrs/**).scripts/linting/schemas/): registered new schemas for ADR identity, standards, BYO template, and handoff instructions.Tests & Activation Harness
scripts/tests/linting/Test-AdrConsistency.Tests.ps1): 27 cases covering all nine ADR-CONSISTENCY rules, edge cases for symmetric lineage, and error-path coverage for malformed frontmatter..github/skills/project-planning/adr-author/tests/): 45–55 cases covering create/advance/update/render/validate flows,_safe_resolveboundary tests, atomic-write rollback simulation, and template adoption.tests/fuzz_harness.py): three corpus directories (corpus/frontmatter/,corpus/lineage/,corpus/state/) seeding inputs to the parser and lineage validator.scripts/tests/activation/Test-AdrAuthorActivation.Tests.ps1): four scenarios validating the skill installs, registers, and invokes from a fresh session. LF normalization fix included so fingerprints match across Windows and Linux runners.Documentation
docs/planning/adrs/0001-record-architecture-decisions.md(MADR v4 format), establishing the repository's first architectural decision record and demonstrating expected frontmatter, body sections, and lineage usage.docs/planning/adrs/covering the three-phase workflow, BYO template adoption, handoff to ADO/GitHub backlogs, and the maturity disclaimer.npm run docs:test.docs/contributing/skills.mdanddocs/contributing/custom-agents.mdupdated to reference the new artifacts.Distribution & Packaging
collections/project-planning.collection.ymllists the new agent, four instructions, and the skill (all markedmaturity: experimental).plugins/project-planning/outputs regenerated vianpm run plugin:generate.extension/package.project-planning.jsonandextension/README.project-planning.mdregenerated vianpm run extension:prepare..markdownlint,.cspell.json, frontmatter validator excludes: extended to cover ADR template files, fixture data, and thetemplates/subdirectory of the skill.Related Issue(s)
None.
Type of Change
Select all that apply:
Code & Documentation:
Infrastructure & Configuration:
AI Artifacts:
prompt-builderagent and addressed all feedback.github/instructions/*.instructions.md).github/prompts/*.prompt.md).github/agents/*.agent.md).github/skills/*/SKILL.md)Other:
.ps1,.sh,.py)Sample Prompts (for AI Artifact Contributions)
User Request:
Execution Flow:
.adr-config.yml(or prompts to bootstrap one), determines the next ADR number from existing entries indocs/planning/adrs/, classifies the decision against the ASR trigger schema, asks scope-sharpening questions per the autonomy tier, and persists the session to.copilot-tracking/adr-plans/<id>/state.json.state.jsonafter each gate.lint:adr-consistency, generates the dual-format backlog handoff (ADO + GitHub work item bodies), and routes peer-agent recommendations (Security/SSSC/RAI) when triggered.Output Artifacts:
docs/planning/adrs/0042-adopt-json-schema-validation.md(MADR v4 format) — preview of generated frontmatter:.copilot-tracking/adr-plans/0042/state.json— phase machine state, autonomy tier, gate results..copilot-tracking/adr-plans/0042/handoff/— ADO and GitHub work item bodies generated by the Govern phase.Success Indicators:
npm run lint:adr-consistencyexits 0 with no findings against the new ADR.npm run validate:skillspasses foradr-author.npm run docs:test(Docusaurus) renders the new ADR with correct sidebar placement and lineage cross-links.state.jsonshowsphase: "govern"andgates.govern.complete: true.For detailed contribution requirements, see:
Testing
Local validation evidence and command results will be appended after the Step 7 automated-check run. Coverage at the source level:
scripts/tests/linting/Test-AdrConsistency.Tests.ps1): 27 cases — all nine ADR-CONSISTENCY rules, lineage symmetry edge cases, malformed-frontmatter error paths..github/skills/project-planning/adr-author/tests/): 45–55 cases — create/advance/update/render/validate flows,_safe_resolveboundary tests, atomic-write rollback, template adoption.fuzzdependency group; not run by default).scripts/tests/activation/Test-AdrAuthorActivation.Tests.ps1): four end-to-end install/register/invoke scenarios with cross-platform LF-normalized fingerprints.The eight repository-required automated checks plus
lint:adr-consistencywill be run before merge — results recorded in the checklist below.Checklist
Required Checks
AI Artifact Contributions
/prompt-analyzeto review contributionprompt-builderreviewRequired Automated Checks
The following validation commands must pass before merging:
npm run lint:md— PASS (199 files, 0 errors)npm run spell-check— PASS (879 files checked, 0 issues)npm run lint:frontmatter— PASS (555 files, 0 warnings, 0 errors) after adding the standard Copilot footer to.github/skills/project-planning/adr-author/tests/corpus/README.mdnpm run validate:skills— PASS (21 skills, 0 errors, 0 warnings)npm run lint:md-links— PASS-out-of-scope. All 7 failing files are pre-existing and outside this PR's diff (verified viagit diff --name-only origin/main...HEAD):.github/skills/security/secure-by-design/SKILL.md,docs/agents/code-review/README.md,docs/agents/rai-planning/agent-overview.md,docs/agents/rai-planning/phase-reference.md,docs/architecture/README.md,docs/getting-started/collections.md,docs/getting-started/mcp-configuration.md.npm run lint:ps— PASS (all files passed PSScriptAnalyzer)npm run plugin:generate— PASS (13 plugins generated, no working-tree changes produced)npm run docs:test— PASS (7 suites, 102 tests)Security Considerations
GHCP Maturity
Warning
This PR ships AI artifacts at experimental maturity. Reviewers and downstream consumers should treat the ADR Planner, its supporting instructions, and the
adr-authorskill as evolving surfaces likely to change before they reachstablematurity. Acknowledge the maturity expectations below before merge..github/agents/project-planning/adr-creation.agent.md.github/instructions/project-planning/adr-identity.instructions.mdstate.jsonschema may evolve; consumers should pin to a tagged release..github/instructions/project-planning/adr-standards.instructions.md.github/instructions/project-planning/adr-byo-template.instructions.md.github/instructions/project-planning/adr-handoff.instructions.md.github/skills/project-planning/adr-author/GHCP Maturity Acknowledgment
Additional Notes
feat/adr-planner-upgrade-v2) is stacked on PR feat(scripts)(settings): add ADR consistency lint infrastructure #1552. Merge order matters; rebase will be required if PR feat(scripts)(settings): add ADR consistency lint infrastructure #1552 changes during review.npm auditsurfaces advisories againstfast-uri(transitive). These are tracked separately and intentionally deferred from this PR per maintainer direction..copilot-tracking/pr/pr-reference-log.md(covers branch snapshot, security analysis, feature inventory, refactor map, test matrix, documentation diff, distribution diff, cross-cutting themes, risks, and validation requirements). It is intentionally untracked and exists only for reviewer convenience.plugins/project-planning/,extension/package.project-planning.json, andextension/README.project-planning.mdare regenerated outputs — do not edit by hand; rerunnpm run plugin:generateandnpm run extension:prepareif the source manifests change during review.