-
Notifications
You must be signed in to change notification settings - Fork 1
chore(governance): simplify agent workflow #847
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
Show all changes
2 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
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
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
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,27 +1,17 @@ | ||
| # Agent Coordination | ||
|
|
||
| Each section, issue, and PR has one write owner, branch, and worktree. Never | ||
| place multiple writable agents in one worktree or have them exchange work by | ||
| pulling a shared branch. | ||
| One active contract has one write owner. Read-only research and review may run | ||
| in parallel. | ||
|
|
||
| Before the first write, the owner records: | ||
| Use the current checkout for an isolated local change when its ownership and | ||
| dirty state are known. Use a dedicated branch and worktree when work is | ||
| concurrent, published, or likely to span sessions. A managed worktree records | ||
| its contract, owner, path, branch, base SHA, allowed files, and dependencies in | ||
| the private path returned by `git rev-parse --git-path agent-worktree.yml`. | ||
|
|
||
| ```yaml | ||
| contract: Issue #{number}: {one behavior contract} | ||
| owner: {agent or human} | ||
| worktree: .worktrees/codex/{issue-slug} | ||
| branch: codex/{issue-slug} | ||
| base_sha: {exact integration-base SHA} | ||
| allowed_files: [{paths or patterns}] | ||
| dependency: None | #{blocking-issue} | ||
| ``` | ||
| Stop on overlapping ownership or unexpected branch movement. Re-read branch, | ||
| `HEAD`, status, and PR head before publishing or merging. Ownership handoff does | ||
| not create a new issue; update the existing contract record. | ||
|
|
||
| Write this YAML to the worktree-private path returned by | ||
| `git rev-parse --git-path agent-worktree.yml`. It is the runtime record; this | ||
| policy file is only its template and must not be overwritten. | ||
|
|
||
| Read-only research and review may run in parallel. A second writable change is | ||
| either a separate issue/worktree or waits for an explicit ownership transfer. | ||
| Before every edit, commit, rebase, push, or merge, re-read the branch, `HEAD`, | ||
| and worktree status; stop on unexpected movement. Report final worktree status | ||
| to the coordinator. Cleanup requires explicit repository-owner authorization. | ||
| Never remove a worktree or branch without explicit repository-owner | ||
| authorization for the exact target. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,11 +1,12 @@ | ||
| # Branch Operations | ||
|
|
||
| A branch belongs to one independently mergeable section, issue, and PR. Its | ||
| dedicated worktree has exactly one write owner. | ||
| Use a branch when a change will be published or must be isolated from concurrent | ||
| writes. A branch has one write owner and contains one independently reviewable | ||
| behavior. | ||
|
|
||
| Before edits, commits, rebases, pushes, or merges, re-read the branch, `HEAD`, | ||
| and status. Do not pull or push another issue's branch as a synchronization | ||
| mechanism; depend on the merged predecessor or an explicitly declared stack. | ||
| Re-read branch, `HEAD`, status, and PR head before publishing or merging. Do not | ||
| use another contract's branch as a synchronization mechanism; depend on its | ||
| merged result or an explicit stack. | ||
|
|
||
| Preserve branches and worktrees after merge, failure, or abandonment until the | ||
| repository owner explicitly authorizes cleanup of exact targets. | ||
| Do not delete a branch or worktree without explicit repository-owner | ||
| authorization for the exact target. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,13 +1,12 @@ | ||
| # Worktree Operations | ||
|
|
||
| One section, issue, and PR is one writable rollback unit. Create one dedicated | ||
| worktree and branch for that unit; do not place two writable agents in it. | ||
| A worktree isolates concurrent, published, or multi-session writes. It is not | ||
| required for read-only work or an isolated local change with known ownership. | ||
|
|
||
| Before the first write, record the contract, owner, worktree path, branch, base | ||
| SHA, allowed files, and dependency. Re-read the branch, `HEAD`, and status | ||
| before edits, commits, rebases, pushes, or merges. A reviewer is read-only. | ||
| Each writable worktree has one owner. Before its first write, record the | ||
| contract, owner, path, branch, base SHA, allowed files, and dependencies in the | ||
| private `agent-worktree.yml` path returned by Git. | ||
|
|
||
| Use the declared integration base, not a blind checkout of `main`. Preserve | ||
| worktrees after merge or abandonment until the repository owner explicitly | ||
| authorizes removal. `git worktree list --porcelain` is the read-only inventory | ||
| command; do not use `remove`, `prune`, or branch deletion as recovery steps. | ||
| Stop on overlap or unexpected movement. Preserve worktrees after merge or | ||
| abandonment until the repository owner explicitly authorizes exact cleanup; | ||
| never use removal, prune, reset, or branch deletion as recovery. |
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
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,32 +1,18 @@ | ||
| name: Bug report | ||
| description: Report reproducible broken behavior for triage | ||
| labels: ["bug", "needs-triage"] | ||
| description: Record reproducible broken behavior | ||
| labels: ["bug"] | ||
| body: | ||
| - type: textarea | ||
| id: current_behavior | ||
| id: evidence | ||
| attributes: | ||
| label: Current behavior | ||
| description: Describe what is broken and where it was observed. | ||
| label: Broken behavior and evidence | ||
| description: What happened, where, and the smallest repeatable observation. | ||
| validations: | ||
| required: true | ||
| - type: textarea | ||
| id: reproduction | ||
| id: expected | ||
| attributes: | ||
| label: Focused reproduction | ||
| description: Provide the smallest repeatable steps and exact evidence. | ||
| validations: | ||
| required: true | ||
| - type: textarea | ||
| id: expected_behavior | ||
| attributes: | ||
| label: Expected behavior | ||
| description: Describe the correct observable result. | ||
| validations: | ||
| required: true | ||
| - type: textarea | ||
| id: boundary | ||
| attributes: | ||
| label: Safety and scope boundary | ||
| description: Name affected trust domains and work that must remain unchanged. | ||
| label: Expected result | ||
| description: State the correct observable behavior. | ||
| validations: | ||
| required: true | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,2 +1,2 @@ | ||
| blank_issues_enabled: false | ||
| blank_issues_enabled: true | ||
| contact_links: [] |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,39 +1,18 @@ | ||
| name: Engineering change | ||
| description: Propose one independently mergeable and rollbackable improvement | ||
| labels: ["enhancement", "needs-triage"] | ||
| description: Record one independently verifiable improvement | ||
| labels: ["enhancement"] | ||
| body: | ||
| - type: textarea | ||
| id: contract | ||
| id: outcome | ||
| attributes: | ||
| label: Change contract | ||
| description: State one behavior and why it is needed. | ||
| label: Outcome | ||
|
proerror77 marked this conversation as resolved.
|
||
| description: What observable behavior should change, and why? | ||
| validations: | ||
| required: true | ||
| - type: textarea | ||
| id: acceptance | ||
| id: proof | ||
| attributes: | ||
| label: Acceptance evidence | ||
| description: List externally observable checks, including a safety counterexample where applicable. | ||
| validations: | ||
| required: true | ||
| - type: textarea | ||
| id: dependencies | ||
| attributes: | ||
| label: Dependencies and merge order | ||
| description: Use GitHub native blocked-by relationships after publication; write None when independent. | ||
| validations: | ||
| required: true | ||
| - type: textarea | ||
| id: out_of_scope | ||
| attributes: | ||
| label: Out of scope | ||
| description: Name adjacent behavior and trust domains excluded from this issue. | ||
| validations: | ||
| required: true | ||
| - type: textarea | ||
| id: rollout | ||
| attributes: | ||
| label: Rollout and rollback impact | ||
| description: State the production impact or None. | ||
| label: Proof | ||
| description: What smallest check will prove the outcome? | ||
| validations: | ||
| required: true | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,47 +1,26 @@ | ||
| name: Product requirement | ||
| description: Define a multi-step outcome before decomposition | ||
| title: "PRD: " | ||
| labels: ["enhancement", "needs-triage", "tracking"] | ||
| name: Product outcome | ||
| description: Coordinate a durable multi-owner or multi-session outcome | ||
| title: "Outcome: " | ||
| labels: ["enhancement", "tracking"] | ||
| body: | ||
| - type: textarea | ||
| id: problem | ||
| attributes: | ||
| label: Problem Statement | ||
| description: Describe the user-visible problem and why it matters. | ||
| label: Problem | ||
| description: What user-visible problem must be solved? | ||
| validations: | ||
| required: true | ||
| - type: textarea | ||
| id: solution | ||
| id: outcome | ||
| attributes: | ||
| label: Solution | ||
| description: Describe the outcome without prescribing speculative machinery. | ||
| label: Observable outcome | ||
| description: What result proves the problem is solved? | ||
| validations: | ||
| required: true | ||
| - type: textarea | ||
| id: stories | ||
| id: constraints | ||
| attributes: | ||
| label: User Stories | ||
| description: List the actors, capabilities, and benefits this outcome must cover. | ||
| label: Constraints | ||
| description: Record only real authority, safety, or compatibility boundaries. | ||
| validations: | ||
| required: true | ||
| - type: textarea | ||
| id: decisions | ||
| attributes: | ||
| label: Implementation Decisions | ||
| description: Record approved boundaries, interfaces, and rollout units. | ||
| validations: | ||
| required: true | ||
| - type: textarea | ||
| id: testing | ||
| attributes: | ||
| label: Testing Decisions | ||
| description: Name the public seams and acceptance evidence. | ||
| validations: | ||
| required: true | ||
| - type: textarea | ||
| id: out_of_scope | ||
| attributes: | ||
| label: Out of Scope | ||
| description: Name adjacent work that this PRD does not authorize. | ||
| validations: | ||
| required: true | ||
| required: false |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,53 +1,46 @@ | ||
| name: Runtime rollout | ||
| description: Request one bounded live mutation or runtime-evidence contract | ||
| labels: ["enhancement", "needs-triage", "runtime"] | ||
| name: Runtime outcome | ||
| description: Request and record one bounded live outcome | ||
| labels: ["enhancement", "runtime"] | ||
| body: | ||
| - type: input | ||
| id: target | ||
| attributes: | ||
| label: Exact target identity | ||
| description: Name the bounded host, cluster resource, service, or repository setting. | ||
| label: Exact target | ||
| validations: | ||
| required: true | ||
| - type: input | ||
| id: controller | ||
| attributes: | ||
| label: Named controller | ||
| description: Name the one authorized writer for this rollout. | ||
| label: One controller | ||
| validations: | ||
| required: true | ||
| - type: textarea | ||
| id: candidate | ||
| attributes: | ||
| label: Candidate and configuration identity | ||
| description: Record immutable source, artifact/image/binary, and configuration identities. | ||
| label: Candidate identity | ||
| validations: | ||
| required: true | ||
| - type: textarea | ||
| id: rollback | ||
| id: configuration | ||
| attributes: | ||
| label: Rollback identity and procedure | ||
| description: Record the immutable previous state and bounded rollback action. | ||
| label: Configuration identity | ||
| validations: | ||
| required: true | ||
| - type: textarea | ||
| id: stop_rules | ||
| id: rollback | ||
| attributes: | ||
| label: Stop rules | ||
| description: Name failures that stop mutation or prevent promotion. | ||
| label: Rollback identity and procedure | ||
| validations: | ||
| required: true | ||
| - type: textarea | ||
| id: success | ||
| id: stop | ||
| attributes: | ||
| label: Success and cleanup evidence | ||
| description: Define independent readback, post-change observation, cleanup, and rollback-expiry evidence. | ||
| label: Stop and cleanup rules | ||
| validations: | ||
| required: true | ||
| - type: textarea | ||
| id: out_of_scope | ||
| id: proof | ||
| attributes: | ||
| label: Out of scope | ||
| description: Name adjacent resources, services, and trust domains that must not change. | ||
| label: Success and direct readback | ||
| validations: | ||
| required: true |
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.