Repurpose ProjectTemplate into a governance and workflow-audit catalog - #226
Merged
Conversation
Strip the buildable sample apps (CodeGen, Console, NuGetLibrary, PyPiLibrary, Benchmarks, Tests), the Docker image sources, and the .NET build infra (Directory.Build.props/.Packages.props, .slnx, dotnet-tools, .dockerignore). The repo becomes a governance + orchestration + audit-catalog repo. Extract the cSpell word list from the deleted workspace into a standalone cspell.json so the CLI and CI read the same config as the editor extension (linter parity). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Move branch rulesets out of .github/ (Actions-owned only) into repo-config/ with an idempotent configure.sh apply script, mirroring the downstream layout. Move the nine app-specific build/publish/codegen workflow tasks into catalog/snippets/workflows/ as inert reference (mapped to their WORKFLOW.md guarantees); keep only the source-only orchestrator set live. Move vscode-tasks, the Docker Hub readme, and the devcontainers into catalog/snippets. Reduce this repo's dependabot.yml to the github-actions ecosystem and keep the full multi-ecosystem config as a catalog reference. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Rewrite AGENTS.md's opening and layout for the audit-catalog identity, delete the five inheritance sections (Quick Start, Carry Verbatim, Staying in Sync, Personas, Known Downstream), and add the "durable guidance lives in committed docs, not agent memory" principle. Repoint moved-file and ruleset links to their new homes. Neutralize "synced verbatim" wording in WORKFLOW.md and the derived-repo drift-report note in copilot-instructions. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Rewrite the root README as this repo's own (purpose, how it operates, dev environment, TODO backlog, license), dropping the sample-app and derived-repo onboarding content. Add spec/readme-structure.md as the preferred README shape the audit checks fleet repos against. Expand repo-config/README.md with the salvaged GitHub setup reference: ruleset import, required secrets, repo settings, and the maintainer-only brownfield re-sign migration. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Author registry/repos.json (self + 7 cataloged + 14 backlog) and the spec manifests: project-types.json (per-type letter/intent checks plus cross-cutting workflow, branch-model, repo-setup, linter-parity, recurring-violations, and readme-structure dimensions), files.json (standardization baseline), and secrets.json (publish mechanism -> required/forbidden secrets). Each JSON check points at the prose section that owns the rationale. spec/validate.py is the dependency-free classification dry-run: it confirms every cataloged repo's types, publish mechanisms, and secrets classify against the spec. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
AUDIT.md defines the read-only per-repo audit: main as ground truth (develop divergence is a drift finding), type resolution from the registry, the applicability gate, per-dimension letter/intent checks, asserting the Actions implement WORKFLOW.md, the ruleset normalized-diff and secret checks, the verdict model (letter miss = drift, letter+intent miss = defect), and the report format. reports/_template.md is the report skeleton. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Add four mermaid diagrams to WORKFLOW.md section 3: the branch model, the PR smoke-feedback path, the two-phase publish matrix, and the artifact seam handoff. Configure cspell to skip mermaid blocks and add the technical words the docs use so cspell passes repo-wide, matching the markdownlint parity. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Rewrite test-pull-request.yml as a lint-only gate: markdownlint, cspell, actionlint, and jq/spec validation, all sharing the repo's own configs, behind the ruleset-bound Check pull request workflow status aggregator. Rewrite publish-release.yml as a self-contained source-only release (NBGV version then a tag + source archive + README + LICENSE per branch), and move the multi-target build-release-task and get-version-task orchestrators to the catalog as reference. Repoint the moved-orchestrator links in the docs. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Replace a non-ASCII section sign in the catalog workflows README, neutralize the last derived-repo phrasings in AGENTS.md and CODESTYLE.md, repoint the moved tasks.json and devcontainer links (CODESTYLE.md, docs/devcontainer.md), and normalize the repo-config rulesets to CRLF per .editorconfig. All docs pass markdownlint and cspell, workflows pass actionlint, spec/validate.py classifies the fleet cleanly, all relative links resolve, and the rulesets match the documented branch model (self-audit dogfood). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Document the rule in AGENTS.md and spec/readme-structure.md: every human-facing markdown file (all except AGENTS.md and copilot-instructions.md, which optimize for agents) uses reference-style links only, defined at the bottom of the file grouped by type under HTML-comment headers and alphabetized within each group. Convert README, CODESTYLE, WORKFLOW, AUDIT, the docs/ guides, the catalog and repo-config READMEs, and the Docker Hub README exemplar; reflow the docs I had hard-wrapped back to one paragraph per line. Add a human-readable Rules index to the README (short single-sentence rules grouped by always/never and by project type) as the reference for what agents enforce and audit. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
This PR repurposes the repository from a code template into a governance + workflow-audit catalog: it removes the sample application/code, introduces a registry/spec system for auditing a fleet of repositories, and reshapes CI/release automation to match a source-only documentation hub.
Changes:
- Remove the .NET/Python sample implementations (apps, libraries, tests, Docker build assets, solution/workspace/tooling scaffolding).
- Add a spec/registry/audit framework (schemas + manifests +
spec/validate.py) plus repo configuration artifacts underrepo-config/. - Update CI and publishing workflows to lint/validate docs/spec only and produce source-only GitHub releases.
Reviewed changes
Copilot reviewed 83 out of 104 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| WORKFLOW.md | Update workflow governance doc; add diagrams and convert links to reference-style. |
| Tests/Tests.csproj | Remove .NET test project from the repo. |
| Tests/SampleTest.cs | Remove sample unit tests. |
| Tests/LoggingTests.cs | Remove logging tests tied to removed sample library. |
| Tests/GlobalUsings.cs | Remove test global usings. |
| Tests/Fixture.cs | Remove test fixtures/collection definitions. |
| Tests/.editorconfig | Remove test-only analyzer overrides. |
| spec/validate.py | Add stdlib-only validator for registry/spec cross-references used by CI. |
| spec/secrets.schema.json | Add JSON schema for publish-mechanism secrets metadata. |
| spec/secrets.json | Add publish mechanism -> required/forbidden secret mapping used by audits/validation. |
| spec/readme-structure.md | Add fleet README structure specification for audit checks. |
| spec/project-types.schema.json | Add schema for project types + cross-cutting dimensions. |
| spec/files.schema.json | Add schema for baseline file/section expectations. |
| spec/files.json | Add baseline file/section catalog for fleet standardization checks. |
| reports/.gitkeep | Keep reports/ directory tracked. |
| reports/_template.md | Add audit report template used for per-repo audit outputs. |
| repo-config/README.md | Document committed repo/ruleset configuration layout and procedures. |
| repo-config/main.json | Provide canonical writable subset of main branch ruleset for audit/config. |
| repo-config/develop.json | Provide canonical writable subset of develop branch ruleset for audit/config. |
| repo-config/configure.sh | Add script to apply committed rulesets to a GitHub repository via API. |
| registry/repos.schema.json | Add JSON schema for fleet registry entries. |
| registry/repos.json | Add fleet registry listing cataloged and backlog repos plus audit metadata. |
| PyPiLibrary/tests/test_example.py | Remove Python sample tests. |
| PyPiLibrary/tests/init.py | Remove Python test package marker (sample removed). |
| PyPiLibrary/src/ptr727_projecttemplate_library/example.py | Remove sample Python module. |
| PyPiLibrary/src/ptr727_projecttemplate_library/_version.py | Remove Python version stub tied to removed sample package. |
| PyPiLibrary/src/ptr727_projecttemplate_library/init.py | Remove sample package init. |
| PyPiLibrary/README.md | Remove PyPI template library documentation. |
| PyPiLibrary/pyproject.toml | Remove Python package project configuration. |
| ProjectTemplate.slnx | Remove solution definition for removed .NET projects/workflow grouping. |
| ProjectTemplate.code-workspace | Remove VS Code workspace for removed template code layout. |
| NuGetLibrary/Options.cs | Remove sample library options type. |
| NuGetLibrary/NuGetLibrary.csproj | Remove sample NuGet library project. |
| NuGetLibrary/LogOptions.cs | Remove sample logging options implementation. |
| NuGetLibrary/Library.cs | Remove sample library surface area. |
| NuGetLibrary/GlobalUsings.cs | Remove sample global usings. |
| NuGetLibrary/Extensions.cs | Remove sample logging extensions. |
| NuGetLibrary/.editorconfig | Remove sample library analyzer overrides. |
| docs/ssh-signing.md | Convert links to reference-style; keep signing guidance consistent. |
| docs/host-setup.md | Convert links to reference-style; keep host setup guidance consistent. |
| docs/devcontainer.md | Repoint devcontainer references to catalog snippet locations; update links. |
| Docker/Version.sh | Remove sample Docker image helper script. |
| Docker/InstallDebugTools.sh | Remove sample Docker debug tooling installer script. |
| Docker/Dockerfile | Remove sample Dockerfile/build pipeline for removed code. |
| Docker/Build.sh | Remove sample Docker build script for removed code. |
| Directory.Packages.props | Remove centralized NuGet package versions (no longer building .NET projects here). |
| Directory.Build.props | Remove centralized MSBuild properties (no longer building .NET projects here). |
| cspell.json | Add repository spell-check configuration for docs/spec linting. |
| Console/Program.cs | Remove sample console app entry point. |
| Console/LoggerFactory.cs | Remove sample console logging setup. |
| Console/GlobalUsings.cs | Remove sample console global usings. |
| Console/Extensions.cs | Remove sample console extensions. |
| Console/Console.csproj | Remove sample console project. |
| Console/CommandLine.cs | Remove sample System.CommandLine wiring. |
| Console/.editorconfig | Remove console-only analyzer overrides. |
| CodeGen/Program.cs | Remove sample codegen program. |
| CodeGen/HttpClientFactory.cs | Remove sample resilience HTTP client factory. |
| CodeGen/GlobalUsings.cs | Remove sample codegen global usings. |
| CodeGen/Extensions.cs | Remove sample codegen logging extensions. |
| CodeGen/CommandLine.cs | Remove sample codegen CLI. |
| CodeGen/CodeGenBuilder.cs | Remove sample generator implementation. |
| CodeGen/CodeGen.csproj | Remove sample codegen project. |
| CodeGen/CodeGen.cs | Remove sample generated output file. |
| CodeGen/AssemblyInfo.cs | Remove sample assembly info helper. |
| CodeGen/ApiNinjas.cs | Remove sample external API integration. |
| CodeGen/.editorconfig | Remove codegen-only analyzer overrides. |
| catalog/snippets/workflows/run-periodic-codegen-pull-request.yml | Add catalog snippet for scheduled codegen entry-point workflow. |
| catalog/snippets/workflows/run-codegen-pull-request-task.yml | Add catalog snippet for reusable codegen+PR task workflow. |
| catalog/snippets/workflows/README.md | Add mapping from workflow snippets to WORKFLOW.md guarantees. |
| catalog/snippets/workflows/publish-docker-readme-task.yml | Add catalog snippet for Docker Hub README publishing task. |
| catalog/snippets/workflows/get-version-task.yml | Add catalog snippet for NBGV version computation task. |
| catalog/snippets/workflows/check-upstream-version-task.yml | Add catalog snippet for upstream-version tracking task. |
| catalog/snippets/workflows/build-pypilibrary-task.yml | Add catalog snippet for building (not publishing) a PyPI package. |
| catalog/snippets/workflows/build-nugetlibrary-task.yml | Add catalog snippet for building/publishing a NuGet library. |
| catalog/snippets/workflows/build-executable-task.yml | Add catalog snippet for building an executable with a runtime matrix. |
| catalog/snippets/workflows/build-docker-task.yml | Add catalog snippet for building/pushing Docker images with registry caching. |
| catalog/snippets/workflows/build-datebadge-task.yml | Add catalog snippet for BYOB “last build” badge generation. |
| catalog/snippets/devcontainer/python/post-create.sh | Add catalog snippet for pinned-uv Python devcontainer post-create script. |
| catalog/snippets/devcontainer/python/devcontainer.json | Add catalog snippet for Python devcontainer definition. |
| catalog/snippets/devcontainer/dotnet/post-create.sh | Add catalog snippet for .NET devcontainer post-create script. |
| catalog/snippets/devcontainer/dotnet/devcontainer.json | Add catalog snippet for .NET devcontainer definition. |
| catalog/snippets/configs/vscode-tasks.json | Add catalog snippet for VS Code tasks (clean-compile + convenience tasks). |
| catalog/snippets/configs/docker-hub-readme.md | Update Docker Hub README exemplar to use reference-style links. |
| catalog/snippets/configs/dependabot.yml | Add multi-ecosystem dual-target Dependabot config exemplar. |
| catalog/README.md | Add catalog index for snippets and their intended use. |
| Benchmarks/SampleBenchmark.cs | Remove sample benchmarks. |
| Benchmarks/Program.cs | Remove benchmark entry point. |
| Benchmarks/GlobalUsings.cs | Remove benchmark global usings. |
| Benchmarks/Benchmarks.csproj | Remove benchmark project. |
| Benchmarks/.editorconfig | Remove benchmark-only analyzer overrides. |
| AUDIT.md | Add authoritative audit procedure for evaluating downstream repos against this hub. |
| .vscode/launch.json | Remove VS Code debug configurations tied to removed sample apps. |
| .github/workflows/test-pull-request.yml | Convert PR workflow to lint/spec-validation only with required aggregator. |
| .github/workflows/publish-release.yml | Convert release workflow to source-only GitHub releases (no build targets). |
| .github/dependabot.yml | Reduce Dependabot to GitHub Actions ecosystem only; point to catalog exemplar for full configs. |
| .github/copilot-instructions.md | Update Copilot instructions to match governance-hub model (no template inheritance). |
| .dockerignore | Remove Docker ignore rules tied to removed build outputs and Docker image workflow. |
| .config/dotnet-tools.json | Remove .NET local tools manifest (no longer building .NET projects here). |
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
Require targetMechanisms in secrets.schema.json (it was used by the validator but not required), and have spec/validate.py report a missing mechanisms / targetMechanisms / types key via the errors list instead of raising KeyError. Narrow the cspell ignore to reports/*/** so the maintained reports/_template.md is spell-checked while per-repo audit reports stay ignored. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
Add repos.json's top-level `repos` key to validate.py's required-key check and report an undefined target->mechanism mapping via the errors list rather than raising KeyError. In configure.sh, fetch the ruleset list once and fail loudly if the API call itself fails, so a failed fetch is never mistaken for "no ruleset exists" and silently turned into a create. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
…ner doc validate.py now flags a cataloged repo with no types (an unclassified entry would otherwise pass silently). Reframe docs/devcontainer.md: this repo ships no toolchain and keeps the two devcontainer definitions as catalog reference, so drop the removed *.code-workspace / PyPiLibrary references and present the SSH signing, bind-mount, and gh-auth mechanics as reference for a repo that uses them. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
Pin the markdownlint-cli2, cspell, and actionlint Docker images in test-pull-request.yml to specific digests (version in a trailing comment) so CI is reproducible and not exposed to a floating :latest. Add *.py to the LF pins in .editorconfig and .gitattributes so shebang scripts like spec/validate.py cannot drift to CRLF. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Uh oh!
There was an error while loading. Please reload this page.
configure.sh now uses gh api --paginate for the ruleset name lookup, so a repo with more rulesets than one page can't hide a match and cause a duplicate create. Still fails loudly if the list call itself fails. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
…ript validate.py now defensively handles every repo entry: non-object entries, a missing status, an unknown status, and malformed publish entries all produce an actionable error instead of a KeyError/traceback, and the summary counts guard their field access. configure.sh takes the first ruleset when a name has duplicates (drift) and warns rather than PUTting to a multi-id URL. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Uh oh!
There was an error while loading. Please reload this page.
Guard the duplicate-name count on non-empty ids: grep -c exits non-zero on empty input, which under set -euo pipefail would abort the script in the common "no ruleset yet, create it" path. Now an empty match falls through to create. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
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 freeto 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.
Abandons the template-inheritance model and converts this repo into a documentation, agent-orchestration, and workflow-audit catalog. Each fleet project now owns its own implementation and is audited against the ground truth here, rather than copying files from a template.
Highlights
repo-config/(withconfigure.sh) since.github/is Actions-owned; the app-specific build/publish/codegen workflows and config exemplars move tocatalog/snippets/.spec/readme-structure.md, the fleet README exemplar); salvage the GitHub-setup/ruleset/brownfield procedures intorepo-config/README.md.registry/repos.json(self + 7 cataloged + 14 backlog),spec/project-types.json(per-type letter/intent checks plus cross-cutting linter-parity, recurring-violations, branch-model, secrets, readme-structure),files.json,secrets.json, JSON schemas, andspec/validate.py(dependency-free classification dry-run).test-pull-request.ymlis now lint-only (markdownlint + cspell + actionlint + spec validation) behind the ruleset-bound aggregator;publish-release.ymlis a self-contained source-only release. The repo classifies as the source-only type and audits itself.Verification
markdownlint 0, cSpell 0, actionlint clean,
spec/validate.pyclassifies the fleet, all relative links resolve, EOL/charset clean, and the self-audit confirms the rulesets match the documented branch model.🤖 Generated with Claude Code