From d9eddcc09f9f49fc7458b40d036e8d33851e841e Mon Sep 17 00:00:00 2001 From: Alison Lomaka Date: Wed, 21 Jan 2026 18:30:01 -0500 Subject: [PATCH 1/2] Initial copilot setup, patterned off SbomToolkit implementation. --- .github/copilot-instructions.md | 1 + .gitignore | 4 + .memory-bank/AGENTS.md | 96 +++++++++++++++++++++ .vscode/settings.json | 5 ++ AGENTS.md | 145 ++++++++++++++++++++++++++++++++ Microsoft.Sbom.code-workspace | 12 +++ 6 files changed, 263 insertions(+) create mode 100644 .github/copilot-instructions.md create mode 100644 .memory-bank/AGENTS.md create mode 100644 .vscode/settings.json create mode 100644 AGENTS.md create mode 100644 Microsoft.Sbom.code-workspace diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 000000000..3910f8e3e --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1 @@ +## https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions#creating-repository-wide-custom-instructions-1 \ No newline at end of file diff --git a/.gitignore b/.gitignore index 1b159ab51..32ae695fa 100644 --- a/.gitignore +++ b/.gitignore @@ -3,6 +3,10 @@ ## ## Get latest from https://github.com/github/gitignore/blob/master/VisualStudio.gitignore +# Memory Bank (local agent context, not committed — except AGENTS.md) +.memory-bank/* +!.memory-bank/AGENTS.md + # User-specific files *.rsuser *.suo diff --git a/.memory-bank/AGENTS.md b/.memory-bank/AGENTS.md new file mode 100644 index 000000000..93296171d --- /dev/null +++ b/.memory-bank/AGENTS.md @@ -0,0 +1,96 @@ +# Memory Bank Templates + +This directory contains persistent context for AI agents across chat sessions. +For operational workflow, see [root AGENTS.md](../AGENTS.md#memory-bank). + +Files in this folder (except this AGENTS.md) are git-ignored — each developer +maintains their own local context. + +## Required Files + +**If any file is missing, create it using the templates below.** + +| File | Purpose | Update Frequency | +|------|---------|------------------| +| `activeContext.md` | Current task, recent changes, next steps, active decisions | After each step | +| `learnings.md` | Technical patterns, known issues, code structure | When patterns discovered | +| `userDirectives.md` | User preferences, style rules, boundaries | Rarely (user-driven) | + +## File Templates + +If any file is missing, create it using the templates below. + +### `activeContext.md` + +```markdown +# Active Context + +## Current Work Focus +[Description of current task/feature being worked on] + +## Recent Changes +- ✅ Completed items with checkmark +- ☐ Pending items with empty checkbox + +## Active Decisions +[Key architectural or implementation decisions made during this work] + +## Next Steps +1. ☐ Step description +2. ☐ Step description + +## Current State +[Summary of where we are in the implementation] +``` + +### `learnings.md` + +```markdown +# Project Learnings + +## Code Structure + +### NormalizedEntities +- `NormalizedBuildDocument` is the root document model +- Format-agnostic; SPDX-specific logic stays in adapters +- When adding fields, must update both SPDX 2.x and 3.x adapters + +### Adapters +- SPDX 2.2: stable, avoid breaking changes +- SPDX 3.0: under active development, JSON-LD format + +### CLI +- Thin layer over Core workflows +- No business logic here; delegate to workflows + +## Known Issues +- [Document any known bugs, quirks, or workarounds] + +## Patterns Discovered +- [Document patterns learned during development] + +## Technical Decisions +- [Document significant architectural decisions and rationale] +``` + +### `userDirectives.md` + +```markdown +# User Directives + +## Response Style +- [Preferred tone, verbosity, format preferences] + +## Behavioral Boundaries +- [Things the agent should never do] + +## Priorities +- [What matters most: speed vs quality, minimal vs comprehensive, etc.] + +## Project-Specific Rules +- [Any additional rules specific to how you want to work] +``` + +## Workflow + +See [root AGENTS.md](../AGENTS.md#memory-bank) for operational workflow instructions. diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 000000000..e354dff5c --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,5 @@ +{ + // Enable automatic discovery of nested AGENTS.md files for GitHub Copilot + // See: https://code.visualstudio.com/docs/copilot/customization/custom-instructions#_use-multiple-agentsmd-files-experimental + "chat.useNestedAgentsMdFiles": true +} diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..229ecf1b7 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,145 @@ +# SBOM Tool Agent Instructions + +This repository contains the Microsoft SBOM Tool, a .NET 8 solution for generating +SPDX 2.2 and SPDX 3.0 compatible Software Bill of Materials (SBOM) files. + +## Repository Structure + +- `src/Microsoft.Sbom.Api/` - Core API for SBOM generation and validation +- `src/Microsoft.Sbom.Common/` - Shared utilities and abstractions +- `src/Microsoft.Sbom.Contracts/` - Public contracts and interfaces +- `src/Microsoft.Sbom.Parsers.Spdx22SbomParser/` - SPDX 2.2 format parser +- `src/Microsoft.Sbom.Parsers.Spdx30SbomParser/` - SPDX 3.0 format parser +- `src/Microsoft.Sbom.Tool/` - Standalone CLI executable +- `src/Microsoft.Sbom.DotNetTool/` - .NET global tool packaging +- `src/Microsoft.Sbom.Adapters/` - External format adapters +- `src/Microsoft.Sbom.Extensions/` - Extension points +- `src/Microsoft.Sbom.Extensions.DependencyInjection/` - DI integration +- `src/Microsoft.Sbom.Targets/` - MSBuild targets for SBOM generation +- `test/` - All test projects + +## Build and Test Commands + +- Build solution: `dotnet build Microsoft.Sbom.sln` +- Run all tests: `dotnet test Microsoft.Sbom.sln` +- Run specific tests: `dotnet test test/Microsoft.Sbom.Api.Tests/` + +## Technology Constraints + +- Target: .NET 8 (`net8.0`) +- Logging: Serilog +- CLI: Spectre.Console.Cli +- Mapping: AutoMapper +- Component Detection: Microsoft.ComponentDetection libraries +- Serialization: `System.Text.Json` preferred; `Newtonsoft.Json` for legacy compatibility + +## Development Guidelines + +- Prefer small, focused changes aligned with existing patterns +- Keep public APIs stable; prefer extending over breaking signatures +- Use `async`/`await` and `Task`-based methods for I/O +- Use guards (`ArgumentNullException.ThrowIfNull`) for public method arguments +- Fail fast for invalid inputs; validate early before expensive work +- Prefer `var` when type is obvious, otherwise explicit types +- Use `readonly` fields where practical + +## Filesystem and IO + +- Use abstractions over static `System.IO` methods where possible +- Avoid hardcoding absolute paths; use relative paths and `Path` helpers +- Code for cross-platform compatibility; avoid Windows-specific paths + +## Error Handling + +- Use clear, actionable error messages +- Surface validation issues as structured results, not only exceptions +- Do not log secrets, sensitive paths, or internal-only identifiers + +## Testing + +- All test projects use MSTest +- Run tests frequently during development +- Write tests for new functionality and bug fixes +- Test behavior, not implementation details + +## PR Guidelines + +- Propose minimal diffs that satisfy the request +- Suggest corresponding test updates for any behavior change +- Keep changes easy to rebase: small commits, clear intent +- Avoid generating large, intrusive refactors unless explicitly requested + +## Memory Bank + +> **Detailed memory file templates:** See [`.memory-bank/AGENTS.md`](.memory-bank/AGENTS.md) + +### Why This Matters + +AI agents are stateless—each conversation starts from zero context. The Memory Bank +creates persistent, structured context that survives across sessions. Without it, +you waste time re-explaining decisions, repeating patterns, and rediscovering issues. +Think of Memory Bank as the agent's project journal: with it, the agent becomes a +knowledgeable team member who remembers your project's unique context and decisions. + +### Files + +At the start of each session, read all files in `.memory-bank/`: + +| File | Purpose | Update Frequency | +|------|---------|------------------| +| `activeContext.md` | Current task, recent changes, next steps | After each step | +| `learnings.md` | Technical patterns, known issues, code structure | When patterns discovered | +| `userDirectives.md` | User preferences, style rules, boundaries | Rarely (user-driven) | + +### Workflow + +#### 1. Starting New Chat Sessions + + +**MANDATORY**: Before answering ANY user request or performing ANY work: + +1. Check if `.memory-bank/` directory exists with ALL three required files: + - `activeContext.md` + - `learnings.md` + - `userDirectives.md` +2. If ANY file is missing, **STOP and create it** using templates in [`.memory-bank/AGENTS.md`](.memory-bank/AGENTS.md) +3. Do NOT proceed with the user's request until Memory Bank is initialized + + +- Read ALL Memory Bank files to initialize your understanding +- If required files are missing, **STOP and create them** using templates in [`.memory-bank/AGENTS.md`](.memory-bank/AGENTS.md) +- If the current work focus has changed, clear `activeContext.md` before continuing +- Confirm Memory Bank is loaded: "📚 Memory Bank loaded — current focus: [topic]" + +#### 2. During Development + +- Follow patterns, decisions, and context documented in the Memory Bank +- **IMPORTANT:** When using tools (writing files, executing commands), preface the action + description with `MEMORY BANK ACTIVE: ` to signal you are operating based on established context + +**Mandatory Step Completion Tracking:** + +- **IMMEDIATELY** after completing ANY step from "Next Steps" in `activeContext.md`, + update the file to mark that step as completed (change ☐ to ✅) +- This update must happen **BEFORE** proceeding to the next step +- **Do NOT batch multiple step completions**—update after each individual step +- Also update the "Current State" section to reflect progress + +**Context Update Guidelines:** + +- Read the current `activeContext.md` before making updates to avoid corruption +- **If `activeContext.md` becomes malformed, STOP and completely rewrite it** with current accurate state +- Update `learnings.md` when discovering new patterns, issues, or technical decisions + +#### 3. Priority Rules + +- When Memory Bank conflicts with general knowledge, **always prioritize Memory Bank** +- Your ability to function effectively depends on the accuracy of the Memory Bank—maintain it diligently + +--- + +> **⚠️ REMINDER:** Memory Bank updates are MANDATORY after each completed step. +> Missing updates cause context rot and repeated work. + +> **⚠️ REMINDER:** If Memory Bank conflicts with general knowledge, +> ALWAYS prefer Memory Bank content. It contains project-specific context. diff --git a/Microsoft.Sbom.code-workspace b/Microsoft.Sbom.code-workspace new file mode 100644 index 000000000..0e8d876ef --- /dev/null +++ b/Microsoft.Sbom.code-workspace @@ -0,0 +1,12 @@ +{ + "folders": [ + { + "path": "." + } + ], + "settings": { + // Enable automatic discovery of nested AGENTS.md files for GitHub Copilot + // See: https://code.visualstudio.com/docs/copilot/customization/custom-instructions#_use-multiple-agentsmd-files-experimental + "chat.useNestedAgentsMdFiles": true + } +} From 10bc1fc32b71625ae6bd44c554b75ec2cb62e8ad Mon Sep 17 00:00:00 2001 From: Alison Lomaka Date: Thu, 22 Jan 2026 15:43:27 -0500 Subject: [PATCH 2/2] experimental - prompt for spinning up new feature work. --- .github/prompts/newfeature.prompt.md | 43 ++++++++++++++++++++++++++++ 1 file changed, 43 insertions(+) create mode 100644 .github/prompts/newfeature.prompt.md diff --git a/.github/prompts/newfeature.prompt.md b/.github/prompts/newfeature.prompt.md new file mode 100644 index 000000000..c2c53da53 --- /dev/null +++ b/.github/prompts/newfeature.prompt.md @@ -0,0 +1,43 @@ +--- +name: newfeature +agent: agent +description: Work with Copilot to define and implement a new feature. +--- + +# New Feature Implementation + +## Context + +You are implementing a new feature for the SBOM Tool. Follow the project's conventions and patterns. + +## Instructions + +CRITICAL! NO EXCEPTIONS! ALWAYS STRICTLY ADHERE TO THE FOLLOWING RULES. + +- You are my peer software developer - never run ahead of me, make sure I have reviewed and approved your last set of work before going ahead with the next one. This includes both drafting the initial set of tasks as well as implementing them. +- DO NOT CHANGE ANY CODE UNTIL I TELL YOU SO! Never run scripts or any tests until I explicitly direct you to do that. +- TREAT CLARIFICATION ANSWERS AS INFORMATION ONLY! When I answer a question, it is NOT an authorization to proceed with code changes. It is only information to update your understanding or the plan. +- USE TOOLS FIRST! When you need information (file locations, code structure, dependencies, command arguments), explore and gather facts using tools BEFORE asking questions. +- ASK ME ONLY ONE QUESTION AT A TIME! Do not proceed until I have answered. +- Before starting any new major step or milestone, fully reread these instructions, .github/copilot-instructions.md and ALL files with changes that are not in git yet. I don't care if your responses are slow - I always want the quality result. +- Before running any script or tool command, ALWAYS examine the arguments it requires and verify they match the current context or user requirements. Do not blindly run commands with default arguments. +- When you need user decisions or clarifications that tools cannot answer (ONLY after using tools to gather facts first), ask me clarification questions ONE AT A TIME. Continue the asking loop until the requirements are clear to you. + +## Workflow +- **FIRST STEP (before anything else):** Ask the user whether to clear the active context in `.memory-bank/activeContext.md`. If the user says yes, reset `activeContext.md` to a fresh template. If the user says no, continue with the existing context. +- Start by working with me to define and refine the feature scope and requirements. Ask clarification questions ONE AT A TIME until you have a complete understanding of what needs to be done. +- Once we have finalized the requirements, create a markdown document named `FEATURE-[short-feature-name].md` in the `./features/[short-feature-name]` directory, creating a subdirectory called `[short-feature-name]` if necessary. This document will outline the feature details, including: + - Feature Name + - Description + - User Stories + - Acceptance Criteria +- Once we have created the feature document, NEVER update it unless I explicitly direct you to do so. +- DO NOT start drafting PROPOSED IMPLEMENTATION STEPS until you have completed all research and I have answered all your clarification questions. +- Then proceed with generating details under PROPOSED IMPLEMENTATION STEPS in PLAIN ENGLISH describing logic and operations conversationally. Only include code snippets, function names, or technical syntax when absolutely necessary to avoid ambiguity. AVOID duplications. +- For each PROPOSED IMPLEMENTATION STEP, discuss and finalize the approach with me. +- When we have agreed on the PROPOSED IMPLEMENTATION STEPS, document them in the feature markdown file under a section titled "PROPOSED IMPLEMENTATION STEPS". +- After generating or updating PROPOSED IMPLEMENTATION STEPS, STOP! Do not proceed to execution. Ask for a final check and wait for my confirmation to start. +- Whenever updating code, ensure that steps below 'PROPOSED IMPLEMENTATION STEPS' are always updated as well. +- Every step in PROPOSED IMPLEMENTATION STEPS MUST have a status tag. Use [COMPLETED] for finished steps, [IN PROGRESS] for current work, or [] for pending steps. When updating PROPOSED IMPLEMENTATION STEPS, ALWAYS verify all steps have status tags and update them based on actual progress. +- To make sure we are done with the current step NEVER PROCEED TO THE NEXT STEP BEFORE I TELL YOU SO. +