Repository navigation
docs: overhaul README, orchestration rules, and all agent prompts - #617
Conversation
- Update README.md with current CLI commands, team-lead flow, --wish flag, agent directory, and worktree documentation - Expand orchestration rules with full team-lead lifecycle and command set - Rewrite PM prompt to promptMode: system with XML behavioral blocks - Refine all 8 worker prompts with XML blocks (promptMode: append) - Refine all 11 council prompts with XML blocks, preserving persona inspirations as perspective framing - Sync all flat .md copies with folder AGENTS.md files
|
Important Review skippedAuto reviews are disabled on base/target branches other than the default branch. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: ASSERTIVE Plan: Pro Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
✨ Finishing Touches🧪 Generate unit tests (beta)
📝 Coding Plan
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Summary of ChangesHello, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request focuses on overhauling the documentation, orchestration rules, and agent prompts to improve clarity, structure, and functionality. The changes aim to provide a more streamlined and autonomous experience, particularly for team-lead driven workflows, and to ensure consistency across all agent prompts and documentation files. Highlights
Changelog
Activity
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request refactors agent definition files to use a more structured, tag-based format for missions, processes, and constraints, and updates the README.md and genie-orchestration.md to introduce new autonomous team-lead functionality and associated CLI commands. Review comments highlight the need to add a 'criteria satisfied' report to the docs agent for consistency, re-add a 'minimal tool surface' constraint to the trace agent to prevent unintended write operations, and standardize the team name placeholder in genie-orchestration.md for clarity.
| <done_report> | ||
| Report when complete: | ||
| - Files created or updated | ||
| - Gaps that were filled | ||
| - Validation results | ||
| - Anything that remains unresolved | ||
|
|
||
| ## When I'm Done | ||
|
|
||
| I report: | ||
| - What I created or updated (files and sections) | ||
| - Which criteria are satisfied (with evidence) | ||
| - Validation results — every claim checked against code | ||
| - What remains undocumented or needs human judgment | ||
|
|
||
| Then my work is complete. | ||
|
|
||
| ## Scope | ||
|
|
||
| I am an intermediate worker. I execute the documentation task and report back. The orchestrator holds the full context window and makes the final ship/no-ship decision. I do not make that call. | ||
|
|
||
| ## Constraints | ||
| - Anything that remains undocumented or needs human judgment | ||
| </done_report> |
There was a problem hiding this comment.
The <done_report> for this agent is missing a crucial item. Other worker agents like engineer and fix are instructed to report on "Which criteria are satisfied (with evidence)". This is an important part of the completion report to confirm the agent's work aligns with the wish. I suggest adding it here for consistency and completeness.
| <done_report> | |
| Report when complete: | |
| - Files created or updated | |
| - Gaps that were filled | |
| - Validation results | |
| - Anything that remains unresolved | |
| ## When I'm Done | |
| I report: | |
| - What I created or updated (files and sections) | |
| - Which criteria are satisfied (with evidence) | |
| - Validation results — every claim checked against code | |
| - What remains undocumented or needs human judgment | |
| Then my work is complete. | |
| ## Scope | |
| I am an intermediate worker. I execute the documentation task and report back. The orchestrator holds the full context window and makes the final ship/no-ship decision. I do not make that call. | |
| ## Constraints | |
| - Anything that remains undocumented or needs human judgment | |
| </done_report> | |
| <done_report> | |
| Report when complete: | |
| - Files created or updated | |
| - Gaps that were filled | |
| - Which criteria are satisfied (with evidence) | |
| - Validation results — every claim checked against code | |
| - Anything that remains undocumented or needs human judgment | |
| </done_report> |
| <constraints> | ||
| - Never apply corrections — investigation only | ||
| - Never modify source files — read and trace only | ||
| - Always reproduce before theorizing — evidence over intuition | ||
| - Evidence required for every root cause claim — no speculation without proof | ||
| - Minimal tool surface — Read, Bash, Glob, Grep only | ||
| - Evidence required for every root cause claim | ||
| - Report everything discovered, even if it wasn't the primary target | ||
| </constraints> |
There was a problem hiding this comment.
The previous version of this prompt included the constraint: "Minimal tool surface — Read, Bash, Glob, Grep only". This is an important guardrail for an investigation-only agent to prevent it from attempting to use writing/editing tools. Consider re-adding this constraint to ensure the agent adheres to its read-only investigation role.
| <constraints> | |
| - Never apply corrections — investigation only | |
| - Never modify source files — read and trace only | |
| - Always reproduce before theorizing — evidence over intuition | |
| - Evidence required for every root cause claim — no speculation without proof | |
| - Minimal tool surface — Read, Bash, Glob, Grep only | |
| - Evidence required for every root cause claim | |
| - Report everything discovered, even if it wasn't the primary target | |
| </constraints> | |
| <constraints> | |
| - Never apply corrections — investigation only | |
| - Never modify source files — read and trace only | |
| - Always reproduce before theorizing — evidence over intuition | |
| - Evidence required for every root cause claim | |
| - Minimal tool surface — Read, Bash, Glob, Grep only | |
| - Report everything discovered, even if it wasn't the primary target | |
| </constraints> |
| **Full lifecycle:** | ||
|
|
||
| 1. **Create team with wish:** `genie team create <name> --repo <path> --wish <slug>` | ||
| - Creates a git worktree at `~/.genie/worktrees/<project>/<name>/` |
There was a problem hiding this comment.
There's a minor inconsistency in the placeholder for the team name. This file uses <name> for the worktree path, while README.md uses <team>. To improve clarity and consistency across all documentation, consider using a more descriptive and uniform placeholder like <team-name>.
| - Creates a git worktree at `~/.genie/worktrees/<project>/<name>/` | |
| - Creates a git worktree at `~/.genie/worktrees/<project>/<team-name>/` |
![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: 72e693c313
ℹ️ 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".
| | Eyeball generated code, miss a bug, fix at 2am | Automated `/review` with severity-tagged gaps | | ||
| | 45 min in, Claude forgets your instructions | Scoped specialists — no context window accumulates junk | | ||
| | 10 min of setup before any work starts | `genie work eng auth-bug#1` — inherits context automatically | | ||
| | 10 min of setup before any work starts | `genie team create auth-fix --wish auth-bug` — team-lead handles the rest | |
There was a problem hiding this comment.
This command example is not runnable as written because genie team create requires --repo <path>; invoking it without that flag returns error: required option '--repo <path>' not specified (confirmed via genie team create --help and running the command). Users who copy this line from the comparison table will fail immediately instead of reaching the autonomous flow.
Useful? React with 👍 / 👎.
- Add missing "criteria satisfied with evidence" to docs agent done_report - Restore "Minimal tool surface" constraint to trace agent - Add required --repo flag to comparison table example
Audit found 11 CRITICAL, 17 HIGH, 6 MEDIUM severity losses from the
XML refactoring. Restores:
- Scope/authority boundary ("intermediate worker") to all 8 workers
- Trace "investigation only, always" constraint + orchestrator handoff
- <execution_mode> sections to all 10 council agents (hybrid capabilities)
- <remember> philosophical grounding to 7 council agents
- council--tracer <thinking_style> with 3 decision heuristic patterns
- council--tracer detailed APPROVE/REJECT/MODIFY conditions
- council--benchmarker full methodology (setup, measurement, tools)
- PM strategic identity and metrics-driven framing
- PM escalation chain specificity (worker→lead→PM→human)
- <related_agents> context for benchmarker, measurer, questioner
- Checklist format (- [ ]) in all council rubrics
Merge the full 740-line prompt-optimizer reference directly into the /refine SKILL.md. The 10-rule system prompt is the entry point; the full reference (type detection, anti-patterns, core patterns, examples, quality checklist) follows as the comprehensive guide. Removes plugins/genie/references/prompt-optimizer.md — no more separate file to forget to load.
Audit found 2 NON-COMPLIANT and 5 NEEDS-WORK agents. Fixes: - refactor: Add D/I/V structure to Mode 2, success_criteria, never_do sections. Define confidence levels. Was NON-COMPLIANT, now COMPLIANT. - qa: Add weighted rubric (4 dimensions), evidence_format spec, clarify AND/OR in verdict gates. Was NON-COMPLIANT, now COMPLIANT. - reviewer: Add evidence format requirement (file:line citations) - engineer: Extract success_criteria and never_do from constraints - fix: Extract success_criteria and never_do from constraints - docs: Extract success_criteria and never_do from constraints - council: Add evidence_requirements schema, strengthen constraints with actionable specifics
Both prompts were missing explicit hand-off conditions between phases. Added **Gate:** lines to each phase defining: - What must be true before the next phase starts - What to do when a gate fails (retry, escalate, stop) PM: 8 phases now have gates. Consolidated redundant commands_reference into tool_usage section. Team-lead: 8 phases now have gates with specific failure conditions (2-round limits, blocked escalation, CI requirements). All 21 agent prompts now COMPLIANT with prompt-optimizer reference.
1 participant
Summary
genie team create --wish, agent directory section, worktree documentation, removed stale Hook Presets section--wishworkflow, complete command set organized by category (team, dispatch, agent, messaging, directory, infra)promptMode: systemwith XML behavioral blocks (<mission>,<principles>,<workflow>,<tool_usage>,<constraints>)promptMode: append, no role promptingpromptMode: append.mdcopies synced with folderAGENTS.mdfiles (43 files total)Net: -1,251 lines (cleaner, more structured prompts)
Wish
docs-overhaul
Test plan
bun run typecheck— passesbun run lint— passes (120 files, 0 fixes)bun test— 736/736 tests passbun run build— bundles successfully (0.35 MB)promptMode: system, all othersappendgenie --helpoutput