feat(project-planning): ISA-95 network planner agent

[nguyena2]

Pull Request

Description

Created the ISA-95 network planning agent and updated collection references to the new path.

This PR also refreshed plugin linkage so the agent remains discoverable in bundled outputs.

Related Issue(s)

Closes #1410

Type of Change

Select all that apply:

Code & Documentation:

• Bug fix (non-breaking change fixing an issue)
• New feature (non-breaking change adding functionality)
• Breaking change (fix or feature causing existing functionality to change)
• Documentation update

Infrastructure & Configuration:

• GitHub Actions workflow
• Linting configuration (markdown, PowerShell, etc.)
• Security configuration
• DevContainer configuration
• Dependency update

AI Artifacts:

• Reviewed contribution with prompt-builder agent and addressed all feedback
• Copilot instructions (.github/instructions/*.instructions.md)
• Copilot prompt (.github/prompts/*.prompt.md)
• Copilot agent (.github/agents/*.agent.md)
• Copilot skill (.github/skills/*/SKILL.md)

Note for AI Artifact Contributors:

• Agents: Research, indexing/referencing other project (using standard VS Code GitHub Copilot/MCP tools), planning, and general implementation agents likely already exist. Review .github/agents/ before creating new ones.
• Skills: Must include both bash and PowerShell scripts. See Skills.
• Model Versions: Only contributions targeting the latest Anthropic and OpenAI models will be accepted. Older model versions (e.g., GPT-3.5, Claude 3) will be rejected.
• See Agents Not Accepted and Model Version Requirements.

Other:

• Script/automation (.ps1, .sh, .py)
• Other (please describe):

Sample Prompts (for AI Artifact Contributions)

User Request:

"Review our brownfield factory site's ISA-95 network segmentation between edge Kubernetes and Azure, and produce a remediation roadmap."

Execution Flow:

1. User invokes the Network ISA-95 Planner agent via prompt or agent picker.
2. Agent enforces intake gating for required ISA-95 context fields before classification.
3. Agent maps zones/conduits, classifies alignment, and produces remediation priorities.
4. Agent writes a markdown assessment and YAML companion artifact output.

Output Artifacts:

• .copilot-tracking/plans/{{YYYY-MM-DD}}-network-isa95-assessment.md (default path when caller does not provide one)

Preview:

# Output A: Plain-Language Assessment
## Current architecture summary
...

```yaml
assessment_metadata:
  ...

**Success Indicators:**
- Agent appears as `Network ISA-95 Planner` in collections/plugin bundles.
- Invoking the agent produces an assessment file at the documented default output path (`network-isa95-assessment`).
- Collection manifests resolve the agent path without stale references.

For detailed contribution requirements, see:

* Common Standards: [docs/contributing/ai-artifacts-common.md](../docs/contributing/ai-artifacts-common.md) - Shared standards for XML blocks, markdown quality, RFC 2119, validation, and testing
* Agents: [docs/contributing/custom-agents.md](../docs/contributing/custom-agents.md) - Agent configurations with tools and behavior patterns
* Prompts: [docs/contributing/prompts.md](../docs/contributing/prompts.md) - Workflow-specific guidance with template variables
* Instructions: [docs/contributing/instructions.md](../docs/contributing/instructions.md) - Technology-specific standards with glob patterns
* Skills: [docs/contributing/skills.md](../docs/contributing/skills.md) - Task execution utilities with cross-platform scripts

## Testing
- Generated PR reference and reviewed diffs using `.copilot-tracking/pr/pr-reference.xml`.
- Verified changed files map to new agent + collection wiring.
- Performed security review of changed artifacts for sensitive data introduction; none found in committed files.
- Manual testing was not performed.

## Checklist

### Required Checks

* [x] Documentation is updated (if applicable) (N/A — collection manifest covers discoverability)
* [x] Files follow existing naming conventions
* [x] Changes are backwards compatible (if applicable)
* [ ] Tests added for new functionality (if applicable)

### AI Artifact Contributions
<!-- If contributing an agent, prompt, instruction, or skill, complete these checks -->
* [x] Used `/prompt-analyze` to review contribution
* [x] Addressed all feedback from `prompt-builder` review
* [x] Verified contribution follows common standards and type-specific requirements

### Required Automated Checks

The following validation commands must pass before merging:

* [x] Markdown linting: `npm run lint:md`
* [x] Spell checking: `npm run spell-check`
* [x] Frontmatter validation: `npm run lint:frontmatter`
* [x] Skill structure validation: `npm run validate:skills`
* [x] Link validation: `npm run lint:md-links`
* [x] PowerShell analysis: `npm run lint:ps`
* [x] Plugin freshness: `npm run plugin:generate`
* [x] Docusaurus tests: `npm run docs:test`

## Security Considerations
<!-- ⚠️ WARNING: Do not commit sensitive information such as API keys, passwords, or personal data -->
* [x] This PR does not contain any sensitive or NDA information
* [x] Any new dependencies have been reviewed for security issues (N/A — no new dependencies)
* [x] Security-related scripts follow the principle of least privilege (N/A — no security scripts modified)

## Additional Notes
- Repository PR template from `.github/PULL_REQUEST_TEMPLATE.md` was used.
- This PR includes AI artifact changes; human review of agent behavior is recommended before merge.

Closes #1410

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 87.61%. Comparing base (2aee4d6) to head (dc88dcd).
⚠️ Report is 5 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1177      +/-   ##
==========================================
- Coverage   87.62%   87.61%   -0.02%     
==========================================
  Files          62       62              
  Lines        9696     9696              
==========================================
- Hits         8496     8495       -1     
- Misses       1200     1201       +1     

Flag	Coverage Δ
pester	84.80% <ø> (-0.02%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.
see 1 file with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[github-actions]

Dependency Review Summary

The full dependency review summary was too large to display here (3099KB, limit is 1024KB).

Please download the artifact named "dependency-review-summary" to view the complete report.

View full job summary

[katriendg]

Thanks for your proposal of the new agent.

One thing I would like to raise here is a discussion on whether this agent makes much sense into the hve-core 'Project Planning' collection, or any of the existing collections for that matter. This agent is very domain-specific, while all other agents in the collection are intentionally agnostic.

My first reflection was whether this makes more sense in edge-ai repo? It can still link back to the Security Planner agent as long as edge-ai has pre-installed extension or guidance around it.

Thoughts?

[nguyena2]

Thanks for your proposal of the new agent.

One thing I would like to raise here is a discussion on whether this agent makes much sense into the hve-core 'Project Planning' collection, or any of the existing collections for that matter. This agent is very domain-specific, while all other agents in the collection are intentionally agnostic.

My first reflection was whether this makes more sense in edge-ai repo? It can still link back to the Security Planner agent as long as edge-ai has pre-installed extension or guidance around it.

Thoughts?

Thanks for your proposal of the new agent.

One thing I would like to raise here is a discussion on whether this agent makes much sense into the hve-core 'Project Planning' collection, or any of the existing collections for that matter. This agent is very domain-specific, while all other agents in the collection are intentionally agnostic.

My first reflection was whether this makes more sense in edge-ai repo? It can still link back to the Security Planner agent as long as edge-ai has pre-installed extension or guidance around it.

Thoughts?

Bill and I briefly discussed where to put this as it could live in edge-ai or here. I decided to put it here as the intent is to be more general. The first pass is very edge-ai as it's what I used to build the agent off of. As we get more clarity on how this agent is used and how it evolves, we can always move it later.

[bindsi]

I really like this agent´s clear structure and purpose to cover a difficult and very important domain for customers.
But I suggest to query more information in the intake process for the brownfield or greenfield scenarios. On the one hand for brownfield it might be relavent to reuse own (reverse) proxies, gateways, vpn, etc. and on the other hand for greenfield the target architecture might be relevant --> maybe be pointing to some Microsoft recommendations (like for AIO https://learn.microsoft.com/en-us/azure/iot-operations/manage-layered-network/concept-iot-operations-in-layered-network, https://github.com/Azure-Samples/explore-iot-operations/blob/main/samples/layered-networking/aio-layered-network.md), maybe we can also address them as a skill and reference those here in the agent.

[WilliamBerryiii]

I really like this agent´s clear structure and purpose to cover a difficult and very important domain for customers. But I suggest to query more information in the intake process for the brownfield or greenfield scenarios. On the one hand for brownfield it might be relavent to reuse own (reverse) proxies, gateways, vpn, etc. and on the other hand for greenfield the target architecture might be relevant --> maybe be pointing to some Microsoft recommendations (like for AIO https://learn.microsoft.com/en-us/azure/iot-operations/manage-layered-network/concept-iot-operations-in-layered-network, https://github.com/Azure-Samples/explore-iot-operations/blob/main/samples/layered-networking/aio-layered-network.md), maybe we can also address them as a skill and reference those here in the agent.

Could also do what we did for the security planner and reference the WAF and CAF to fold in those default Azure Practices

[nguyena2]

I added more intake questions for both greenfield and brownfield scenarios. Moved the .md into its own networking folder since I do see it get more expansive in the future. Also added a skills .md to follow security, to help provide those default practices

[katriendg]

Thanks for this new agent. I've left a few comments, I think the agent is a good groundwork, just wondering if it is at the right location (collection), and if the skill adds much value. If we can simplify without it, I would choose that option.

[github-actions]

Automated Quality Review

This PR introduces the Network ISA-95 Planner agent, collection manifest wiring, and plugin regeneration. The agent's structure, frontmatter, step-based protocol, intake gating, and collection dependency on Researcher Subagent (already present in both manifests ✅) all look sound. However, several PR template compliance issues require action before this is ready for human review.

---

📋 Issue Alignment

Issue #1410 is linked via Closes #1410. The issue content could not be accessed to verify alignment, but the PR description's stated goal (create ISA-95 network planner agent) is consistent with the files changed. ⚠️ A human reviewer should confirm the issue requirements are fully met.

---

❌ PR Template Compliance

1. Missing "User Request" in Sample Prompts

The PR template requires a User Request sub-section under Sample Prompts:

What natural language request would trigger this agent/prompt/instruction?

The PR omits this sub-section entirely. Please add a short example invocation such as:

"Review our brownfield factory site's ISA-95 network segmentation and generate a remediation roadmap."

2. AI Artifact Contributions checklist — all items unchecked

The PR has [x] Copilot agent checked under AI Artifacts, but the corresponding AI Artifact Contributions checklist under Checklist is entirely unchecked:

• [ ] Used /prompt-analyze to review contribution
• [ ] Addressed all feedback from prompt-builder review
• [ ] Verified contribution follows common standards and type-specific requirements

Per the PR template instructions, when any AI Artifact type checkbox is checked these checklist items must also be completed (or explicitly waived with justification). The Reviewed contribution with prompt-builder agent and addressed all feedback checkbox in the AI Artifacts type block is also unchecked.

3. Execution Flow says "renamed" — contradicts PR intent

The Execution Flow reads:

"User invokes the renamed planning agent via prompt or agent picker."

The PR description states this is a new agent ("Created the ISA-95 network planning agent"). "Renamed" implies a pre-existing agent was renamed, which is inconsistent with the rest of the PR. This appears to be stale copy-paste from a previous draft. Please update the Execution Flow to accurately describe the new agent invocation.

4. Documentation checkbox unchecked

[ ] Documentation is updated (if applicable) is unchecked. The collections/project-planning.collection.md was updated, which covers collection-level discovery. If no entry is required in the docs/contributing/ or docs/hve-guide/ trees for this agent, please check the box and note "N/A — collection manifest description covers discoverability."

---

⚠️ Coding Standards

5. Core Principles RFC 2119 keyword strength (inline comment on lines 15–19)

Five of six Core Principles use SHOULD, meaning they are optional per RFC 2119. For a security assessment agent, the security-first approach and zone/conduit-based planning should be MUST. See the inline comment for a suggested revision.

---

✅ Code Quality

• Agent structure is well-organised: required intake gating in Step 0 before any classification output is a solid safeguard against hallucinated assessments.
• Frontmatter is correct: disable-model-invocation: true paired with agents: - Researcher Subagent is the right pattern for an orchestrating agent.
• Researcher Subagent is already present in both project-planning.collection.yml and hve-core-all.collection.yml — no missing dependency.
• maturity: experimental is correctly applied in both collection manifests.
• Plugin symlink files and README entries are consistent with the new agent path.
• YAML companion artifact schema is well-defined with distinct intake-gate-pending and full output schemas.
• Escalation criteria for safety, regulatory, and ownership disputes are clearly articulated.

---

🔧 Required Action Items

1. Add the "User Request" sub-section to the Sample Prompts section.
2. Complete or justify the AI Artifact Contributions checklist items (or check "Reviewed contribution with prompt-builder agent" if that review was performed).
3. Fix the "renamed" wording in Execution Flow to reflect new-agent invocation.
4. Resolve the Documentation checkbox (check it or add a "N/A" note).
5. Consider elevating foundational security behaviours in Core Principles from SHOULD to MUST (see inline comment).

Note

🔒 Integrity filter blocked 1 item

The following item were blocked because they don't meet the GitHub integrity level.

• #1410 issue_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 | none

Generated by PR Review for issue #1177 · ● 1.4M

[github-actions]

PR Review Summary

This PR introduces the Network ISA-95 Planner agent, updates both collection manifests, and regenerates plugin outputs. The agent content itself is well-structured and follows most codebase conventions. However, there are several required template compliance gaps that must be addressed before merging.

---

⚠️ Issue Alignment

Issue #1410 could not be read during this automated review (filtered by integrity policy). The PR description adequately describes the change intent (new ISA-95 network planning agent with collection wiring), but human reviewers should verify alignment with the linked issue before approving.

---

❌ PR Template Compliance

Missing "User Request" sub-section in Sample Prompts

The PR template requires a "User Request" field under Sample Prompts describing the natural language input that triggers the agent. The PR description contains "Execution Flow", "Output Artifacts", and "Success Indicators" but omits "User Request". Please add this sub-section.

Unchecked required checklist items

The following items must be addressed by AI artifact contributors and are currently unchecked:

Checklist Item	Status
Documentation is updated (if applicable) — docs were updated (collection.md files and plugin READMEs changed)	❌ Unchecked
Reviewed contribution with prompt-builder agent and addressed all feedback (AI Artifacts section)	❌ Unchecked
Used /prompt-analyze to review contribution (AI Artifact Contributions)	❌ Unchecked
Addressed all feedback from prompt-builder review (AI Artifact Contributions)	❌ Unchecked
Verified contribution follows common standards and type-specific requirements (AI Artifact Contributions)	❌ Unchecked

Per the PR template note: "Reviewed contribution with prompt-builder agent and addressed all feedback" is required for AI artifact contributions.

---

🔍 Coding Standards

Two inline comments have been posted on the agent file:

1. tools field format (line 5): Uses YAML flow sequence (['agent', 'edit/editFiles', 'microsoft-docs/*']) instead of the block sequence format shown in the instructions examples. Minor but inconsistent with codebase convention.

2. Default output path (line ~112): .copilot-tracking/reviews/{{YYYY-MM-DD}}-network-isa95-assessment.md places planning assessments in the reviews/ subdirectory, which per codebase conventions is reserved for code review artifacts. Consider .copilot-tracking/plans/ or a dedicated directory.

---

✅ Code Quality and Security

• No security vulnerabilities found.
• No secrets or sensitive data detected.
• Subagent dependency (Researcher Subagent) is correctly declared in agents: frontmatter and is already present in both project-planning.collection.yml and hve-core-all.collection.yml — no missing dependencies.
• Agent structure follows step-based protocol pattern correctly (Steps 0–7 with intake gate).
• RFC 2119 language (MUST/SHOULD) is used consistently and appropriately.
• Attribution footer (> Brought to you by microsoft/hve-core) is present.
• Collection manifest entries, plugin README rows, and symlink files are all consistent.

---

📋 Action Items

1. Add the "User Request" sub-section to the Sample Prompts section of the PR description.
2. Check the "Documentation is updated" checkbox — docs were updated.
3. Complete the prompt-builder / /prompt-analyze review process and check all AI Artifact Contributions checklist items.
4. Address the two inline comments on the agent file (tools format and default output path).

Note

🔒 Integrity filter blocked 1 item

The following item were blocked because they don't meet the GitHub integrity level.

• #1410 issue_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 | none

Generated by PR Review for issue #1177 · ● 2.3M

[auyidi1]

I added more intake questions for both greenfield and brownfield scenarios. Moved the .md into its own networking folder since I do see it get more expansive in the future. Also added a skills .md to follow security, to help provide those default practices

See my comments on bluefield scenarios.

[auyidi1]

Thanks for your proposal of the new agent.

One thing I would like to raise here is a discussion on whether this agent makes much sense into the hve-core 'Project Planning' collection, or any of the existing collections for that matter. This agent is very domain-specific, while all other agents in the collection are intentionally agnostic.

My first reflection was whether this makes more sense in edge-ai repo? It can still link back to the Security Planner agent as long as edge-ai has pre-installed extension or guidance around it.

Thoughts?

The agent should be general enough for hve-core. However, any AIO-specific conduit patterns (MQTT broker bridging, Arc agent connectivity, ACSA sync) could be an edge-ai extension/overlay. Keeping the base agent in hve-core and adding AIO-specific guidance in edge-ai seems right.

[github-actions]

PR Review: feat/networking-agent — Network ISA-95 Planner Agent

Overview

This PR adds a well-structured ISA-95 network planning agent along with the required collection and plugin wiring. The intake gate, step-based protocol, delegation model, and attribution footer all follow repository conventions correctly. Two functional gaps require resolution before merge.

---

Issue Alignment

Closes #1410. The PR description, agent scope, and collection entries are mutually consistent. Issue details could not be independently verified, but the stated intent (ISA-95 network planning for edge Kubernetes → Azure) is coherent with the delivered artifact.

---

PR Template Compliance ✅

All required template sections are filled. Checkboxes are appropriate: "New feature" and "Copilot agent" are checked and match the actual diff. AI Artifact contribution checklist items are all checked. Security considerations are attested. No violations found.

---

Coding Standards ✅

Checked against .github/instructions/ rules for **/*.agent.md:

Check	Result
Required frontmatter fields (name, description, disable-model-invocation, agents)	✅
Researcher Subagent present in both affected collection YAMLs	✅
Step-based protocol with ## Required Steps / ### Step N: format	✅
Intake gate before planning steps	✅
Output artifact path and progressive-documentation contract	✅
Attribution footer Brought to you by microsoft/hve-core	✅
Writing style: no em dashes, no bolded-prefix list items	✅
Collection YAML ordering (alphabetical by path)	✅
Symlink targets resolve correctly in both plugin bundles	✅

---

Code Quality — Findings Requiring Changes

Two inline comments are attached. Summary:

1. 🔍 Missing routing branch for "mixed" site profile (Step 5)

The intake question explicitly offers "mixed" as a valid site profile answer, but ### Step 5 only defines deterministic routing branches for brownfield and greenfield tracks. A user answering "mixed" triggers undefined routing behaviour, breaking the agent's own MUST route deterministically contract. A "mixed" branch that applies both tracks to their respective segments must be added.

2. ⚠️ YAML schema lifecycle is ambiguous (Output B)

The intake-gate-pending minimum schema introduces intake_questions and intake_gate_status keys that do not appear in the full YAML schema. No specification is provided for how the file transitions between the two states, leaving downstream tooling and reviewers without a clear contract. Either carry the keys forward as nullable fields in the full schema, or add an explicit replacement note.

---

Action Items

1. Add a "mixed" routing path to Step 5 (see inline comment).
2. Clarify the YAML schema lifecycle for intake_gate_status and intake_questions (see inline comment).

Note

🔒 Integrity filter blocked 1 item

The following item were blocked because they don't meet the GitHub integrity level.

• #1410 issue_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 | none

Generated by PR Review for issue #1177 · ● 1.5M

[nguyena2]

Thanks for your proposal of the new agent.
One thing I would like to raise here is a discussion on whether this agent makes much sense into the hve-core 'Project Planning' collection, or any of the existing collections for that matter. This agent is very domain-specific, while all other agents in the collection are intentionally agnostic.
My first reflection was whether this makes more sense in edge-ai repo? It can still link back to the Security Planner agent as long as edge-ai has pre-installed extension or guidance around it.
Thoughts?

The agent should be general enough for hve-core. However, any AIO-specific conduit patterns (MQTT broker bridging, Arc agent connectivity, ACSA sync) could be an edge-ai extension/overlay. Keeping the base agent in hve-core and adding AIO-specific guidance in edge-ai seems right.

I removed the specific AIO to make the agent more general.

[github-actions]

Automated Quality Review

Overall this is a well-structured PR that follows repository conventions. One minor documentation inconsistency is flagged as an inline comment; everything else is in order.

---

Issue Alignment

⚠️ Issue #1410 could not be read (integrity policy). Based on the PR description, the changes (new Network ISA-95 Planner agent + collection/plugin wiring) appear consistent with the stated intent. Please confirm the linked issue is still accurate and not stale.

---

PR Template Compliance

✅ All required sections are filled in with substantive content.
✅ "New feature" and "Copilot agent" checkboxes are checked and match the actual diff.
✅ The "Reviewed contribution with prompt-builder agent" checkbox is checked.
✅ All required automated checks are marked as passed.
✅ Security considerations are completed with appropriate N/A annotations.

---

Coding Standards Review

✅ Agent frontmatter (name:, description:, disable-model-invocation: true, tools:, agents:) follows the conventions defined in the prompt-builder instructions.
✅ description: includes the required attribution suffix (- Brought to you by microsoft/hve-core).
✅ The Researcher Subagent declared in agents: is already present in both affected collection manifests — no missing dependency.
✅ maturity: experimental is correctly set in both hve-core-all.collection.yml and project-planning.collection.yml.
✅ Plugin symlinks use the correct relative path and are registered in both plugin READMEs.
✅ Attribution footer (> Brought to you by microsoft/hve-core) is present at the end of the agent file.
✅ RFC 2119 language (MUST, SHOULD) is used consistently and appropriately throughout.

i️ No model: field specified. Contributing guidelines state only the latest models are accepted. Omitting model: relies on the platform default (which is typically the latest), so this is not a blocking issue, but explicitly declaring a model (e.g., model: claude-sonnet-4) would make the intent unambiguous and future-proof against default changes.

---

Code Quality

✅ No security vulnerabilities or secrets exposure detected.
✅ The intake gate (Step 0) correctly prevents premature alignment classification or remediation output — a strong safety design for a security-focused agent.
✅ The YAML companion artifact schema is well-defined with a documented transitional gate-pending form.
✅ The escalation criteria section is present and appropriate for a planning agent with operational safety implications.

⚠️ Output path inconsistency (see inline comment): The PR description's "Output Artifacts" preview lists reviews/ as the default subdirectory, while the agent body specifies plans/. These should match. Please align the PR description to the agent body (or vice versa).

---

Action Items

1. Resolve the output path discrepancy between the PR description (reviews/) and the agent body (plans/) — see the inline comment on line 87 of the agent file.
2. (Optional) Add an explicit model: field to make model targeting unambiguous.

Note

🔒 Integrity filter blocked 1 item

The following item were blocked because they don't meet the GitHub integrity level.

• #1410 issue_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 | none

Generated by PR Review for issue #1177 · ● 2.3M

no need