github-project-agent-coordination

GitHub Project Agent Coordination

Use GitHub Project #6, cf-controlplane-project, as a lightweight coordination index for agent work selection and near-roadmap anticipation. The board helps agents answer what is active, blocked, ready, deferred, or done across issues, PRs, and deliberately scoped roadmap draft items. It is not a second issue body, PR body, evidence ledger, or goal store.

Core Rules

• Read Project #6 Agent Issue View during SuperLoop re-entry before choosing or confirming the current subgoal.
• Include both live issue/PR items and roadmap draft items in that readback.
• Treat issues, PRs, repo files, tests, runtime probes, and governance ledgers as authoritative for substance.
• Use the project board only for cross-object coordination and roadmap-lane visibility.
• Update Agent state only after durable state changes, not for transient progress within a turn.
• Create or update draft roadmap items only for durable future paths named by roadmap artifacts, user intent, or repeated project evidence. Do not create draft items for every thought, command, or transient follow-up.
• Promote a draft roadmap item to an issue or PR only when it becomes selected bounded work with acceptance criteria and an evidence plan.
• Respect configured GitHub Project workflows: if GitHub auto-adds issue or PR items, or auto-marks merged PR items done, do not create duplicate native project items or fight the workflow-managed status.
• Preserve the board-use directive in successor formal goals.
• Keep mutations idempotent: read the item and field IDs first, then update only the intended project item field.
• Record dependency-aware queue changes and reflective-learning outcomes only when they become durable coordination state. A transient idea from a run does not need a board mutation; an incorporated requirement, promoted regression, deferred owner, or selected next target does.
• Do not encode semantic pass/fail or readiness in Project fields from matched strings, regexes, keyword searches, or string parsing over free-form model output. The board may summarize accepted evaluator results or structural evidence, but it is not an oracle for generated prose.

Field Semantics

• Title: native issue/PR title, or a concise Roadmap: ... title for draft roadmap items.
• Status: GitHub Projects default workflow state. Leave it coarse unless the operator asks to make it authoritative. Prefer configured GitHub workflow automation for native issue/PR status transitions.
• Labels: native issue labels. Maintain on issues, not by project-field hacks.
• Linked pull requests: native GitHub relationship. Prefer PR body/reference hygiene over manual board bookkeeping.
• Parent issue: use only when GitHub issue hierarchy is intentionally set.
• Created and Updated: native timestamps. Do not manually maintain.
• Agent state: agent-facing coordination state. This is the main field agents may update.
• Agent owner: text lease owner for controller/worker coordination. Use stable IDs such as codex-thread:<thread-id>, codex-agent:<worker-agent-id>, or codex-agent:<parent-agent-id>/<child-agent-id>. Do not use rotating Codex display names as owner identity.

Project Enum Value Semantics

If a single-select enum value is not defined here, do not use it as an agent coordination signal until the operator or a follow-up source/docs branch gives it a ContextForge-specific meaning.

Status values are workflow-owned:

• Todo: open item added to the project but not workflow-linked to active work.
• In progress: workflow evidence says the issue or PR is active, linked, reopened, or under review.
• Done: issue or PR is closed or merged.

Agent state values are agent-owned:

• Candidate: plausible future work, not selected now.
• Ready: validated or prepared enough to pick up without broad rediscovery.
• Active: current SuperLoop/subgoal work.
• Blocked: cannot advance without an approval, external state, or concrete prerequisite.
• In Review: source or plan is packaged for review, merge, or acceptance.
• Done: merged, closed, or otherwise completed with durable evidence.
• Deferred: intentionally later-phase work that should not attract ordinary cleanup pressure.

Agent state should reflect evidence-backed coordination, not optimism. When a use case is reordered by dependency analysis, mark or comment only the durable selection rationale; do not make the numeric order look authoritative if the dependency mesh says otherwise.

Lane values identify the dominant roadmap surface:

• Service identity: canonical naming, deduplication, and backend identity.
• Project state: project-local state files, contracts, and helper readback.
• Contract artifacts: schemas, fixtures, and machine-readable agreements.
• Project init: activation, repair, approval, and apply/readback flows.
• Authorization: operator approvals and action boundaries.
• Apply recovery: recovery from partial or failed apply operations.
• Service management: service lifecycle scripts, manifests, and health.
• Registry validation: ContextForge registry checks and registration proof.
• Transport: stdio, SSE, streamable HTTP, and bridge behavior.
• Tool policy: client/tool allowlists, guidance, and safety controls.
• Client adapters: Pi, OpenCode, or other client-specific integration code.
• Evidence: probes, ledgers, proof artifacts, and claim discipline.
• Trust: hook trust, consent, provenance, and trust-state boundaries.
• Auth: tokens, credentials, login, and authentication boundaries.
• Remote exposure: network exposure, ports, hosts, and remote access.
• Service provisioning: installing or materializing backend services.
• Proof service: reusable validation/proof-producing service behavior.
• Language catalog: prompt, resource, and tool-language inventory.
• Service onboarding: facilitated addition of new MCP/service offerings.
• Inventory: read-only discovery of configured services and clients.
• Tool guidance: registered prompt/resource guidance for tools.
• Governance: decisions, abeyant intentions, and open questions.
• Memory: continuity, compaction, and persistent agent knowledge.
• Wrapper validation: wrapper lifecycle and wrapper/client behavior checks.
• Operator UX: human-facing command flow, prompts, and ergonomics.
• Coordination: issue, PR, Project, merge queue, and SuperLoop orchestration.
• Readiness: acceptance gates and activation-readiness packaging.

Priority values describe importance:

• low: useful cleanup or later polish.
• medium: worthwhile roadmap work without urgent sequencing pressure.
• high: important for near-term roadmap progress or repeated friction.
• critical: blocks safe operation, major roadmap progress, or trust.

Risk values describe expected blast radius if mishandled:

• Low: local, easy to verify, and easy to revert.
• Low-Med: mostly local with a small coordination or behavior risk.
• Med: meaningful cross-file, workflow, or user-visible risk.
• Med-High: broad workflow/runtime impact or difficult recovery.
• High: could disrupt active operation, trust, secrets, or critical state.

Effort values describe likely implementation size:

• Low: one focused edit, probe, issue update, or narrow test slice.
• Medium: several coordinated edits or a moderate validation pass.
• High: multi-surface implementation, migration, or extended validation.

Complexity values describe reasoning and integration uncertainty:

• Low: clear pattern and isolated behavior.
• Medium: multiple dependencies or nontrivial sequencing.
• High: architecture, runtime integration, or uncertain external behavior.

Team is inherited from a generic GitHub Project template. Do not set Squad 1, Squad 2, or Squad 3 for ContextForge work until a real team model is defined.

Roadmap Draft Items

Roadmap draft items are allowed when the project needs an intelligible, intentful future visible to agents before every lane is ready to become a GitHub issue. Keep them at lane or bounded-initiative resolution:

• title format: Roadmap: <lane or initiative>;
• body: outcome, current evidence source, promotion trigger, and non-goals;
• Agent state: usually Candidate, Ready, or Deferred;
• no detailed evidence duplication; link or name the authoritative doc, issue, PR, or decision instead.

Use draft items to prevent future paths from being lost during compaction or goal refresh. Do not let draft items replace issues once implementation begins. When a draft roadmap item is promoted to an issue or PR, allow the configured Project workflow to create the native issue/PR project item. Then retire, defer, or cross-reference the draft item so the board does not contain two active items for the same work.

Configured Project Workflows

The following GitHub Project #6 workflows were verified read-only in the GitHub UI on 2026-06-17. Treat this as the current automation contract until a fresh browser or API readback proves it changed.

• Auto-add to project: for repository contextforge-control-plane, filter is:issue,pr is:open; matching open issues and PRs are added to the project.
• Item added to project: when an issue or pull request is added, set Status: Todo.
• Pull request linked to issue: when a pull request is linked to an issue, set Status: In progress.
• Code changes requested: when a pull request has a review requesting changes, set Status: In progress.
• Code review approved: when a pull request is approved, set Status: In progress.
• Pull request merged: when a pull request is merged, set Status: Done.
• Item closed: when an issue or pull request is closed, set Status: Done.
• Item reopened: when an issue or pull request is reopened, set Status: In progress.
• Auto-close issue: when Status is updated to `Do

Content truncated.