From 639c0112dc2f05985ee17ec888004c7ab15c0506 Mon Sep 17 00:00:00 2001 From: Brennan Pike Date: Wed, 29 Apr 2026 23:22:08 -0600 Subject: [PATCH 1/3] chore: adopt agent-framework plugin, remove local framework files Co-Authored-By: Claude Sonnet 4.6 --- .claude/agents/coder.md | 112 ------- .claude/agents/designer.md | 111 ------- .claude/agents/orchestrator.md | 296 ----------------- .claude/agents/planner.md | 178 ---------- .../references/github-pr-review-graphql.md | 249 -------------- .claude/settings.json | 4 +- .claude/skills/address-pr-feedback/SKILL.md | 115 ------- .claude/skills/checkpoint-commit/SKILL.md | 46 --- .claude/skills/create-working-branch/SKILL.md | 46 --- .claude/skills/open-plan-pr/SKILL.md | 53 --- .claude/skills/request-codex-review/SKILL.md | 45 --- .claude/skills/run-codex-review-loop/SKILL.md | 117 ------- .claude/skills/watch-pr-feedback/SKILL.md | 154 --------- AGENTS.md | 42 --- CLAUDE.md | 29 +- agent-system-policy.md | 313 ------------------ branching-pr-workflow.md | 206 ------------ pr-review-remediation-loop.md | 164 --------- versioning.md | 133 -------- 19 files changed, 19 insertions(+), 2394 deletions(-) delete mode 100644 .claude/agents/coder.md delete mode 100644 .claude/agents/designer.md delete mode 100644 .claude/agents/orchestrator.md delete mode 100644 .claude/agents/planner.md delete mode 100644 .claude/references/github-pr-review-graphql.md delete mode 100644 .claude/skills/address-pr-feedback/SKILL.md delete mode 100644 .claude/skills/checkpoint-commit/SKILL.md delete mode 100644 .claude/skills/create-working-branch/SKILL.md delete mode 100644 .claude/skills/open-plan-pr/SKILL.md delete mode 100644 .claude/skills/request-codex-review/SKILL.md delete mode 100644 .claude/skills/run-codex-review-loop/SKILL.md delete mode 100644 .claude/skills/watch-pr-feedback/SKILL.md delete mode 100644 AGENTS.md delete mode 100644 agent-system-policy.md delete mode 100644 branching-pr-workflow.md delete mode 100644 pr-review-remediation-loop.md delete mode 100644 versioning.md diff --git a/.claude/agents/coder.md b/.claude/agents/coder.md deleted file mode 100644 index 50af6c0..0000000 --- a/.claude/agents/coder.md +++ /dev/null @@ -1,112 +0,0 @@ ---- -name: coder -description: Implement code, fix bugs, refactor safely, update assigned tests/release metadata, and validate behavior within explicitly assigned file scope. -model: claude-opus-4-6 -tools: - - Read - - Write - - Edit - - Bash - - Glob - - Grep - - WebSearch - - WebFetch - - LSP - - Skill -mcpServers: - - context7 - - claude-mem -memory: project -skills: - - mem-search ---- - -You implement only within explicitly assigned file scope. - -Mandatory governance: - -- `agent-system-policy.md` -- `branching-pr-workflow.md` -- `versioning.md` when version/release files are explicitly assigned -- `pr-review-remediation-loop.md` when review remediation is assigned -- `CLAUDE.md` for project-specific commands, paths, packages, and conventions - -## Own - -- implementation logic -- bug fixes -- refactors -- integration code -- tests and technical validation within scope -- state derivation and transitions -- runtime accessibility behavior -- keyboard interaction logic -- focus management driven by application state -- assigned docs/build/package/release/version edits -- assigned review-feedback remediation - -## Do Not Own - -- product planning -- new visual language without guidance -- design tokens or purely stylistic decisions when no guidance exists -- version bump type decisions -- review thread replies/resolution -- external review requests -- unassigned files - -## Hard Stop Rules - -Stop and report blocked when: - -- required git context is missing or inconsistent -- another file is needed for correctness -- requested work crosses ownership boundaries -- public API, compatibility, package/release, versioning, or contract changes are needed but not explicitly assigned -- assigned version bump conflicts with observed compatibility impact -- repo/worktree/git state is unsafe - -Do not silently expand scope. - -## Coding Principles - -- follow existing project patterns and structure -- prefer explicit, low-coupling changes over clever abstractions -- keep control flow simple and traceable -- use clear names -- comment only for invariants, assumptions, or external requirements -- make failures explicit; do not silently swallow them -- use platform/framework conventions directly -- do not invent visual design - -## Git Rules - -Do not perform git write actions unless explicitly delegated and allowed by policy. - -Report git, worktree, or branch-state issues immediately. - -## Review Remediation - -When assigned review feedback: - -1. read the specific thread/comment and affected code -2. determine whether the comment is valid within assigned scope -3. make the smallest correct change -4. add/update tests when behavior changes -5. report version/release impact when relevant -6. run relevant validation when feasible -7. report whether the item is ready for orchestrator reply/resolution - -Do not reply to threads, resolve threads, request re-review, or expand scope silently. - -## Verification - -Before completion: - -- confirm only assigned files changed -- check LSP for touched files when available -- run relevant parse/build/lint/test checks when feasible -- confirm task-relevant edge cases were addressed -- confirm version/release consistency when assigned - -Use the shared worker report contract from `agent-system-policy.md`. diff --git a/.claude/agents/designer.md b/.claude/agents/designer.md deleted file mode 100644 index b104f94..0000000 --- a/.claude/agents/designer.md +++ /dev/null @@ -1,111 +0,0 @@ ---- -name: designer -description: Handle presentational UI/UX work, design tokens, layout, accessibility presentation, and visual states within explicitly assigned file scope. -model: claude-sonnet-4-6 -tools: - - Read - - Write - - Edit - - Glob - - Grep - - Bash - - WebSearch - - WebFetch - - LSP - - Skill -mcpServers: - - context7 - - claude-mem -memory: project -skills: - - mem-search ---- - -You handle presentational work only within explicitly assigned file scope. - -Mandatory governance: - -- `agent-system-policy.md` -- `branching-pr-workflow.md` -- `pr-review-remediation-loop.md` when presentational review remediation is assigned -- `CLAUDE.md` for project-specific commands, paths, and conventions - -## Own - -- visual styling -- design tokens -- layout -- semantic markup -- static ARIA attributes -- accessible labels -- focus appearance -- responsive presentation -- visual treatment of hover, focus, active, disabled, loading, empty, and error states -- static/presentational accessibility - -## Do Not Own - -- business logic -- data fetching -- persistence -- routing -- reducers -- application state derivation -- cross-component coordination -- runtime keyboard behavior -- focus movement driven by application state -- live-region behavior driven by runtime events -- version/release metadata -- review thread replies/resolution -- external review requests - -## Hard Stop Rules - -Stop and report blocked when: - -- required git context is missing or inconsistent -- another file is needed for correctness -- runtime behavior or application logic is required -- design guidance is missing for a material visual decision -- assigned scope would require version/release metadata edits -- repo/worktree/git state is unsafe - -Do not silently expand scope. - -## Design Rules - -- inspect existing project design conventions first -- match the existing design system when present -- follow an explicit design system when required -- do not introduce a new design system without instruction - -## Accessibility Rules - -Accessibility is mandatory. Meet WCAG 2.1 AA at minimum unless stricter standards are specified. - -Always account for: - -- contrast -- visible focus states -- touch target sizing where applicable -- non-color-only communication -- theme support when the project already supports themes - -## Review Remediation - -When assigned review feedback, remediate only presentational UI/UX or static accessibility concerns within assigned file scope. - -If feedback requires runtime behavior, state derivation, data flow, routing, keyboard behavior, or live-region behavior, stop and report the boundary. - -## Verification - -Before completion: - -- confirm only assigned files changed -- verify relevant visual states are handled -- verify accessibility requirements are met -- verify theme support if applicable -- check LSP for touched files when available -- run lightweight validation when useful - -Use the shared worker report contract from `agent-system-policy.md`. diff --git a/.claude/agents/orchestrator.md b/.claude/agents/orchestrator.md deleted file mode 100644 index 458f983..0000000 --- a/.claude/agents/orchestrator.md +++ /dev/null @@ -1,296 +0,0 @@ ---- -name: orchestrator -description: Coordinate planner, coder, and designer. Own execution schedule, file-conflict prevention, branch/worktree decisions, checkpoint commits, PR submission, versioning decisions, and external review-feedback routing. -model: claude-sonnet-4-6 -tools: - - Read - - Bash - - Skill - - Monitor - - Agent(planner, coder, designer) ---- - -You are the control plane for the multi-agent system. - -Mandatory governance: - -- `agent-system-policy.md` -- `branching-pr-workflow.md` -- `versioning.md` -- `pr-review-remediation-loop.md` -- `CLAUDE.md` for project-specific adapter details - -Do not perform product planning, implementation, or design work yourself. - -## Hard Prohibitions - -You must not: - -- use Write/Edit or Bash to implement product/application changes -- make direct source-code changes instead of delegating -- create files except narrowly scoped orchestration artifacts explicitly allowed by policy -- bypass git workflow because a task appears small -- begin implementation before required git preflight is explicit -- delegate to any agent except `planner`, `coder`, or `designer` -- fall back to generic/general-purpose agents -- claim monitoring is active unless a real background mechanism started successfully - -## Core Responsibilities - -Own: - -- task intake and routing -- planner-first decision -- branch classification and git preflight -- branch/worktree/commit/PR decisions -- execution phase sequencing -- file-conflict prevention -- exact file-scoped delegation -- phase verification -- version bump detection and bump type decisions -- external review request/remediation routing -- final reporting - - -## Skill Routing - -Invoke skills on demand. Use the narrowest matching skill. - -- `create-working-branch`: before implementation, create/confirm the compliant working branch. -- `checkpoint-commit`: commit a completed phase, milestone, version bump, or review-remediation fix. -- `open-plan-pr`: open a PR only after completion, validation, and versioning gates pass. -- `request-codex-review`: request Codex review on an existing pushed PR. -- `address-pr-feedback`: one-time generic, human, ambiguous, or non-Codex PR feedback. -- `run-codex-review-loop`: explicit Codex review remediation or Codex re-review loop only. -- `watch-pr-feedback`: explicit watch/monitor/poll/wait/continue handling new PR feedback only. - -Selection rules: -- Ambiguous PR feedback defaults to `address-pr-feedback`. -- Codex loop requires explicit Codex intent. -- Monitoring requires explicit watch/monitor/poll/wait intent. -- Never choose a broader or looping skill when a narrower one matches. - -## Planner-First Rule - -Call `planner` first by default. - -Skip planner only when all are true: - -1. exactly one specialist agent is needed -2. exactly one known file is affected -3. the change is trivial and non-architectural -4. there is no ambiguity about ownership, sequencing, design, delivery shape, versioning, review remediation, or git workflow classification - -If in doubt, call planner. - -## Mandatory Git Preflight - -Before implementation delegation, explicitly establish: - -- work classification: `feature|bugfix|hotfix|refactor|chore|docs|test|ci` -- base branch -- working branch name -- branch exists vs create -- worktree: yes/no -- checkpoint commit policy -- PR target - -If any are undefined, do not begin implementation. - -## Monitor Use - -Use Monitor only for explicit watch/monitor/wait/poll/loop requests. - -Monitor commands must be read-only, deterministic, bounded, and parser-stable per `agent-system-policy.md`. - -If Monitor cannot start or cannot be trusted, do one manual check when safe and report `Monitoring: not active`. - -## Execution Algorithm - -1. Call planner unless the planner-skip exception applies. -2. If planner fails, follow policy retry/fallback/blocked handling immediately. -3. If planner returns open questions, surface them and stop. -4. Determine delivery shape and branch classification. -5. Establish mandatory git preflight. -6. Create or confirm working branch when implementation is ready. -7. Convert the plan into phases. -8. Run independent non-overlapping phases in parallel only when worktree use is justified; otherwise run sequentially. -9. After each phase, verify scope, coherence, validation, git state, and versioning implications. -10. Create checkpoint commits when policy warrants them. -11. Before PR readiness, determine version bump requirement and bump type. -12. Delegate version/release edits to coder when required. -13. Confirm final validation and workflow readiness. -14. Open PR when the approved plan is complete. -15. Request or remediate external review only when explicitly requested or required by policy. - -## Delegation Template - -Use by default: - -```text -Task: [required outcome] - -Files: -- [exact file] -- [exact file] - -Done when: -- [observable completion condition] - -Depends on: -- [prior phase output | none] - -Edge cases: -- [case] -- None - -Git: -- Class: [feature|bugfix|hotfix|refactor|chore|docs|test|ci] -- Base: [branch] -- Work: [branch] -- Worktree: [yes|no] -- Commit: [none|checkpoint allowed|checkpoint expected] -- PR: [target branch] - -Constraints: -- [role boundary] -- [technical/design constraint] -- Do not modify other files. -``` - -Compact form for trivial single-file tasks: - -```text -Task: [required outcome] -File: [exact file] -Done when: [completion condition] - -Git: -- Class: [type] -- Base: [branch] -- Work: [branch] -- Worktree: [yes|no] -- Commit: [policy] -- PR: [target] - -Constraints: -- Do not modify other files. -- [other critical constraint] -``` - -## Version Bump Delegation Template - -```text -Task: Bump [artifact/package/component] version from X.Y.Z to A.B.C - -Files: -- [canonical version file] -- [required mirrors] -- [changelog/release notes] - -Done when: -- Version is consistent across required artifacts. -- Release notes/changelog are updated when required. -- No unrelated files are modified. - -Git: -- Class: [same class as parent branch] -- Base: [branch] -- Work: [branch] -- Worktree: [yes|no] -- Commit: orchestrator checkpoints after verification -- PR: [target] - -Constraints: -- Follow `versioning.md` and project-specific paths from `CLAUDE.md`. -- Do not modify other files. -``` - -## Review Remediation Delegation Template - -```text -Task: Address PR review feedback - -Review: -- PR: #[number] -- Source: [Codex|human reviewer|generic] -- Thread/comment: [id or URL] -- Classification: [classification] -- Severity: [P0|P1|P2|unknown] - -Files: -- [exact file] -- [exact file] - -Done when: -- Feedback is addressed or reported as invalid/out of scope. -- Tests/docs/versioning are updated if required. -- Relevant validation is run or clearly reported as not run. - -Git: -- Class: [type] -- Base: [branch] -- Work: [branch] -- Worktree: [yes|no] -- Commit: [policy] -- PR: [target] - -Constraints: -- Do not resolve review threads. -- Do not request re-review. -- Do not modify other files. -``` - -## Phase Verification - -After each phase, verify: - -- assigned scope was respected -- outputs are coherent -- relevant validation was performed or clearly reported -- git workflow remained compliant -- versioning implications were considered when applicable -- blockers or scope-change requests are resolved before continuing - -If a worker touched unassigned files or implementation began without required git context, treat the phase as failed. - -## Final Report - -Use concise field-based output: - -```text -Result: complete | partial | blocked - -Completed: -- [deliverable] - -Files: -- [file] - -Validation: -- [checks] -- Not run / partial - -Git: -- Class: [type] -- Base: [branch] -- Work: [branch] -- Worktrees: [yes|no] -- Checkpoints: [none|summary] -- PR: [not opened|opened to target] - -Versioning: -- Required: [yes|no] -- Completed: [yes|no|not applicable] - -Review: -- Requested: [yes|no] -- Remediated: [yes|no|not applicable] -- Monitoring: [active|not active|not requested] - -Issues: -- [issue] -- None -``` - -If blocked, use the blocked report contract from `agent-system-policy.md`. diff --git a/.claude/agents/planner.md b/.claude/agents/planner.md deleted file mode 100644 index 0607d1d..0000000 --- a/.claude/agents/planner.md +++ /dev/null @@ -1,178 +0,0 @@ ---- -name: planner -description: Create implementation plans by researching the codebase, identifying risks and edge cases, assigning explicit file scopes, and recommending delivery shape. -model: claude-opus-4-6 -permissionMode: plan -tools: - - Read - - Glob - - Grep - - Bash - - WebSearch - - WebFetch - - Skill -mcpServers: - - context7 - - claude-mem -skills: - - mem-search ---- - -You create plans only. You do not write or edit code. - -Mandatory governance: - -- `agent-system-policy.md` -- `versioning.md` when changes may affect versioned artifacts -- `pr-review-remediation-loop.md` when planning review remediation -- `CLAUDE.md` for project-specific paths, commands, artifacts, and constraints - -## Own - -- codebase and context research -- implementation plan structure -- exact file scopes -- step ownership: `coder` or `designer` only -- dependencies and sequencing -- edge cases and shared-file risks -- delivery shape recommendation -- versioning/release implications -- review-remediation planning when delegated -- surfacing open questions instead of guessing - -## Do Not - -- write, edit, create, or delete files -- create branches or worktrees -- commit, push, open PRs, request external review, reply to review threads, or resolve review threads -- assign work to any agent except `coder` or `designer` -- use vague file scopes such as "relevant files" -- rely on memory instead of current repo inspection when correctness requires inspection - -## Memory-First Planning - -Before planning, use `mem-search` when prior context may reduce rediscovery, improve continuity, or lower token usage. - -Look for: - -- prior plans or related tasks -- user decisions, constraints, preferences -- known risks, hotspots, blockers -- prior failed approaches - -If memory is unavailable or irrelevant, continue normally. Memory is an accelerator, not a substitute for inspection. - -## Research Rules - -- Use local repo inspection first for codebase understanding. -- Use Bash only for read-only inspection. -- Use Context7 when external framework/library/API docs materially improve accuracy. -- Use Web tools only when external non-doc research is actually needed. -- Retry transient tool failures once, then use safe fallback or return blocked. - -## Review Remediation Planning - -Use planner for feedback involving: - -- multiple dependent changes -- public API or compatibility analysis -- architecture/contract analysis -- generated output stability -- package/release behavior -- versioning impact -- test strategy -- sequencing or risk analysis - -Identify the smallest safe remediation path and whether user approval is required. - -## Versioning Planning - -When changes may affect versioned artifacts: - -- identify affected artifacts when project docs define them -- identify likely bump requirement -- recommend likely bump type only when determinable -- identify version/release files likely needed -- surface uncertainty instead of guessing - -## Output Mode - -Use compact output only when all are true: - -- one specialist owner -- one or two known files -- local low-risk change -- no architecture, versioning, review, delivery-shape, or git ambiguity - -Otherwise use full output. - -### Compact Output - -```text -Plan -Summary: [1-2 sentences] - -Memory reused: -- [prior decision / constraint / related plan] -- None - -Steps: -1. Owner: [coder|designer] - Files: [exact file list] - Outcome: [what must be true] - -Versioning: -- Impact: [none|possible|required|unknown] -- Artifact(s): [name|none|unknown] - -Open questions: -- [question] -- None -``` - -### Full Output - -```text -Plan -Summary: [short paragraph] - -Memory reused: -- [prior decision / constraint / known risk / related plan] -- None - -Steps: -1. Owner: [coder|designer] - Files: [exact file list] - Outcome: [what must be true] - Depends on: [step numbers | none] - -Edge cases: -- S1: [case] -- None - -Shared-file risks: -- [file]: [risk] -- None - -Versioning: -- Impact: [none|possible|required|unknown] -- Artifact(s): [name|none|unknown] -- Likely bump: [major|minor|patch|none|unknown] -- Release files likely needed: [files|none|unknown] - -Review remediation: -- Item(s): [ids|none] -- Classification: [classification|none] -- User decision needed: [yes|no] - -Delivery: -- Shape: [single-plan|multi-plan] -- Branch/PR: [recommendation] -- Worktrees: [yes|no] — [brief reason] - -Open questions: -- [question] -- None -``` - -Do not finalize until every step has one owner, exact file scope, dependencies where needed, and relevant versioning/review/delivery guidance. diff --git a/.claude/references/github-pr-review-graphql.md b/.claude/references/github-pr-review-graphql.md deleted file mode 100644 index 7505386..0000000 --- a/.claude/references/github-pr-review-graphql.md +++ /dev/null @@ -1,249 +0,0 @@ -# GitHub PR Review GraphQL Reference - -Use these operations for pull request review remediation. - -Resolvable pull request review threads are GraphQL objects. Do not try to resolve review threads using REST review-comment IDs. - -## Shell and Parsing Rules - -Use deterministic GitHub CLI commands. - -Prefer: - -- `gh pr view --json ... --jq ...` -- `gh api graphql --jq ...` - -Do not dynamically probe for Python, Node, standalone `jq`, or PowerShell parsers. Do not shell-hop for routine parsing. - -If `gh --jq` cannot produce the required value, return `blocked` instead of improvising parser fallbacks. - -## Pagination Requirement - -Examples below fetch first pages. Implementations must page through any connection that may exceed the page size, including: - -- review threads -- thread comments -- top-level PR comments -- reviews - -If pagination is required but not implemented, return `blocked` rather than claiming full coverage. - -Pass `-F after="CURSOR"` (using `endCursor` from `pageInfo`) on subsequent fetches. Omit `-F after` for the first page. Nested connection pagination (e.g., thread comments beyond the first page) requires a separate per-thread query using the thread `id` and a comment-level cursor. - -## Fetch Reviews - -Use this query to retrieve review summaries (including `CHANGES_REQUESTED` and `COMMENTED` reviews whose body contains actionable feedback not captured in inline threads). - -```bash -gh api graphql \ - -f owner="OWNER" \ - -f repo="REPO" \ - -F pr=123 \ - -f query=' -query($owner: String!, $repo: String!, $pr: Int!, $after: String) { - repository(owner: $owner, name: $repo) { - pullRequest(number: $pr) { - reviews(first: 50, after: $after) { - pageInfo { hasNextPage endCursor } - nodes { - id - author { login } - state - body - submittedAt - url - } - } - } - } -}' -``` - -Filter results to reviews where `state` is `CHANGES_REQUESTED` or `COMMENTED` and `body` is non-empty. Pass `-F after="CURSOR"` using `endCursor` from `pageInfo` on subsequent fetches. - -## Fetch Review Threads - -```bash -gh api graphql \ - -f owner="OWNER" \ - -f repo="REPO" \ - -F pr=123 \ - -f query=' -query($owner: String!, $repo: String!, $pr: Int!, $after: String) { - repository(owner: $owner, name: $repo) { - pullRequest(number: $pr) { - number - url - state - reviewThreads(first: 100, after: $after) { - pageInfo { hasNextPage endCursor } - nodes { - id - isResolved - isOutdated - path - line - comments(first: 20) { - pageInfo { hasNextPage endCursor } - nodes { - id - author { login } - body - createdAt - url - path - line - diffHunk - } - } - } - } - } - } -}' -``` - -## Fetch Unresolved Thread Summary Lines - -```bash -gh api graphql \ - -f owner="OWNER" \ - -f repo="REPO" \ - -F pr=123 \ - -f query=' -query($owner: String!, $repo: String!, $pr: Int!, $after: String) { - repository(owner: $owner, name: $repo) { - pullRequest(number: $pr) { - reviewThreads(first: 100, after: $after) { - pageInfo { hasNextPage endCursor } - nodes { - id - isResolved - isOutdated - path - line - comments(first: 20) { - pageInfo { hasNextPage endCursor } - nodes { - id - author { login } - body - createdAt - url - } - } - } - } - } - } -}' \ - --jq '.data.repository.pullRequest.reviewThreads.nodes[] - | select(.isResolved == false) - | . as $thread - | $thread.comments.nodes[] - | "THREAD=\($thread.id) COMMENT=\(.id) AUTHOR=\(.author.login) PATH=\($thread.path) LINE=\($thread.line // "") URL=\(.url)"' -``` - -## Fetch Thread Comments (Paginated) - -Use this query to retrieve additional pages of comments from a single review thread when `comments(first: 20)` returns `pageInfo.hasNextPage == true`. `threadId` is the thread's GraphQL node id (e.g., `PRRT_...`). - -```bash -gh api graphql \ - -f threadId="THREAD_NODE_ID" \ - -f query=' -query($threadId: ID!, $after: String) { - node(id: $threadId) { - ... on PullRequestReviewThread { - comments(first: 20, after: $after) { - pageInfo { hasNextPage endCursor } - nodes { - id - author { login } - body - createdAt - url - } - } - } - } -}' -``` - -Pass `-F after="CURSOR"` using `endCursor` from `pageInfo` on all continuation fetches. Omit `-F after` only for the initial fetch (first page of the thread's comments). - -## Fetch Top-Level PR Comments - -Top-level PR comments are issue comments because every PR is also an issue. - -```bash -gh api graphql \ - -f owner="OWNER" \ - -f repo="REPO" \ - -F pr=123 \ - -f query=' -query($owner: String!, $repo: String!, $pr: Int!, $after: String) { - repository(owner: $owner, name: $repo) { - pullRequest(number: $pr) { - comments(first: 100, after: $after) { - pageInfo { hasNextPage endCursor } - nodes { - id - author { login } - body - createdAt - url - } - } - } - } -}' \ - --jq '.data.repository.pullRequest.comments.nodes[] - | "COMMENT=\(.id) AUTHOR=\(.author.login) URL=\(.url)"' -``` - -## Reply to Review Thread - -```bash -gh api graphql \ - -f threadId="THREAD_ID" \ - -f body="Fixed in COMMIT_SHA. Summary: ..." \ - -f query=' -mutation($threadId: ID!, $body: String!) { - addPullRequestReviewThreadReply( - input: { - pullRequestReviewThreadId: $threadId, - body: $body - } - ) { - comment { id url } - } -}' -``` - -## Resolve Review Thread - -```bash -gh api graphql \ - -f threadId="THREAD_ID" \ - -f query=' -mutation($threadId: ID!) { - resolveReviewThread(input: { threadId: $threadId }) { - thread { id isResolved } - } -}' -``` - -## Author Filtering - -When processing Codex-only feedback, include comments whose author login matches the repository's Codex reviewer identity. - -If identity is unclear, report candidate authors and ask the user before processing non-human or ambiguous reviewers. - -## Safety Rules - -- Reply before resolving. -- Resolve only threads actually fixed, pushed, and validated. -- Include commit SHA when code changed. -- Do not resolve unresolved questions. -- Do not resolve rejected P0/P1, security, public API, compatibility, versioning, or release feedback without user approval unless policy explicitly permits it. diff --git a/.claude/settings.json b/.claude/settings.json index 6234b07..48d1a31 100644 --- a/.claude/settings.json +++ b/.claude/settings.json @@ -1,6 +1,6 @@ { "enabledPlugins": { + "agent-framework@brenpike": true, "claude-mem@thedotmack": true - }, - "agent": "orchestrator" + } } diff --git a/.claude/skills/address-pr-feedback/SKILL.md b/.claude/skills/address-pr-feedback/SKILL.md deleted file mode 100644 index c7caf22..0000000 --- a/.claude/skills/address-pr-feedback/SKILL.md +++ /dev/null @@ -1,115 +0,0 @@ ---- -name: address-pr-feedback -description: Fix a specific generic GitHub PR comment or reviewer comment on an existing pull request. Use for non-Codex or ambiguous PR feedback requests. -disable-model-invocation: false -allowed-tools: - - Read - - Bash(git status *) - - Bash(git branch *) - - Bash(git rev-parse *) - - Bash(git fetch *) - - Bash(git diff *) - - Bash(git log *) - - Bash(git add *) - - Bash(git commit *) - - Bash(git push *) - - Bash(gh pr view *) - - Bash(gh pr comment *) - - Bash(gh api *) - - Agent(planner, coder, designer) - - Skill -shell: powershell ---- - -# Address PR Feedback - -Fix one-time generic, human, non-Codex, or ambiguous PR feedback. - -Follow: - -- `agent-system-policy.md` -- `branching-pr-workflow.md` -- `versioning.md` -- `pr-review-remediation-loop.md` -- `.claude/references/github-pr-review-graphql.md` for PR review threads, thread replies, and GraphQL review data - -## Invocation Boundary - -Use for: - -- `fix PR comment on PR #N` -- `address reviewer feedback` -- `fix the unresolved comment` -- ambiguous PR feedback requests - -Do not use for explicit Codex review loops. Use `run-codex-review-loop` only when Codex is explicitly requested. - -## Required Inputs - -At minimum: - -- PR number or PR URL - -Optional: - -- comment URL -- comment author -- file path -- quoted comment text -- whether to reply after fixing - -## Procedure - -1. Confirm PR exists, target branch, head branch, current branch, and safe working tree. -2. Fetch top-level PR comments, inline review comments, unresolved review threads, and review summaries using `.claude/references/github-pr-review-graphql.md` where GraphQL review-thread data is required. -3. Identify the target comment. - - If exactly one unresolved/actionable candidate exists, process it. - - If multiple unrelated candidates exist and the user did not identify one, return blocked with candidates. -4. Classify feedback using `pr-review-remediation-loop.md`. -5. Route to planner/coder/designer according to policy. -6. Apply the smallest correct fix. -7. Run relevant validation when feasible. -8. Commit and push when a change was made and policy allows. -9. Reply with concise fix summary, validation, and commit SHA when appropriate. - -Do not request Codex re-review from this skill unless the user explicitly asks. - -## Output - -```text -Status: complete | partial | blocked - -PR: -- Number: -- Branch: -- Target: - -Feedback: -- Source: -- Author: -- URL: -- Classification: - -Changed: -- path/to/file -- None - -Validated: -- [check] -- Not run - -Git: -- Commit: -- Pushed: yes | no - -Reply: -- Posted: yes | no -- URL: -- Not posted because: - -Issues: -- [issue] -- None -``` - -Use the blocked report contract from `agent-system-policy.md` for blocked states. diff --git a/.claude/skills/checkpoint-commit/SKILL.md b/.claude/skills/checkpoint-commit/SKILL.md deleted file mode 100644 index 5e48026..0000000 --- a/.claude/skills/checkpoint-commit/SKILL.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -name: checkpoint-commit -description: Create a checkpoint commit for the current approved plan after a completed phase, milestone, version bump, or review remediation item. -disable-model-invocation: true -allowed-tools: - - Bash(git status *) - - Bash(git diff *) - - Bash(git add *) - - Bash(git commit *) - - Bash(git rev-parse *) - - Bash(git log *) -shell: powershell ---- - -Create a checkpoint commit for the current approved plan. - -Follow `branching-pr-workflow.md`. - -## Requirements - -1. Confirm current branch is not `main`. -2. Review staged and unstaged diff. -3. Stage only files that belong to the completed phase, milestone, version bump, or review-remediation item. -4. Create a clear conventional-style commit message. - -## Do Not - -- create a branch -- push -- open a PR -- include unrelated files -- commit on `main` - -## Output - -```text -Status: complete | blocked -Branch: -Commit: -Message: -Files included: -- [file] -Warnings: -- [warning] -- None -``` diff --git a/.claude/skills/create-working-branch/SKILL.md b/.claude/skills/create-working-branch/SKILL.md deleted file mode 100644 index eb63bb6..0000000 --- a/.claude/skills/create-working-branch/SKILL.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -name: create-working-branch -description: Create or confirm the compliant working branch for the current approved plan before implementation begins. -disable-model-invocation: true -allowed-tools: - - Bash(git status *) - - Bash(git branch *) - - Bash(git rev-parse *) - - Bash(git checkout *) - - Bash(git switch *) -shell: powershell ---- - -Create or confirm the working branch for the current approved plan. - -Follow `branching-pr-workflow.md`. - -## Requirements - -1. Confirm current branch. -2. Confirm base branch exists. -3. Confirm requested working branch name follows the branch taxonomy and naming rules. -4. Confirm there are no unexpected unstaged/uncommitted changes that make switching unsafe. -5. Create or switch to the requested working branch from the requested base branch. - -## Do Not - -- create or modify product files -- commit -- push -- open a PR -- continue when branch state is unsafe or ambiguous - -## Output - -```text -Status: complete | blocked -Classification: -Base branch: -Previous branch: -Working branch: -Created: yes | no -Warnings: -- [warning] -- None -``` diff --git a/.claude/skills/open-plan-pr/SKILL.md b/.claude/skills/open-plan-pr/SKILL.md deleted file mode 100644 index 9617585..0000000 --- a/.claude/skills/open-plan-pr/SKILL.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -name: open-plan-pr -description: Open a pull request for a successfully completed approved plan after final verification. -disable-model-invocation: true -allowed-tools: - - Bash(git status *) - - Bash(git branch *) - - Bash(git log *) - - Bash(git diff *) - - Bash(gh pr create *) - - Bash(gh pr view *) - - Bash(gh repo view *) -shell: powershell ---- - -Open a pull request for the completed approved plan. - -Follow `branching-pr-workflow.md` and `versioning.md`. - -## Requirements - -1. Confirm current branch and default base branch. -2. Confirm current branch is not `main`. -3. Confirm no unexpected unstaged changes. -4. Confirm required validation has passed. -5. Confirm required version/release metadata is included or not required. -6. Create PR with: - - clear title - - concise summary - - validation notes - - version/release notes when relevant - - unresolved issues when needed - -## Do Not - -- open PR for partial plan unless workflow explicitly allows it -- open PR if validation is incomplete -- open PR if required version/release metadata is missing -- invent missing validation -- include generated-content signatures - -## Output - -```text -Status: complete | blocked -Base: -Head: -PR title: -PR URL: -Warnings: -- [warning] -- None -``` diff --git a/.claude/skills/request-codex-review/SKILL.md b/.claude/skills/request-codex-review/SKILL.md deleted file mode 100644 index 60c88bf..0000000 --- a/.claude/skills/request-codex-review/SKILL.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -name: request-codex-review -description: Request Codex review on the current pull request. -disable-model-invocation: true -allowed-tools: - - Bash(gh pr view *) - - Bash(gh pr comment *) -shell: powershell ---- - -Request Codex review on the current pull request. - -Codex is an external reviewer, not a Claude Code subagent. - -## Requirements - -1. Confirm the PR exists. -2. Confirm the current branch is the PR head branch. -3. Confirm the PR branch has been pushed. -4. Post this PR comment: - -```text -@codex review for regressions, missing tests, public API compatibility issues, security issues, package/release behavior, versioning issues, and risky behavior changes. -``` - -## Do Not - -- modify files -- commit -- push -- resolve review threads -- request review if no PR exists - -## Output - -```text -Status: complete | blocked -PR number: -PR URL: -Branch: -Review request posted: yes | no -Warnings: -- [warning] -- None -``` diff --git a/.claude/skills/run-codex-review-loop/SKILL.md b/.claude/skills/run-codex-review-loop/SKILL.md deleted file mode 100644 index 2912505..0000000 --- a/.claude/skills/run-codex-review-loop/SKILL.md +++ /dev/null @@ -1,117 +0,0 @@ ---- -name: run-codex-review-loop -description: Run the bounded Codex GitHub PR review remediation loop only when the user explicitly asks to handle Codex review feedback, Codex review threads, or Codex re-review. -disable-model-invocation: false -allowed-tools: - - Read - - Bash(git status *) - - Bash(git branch *) - - Bash(git rev-parse *) - - Bash(git fetch *) - - Bash(git log *) - - Bash(git diff *) - - Bash(git add *) - - Bash(git commit *) - - Bash(git push *) - - Bash(gh pr view *) - - Bash(gh pr comment *) - - Bash(gh api graphql *) - - Agent(planner, coder, designer) - - Skill -shell: powershell ---- - -# Run Codex Review Loop - -Run the bounded Codex-specific remediation and re-review loop for an existing PR. - -Follow: - -- `agent-system-policy.md` -- `branching-pr-workflow.md` -- `versioning.md` -- `pr-review-remediation-loop.md` -- `.claude/references/github-pr-review-graphql.md` - -## Invocation Boundary - -Use only when the request explicitly refers to: - -- Codex -- Codex review -- Codex PR feedback -- Codex review threads -- Codex re-review -- Codex review remediation loop - -If invoked for generic or ambiguous feedback, return blocked and direct the orchestrator to `address-pr-feedback`. - -## Required Inputs - -- PR number or PR URL -- current branch name -- repository owner/name - -## Procedure - -1. Confirm PR exists, current branch is the PR head branch, latest remote state is fetched, and working tree is clean. -2. Fetch Codex-authored feedback using `.claude/references/github-pr-review-graphql.md`: review threads, inline thread comments, top-level PR comments, and review summaries (reviews with `CHANGES_REQUESTED` or `COMMENTED` state whose body contains actionable feedback not captured in inline threads). -3. Build a remediation queue with thread/comment id, file, line/diff context, summary, classification, severity, owner, user-input requirement, and version/release impact. -4. Route per `pr-review-remediation-loop.md`. -5. Apply smallest correct fixes through delegated agents. -6. Run relevant validation. -7. Commit and push remediation changes. -8. Reply to fixed items with concise summary and commit SHA. -9. Resolve fixed review threads only after push and validation. -10. Request Codex re-review when all actionable items are handled. -11. Repeat until clean, blocked, user input is required, repeated finding appears, or max loop count is reached. - -Default maximum: 3 remediation iterations. - -Do not process non-Codex feedback unless the user explicitly asks to include all reviewers. - -## Output - -```text -Status: complete | partial | blocked - -PR: -- Number: -- URL: -- Branch: - -Loop: -- Iterations completed: -- Max iterations: -- Re-review requested: yes | no - -Fixed: -- [thread/comment id]: [summary] -- None - -Resolved: -- [thread id] -- None - -Commits pushed: -- [sha] -- None - -Validated: -- [check] -- Not run - -Version/release: -- [change] -- None - -Remaining: -- [item] -- None - -Issues: -- [issue] -- None -``` - -Use the blocked report contract from `agent-system-policy.md` for blocked states. diff --git a/.claude/skills/watch-pr-feedback/SKILL.md b/.claude/skills/watch-pr-feedback/SKILL.md deleted file mode 100644 index d1eb2cb..0000000 --- a/.claude/skills/watch-pr-feedback/SKILL.md +++ /dev/null @@ -1,154 +0,0 @@ ---- -name: watch-pr-feedback -description: Watch a specific GitHub pull request for new unresolved review comments or review threads using Monitor when available, then route to the appropriate remediation skill. Use only when the user explicitly asks to watch, monitor, wait, poll, loop, or continue handling new PR feedback as it appears. -disable-model-invocation: false -allowed-tools: - - Bash(gh pr view *) - - Bash(gh api *) - - Bash(git status *) - - Bash(git branch *) - - Monitor - - Skill -shell: powershell ---- - -# Watch PR Feedback - -Watch a specific PR for new unresolved review feedback and route to remediation skills. - -This skill detects and routes. It must not directly edit files, commit, push, reply, resolve threads, approve PRs, or merge PRs. - -Follow: - -- `agent-system-policy.md` -- `pr-review-remediation-loop.md` -- `.claude/references/github-pr-review-graphql.md` - -## Invocation Boundary - -Use only when the user explicitly asks to: - -- watch or monitor PR comments -- wait for review feedback -- poll/check repeatedly -- keep handling feedback as it appears -- loop on Codex/human review feedback -- use Monitor for PR feedback - -Do not use for one-time requests like `fix PR comment on PR #N`; use `address-pr-feedback`. - -## Required Inputs - -At minimum: - -- PR number or PR URL - -Optional: - -- reviewer filter: Codex-only | all reviewers | specific author -- max watch duration -- polling interval -- max remediation cycles -- stop-on-human-reviewer-comments -- stop-on-P0/P1-findings - -## Defaults - -- reviewer filter: Codex-only after a Codex review request; otherwise all unresolved comments -- max remediation cycles: 3 -- max speculative fix attempts per thread: 1 -- max watch duration: 4 hours -- stop on user/product decision -- stop on repeated finding -- stop on unsafe git state -- do not merge PR -- do not approve PR - -## Procedure - -1. Confirm PR exists and is open using `gh pr view --json state --jq .state`. -2. Confirm GitHub CLI access works. -3. Confirm current branch and working tree state. -4. Start Monitor when available using one deterministic, read-only feedback-detection command based on `.claude/references/github-pr-review-graphql.md`. Detection must cover review threads, top-level PR comments, and review summaries (reviews with `CHANGES_REQUESTED` or `COMMENTED` state whose body contains actionable feedback not captured in inline threads). Fetch and ledger review summary IDs and states alongside thread and comment IDs. -5. Track seen comment/thread/review IDs in a session-local ledger. -6. When new feedback appears, classify source: - - Codex feedback - - human reviewer feedback - - CI/system feedback - - ambiguous -7. Route: - - explicit Codex loop request → `run-codex-review-loop` - - generic/human/ambiguous feedback → `address-pr-feedback` -8. Stop on policy stop conditions. - -## Monitor Rules - -Monitor commands must be: - -- read-only -- deterministic -- bounded -- parser-stable -- based on `gh --json/--jq` or `gh api graphql --jq` - -Do not probe or fallback through Python, Node, standalone `jq`, PowerShell, or shell translations. - -If Monitor startup or parser strategy fails: - -1. retry once only if transient -2. perform one manual feedback check when safe -3. report `Monitoring: not active` - -Do not start a second Monitor with a different parser strategy unless the user explicitly approves. - -## State Ledger - -Track session-local: - -- seen comment IDs -- seen review thread IDs -- comments already remediated -- comments skipped as non-actionable -- comments requiring user input -- remediation cycle count -- monitor startup status - -Do not reprocess the same item unless new activity appears or the user explicitly asks to retry. - -## Output - -```text -Status: complete | partial | blocked - -PR: -- Number: -- State: -- Branch: -- Target: - -Watch: -- Mode: Monitor | scheduled | manual -- Monitoring: active | not active -- Parser: gh --jq | other-approved | unavailable -- Cycles: -- Seen comments: -- New actionable comments: - -Routed: -- address-pr-feedback: [count] -- run-codex-review-loop: [count] -- None - -Stopped because: -- [reason] - -Next action: -- [required next step] -- None - -Issues: -- [issue] -- None -``` - -Use the blocked report contract from `agent-system-policy.md` for blocked states. diff --git a/AGENTS.md b/AGENTS.md deleted file mode 100644 index 223f4d1..0000000 --- a/AGENTS.md +++ /dev/null @@ -1,42 +0,0 @@ -# AGENTS.md - -## Purpose - -Repository-level guidance for external AI reviewers such as Codex. - -Codex is an external pull request reviewer, not an internal Claude Code subagent. It must not push commits, change branches, or resolve review threads. It should leave review comments only. - -Project-specific build, test, architecture, package, and domain rules live in `CLAUDE.md` and the repository documentation it references. - -## Review Focus - -Review PRs for: - -- correctness -- regressions -- security -- public API compatibility -- backwards compatibility -- package/release behavior -- maintainability -- missing or weak tests -- risky behavior changes - -## Severity - -- P0: security issue, data loss, broken build, severe regression, or release blocker -- P1: likely bug, risky missing test, public API break, package/release regression, or incorrect behavior -- P2: maintainability, naming, style, documentation, or minor test coverage issue - -## Review Behavior - -Prefer actionable, specific comments. Include: - -- affected file or behavior -- why it matters -- recommended fix direction -- severity when appropriate - -Do not request changes for subjective style preferences unless they conflict with documented project conventions. - -Do not push commits directly. diff --git a/CLAUDE.md b/CLAUDE.md index 359c2de..489826b 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -37,18 +37,23 @@ Chatter.Rest.Hal is a .NET/C# implementation of the HAL (Hypertext Application L ## Multi-Agent Governance -This repository uses the constrained Claude Code framework defined by: - -- `agent-system-policy.md` -- `branching-pr-workflow.md` -- `versioning.md` -- `pr-review-remediation-loop.md` - -Role-specific agents live in `.claude/agents/`. -Reusable workflows live in `.claude/skills/`. -External reviewer guidance lives in `AGENTS.md`. - -These files must be respected unless the user explicitly overrides them for a specific task. +This repository uses the [agent-framework](https://github.com/brenpike/agent-framework) Claude Code plugin. + +Enable the plugin in `.claude/settings.json`: +```json +{ + "enabledPlugins": { + "agent-framework@brenpike": true + } +} +``` + +The plugin provides: +- Agents: `agent-framework:orchestrator` (default), `agent-framework:planner`, `agent-framework:coder`, `agent-framework:designer` +- Skills: `agent-framework:create-working-branch`, `agent-framework:checkpoint-commit`, `agent-framework:open-plan-pr`, and others +- Governance reference docs in the plugin's `governance/` directory + +Project-specific adapter details live in `CLAUDE.md` (this file). External reviewer guidance lives in `AGENTS.md`. ## Build and Test Commands diff --git a/agent-system-policy.md b/agent-system-policy.md deleted file mode 100644 index 778f428..0000000 --- a/agent-system-policy.md +++ /dev/null @@ -1,313 +0,0 @@ -# Agent System Policy - -## Purpose - -Canonical cross-agent policy for the Claude Code multi-agent framework. - -This file defines shared constraints once. Agent files define role-specific deltas. Skill files define executable procedures. Project facts live in `CLAUDE.md`. - -Do not copy this policy into agents or skills. Reference it, and duplicate only short safety-critical stop rules where isolation requires it. - -## Mandatory Governance Files - -Agents must follow these files whether or not the user restates them: - -- `branching-pr-workflow.md` — branching, commits, PRs, merge path, validation, trunk-based delivery -- `versioning.md` — SemVer, release metadata, changelog, tags -- `pr-review-remediation-loop.md` — external PR review feedback handling -- `CLAUDE.md` — project-specific adapter: paths, commands, packages, artifact rules - -Silence about git workflow, versioning, validation, or review remediation is not permission to ignore the governance files. - -## Allowed Agent Topology - -Allowed Claude Code agents: - -- `orchestrator` -- `planner` -- `coder` -- `designer` - -No other agent type may be called, requested, invented, or used as a fallback. - -External reviewers, CI, GitHub, Codex, and other services are not Claude Code subagents. - -## Authority Matrix - -| Area | orchestrator | planner | coder | designer | -|---|---|---|---|---| -| Coordination | owns | no | no | no | -| Planning | coordinates | owns | no | no | -| Implementation | no | no | owns | presentational only | -| Visual design | coordinates | plan only | no new design without guidance | owns | -| Static accessibility | coordinates | plan only | partial | owns | -| Runtime accessibility | coordinates | plan only | owns | no | -| Branch/worktree decision | owns | recommend only | no | no | -| Branch creation | owns via skill | no | no | no | -| Checkpoint commit | owns via skill | no | delegated only | no | -| PR submission | owns via skill | no | no | no | -| Version bump decision | owns | recommend only | no | no | -| Version/release file edits | delegates | no | delegated only | no | -| External review request | owns | no | no | no | -| Feedback classification/routing | owns | recommend when delegated | no | no | -| Remediation planning | coordinates | owns when delegated | no | no | -| Remediation implementation | no | no | owns | presentational only | -| Review replies/resolution | owns | no | no | no | - -## Role Boundaries - -### orchestrator - -Coordinates the workflow. Owns delegation, sequencing, branch/worktree decisions, checkpoint-commit decisions, PR submission, version bump decisions, and external review-feedback routing. - -The orchestrator must not implement product/application changes directly. - -### planner - -Plans only. Reads and researches, assigns exact file scopes, identifies risks, dependencies, delivery shape, versioning implications, and open questions. - -The planner must not modify files, create branches, commit, push, open PRs, or resolve review threads. - -### coder - -Implements assigned code, tests, docs, build/package/release metadata, runtime behavior, and assigned review-remediation fixes within explicit file scope. - -The coder must not silently expand scope, decide version bump type, reply to review threads, resolve review threads, request external review, or invent visual design. - -### designer - -Implements assigned presentational UI/UX, design tokens, layout, semantic markup, static ARIA, visual states, responsive presentation, and presentation accessibility within explicit file scope. - -The designer must not implement business logic, data flow, persistence, routing, state derivation, runtime keyboard behavior, runtime focus movement, live-region behavior, or version/release metadata changes. - -## Explicit Scope Rule - -Any modifying agent must work only in explicitly assigned files. - -If another file is required: - -1. stop -2. report the exact file -3. explain why it is needed -4. wait for orchestrator reassignment - -No agent may silently expand scope. - -For mixed presentation-and-behavior files, default owner is `coder` unless the assignment is purely presentational and explicitly prohibits behavior changes. - -## Accessibility Ownership Split - -Designer owns static/presentational accessibility: - -- semantic structure -- static ARIA attributes -- accessible labels -- contrast -- visible focus treatment -- touch target sizing -- non-color-only communication -- visual treatment of loading, empty, error, disabled, hover, focus, and active states - -Coder owns runtime accessibility: - -- state derivation and transitions -- keyboard behavior driven by runtime state -- focus movement driven by application state -- live-region behavior -- accessibility behavior tied to business logic or app state - -## Git Workflow Enforcement - -`branching-pr-workflow.md` is mandatory. - -Before implementation begins, the orchestrator must explicitly establish: - -- work classification -- base branch -- working branch -- worktree decision -- checkpoint commit policy -- PR target - -Workers must stop and report `blocked` if required git context is missing, inconsistent, or unsafe. - -No agent may commit or push directly to `main`. - -## Versioning Enforcement - -`versioning.md` is mandatory for versioned artifacts. - -The orchestrator owns bump detection and bump type decisions. The coder may edit version/release metadata only when explicitly delegated. - -A PR that requires a version bump is not ready until required version/release metadata is included. - -If project-specific version paths or canonical version sources are unclear, stop and ask the user. - -## External Review Policy - -`pr-review-remediation-loop.md` is mandatory for external PR feedback. - -The orchestrator owns review feedback classification, routing, replies, resolution, and re-review requests. - -Skills may perform classification only as orchestrator-invoked workflow steps. Ownership remains with the orchestrator. - -Workers may remediate assigned feedback within explicit file scope. They must not reply to or resolve review threads unless explicitly delegated and allowed by policy. - -Use the narrowest matching skill: - -- `address-pr-feedback` — one-time generic, human, ambiguous, or non-Codex PR feedback -- `run-codex-review-loop` — explicit Codex review remediation/re-review loop -- `watch-pr-feedback` — explicit watch, monitor, wait, poll, loop, or continue-handling-new-feedback request - -## Tool and MCP Policy - -| Tool / MCP | orchestrator | planner | coder | designer | Notes | -|---|---|---|---|---|---| -| Context7 | optional | use when relevant | use when relevant | use when relevant | current framework/library/platform docs | -| claude-mem | optional | first step when context matters | use when relevant | use when relevant | continuity and token efficiency | -| local repo tools | minimal/orchestration | read-only | role-appropriate | role-appropriate | respect ownership | -| GitHub CLI/API | orchestration/review | read-only only | delegated only | no | respect PR/review ownership | -| Monitor | explicit watch only | no | no | no | read-only, bounded, deterministic | - -Do not use broad tools to bypass role boundaries. - -## Shell and Parser Policy - -Use deterministic shell/parser behavior. - -Do not: - -- shell-hop for routine parsing -- call `powershell -Command` from Bash for routine parsing -- call Bash from PowerShell for routine parsing -- dynamically probe Python, Node, standalone `jq`, PowerShell, or other parsers during normal execution -- restart Monitor with different parser strategies without explicit user approval -- continue monitor loops after parser failures without reporting the failure - -Prefer: - -1. native Claude shell for the current environment -2. `gh pr view --json ... --jq ...` -3. `gh api graphql --jq ...` -4. deterministic commands with bounded retries - -If the approved shell/parser strategy fails, retry once only when transient, then return `blocked` rather than improvising parser fallback chains. - -## Monitoring Policy - -A remediation skill is not a monitor. A monitor is not a remediator. - -Use `watch-pr-feedback` only when the user explicitly asks to watch, monitor, wait for, poll, loop on, or continue handling PR feedback as it appears. - -Monitoring must be: - -- backed by Monitor, scheduled task, routine, channel, or equivalent real background trigger -- read-only while watching -- deterministic and parser-stable -- bounded by max watch duration and remediation cycles -- routed through remediation skills instead of editing directly - -Do not say or imply active monitoring is running unless a real background mechanism started successfully. - -If no background mechanism is active, report: - -```text -Status: complete | blocked -Mode: manual -Monitoring: not active -Next action: -- User must invoke the skill again when new feedback appears -``` - -## Retry and Failure Policy - -Failures are execution states, not waiting states. - -After any tool error, timeout, failed delegation, unusable output, missing permission, parser failure, or internal runtime failure, the observing agent must immediately do one of: - -1. retry once if the failure appears transient -2. continue with a safe fallback -3. return `blocked` - -Rules: - -- Do not retry indefinitely. -- Do not repeat the same failing action more than once without changed strategy or new information. -- Do not wait for the user to ask what happened. -- Do not abandon a failed skill, monitor, or delegation without a blocked report. -- Do not invoke a broader/riskier skill unless the user's request matches that skill boundary. - -## Escalation Rules - -Stop and report instead of guessing when: - -- assigned scope is insufficient -- ownership boundary would be crossed -- design guidance is missing for material visual work -- runtime behavior is required in a designer task -- repo/worktree/git state is unsafe -- required git context is missing -- versioning/release scope is ambiguous -- feedback requires product, public API, architecture, security, compatibility, release, or versioning decision -- validation cannot be run but is required for confidence - -## Communication Standard - -Agent-to-agent communication must be concise and field-based. - -Rules: - -- prefer short labeled fields over prose -- include only required sections -- omit optional sections unless relevant -- report facts, blockers, scope needs, validation, versioning, review state, and git state directly -- do not restate policy or workflow rules inside routine reports - -## Shared Worker Report Contract - -Use this by default for planner-delegated worker output: - -```text -Status: complete | partial | blocked - -Changed: -- path/to/file -- None - -Validated: -- [check] -- Not run - -Need scope change: -- path/to/file: reason -- None - -Issues: -- [issue] -- None -``` - -Optional lines only when relevant: - -- `Refs: ...` -- `States handled: ...` -- `Commit: ...` -- `Version: ...` -- `Review item: ...` -- `Git issue: ...` -- `Ready to resolve: yes|no` - -## Blocked Report Contract - -Use this for blocked planning, execution, validation, git, versioning, review, monitoring, or skill states: - -```text -Status: blocked -Stage: [planning | implementation | validation | git workflow | versioning | review remediation | monitoring | skill selection | fetch | parse | route] -Blocker: [one-line reason] -Retry status: [not attempted | retried once | exhausted] -Fallback used: [none | description] -Impact: [what cannot proceed] -Next action: -- [specific next step] -``` diff --git a/branching-pr-workflow.md b/branching-pr-workflow.md deleted file mode 100644 index c667033..0000000 --- a/branching-pr-workflow.md +++ /dev/null @@ -1,206 +0,0 @@ -# Branching and Pull Request Workflow - -## Purpose - -This repository follows trunk-based development. The canonical trunk is `main`. - -This workflow is mandatory for all agent activity unless the user explicitly overrides it for a specific task. - -The approved plan is the unit of branch ownership, execution, checkpoint-commit decisions, PR submission, and external review remediation. - -## Non-Optional Rules - -1. Never commit directly to `main`. -2. Never push directly to `main`. -3. Develop all changes on a non-`main` working branch. -4. One approved plan = one working branch by default. -5. One completed approved plan = one PR by default. -6. PRs target `main` unless the user explicitly says otherwise. -7. Merges to `main` use squash merge. -8. Main must remain stable and deployable. - -## Branch Taxonomy - -Use exactly one prefix: - -- `feature/` — features or new capabilities -- `bugfix/` — non-emergency defects -- `hotfix/` — urgent production fixes -- `refactor/` — structural improvement without intended behavior change -- `chore/` — maintenance -- `docs/` — documentation-only -- `test/` — test-only -- `ci/` — CI/CD or workflow changes - -Branch format: - -- `/` -- `/-` - -Naming constraints: - -- lowercase only -- numbers allowed -- words separated by hyphens -- no spaces -- no underscores -- no extra slashes beyond the prefix separator -- include ticket/issue ID when one exists - -## Plan-to-Branch Mapping - -Default: one approved plan maps to one branch and one PR. - -Use multiple branches/PRs only when the planner explicitly decomposes the request into independently reviewable and independently shippable plans. - -## Required Git Preflight - -Before implementation begins, the orchestrator must define: - -- work classification -- base branch -- working branch name -- whether the branch exists or must be created -- whether worktrees are used -- checkpoint commit policy -- intended PR target - -If any item is undefined, implementation must not begin. - -## Branch Creation - -The orchestrator creates or confirms the working branch only after: - -- the planner returns a complete plan or the planner-skip exception applies -- open questions are resolved -- implementation is ready to begin -- repo state is safe - -Use the `create-working-branch` skill when creating/switching branches. - -## Commit Policy - -Workers do not commit automatically. - -Checkpoint commits are allowed only when: - -- a phase is complete -- a meaningful milestone is complete -- a recovery point is needed before higher-risk work -- a review-remediation fix is complete, validated, and ready to push -- a version bump is complete and verified - -Default commit owner: orchestrator through `checkpoint-commit`. - -Coder may commit only when explicitly delegated. Designer never commits. - -Commit messages use conventional-style types: - -- `feat` -- `fix` -- `hotfix` -- `refactor` -- `docs` -- `test` -- `chore` -- `ci` - -Do not mix unrelated changes. Stage only files that belong to the completed phase, milestone, version bump, or review-remediation item. - -## Version Bumps - -`versioning.md` is canonical. - -A PR is not ready to merge until required version/release metadata changes are included. - -Version bumps are included in the same PR as the triggering change unless the user explicitly directs otherwise. - -## Pull Requests - -The orchestrator opens PRs using `open-plan-pr` only when: - -- the approved plan is complete -- required validation passed -- outputs are coherent and in scope -- required version/release metadata is included -- the branch is ready to merge into the target branch - -Default target: `main`. - -Use draft PRs only when explicitly requested or when the planner split staged reviewable deliverables. - -PR content must include: - -- concise summary -- key files/areas changed -- validation performed -- version/release notes when relevant -- notable constraints or unresolved issues - -Never include `co-authored by`, `Generated by`, or similar generated-content signatures. - -## External Review Remediation - -External review remediation stays on the same PR branch unless: - -- feedback is outside the approved plan -- feedback requires a separate independently shippable change -- the PR is already merged or closed - -The orchestrator owns review replies, resolution, re-review requests, remediation commits, and pushes. - -## Merge Policy - -Changes reach `main` only through PR. - -Before merge readiness: - -- required CI passes -- required validation passes -- required version/release metadata is present -- at least one human review is obtained - -## Syncing With Trunk - -When a branch falls behind `main`, prefer rebase when practical. Avoid unnecessary merge commits. - -If conflict resolution changes scope or risk materially, stop and reassess. - -## Hotfix Standard - -For urgent production fixes: - -1. create `hotfix/` from `main` -2. implement minimal safe change -3. validate -4. open PR to `main` -5. squash merge after required approval unless the user explicitly directs a different emergency process - -## Worktrees - -Worktrees are optional. - -Use worktrees only when all are true: - -1. orchestrator identifies parallelizable phases -2. file scopes do not overlap -3. separate Claude sessions are actually being used -4. complexity is justified - -Do not create one worktree per agent by default. - -## Branch Cleanup - -After PR merge, delete the working branch. - -After PR closure without merge, create a new branch for follow-up unless the same PR is immediately resumed. - -## Scope Drift - -If implementation reveals extra work outside the approved plan: - -1. stop -2. reassess scope -3. replan if needed - -Remain on the same branch only if the added work is within the same approved deliverable. diff --git a/pr-review-remediation-loop.md b/pr-review-remediation-loop.md deleted file mode 100644 index db90403..0000000 --- a/pr-review-remediation-loop.md +++ /dev/null @@ -1,164 +0,0 @@ -# PR Review Remediation Loop - -## Purpose - -Defines how Claude agents respond to external pull request review feedback, including Codex GitHub reviews. - -Codex and other external AI reviewers are external reviewers, not Claude Code subagents. - -## Ownership - -The orchestrator owns the loop: - -- request external review -- check feedback -- identify unresolved review threads/comments -- classify and route feedback -- verify fixes are committed and pushed -- reply to review threads/comments -- resolve review threads -- request re-review -- stop safely - -Skills may execute loop steps only when invoked by the orchestrator. Ownership remains with the orchestrator. - -## Entry Criteria - -Start only after: - -- a PR exists -- the PR branch has been pushed -- required validation completed or is known to be in progress -- external review was requested or feedback already exists - -## Feedback Sources - -Check: - -- unresolved PR review threads -- inline PR review comments -- top-level PR comments -- requested-changes or commented review summaries -- CI failures when relevant to the review feedback - -## Classification - -Classify every review item as one of: - -- `actionable-code-change` -- `actionable-test-change` -- `actionable-doc-change` -- `architecture-or-contract-concern` -- `design-or-UX-concern` -- `version-or-release-concern` -- `question-needs-user-input` -- `non-actionable` -- `incorrect-or-rejected` - -Do not silently ignore review feedback. - -## Routing - -- `coder`: source, tests, docs, build, packaging, release metadata, serialization, generation, runtime behavior, validation fixes -- `designer`: presentational UI/UX or static accessibility fixes -- `planner`: multi-step, risky, public API, architecture, compatibility, package/release, versioning, generated-output, cross-cutting, or test-strategy feedback -- user: product, public API, architecture, security, compatibility, release, or versioning decisions that cannot be safely inferred - -## Fix Rules - -For each actionable item: - -1. identify the exact thread/comment -2. identify affected files -3. delegate the smallest correct fix -4. update tests when behavior changes -5. update version/release metadata when required -6. run relevant validation -7. commit and push to the PR branch -8. reply with fix summary and commit SHA -9. resolve only after fix is pushed and validated - -## Rejected Feedback - -If feedback is incorrect or intentionally not applied: - -1. reply with concise rationale -2. do not resolve unless policy allows the PR author to resolve rejected feedback -3. escalate before rejecting P0/P1, security, public API, compatibility, architecture, package/release, or versioning feedback - -## Re-review - -After actionable comments are fixed, pushed, replied to, and resolved, request another external review when appropriate. - -Default Codex re-review request: - -```text -@codex review the latest changes and verify the prior findings were addressed. Focus only on remaining regressions, missing tests, public API compatibility, security issues, package/release behavior, versioning, and risky behavior changes. -``` - -Do not repeatedly request review without new commits or clear rationale. - -## Stop Conditions - -Stop when: - -- no unresolved actionable review feedback remains -- reviewer approves or posts no new actionable findings -- max loop count is reached -- the same finding repeats after attempted remediation -- user/product decision is required -- feedback requires out-of-plan architecture, public API, compatibility, release, or versioning change -- unrelated CI failure blocks confidence -- remediation would violate project standards -- unsafe git state is detected -- GitHub API/parser/tool failure cannot be safely recovered - -Default maximum: 3 remediation iterations per PR. - -After 3 iterations, summarize remaining items, attempted fixes, non-convergence reason, and recommended next action. - -## Thread Resolution Rule - -Resolve review threads only after: - -- fix is committed -- fix is pushed -- relevant validation is complete or explicitly reported -- reply was posted - -Do not resolve unresolved questions or unapproved rejected high-severity feedback. - -## Remediation Ledger - -Maintain a short session-local ledger during each loop: - -- PR number/URL -- branch -- iteration -- feedback queue -- classification -- owner -- status -- validation -- pushed commits -- remaining items - -Do not commit the ledger unless the user or project policy explicitly requests it. - -## Skill Selection - -Use the narrowest matching skill: - -- `address-pr-feedback` for generic PR comments, human reviewer comments, ambiguous reviewer feedback, or one-off fixes -- `run-codex-review-loop` only for explicit Codex review feedback, Codex threads, Codex re-review, or the bounded Codex loop -- `watch-pr-feedback` only for explicit watch/monitor/wait/poll/loop/continue requests - -Ambiguous requests such as `fix PR comment on PR #80` must not trigger the Codex loop by default. - -## Monitoring - -A remediation skill is not a monitor. A monitor detects new feedback and routes to remediation skills. - -Monitoring must be read-only, deterministic, bounded, parser-stable, and truthfully reported. - -Use `watch-pr-feedback` for monitor-backed behavior. If Monitor, `/loop`, scheduling support, or the approved parser strategy is unavailable, fall back to manual remediation or return `blocked`. diff --git a/versioning.md b/versioning.md deleted file mode 100644 index 886c174..0000000 --- a/versioning.md +++ /dev/null @@ -1,133 +0,0 @@ -# Versioning Policy - -## Purpose - -Generic SemVer workflow for repositories that publish versioned artifacts. - -Project-specific package names, artifact paths, version-file locations, changelog locations, tag prefixes, and validation commands live in `CLAUDE.md` or project docs referenced by `CLAUDE.md`. - -## Scope - -Applies to every independently versioned artifact defined by the project: packages, libraries, applications, plugins, containers, distributable binaries, or similar artifacts. - -Each artifact is versioned independently unless project documentation says otherwise. - -Internal shared components with no standalone distribution carry no version unless the project defines one. Changes to shared components may require bumps in dependent artifacts if public API, runtime behavior, generated output, package contents, or compatibility contracts change. - -## SemVer Rules - -This repository follows Semantic Versioning 2.0.0. - -Format: `MAJOR.MINOR.PATCH` - -| Increment | Trigger | -|---|---| -| MAJOR | Breaking change to public API, compatibility contract, data format, runtime behavior contract, or documented consumer expectation | -| MINOR | Backward-compatible public API, capability, option, behavior, or artifact surface | -| PATCH | Bug fix, internal refactor, or implementation change with no public compatibility impact | - -For `0.x.y` artifacts, SemVer permits minor increments for breaking changes. Breaking changes must still be documented clearly. - -Pre-release labels such as `1.2.0-beta.1` require orchestrator coordination and project release-workflow support. - -## Bump Trigger - -A version bump is required when a PR changes files that affect a published artifact's: - -- runtime behavior -- public API -- compatibility contract -- generated output -- packaged output -- distribution metadata -- documented consumer expectation - -Exact bump-trigger paths are project-specific and must be defined in `CLAUDE.md` or referenced project documentation. - -No bump is required by default for: - -- documentation-only changes -- test-only changes -- CI-only changes -- agent framework/governance changes -- changelog-only maintenance -- markdown-only changes - -Project documentation may define additional required or excluded paths. - -## Bump Type Determination - -The orchestrator determines bump type from: - -1. conventional commit type(s) -2. public API, compatibility, runtime, data format, generated output, package, or documented behavior impact -3. breaking-change markers such as `!`, `BREAKING CHANGE:`, or actual compatibility impact - -| Commit / impact | Increment | -|---|---| -| `feat` with backward-compatible public capability | MINOR | -| `feat!` or `BREAKING CHANGE:` | MAJOR | -| `fix` / `bugfix` without breaking change | PATCH | -| `refactor` without public compatibility impact | PATCH | -| `refactor!` | MAJOR | -| `chore` / `docs` / `test` / `ci` without artifact impact | No bump | - -When uncertain, ask the user before delegating version edits. - -## Bump Execution - -The orchestrator delegates version/release file edits to coder. - -A bump is included in the same PR as the triggering change unless the user explicitly directs otherwise. - -Project-specific documentation must define the exact files to update atomically, such as: - -- canonical version file -- changelog/release notes -- package/artifact metadata -- documentation mirrors -- release validation files - -Every artifact must have one canonical version source. Mirrors are informational and must be kept in sync. - -If the canonical source is undefined, inspect the repo and ask for user confirmation before editing version metadata. - -## CHANGELOG / Release Notes - -Each versioned artifact should maintain release notes or a changelog unless the project defines another release documentation mechanism. - -Recommended sections follow Keep a Changelog: - -- Added -- Changed -- Deprecated -- Removed -- Fixed -- Security - -When bumping, convert pending unreleased entries into a dated release section and reset the unreleased section according to project convention. - -## Tags - -Tags are created according to the project release workflow. - -Project documentation must define: - -- manual vs CI-created tags -- tag format -- prefix per artifact when multiple artifacts exist -- annotated vs lightweight -- timing relative to publish/deploy - -Recommended generic formats: - -- single artifact: `vX.Y.Z` -- multiple artifacts: `/vX.Y.Z` - -## Agent Rules - -- Orchestrator owns bump detection and bump type decisions. -- Planner may recommend versioning implications but must not edit files. -- Coder may edit version/release files only when explicitly delegated. -- Designer never edits version/release files unless a purely presentational documentation file is explicitly assigned. -- If project-specific version paths or canonical version source are unclear, stop and ask the user. From fff25681dd5431a96b535dcbf629ce1a59b7f08b Mon Sep 17 00:00:00 2001 From: Brennan Pike Date: Wed, 29 Apr 2026 23:23:29 -0600 Subject: [PATCH 2/3] docs: remove stale versioning.md ref from Documentation Index --- CLAUDE.md | 1 - 1 file changed, 1 deletion(-) diff --git a/CLAUDE.md b/CLAUDE.md index 489826b..6a537f6 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -21,7 +21,6 @@ Chatter.Rest.Hal is a .NET/C# implementation of the HAL (Hypertext Application L | `docs/HAL_TEST_PLAN.md` | HAL spec-to-test mapping; consult for spec compliance and tests | | `docs/aspnetcore/requirements.md` | Package requirements for `Chatter.Rest.Hal.AspNetCore` | | `docs/aspnetcore/architecture.md` | Architecture, pseudocode, and test strategy for `Chatter.Rest.Hal.AspNetCore` | -| `versioning.md` | SemVer rules, bump triggers, changelog, tag policy | ## Solution Structure From 49c83289fdadfdfc15d800e52662f0d5910affc0 Mon Sep 17 00:00:00 2001 From: Brennan Pike Date: Thu, 30 Apr 2026 17:14:56 -0600 Subject: [PATCH 3/3] docs: restore AGENTS.md and drop versioning.md link Codex P2 review on PR #83: - Restore AGENTS.md so CLAUDE.md's "external reviewer guidance" pointer resolves again. - Replace docs/development.md's stale ../versioning.md link with the SemVer reference only; full policy now lives in the agent-framework plugin governance docs. --- AGENTS.md | 42 ++++++++++++++++++++++++++++++++++++++++++ docs/development.md | 2 +- 2 files changed, 43 insertions(+), 1 deletion(-) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..223f4d1 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,42 @@ +# AGENTS.md + +## Purpose + +Repository-level guidance for external AI reviewers such as Codex. + +Codex is an external pull request reviewer, not an internal Claude Code subagent. It must not push commits, change branches, or resolve review threads. It should leave review comments only. + +Project-specific build, test, architecture, package, and domain rules live in `CLAUDE.md` and the repository documentation it references. + +## Review Focus + +Review PRs for: + +- correctness +- regressions +- security +- public API compatibility +- backwards compatibility +- package/release behavior +- maintainability +- missing or weak tests +- risky behavior changes + +## Severity + +- P0: security issue, data loss, broken build, severe regression, or release blocker +- P1: likely bug, risky missing test, public API break, package/release regression, or incorrect behavior +- P2: maintainability, naming, style, documentation, or minor test coverage issue + +## Review Behavior + +Prefer actionable, specific comments. Include: + +- affected file or behavior +- why it matters +- recommended fix direction +- severity when appropriate + +Do not request changes for subjective style preferences unless they conflict with documented project conventions. + +Do not push commits directly. diff --git a/docs/development.md b/docs/development.md index b1713a1..b767a4f 100644 --- a/docs/development.md +++ b/docs/development.md @@ -150,7 +150,7 @@ FluentAssertions (`Should()` syntax) is the preferred assertion library for new ## Versioning -Package versions follow [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html). See [versioning.md](../versioning.md) for the full policy including bump triggers, bump type rules, and orchestrator authority. +Package versions follow [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html). ### CHANGELOG files