-
Notifications
You must be signed in to change notification settings - Fork 0
[codex] add Hermes dev team mode #13
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 1 commit
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 |
|---|---|---|
| @@ -0,0 +1,107 @@ | ||
| # Hermes Dev Team Mode | ||
|
|
||
| Hermes Dev Team Mode turns one Hermes agent into the manager for a local | ||
| development team. The human communicates with the manager in Zulip, watches | ||
| canonical issues move through Vikunja project boards, and QA's a live dev | ||
| server exposed on the local network. | ||
|
|
||
| ## Operating Model | ||
|
|
||
| - The current Hermes agent is the manager. | ||
| - The manager identity is the Hermes/Zulip email address. | ||
| - Each manager owns one internal Vikunja project named | ||
| `Hermes Manager - <email>`. | ||
| - Main project boards remain the canonical user-visible source of issue state. | ||
| - Worker agents only work internal manager-project tasks. | ||
| - The manager is the only agent that moves main-board cards and writes to the | ||
| live integration worktree used by the dev server. | ||
|
|
||
| ## Board Model | ||
|
|
||
| Main project boards should use these buckets: | ||
|
|
||
| - `To-Do` | ||
| - `Blocked` | ||
| - `Doing` | ||
| - `Review` | ||
| - `Done` | ||
|
|
||
| Manager projects should use these buckets: | ||
|
|
||
| - `Queued` | ||
| - `Working` | ||
| - `Integrating` | ||
| - `Blocked` | ||
| - `Closed` | ||
|
|
||
| When Dev Team Mode watches a board, missing buckets are provisioned | ||
| automatically by the Hermes runtime. Setup checks may report missing buckets, | ||
| but should not require a human to create them by hand. | ||
|
|
||
| ## Zulip Intake | ||
|
|
||
| The manager triages Zulip QA messages instead of creating a task for every | ||
| message. For each message, it decides whether to: | ||
|
|
||
| - create a new canonical main-board issue | ||
| - update or deduplicate against an existing issue | ||
| - ask for a short clarification | ||
| - ignore conversational noise | ||
|
|
||
| Status updates should be quiet unless asked. The manager may still acknowledge | ||
| new issue creation, ask clarifying questions, or report blockers that require | ||
| human action. | ||
|
|
||
| ## Worker Dispatch | ||
|
|
||
| Workers are per-task runs. For each dispatched issue, the manager: | ||
|
|
||
| 1. Infers the local repository from task text, task description, linked GitHub | ||
| URLs, or repo-like strings. | ||
| 2. Creates a dedicated git worktree under the configured Hermes worktree root. | ||
| 3. Creates a linked worker task in the manager project. | ||
| 4. Runs the configured worker command template with task and worktree context. | ||
| 5. Reviews the worker diff. | ||
| 6. Applies accepted changes into the integration worktree. | ||
| 7. Moves the main-board issue to `Review` for human QA. | ||
|
|
||
| The worker command is configured locally with `HV_HERMES_WORKER_COMMAND` or the | ||
| equivalent Hermes config value. Workers must not edit the integration worktree | ||
| directly. | ||
|
|
||
| ## Suggested Hermes Config | ||
|
|
||
| ```yaml | ||
| platforms: | ||
| zulip: | ||
| enabled: true | ||
|
|
||
| dev_team: | ||
| enabled: true | ||
| manager_identity: "${ZULIP_EMAIL}" | ||
| manager_project_name_template: "Hermes Manager - {email}" | ||
| watch_projects: "all" | ||
| repo_search_roots: | ||
| - ~/Work/happyvertical/repos | ||
| - ~/Work/anytown/repos | ||
| worktree_root: ~/.hermes/dev-team/worktrees | ||
| integration_root: ~/.hermes/dev-team/integration | ||
| worker_command: "${HV_HERMES_WORKER_COMMAND}" | ||
| main_buckets: [To-Do, Blocked, Doing, Review, Done] | ||
| manager_buckets: [Queued, Working, Integrating, Blocked, Closed] | ||
| status_updates: on_request | ||
| integration_gate: review_only | ||
| ``` | ||
|
|
||
| ## Blocking Conditions | ||
|
|
||
| Move the main-board issue or worker task to `Blocked` when: | ||
|
|
||
| - no local repository can be inferred | ||
| - the worker command is missing or fails before producing reviewable output | ||
| - a required credential or service is unavailable | ||
| - the manager cannot apply the worker diff cleanly | ||
| - the dev server or integration worktree is not reachable | ||
|
|
||
| Blocker comments must name the first concrete blocker and the smallest next | ||
| action. Never include secrets, tokens, cookies, passwords, or decrypted values. | ||
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
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 |
|---|---|---|
| @@ -0,0 +1,81 @@ | ||
| --- | ||
| name: hermes-manager | ||
| description: Use when operating Hermes Dev Team Mode, coordinating worker agents, managing Vikunja board state, or integrating fixes into a live dev-server worktree. | ||
| metadata: | ||
| short-description: Manage local Hermes developer workers | ||
| --- | ||
|
|
||
| # Hermes Manager Procedure | ||
|
|
||
| Use this procedure when the current Hermes agent is acting as the manager for | ||
| local developer workers. The human talks to this manager in Zulip and watches | ||
| canonical issue cards on Vikunja main project boards. Do not print or store | ||
| tokens, cookies, passwords, or decrypted secret values. | ||
|
|
||
| ## Manager Responsibilities | ||
|
|
||
| 1. Own communication with the human. | ||
| - Respond in Zulip as the single point of contact. | ||
| - Keep status quiet unless asked, except for clarifying questions, | ||
| acknowledgements of created issues, and blockers requiring human action. | ||
| 2. Own main-board state. | ||
| - Main project cards are canonical user-visible issues. | ||
| - Move main cards through `To-Do`, `Blocked`, `Doing`, `Review`, and `Done`. | ||
| - Auto-provision missing expected buckets through the Hermes runtime. | ||
| 3. Own worker dispatch. | ||
| - Use one manager project named `Hermes Manager - <email>`. | ||
| - Use manager-project buckets `Queued`, `Working`, `Integrating`, | ||
| `Blocked`, and `Closed`. | ||
| - Create one internal worker task per dispatched main-board issue. | ||
| 4. Own live integration. | ||
| - Workers must use isolated git worktrees. | ||
| - Only the manager may apply accepted worker output to the integration | ||
| worktree used by the local-network dev server. | ||
| - Integration is gated by manager review of the diff; local tests are | ||
| optional unless the task or repo instructions require them. | ||
|
|
||
| ## Zulip Intake | ||
|
|
||
| For each QA message, decide whether to create a new issue, update an existing | ||
| issue, ask for clarification, or ignore conversational noise. Do not create a | ||
| Vikunja task for every Zulip message. Prefer actionable main-board issues with | ||
| clear repro context. | ||
|
|
||
| ## Repository Inference | ||
|
|
||
| Infer the target repository from task text, descriptions, linked GitHub URLs, | ||
| and repo-like strings. Search configured repo roots such as | ||
| `~/Work/happyvertical/repos` and `~/Work/anytown/repos`, matching task GitHub | ||
| URLs to local git remotes. If inference is ambiguous or missing, block the task | ||
| and ask the human for the repo. | ||
|
|
||
| ## Worker Run Contract | ||
|
|
||
| For each per-task worker run, provide these values through the configured worker | ||
| command template or environment: | ||
|
|
||
| - main Vikunja task ID and URL | ||
| - worker Vikunja task ID and URL | ||
| - repository path | ||
| - worker worktree path | ||
| - branch name | ||
| - integration worktree path | ||
| - dev server URL when known | ||
| - manager identity | ||
|
|
||
| The worker should return reviewable output in its worktree and exit `0` when it | ||
| is ready for manager review. Non-zero exits, dirty state that cannot be | ||
| understood, or missing output are blockers. | ||
|
|
||
| ## Integration Gate | ||
|
|
||
| Before applying worker output: | ||
|
|
||
| 1. Read the worker task, comments, and diff. | ||
| 2. Confirm the diff is scoped to the main-board issue. | ||
| 3. Apply accepted changes into the integration worktree. | ||
| 4. Move the main-board issue to `Review`. | ||
| 5. Leave the worker task `Closed` or `Blocked` with a concise status comment. | ||
|
|
||
| If the patch does not apply cleanly, move both the worker task and main-board | ||
| issue to `Blocked` with the smallest next action. |
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.