docs(governance): gate implementation on merged intent PR - #137
Conversation
Define a clear three-layer collaboration model for spec-driven work by separating design backlog, project roadmap, and active change execution boards. Add explicit work-package guidance with Gate-based freezing rules, ownership fields, and status flow so high-speed parallel development can scale without turning project-level TODOs into contention points. Add a reusable execution-board template and a collaboration design note, then migrate the existing AgentScope execution TODO into the standardized sample format while preserving its technical task content and dependency model. Keep AGENTS.md out of this commit so the documentation governance changes remain isolated from unrelated workspace edits.
Create a temporary local backup commit for the current uncommitted workspace changes so opt_todo_rule can be safely rebased onto the latest origin/main. This commit intentionally captures the in-progress AGENTS.md edit and the newly added step-driven execution-board docs as a local preservation point only. The goal is to avoid losing working tree state while updating the branch against the latest remote main for change-selection review.
Add a repo-local skill that standardizes how spec-driven collaborative execution boards are created, refreshed, and downgraded. Remove the earlier trial step-driven active board artifacts so this branch no longer carries a concrete execution-board rollout. The branch now keeps only the reusable skill, leaving real board creation as a later explicit action. Verification: git diff --cached --check
Add an explicit docs-only intent PR gate between claim/spec-sync and implementation. Clarify the two-layer collaboration model across governance docs: the outer Claim Ledger reserves TODO scope, while per-change execution boards coordinate work packages, Gate freezes, and touch scope inside an active change. Sync the development-workflow and spec-driven-collab-board skills so they require ownership declaration, determine when an execution board is needed, and block implementation until the docs-only intent PR is merged into main. Verification: git diff --check for updated governance docs and skills.
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 9c204d85ff
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
@codex review |
There was a problem hiding this comment.
💡 Codex Review
https://github.com/zts212653/Deterministic-Agent-Runtime-Engine/blob/9c204d85ffad3678b78de75e5e7f99e52547b610/docs/guides/Team_Agent_Collab_Playbook.md#L15-L16
The new playbook hard-codes references like /Users/lysander/projects/dare-framework/..., which only resolve on one specific workstation. For everyone else (including CI and other contributors), these links are broken, so the governance sources this document points to become non-discoverable and easy to misapply. Replace these with repository-relative paths (for example docs/agent_rules.md, .github/workflows/ci-gate.yml) to keep the guidance portable.
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Fix three review findings from PR #137. Replace the AGENTS bootstrap text with a valid skill instruction instead of a nonexistent shell command. Convert workstation-specific collaboration playbook references to repo-relative paths so the links remain portable for other contributors and CI. Add the missing Gate-4 definition to the execution-board template so the sample work-package freeze gate matches the declared gate summary. Verification: git diff --check for updated files.
|
Addressed the latest review feedback in Updated:
Verification:
|
Remove the repo-level AGENTS bootstrap block that instructed agents to use the local superpowers workflow. This bootstrap is environment-specific and should stay in the local setup rather than being committed into the shared repository. The rest of the governance and collaboration changes remain unchanged. Verification: git diff --check -- AGENTS.md
|
Updated in
This keeps the PR focused on the governance / intent-PR workflow changes while leaving local agent bootstrap out of repo state. |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 6f9e899b6b
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| @@ -0,0 +1,82 @@ | |||
| # AgentScope Execution Board Migration Implementation Plan | |||
|
|
|||
| > **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. | |||
There was a problem hiding this comment.
This plan is currently not executable as written because it makes superpowers:executing-plans mandatory, but that skill is not present in this repository’s skill catalog (checked .codex/skills/). Any agent that follows this “REQUIRED SUB-SKILL” instruction will fail before doing the migration work, so the plan should reference an available skill or provide a valid fallback path.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Fixed in c956932. Removed the hard dependency on superpowers:executing-plans and replaced it with repository-available workflow guidance so the migration plan does not assume local-only skills.
Address the remaining review feedback in PR #137. Remove the migration plan's hard dependency on a local superpowers skill and replace it with repository-available workflow guidance. Update the collaboration granularity design to reflect the current governance model: Claim Ledger is the outer ownership record, execution boards are the inner coordination layer, and docs-only intent PRs gate implementation. Verification: git diff --check for updated plan files.
1 participant
Summary
This PR adds an explicit docs-only
intent PRgate before implementation starts.The repository already has
Claim Ledgerto reserve TODO scope. This change adds the missing visibility gate:spec-sync / intent PRis merged intomainKey Changes
Claim Ledgerfor TODO scope ownershipexecution boardfor work packages, Gates, and touch scopeintent PRmerge before implementationUpdated Files
docs/guides/Documentation_First_Development_SOP.mddocs/todos/README.mddocs/todos/templates/change_execution_todo_template.mddocs/guides/Development_Constraints.mddocs/guides/Team_Agent_Collab_Playbook.md.codex/skills/development-workflow/SKILL.md.codex/skills/spec-driven-collab-board/SKILL.mdNew Workflow
Claim Ledgerintent PRintent PRintomainimpl PRFor high-conflict changes, the flow can be:
intent PR -> Gate freeze PR -> impl PRNotes
Claim Ledgermodel frommainmainVerification
git diff --check origin/main...HEAD./scripts/ci/check_governance_evidence_truth.shReviewer Checklist
Please review this PR mainly as a governance / workflow change.
1. Rule Coherence
Claim Ledgeris still the outer ownership layerexecution boardis clearly defined as the inner coordination layerTODO_INDEX,project_overall_todos, and per-change execution boards are no longer ambiguous2. New Gate
intent PRgate is clearly statedintent PRis merged intomain3. Practicality
intent PR -> Gate freeze PR -> impl PR4. Skill Alignment
development-workflowreflects the same gate order as the governance docsspec-driven-collab-boardreflects the same outer/inner board model5. Merge Safety
mainClaim Ledgermodel rather than replacing it6. Acceptance Question