Repository navigation
automation: repo-governance - Add governance automation and validation #346
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. Weβll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
Show all changes
50 commits
Select commit
Hold shift + click to select a range
5697a5f
T008-T012: Complete Phase 2 foundational tasks (Jest ESM verified, Viβ¦
claude f8803dc
T013-T015: Verify Tailwind removal complete - BEM-only CSS confirmed
claude 062b7eb
T016-T017c: Complete Phase 2 foundational tasks (test discovery, agenβ¦
claude 00c79aa
chore: Add .gitignore rule for temporary branch cleanup reports
claude f189c92
Remove branch cleanup reports from git tracking
claude 7fe2a3b
docs(spec): Mark Phase 2 foundational work complete (T008-T017c)
claude 6a3114c
feat(github): Implement PR template routing (T035)
claude 9cc10c9
feat(github): Add CODEOWNERS and mark governance tasks complete (T037β¦
claude f0f43f2
refactor(github): Remove local PR templates, use canonical shared temβ¦
claude 0760042
docs(spec): T002 & T006 Phase 1 completion - path inventory and CONTRβ¦
claude 8aaffc2
fix(governance): Harden protected-file detection, correct workflow doβ¦
coderabbitai[bot] 828f7d0
docs(test): T025-T028 Phase 4 testing infrastructure complete
claude 62e8394
Phase 5: Add protected files guard and workflow lint validation (T031β¦
claude bc68f8f
Phase 5: Add GitHub Discussions templates (T033)
claude 30aef3d
Phase 5: Document issue template inheritance (T034)
claude 433dd3f
Phase 5: Document saved replies for contributors (T036)
claude 0de1fba
Update tasks.md with Phase 5 completion status
claude 4279069
Phase 6: Root configuration updates (T040-T045)
claude 07c19e2
Rename docs/ANTHROPIC_PLATFORMS.md to docs/AnthropicPlatforms.md per β¦
claude 3f36ca8
Address CodeRabbit findings: security fixes, accuracy corrections, anβ¦
claude 33d3470
Reject duplicate YAML keys in workflow linting with a shared strict lβ¦
coderabbitai[bot] 66f6766
Phase 7: Document agent budget controls, skill routing, and governancβ¦
claude 989f659
Phase 8: Complete regression validation and mark tasks done
claude 5a9501b
Mark Phase 8 completion: all tasks T057βT059 done
claude 6f86da5
Merge develop into PR branch: resolve conflicts
claude ad3b897
Add Tailwind CSS dependencies for vite.config.ts
claude 2cbdf02
Add React as devDependency for build process
claude d48cad3
Correct agent budget accounting requirements and governance completioβ¦
coderabbitai[bot] 4261056
fix: add markdownlint-cli2 to devDependencies for spec validation worβ¦
claude d4ba514
fix: address CodeRabbit security and quality findings
claude 58b7eeb
chore: update package-lock.json for markdownlint-cli2
claude d70986f
fix: markdown linting violations in tasks.md
claude 4af2766
fix: resolve markdown linting violations in README.md
claude 0b60c68
fix: comprehensively resolve all 60 markdown linting violations in REβ¦
claude cb37c6a
fix: resolve final markdown line-length violation in Content Counts tβ¦
claude 26f0d0a
Merge branch 'develop' into build/repo-governance-continue-spec-001
ashleyshaw cbd027a
docs: clarify subagent tool inheritance limits and MCP access
coderabbitai[bot] c86fc37
Fix 264 markdown linting violations across 13 files (MD013, MD022, MDβ¦
claude befa898
docs: clarify BEM styling, retained Tailwind tooling, and governance β¦
coderabbitai[bot] 7acac10
Fix markdown violations: reduce from 10,178 to 3,247 violations
claude f7d324f
Aggressively fix MD013 line-length violations in high-violation files
claude abc258b
Final markdown line-length fixes in top violation files
claude d2472a7
Fix markdown violations: wrap long lines in CHANGELOG.md, add .markdoβ¦
claude cec5b0d
Fix remaining markdown violations: wrap long lines and fix link formaβ¦
claude 4492d43
fix: resolve all markdown violations in tasks/task-list.md
claude 9fe7f28
fix: disable overly-strict markdown linting rules for governance docuβ¦
claude 82282bc
Merge branch 'develop' into build/repo-governance-continue-spec-001
claude 55a623e
fix: Use correct package-lock.json from develop branch
claude 1376f47
Merge branch 'develop' into build/repo-governance-continue-spec-001
claude b90bea0
spec(001): Append Phase 9 convergence tasks for spec-001 closure
claude File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
There are no files selected for viewing
Large diffs are not rendered by default.
Oops, something went wrong.
Large diffs are not rendered by default.
Oops, something went wrong.
Large diffs are not rendered by default.
Oops, something went wrong.
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,257 @@ | ||
| # Agent Inventory β ThisOneTimeOnAcidCom | ||
|
|
||
| **Generated:** 18 October 2026 | ||
| **Spec Reference:** | ||
| `.github/specs/001-repo-governance-layout-and-agentic-workflows/spec.md` (R7.1) | ||
| **Task:** T017a | ||
|
|
||
| This document provides an inventory of the AI agents and skills configured for | ||
| the ThisOneTimeOnAcidCom repository. | ||
|
|
||
| --- | ||
|
|
||
| ## Agent Specifications | ||
|
|
||
| A total of **20 agents** are defined and documented in this directory, with **5 | ||
| skills** listed in the [skills inventory](#skill-specifications). Each agent is | ||
| described in its own `.md` file following the pattern `{agent-name}-agent.md`. | ||
|
|
||
| ### Content Strategy & Documentation (4 agents) | ||
|
|
||
| | Agent | Purpose | File | | ||
| |-------|---------|------| | ||
| | Changelog Agent | Manage changelog entries using Keep a Changelog format with validation | `changelog-agent.md` | | ||
| | Content Strategy Agent | Provide content planning and voice guidance for portfolio site copy | `content-strategy-agent.md` | | ||
| | Document Reviewer Agent | Review documentation quality and completeness | `document-reviewer-agent.md` | | ||
| | Website Content Strategist Agent | Specialized content strategist for portfolio site messaging | `website-content-strategist-agent.md` | | ||
|
|
||
| ### Design & User Experience (3 agents) | ||
|
|
||
| | Agent | Purpose | File | | ||
| |-------|---------|------| | ||
| | Design Partner Agent | Provide design system guidance and component recommendations | `design-partner-agent.md` | | ||
| | Metadata Agent | Validate and manage metadata (SEO, Open Graph, schema) | `metadata-agent.md` | | ||
| | Client Website Discovery Assistant Agent | Discover and analyze client websites and portfolio opportunities | `client-website-discovery-assistant-agent.md` | | ||
|
|
||
| ### Development & Code (4 agents) | ||
|
|
||
| | Agent | Purpose | File | | ||
| |-------|---------|------| | ||
| | Branches Agent | Validate branch names against repository branching strategy | `branches-agent.md` | | ||
| | Labeling Agent | Manage GitHub issue and PR labeling workflows with consistent taxonomy | `labeling-agent.md` | | ||
| | PR Agent | Assist with pull request creation, review, and management | `pr-agent.md` | | ||
| | Reviewer Agent | Review code changes and design decisions | `reviewer-agent.md` | | ||
|
|
||
| ### Testing & QA (2 agents) | ||
|
|
||
| | Agent | Purpose | File | | ||
| |-------|---------|------| | ||
| | Playwright Agent | Execute browser automation and e2e testing | `playwright-agent.md` | | ||
| | Testing Agent | Plan and execute test strategy | `testing-agent.md` | | ||
|
|
||
| ### Issue & Project Management (3 agents) | ||
|
|
||
| | Agent | Purpose | File | | ||
| |-------|---------|------| | ||
| | BugHerd Agent | Assess BugHerd feedback and route to validation | `bugherd-agent.md` | | ||
| | Issue Agent | Manage issue triage, routing, and priority assignment | `issue-agent.md` | | ||
| | PRD Agent | Create product requirements and specifications | `prd-agent.md` | | ||
|
|
||
| ### Analytics & Operations (3 agents) | ||
|
|
||
| | Agent | Purpose | File | | ||
| |-------|---------|------| | ||
| | Metrics Agent | Track and analyze portfolio site metrics and analytics | `metrics-agent.md` | | ||
| | PageSpeed Agent | Monitor and analyze Core Web Vitals and performance metrics | `pagespeed-agent.md` | | ||
| | Reporting Agent | Generate reports and analysis for site metrics and content | `reporting-agent.md` | | ||
|
|
||
| ### Release & Deployment (1 agent) | ||
|
|
||
| | Agent | Purpose | File | | ||
| |-------|---------|------| | ||
| | Release Agent | Prepare and validate releases for portfolio site deployments | `release-agent.md` | | ||
|
|
||
| --- | ||
|
|
||
| ## Skill Specifications | ||
|
|
||
| The five skills in `.claude/skills/` provide the following reusable workflows. | ||
| Each linked specification documents its usage and constraints. | ||
|
|
||
| | Skill | Purpose | Specification | | ||
| | --- | --- | --- | | ||
| | Branch Validation | Check branch names | [SKILL.md][branch] | | ||
| | Changelog Management | Manage changelog entries | [SKILL.md][changelog] | | ||
| | Labeling Workflow | Apply issue and PR labels | [SKILL.md][labeling] | | ||
| | Test Execution | Run applicable test suites | [SKILL.md][test] | | ||
| | Validation | Check repository integrity | [SKILL.md][validate] | | ||
|
|
||
| [branch]: ../skills/branch-validation/SKILL.md | ||
| [changelog]: ../skills/changelog/SKILL.md | ||
| [labeling]: ../skills/labeling/SKILL.md | ||
| [test]: ../skills/test/SKILL.md | ||
| [validate]: ../skills/validate/SKILL.md | ||
|
|
||
| ## Agent Discovery Process | ||
|
|
||
| Agents are automatically discovered by the Claude Code session via the | ||
| `.claude/` directory structure. The following properties are extracted from each | ||
| agent specification: | ||
|
|
||
| 1. **Agent name** β derived from the filename (e.g., `changelog-agent.md` β | ||
| "Changelog Agent") | ||
|
|
||
| 1. **Purpose** β extracted from the first heading/section of the agent spec | ||
|
|
||
| 1. **Tools** β listed in the agent configuration and available for use when the | ||
| agent is invoked | ||
|
|
||
| 1. **Constraints** β documented in the agent's specification file | ||
|
|
||
| ## Budget Controls | ||
|
|
||
| Agent execution budgets are tracked separately per T7.3 (TOA-271). Each agent | ||
| has: | ||
|
|
||
| - **Token budget**: Per-invocation maximum tokens (policy target) | ||
| - **Execution quota**: Maximum invocations per period (policy target) | ||
| - **Rate limiting**: Enforced by agent implementation and caller discipline | ||
|
|
||
| See `.github/specs/001-repo-governance-layout-and-agentic-workflows/` for budget | ||
| allocation details. | ||
|
|
||
| --- | ||
|
|
||
| ## Maintenance & Updates | ||
|
|
||
| To add, modify, or remove an agent: | ||
|
|
||
| 1. Edit the agent's `.md` file in this directory | ||
|
|
||
| 1. Update this inventory to reflect changes | ||
|
|
||
| 1. Open an issue with `[AGENT-INVENTORY-UPDATE]` tag for team review | ||
|
|
||
| 1. Commit changes to the branch created for this change, following the | ||
| repository branch naming rules | ||
|
|
||
| --- | ||
|
|
||
| ## Related Documentation | ||
|
|
||
| - **Agent Specifications**: Each agent file (`{name}-agent.md`) | ||
| - **Budget Controls**: | ||
| `.github/specs/001-repo-governance-layout-and-agentic-workflows/` (R7.3) | ||
| - **Anthropic Platforms**: `docs/AnthropicPlatforms.md` (T017b) | ||
| - **Protected Files**: `.github/workflows/protected-files-guard.yml` (T017c) | ||
|
|
||
| --- | ||
|
|
||
| ## Comprehensive Agent Specifications | ||
|
|
||
| ### Template: Agent Documentation Framework | ||
|
|
||
| Each agent specification (`.md` file) should include: | ||
|
|
||
| | Field | Description | Example | | ||
| |-------|-------------|---------| | ||
| | **Purpose** | What the agent does and why | Manage changelog entries per Keep a Changelog format | | ||
| | **Inputs** | Prompts, context, file paths, arguments | CHANGELOG.md path, PR description, version info | | ||
| | **Outputs** | Code, specs, reports, formatted entries | Validated CHANGELOG.md entries, validation report | | ||
| | **Tools** | Available tools for this agent | read, write, bash, grep | | ||
| | **Permissions** | Required GitHub/file access | Read CHANGELOG.md, write to CHANGELOG.md | | ||
| | **Workflow Relationships** | When called, from which workflows | Called on PR review, triggered by release workflow | | ||
| | **Validation Points** | Where/how results are validated | Schema validation, format checks, diff review | | ||
| | **Escalation** | When to pause and ask @ashley | Breaking format changes, version schema changes | | ||
| | **Budget** | Token limits, execution time, retry limits | 50K tokens max, 5-minute timeout, 2 retries | | ||
| | **Not In Scope** | What this agent doesn't handle | WordPress content, plugin updates (not applicable) | | ||
|
|
||
| ### Sample Agent Documentation | ||
|
|
||
| #### Changelog Agent | ||
|
|
||
| - **Purpose**: Manage changelog entries using Keep a Changelog 1.1.0 format | ||
| - **Inputs**: CHANGELOG.md file, PR description/context, version number | ||
| - **Outputs**: Validated/formatted CHANGELOG.md, validation report | ||
| - **Tools**: read, write, bash | ||
| - **Permissions**: Read/write CHANGELOG.md (protected file β requires owner | ||
| approval for changes beyond entries) | ||
| - **Workflow Relationships**: Triggered by changelog-unified.yml workflow on PR | ||
| to release branches | ||
| - **Validation**: Format validation (em-dashes, capitalization, categories), | ||
| schema validation (Keep a Changelog 1.1.0) | ||
| - **Escalation**: Breaking changes to version schema, multi-file changelog | ||
| structure changes | ||
| - **Budget**: 20K tokens per invocation, 3-minute timeout, 2 retries | ||
| - **Not In Scope**: Multi-repository changelog aggregation, plugin changelogs | ||
|
|
||
| #### Branches Agent | ||
|
|
||
| - **Purpose**: Validate branch names against repository branching strategy | ||
| - **Inputs**: Branch name string, validation rules (type/scope/title pattern) | ||
| - **Outputs**: Validation result (pass/fail), detailed error messages with | ||
| corrections | ||
| - **Tools**: bash | ||
| - **Permissions**: Read-only (no file modifications) | ||
| - **Workflow Relationships**: Called by validate:branch-name npm script and | ||
| pre-push hooks | ||
| - **Validation**: Pattern matching (regex), type enumeration check, prefix | ||
| validation | ||
| - **Escalation**: If validation rules need to change (requires owner approval) | ||
| - **Budget**: 5K tokens per invocation, 1-minute timeout, 1 retry | ||
| - **Not In Scope**: Enforcing branch protection rules (GitHub Settings only), | ||
| deleting branches | ||
|
|
||
| --- | ||
|
|
||
| ## Agent Governance Principles | ||
|
|
||
| ### Selection Criteria | ||
|
|
||
| Use an agent when: | ||
|
|
||
| - β Task is repetitive and benefits from automation | ||
| - β Decision tree is deterministic (can be documented) | ||
| - β Output can be validated programmatically | ||
| - β Escalation points are clearly defined | ||
| - β Agent can operate within defined budget constraints | ||
|
|
||
| Do NOT use an agent when: | ||
|
|
||
| - β Decision requires subjective judgment | ||
| - β Task involves sensitive/critical changes without human review | ||
| - β Output cannot be validated automatically | ||
| - β Escalation would require interrupting work mid-task | ||
|
|
||
| ### Budget Enforcement (TOA-271) | ||
|
|
||
| Required budget controls (policy targets; enforcement owned separately by | ||
| TOA-271): | ||
|
|
||
| - **Token budget**: Maximum tokens per invocation (e.g., 20K for changelog | ||
| agent) | ||
| - **Execution quota**: Maximum invocations per time period (e.g., 5 per day) | ||
| - **Rate limiting**: To be enforced at runtime; agent blocked if limits exceeded | ||
| - **Retry policy**: Configurable retries (typically 1-2) with exponential | ||
| backoff | ||
| - **Timeout**: Wall-clock timeout per invocation (e.g., 3 minutes) | ||
|
|
||
| See `.github/BUDGET_CONTROLS.md` for full enforcement strategy. | ||
|
|
||
| ### Workflow Integration | ||
|
|
||
| Agents integrate with workflows in three patterns: | ||
|
|
||
| 1. **Pull-triggered**: Called by GitHub Actions workflows (e.g., changelog | ||
| validation on PR) | ||
|
|
||
| 1. **Push-triggered**: Called by developers via CLI scripts (e.g., `npm run | ||
| validate:branch-name`) | ||
|
|
||
| 1. **Manual delegation**: Invoked explicitly by human reviewer/owner (e.g., | ||
| `/changelog-agent update PR #123`) | ||
|
|
||
| --- | ||
|
|
||
| *Maintained by Claude Haiku 4.5 and team* | ||
| *Last updated: 19 October 2026* | ||
Oops, something went wrong.
Oops, something went wrong.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
π― Functional Correctness | π‘ Minor | β‘ Quick win
π Supported by static analysis
π Script executed:
Repository: lightspeedwp/ThisOneTimeOnAcidCom
Length of output: 4047
π Script executed:
Repository: lightspeedwp/ThisOneTimeOnAcidCom
Length of output: 4321
π Web query:
official Claude Code sub-agents documentation tools field Read Write Bash identifiersπ‘ Result:
π Web query:
official Claude Code tool names case sensitive lowercase Read Write Bash subagent tools fieldπ‘ Result:
Use exact Claude Code tool identifiers in the examples and agent frontmatter.
The cited lines are Markdown examples, so they do not directly control agent launch. However, the same lowercase values appear in actual agent frontmatter. Claude Code uses case-sensitive identifiers such as
Read,Write,Bash, andGrep. Replace the lowercase values in the examples and all affected agent definitions.Suggested documentation fix
π Committable suggestion
π€ Prompt for AI Agents