Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 52 additions & 0 deletions packages/camera/camera_android_camerax/.agents/playbook.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
# Playbook: One-Shot Agentic Development Workflow

This playbook outlines the recommended workflow for humans to orchestrate agent-driven feature development. It is structured into two main phases: **Planning & Consensus** and **Phased Execution & Validation**.

```mermaid
graph TD
A[Start: Define Feature/Issue] --> B[Phase 1: Generate Execution Plan]

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe not now but eventually we could add a section on the "define feature/issue" piece where we describe what kind of issues (in my mind, clearly scoped issues at least for now) would work best for this oneshot approach.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yeah, I agree but we will need to learn that from experience.

B --> C[Commit Plan & Open PR]
C --> D[Peer Code Review & Comments]
D -->|Comments Added| E[Agent Updates Plan in PR]
E --> D
D -->|Approved| F[Phase 2: Environment Setup & Verification]
F --> G[Run One-Shot Execution Flow]
G --> H[Complete: Ready for final PR approval]
```

---

## Phase 1: Planning & Consensus

The planning phase ensures the agent and human stakeholders align on the technical design and scope before any implementation begins.

### 1. Generating the Plan
* **Action:** Prompt the agent to analyze the requirements and write a detailed execution plan (`plan.md` or similar design artifact).
* **Tooling:** You can recommend the `/plan` or `/grill-me` slash commands to help generate and refine the plan iteratively.
Comment thread
reidbaker marked this conversation as resolved.

### 2. PR-Based Consensus Loop
To gather consensus across multiple technical voices/reviewers:
1. **Commit and Push:** Commit the plan artifact to a git branch and open a Pull Request (PR).
2. **Review:** Human reviewers add comments directly on the plan in the PR.
3. **Iterative Updates:** The agent is responsible for reading the PR comments and updating the plan until all comments are addressed and the plan is approved.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So this will take the place of the human leaving comments on the plan directly in the IDE?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This will hopefully take the place of having the human have to manually prompt the agent with either the comments or "go fetch the comments and address them".

Practically will win out here for whatever allows us to make progress. That said having a record of the types of feedback and how the agent responds might help us with evals later.


> [!NOTE]
> Utilizing PRs for plan review is the most effective mechanism for achieving consensus on design decisions before modifying production code.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also it's great to track the changes over the iterations!


---

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also a potential do-later (and maybe this is better fit for a skill): we can add some notes on what folks might want to look out for when reviewing the plan. Some examples:

  • If you want integration testing, make sure it lists out how it will find + launch an emulator
  • In the spirit of test-driven development, make sure it proposes unit tests that break initially but will not break after the fix before it starts development
  • Make sure it will run the pre-push skill before creating a PR


## Phase 2: Execution & Validation

Once the plan is approved, the workflow transitions to the execution phase.

### 1. Environment Verification
Before execution begins, the agent must validate that the environment is fully set up and in a clean, working state.
* **Pre-Flight Checks:** Run the repository diagnostics or readiness checks (such as the `check-readiness` skill) to verify toolchain versions, environment variables, and SDK configurations.
Comment thread
reidbaker marked this conversation as resolved.
* **Clean State Check:** Run static analysis and basic tests on the unmodified branch to confirm that any existing failures are identified beforehand.

### 2. One-Shot Execution Flow
In this phase, the agent executes the approved plan using a specialized one-shot execution skill or subagent context.

At a high level, this execution flow focuses on:
1. **Targeted Code Modification:** Editing the codebase strictly within the bounds of the approved plan.
2. **Verification & Testing:** Running automated validation (linters, formatters, and unit/integration tests) to ensure the change functions correctly and does not introduce regressions.
Loading