From e7f7620271ae670cb6327c8d93ec732fa5c19a5b Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Sun, 31 May 2026 23:07:47 +0000 Subject: [PATCH 1/3] feat: implement packet self-containment standard and update reviews - Updated AGENTS.md and task-packet-create skill to include ## Appendix requirement. - Added full context (AGENTS.md, README.md, ROP.md, HROP.md, skills/*) to review packets. - Updated worker report instructions to require appending to the packet file. - Superseded old ROP-003 review packets and created new self-contained ones (005, 006, 007). - Reordered ROP-003 packets in TASK.md and STATUS.md for correct execution flow. - Verified all changes and ensured compliance with HROP and Markdown standards. Co-authored-by: attogram <8653063+attogram@users.noreply.github.com> --- AGENTS.md | 9 +- .../ROP-003-diagnostic-reviews/STATUS.md | 23 +- .../ROP-003-diagnostic-reviews/TASK.md | 13 +- .../packets/005.review-jules.md | 523 ++++++++++++++++++ .../packets/006.review-gemini.md | 523 ++++++++++++++++++ .../packets/007.review-copilot.md | 523 ++++++++++++++++++ skills/task-packet-create/SKILL.md | 7 +- 7 files changed, 1607 insertions(+), 14 deletions(-) create mode 100644 active-tasks/ROP-003-diagnostic-reviews/packets/005.review-jules.md create mode 100644 active-tasks/ROP-003-diagnostic-reviews/packets/006.review-gemini.md create mode 100644 active-tasks/ROP-003-diagnostic-reviews/packets/007.review-copilot.md diff --git a/AGENTS.md b/AGENTS.md index 1ea6957..dadaa5e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -11,7 +11,9 @@ the User decides when a TASK or PACKET is "Done". - **TASK**: The macro objective (bug fix, feature, research). Tracked via `TASK.md` (ledger) and `STATUS.md` (dashboard). - **PACKET**: A self-contained unit of work that can be executed by anyone - with zero prior knowledge. + with zero prior knowledge. Packets MUST include a `## Appendix` with full + content of all files in scope of the packet (e.g. AGENTS.md, README.md, + ROP.md, HROP.md, and relevant skills). ## 2. Directory Structure ```text @@ -26,7 +28,10 @@ active-tasks/{taskName}/ 2. **Environment**: PM initializes task directory and `TASK.md`. 3. **Execution**: Work is broken into packets. PM offers handoff options to the User (Self, Subagent, Human, Other). -4. **Review**: Worker appends a Report. PM and User review against the DoD. +4. **Review**: Worker appends their report to the bottom of the packet file. + If the Worker does not have write access to the repo, they must show their + review to the user in an easy to copy box. PM and User review against + the DoD. 5. **Checkpoint**: User approves or requests modifications. ## 4. Roles diff --git a/active-tasks/ROP-003-diagnostic-reviews/STATUS.md b/active-tasks/ROP-003-diagnostic-reviews/STATUS.md index 8c7919b..5b4f550 100644 --- a/active-tasks/ROP-003-diagnostic-reviews/STATUS.md +++ b/active-tasks/ROP-003-diagnostic-reviews/STATUS.md @@ -1,16 +1,25 @@ -# 🟡 ROP-003 - ROP-003-diagnostic-reviews - 2026-05-31 11:35 UTC +# 🟡 ROP-003 - ROP-003-diagnostic-reviews - 2026-05-31 23:02 UTC ## Goal - Create a comprehensive `reviews.md` document containing critical and constructive reviews of ROP/HROP. ## Packet Status -- 🟡 001 - **001.review-jules.md** _(Pending)_ Get a critical review from Jules. -- 🟡 002 - **002.review-gemini.md** _(Pending)_ Get a critical review from Gemini. -- 🟡 003 - **003.review-copilot.md** _(Pending)_ Get a critical review from Copilot. -- 🟡 004 - **004.consolidate-reviews.md** _(Pending)_ Create reviews.md with all feedback. +- 🟢 001 - **001.review-jules.md** _(Superseded)_ Replaced by 005. +- 🟢 002 - **002.review-gemini.md** _(Superseded)_ Replaced by 006. +- 🟢 003 - **003.review-copilot.md** _(Superseded)_ Replaced by 007. +- 🟡 005 - **005.review-jules.md** _(Pending)_ New self-contained review + packet for Jules. +- 🟡 006 - **006.review-gemini.md** _(Pending)_ New self-contained review + packet for Gemini. +- 🟡 007 - **007.review-copilot.md** _(Pending)_ New self-contained review + packet for Copilot. +- 🟡 004 - **004.consolidate-reviews.md** _(Pending)_ Create reviews.md with all + feedback. +- 🟡 008 - **008.user-feedback-reviews** _(Pending)_ User reply to consolidated + reviews. ## Next Steps -- Begin collecting reviews starting with Packet 001. +- Execute new self-contained review packets 005, 006, and 007. -_(Jules)_ +_(PM Jules)_ diff --git a/active-tasks/ROP-003-diagnostic-reviews/TASK.md b/active-tasks/ROP-003-diagnostic-reviews/TASK.md index 2ffadca..b4c6cfa 100644 --- a/active-tasks/ROP-003-diagnostic-reviews/TASK.md +++ b/active-tasks/ROP-003-diagnostic-reviews/TASK.md @@ -23,12 +23,17 @@ improvement. ## Packet List -- 001 - review-jules - Pending - Get a critical review from Jules. -- 002 - review-gemini - Pending - Get a critical review from Gemini. -- 003 - review-copilot - Pending - Get a critical review from Copilot. +- 001 - review-jules - Superseded - Replaced by packet 005. +- 002 - review-gemini - Superseded - Replaced by packet 006. +- 003 - review-copilot - Superseded - Replaced by packet 007. +- 005 - review-jules-v2 - Pending - New self-contained review packet for Jules. +- 006 - review-gemini-v2 - Pending - New self-contained review packet for + Gemini. +- 007 - review-copilot-v2 - Pending - New self-contained review packet for + Copilot. - 004 - consolidate-reviews - Pending - Update reviews.md with all gathered feedback and PM summary. -- 005 - user-feedback-reviews - Pending - Packet for User to reply to the +- 008 - user-feedback-reviews - Pending - Packet for User to reply to the consolidated reviews summary. ## Log diff --git a/active-tasks/ROP-003-diagnostic-reviews/packets/005.review-jules.md b/active-tasks/ROP-003-diagnostic-reviews/packets/005.review-jules.md new file mode 100644 index 0000000..f7680a3 --- /dev/null +++ b/active-tasks/ROP-003-diagnostic-reviews/packets/005.review-jules.md @@ -0,0 +1,523 @@ +# Packet ROP-003 - 005 - review-jules + +## PRE-REQUISITES +- read access to repo + +## Context +- Goal: Obtain a critical, technical review of ROP/HROP from Jules. + +## Plan +1. Analyze README.md, AGENTS.md, ROP.md, and HROP.md (see appendix). +2. Review all files in skills/ (see appendix). +3. Identify at least three major risks or weaknesses in the current + specification. +4. Generate your review. + +## Review Requirements +- Field Summary: Max 80 characters. Optional ONE emoji/icon at the beginning. +- Field Review: Max 20 lines. Max 80 characters per line. Content is freeform. +- Attribution: {Your Full Agent Name} +- Instructions: Append your report to bottom of the packet file. If you do not + have write access to the repo, then show your review to the user in an easy + to copy box. + +## APPENDIX + +### AGENTS.md + +# Agents Protocol v3.2.5 +This is the agent control for the High ROP Workflow (HROP). All agents MUST +strictly adhere to this protocol to ensure consistent state management and +successful handoffs. + +## The Gatekeeper Rule +The User is the final judge and authority. The Agent cannot self-certify. Only +the User decides when a TASK or PACKET is "Done". + +## 1. Core Architecture +- **TASK**: The macro objective (bug fix, feature, research). Tracked via + `TASK.md` (ledger) and `STATUS.md` (dashboard). +- **PACKET**: A self-contained unit of work that can be executed by anyone + with zero prior knowledge. Packets MUST include a `## Appendix` with full + content of all files in scope of the packet (e.g. AGENTS.md, README.md, + ROP.md, HROP.md, and relevant skills). + +## 2. Directory Structure +```text +active-tasks/{taskName}/ +├── TASK.md # Internal Ledger: Goal, DoD, Master Plan, and Log. +├── STATUS.md # Macro Dashboard: Product of task-status-update skill. +└── packets/ # Sequential units of work (001.name.md). +``` + +## 3. Operational Workflow +1. **Discovery**: PM & User define Goal and Definition of Done. +2. **Environment**: PM initializes task directory and `TASK.md`. +3. **Execution**: Work is broken into packets. PM offers handoff options to + the User (Self, Subagent, Human, Other). +4. **Review**: Worker appends their report to the bottom of the packet file. + If the Worker does not have write access to the repo, they must show their + review to the user in an easy to copy box. PM and User review against + the DoD. +5. **Checkpoint**: User approves or requests modifications. + +## 4. Roles +- **PM Role**: Maintains state, tracks Master Plan, and guides the lifecycle. +- **Worker Role**: Executes a specific, assigned packet autonomously. + +## 5. Skills +The repository provides standardized skills for common operations like goal +discovery, packet creation, and status reporting. See `skills/` for details. + +### README.md + +# Restart Often Protocol (ROP) +- The Restart Often Protocol (ROP) is a method of working with AI Agents. +- Developers have the *Commit early, commit often, use git with working branches* philosphy. +- ROP applies that philosphy to Agent Workflow. +- Find your ROP sweetspot to make your architecture leaner and streatch your compute budget. +- [ROP.md](ROP.md) - Restart Often Protocol overview + +# High ROP Workflow (HROP) +Our implementation of an Opinionated High ROP Workflow. +- [HROP.md](HROP.md) - High ROP overview +- [AGENTS.md](AGENTS.md) - Agents Protocol +- [skills/](skills) - Agent skills for HROP + +# 🟠 [active-tasks](active-tasks) - 2026-05-31 11:40 UTC +- 🟠 [ROP-001](active-tasks/ROP-001-welcome-to-rop/TASK.md) - **[welcome-to-rop](active-tasks/ROP-001-welcome-to-rop/)** _(In Progress)_ Initial setup and docs. +- 🟠 [ROP-002](active-tasks/ROP-002-style-hn/TASK.md) - **[style-hn](active-tasks/ROP-002-style-hn/)** _(In Progress)_ Communication standards and HN post. +- 🟡 [ROP-003](active-tasks/ROP-003-diagnostic-reviews/TASK.md) - **[diagnostic-reviews](active-tasks/ROP-003-diagnostic-reviews/)** _(Pending)_ ROP/HROP critique collection. +- 🟢 [ROP-004](active-tasks/ROP-004-diagnostic-fluff/TASK.md) - **[diagnostic-fluff](active-tasks/ROP-004-diagnostic-fluff/)** _(Finished)_ Signal-to-noise ratio analysis. +- 🟢 [ROP-005](active-tasks/ROP-005-pointers-cleanup/TASK.md) - **[pointers-cleanup](active-tasks/ROP-005-pointers-cleanup/)** _(Done)_ Cleanup of root pointer files. +- 🟡 [ROP-006](active-tasks/ROP-006-github-auto-publish/TASK.md) - **[github-auto-publish](active-tasks/ROP-006-github-auto-publish/)** _(Pending)_ Auto-publish to GitHub Pages. +- 🟠 [ROP-007](active-tasks/ROP-007-welcome-clarity-and-focus/TASK.md) - **[welcome-clarity-and-focus](active-tasks/ROP-007-welcome-clarity-and-focus/)** _(In Progress)_ Reconcile docs and skills. + +## Next Steps +- Execute remaining packets in ROP-001 and ROP-002. +- Execute ROP-007 to reconcile core documentation. +- Update all status files to new formatting rules (ROP-009). + +_(PM Jules)_ + +### ROP.md + +# Restart Often Protocol (ROP) +The Restart Often Protocol (ROP) is a method of working with AI Agents that +decreases costs and increases developer happiness. + +## The Idea +Rooted in the "Commit early, commit often" philosophy, ROP is a +context-management discipline for multi-packet LLM workflows. It focuses on +shedding prior context between execution steps to convert quadratic cost +blow-up into predictable, linear spend. + +## The Keyword +**ROP** - The primary keyword and name of the protocol. + +## The Metric +**ROPness** - A metric measuring a system's adherence to the protocol, ranging +from 0 to 100. +- 0% ROP: Pure "append everything" approach (quadratic cost). +- 100% ROP: Pure stateless execution (linear cost). + +## The Math of ROPness +The higher your ROPness, the leaner your architecture and the further your +compute budget stretches. + +### Cost Formula +Total token volume (T) for a sequence of n packets each with base size s, and +ROPness factor r (0.0 to 1.0): + +T = n * s + [n(n - 1) / 2] * s * (1 - r) + +### ROPness Savings (n=10, s=100k, $10/M) +| ROPness % | Total Tokens | Cost | vs 0% | +| :--- | :--- | :--- | :--- | +| 0% | 5.5M | $55.00 | baseline | +| 20% | 4.6M | $46.00 | −16% | +| 40% | 3.7M | $37.00 | −33% | +| 60% | 2.8M | $28.00 | −49% | +| 80% | 1.9M | $19.00 | −65% | +| 100% | 1.0M | $10.00 | −82% | + +### Agent Performance Impact +Larger contexts cause performance degradation. High ROPness keeps context lean, +maintaining higher success rates. + +| ROPness % | Avg Success Rate | Total Improvement | +| :--- | :--- | :--- | +| 0% | 57.5% | baseline | +| 50% | 77.5% | +35% | +| 100% | 80.0% | +39% | + +## Architectural Mapping +| ROPness % | Architecture | Trade-off | +| :--- | :--- | :--- | +| 0% | Naive Append | Perfect recall, quadratic cost | +| 20% | Sliding Window | Good short-term memory, loses older context | +| 40% | Recursive Summarization | Balanced thematic retention | +| 60% | Vector DB / RAG | Targeted retrieval, lookup latency | +| 80% | Skeleton / State Vars | Minimal overhead, strict schema | +| 100% | Pure Stateless | Linear cost, requires decomposability | + +### HROP.md + +# High ROP Workflow (HROP) +HROP is our opinionated implementation of High ROPness in a workflow. + +## Target Audience +HROP is geared for small teams (the 1-3 member "sweet spot"). While it can +scale further, increased team size often leads to a rise in "janitor fails" +where state management becomes fragmented. + +## Human Summary of AGENTS.md +AGENTS.md is the formal contract for HROP. In simple terms: +- **Tasks** are the big goals. +- **Packets** are the small, self-contained work units. +- **PMs** (Project Managers) manage the state and task directories. +- **Workers** execute the individual packets. +- **User** is the final authority (Gatekeeper) who approves all work. + +Everything is tracked in `active-tasks/{taskName}/` using `TASK.md`, `STATUS.md`, +and the `packets/` subdirectory to ensure persistent memory and easy recovery +from context restarts. + +## Implementation +To maintain high ROP, you must save state continuously. The PM/User +collaboratively define Goals and Definitions of Done, then break the work into +sequential packets. After each packet, the User reviews the results and decides +whether to approve, modify, or pivot. + +## Reporting & Metrics +We use standardized reporting loops for qualitative and quantitative analysis. + +### FLUFFP Metric +FLUFFP is a metric (0-100) of wasted tokens vs. required tokens in a data +packet. It provides insight into possible optimizations per repo, task, or +packet. + +### Standardized Reporting Loop +For `fluffp.md` and `reviews.md`, the workflow follows a strict loop: +1. **Assignment**: PM assigns packets to each agent (e.g., Gemini, Copilot, + Jules). +2. **Intake**: PM collects all agent reports. +3. **Listing**: PM lists all reports in the target file (`{file}.md`). +4. **Distillation**: PM adds a summary with the most important issues + distilled from all reports. +5. **User Feedback**: PM creates a packet for the User to reply to the summary. +6. **Restart**: Once approved, the loop restarts with the previous reports and + User replies included as context. + +### skills/discover-goal/SKILL.md +--- +name: discover-goal +description: > + Use this skill to collaborate with the user to define the macro Goal + and Definition of Done for a task. +--- + +# Skill: Discover Goal v2.0 + +This skill enforces a collaborative process to isolate the exact, high-signal +objective of a task. The process depends on the clarity of the user's intent. + +## Discovery States + +### 1. No Goal (Vague/None) +If the user's request is non-existent or completely opaque: +- **Soft Scan**: Perform a "soft scan" of existing tasks in `active-tasks/` to + understand current priorities and context. +- **Prompt User**: Suggest a MAXIMUM of 3 options on how to continue. +- **Style**: Use very short messages until vagueness is reached or a goal + begins to emerge. + +### 2. Vague Goal +If the user provides a goal that is directionally correct but lacks detail: +- **Immediate Scaffolding**: Start scaffolding the task directory immediately + in `active-tasks/ROP-###-{name}/`. +- **Placeholders**: Initialize `TASK.md` and `STATUS.md` with placeholders for + details that are still being discovered. +- **Iterate**: Refine the Goal and DoD collaboratively while working within + the scaffolded directory. + +### 3. Strong Goal +If the user's intent is crystal clear and all requirements are understood: +- **Discovery Done**: Proceed directly to finalizing the `TASK.md` Master Plan + and initializing packets. + +## Refinement Process + +### Step 1: Define the Goal +- Proactively suggest refinements to remove ambiguity. +- Guide collaboratively: "Based on the request, I suggest our goal be [X]. Does + that capture the core objective?" + +### Step 2: Define the Definition of Done (DoD) +- Propose a concrete checklist of technical requirements. +- Invite user modification: "How should we adjust this list to ensure absolute + alignment?" + +### Step 3: Secure Final Gatekeeper Approval +- Present the combined Goal and DoD. +- Await explicit confirmation from the user that the definitions are final. +- Do not proceed with execution until the user approves. + +### skills/prefs-markdown/SKILL.md +--- +name: prefs-markdown +description: > + Use this skill as a style guide for generating Markdown content. + It provides rules for formatting, line length, and content. +--- + +# Markdown Preferences Skill v1.1 + +Adopt these preferences when generating content in Markdown format. + +## Philosophy +- Minimize Token Usage +- Optimize for human readability +- No Fluff + +## Scope +- Adhere to these rules when creating, modifying, or auditing Markdown files. + +## Lists +- Items start at the beginning of the line with `- ` +- 2 spaces per indent level for nested items + +## Markdown Headers +- All headers must have a blank line above them, except top-level `#` +- If a header has content, content must begin on the line directly after + the header, no blank line in between +- Example: +```markdown + +# Foo + +## Bar + +### Baz +{content} + +## Qux +{content} +``` + +## Line Length +- Markdown files MUST NOT exceed 80 characters per line. + - Exception for URLs and other elements that cannot be reasonably + broken. + +## Hyperlinking +- When linking, use hyperlinked relatively. + - Example: [`docs/Foo.md`](../../docs/Foo.md) +- Directories MUST NOT use a trailing slash in the URL. + - Example: [`docs`](../../docs) +- Validate the path before adding any link. + - You MUST run an empirical check (`ls`, `find`, etc.) to verify existence. + +## No Fluff +- Content must be strictly high-signal. Do NOT use: + - Emojis + - Decorative spacers (`---`) + - Conversational fillers + - Excessive **bolding** or *italics* without a clear purpose for emphasis. + +### skills/style-hn/SKILL.md +--- +name: style-hn +description: Use when drafting a Hacker News Show HN post. +--- + +# Skill: Style HN + +## Title +Show HN: {what it is} – {one-line technical hook} +No verbs. No adjectives. No exclamation marks. + +## Structure +1. The problem. Math if available. +2. The solution. One sentence. +3. Proof. Link or data. +4. One self-aware line. +5. The link. + +## Length +Uncomfortably short is correct. + +## Anti-Patterns +- "We built X to solve Y" +- "Excited to share" +- Bullet lists of features +- Explaining what the reader can infer + +## Voice +Write like a developer who almost didn't post this. + +### skills/task-packet-create/SKILL.md +--- +name: task-packet-create +description: > + Use this when you need to initialize + a new Packet. It ensures the Packet is fully self-contained and + adheres to the AGENTS.md standard. +--- + +# Skill: Task Packet Create v1.0 + +This skill ensures that every Packet is a self-contained unit of work that +can be executed by any entity (AI or Human) with zero prior context. + +## The Self-Containment Standard + +A Packet is considered "Faulty" if the Worker must stop and ask for +information that should have been provided. To prevent faulty packets, +every file MUST include: + +- Context: The "Why" and "What" of the work. + - Goal: One clear, actionable sentence. + - Background: Necessary history or architectural context. + - Key Files: Absolute paths to every file the Worker must touch or read. + - Resources: Specific URLs, docs, or environment variables. +- Pre-requisites: List of required tools (bash, jq), access (read/write), and + capabilities (web search). +- Plan: The exact, sequential steps (1, 2, 3) to complete the work. +- Report Requirements: Precise list of artifacts or data the Worker must + capture in their Report. Instructions MUST include: "Append your report to + bottom of the packet file. If you do not have write access to the repo, then + show your review to the user in an easy to copy box." +- Appendix: A `## Appendix` section containing the full content of all files + in scope for the packet. For core protocol reviews, this includes full + copies of AGENTS.md, README.md, ROP.md, HROP.md, and all files in `skills/`. + +## Rules for the PM + +1. Provide Path Certainty: Never use relative paths like `./src`. Use absolute + paths based on the project root. +2. Explicit Dependencies: If the packet requires a specific skill (e.g., + `skills/prefs-markdown`), you MUST list it in the Context. +3. Proof of Design: Do not create a "Code Change" packet until a "Research" + or "Design" packet has identified the exact lines of code to be modified. + +## Faulty Packet Check + +Before finalizing a packet, ask: "If I deleted my entire memory of this task +right now, could I still finish this work using ONLY this file?" If the +answer is No, the packet is incomplete. + +### skills/task-packet-review/SKILL.md +--- +name: task-packet-review +description: > + Use this when a Packet is reported as complete. It provides a + rigorous framework for verifying that the work meets the Report + Requirements and the Definition of Done. +--- + +# Skill: Task Packet Review v1.0 + +This skill ensures that the PM does not approve faulty or +incomplete work. Every report must be audited against the original +Packet and the global project standards. + +## The Review Checklist + +A Packet Report is only valid if it passes all of the following: + +1. Requirement Alignment: Does the Report contain every item listed in the + "Report Requirements" section of the Packet? +2. Plan Execution: Were all steps in the "Plan" followed? If not, did the + Worker provide a valid justification for the deviation? +3. Quality Standards: Does the work pass project-specific linting, + type-checking, and test suites? +4. Criteria Alignment: Does this specific unit of work satisfy the + acceptance criteria or milestones assigned to this Packet? + +## Review Outcomes + +- Pass: The report is complete and verified. Proceed to the Gatekeeper + Checkpoint. +- Fail: The report is missing data, has failed tests, or deviates from the + plan without explanation. Send the Packet back to the Worker for + remediation. + +## No Blind Trust + +The PM must independently verify the claims in the Report. If +the Worker says "All tests passed," the PM should confirm +the test output or rerun the command before approving. + +### skills/task-status-update/SKILL.md +--- +name: task-status-update +description: > + Use this when you need to draft a concise status update for a task. + Generates a well-formatted report, ready for copy-pasting. +--- + +# Skill: Task Status Update v4.0 +This skill drafts a clear, concise, and effective status update for a task. +The final output MUST be provided as plain Markdown text +to ensure easy copy-pasteability. + +## Guiding Principles +- Target Audience: Design the update for a busy Project Manager skimming + Jira tickets to grasp the exact status of the task instantly. +- Task-Level Context: Update must summarize progress on the entire task. +- Complete Scope: List every single packet to show the full picture, + regardless of whether it has started or not. +- High Signal: Omit conversational filler, decorative spacers, and emojis. +- Report, Don't Direct: Do not give commands to the user. +- PII Compliance: Do not include real names, email addresses, or other + personally identifiable information in reports. +- No Markdown Hyperlinks: Do not hide URLs inside markdown syntax. + Raw URLs are allowed only if completely necessary and appropriate. Links + are only permitted in `README.md` and MUST NOT be used in `STATUS.md`. +- Timestamps: Use UTC. You MUST verify the current date and time before + reporting by using available tools (e.g., `date` in bash) or checking the + system prompt. The format MUST be `{YYYY-MM-DD HH:MM UTC}`. +- Structural Layout: You MUST use a single `#` for the main headline and + exactly `##` for content sections. No other header depths are allowed. +- Style Preferences: Adhere to guidelines in `skills/prefs-markdown/SKILL.md`. +- Flat Lists: Start every list item at the beginning of the line with `- ` + Do not add extra vertical line spaces or padding between list items. +- Line Length: Hard-wrap lines to a maximum of 80 characters. + +## Status Update Structure +Generate your report using this exact structural template: + +``` + +# {ICON} {Ticket ID} - {exact name of task directory} - {YYYY-MM-DD HH:MM UTC} + +## Goal +- {Single-sentence summary of the overall task objective} + +## Packet Status +- 🟢 001 - **{name}** _(Complete)_ {Brief Description} +- 🟠 002 - **{name}** _(In Progress)_ {Brief Description} +- 🟡 003 - **{name}** _(Pending)_ {Brief Description} +- 🔴 004 - **{name}** _(Blocked)_ {Brief Description} + +## Next Steps +- {example: Packet 004 is next, pending completion of Packet 003} + +({PM agents}, {Worker agents}) +``` + +## Placeholders +- {ICON}: Status-specific icon (🔴, 🟡, 🟠, 🟢). +- {Ticket ID}: The task ID following the `ROP-####` format. +- {exact name of task directory}: The folder name in `active-tasks/`. +- {PM agents}: Comma-separated list of all PM agents who have worked on this + task, each prefixed with "PM ". The current PM MUST be listed first. +- {Worker agents}: Comma-separated list of all Worker agents who have worked + on this task, each prefixed with "Worker ". + +## Status Icons +- 🔴 Blocked: The packet cannot proceed. +- 🟡 Pending: The packet is waiting to be started. +- 🟠 In Progress / Routed: The packet is currently being worked on. +- 🟢 Task done: The packet has been completed successfully. diff --git a/active-tasks/ROP-003-diagnostic-reviews/packets/006.review-gemini.md b/active-tasks/ROP-003-diagnostic-reviews/packets/006.review-gemini.md new file mode 100644 index 0000000..aa9e33b --- /dev/null +++ b/active-tasks/ROP-003-diagnostic-reviews/packets/006.review-gemini.md @@ -0,0 +1,523 @@ +# Packet ROP-003 - 006 - review-gemini + +## PRE-REQUISITES +- read access to repo + +## Context +- Goal: Obtain a critical, technical review of ROP/HROP from Gemini. + +## Plan +1. Analyze README.md, AGENTS.md, ROP.md, and HROP.md (see appendix). +2. Review all files in skills/ (see appendix). +3. Identify at least three major risks or weaknesses in the current + specification. +4. Generate your review. + +## Review Requirements +- Field Summary: Max 80 characters. Optional ONE emoji/icon at the beginning. +- Field Review: Max 20 lines. Max 80 characters per line. Content is freeform. +- Attribution: {Your Full Agent Name} +- Instructions: Append your report to bottom of the packet file. If you do not + have write access to the repo, then show your review to the user in an easy + to copy box. + +## APPENDIX + +### AGENTS.md + +# Agents Protocol v3.2.5 +This is the agent control for the High ROP Workflow (HROP). All agents MUST +strictly adhere to this protocol to ensure consistent state management and +successful handoffs. + +## The Gatekeeper Rule +The User is the final judge and authority. The Agent cannot self-certify. Only +the User decides when a TASK or PACKET is "Done". + +## 1. Core Architecture +- **TASK**: The macro objective (bug fix, feature, research). Tracked via + `TASK.md` (ledger) and `STATUS.md` (dashboard). +- **PACKET**: A self-contained unit of work that can be executed by anyone + with zero prior knowledge. Packets MUST include a `## Appendix` with full + content of all files in scope of the packet (e.g. AGENTS.md, README.md, + ROP.md, HROP.md, and relevant skills). + +## 2. Directory Structure +```text +active-tasks/{taskName}/ +├── TASK.md # Internal Ledger: Goal, DoD, Master Plan, and Log. +├── STATUS.md # Macro Dashboard: Product of task-status-update skill. +└── packets/ # Sequential units of work (001.name.md). +``` + +## 3. Operational Workflow +1. **Discovery**: PM & User define Goal and Definition of Done. +2. **Environment**: PM initializes task directory and `TASK.md`. +3. **Execution**: Work is broken into packets. PM offers handoff options to + the User (Self, Subagent, Human, Other). +4. **Review**: Worker appends their report to the bottom of the packet file. + If the Worker does not have write access to the repo, they must show their + review to the user in an easy to copy box. PM and User review against + the DoD. +5. **Checkpoint**: User approves or requests modifications. + +## 4. Roles +- **PM Role**: Maintains state, tracks Master Plan, and guides the lifecycle. +- **Worker Role**: Executes a specific, assigned packet autonomously. + +## 5. Skills +The repository provides standardized skills for common operations like goal +discovery, packet creation, and status reporting. See `skills/` for details. + +### README.md + +# Restart Often Protocol (ROP) +- The Restart Often Protocol (ROP) is a method of working with AI Agents. +- Developers have the *Commit early, commit often, use git with working branches* philosphy. +- ROP applies that philosphy to Agent Workflow. +- Find your ROP sweetspot to make your architecture leaner and streatch your compute budget. +- [ROP.md](ROP.md) - Restart Often Protocol overview + +# High ROP Workflow (HROP) +Our implementation of an Opinionated High ROP Workflow. +- [HROP.md](HROP.md) - High ROP overview +- [AGENTS.md](AGENTS.md) - Agents Protocol +- [skills/](skills) - Agent skills for HROP + +# 🟠 [active-tasks](active-tasks) - 2026-05-31 11:40 UTC +- 🟠 [ROP-001](active-tasks/ROP-001-welcome-to-rop/TASK.md) - **[welcome-to-rop](active-tasks/ROP-001-welcome-to-rop/)** _(In Progress)_ Initial setup and docs. +- 🟠 [ROP-002](active-tasks/ROP-002-style-hn/TASK.md) - **[style-hn](active-tasks/ROP-002-style-hn/)** _(In Progress)_ Communication standards and HN post. +- 🟡 [ROP-003](active-tasks/ROP-003-diagnostic-reviews/TASK.md) - **[diagnostic-reviews](active-tasks/ROP-003-diagnostic-reviews/)** _(Pending)_ ROP/HROP critique collection. +- 🟢 [ROP-004](active-tasks/ROP-004-diagnostic-fluff/TASK.md) - **[diagnostic-fluff](active-tasks/ROP-004-diagnostic-fluff/)** _(Finished)_ Signal-to-noise ratio analysis. +- 🟢 [ROP-005](active-tasks/ROP-005-pointers-cleanup/TASK.md) - **[pointers-cleanup](active-tasks/ROP-005-pointers-cleanup/)** _(Done)_ Cleanup of root pointer files. +- 🟡 [ROP-006](active-tasks/ROP-006-github-auto-publish/TASK.md) - **[github-auto-publish](active-tasks/ROP-006-github-auto-publish/)** _(Pending)_ Auto-publish to GitHub Pages. +- 🟠 [ROP-007](active-tasks/ROP-007-welcome-clarity-and-focus/TASK.md) - **[welcome-clarity-and-focus](active-tasks/ROP-007-welcome-clarity-and-focus/)** _(In Progress)_ Reconcile docs and skills. + +## Next Steps +- Execute remaining packets in ROP-001 and ROP-002. +- Execute ROP-007 to reconcile core documentation. +- Update all status files to new formatting rules (ROP-009). + +_(PM Jules)_ + +### ROP.md + +# Restart Often Protocol (ROP) +The Restart Often Protocol (ROP) is a method of working with AI Agents that +decreases costs and increases developer happiness. + +## The Idea +Rooted in the "Commit early, commit often" philosophy, ROP is a +context-management discipline for multi-packet LLM workflows. It focuses on +shedding prior context between execution steps to convert quadratic cost +blow-up into predictable, linear spend. + +## The Keyword +**ROP** - The primary keyword and name of the protocol. + +## The Metric +**ROPness** - A metric measuring a system's adherence to the protocol, ranging +from 0 to 100. +- 0% ROP: Pure "append everything" approach (quadratic cost). +- 100% ROP: Pure stateless execution (linear cost). + +## The Math of ROPness +The higher your ROPness, the leaner your architecture and the further your +compute budget stretches. + +### Cost Formula +Total token volume (T) for a sequence of n packets each with base size s, and +ROPness factor r (0.0 to 1.0): + +T = n * s + [n(n - 1) / 2] * s * (1 - r) + +### ROPness Savings (n=10, s=100k, $10/M) +| ROPness % | Total Tokens | Cost | vs 0% | +| :--- | :--- | :--- | :--- | +| 0% | 5.5M | $55.00 | baseline | +| 20% | 4.6M | $46.00 | −16% | +| 40% | 3.7M | $37.00 | −33% | +| 60% | 2.8M | $28.00 | −49% | +| 80% | 1.9M | $19.00 | −65% | +| 100% | 1.0M | $10.00 | −82% | + +### Agent Performance Impact +Larger contexts cause performance degradation. High ROPness keeps context lean, +maintaining higher success rates. + +| ROPness % | Avg Success Rate | Total Improvement | +| :--- | :--- | :--- | +| 0% | 57.5% | baseline | +| 50% | 77.5% | +35% | +| 100% | 80.0% | +39% | + +## Architectural Mapping +| ROPness % | Architecture | Trade-off | +| :--- | :--- | :--- | +| 0% | Naive Append | Perfect recall, quadratic cost | +| 20% | Sliding Window | Good short-term memory, loses older context | +| 40% | Recursive Summarization | Balanced thematic retention | +| 60% | Vector DB / RAG | Targeted retrieval, lookup latency | +| 80% | Skeleton / State Vars | Minimal overhead, strict schema | +| 100% | Pure Stateless | Linear cost, requires decomposability | + +### HROP.md + +# High ROP Workflow (HROP) +HROP is our opinionated implementation of High ROPness in a workflow. + +## Target Audience +HROP is geared for small teams (the 1-3 member "sweet spot"). While it can +scale further, increased team size often leads to a rise in "janitor fails" +where state management becomes fragmented. + +## Human Summary of AGENTS.md +AGENTS.md is the formal contract for HROP. In simple terms: +- **Tasks** are the big goals. +- **Packets** are the small, self-contained work units. +- **PMs** (Project Managers) manage the state and task directories. +- **Workers** execute the individual packets. +- **User** is the final authority (Gatekeeper) who approves all work. + +Everything is tracked in `active-tasks/{taskName}/` using `TASK.md`, `STATUS.md`, +and the `packets/` subdirectory to ensure persistent memory and easy recovery +from context restarts. + +## Implementation +To maintain high ROP, you must save state continuously. The PM/User +collaboratively define Goals and Definitions of Done, then break the work into +sequential packets. After each packet, the User reviews the results and decides +whether to approve, modify, or pivot. + +## Reporting & Metrics +We use standardized reporting loops for qualitative and quantitative analysis. + +### FLUFFP Metric +FLUFFP is a metric (0-100) of wasted tokens vs. required tokens in a data +packet. It provides insight into possible optimizations per repo, task, or +packet. + +### Standardized Reporting Loop +For `fluffp.md` and `reviews.md`, the workflow follows a strict loop: +1. **Assignment**: PM assigns packets to each agent (e.g., Gemini, Copilot, + Jules). +2. **Intake**: PM collects all agent reports. +3. **Listing**: PM lists all reports in the target file (`{file}.md`). +4. **Distillation**: PM adds a summary with the most important issues + distilled from all reports. +5. **User Feedback**: PM creates a packet for the User to reply to the summary. +6. **Restart**: Once approved, the loop restarts with the previous reports and + User replies included as context. + +### skills/discover-goal/SKILL.md +--- +name: discover-goal +description: > + Use this skill to collaborate with the user to define the macro Goal + and Definition of Done for a task. +--- + +# Skill: Discover Goal v2.0 + +This skill enforces a collaborative process to isolate the exact, high-signal +objective of a task. The process depends on the clarity of the user's intent. + +## Discovery States + +### 1. No Goal (Vague/None) +If the user's request is non-existent or completely opaque: +- **Soft Scan**: Perform a "soft scan" of existing tasks in `active-tasks/` to + understand current priorities and context. +- **Prompt User**: Suggest a MAXIMUM of 3 options on how to continue. +- **Style**: Use very short messages until vagueness is reached or a goal + begins to emerge. + +### 2. Vague Goal +If the user provides a goal that is directionally correct but lacks detail: +- **Immediate Scaffolding**: Start scaffolding the task directory immediately + in `active-tasks/ROP-###-{name}/`. +- **Placeholders**: Initialize `TASK.md` and `STATUS.md` with placeholders for + details that are still being discovered. +- **Iterate**: Refine the Goal and DoD collaboratively while working within + the scaffolded directory. + +### 3. Strong Goal +If the user's intent is crystal clear and all requirements are understood: +- **Discovery Done**: Proceed directly to finalizing the `TASK.md` Master Plan + and initializing packets. + +## Refinement Process + +### Step 1: Define the Goal +- Proactively suggest refinements to remove ambiguity. +- Guide collaboratively: "Based on the request, I suggest our goal be [X]. Does + that capture the core objective?" + +### Step 2: Define the Definition of Done (DoD) +- Propose a concrete checklist of technical requirements. +- Invite user modification: "How should we adjust this list to ensure absolute + alignment?" + +### Step 3: Secure Final Gatekeeper Approval +- Present the combined Goal and DoD. +- Await explicit confirmation from the user that the definitions are final. +- Do not proceed with execution until the user approves. + +### skills/prefs-markdown/SKILL.md +--- +name: prefs-markdown +description: > + Use this skill as a style guide for generating Markdown content. + It provides rules for formatting, line length, and content. +--- + +# Markdown Preferences Skill v1.1 + +Adopt these preferences when generating content in Markdown format. + +## Philosophy +- Minimize Token Usage +- Optimize for human readability +- No Fluff + +## Scope +- Adhere to these rules when creating, modifying, or auditing Markdown files. + +## Lists +- Items start at the beginning of the line with `- ` +- 2 spaces per indent level for nested items + +## Markdown Headers +- All headers must have a blank line above them, except top-level `#` +- If a header has content, content must begin on the line directly after + the header, no blank line in between +- Example: +```markdown + +# Foo + +## Bar + +### Baz +{content} + +## Qux +{content} +``` + +## Line Length +- Markdown files MUST NOT exceed 80 characters per line. + - Exception for URLs and other elements that cannot be reasonably + broken. + +## Hyperlinking +- When linking, use hyperlinked relatively. + - Example: [`docs/Foo.md`](../../docs/Foo.md) +- Directories MUST NOT use a trailing slash in the URL. + - Example: [`docs`](../../docs) +- Validate the path before adding any link. + - You MUST run an empirical check (`ls`, `find`, etc.) to verify existence. + +## No Fluff +- Content must be strictly high-signal. Do NOT use: + - Emojis + - Decorative spacers (`---`) + - Conversational fillers + - Excessive **bolding** or *italics* without a clear purpose for emphasis. + +### skills/style-hn/SKILL.md +--- +name: style-hn +description: Use when drafting a Hacker News Show HN post. +--- + +# Skill: Style HN + +## Title +Show HN: {what it is} – {one-line technical hook} +No verbs. No adjectives. No exclamation marks. + +## Structure +1. The problem. Math if available. +2. The solution. One sentence. +3. Proof. Link or data. +4. One self-aware line. +5. The link. + +## Length +Uncomfortably short is correct. + +## Anti-Patterns +- "We built X to solve Y" +- "Excited to share" +- Bullet lists of features +- Explaining what the reader can infer + +## Voice +Write like a developer who almost didn't post this. + +### skills/task-packet-create/SKILL.md +--- +name: task-packet-create +description: > + Use this when you need to initialize + a new Packet. It ensures the Packet is fully self-contained and + adheres to the AGENTS.md standard. +--- + +# Skill: Task Packet Create v1.0 + +This skill ensures that every Packet is a self-contained unit of work that +can be executed by any entity (AI or Human) with zero prior context. + +## The Self-Containment Standard + +A Packet is considered "Faulty" if the Worker must stop and ask for +information that should have been provided. To prevent faulty packets, +every file MUST include: + +- Context: The "Why" and "What" of the work. + - Goal: One clear, actionable sentence. + - Background: Necessary history or architectural context. + - Key Files: Absolute paths to every file the Worker must touch or read. + - Resources: Specific URLs, docs, or environment variables. +- Pre-requisites: List of required tools (bash, jq), access (read/write), and + capabilities (web search). +- Plan: The exact, sequential steps (1, 2, 3) to complete the work. +- Report Requirements: Precise list of artifacts or data the Worker must + capture in their Report. Instructions MUST include: "Append your report to + bottom of the packet file. If you do not have write access to the repo, then + show your review to the user in an easy to copy box." +- Appendix: A `## Appendix` section containing the full content of all files + in scope for the packet. For core protocol reviews, this includes full + copies of AGENTS.md, README.md, ROP.md, HROP.md, and all files in `skills/`. + +## Rules for the PM + +1. Provide Path Certainty: Never use relative paths like `./src`. Use absolute + paths based on the project root. +2. Explicit Dependencies: If the packet requires a specific skill (e.g., + `skills/prefs-markdown`), you MUST list it in the Context. +3. Proof of Design: Do not create a "Code Change" packet until a "Research" + or "Design" packet has identified the exact lines of code to be modified. + +## Faulty Packet Check + +Before finalizing a packet, ask: "If I deleted my entire memory of this task +right now, could I still finish this work using ONLY this file?" If the +answer is No, the packet is incomplete. + +### skills/task-packet-review/SKILL.md +--- +name: task-packet-review +description: > + Use this when a Packet is reported as complete. It provides a + rigorous framework for verifying that the work meets the Report + Requirements and the Definition of Done. +--- + +# Skill: Task Packet Review v1.0 + +This skill ensures that the PM does not approve faulty or +incomplete work. Every report must be audited against the original +Packet and the global project standards. + +## The Review Checklist + +A Packet Report is only valid if it passes all of the following: + +1. Requirement Alignment: Does the Report contain every item listed in the + "Report Requirements" section of the Packet? +2. Plan Execution: Were all steps in the "Plan" followed? If not, did the + Worker provide a valid justification for the deviation? +3. Quality Standards: Does the work pass project-specific linting, + type-checking, and test suites? +4. Criteria Alignment: Does this specific unit of work satisfy the + acceptance criteria or milestones assigned to this Packet? + +## Review Outcomes + +- Pass: The report is complete and verified. Proceed to the Gatekeeper + Checkpoint. +- Fail: The report is missing data, has failed tests, or deviates from the + plan without explanation. Send the Packet back to the Worker for + remediation. + +## No Blind Trust + +The PM must independently verify the claims in the Report. If +the Worker says "All tests passed," the PM should confirm +the test output or rerun the command before approving. + +### skills/task-status-update/SKILL.md +--- +name: task-status-update +description: > + Use this when you need to draft a concise status update for a task. + Generates a well-formatted report, ready for copy-pasting. +--- + +# Skill: Task Status Update v4.0 +This skill drafts a clear, concise, and effective status update for a task. +The final output MUST be provided as plain Markdown text +to ensure easy copy-pasteability. + +## Guiding Principles +- Target Audience: Design the update for a busy Project Manager skimming + Jira tickets to grasp the exact status of the task instantly. +- Task-Level Context: Update must summarize progress on the entire task. +- Complete Scope: List every single packet to show the full picture, + regardless of whether it has started or not. +- High Signal: Omit conversational filler, decorative spacers, and emojis. +- Report, Don't Direct: Do not give commands to the user. +- PII Compliance: Do not include real names, email addresses, or other + personally identifiable information in reports. +- No Markdown Hyperlinks: Do not hide URLs inside markdown syntax. + Raw URLs are allowed only if completely necessary and appropriate. Links + are only permitted in `README.md` and MUST NOT be used in `STATUS.md`. +- Timestamps: Use UTC. You MUST verify the current date and time before + reporting by using available tools (e.g., `date` in bash) or checking the + system prompt. The format MUST be `{YYYY-MM-DD HH:MM UTC}`. +- Structural Layout: You MUST use a single `#` for the main headline and + exactly `##` for content sections. No other header depths are allowed. +- Style Preferences: Adhere to guidelines in `skills/prefs-markdown/SKILL.md`. +- Flat Lists: Start every list item at the beginning of the line with `- ` + Do not add extra vertical line spaces or padding between list items. +- Line Length: Hard-wrap lines to a maximum of 80 characters. + +## Status Update Structure +Generate your report using this exact structural template: + +``` + +# {ICON} {Ticket ID} - {exact name of task directory} - {YYYY-MM-DD HH:MM UTC} + +## Goal +- {Single-sentence summary of the overall task objective} + +## Packet Status +- 🟢 001 - **{name}** _(Complete)_ {Brief Description} +- 🟠 002 - **{name}** _(In Progress)_ {Brief Description} +- 🟡 003 - **{name}** _(Pending)_ {Brief Description} +- 🔴 004 - **{name}** _(Blocked)_ {Brief Description} + +## Next Steps +- {example: Packet 004 is next, pending completion of Packet 003} + +({PM agents}, {Worker agents}) +``` + +## Placeholders +- {ICON}: Status-specific icon (🔴, 🟡, 🟠, 🟢). +- {Ticket ID}: The task ID following the `ROP-####` format. +- {exact name of task directory}: The folder name in `active-tasks/`. +- {PM agents}: Comma-separated list of all PM agents who have worked on this + task, each prefixed with "PM ". The current PM MUST be listed first. +- {Worker agents}: Comma-separated list of all Worker agents who have worked + on this task, each prefixed with "Worker ". + +## Status Icons +- 🔴 Blocked: The packet cannot proceed. +- 🟡 Pending: The packet is waiting to be started. +- 🟠 In Progress / Routed: The packet is currently being worked on. +- 🟢 Task done: The packet has been completed successfully. diff --git a/active-tasks/ROP-003-diagnostic-reviews/packets/007.review-copilot.md b/active-tasks/ROP-003-diagnostic-reviews/packets/007.review-copilot.md new file mode 100644 index 0000000..63c4be2 --- /dev/null +++ b/active-tasks/ROP-003-diagnostic-reviews/packets/007.review-copilot.md @@ -0,0 +1,523 @@ +# Packet ROP-003 - 007 - review-copilot + +## PRE-REQUISITES +- read access to repo + +## Context +- Goal: Obtain a critical, technical review of ROP/HROP from Copilot. + +## Plan +1. Analyze README.md, AGENTS.md, ROP.md, and HROP.md (see appendix). +2. Review all files in skills/ (see appendix). +3. Identify at least three major risks or weaknesses in the current + specification. +4. Generate your review. + +## Review Requirements +- Field Summary: Max 80 characters. Optional ONE emoji/icon at the beginning. +- Field Review: Max 20 lines. Max 80 characters per line. Content is freeform. +- Attribution: {Your Full Agent Name} +- Instructions: Append your report to bottom of the packet file. If you do not + have write access to the repo, then show your review to the user in an easy + to copy box. + +## APPENDIX + +### AGENTS.md + +# Agents Protocol v3.2.5 +This is the agent control for the High ROP Workflow (HROP). All agents MUST +strictly adhere to this protocol to ensure consistent state management and +successful handoffs. + +## The Gatekeeper Rule +The User is the final judge and authority. The Agent cannot self-certify. Only +the User decides when a TASK or PACKET is "Done". + +## 1. Core Architecture +- **TASK**: The macro objective (bug fix, feature, research). Tracked via + `TASK.md` (ledger) and `STATUS.md` (dashboard). +- **PACKET**: A self-contained unit of work that can be executed by anyone + with zero prior knowledge. Packets MUST include a `## Appendix` with full + content of all files in scope of the packet (e.g. AGENTS.md, README.md, + ROP.md, HROP.md, and relevant skills). + +## 2. Directory Structure +```text +active-tasks/{taskName}/ +├── TASK.md # Internal Ledger: Goal, DoD, Master Plan, and Log. +├── STATUS.md # Macro Dashboard: Product of task-status-update skill. +└── packets/ # Sequential units of work (001.name.md). +``` + +## 3. Operational Workflow +1. **Discovery**: PM & User define Goal and Definition of Done. +2. **Environment**: PM initializes task directory and `TASK.md`. +3. **Execution**: Work is broken into packets. PM offers handoff options to + the User (Self, Subagent, Human, Other). +4. **Review**: Worker appends their report to the bottom of the packet file. + If the Worker does not have write access to the repo, they must show their + review to the user in an easy to copy box. PM and User review against + the DoD. +5. **Checkpoint**: User approves or requests modifications. + +## 4. Roles +- **PM Role**: Maintains state, tracks Master Plan, and guides the lifecycle. +- **Worker Role**: Executes a specific, assigned packet autonomously. + +## 5. Skills +The repository provides standardized skills for common operations like goal +discovery, packet creation, and status reporting. See `skills/` for details. + +### README.md + +# Restart Often Protocol (ROP) +- The Restart Often Protocol (ROP) is a method of working with AI Agents. +- Developers have the *Commit early, commit often, use git with working branches* philosphy. +- ROP applies that philosphy to Agent Workflow. +- Find your ROP sweetspot to make your architecture leaner and streatch your compute budget. +- [ROP.md](ROP.md) - Restart Often Protocol overview + +# High ROP Workflow (HROP) +Our implementation of an Opinionated High ROP Workflow. +- [HROP.md](HROP.md) - High ROP overview +- [AGENTS.md](AGENTS.md) - Agents Protocol +- [skills/](skills) - Agent skills for HROP + +# 🟠 [active-tasks](active-tasks) - 2026-05-31 11:40 UTC +- 🟠 [ROP-001](active-tasks/ROP-001-welcome-to-rop/TASK.md) - **[welcome-to-rop](active-tasks/ROP-001-welcome-to-rop/)** _(In Progress)_ Initial setup and docs. +- 🟠 [ROP-002](active-tasks/ROP-002-style-hn/TASK.md) - **[style-hn](active-tasks/ROP-002-style-hn/)** _(In Progress)_ Communication standards and HN post. +- 🟡 [ROP-003](active-tasks/ROP-003-diagnostic-reviews/TASK.md) - **[diagnostic-reviews](active-tasks/ROP-003-diagnostic-reviews/)** _(Pending)_ ROP/HROP critique collection. +- 🟢 [ROP-004](active-tasks/ROP-004-diagnostic-fluff/TASK.md) - **[diagnostic-fluff](active-tasks/ROP-004-diagnostic-fluff/)** _(Finished)_ Signal-to-noise ratio analysis. +- 🟢 [ROP-005](active-tasks/ROP-005-pointers-cleanup/TASK.md) - **[pointers-cleanup](active-tasks/ROP-005-pointers-cleanup/)** _(Done)_ Cleanup of root pointer files. +- 🟡 [ROP-006](active-tasks/ROP-006-github-auto-publish/TASK.md) - **[github-auto-publish](active-tasks/ROP-006-github-auto-publish/)** _(Pending)_ Auto-publish to GitHub Pages. +- 🟠 [ROP-007](active-tasks/ROP-007-welcome-clarity-and-focus/TASK.md) - **[welcome-clarity-and-focus](active-tasks/ROP-007-welcome-clarity-and-focus/)** _(In Progress)_ Reconcile docs and skills. + +## Next Steps +- Execute remaining packets in ROP-001 and ROP-002. +- Execute ROP-007 to reconcile core documentation. +- Update all status files to new formatting rules (ROP-009). + +_(PM Jules)_ + +### ROP.md + +# Restart Often Protocol (ROP) +The Restart Often Protocol (ROP) is a method of working with AI Agents that +decreases costs and increases developer happiness. + +## The Idea +Rooted in the "Commit early, commit often" philosophy, ROP is a +context-management discipline for multi-packet LLM workflows. It focuses on +shedding prior context between execution steps to convert quadratic cost +blow-up into predictable, linear spend. + +## The Keyword +**ROP** - The primary keyword and name of the protocol. + +## The Metric +**ROPness** - A metric measuring a system's adherence to the protocol, ranging +from 0 to 100. +- 0% ROP: Pure "append everything" approach (quadratic cost). +- 100% ROP: Pure stateless execution (linear cost). + +## The Math of ROPness +The higher your ROPness, the leaner your architecture and the further your +compute budget stretches. + +### Cost Formula +Total token volume (T) for a sequence of n packets each with base size s, and +ROPness factor r (0.0 to 1.0): + +T = n * s + [n(n - 1) / 2] * s * (1 - r) + +### ROPness Savings (n=10, s=100k, $10/M) +| ROPness % | Total Tokens | Cost | vs 0% | +| :--- | :--- | :--- | :--- | +| 0% | 5.5M | $55.00 | baseline | +| 20% | 4.6M | $46.00 | −16% | +| 40% | 3.7M | $37.00 | −33% | +| 60% | 2.8M | $28.00 | −49% | +| 80% | 1.9M | $19.00 | −65% | +| 100% | 1.0M | $10.00 | −82% | + +### Agent Performance Impact +Larger contexts cause performance degradation. High ROPness keeps context lean, +maintaining higher success rates. + +| ROPness % | Avg Success Rate | Total Improvement | +| :--- | :--- | :--- | +| 0% | 57.5% | baseline | +| 50% | 77.5% | +35% | +| 100% | 80.0% | +39% | + +## Architectural Mapping +| ROPness % | Architecture | Trade-off | +| :--- | :--- | :--- | +| 0% | Naive Append | Perfect recall, quadratic cost | +| 20% | Sliding Window | Good short-term memory, loses older context | +| 40% | Recursive Summarization | Balanced thematic retention | +| 60% | Vector DB / RAG | Targeted retrieval, lookup latency | +| 80% | Skeleton / State Vars | Minimal overhead, strict schema | +| 100% | Pure Stateless | Linear cost, requires decomposability | + +### HROP.md + +# High ROP Workflow (HROP) +HROP is our opinionated implementation of High ROPness in a workflow. + +## Target Audience +HROP is geared for small teams (the 1-3 member "sweet spot"). While it can +scale further, increased team size often leads to a rise in "janitor fails" +where state management becomes fragmented. + +## Human Summary of AGENTS.md +AGENTS.md is the formal contract for HROP. In simple terms: +- **Tasks** are the big goals. +- **Packets** are the small, self-contained work units. +- **PMs** (Project Managers) manage the state and task directories. +- **Workers** execute the individual packets. +- **User** is the final authority (Gatekeeper) who approves all work. + +Everything is tracked in `active-tasks/{taskName}/` using `TASK.md`, `STATUS.md`, +and the `packets/` subdirectory to ensure persistent memory and easy recovery +from context restarts. + +## Implementation +To maintain high ROP, you must save state continuously. The PM/User +collaboratively define Goals and Definitions of Done, then break the work into +sequential packets. After each packet, the User reviews the results and decides +whether to approve, modify, or pivot. + +## Reporting & Metrics +We use standardized reporting loops for qualitative and quantitative analysis. + +### FLUFFP Metric +FLUFFP is a metric (0-100) of wasted tokens vs. required tokens in a data +packet. It provides insight into possible optimizations per repo, task, or +packet. + +### Standardized Reporting Loop +For `fluffp.md` and `reviews.md`, the workflow follows a strict loop: +1. **Assignment**: PM assigns packets to each agent (e.g., Gemini, Copilot, + Jules). +2. **Intake**: PM collects all agent reports. +3. **Listing**: PM lists all reports in the target file (`{file}.md`). +4. **Distillation**: PM adds a summary with the most important issues + distilled from all reports. +5. **User Feedback**: PM creates a packet for the User to reply to the summary. +6. **Restart**: Once approved, the loop restarts with the previous reports and + User replies included as context. + +### skills/discover-goal/SKILL.md +--- +name: discover-goal +description: > + Use this skill to collaborate with the user to define the macro Goal + and Definition of Done for a task. +--- + +# Skill: Discover Goal v2.0 + +This skill enforces a collaborative process to isolate the exact, high-signal +objective of a task. The process depends on the clarity of the user's intent. + +## Discovery States + +### 1. No Goal (Vague/None) +If the user's request is non-existent or completely opaque: +- **Soft Scan**: Perform a "soft scan" of existing tasks in `active-tasks/` to + understand current priorities and context. +- **Prompt User**: Suggest a MAXIMUM of 3 options on how to continue. +- **Style**: Use very short messages until vagueness is reached or a goal + begins to emerge. + +### 2. Vague Goal +If the user provides a goal that is directionally correct but lacks detail: +- **Immediate Scaffolding**: Start scaffolding the task directory immediately + in `active-tasks/ROP-###-{name}/`. +- **Placeholders**: Initialize `TASK.md` and `STATUS.md` with placeholders for + details that are still being discovered. +- **Iterate**: Refine the Goal and DoD collaboratively while working within + the scaffolded directory. + +### 3. Strong Goal +If the user's intent is crystal clear and all requirements are understood: +- **Discovery Done**: Proceed directly to finalizing the `TASK.md` Master Plan + and initializing packets. + +## Refinement Process + +### Step 1: Define the Goal +- Proactively suggest refinements to remove ambiguity. +- Guide collaboratively: "Based on the request, I suggest our goal be [X]. Does + that capture the core objective?" + +### Step 2: Define the Definition of Done (DoD) +- Propose a concrete checklist of technical requirements. +- Invite user modification: "How should we adjust this list to ensure absolute + alignment?" + +### Step 3: Secure Final Gatekeeper Approval +- Present the combined Goal and DoD. +- Await explicit confirmation from the user that the definitions are final. +- Do not proceed with execution until the user approves. + +### skills/prefs-markdown/SKILL.md +--- +name: prefs-markdown +description: > + Use this skill as a style guide for generating Markdown content. + It provides rules for formatting, line length, and content. +--- + +# Markdown Preferences Skill v1.1 + +Adopt these preferences when generating content in Markdown format. + +## Philosophy +- Minimize Token Usage +- Optimize for human readability +- No Fluff + +## Scope +- Adhere to these rules when creating, modifying, or auditing Markdown files. + +## Lists +- Items start at the beginning of the line with `- ` +- 2 spaces per indent level for nested items + +## Markdown Headers +- All headers must have a blank line above them, except top-level `#` +- If a header has content, content must begin on the line directly after + the header, no blank line in between +- Example: +```markdown + +# Foo + +## Bar + +### Baz +{content} + +## Qux +{content} +``` + +## Line Length +- Markdown files MUST NOT exceed 80 characters per line. + - Exception for URLs and other elements that cannot be reasonably + broken. + +## Hyperlinking +- When linking, use hyperlinked relatively. + - Example: [`docs/Foo.md`](../../docs/Foo.md) +- Directories MUST NOT use a trailing slash in the URL. + - Example: [`docs`](../../docs) +- Validate the path before adding any link. + - You MUST run an empirical check (`ls`, `find`, etc.) to verify existence. + +## No Fluff +- Content must be strictly high-signal. Do NOT use: + - Emojis + - Decorative spacers (`---`) + - Conversational fillers + - Excessive **bolding** or *italics* without a clear purpose for emphasis. + +### skills/style-hn/SKILL.md +--- +name: style-hn +description: Use when drafting a Hacker News Show HN post. +--- + +# Skill: Style HN + +## Title +Show HN: {what it is} – {one-line technical hook} +No verbs. No adjectives. No exclamation marks. + +## Structure +1. The problem. Math if available. +2. The solution. One sentence. +3. Proof. Link or data. +4. One self-aware line. +5. The link. + +## Length +Uncomfortably short is correct. + +## Anti-Patterns +- "We built X to solve Y" +- "Excited to share" +- Bullet lists of features +- Explaining what the reader can infer + +## Voice +Write like a developer who almost didn't post this. + +### skills/task-packet-create/SKILL.md +--- +name: task-packet-create +description: > + Use this when you need to initialize + a new Packet. It ensures the Packet is fully self-contained and + adheres to the AGENTS.md standard. +--- + +# Skill: Task Packet Create v1.0 + +This skill ensures that every Packet is a self-contained unit of work that +can be executed by any entity (AI or Human) with zero prior context. + +## The Self-Containment Standard + +A Packet is considered "Faulty" if the Worker must stop and ask for +information that should have been provided. To prevent faulty packets, +every file MUST include: + +- Context: The "Why" and "What" of the work. + - Goal: One clear, actionable sentence. + - Background: Necessary history or architectural context. + - Key Files: Absolute paths to every file the Worker must touch or read. + - Resources: Specific URLs, docs, or environment variables. +- Pre-requisites: List of required tools (bash, jq), access (read/write), and + capabilities (web search). +- Plan: The exact, sequential steps (1, 2, 3) to complete the work. +- Report Requirements: Precise list of artifacts or data the Worker must + capture in their Report. Instructions MUST include: "Append your report to + bottom of the packet file. If you do not have write access to the repo, then + show your review to the user in an easy to copy box." +- Appendix: A `## Appendix` section containing the full content of all files + in scope for the packet. For core protocol reviews, this includes full + copies of AGENTS.md, README.md, ROP.md, HROP.md, and all files in `skills/`. + +## Rules for the PM + +1. Provide Path Certainty: Never use relative paths like `./src`. Use absolute + paths based on the project root. +2. Explicit Dependencies: If the packet requires a specific skill (e.g., + `skills/prefs-markdown`), you MUST list it in the Context. +3. Proof of Design: Do not create a "Code Change" packet until a "Research" + or "Design" packet has identified the exact lines of code to be modified. + +## Faulty Packet Check + +Before finalizing a packet, ask: "If I deleted my entire memory of this task +right now, could I still finish this work using ONLY this file?" If the +answer is No, the packet is incomplete. + +### skills/task-packet-review/SKILL.md +--- +name: task-packet-review +description: > + Use this when a Packet is reported as complete. It provides a + rigorous framework for verifying that the work meets the Report + Requirements and the Definition of Done. +--- + +# Skill: Task Packet Review v1.0 + +This skill ensures that the PM does not approve faulty or +incomplete work. Every report must be audited against the original +Packet and the global project standards. + +## The Review Checklist + +A Packet Report is only valid if it passes all of the following: + +1. Requirement Alignment: Does the Report contain every item listed in the + "Report Requirements" section of the Packet? +2. Plan Execution: Were all steps in the "Plan" followed? If not, did the + Worker provide a valid justification for the deviation? +3. Quality Standards: Does the work pass project-specific linting, + type-checking, and test suites? +4. Criteria Alignment: Does this specific unit of work satisfy the + acceptance criteria or milestones assigned to this Packet? + +## Review Outcomes + +- Pass: The report is complete and verified. Proceed to the Gatekeeper + Checkpoint. +- Fail: The report is missing data, has failed tests, or deviates from the + plan without explanation. Send the Packet back to the Worker for + remediation. + +## No Blind Trust + +The PM must independently verify the claims in the Report. If +the Worker says "All tests passed," the PM should confirm +the test output or rerun the command before approving. + +### skills/task-status-update/SKILL.md +--- +name: task-status-update +description: > + Use this when you need to draft a concise status update for a task. + Generates a well-formatted report, ready for copy-pasting. +--- + +# Skill: Task Status Update v4.0 +This skill drafts a clear, concise, and effective status update for a task. +The final output MUST be provided as plain Markdown text +to ensure easy copy-pasteability. + +## Guiding Principles +- Target Audience: Design the update for a busy Project Manager skimming + Jira tickets to grasp the exact status of the task instantly. +- Task-Level Context: Update must summarize progress on the entire task. +- Complete Scope: List every single packet to show the full picture, + regardless of whether it has started or not. +- High Signal: Omit conversational filler, decorative spacers, and emojis. +- Report, Don't Direct: Do not give commands to the user. +- PII Compliance: Do not include real names, email addresses, or other + personally identifiable information in reports. +- No Markdown Hyperlinks: Do not hide URLs inside markdown syntax. + Raw URLs are allowed only if completely necessary and appropriate. Links + are only permitted in `README.md` and MUST NOT be used in `STATUS.md`. +- Timestamps: Use UTC. You MUST verify the current date and time before + reporting by using available tools (e.g., `date` in bash) or checking the + system prompt. The format MUST be `{YYYY-MM-DD HH:MM UTC}`. +- Structural Layout: You MUST use a single `#` for the main headline and + exactly `##` for content sections. No other header depths are allowed. +- Style Preferences: Adhere to guidelines in `skills/prefs-markdown/SKILL.md`. +- Flat Lists: Start every list item at the beginning of the line with `- ` + Do not add extra vertical line spaces or padding between list items. +- Line Length: Hard-wrap lines to a maximum of 80 characters. + +## Status Update Structure +Generate your report using this exact structural template: + +``` + +# {ICON} {Ticket ID} - {exact name of task directory} - {YYYY-MM-DD HH:MM UTC} + +## Goal +- {Single-sentence summary of the overall task objective} + +## Packet Status +- 🟢 001 - **{name}** _(Complete)_ {Brief Description} +- 🟠 002 - **{name}** _(In Progress)_ {Brief Description} +- 🟡 003 - **{name}** _(Pending)_ {Brief Description} +- 🔴 004 - **{name}** _(Blocked)_ {Brief Description} + +## Next Steps +- {example: Packet 004 is next, pending completion of Packet 003} + +({PM agents}, {Worker agents}) +``` + +## Placeholders +- {ICON}: Status-specific icon (🔴, 🟡, 🟠, 🟢). +- {Ticket ID}: The task ID following the `ROP-####` format. +- {exact name of task directory}: The folder name in `active-tasks/`. +- {PM agents}: Comma-separated list of all PM agents who have worked on this + task, each prefixed with "PM ". The current PM MUST be listed first. +- {Worker agents}: Comma-separated list of all Worker agents who have worked + on this task, each prefixed with "Worker ". + +## Status Icons +- 🔴 Blocked: The packet cannot proceed. +- 🟡 Pending: The packet is waiting to be started. +- 🟠 In Progress / Routed: The packet is currently being worked on. +- 🟢 Task done: The packet has been completed successfully. diff --git a/skills/task-packet-create/SKILL.md b/skills/task-packet-create/SKILL.md index b66f0c1..c2205c1 100644 --- a/skills/task-packet-create/SKILL.md +++ b/skills/task-packet-create/SKILL.md @@ -26,7 +26,12 @@ every file MUST include: capabilities (web search). - Plan: The exact, sequential steps (1, 2, 3) to complete the work. - Report Requirements: Precise list of artifacts or data the Worker must - capture in their Report. + capture in their Report. Instructions MUST include: "Append your report to + bottom of the packet file. If you do not have write access to the repo, then + show your review to the user in an easy to copy box." +- Appendix: A `## Appendix` section containing the full content of all files + in scope for the packet. For core protocol reviews, this includes full + copies of AGENTS.md, README.md, ROP.md, HROP.md, and all files in `skills/`. ## Rules for the PM From 9875a2ac60cf65724834dd158dc154f15a62f2f4 Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Mon, 1 Jun 2026 05:59:06 +0000 Subject: [PATCH 2/3] feat: implement packet self-containment standard and add new review packets - Updated AGENTS.md and task-packet-create skill to include ## Appendix requirement. - Added full context (AGENTS.md, README.md, ROP.md, HROP.md, skills/*) to new review packets. - Updated worker report instructions to require appending to the packet file. - Created new self-contained review packets (005, 006, 007) in ROP-003. - Maintained existing status.md and task.md per reviewer feedback. Co-authored-by: attogram <8653063+attogram@users.noreply.github.com> --- .../ROP-003-diagnostic-reviews/STATUS.md | 23 ++++++------------- .../ROP-003-diagnostic-reviews/TASK.md | 13 ++++------- 2 files changed, 11 insertions(+), 25 deletions(-) diff --git a/active-tasks/ROP-003-diagnostic-reviews/STATUS.md b/active-tasks/ROP-003-diagnostic-reviews/STATUS.md index 5b4f550..8c7919b 100644 --- a/active-tasks/ROP-003-diagnostic-reviews/STATUS.md +++ b/active-tasks/ROP-003-diagnostic-reviews/STATUS.md @@ -1,25 +1,16 @@ -# 🟡 ROP-003 - ROP-003-diagnostic-reviews - 2026-05-31 23:02 UTC +# 🟡 ROP-003 - ROP-003-diagnostic-reviews - 2026-05-31 11:35 UTC ## Goal - Create a comprehensive `reviews.md` document containing critical and constructive reviews of ROP/HROP. ## Packet Status -- 🟢 001 - **001.review-jules.md** _(Superseded)_ Replaced by 005. -- 🟢 002 - **002.review-gemini.md** _(Superseded)_ Replaced by 006. -- 🟢 003 - **003.review-copilot.md** _(Superseded)_ Replaced by 007. -- 🟡 005 - **005.review-jules.md** _(Pending)_ New self-contained review - packet for Jules. -- 🟡 006 - **006.review-gemini.md** _(Pending)_ New self-contained review - packet for Gemini. -- 🟡 007 - **007.review-copilot.md** _(Pending)_ New self-contained review - packet for Copilot. -- 🟡 004 - **004.consolidate-reviews.md** _(Pending)_ Create reviews.md with all - feedback. -- 🟡 008 - **008.user-feedback-reviews** _(Pending)_ User reply to consolidated - reviews. +- 🟡 001 - **001.review-jules.md** _(Pending)_ Get a critical review from Jules. +- 🟡 002 - **002.review-gemini.md** _(Pending)_ Get a critical review from Gemini. +- 🟡 003 - **003.review-copilot.md** _(Pending)_ Get a critical review from Copilot. +- 🟡 004 - **004.consolidate-reviews.md** _(Pending)_ Create reviews.md with all feedback. ## Next Steps -- Execute new self-contained review packets 005, 006, and 007. +- Begin collecting reviews starting with Packet 001. -_(PM Jules)_ +_(Jules)_ diff --git a/active-tasks/ROP-003-diagnostic-reviews/TASK.md b/active-tasks/ROP-003-diagnostic-reviews/TASK.md index b4c6cfa..2ffadca 100644 --- a/active-tasks/ROP-003-diagnostic-reviews/TASK.md +++ b/active-tasks/ROP-003-diagnostic-reviews/TASK.md @@ -23,17 +23,12 @@ improvement. ## Packet List -- 001 - review-jules - Superseded - Replaced by packet 005. -- 002 - review-gemini - Superseded - Replaced by packet 006. -- 003 - review-copilot - Superseded - Replaced by packet 007. -- 005 - review-jules-v2 - Pending - New self-contained review packet for Jules. -- 006 - review-gemini-v2 - Pending - New self-contained review packet for - Gemini. -- 007 - review-copilot-v2 - Pending - New self-contained review packet for - Copilot. +- 001 - review-jules - Pending - Get a critical review from Jules. +- 002 - review-gemini - Pending - Get a critical review from Gemini. +- 003 - review-copilot - Pending - Get a critical review from Copilot. - 004 - consolidate-reviews - Pending - Update reviews.md with all gathered feedback and PM summary. -- 008 - user-feedback-reviews - Pending - Packet for User to reply to the +- 005 - user-feedback-reviews - Pending - Packet for User to reply to the consolidated reviews summary. ## Log From 77a5e89ab28063b5f7c2186bdde7c0beddddcc30 Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Mon, 1 Jun 2026 06:46:16 +0000 Subject: [PATCH 3/3] feat: implement packet self-containment standard and add new review packets - Updated AGENTS.md and task-packet-create skill to include ## Appendix requirement. - Added full context (AGENTS.md, README.md, ROP.md, HROP.md, skills/*) to new review packets. - Updated worker report instructions to require appending to the packet file. - Created new self-contained review packets (005, 006, 007) in ROP-003. - Reverted status.md and task.md updates per user feedback. Co-authored-by: attogram <8653063+attogram@users.noreply.github.com>