[WIP] Specification and Prototype Development for IP Assignment Tool

[Copilot]

Coding agent has begun work on Specification and Prototype Development for IP Assignment Tool and will replace this description as work progresses.

See problem context

The user has attached the following files from their workspace:

• tools/EnvironmentDetailAssignment/README.md

The following is a snapshot of a chat conversation between a user and an AI coding assistant. Prioritize later messages in the conversation.
User: help me build a spec for a new script tool. ask questions to help define the spec and write the Markdown readme file in the EnvironmentDetailAssignement directory.
The tool will use JSON output from IPAssignment tool for a list of subnets and VLAN ID's utilized in the environment.
An additional JSON will be used to define the network ip assignments for a given subnet and or VLAN id.
This will be used to have a standardize process for defining the IP payload of an environemnt.

Problem:
Need to standardize the IP assignments for an environment with multiple subnets and hardware requirements. This will generate a standard list of IP assignemtn for all the required devices that operate within individual subunet spaces. Each subnet can have the option to have a switch IP assignment, gateway assignment, load balancer assignment, firewall assignment, pluse server/virtual machine ip assignemnts to service applications. This will output data in the following formats

• CSV
• Markdown
• JSON, if JSON output is utilized this will be compatable with network config generator.
  AI: Diving into the new IP assignment tool spec by pinning down the missing details so we can document it properly.
  Plan: 1) clarify requirements, 2) write the spec, 3) update the EnvironmentDetailAssignment README.

To flesh out the spec, could you share a bit more?

• Workflow: How will users run this tool—standalone script invoked manually, part of a pipeline, or integrated into an existing UI?
• Inputs:
  • Where will the subnet/VLAN JSON from IPAssignment live, and what key fields/structure should we expect?
  • For the “additional JSON” defining per-subnet assignments, do you already have a schema or example (fields for devices, roles, reserved ranges, etc.)?
• Output expectations:
  • Should CSV/Markdown/JSON all be generated on every run, or selectable via flags?
  • Any specific columns/order for the CSV or table layout for Markdown?
  • For the JSON output compatible with the network config generator, do we need to match an existing schema?
• Business rules:
  • Any default assumptions (e.g., reserve first IP for gateway, last for broadcast) or validation rules we must enforce?
  • How should conflicts or missing data be handled?
• Operational details: Preferred language (Python like the rest of the repo?), logging, config files, or CLI parameters we should support?
• Adjacencies: Should the tool emit warnings/reports for unused IPs, duplicates, or capacity planning? Any desire for templated comments/metadata in the outputs?

Once I’ve got these answers, I can write a precise spec and reflect it in the README.
User: Workflow: manual script invoked, but can work in conjunction with a pipeline at a later date.
Input: Example tools\EnvironmentDetailAssignment\IPAssignment-Example.json
Output: CSV/Markdown/JSON are selectable from a pram input option. Default will be Markdown.

• CSV VLAN ID, VLAN Name, Device, IP Assignment, Subnet Mask, Cidr
  (Note: include Network and Broadcast IP in the assignments)f
• JSON, I changed my mind on the compatiablty aspect. Make the JSON have the same values as the CSV but in JSON format.
  Business Rules: Each subnet will have a default reservation for network components if they are not defined.
• Gateway IP, first IP after the network IP address. Example: 192.168.0.0/24, network: 192.168.0.0, gateway: 192.168.0.1
• TOR, if two network devices are define each TOR will have a IP assigned. If a single TOR is defined, this will only have the Gateway IP address. If two TOR's are utilized, this would assume the two TORs are configured in a Cisco Nexus HSRP configuration. If more than 1 TOR is defined, each tor will be assigned a IP after the gateway IP address. if the gateway is 192.168.0.1, then TOR1 will be 192.168.0.2, and TOR2 wil lbe 192.168.0.3.
• Defaults always define the Network, Gateway and Broadcast IP addresses
• A supporting JSON will be required to define the network strucutre of the environemnt. If a subnet is defined in the supporting JSON and not included in the IPAssignment JSON then throw an error. the defined network need to match by network name.
• two independant JSON files will be used.
  • IPAddress JSON will be created from a supporting tool under tools/IPassignment powershell module.
  • EnvironmentDetailAssignement JSON will define the full IP payload of the environment. Network names will be used to match against. the names need to be unique.
    Operational details: Powershell based, logging so help debug errors when Verbose flags are utilzied. Config file two input JSON files defined with params. EnvironemntDetailAssignment JSON will assume in a local directroy with a matching name if not defined in a param.
    Adjacencies: throw an error on duplicate IP assignments. What comments or metadata ouputs would your recomend as a expert network engineer and expert powershell developer?

AI:

AI: 

AI:

AI: 

User: @agent Try Again
AI:

AI: 

AI:

AI: 

AI: Documented the new Environment Detail Assignment tool spec and captured all your business rules right in
AI: .

actions taken

• Drafted a full workflow/spec covering inputs, validation, allocation logic, output formats, logging expectations, and future enhancements.
• Added recommended CLI parameters, error-handling behavior, and helper-function guidance tailored for a PowerShell implementation.
• Included detailed manifest schema examples, device allocation semantics (auto, pool, explicit), and comprehensive metadata suggestions.
• Expanded logging/diagnostics guidance and laid out CSV/Markdown/JSON schema expectations—including the metadata columns you asked about.

requirements coverage

• Requirements clarification → Done (details embedded in spec).
• Tool specification capturing workflow, business rules, defaults, validation, outputs → Done.
• README update in EnvironmentDetailAssignment directory with Markdown spec → Done.

Let me know when you’re ready to move from spec to script implementation or need sample manifests/outputs.
User: Update on implemntation notes, this will be designed for PowerShell 7 or newer versions.
AI:

AI: 

AI: Acknowledged the implementation-note tweak; confirming we now call out PowerShell 7+ support explicitly.
Plan recap: 1) update implementation guidance, 2) verify formatting.

actions taken

• Added a leading bullet in the Implementation Notes section of
  AI: stating the tool targets PowerShell 7 or newer, aligning the spec with your runtime requirement.

notes

• No code or tests were run—documentation-only change.
  User: update Unit-Tests will be generated to support this tool and ensure functional valiation of the tool
  AI:

AI: 

AI: Logged the new unit-test requirement in
AI: under Implementation Notes, emphasizing a Pester suite to cover parsing, allocation logic, collision detection, and multi-format output checks.
User: Using the Readme.md as a documentation Spec, build a protype of the tool.

TITLE: Specification and Prototype Development for IP Assignment Tool

USER INTENT: The user aims to develop a specification and prototype for a new script tool that standardizes IP assignments across multiple subnets and VLANs, utilizing JSON outputs from existing tools.

TASK DESCRIPTION: The user is defining a new script tool that will standardize IP assignments for environments with multiple subnets and hardware requirements. The tool will generate outputs in CSV, Markdown, and JSON formats, with specific rules for IP assignments, including default reservations for network components.

EXISTING:

• The user has provided a detailed specification draft in the tools/EnvironmentDetailAssignment/README.md file, which includes:
  • Workflow: Manual script invocation with potential pipeline integration.
  • Input: Example JSON file located at tools/EnvironmentDetailAssignment/IPAssignment-Example.json.
  • Output: Selectable formats (CSV, Markdown, JSON) with Markdown as the default.
  • Business rules for IP assignments, including default gateway and TOR configurations.
  • Operational details specifying PowerShell as the implementation language, with logging and configuration requirements.
  • Error handling for duplicate IP assignments and mismatched network definitions.

PENDING:

• The user has requested the development of a prototype based on the README documentation.
• Unit tests will need to be created to validate the functionality of the tool.

CODE STATE:

• The README file at tools/EnvironmentDetailAssignment/README.md has been updated to reflect the specifications and requirements for the tool, including:
  • Implementation notes targeting PowerShell 7 or newer.
  • A requirement for unit tests using Pester for functional validation.

RELEVANT CODE/DOCUMENTATION SNIPPETS:

• Example output structure for CSV:

  VLAN ID, VLAN Name, Device, IP Assignment, Subnet Mask, CIDR
  

• Business rules for IP assignments:
  • Gateway IP: first IP after the network IP address.
  • TOR IP assignments based on the number of defined network devices.
  • Error handling for undefined subnets in the supporting JSON.

OTHER NOTES: The user has emphasized the importance of logging for debugging and has requested recommendations for comments or metadata outputs as an expert in network engineering and PowerShell development. The assistant has documented all requirements and is prepared to assist in moving from specification to implementation.

Original prompt

Using the Readme.md as a documentation Spec, build a protype of the tool.

The user has attached the following files from their workspace:

• tools/EnvironmentDetailAssignment/README.md

The following is a snapshot of a chat conversation between a user and an AI coding assistant. Prioritize later messages in the conversation.
User: help me build a spec for a new script tool. ask questions to help define the spec and write the Markdown readme file in the EnvironmentDetailAssignement directory.
The tool will use JSON output from IPAssignment tool for a list of subnets and VLAN ID's utilized in the environment.
An additional JSON will be used to define the network ip assignments for a given subnet and or VLAN id.
This will be used to have a standardize process for defining the IP payload of an environemnt.

Problem:
Need to standardize the IP assignments for an environment with multiple subnets and hardware requirements. This will generate a standard list of IP assignemtn for all the required devices that operate within individual subunet spaces. Each subnet can have the option to have a switch IP assignment, gateway assignment, load balancer assignment, firewall assignment, pluse server/virtual machine ip assignemnts to service applications. This will output data in the following formats

• CSV
• Markdown
• JSON, if JSON output is utilized this will be compatable with network config generator.
  AI: Diving into the new IP assignment tool spec by pinning down the missing details so we can document it properly.
  Plan: 1) clarify requirements, 2) write the spec, 3) update the EnvironmentDetailAssignment README.

To flesh out the spec, could you share a bit more?

• Workflow: How will users run this tool—standalone script invoked manually, part of a pipeline, or integrated into an existing UI?
• Inputs:
  • Where will the subnet/VLAN JSON from IPAssignment live, and what key fields/structure should we expect?
  • For the “additional JSON” defining per-subnet assignments, do you already have a schema or example (fields for devices, roles, reserved ranges, etc.)?
• Output expectations:
  • Should CSV/Markdown/JSON all be generated on every run, or selectable via flags?
  • Any specific columns/order for the CSV or table layout for Markdown?
  • For the JSON output compatible with the network config generator, do we need to match an existing schema?
• Business rules:
  • Any default assumptions (e.g., reserve first IP for gateway, last for broadcast) or validation rules we must enforce?
  • How should conflicts or missing data be handled?
• Operational details: Preferred language (Python like the rest of the repo?), logging, config files, or CLI parameters we should support?
• Adjacencies: Should the tool emit warnings/reports for unused IPs, duplicates, or capacity planning? Any desire for templated comments/metadata in the outputs?

Once I’ve got these answers, I can write a precise spec and reflect it in the README.
User: Workflow: manual script invoked, but can work in conjunction with a pipeline at a later date.
Input: Example tools\EnvironmentDetailAssignment\IPAssignment-Example.json
Output: CSV/Markdown/JSON are selectable from a pram input option. Default will be Markdown.

• CSV VLAN ID, VLAN Name, Device, IP Assignment, Subnet Mask, Cidr
  (Note: include Network and Broadcast IP in the assignments)f
• JSON, I changed my mind on the compatiablty aspect. Make the JSON have the same values as the CSV but in JSON format.
  Business Rules: Each subnet will have a default reservation for network components if they are not defined.
• Gateway IP, first IP after the network IP address. Example: 192.168.0.0/24, network: 192.168.0.0, gateway: 192.168.0.1
• TOR, if two network devices are define each TOR will have a IP assigned. If a single TOR is defined, this will only have the Gateway IP address. If two TOR's are utilized, this would assume the two TORs are configured in a Cisco Nexus HSRP configuration. If more than 1 TOR is defined, each tor will be assigned a IP after the gateway IP address. if the gateway is 192.168.0.1, then TOR1 will be 192.168.0.2, and TOR2 wil lbe 192.168.0.3.
• Defaults always define the Network, Gateway and Broadcast IP addresses
• A supporting JSON will be required to define the network strucutre of the environemnt. If a subnet is defined in the supporting JSON and not included in the IPAssignment JSON then throw an error. the defined network need to match by network name.
• two independant JSON files will be used.
  • IPAddress JSON will be created from a supporting tool under tools/IPassignment powershell module.
  • EnvironmentDetailAssignement JSON will define the full IP payload of the environment. Network names will be used to match against. the names need to be unique.
    Operational details: Powershell based, logging so help debug errors when Verbose flags are utilzied. Config file t...

Created from VS Code via the [GitHub Pull Request](https://marketplace.visualstudio.com/items?itemName=GitHub.vscode-pull-request-github) extension.

---

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.