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
264
.hooks/issue-linter.js
Normal file
264
.hooks/issue-linter.js
Normal file
@@ -0,0 +1,264 @@
|
||||
#!/usr/bin/env node
|
||||
|
||||
/**
|
||||
* Issue Linter - Pre-commit hook validator
|
||||
*
|
||||
* Runs before every commit to ensure issue files are valid.
|
||||
*
|
||||
* Usage:
|
||||
* node .hooks/issue-linter.js
|
||||
*
|
||||
* Exit codes:
|
||||
* 0 - All checks passed
|
||||
* 1 - Validation errors found
|
||||
*/
|
||||
|
||||
const fs = require('fs');
|
||||
const path = require('path');
|
||||
const { execSync } = require('child_process');
|
||||
|
||||
// Configuration
|
||||
const ISSUES_DIR = '.issues';
|
||||
const REQUIRED_FRONTMATTER = ['id', 'title', 'status', 'priority', 'created'];
|
||||
const VALID_STATUSES = ['open', 'in-progress', 'done', 'blocked'];
|
||||
const VALID_PRIORITIES = ['low', 'medium', 'high', 'critical'];
|
||||
const REQUIRED_SECTIONS = ['What', 'Why', 'Acceptance Criteria', 'Verification'];
|
||||
|
||||
// Colors for output
|
||||
const RED = '\x1b[31m';
|
||||
const GREEN = '\x1b[32m';
|
||||
const YELLOW = '\x1b[33m';
|
||||
const RESET = '\x1b[0m';
|
||||
|
||||
let errors = [];
|
||||
let warnings = [];
|
||||
|
||||
function logError(msg) {
|
||||
errors.push(msg);
|
||||
console.error(`${RED}[issue-linter] ERROR: ${msg}${RESET}`);
|
||||
}
|
||||
|
||||
function logWarning(msg) {
|
||||
warnings.push(msg);
|
||||
console.warn(`${YELLOW}[issue-linter] WARNING: ${msg}${RESET}`);
|
||||
}
|
||||
|
||||
function logInfo(msg) {
|
||||
console.log(`${GREEN}[issue-linter] ${msg}${RESET}`);
|
||||
}
|
||||
|
||||
/**
|
||||
* Parse YAML frontmatter from markdown content
|
||||
*/
|
||||
function parseFrontmatter(content) {
|
||||
const match = content.match(/^---\n([\s\S]*?)\n---/);
|
||||
if (!match) return {};
|
||||
|
||||
const frontmatter = {};
|
||||
const lines = match[1].split('\n');
|
||||
|
||||
for (const line of lines) {
|
||||
const colonIndex = line.indexOf(':');
|
||||
if (colonIndex === -1) continue;
|
||||
|
||||
const key = line.slice(0, colonIndex).trim();
|
||||
let value = line.slice(colonIndex + 1).trim();
|
||||
|
||||
// Handle arrays (depends-on)
|
||||
if (value.startsWith('[') && value.endsWith(']')) {
|
||||
value = value.slice(1, -1).split(',').map(v => v.trim());
|
||||
}
|
||||
|
||||
frontmatter[key] = value;
|
||||
}
|
||||
|
||||
return frontmatter;
|
||||
}
|
||||
|
||||
/**
|
||||
* Check if a section exists in the content
|
||||
*/
|
||||
function sectionExists(content, sectionName) {
|
||||
// Look for ## Section Name or ### Section Name
|
||||
const regex = new RegExp(`^#{2,3}\\s+${sectionName}\\s*$`, 'm');
|
||||
return regex.test(content);
|
||||
}
|
||||
|
||||
/**
|
||||
* Get all files that were changed in this commit
|
||||
*/
|
||||
function getChangedFiles() {
|
||||
try {
|
||||
const output = execSync('git diff --cached --name-only', { encoding: 'utf8' });
|
||||
return output.trim().split('\n').filter(f => f.length > 0);
|
||||
} catch (e) {
|
||||
// Fallback for when git commands fail
|
||||
return [];
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Get the staging area (added files)
|
||||
*/
|
||||
function getStagedFiles() {
|
||||
try {
|
||||
const output = execSync('git diff --cached --name-only --diff-filter=ACM', { encoding: 'utf8' });
|
||||
return output.trim().split('\n').filter(f => f.length > 0);
|
||||
} catch (e) {
|
||||
return [];
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Get all issue files in .issues/
|
||||
*/
|
||||
function getIssueFiles() {
|
||||
const issuesPath = path.join(process.cwd(), ISSUES_DIR);
|
||||
|
||||
if (!fs.existsSync(issuesPath)) {
|
||||
return [];
|
||||
}
|
||||
|
||||
const files = fs.readdirSync(issuesPath, { recursive: true });
|
||||
return files
|
||||
.filter(f => f.endsWith('.md'))
|
||||
.map(f => path.join(ISSUES_DIR, f));
|
||||
}
|
||||
|
||||
/**
|
||||
* Validate a single issue file
|
||||
*/
|
||||
function validateIssueFile(filePath) {
|
||||
const fullPath = path.join(process.cwd(), filePath);
|
||||
|
||||
if (!fs.existsSync(fullPath)) {
|
||||
logError(`${filePath} does not exist`);
|
||||
return false;
|
||||
}
|
||||
|
||||
const content = fs.readFileSync(fullPath, 'utf8');
|
||||
const frontmatter = parseFrontmatter(content);
|
||||
let hasErrors = false;
|
||||
|
||||
// Check required frontmatter
|
||||
for (const field of REQUIRED_FRONTMATTER) {
|
||||
if (!(field in frontmatter)) {
|
||||
logError(`${filePath}: Missing frontmatter field "${field}"`);
|
||||
hasErrors = true;
|
||||
}
|
||||
}
|
||||
|
||||
// Check status is valid
|
||||
if (frontmatter.status && !VALID_STATUSES.includes(frontmatter.status)) {
|
||||
logError(`${filePath}: Invalid status "${frontmatter.status}". Must be one of: ${VALID_STATUSES.join(', ')}`);
|
||||
hasErrors = true;
|
||||
}
|
||||
|
||||
// Check priority is valid
|
||||
if (frontmatter.priority && !VALID_PRIORITIES.includes(frontmatter.priority)) {
|
||||
logError(`${filePath}: Invalid priority "${frontmatter.priority}". Must be one of: ${VALID_PRIORITIES.join(', ')}`);
|
||||
hasErrors = true;
|
||||
}
|
||||
|
||||
// Check completed date if status is done
|
||||
if (frontmatter.status === 'done' && !frontmatter.completed) {
|
||||
logError(`${filePath}: Has status "done" but no "completed" date in frontmatter`);
|
||||
hasErrors = true;
|
||||
}
|
||||
|
||||
// Check required sections
|
||||
for (const section of REQUIRED_SECTIONS) {
|
||||
if (!sectionExists(content, section)) {
|
||||
logError(`${filePath}: Missing section "## ${section}"`);
|
||||
hasErrors = true;
|
||||
}
|
||||
}
|
||||
|
||||
// Check Plan exists if status is in-progress
|
||||
if (frontmatter.status === 'in-progress' && !sectionExists(content, 'Plan')) {
|
||||
logError(`${filePath}: Has status "in-progress" but no Plan section`);
|
||||
hasErrors = true;
|
||||
}
|
||||
|
||||
// Check Agent Working Notes is deleted if status is done
|
||||
if (frontmatter.status === 'done' && sectionExists(content, 'Agent Working Notes')) {
|
||||
logError(`${filePath}: Has status "done" but Agent Working Notes section not deleted`);
|
||||
hasErrors = true;
|
||||
}
|
||||
|
||||
return !hasErrors;
|
||||
}
|
||||
|
||||
/**
|
||||
* Check if code was changed without a corresponding issue file
|
||||
*/
|
||||
function checkCodeWithoutIssue(stagedFiles) {
|
||||
const codeExtensions = ['.js', '.ts', '.jsx', '.tsx', '.py', '.go', '.rs', '.java', '.c', '.cpp', '.h', '.hpp', '.rb', '.php', '.cs', '.swift', '.kt', '.scala', '.vue', '.svelte'];
|
||||
|
||||
const codeFiles = stagedFiles.filter(f => {
|
||||
const ext = path.extname(f);
|
||||
return codeExtensions.includes(ext) || f.startsWith('src/') || f.startsWith('lib/') || f.startsWith('app/');
|
||||
});
|
||||
|
||||
const issueFiles = getIssueFiles();
|
||||
|
||||
for (const codeFile of codeFiles) {
|
||||
// Check if there's a related issue file
|
||||
// Extract potential issue number from recent commits or check .issues/INDEX.md
|
||||
// For simplicity, we just warn if there are code changes
|
||||
if (issueFiles.length === 0) {
|
||||
logWarning(`${codeFile}: Code changed but no issue files found`);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Main validation
|
||||
*/
|
||||
function main() {
|
||||
console.log('[issue-linter] Running pre-commit validation...\n');
|
||||
|
||||
const stagedFiles = getStagedFiles();
|
||||
const issueFiles = getIssueFiles();
|
||||
|
||||
// If no issues exist yet (first time setup), skip issue validation
|
||||
if (issueFiles.length === 0) {
|
||||
logInfo('No issue files found. Skipping issue validation.');
|
||||
logInfo('Add issue files to .issues/ directory before committing code.');
|
||||
process.exit(0);
|
||||
}
|
||||
|
||||
// Validate all issue files (not just staged ones)
|
||||
let allValid = true;
|
||||
for (const file of issueFiles) {
|
||||
if (!validateIssueFile(file)) {
|
||||
allValid = false;
|
||||
}
|
||||
}
|
||||
|
||||
// Check for code changes without issues
|
||||
checkCodeWithoutIssue(stagedFiles);
|
||||
|
||||
// Summary
|
||||
console.log('');
|
||||
if (errors.length > 0) {
|
||||
console.error(`${RED}[issue-linter] FAIL: ${errors.length} error(s) found${RESET}`);
|
||||
if (warnings.length > 0) {
|
||||
console.warn(`${YELLOW}[issue-linter] ${warnings.length} warning(s)${RESET}`);
|
||||
}
|
||||
process.exit(1);
|
||||
} else if (warnings.length > 0) {
|
||||
console.warn(`${YELLOW}[issue-linter] PASS with warnings: ${warnings.length} warning(s)${RESET}`);
|
||||
process.exit(0);
|
||||
} else {
|
||||
logInfo('PASS: All issue files are valid');
|
||||
process.exit(0);
|
||||
}
|
||||
}
|
||||
|
||||
// Run if called directly
|
||||
if (require.main === module) {
|
||||
main();
|
||||
}
|
||||
|
||||
module.exports = { validateIssueFile, parseFrontmatter };
|
||||
35
.issues/INDEX.md
Normal file
35
.issues/INDEX.md
Normal file
@@ -0,0 +1,35 @@
|
||||
# Issue Index
|
||||
|
||||
All open and closed issues for this project.
|
||||
|
||||
## Open Issues
|
||||
|
||||
| # | Title | Priority | Depends On | Status |
|
||||
|---|---|---|---|---|
|
||||
| — | No open issues | — | — | — |
|
||||
|
||||
## Closed Issues
|
||||
|
||||
| # | Title | Completed |
|
||||
|---|---|---|
|
||||
| — | No closed issues | — |
|
||||
|
||||
## Legend
|
||||
|
||||
- **Priority**: low < medium < high < critical
|
||||
- **Status**: open → in-progress → done (or blocked)
|
||||
- **Depends On**: Blocked until these issues are done
|
||||
|
||||
## Creating a New Issue
|
||||
|
||||
1. Pick the next number (highest + 1)
|
||||
2. Create `/.issues/<number>-<slug>.md`
|
||||
3. Use format from `/docs/workflow/ISSUE-FORMAT.md`
|
||||
4. Add entry to this table
|
||||
5. See `/docs/workflow/AGENT-PROMPTS.md` for creation prompt
|
||||
|
||||
## Workflow Overview
|
||||
|
||||
See `/docs/workflow/INDEX.md` for quick start.
|
||||
|
||||
See `/docs/workflow/WORKFLOW.md` for detailed stages.
|
||||
56
.issues/example/001-example-issue.md
Normal file
56
.issues/example/001-example-issue.md
Normal file
@@ -0,0 +1,56 @@
|
||||
---
|
||||
id: 001
|
||||
title: Example issue with full format
|
||||
status: open
|
||||
priority: medium
|
||||
created: 2024-04-18
|
||||
---
|
||||
|
||||
## What
|
||||
This is an example issue demonstrating the complete format. Replace this with your actual issue.
|
||||
|
||||
## Why
|
||||
Use this as a template when creating new issues. Delete this issue after reviewing the format.
|
||||
|
||||
## Acceptance Criteria
|
||||
- [ ] This example can be deleted
|
||||
- [ ] Format is clear and usable
|
||||
- [ ] All required sections are present
|
||||
|
||||
## Verification
|
||||
1. Read this file
|
||||
2. Verify all sections are present
|
||||
3. Delete this file when done
|
||||
|
||||
---
|
||||
|
||||
## 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 -->
|
||||
|
||||
### Blockers
|
||||
<!-- List any blockers with proposed solutions. If none, write "None." -->
|
||||
|
||||
### Self-Verification
|
||||
<!-- Must be filled before claiming done -->
|
||||
- [ ] Smoke test ran:
|
||||
- [ ] Acceptance criteria checked:
|
||||
- [ ] Screenshot taken (if UI change):
|
||||
- [ ] Dependent issues still work:
|
||||
|
||||
### Human Review Notes
|
||||
<!-- Human fills after agent marks done -->
|
||||
|
||||
Review date:
|
||||
|
||||
Reasoning check:
|
||||
- [ ] Plan makes sense
|
||||
- [ ] Status log shows good decisions
|
||||
- [ ] Self-verification is complete and honest
|
||||
|
||||
Feedback:
|
||||
79
README.md
79
README.md
@@ -1,3 +1,78 @@
|
||||
# workflow
|
||||
# Workflow Template
|
||||
|
||||
Standard issue-based workflow template for teams. Clone this repo to start a new project with enforced issue tracking.
|
||||
A portable, file-based issue tracking and development workflow for teams.
|
||||
|
||||
## Quick Start
|
||||
|
||||
1. **Clone this repo** into your new project
|
||||
2. **Install dependencies**: `pnpm install` (or npm, yarn)
|
||||
3. **Run setup**: `pnpm run setup` (installs pre-commit hook)
|
||||
4. **Read the docs**: See `docs/workflow/INDEX.md`
|
||||
5. **Start working**: See `docs/workflow/WORKFLOW.md`
|
||||
|
||||
## What This Is
|
||||
|
||||
- **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/ # Workflow documentation
|
||||
│ ├── INDEX.md ← Start here
|
||||
│ ├── ISSUE-FORMAT.md ← Issue file format
|
||||
│ ├── WORKFLOW.md ← Step-by-step process
|
||||
│ └── AGENT-PROMPTS.md ← Copy-paste agent prompts
|
||||
├── .issues/ # Issue files
|
||||
│ ├── INDEX.md # List of all issues
|
||||
│ └── example/ # Example issues
|
||||
├── .hooks/ # Pre-commit validators
|
||||
│ └── issue-linter.js # Issue format validator
|
||||
└── package.json # Setup scripts
|
||||
```
|
||||
|
||||
## Setup
|
||||
|
||||
```bash
|
||||
# Clone this repo into your new project
|
||||
git clone https://git.fbrns.co/shoko/workflow.git my-new-project
|
||||
cd my-new-project
|
||||
|
||||
# Remove git history (optional, for a fresh start)
|
||||
rm -rf .git
|
||||
|
||||
# Initialize git
|
||||
git init
|
||||
|
||||
# Install dependencies
|
||||
pnpm install
|
||||
|
||||
# Setup pre-commit hook
|
||||
pnpm run setup
|
||||
|
||||
# Remove this README (it's the template's README)
|
||||
rm README.md
|
||||
```
|
||||
|
||||
## For Teams
|
||||
|
||||
This template is maintained at: https://git.fbrns.co/shoko/workflow
|
||||
|
||||
To update the template for all projects:
|
||||
1. Pull latest changes from this repo
|
||||
2. Merge into your project
|
||||
|
||||
## Documentation
|
||||
|
||||
- [Workflow Overview](docs/workflow/INDEX.md)
|
||||
- [Issue Format](docs/workflow/ISSUE-FORMAT.md)
|
||||
- [Step-by-Step Workflow](docs/workflow/WORKFLOW.md)
|
||||
- [Agent Prompts](docs/workflow/AGENT-PROMPTS.md)
|
||||
|
||||
## License
|
||||
|
||||
Internal use. See https://git.fbrns.co/shoko/workflow
|
||||
|
||||
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.
|
||||
14
package.json
Normal file
14
package.json
Normal file
@@ -0,0 +1,14 @@
|
||||
{
|
||||
"name": "workflow-template",
|
||||
"version": "1.0.0",
|
||||
"description": "Standard issue-based workflow template for teams",
|
||||
"private": true,
|
||||
"scripts": {
|
||||
"setup": "node .hooks/issue-linter.js --setup",
|
||||
"validate:issues": "node .hooks/issue-linter.js",
|
||||
"test": "echo \"Add your test commands here\""
|
||||
},
|
||||
"devDependencies": {
|
||||
"pre-commit-hook": "^3.0.0"
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user