docs: add FOC board rules for automated board maintenance#34
Merged
Conversation
3 tasks
There was a problem hiding this comment.
Pull request overview
Adds a documentation framework for maintaining the FilOzone FOC GitHub Projects v2 board, including rule definitions, a sweep playbook, and an agent prompt to guide automated/human sweeps. Also documents a current limitation in github-projects-client and links it to tracked future improvements.
Changes:
- Introduces
foc-board-rules/with rule categories (PR hygiene, status lifecycle, field completeness) and cross-references. - Adds a 6-stage sweep playbook and a ready-to-use sweep agent prompt for repeatable board maintenance.
- Updates
github-projects-client/README.mdwith a “Known gaps” note linking to a tracked improvement idea.
Reviewed changes
Copilot reviewed 8 out of 8 changed files in this pull request and generated 6 comments.
Show a summary per file
| File | Description |
|---|---|
| github-projects-client/README.md | Documents a known API surface gap and links to the future-ideas tracker. |
| foc-board-rules/README.md | Index + general behavior/operational guidelines for applying the rules. |
| foc-board-rules/pr-hygiene.md | Defines R-PR-* rules for PR assignment, status routing, and staleness handling. |
| foc-board-rules/status-lifecycle.md | Defines R-SL-* rules for status transitions and linked-PR lifecycle semantics. |
| foc-board-rules/field-completeness.md | Defines R-FC-* rules for required fields and cycle/milestone/estimate completeness. |
| foc-board-rules/sweep-playbook.md | Stage-by-stage sweep procedure with queries, rules applied, and guard rails. |
| foc-board-rules/sweep-agent-prompt.md | System prompt for running sweeps consistently in new LLM sessions. |
| foc-board-rules/future-ideas.md | Captures follow-up tooling ideas discovered during sweep iterations. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
rjan90
approved these changes
May 4, 2026
Contributor
rjan90
left a comment
rjan90
left a comment
There was a problem hiding this comment.
A couple okay suggestions from Copilot here, but else lgtm
github-project-automation
Bot
moved this from 🔎 Awaiting review
to ✔️ Approved by reviewer
in FOC
7 tasks
BigLep
force-pushed
the
biglep/bulk-set-board-item-field
branch
from
ec9da64 to
7d2c09d
Compare
Rules for keeping the FOC project board consistent, intended to be applied by LLMs via the FilOzzy MCP server or by humans during triage. - General behavior: 9 rules covering reporting, query strategy, batch PR metadata, bulk operations, external repos, unfamiliar theme flagging, and count reconciliation - PR hygiene (R-PR-001–009): assignment, dependabot handling, triage routing, draft detection, reviewer requirements, merged/closed status - Field completeness (R-FC-001–009): assignees, cycle theme defaults by repo, cycle assignment, milestone scoping (issues only), active milestone cycle enforcement - Status lifecycle: status transition rules Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Add general behavior rules #7-#9: flag unfamiliar Cycle Themes, reconcile bulk operation counts, prefer list_board_items over individual get_board_item calls (with note on relationship field string resolution) - R-FC-003: broaden from Todo+ to all open issues, exclude zOrganizing Items, add parent issue milestone inheritance - R-FC-004: add tpm-utils and foc-devnet repo defaults - R-FC-006: simplify (remove milestone prerequisite for cycle) - R-FC-009: new rule for active milestone cycle enforcement Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Add sweep-playbook.md with staged workflow (PRs → Triage issues → field completeness) - R-PR-005: Broaden draft PR rule to cover all non-Done/non-Todo statuses - R-PR-007: Check both reviewRequests and reviews for human engagement - R-SL-001: Require write access verification before acting on approvals - R-SL-004: Add rule for moving Triage issues to Todo when fields are set - R-FC-006/009: Scope cycle rules to in-flight items only (not Todo/Triage) - Add permissions checking guidance (rule 10) and future-ideas.md - Renumber R-SL-004→005, update README with sweep playbook link Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…nd PR status guard Add rule 1 (self-improving system), rule 12 (batch GraphQL metadata), R-FC-001 assignee investigation with zOrganizing exclusion, R-FC-008 recently-done reporting, R-SL-006 (flag PRs in "Issue awaiting PR merge"), Docs heuristic for Cycle Theme, and consolidate sweep playbook Stage 4 into a single query. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Rules added or expanded based on sweep findings: - R-PR-006: now covers In Progress PRs, checks review/commit timeline before moving (not just Triage → Awaiting Review) - R-SL-001: expanded to In Progress PRs, added superseding logic for changes_requested, added flagging context guidance - R-SL-006: flag PRs in "Issue awaiting PR merge" (data entry error) - R-SL-007: PRs with write-access changes_requested move back to In Progress - R-SL-008: issues with linked PRs move to "Issue awaiting PR merge" - R-FC-006: dependabot/release Todo PRs get current cycle - General rule 13: use REST API for mutations, not gh pr edit - General rule 6: simplified to per-repo REST only, removed GraphQL - Sweep playbook updated for all new rules in Stages 1 and 2 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Add FilOzone/filecoin-services to R-FC-004 repo defaults (flag for human review) - Add "active items" terminology to status-lifecycle - Add R-SL-009: stale active items (2+ weeks, two-pass board/GitHub check) - Expand Stage 4 to cover linked PR detection, staleness, and cycle gaps - Update R-PR-001: merged release PRs assigned to merger, not bot author - Update Stage 5 to reflect release PR assignee rule Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Add sweep-agent-prompt.md for running board sweeps in fresh sessions - Formalize terminology: Item, Blessed orgs, external items - Skip repo-level mutations on external items instead of try-once - Exclude external items from milestone flagging (R-FC-003) - Add R-PR-002 priority over R-FC-004 for dependabot PRs - Add note that R-FC-004 repo defaults don't apply to dependabot - Fix query syntax in README rule 5, add no:field guidance Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Makes cross-references navigable for both humans and LLMs. Adds convention as rule 15 in README and backfills links across all rule files. Also adds sweep-agent-prompt.md to the Rule files list. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Add rule requiring issues in active milestones to have a Dev Days Estimate so effort remaining calculations are accurate. Add Stage 6 to sweep playbook as a report-only stage. Also clarify that sweep playbook is exempt from cross-file hyperlinking convention, and add a future idea for exposing updated_at/creator in list_board_items. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Fix "all open PRs/issues" wording to "non-Done" where queries don't constrain is:open (sweep-playbook.md, README.md) - Add `maintain` permission level alongside write/admin for reviewer permission checks (status-lifecycle.md, README.md, pr-hygiene.md, sweep-playbook.md) - Update sweep-agent-prompt.md to reference R-FC-010 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
BigLep
force-pushed
the
biglep/foc-board-rules-initial-stab
branch
from
36b9a65 to
65186e4
Compare
The first real sweep revealed that fetching full `reviews` bodies in per-repo `gh pr list` calls consumed thousands of context lines (mostly for PRs not on the board), causing scanning errors and missed items. Phase 1 now fetches only lightweight fields (author, isDraft, reviewDecision, reviewRequests). Phase 2 makes targeted `gh pr view` calls only for PRs needing deep analysis (R-PR-006 status determination, R-SL-001 approval verification, R-SL-007 changes-requested). Also adds targeted `no:field` board queries for field-gap checks to the playbook, and strengthens the MCP enhancement case in future-ideas.md with real sweep failure data. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Contributor
Author
|
901248a added another set of improvements when running through all the rules again. I'll merge this now. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Background
This set of rules was built up over the course of a week while I triaged and cleaned up FOC . Instead of manually manipulating the board, I worked with Claude to build up this ruleset and would have Claude apply the rules to make sure I was getting what I wanted. In future, I can imagine putting this in Notion if have a Notion agent, but this gets it off my machine for now.
Summary
Rule files
foc-board-rules/README.mdfoc-board-rules/pr-hygiene.mdfoc-board-rules/status-lifecycle.mdfoc-board-rules/field-completeness.mdfoc-board-rules/sweep-playbook.mdfoc-board-rules/sweep-agent-prompt.mdfoc-board-rules/future-ideas.mdTest plan
Additional Notes
masterafter feat: add bulk mutations, field clearing, and robustness fixes #32 lands in master.🤖 Generated with Claude Code