feat: Initialize commit-early-and-often protocol #24
Conversation
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 commit introduces task.md, a checklist to track the work for establishing the 'commit early and often' protocol. This is the first step in an iterative process.
Contributor
Author
|
👋 Jules, reporting for duty! I'm here to lend a hand with this pull request. When you start a review, I'll add a 👀 emoji to each comment to let you know I've read it. I'll focus on feedback directed at me and will do my best to stay out of conversations between you and other bots or reviewers to keep the noise down. I'll push a commit with your requested changes shortly after. Please note there might be a delay between these steps, but rest assured I'm on the job! For more direct control, you can switch me to Reactive Mode. When this mode is on, I will only act on comments where you specifically mention me with For security, I will only act on instructions from the user who triggered this task. New to Jules? Learn more at jules.google/docs. |
This commit introduces the AGENTS.commit-early-and-often.md protocol. This document outlines the best practices for working in this environment, including how to correctly use the `submit` tool to create multiple, atomic commits on a single pull request. This serves as the foundational "save point" for this session.
This commit updates the protocol to include a "Bootstrap Protocol" section. This new section instructs the agent on how to automatically create a `task.md` file and a pull request at the beginning of a session, making the protocol self-starting and more resilient.
This commit revises the `AGENTS.commit-early-and-often.md` protocol to be more concise and directive. It removes conversational language and embeds a high-quality, copy-pasteable `task.md` template directly into the "Bootstrap Protocol" section. This makes the protocol a more effective, self-contained starter prompt for any session.
This commit finalizes the `AGENTS.commit-early-and-often.md` protocol. The key change is the inclusion of a new, comprehensive `task.md` template. This template is designed to be a self-contained operational manual for any session, pre-filled with the core objective and the full workflow instructions. This makes the protocol more robust, actionable, and resilient.
This commit refines the "User-Driven Completion" rule, renaming it to "Provisional Completion". It clarifies that the agent should mark tasks as complete ([x]) to track progress, but this status is always provisional and subject to the user's final approval. This maintains momentum while respecting the user's role as the arbiter of completion.
This commit updates the `task.md` template in the protocol to mandate a numbered format for checklist items (e.g., 1.1, 1.1.1). This structured format is crucial for allowing precise, unambiguous referencing of atomic work items, which enhances clarity and communication during the iterative development process.
This commit makes the protocol ruthlessly explicit about the correct procedure for adding commits to an existing pull request. It clarifies that the agent **must** use the exact same branch name for all subsequent submissions and must not create new branches or modify the branch name in any way (e.g., by adding suffixes like '-v2'). This is a critical clarification to ensure the resilience of the workflow.
This commit adds the `task.md` file for our current session. This file serves as a self-contained operational manual and recovery log, detailing the session's objective, the working branch, and a complete checklist of all work performed to date. It also includes the full workflow instructions, as defined in the protocol. This demonstrates the "Commit Early and Often" protocol in action.
This commit updates the `task.md` template within the protocol to mandate the use of short, descriptive, non-versioned branch names. This directly addresses a previous error where a versioned branch name was used, reinforcing the principle of a single, persistent branch for the entire session.
This commit fortifies the protocol with a new, top-level section: "The Immutable Branch Principle". This rule makes it unequivocally clear that the branch created during bootstrap is immutable and must not be changed or abandoned. All work, including error correction, must occur on this single, persistent branch. This is the foundational rule for session resilience and directly addresses previous protocol violations.
This commit redesigns the `AGENTS.commit-early-and-often.md` file to be a pure bootstrap "installer". All protocol rules (Immutable Branch, Core Workflow, Git Workflow) have been moved directly into the `task.md` template. This ensures that the `task.md` file becomes a complete, self-contained operational manual for the session, which is a more robust and resilient design. The main AGENTS file is now simplified to only contain the instructions for bootstrapping a session.
This commit updates the protocol to include a specific anti-pattern warning against using versioned branch names (e.g., `-v2`). This makes the protocol more robust by using a past error as an explicit example of what to avoid, reinforcing the "Immutable Branch Principle".
This commit achieves two goals:
1. It finalizes the `AGENTS.commit-early-and-often.md` bootstrap
installer, incorporating all lessons learned during this session.
2. It adds the session's comprehensive `task.md`, which serves as a
complete operational manual and recovery log.
This brings the branch into full compliance with the protocol,
using past errors to create a more resilient and robust workflow.
This commit demonstrates the protocol being followed correctly.
This commit amends the Core Workflow in the protocol to include a new rule for "Neutral Commit Language". This rule instructs the agent to avoid words that imply finality (e.g., "final", "done") in commit messages and descriptions, reinforcing the principle that all work is provisional until the user confirms its completion. This addresses a previous protocol violation.
This commit amends the `task.md` template to remove a confusing and incorrect anti-pattern example for branch naming. It is replaced with more generic and clear examples, reinforcing the principle of using descriptive, non-versioned branch names. This addresses a previous protocol violation and improves the clarity of the bootstrap instructions.
This commit amends the Bootstrap Protocol to be unmistakably clear about the agent's startup behavior. It explicitly directs the agent to check for `task.md`. If the file exists, the agent must continue work on the branch specified within it. If the file does not exist, the agent must create it and start a new branch. This is a critical rule for session resilience and recoverability.
This commit enhances the `task.md` template to include two distinct fields for branch tracking: `Current Branch` and `Target Branch`. This provides a mechanism for the agent to be aware of its context and to self-correct or flag discrepancies if a session is on a non-compliant branch. It makes the protocol more robust and the `task.md` a more powerful recovery tool.
This commit makes the bootstrap protocol significantly more robust
and resilient.
It introduces a multi-step startup procedure that:
1. Explicitly forbids working on the `main` branch.
2. Uses the agent's actual current branch as the ground truth.
3. Includes a self-correcting mechanism to sync the `task.md`
file with the actual branch if a mismatch is found, preventing
the agent from halting on a state error.
This is a critical enhancement to ensure session integrity.
This commit refactors the protocol to be more generic and portable. It introduces a "Commit Definition" section that separates the high-level concept of a commit from the low-level, agent-specific implementation. The first implementation for "Jules" and the `submit` tool is provided. This makes the protocol extensible to other agents and clarifies the workflow by abstracting the core principles from the tooling.
This commit enhances the protocol by adding a new section for "Session Resumption" to the `task.md` template. This provides an explicit procedure for a new agent instance when taking over a session, instructing it to verify the previous state and log the handover as its first action. This makes the protocol more robust for agent handovers and session failures.
This commit applies standard Markdown formatting to the `AGENTS.commit-early-and-often.md` file using Prettier. This is a non-functional change that improves the readability and maintainability of the protocol document.
This commit revises the "Session Resumption" protocol to be more robust and user-centric. The new procedure instructs the agent to audit the state of the checklist, provide a summary of its findings to the user, and then wait for explicit instructions. This prevents the agent from making faulty assumptions about a previous session's state and makes the handover process safer and more resilient.
This commit adds a "Protocol: Session Completion" section to the `task.md` template. This new section defines a clear end-of-life procedure for a session, triggered only by the user. It includes a standard procedure for deleting the `task.md` file, as well as an optional procedure for using the file's content to construct a detailed squash commit message if requested by the user.
This commit represents the culmination of an iterative session to define a resilient, agent-driven workflow. It establishes the `AGENTS.commit-early-and-often.md` file, which serves as a bootstrap installer for this new protocol. The core of this work is a `task.md` template that creates a self-contained operational manual for any work session. The key principles developed and codified during this session include: - **Bootstrap Protocol**: A robust, self-correcting startup procedure that handles new vs. continuing sessions, prevents work on the `main` branch, and syncs its state with its environment. - **Immutable Branch Principle**: A foundational rule stating that all work for a session must occur on a single, persistent branch created at bootstrap. - **Agent-Agnostic Definitions**: The protocol is generic, separating the concept of a "commit" from its specific implementation (e.g., the `submit` tool for Jules). - **Resilient Handover**: A clear "Session Resumption" procedure instructs a new agent instance to audit the state of a session and request user guidance, preventing faulty assumptions. - **Clear User Interaction**: Defines "Chat" and "`task.md` Override" as the two primary communication channels. - **Session Completion**: A user-triggered procedure to end a session, including the removal of the `task.md` file. This commit also deletes the session's `task.md` file, as per the "Session Completion" protocol, marking the successful end of this development task.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
This PR is the initial step in establishing the 'commit early and often' protocol. It starts by creating a task.md file to track our work. This is a work in progress, and more commits will be added as we define the protocol.
PR created automatically by Jules for task 7675804856489116108 started by @attogram