docs(architecture): add architecture documentation and value proposition#252
Merged
WilliamBerryiii merged 7 commits intomainfrom Jan 24, 2026
Merged
Conversation
- add docs/architecture/ with component relationships and CI/CD docs - add docs/README.md as documentation hub - update root README with enterprise framework positioning - fix artifact counts to match actual codebase 📚 - Generated by Copilot
Contributor
Dependency Review✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.Scanned FilesNone |
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #252 +/- ##
==========================================
+ Coverage 28.77% 28.83% +0.06%
==========================================
Files 14 14
Lines 2735 2736 +1
==========================================
+ Hits 787 789 +2
+ Misses 1948 1947 -1
Flags with carried forward coverage won't be shown. Click here to find out more.
🚀 New features to boost your workflow:
|
Contributor
There was a problem hiding this comment.
Pull request overview
This PR adds comprehensive architecture documentation to satisfy OSSF Silver badge compliance requirements by creating a docs/architecture/ directory with detailed descriptions of system components, CI/CD pipelines, testing infrastructure, and the AI artifacts hierarchy.
Changes:
- Creates architecture documentation hub with component diagrams and relationships
- Documents four-tier AI artifact delegation model (prompts, agents, instructions, skills)
- Details GitHub Actions CI/CD pipeline architecture with workflow inventory
- Documents PowerShell Pester test infrastructure with coverage configuration
- Adds
docs/README.mdas a navigation hub with audience-based guidance - Updates root
README.mdwith enterprise framework positioning and artifact counts
Reviewed changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/architecture/workflows.md | Comprehensive documentation of GitHub Actions CI/CD pipelines including PR validation, main branch, security, and publishing workflows |
| docs/architecture/testing.md | PowerShell Pester test infrastructure documentation including directory structure, configuration, utilities, and execution instructions |
| docs/architecture/ai-artifacts.md | Four-tier artifact system documentation covering prompts, agents, instructions, and skills with delegation flow and interfaces |
| docs/architecture/README.md | System architecture overview with component diagram, subsystem descriptions, and package relationships |
| docs/README.md | Documentation hub with audience-based navigation covering getting started, RPI methodology, prompt engineering, contributing, and architecture |
| README.md | Updated root README with enterprise framework positioning, accurate artifact counts, validation pipeline details, and enhanced project structure |
10 tasks
- add author field to docs/README.md and docs/architecture/*.md files - fix variable persistence bug in Validate-MarkdownFrontmatter.ps1 - add exclusions for .copilot-tracking and TEMPLATE files 🐛 - Generated by Copilot
- correct prompts count from 19 to 18 in README.md - remove misleading sequential arrows in workflows.md diagram - fix broken fragment link to #activation-context in docs/README.md 🔧 - Generated by Copilot
- remove bolded-prefix list items in ai-artifacts.md flow mechanics - replace em dash with N/A in README.md Scripts row - rewrite Key capabilities list without bold prefixes - rewrite validation system list without bold prefixes - fix link text mismatch in docs/README.md 📝 - Generated by Copilot
katriendg
approved these changes
Jan 23, 2026
Contributor
katriendg
left a comment
There was a problem hiding this comment.
Some minor comments, overall such a great addition to the docs!
bindsi
approved these changes
Jan 23, 2026
…iscovery - change Agents activation from '@mention' to 'agent picker' in README.md - remove @ prefix from prompt-builder agent reference - reword skills discovery to describe automatic context matching 🤖 - Generated by Copilot
- Add periods to complete sentence list items per writing style guidelines - Remove bold-prefix patterns from contribution points list - Change author to Microsoft for hve-core team consistency
29 tasks
WilliamBerryiii
added a commit
that referenced
this pull request
Jan 25, 2026
## Description Adds workflow-level concurrency controls to all three orchestrator workflows. This prevents unnecessary parallel runs when multiple commits are pushed in quick succession and reduces GitHub Actions resource consumption. **Changes:** - Added `concurrency` block to `pr-validation.yml` with `cancel-in-progress: true` to cancel stale PR validation runs when new commits arrive - Added `concurrency` block to `main.yml` with `cancel-in-progress: false` to prevent cancellation of main branch builds - Added `concurrency` block to `weekly-security-maintenance.yml` with `cancel-in-progress: false` for scheduled job protection - Updated `.cspell/general-technical.txt` with missing dictionary terms (`carryforward`, `SCHED`, `SECCHECK`) that were causing pre-existing spell-check failures ## Related Issue(s) Fixes #274 ## 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:** - [x] GitHub Actions workflow - [x] 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`) > **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. > - **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](../docs/contributing/custom-agents.md#agents-not-accepted) and [Model Version Requirements](../docs/contributing/ai-artifacts-common.md#model-version-requirements). **Other:** - [ ] Script/automation (`.ps1`, `.sh`, `.py`) - [ ] Other (please describe): ## Sample Prompts (for AI Artifact Contributions) N/A - This PR does not include AI artifacts. ## Testing - [x] YAML lint validation passes (`npm run lint:yaml`) - [x] Spell check passes (`npm run spell-check`) ## Checklist ### Required Checks - [ ] Documentation is updated (if applicable) - [x] Files follow existing naming conventions - [x] Changes are backwards compatible (if applicable) - [ ] Tests added for new functionality (if applicable) ### AI Artifact Contributions N/A ### 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` - [ ] Link validation: `npm run lint:md-links` - [ ] PowerShell analysis: `npm run lint:ps` ## Security Considerations - [x] This PR does not contain any sensitive or NDA information - [ ] Any new dependencies have been reviewed for security issues - [x] Security-related scripts follow the principle of least privilege ## Additional Notes ### Concurrency Configuration Patterns | Workflow | Group Key | Cancel In-Progress | Rationale | |----------|-----------|-------------------|-----------| | `pr-validation.yml` | `workflow-head_ref` | `true` | Cancel stale PR runs when new commits arrive | | `main.yml` | `workflow-ref` | `false` | Protect main branch builds from cancellation | | `weekly-security-maintenance.yml` | `workflow` | `false` | Single weekly job, no ref variation needed | ### Dictionary Updates Fixed pre-existing spell-check gaps that passed CI due to timing: - `carryforward` - Codecov configuration term (PR #250) - `SCHED`, `SECCHECK` - Mermaid diagram labels (PR #252) ⚡ - Generated by Copilot
WilliamBerryiii
pushed a commit
that referenced
this pull request
Jan 28, 2026
🤖 I have created a release *beep* *boop* --- ## [2.0.0](hve-core-v1.1.0...hve-core-v2.0.0) (2026-01-28) ### ⚠ BREAKING CHANGES * **agents:** add Task Reviewer and expand RPI to 4-phase workflow ([#277](#277)) ### ✨ Features * **agents:** add hve-core-installer agent to extension package ([#297](#297)) ([c0e48c6](c0e48c6)) * **agents:** add Task Reviewer and expand RPI to 4-phase workflow ([#277](#277)) ([ae76cab](ae76cab)) * **build:** add code coverage reporting to Pester workflow ([#230](#230)) ([a34822a](a34822a)) * **docs:** add GOVERNANCE.md for OSSF Silver Badge compliance ([#235](#235)) ([b0e752c](b0e752c)) * **docs:** add ROADMAP.md for OSSF Silver badge compliance ([#238](#238)) ([4a41c16](4a41c16)) * **mcp:** add MCP server configuration guidance and installer enhancements ([#225](#225)) ([0bce418](0bce418)) * **scripts:** add YAML linting with actionlint ([#234](#234)) ([d9301f9](d9301f9)) * **security:** add OpenSSF Scorecard workflow and badge ([#271](#271)) ([7c6d788](7c6d788)) * **skills:** add video-to-gif conversion skill with FFmpeg two-pass optimization ([#247](#247)) ([8d65c42](8d65c42)) * **tests:** add Pester tests for LintingHelpers and Validate-MarkdownFrontmatter ([#197](#197), [#198](#198)) ([#205](#205)) ([51ae563](51ae563)) ### 🐛 Bug Fixes * **build:** detect table formatting changes via git diff ([#261](#261)) ([985eee0](985eee0)) * **build:** disable MD024 lint rule in CHANGELOG for release-please ([#220](#220)) ([971df94](971df94)) * **build:** quote shell variables and group redirects in workflow files ([#299](#299)) ([3372509](3372509)) * **build:** resolve scorecard badge and workflow security issues ([#301](#301)) ([aeaed13](aeaed13)) * **extension:** remove frontmatter from README and exclude from markdown linting ([#223](#223)) ([4272529](4272529)) * **instructions:** quote applyTo glob pattern for YAML compatibility ([#216](#216)) ([085199c](085199c)) * **scripts:** add FooterExcludePaths parameter to frontmatter validation ([#334](#334)) ([64db98d](64db98d)) * **scripts:** add GHSA word and logs/ exclusion to cspell config ([#214](#214)) ([5c99b3f](5c99b3f)) * **scripts:** correct type assertions in Invoke-YamlLint.Tests.ps1 ([#332](#332)) ([af7050d](af7050d)) * **scripts:** eliminate false positives in dependency pinning npm pattern ([#273](#273)) ([ccbdfa3](ccbdfa3)) * **security:** add artifact attestation for signed releases ([#257](#257)) ([c52d6e2](c52d6e2)) * standardize markdown footers and complete frontmatter ([#217](#217)) ([b4e7556](b4e7556)) ### 📚 Documentation * add OpenSSF Best Practices Passing badge to README ([#239](#239)) ([91bc529](91bc529)) * **architecture:** add architecture documentation and value proposition ([#252](#252)) ([0e4b02f](0e4b02f)) * **contributing:** add testing requirements for OSSF compliance ([#254](#254)) ([4db1a18](4db1a18)) * **docs:** add enterprise status badges to README header ([#270](#270)) ([ccb68a4](ccb68a4)) * **security:** add security assurance case and threat model for OSSF Silver ([#259](#259)) ([a390e26](a390e26)) ### ♻️ Refactoring * **application:** wrap execution with try blocks, ensure proper … ([#296](#296)) ([35c4417](35c4417)) * **scripts:** extract frontmatter validation to testable module ([#293](#293)) ([4e8707e](4e8707e)) * **scripts:** extract pure functions for Pester testability ([#221](#221)) ([d40e742](d40e742)) ### 🔧 Maintenance * **deps-dev:** bump cspell from 9.4.0 to 9.6.0 in the npm-dependencies group ([#208](#208)) ([855914b](855914b)) * **deps-dev:** bump cspell from 9.6.0 to 9.6.1 in the npm-dependencies group ([#294](#294)) ([1e45ad6](1e45ad6)) * **deps:** bump actions/setup-node from 6.1.0 to 6.2.0 in the github-actions group ([#209](#209)) ([c4c69e2](c4c69e2)) * **deps:** bump the github-actions group with 4 updates ([#295](#295)) ([d8337b8](d8337b8)) * remove step-security/harden-runner from workflows ([#246](#246)) ([c5708d8](c5708d8)) --- This PR was generated with [Release Please](https://github.com/googleapis/release-please). See [documentation](https://github.com/googleapis/release-please#release-please). Co-authored-by: hve-core-release-please[bot] <254602402+hve-core-release-please[bot]@users.noreply.github.com>
This was referenced Jan 28, 2026
This was referenced Feb 6, 2026
This was referenced Feb 13, 2026
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.
docs(architecture): add architecture documentation and value proposition
Description
Add comprehensive architecture documentation to satisfy OSSF Silver badge compliance requirements. This PR creates
docs/architecture/with component relationships, CI/CD pipeline documentation, test infrastructure details, and the four-tier artifact delegation model.Key changes:
docs/README.mdas the documentation hub with audience-based navigationdocs/architecture/README.mdwith system diagram and component summarydocs/architecture/ai-artifacts.mddocs/architecture/testing.mddocs/architecture/workflows.mdREADME.mdwith enterprise framework positioning and accurate artifact countsBug fix included:
Validate-MarkdownFrontmatter.ps1variable persistence bug where$isGitHubLocalpersisted across loop iterations, causing docs files to incorrectly skip validation when processed after.github/files without frontmatter.copilot-trackingand*TEMPLATE*files from docs validationRelated Issue(s)
Closes #240
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)> 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.> - 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:
.ps1,.sh,.py)Sample Prompts (for AI Artifact Contributions)
Testing
Documentation-only changes validated through:
npm run lint:md)npm run lint:frontmatter)npm run lint:md-links)npm run spell-check)Checklist
Required Checks
AI Artifact Contributions
Required Automated Checks
The following validation commands must pass before merging:
npm run lint:mdnpm run spell-checknpm run lint:frontmatternpm run lint:md-linksnpm run lint:psSecurity Considerations
No security impact. This PR adds documentation files only with no executable code changes.
Additional Notes
This PR addresses the OSSF Silver badge
documentation_architecturecriterion which requires projects to describe software architecture including components, interfaces, and data flow.Acceptance criteria from #240 satisfied:
Statistics: 6 files changed, 897 insertions(+), 17 deletions(-)
📚 - Generated by Copilot