Initial workflow template
- docs/workflow/: INDEX, ISSUE-FORMAT, WORKFLOW, AGENT-PROMPTS - .issues/: INDEX, example issue - .hooks/: issue-linter.js (pre-commit validator) - package.json with setup script - README.md See docs/workflow/INDEX.md to get started.
This commit is contained in:
shokollm
255
docs/workflow/AGENT-PROMPTS.md
Normal file
255
docs/workflow/AGENT-PROMPTS.md
Normal file
@@ -0,0 +1,255 @@
|
||||
# Agent Prompts
|
||||
|
||||
Copy-paste ready prompts for each stage of the workflow.
|
||||
|
||||
---
|
||||
|
||||
## Stage 2: Pick Up — Agent Prompt
|
||||
|
||||
Copy and paste this when starting work on an issue:
|
||||
|
||||
```
|
||||
You're picking up issue #<number>: <title>
|
||||
|
||||
Steps:
|
||||
1. Read /.issues/<number>-<title>.md completely
|
||||
2. Read all depends-on issues:
|
||||
<list issue numbers here>
|
||||
3. Read related code:
|
||||
<list files here>
|
||||
4. Write your Plan in ## Agent Working Notes > Plan:
|
||||
- Approach: how will you solve this?
|
||||
- Files to touch: which files will you change?
|
||||
- Risks: what could go wrong?
|
||||
5. Change status to `in-progress`
|
||||
6. Wait for human acknowledgment before proceeding
|
||||
|
||||
Remember: You must understand the dependencies before starting. Don't assume they work a certain way.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Stage 3: Implementation — Status Log Prompt
|
||||
|
||||
After each significant step, log it:
|
||||
|
||||
```
|
||||
Add to ## Status Log:
|
||||
|
||||
YYYY-MM-DD HH:MM - <What you did>
|
||||
<Why you did it this way>
|
||||
<Any decisions made>
|
||||
```
|
||||
|
||||
Example:
|
||||
```
|
||||
2024-04-18 14:30 - Implemented delete button component
|
||||
Decided to put it in SettingsPage.tsx rather than separate component
|
||||
since it's only used in one place. Button uses danger variant for emphasis.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Stage 3: Implementation — Scope Change Prompt
|
||||
|
||||
If scope needs to change:
|
||||
|
||||
```
|
||||
Stop implementation immediately.
|
||||
|
||||
Add to ## Status Log:
|
||||
---
|
||||
Scope change detected: <description>
|
||||
|
||||
Original scope: <what was scoped>
|
||||
New requirement: <what was found>
|
||||
|
||||
Proposed solution:
|
||||
<your proposed approach>
|
||||
|
||||
Status: Waiting for human approval before proceeding.
|
||||
---
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Stage 3: Implementation — Blocker Prompt
|
||||
|
||||
If blocked:
|
||||
|
||||
```
|
||||
Add to ## Blockers:
|
||||
|
||||
Blocker: <description>
|
||||
Proposed solution: <your proposed approach>
|
||||
Status: Waiting for resolution.
|
||||
|
||||
Do not proceed until this is resolved.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Stage 4: Self-Verification Prompt
|
||||
|
||||
Copy and paste this template, then fill in each item:
|
||||
|
||||
```
|
||||
## Self-Verification
|
||||
|
||||
Complete before claiming done:
|
||||
|
||||
- [ ] Smoke test ran:
|
||||
Command: <command>
|
||||
Result: <pass/fail>
|
||||
If fail: <what failed, what you did about it>
|
||||
|
||||
- [ ] Acceptance criteria checked:
|
||||
<List each criterion and result>
|
||||
- [ ] Criterion 1: <pass/fail> — <notes>
|
||||
- [ ] Criterion 2: <pass/fail> — <notes>
|
||||
|
||||
- [ ] Screenshot taken (if UI change):
|
||||
<path to screenshot> or N/A
|
||||
|
||||
- [ ] Dependent issues still work:
|
||||
- Issue #<number>: <what you tested> — <pass/fail>
|
||||
- Issue #<number>: <what you tested> — <pass/fail>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Stage 5: Request Review Prompt
|
||||
|
||||
After completing self-verification:
|
||||
|
||||
```
|
||||
## Agent Working Notes
|
||||
|
||||
[after Self-Verification is complete]
|
||||
|
||||
Add to ### Human Review Notes:
|
||||
|
||||
Agent requests review.
|
||||
|
||||
All self-verification checks passed. Ready for approval to close.
|
||||
|
||||
Files changed: <list>
|
||||
Tests added: <list if any>
|
||||
Screenshots: <path if applicable>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Full Issue Implementation Prompt
|
||||
|
||||
For the agent to use from start to finish:
|
||||
|
||||
```
|
||||
## Your Task
|
||||
|
||||
Implement issue #<number>: <title>
|
||||
|
||||
## Instructions
|
||||
|
||||
1. **Read the issue file**: `/.issues/<number>-<title>.md`
|
||||
2. **Read dependencies**: Issues listed in `depends-on`
|
||||
3. **Read related code**: Files that will be affected
|
||||
4. **Write your Plan** in the issue file's `## Agent Working Notes > Plan`
|
||||
5. **Wait for acknowledgment** ("ok" from human)
|
||||
6. **Implement** the feature or fix
|
||||
7. **Log decisions** in `## Status Log` as you go
|
||||
8. **If scope changes or blocked**: Stop, document, wait
|
||||
9. **Self-verify** using the template in Stage 4
|
||||
10. **Request review** when done
|
||||
|
||||
## Key Rules
|
||||
|
||||
- Think out loud in the issue file
|
||||
- Verify before claiming done
|
||||
- Ask if unsure — don't assume
|
||||
- Dependencies must be verified, not assumed
|
||||
- Pre-commit hook will check your issue file — keep it complete
|
||||
|
||||
## Do NOT
|
||||
|
||||
- Skip the issue file format
|
||||
- Skip self-verification
|
||||
- Proceed without human acknowledgment on plans
|
||||
- Ignore scope changes
|
||||
- Assume dependencies work without checking
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Dependency Verification Prompt
|
||||
|
||||
When checking if a dependency works:
|
||||
|
||||
```
|
||||
## Dependency Check: Issue #<number>
|
||||
|
||||
Issue: <title>
|
||||
Status: <status>
|
||||
Output: <what this issue produces>
|
||||
|
||||
Verification performed:
|
||||
- Ran tests: <command> — <pass/fail>
|
||||
- Checked integration: <what you tested>
|
||||
- Screenshots (if UI): <path or N/A>
|
||||
|
||||
Result: <dependency works / dependency has issues>
|
||||
|
||||
If dependency has issues:
|
||||
- Document what doesn't work
|
||||
- Write proposed fix in ## Blockers
|
||||
- Do not proceed until resolved
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Issue Creation Prompt
|
||||
|
||||
For creating a new issue:
|
||||
|
||||
```
|
||||
## Create New Issue
|
||||
|
||||
Create a new issue file in /.issues/
|
||||
|
||||
1. Check /.issues/INDEX.md for the next available number
|
||||
2. Create /.issues/<number>-<slug>.md using the format in /docs/workflow/ISSUE-FORMAT.md
|
||||
3. Fill in:
|
||||
- All frontmatter
|
||||
- ## What — what needs to be built or fixed
|
||||
- ## Why — why it matters
|
||||
- ## Acceptance Criteria — testable checklist
|
||||
- ## Verification — how to test it
|
||||
- Leave ## Agent Working Notes empty
|
||||
4. Add to /.issues/INDEX.md
|
||||
5. Set status to `open`
|
||||
|
||||
Issue number: <next number>
|
||||
Issue slug: <descriptive-kebab-case>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Pre-commit Hook Failure Response
|
||||
|
||||
If the pre-commit hook fails:
|
||||
|
||||
```
|
||||
The pre-commit hook rejected your commit due to issue file errors.
|
||||
|
||||
Error: <error message from hook>
|
||||
|
||||
Fix the issue file(s) before committing:
|
||||
- Missing frontmatter fields
|
||||
- Missing required sections
|
||||
- Invalid status values
|
||||
- Missing Plan when status is in-progress
|
||||
- Missing completed date when status is done
|
||||
- Agent Working Notes not deleted when status is done
|
||||
|
||||
After fixing, try committing again.
|
||||
```
|
||||
96
docs/workflow/INDEX.md
Normal file
96
docs/workflow/INDEX.md
Normal file
@@ -0,0 +1,96 @@
|
||||
# Workflow Template
|
||||
|
||||
A portable, file-based issue tracking and development workflow for teams.
|
||||
|
||||
## Quick Start
|
||||
|
||||
1. **Clone or fork this repo** into your new project
|
||||
2. **Run setup** (if applicable to your project)
|
||||
3. **Read this entire doc** before starting work
|
||||
4. **Read `/docs/workflow/ISSUE-FORMAT.md`** before creating your first issue
|
||||
5. **Follow `/docs/workflow/WORKFLOW.md`** for the step-by-step process
|
||||
|
||||
## What This Is
|
||||
|
||||
A workflow where:
|
||||
- **Issues are files** in `/.issues/`, not in external trackers
|
||||
- **Issues are tracked by git**, alongside the code they affect
|
||||
- **Agents think out loud** in issue files, making reasoning visible
|
||||
- **Humans approve reasoning**, not code line-by-line
|
||||
- **Pre-commit hooks enforce** issue format before any commit
|
||||
|
||||
## File Structure
|
||||
|
||||
```
|
||||
/
|
||||
├── docs/workflow/
|
||||
│ ├── INDEX.md ← You are here
|
||||
│ ├── ISSUE-FORMAT.md ← Required fields for issue files
|
||||
│ ├── WORKFLOW.md ← Step-by-step stages and gates
|
||||
│ └── AGENT-PROMPTS.md ← Copy-paste prompts for agents
|
||||
├── .issues/
|
||||
│ ├── INDEX.md ← List of all open issues
|
||||
│ └── example/
|
||||
│ └── 001-example.md
|
||||
├── .hooks/
|
||||
│ └── issue-linter.js ← Pre-commit validator
|
||||
└── package.json ← (optional) setup scripts
|
||||
```
|
||||
|
||||
## Key Principles
|
||||
|
||||
1. **If it's not written down, it doesn't exist.**
|
||||
All context, decisions, and feedback live in the issue file.
|
||||
|
||||
2. **The agent thinks out loud.**
|
||||
Every significant step—plan, decisions, blockers, verification—is written in the issue.
|
||||
|
||||
3. **Verification before handoff.**
|
||||
The agent must prove the work works before declaring it done.
|
||||
|
||||
4. **Humans approve reasoning, not tasks.**
|
||||
Your job is to agree or disagree with the agent's logic, not to catch missing code.
|
||||
|
||||
5. **Integration is a first-class concern.**
|
||||
Issues have dependencies. Dependencies must be checked before claiming done.
|
||||
|
||||
## Before Starting a New Project
|
||||
|
||||
Tell your agent to set up the workflow:
|
||||
|
||||
> "feynman, set up the workflow using the template from https://git.fbrns.co/shoko/workflow"
|
||||
|
||||
The agent will copy the structure and install the pre-commit hook automatically.
|
||||
|
||||
## For New Team Members
|
||||
|
||||
```bash
|
||||
# Clone the project
|
||||
git clone <repo-url>
|
||||
pnpm install # or npm install, yarn, etc.
|
||||
|
||||
# Read the docs
|
||||
cat docs/workflow/INDEX.md
|
||||
cat docs/workflow/ISSUE-FORMAT.md
|
||||
cat docs/workflow/WORKFLOW.md
|
||||
|
||||
# Check what's being worked on
|
||||
cat .issues/INDEX.md
|
||||
|
||||
# Pick an issue, read it, start working
|
||||
```
|
||||
|
||||
## Pre-commit Hook
|
||||
|
||||
The hook at `.hooks/issue-linter.js` runs automatically before every commit. It will reject commits that:
|
||||
- Change code without a corresponding issue file
|
||||
- Have incomplete issue files (missing required fields)
|
||||
- Have invalid status values
|
||||
- Have `done` status without completion date
|
||||
|
||||
## Getting Help
|
||||
|
||||
- **Workflow questions** → Read `/docs/workflow/WORKFLOW.md`
|
||||
- **Issue format questions** → Read `/docs/workflow/ISSUE-FORMAT.md`
|
||||
- **Agent instructions** → Copy prompts from `/docs/workflow/AGENT-PROMPTS.md`
|
||||
- **What's open** → Check `/.issues/INDEX.md`
|
||||
215
docs/workflow/ISSUE-FORMAT.md
Normal file
215
docs/workflow/ISSUE-FORMAT.md
Normal file
@@ -0,0 +1,215 @@
|
||||
# Issue Format
|
||||
|
||||
Every issue is a single Markdown file in `/.issues/`. No exceptions.
|
||||
|
||||
## File Naming
|
||||
|
||||
```
|
||||
<number>-<slug>.md
|
||||
```
|
||||
|
||||
- `<number>`: Sequential, zero-padded to 3 digits (001, 002, 010, 100)
|
||||
- `<slug>`: Short, kebab-case, descriptive (e.g., `user-authentication`, `fix-nav-crash`)
|
||||
|
||||
Examples:
|
||||
- `001-user-authentication.md`
|
||||
- `042-fix-login-modal.md`
|
||||
- `100-setup-ci-cd.md`
|
||||
|
||||
## Required Frontmatter
|
||||
|
||||
```yaml
|
||||
---
|
||||
id: 001
|
||||
title: Add user authentication
|
||||
status: open # open | in-progress | done | blocked
|
||||
priority: high # low | medium | high | critical
|
||||
depends-on: # optional, list issue IDs
|
||||
- 000
|
||||
created: 2024-04-18
|
||||
completed: # fill when status becomes done
|
||||
---
|
||||
```
|
||||
|
||||
## Required Sections
|
||||
|
||||
### 1. What
|
||||
One paragraph explaining *what* needs to be built or fixed. Be specific.
|
||||
|
||||
### 2. Why
|
||||
One paragraph explaining *why* this matters. Link to customer feedback, bug reports, or business context if available.
|
||||
|
||||
### 3. Acceptance Criteria
|
||||
A checklist. Each item should be:
|
||||
- Testable (can say "pass" or "fail")
|
||||
- Specific (not vague like "works well")
|
||||
- Independent (not dependent on other criteria)
|
||||
|
||||
Example:
|
||||
```markdown
|
||||
## Acceptance Criteria
|
||||
- [ ] Button visible only to authenticated users
|
||||
- [ ] Clicking opens a confirmation modal
|
||||
- [ ] Confirming deletes account and redirects to homepage
|
||||
- [ ] No console errors on the settings page
|
||||
```
|
||||
|
||||
### 4. Verification
|
||||
How to test this issue. Include:
|
||||
- What commands to run
|
||||
- What to look for
|
||||
- What routes to check
|
||||
- Any manual steps required
|
||||
|
||||
Example:
|
||||
```markdown
|
||||
## Verification
|
||||
1. Run `pnpm test -- --grep "settings"`
|
||||
2. Start dev server: `pnpm dev`
|
||||
3. Navigate to `/settings`
|
||||
4. Log in and verify button appears
|
||||
5. Click button, verify modal opens
|
||||
6. Confirm deletion, verify redirect to homepage
|
||||
```
|
||||
|
||||
## Agent Working Notes (Required for All Issues)
|
||||
|
||||
This section is **for the agent to fill in**. It is deleted before closing.
|
||||
|
||||
```markdown
|
||||
---
|
||||
|
||||
## Agent Working Notes
|
||||
|
||||
### Plan
|
||||
<!-- What approach will you take? List steps before coding. -->
|
||||
- [ ]
|
||||
|
||||
### Status Log
|
||||
<!-- Timestamped entries: what was done, what was decided, what was found -->
|
||||
<!-- Format: YYYY-MM-DD HH:MM - Entry -->
|
||||
|
||||
### Blockers
|
||||
<!-- List any blockers with proposed solutions. If none, write "None." -->
|
||||
|
||||
### Self-Verification
|
||||
<!-- Must be filled before claiming done -->
|
||||
- [ ] Smoke test ran: <!-- command and result -->
|
||||
- [ ] Acceptance criteria checked: <!-- which ones, results -->
|
||||
- [ ] Screenshot taken (if UI change): <!-- path or "N/A" -->
|
||||
- [ ] Dependent issues still work: <!-- which ones, results -->
|
||||
```
|
||||
|
||||
### Self-Verification Fields
|
||||
|
||||
| Field | When to Fill | What to Write |
|
||||
|---|---|---|
|
||||
| Smoke test | Always | Command run and whether it passed |
|
||||
| Acceptance criteria | Always | Which criteria were checked, results |
|
||||
| Screenshot | UI changes only | Path to screenshot or "N/A" |
|
||||
| Dependent issues | Has depends-on | Which issues were tested, results |
|
||||
|
||||
## Human Review Notes
|
||||
|
||||
Filled by the human reviewer.
|
||||
|
||||
```markdown
|
||||
### Human Review Notes
|
||||
<!-- Human fills after agent marks done -->
|
||||
|
||||
Review date: YYYY-MM-DD
|
||||
|
||||
Reasoning check:
|
||||
- [ ] Plan makes sense
|
||||
- [ ] Status log shows good decisions
|
||||
- [ ] Self-verification is complete and honest
|
||||
|
||||
Feedback: <!-- any changes requested, or "Approved" -->
|
||||
```
|
||||
|
||||
## Example Issue
|
||||
|
||||
```markdown
|
||||
---
|
||||
id: 023
|
||||
title: Add delete account button to settings
|
||||
status: open
|
||||
priority: high
|
||||
depends-on:
|
||||
- 018
|
||||
created: 2024-04-18
|
||||
---
|
||||
|
||||
## What
|
||||
Add a "Delete Account" button to the user settings page. The button should only be visible to authenticated users and require confirmation before deletion.
|
||||
|
||||
## Why
|
||||
Users need a way to permanently delete their account. Currently there's no path to account deletion, leading to support requests.
|
||||
|
||||
## Acceptance Criteria
|
||||
- [ ] Button visible only to authenticated users
|
||||
- [ ] Clicking opens a confirmation modal
|
||||
- [ ] Confirming deletes account and redirects to homepage
|
||||
- [ ] No console errors on the settings page
|
||||
|
||||
## Verification
|
||||
1. Run `pnpm test -- --grep "settings"`
|
||||
2. Start dev server: `pnpm dev`
|
||||
3. Navigate to `/settings`
|
||||
4. Verify button appears after login
|
||||
5. Click button, verify modal opens
|
||||
6. Confirm deletion, verify redirect to homepage
|
||||
|
||||
---
|
||||
|
||||
## Agent Working Notes
|
||||
|
||||
### Plan
|
||||
- [ ]
|
||||
|
||||
### Status Log
|
||||
|
||||
### Blockers
|
||||
None.
|
||||
|
||||
### Self-Verification
|
||||
- [ ] Smoke test ran:
|
||||
- [ ] Acceptance criteria checked:
|
||||
- [ ] Screenshot taken (if UI change):
|
||||
- [ ] Dependent issues still work:
|
||||
|
||||
### Human Review Notes
|
||||
|
||||
Review date:
|
||||
|
||||
Reasoning check:
|
||||
- [ ] Plan makes sense
|
||||
- [ ] Status log shows good decisions
|
||||
- [ ] Self-verification is complete and honest
|
||||
|
||||
Feedback:
|
||||
```
|
||||
|
||||
## Validation Rules
|
||||
|
||||
The pre-commit hook checks:
|
||||
|
||||
| Rule | Error Message |
|
||||
|---|---|
|
||||
| Code changed without issue file | `Code changed but no issue file found for: <files>` |
|
||||
| Missing frontmatter | `Missing frontmatter in: <file>` |
|
||||
| Missing required sections | `Missing section in <file>: <section>` |
|
||||
| Invalid status | `Invalid status in <file>: <value>` |
|
||||
| Status "done" without completed date | `<file> has status "done" but no completed date` |
|
||||
| Status "in-progress" without Plan | `<file> has status "in-progress" but no Plan` |
|
||||
| Agent Working Notes not deleted on close | `<file> has status "done" but Agent Working Notes not deleted` |
|
||||
|
||||
## Creating a New Issue
|
||||
|
||||
1. Pick the next number: check `/.issues/INDEX.md` for the highest
|
||||
2. Create the file with this exact template
|
||||
3. Add to `/.issues/INDEX.md`
|
||||
4. Move status to `in-progress` when starting work
|
||||
5. Delete Agent Working Notes when closing
|
||||
|
||||
Do not create issues outside of `/.issues/`. Do not use external issue trackers.
|
||||
345
docs/workflow/WORKFLOW.md
Normal file
345
docs/workflow/WORKFLOW.md
Normal file
@@ -0,0 +1,345 @@
|
||||
# Workflow
|
||||
|
||||
The complete step-by-step process for working through an issue, from creation to close.
|
||||
|
||||
## Overview
|
||||
|
||||
```
|
||||
┌────────────────────────────────────────────────────────────────────┐
|
||||
│ 1. ISSUE CREATION Human or agent creates issue file │
|
||||
│ All required fields filled │
|
||||
│ Dependencies identified │
|
||||
└────────────────────────────────┬───────────────────────────────────┘
|
||||
↓
|
||||
┌────────────────────────────────────────────────────────────────────┐
|
||||
│ 2. PICK UP Agent reads issue + dependencies │
|
||||
│ Agent writes Plan │
|
||||
│ Human acknowledges or revises │
|
||||
└────────────────────────────────┬───────────────────────────────────┘
|
||||
↓
|
||||
┌────────────────────────────────────────────────────────────────────┐
|
||||
│ 3. IMPLEMENTATION Agent works and logs decisions │
|
||||
│ New information → pause + ask │
|
||||
│ Blocker → write + wait │
|
||||
└────────────────────────────────┬───────────────────────────────────┘
|
||||
↓
|
||||
┌────────────────────────────────────────────────────────────────────┐
|
||||
│ 4. SELF-VERIFICATION Agent runs smoke test │
|
||||
│ Agent checks acceptance criteria │
|
||||
│ Agent takes screenshot if UI │
|
||||
│ Agent verifies dependencies │
|
||||
└────────────────────────────────┬───────────────────────────────────┘
|
||||
↓
|
||||
┌────────────────────────────────────────────────────────────────────┐
|
||||
│ 5. READY FOR REVIEW Agent marks done in Status Log │
|
||||
│ Agent requests review in file │
|
||||
│ Human reviews reasoning │
|
||||
│ Human approves or requests changes │
|
||||
└────────────────────────────────┬───────────────────────────────────┘
|
||||
↓
|
||||
┌────────────────────────────────────────────────────────────────────┐
|
||||
│ 6. CLOSE Human approves → status: done │
|
||||
│ Agent Working Notes deleted │
|
||||
│ PR created with issue number │
|
||||
└────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Stage 1: Issue Creation
|
||||
|
||||
### Who: Human (or agent with human approval)
|
||||
|
||||
### Steps
|
||||
|
||||
1. Check `/.issues/INDEX.md` for the current highest issue number
|
||||
2. Create `/.issues/<number>-<slug>.md` using the format in `ISSUE-FORMAT.md`
|
||||
3. Fill in:
|
||||
- All frontmatter (id, title, status, priority, depends-on, created)
|
||||
- `## What` — what needs to be built or fixed
|
||||
- `## Why` — why it matters
|
||||
- `## Acceptance Criteria` — testable checklist
|
||||
- `## Verification` — how to test it
|
||||
- Leave `## Agent Working Notes` empty (for the agent to fill)
|
||||
4. Add the issue to `/.issues/INDEX.md`
|
||||
5. Mark status as `open`
|
||||
|
||||
### Exit Gate
|
||||
|
||||
Issue file exists with all required fields. Human has reviewed and approved the issue.
|
||||
|
||||
---
|
||||
|
||||
## Stage 2: Pick Up
|
||||
|
||||
### Who: Agent
|
||||
|
||||
### Steps
|
||||
|
||||
1. Read this issue file completely
|
||||
2. Read all issues listed in `depends-on`
|
||||
3. Read any related code that will be affected
|
||||
4. Write your Plan in `## Agent Working Notes > Plan`
|
||||
- Approach: how will you solve this?
|
||||
- Files to touch: which files will you change?
|
||||
- Risks: what could go wrong?
|
||||
5. Change status to `in-progress`
|
||||
6. Commit this initial work (optional, but recommended)
|
||||
7. Wait for human acknowledgment
|
||||
|
||||
### Human's Role
|
||||
|
||||
Read the Plan. Ask yourself:
|
||||
- Does the approach make sense?
|
||||
- Are the files to touch correct?
|
||||
- Did the agent read the dependencies?
|
||||
|
||||
React with:
|
||||
- **"ok"** — proceed with implementation
|
||||
- **"revise" + feedback** — explain what needs to change and why
|
||||
|
||||
### Exit Gate
|
||||
|
||||
Agent has written a Plan. Human has said "ok" (or equivalent).
|
||||
|
||||
---
|
||||
|
||||
## Stage 3: Implementation
|
||||
|
||||
### Who: Agent
|
||||
|
||||
### Steps
|
||||
|
||||
1. Work through the Plan
|
||||
2. After each significant step, add an entry to `## Status Log`:
|
||||
```markdown
|
||||
YYYY-MM-DD HH:MM - Did X, decided Y because Z
|
||||
```
|
||||
3. If new information changes scope:
|
||||
- Stop
|
||||
- Write the new information in Status Log
|
||||
- Add a note: "Scope change detected, waiting for approval"
|
||||
- Wait for human approval before continuing
|
||||
4. If you encounter a blocker:
|
||||
- Write it in `## Blockers` with a proposed solution
|
||||
- Wait for resolution before continuing
|
||||
5. Do NOT skip steps or make assumptions about dependencies
|
||||
|
||||
### What Belongs in Status Log
|
||||
|
||||
- Decisions made and why
|
||||
- Code approaches tried and discarded
|
||||
- Findings from reading code
|
||||
- Anything that affects the plan
|
||||
- Any interaction with dependencies
|
||||
|
||||
### What Does NOT Belong in Status Log
|
||||
|
||||
- Trivial actions ("changed variable x to y")
|
||||
- Unnecessary detail
|
||||
- Personal commentary
|
||||
|
||||
### Exit Gate
|
||||
|
||||
Implementation complete. Self-Verification filled (see Stage 4).
|
||||
|
||||
---
|
||||
|
||||
## Stage 4: Self-Verification
|
||||
|
||||
### Who: Agent
|
||||
|
||||
### Steps
|
||||
|
||||
1. Run smoke tests:
|
||||
```bash
|
||||
# Run tests related to this feature
|
||||
pnpm test -- --grep "<relevant-pattern>"
|
||||
|
||||
# Check for console errors
|
||||
# (manually or via test)
|
||||
```
|
||||
2. Check each Acceptance Criterion:
|
||||
- Can you verify it passes? Mark `[x]`
|
||||
- Does it fail? Mark `[ ]` and fix it
|
||||
3. If UI change: take a screenshot
|
||||
- Save to `.issues/screenshots/<issue-id>-<description>.png`
|
||||
- Reference it in Self-Verification
|
||||
4. If depends-on: verify dependent features still work
|
||||
- Run their tests
|
||||
- Do a quick manual check
|
||||
5. Fill `## Agent Working Notes > Self-Verification`
|
||||
|
||||
### Self-Verification Must Be Honest
|
||||
|
||||
If a smoke test fails, fix it before claiming done. If an acceptance criterion can't be met, document why and wait for human guidance.
|
||||
|
||||
Do not claim "verified" if it isn't. The human will find out during review.
|
||||
|
||||
### Exit Gate
|
||||
|
||||
All Self-Verification items checked. Smoke test passes. Dependencies verified.
|
||||
|
||||
---
|
||||
|
||||
## Stage 5: Ready for Review
|
||||
|
||||
### Who: Human
|
||||
|
||||
### Agent's Steps
|
||||
|
||||
1. Ensure Status Log is complete
|
||||
2. Ensure Self-Verification is complete
|
||||
3. Add a review request in the file:
|
||||
```markdown
|
||||
### Human Review Notes
|
||||
|
||||
Review date: YYYY-MM-DD
|
||||
|
||||
Agent requests review.
|
||||
```
|
||||
4. The human will fill in the rest
|
||||
|
||||
### Human's Steps
|
||||
|
||||
1. Read the issue file completely
|
||||
2. Read the Status Log
|
||||
3. Read the Self-Verification
|
||||
4. Ask yourself:
|
||||
- Does the reasoning make sense?
|
||||
- Were good decisions made?
|
||||
- Did the agent check the dependencies?
|
||||
- Is the Self-Verification honest?
|
||||
- Are there any edge cases not covered?
|
||||
|
||||
5. Either:
|
||||
- **Approve**: Write "Approved" in Human Review Notes, proceed to Stage 6
|
||||
- **Request changes**: Write specific feedback in Human Review Notes, agent fixes (go back to Stage 3)
|
||||
|
||||
### What You're Approving
|
||||
|
||||
**Reasoning, not tasks.** You're not checking code line-by-line. You're checking:
|
||||
- The agent understood the problem
|
||||
- The agent made sensible decisions
|
||||
- The agent verified the work
|
||||
- Integration with dependencies was checked
|
||||
|
||||
If the reasoning is sound and verification was thorough, approve.
|
||||
|
||||
### Exit Gate
|
||||
|
||||
Human has written "Approved" in Human Review Notes.
|
||||
|
||||
---
|
||||
|
||||
## Stage 6: Close
|
||||
|
||||
### Who: Agent (with human oversight)
|
||||
|
||||
### Steps
|
||||
|
||||
1. Human changes status to `done`
|
||||
2. Human adds `completed: <date>` to frontmatter
|
||||
3. Agent deletes the `## Agent Working Notes` section
|
||||
4. Agent creates PR with issue number in title: `feat(#023): Add delete account button`
|
||||
5. Agent commits any remaining changes
|
||||
6. Agent notifies human PR is ready
|
||||
7. Human reviews PR and merges (or agent merges if approved)
|
||||
|
||||
### PR Requirements
|
||||
|
||||
- Title includes issue number: `feat(#023): ...`, `fix(#042): ...`
|
||||
- PR description links to the issue file
|
||||
- All checks pass (including pre-commit hook)
|
||||
|
||||
### Exit Gate
|
||||
|
||||
Issue closed. PR merged. Issue file has:
|
||||
- status: done
|
||||
- completed: <date>
|
||||
- Agent Working Notes section deleted
|
||||
|
||||
---
|
||||
|
||||
## Dependency Handling
|
||||
|
||||
### Creating Dependent Issues
|
||||
|
||||
When creating an issue that depends on another:
|
||||
1. List the dependency in `depends-on` frontmatter
|
||||
2. Read the dependency's issue file
|
||||
3. Understand what the dependency produces
|
||||
4. In your Plan, reference the dependency's output
|
||||
|
||||
### Working on Dependent Issues
|
||||
|
||||
Before starting:
|
||||
1. Read the dependency's issue file
|
||||
2. Read the dependency's code output (PR, files changed)
|
||||
3. Verify the dependency works in context
|
||||
|
||||
During:
|
||||
4. If dependency breaks, document it in Blockers
|
||||
5. Do not assume dependency is correct
|
||||
|
||||
Before claiming done:
|
||||
6. Verify your work with the dependency's output
|
||||
7. If integration breaks, fix or document
|
||||
|
||||
### Blocking Issues
|
||||
|
||||
If an issue is blocked by a dependency:
|
||||
- Set status to `blocked`
|
||||
- Add a note explaining why
|
||||
- Move to the next unblocked issue
|
||||
- Check back when the dependency is closed
|
||||
|
||||
---
|
||||
|
||||
## Parallel Work
|
||||
|
||||
Multiple agents can work on multiple issues simultaneously if:
|
||||
1. Issues are not dependent on each other
|
||||
2. Each agent reads the other's issues (to understand integration points)
|
||||
3. Each agent documents integration points checked
|
||||
|
||||
If issues ARE dependent:
|
||||
- Complete the dependency first (or mark it as priority)
|
||||
- Or coordinate with the human on timing
|
||||
|
||||
---
|
||||
|
||||
## Handling Scope Creep
|
||||
|
||||
If during implementation you discover the issue needs more than originally scoped:
|
||||
|
||||
1. **Stop coding**
|
||||
2. Document what was found in Status Log
|
||||
3. Write a proposed scope change in Status Log
|
||||
4. Mark it: "Scope change: waiting for approval"
|
||||
5. **Wait for human decision**
|
||||
6. Either:
|
||||
- Human approves scope expansion
|
||||
- Human creates a new issue for the expanded scope
|
||||
- Human decides scope stays the same
|
||||
|
||||
Do NOT unilaterally expand scope. Do NOT ignore the scope change.
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Situation | Action |
|
||||
|---|---|
|
||||
| Blocker encountered | Write in Blockers with proposed solution. Wait. |
|
||||
| Dependency broken | Document in Blockers. Wait for fix or guidance. |
|
||||
| Scope needs to expand | Stop. Document. Wait for approval. |
|
||||
| Can't verify something | Document what couldn't be verified and why. Ask for guidance. |
|
||||
| Human doesn't respond | Send a reminder. Do not proceed without acknowledgment. |
|
||||
| Pre-commit hook fails | Fix the issue file. Do not bypass the hook. |
|
||||
|
||||
---
|
||||
|
||||
## When in Doubt
|
||||
|
||||
Ask. Write in the issue file. Wait for response. Proceed only when you have acknowledgment.
|
||||
|
||||
It is better to pause and ask than to assume and break things.
|
||||
Reference in New Issue
Block a user