notque/vexjoy-agent / skills/process/workflow
workflow
VerifiedStructured work: multi-phase tasks, feature builds, planning, objective loops, hill climbing.
references/workflow-orchestrator/references/task-patterns.md
View on GitHub# Common Task Patterns
This document describes common task patterns and their verification strategies. Use these patterns when breaking down work into executable tasks.
**Note**: Examples reference various frameworks (Django, Flask, React, etc.). Adapt commands to match your project's tech stack.
## Pattern Categories
1. **File Creation Patterns** - Creating new files and resources
2. **File Modification Patterns** - Updating existing files
3. **Database Patterns** - Schema changes and migrations
4. **Testing Patterns** - Adding and running tests
5. **Configuration Patterns** - Updating system configuration
6. **Build & Deploy Patterns** - Compilation and deployment tasks
7. **Validation Patterns** - Verification and checking tasks
---
## 1. File Creation Patterns
### Pattern: Create Python Module
**When to use**: Creating new Python file with class or functions
**Task Structure**:
```json
{
"task_id": "T1",
"title": "Create [module_name] module",
"estimated_duration": "3 minutes",
"files": ["/absolute/path/to/module_name.py"],
"operations": [
"Create module_name.py file",
"Add module docstring",
"Define [Class/Function] with type hints",
"Add basic error handling"
],
"verification": {
"command": "python3 -c 'import module_name; print(dir(module_name))'",
"expected_output": "['ClassName', 'function_name']",
"success_criteria": "Module imports successfully and exports expected names"
}
}
```
**Verification Alternatives**:
- Type checking: `mypy /path/to/module_name.py`
- Linting: `pylint /path/to/module_name.py`
- Import test: `python3 -c 'import module_name'`
### Pattern: Create React Component
**When to use**: Creating new React/TypeScript component
**Task Structure**:
```json
{
"task_id": "T1",
"title": "Create [ComponentName] component",
"estimated_duration": "4 minutes",
"files": ["/absolute/path/to/ComponentName.tsx"],
"operations": [
"Create ComponentName.tsx file",
"Define TypeScript props interface",
"Implement functional component",
"Export component"
],
"verification": {
"command": "npx tsc --noEmit --project /path/to/tsconfig.json",
"expected_output": "No errors",
"success_criteria": "TypeScript compiles without errors"
}
}
```
**Verification Alternatives**:
- ESLint: `npx eslint /path/to/ComponentName.tsx`
- Import test: `node -e "require('./ComponentName')"`
- Build test: `npm run build`
### Pattern: Create Configuration File
**When to use**: Adding new YAML, JSON, or INI configuration
**Task Structure**:
```json
{
"task_id": "T1",
"title": "Create [config_name] configuration",
"estimated_duration": "2 minutes",
"files": ["/absolute/path/to/config.yaml"],
"operations": [
"Create config.yaml file",
"Define required configuration keys",
"Add default values",
"Add comments explaining options"
],
"verification": {
"command": "python3 -c 'import yaml; yaml.safe_load(open(\"/path/to/config.yaml\"))'",
"expected_output": "No exceptions",
"success_criteria": "YAML file is valid and parseable"
}
}
```
**Verification Alternatives**:
- JSON: `python3 -m json.tool < config.json`
- YAML: `yamllint config.yaml`
- INI: `python3 -c 'import configparser; c = configparser.ConfigParser(); c.read("config.ini")'`
### Pattern: Create Database Migration
**When to use**: Adding new database schema change
**Task Structure**:
```json
{
"task_id": "T1",
"title": "Create migration for [table_name]",
"estimated_duration": "3 minutes",
"files": ["/absolute/path/to/migrations/0001_create_table.py"],
"operations": [
"Create migration file with timestamp",
"Define up migration (create table/add column)",
"Define down migration (rollback logic)",
"Add migration dependencies"
],
"verification": {
"command": "python manage.py migrate --plan",
"expected_output": "0001_create_table",
"success_criteria": "Migration appears in plan without errors"
}
}
```
**Verification Alternatives**:
- Django: `python manage.py sqlmigrate app_name 0001`
- Alembic: `alembic upgrade --sql head`
- Flyway: `flyway validate`
---
## 2. File Modification Patterns
### Pattern: Add Function to Existing Module
**When to use**: Extending existing Python module with new function
**Task Structure**:
```json
{
"task_id": "T2",
"title": "Add [function_name] to [module]",
"estimated_duration": "3 minutes",
"files": ["/absolute/path/to/existing_module.py"],
"operations": [
"Add function_name with type hints",
"Add docstring with examples",
"Implement function logic",
"Add to __all__ export list"
],
"verification": {
"command": "python3 -c 'from module import function_name; print(function_name.__doc__)'",
"expected_output": "Function docstring appears",
"success_criteria": "Function is importable and has documentation"
}
}
```
**Verification Alternatives**:
- Test existing functions: `python3 -m pytest tests/test_module.py`
- Check exports: `python3 -c 'import module; print(module.__all__)'`
- Type check: `mypy module.py`
### Pattern: Update API Route
**When to use**: Modifying existing API endpoint behavior
**Task Structure**:
```json
{
"task_id": "T2",
"title": "Update [endpoint] to support [feature]",
"estimated_duration": "4 minutes",
"files": ["/absolute/path/to/routes/endpoint.py"],
"operations": [
"Add new parameter to route function",
"Add validation for new parameter",
"Update response format",
"Maintain backward compatibility"
],
"verification": {
"command": "curl -X GET http://localhost:5000/api/endpoint?new_param=test",
"expected_output": "200 OK",
"success_criteria": "Endpoint accepts new parameter and returns success"
}
}
```
**Verification Alternatives**:
- Integration test: `python3 -m pytest tests/test_endpoint.py`
- OpenAPI validation: `swagger-cli validate openapi.yaml`
- Manual test: `curl -v http://endpoint`
### Pattern: Refactor Class
**When to use**: Restructuring existing class without changing interface
**Task Structure**:
```json
{
"task_id": "T2",
"title": "Refactor [ClassName] for [reason]",
"estimated_duration": "5 minutes",
"files": ["/absolute/path/to/class_module.py"],
"operations": [
"Extract helper methods",
"Simplify complex logic",
"Add type hints",
"Preserve public interface"
],
"verification": {
"command": "python3 -m pytest tests/test_class_module.py -v",
"expected_output": "All tests pass",
"success_criteria": "All existing tests pass without modification"
}
}
```
**Verification Alternatives**:
- Coverage: `pytest --cov=module --cov-report=term-missing`
- Type check: `mypy class_module.py`
- Import test: `python3 -c 'from module import ClassName'`
---
## 3. Database Patterns
### Pattern: Add Database Column
**When to use**: Adding new field to existing table
**Task Structure**:
```json
{
"task_id": "T3",
"title": "Add [column_name] to [table_name]",
"estimated_duration": "3 minutes",
"files": ["/absolute/path/to/migrations/000X_add_column.py"],
"operations": [
"Create migration adding column",
"Set column type and constraints",
"Add default value for existing rows",
"Add index if needed for queries"
],
"verification": {
"command": "python manage.py migrate && python manage.py dbshell -c '\\d table_name'",
"expected_output": "column_name appears in schema",
"success_criteria": "Column exists with correct type and constraints"
}
}
```
**Verification Alternatives**:
- SQL check: `SELECT column_name FROM information_schema.columns WHERE table_name='table_name'`
- ORM check: `python3 -c 'from models import Model; print(Model._meta.fields)'`
- Data check: `SELECT column_name FROM table_name LIMIT 1`
### Pattern: Create Database Index
**When to use**: Adding index to improve query performance
**Task Structure**:
```json
{
"task_id": "T3",
"title": "Add index on [column] for [table]",
"estimated_duration": "2 minutes",
"files": ["/absolute/path/to/migrations/000X_add_index.py"],
"operations": [
"Create migration adding index",
"Specify index type (btree, hash, etc.)",
"Add concurrent creation flag if needed",
"Document query being optimized"
],
"verification": {
"command": "python manage.py dbshell -c '\\di table_name_*'",
"expected_output": "index_name appears in list",
"success_criteria": "Index exists on specified column"
}
}
```
**Verification Alternatives**:
- Query plan: `EXPLAIN SELECT * FROM table WHERE column = 'value'`
- Index list: `SELECT indexname FROM pg_indexes WHERE tablename = 'table_name'`
- Performance: `SELECT * FROM table WHERE column = 'value'` (should use index)
### Pattern: Seed Database Data
**When to use**: Adding initial or test data to database
**Task Structure**:
```json
{
"task_id": "T3",
"title": "Seed [data_type] data",
"estimated_duration": "3 minutes",
"files": ["/absolute/path/to/fixtures/seed_data.json"],
"operations": [
"Create fixture file with seed data",
"Define data in correct format",
"Add data for all required tables",
"Ensure data is idempotent (can run multiple times)"
],
"verification": {
"command": "python manage.py loaddata fixtures/seed_data.json && python manage.py dbshell -c 'SELECT COUNT(*) FROM table_name'",
"expected_output": "Expected row count",
"success_criteria": "Data loaded successfully and appears in database"
}
}
```
**Verification Alternatives**:
- ORM query: `python3 -c 'from models import Model; print(Model.objects.count())'`
- Direct query: `SELECT * FROM table_name WHERE id = 'known_id'`
- Fixture validation: `python3 -m json.tool fixtures/seed_data.json`
---
## 4. Testing Patterns
### Pattern: Add Unit Test
**When to use**: Creating test for individual function or class
**Task Structure**:
```json
{
"task_id": "T4",
"title": "Add unit test for [function_name]",
"estimated_duration": "4 minutes",
"files": ["/absolute/path/to/tests/test_module.py"],
"operations": [
"Create/update test file",
"Add test function with descriptive name",
"Test happy path",
"Test edge cases and error handling"
],
"verification": {
"command": "python3 -m pytest tests/test_module.py::test_function_name -v",
"expected_output": "1 passed",
"success_criteria": "New test passes"
}
}
```
**Verification Alternatives**:
- All tests: `pytest tests/test_module.py -v`
- Coverage: `pytest tests/test_module.py --cov=module --cov-report=term`
- Specific test: `pytest -k test_function_name`
### Pattern: Add Integration Test
**When to use**: Testing interaction between multiple components
**Task Structure**:
```json
{
"task_id": "T4",
"title": "Add integration test for [workflow]",
"estimated_duration": "5 minutes",
"files": ["/absolute/path/to/tests/integration/test_workflow.py"],
"operations": [
"Create integration test file",
"Set up test database/fixtures",
"Test end-to-end workflow",
"Assert expected outcomes",
"Clean up test data"
],
"verification": {
"command": "python3 -m pytest tests/integration/test_workflow.py -v",
"expected_output": "1 passed",
"success_criteria": "Integration test passes with real database"
}
}
```
**Verification Alternatives**:
- With fixtures: `pytest tests/integration/test_workflow.py --fixtures`
- Verbose: `pytest tests/integration/test_workflow.py -vv`
- Stop on failure: `pytest tests/integration/test_workflow.py -x`
### Pattern: Add Regression Test for Bug
**When to use**: Testing that specific bug is fixed
**Task Structure**:
```json
{
"task_id": "T4",
"title": "Add regression test for bug #[issue_number]",
"estimated_duration": "3 minutes",
"files": ["/absolute/path/to/tests/test_regressions.py"],
"operations": [
"Create test that reproduces bug",
"Test should fail before fix (confirming bug)",
"Add clear comment linking to issue",
"Test will pass after bug fix"
],
"verification": {
"command": "python3 -m pytest tests/test_regressions.py::test_issue_123 -v",
"expected_output": "1 failed (initially) or 1 passed (after fix)",
"success_criteria": "Test fails initially, passes after fix applied"
}
}
```
**Verification Alternatives**:
- Run before fix: Should fail
- Run after fix: Should pass
- Mark as xfail: `pytest.mark.xfail` until fixed
---
## 5. Configuration Patterns
### Pattern: Update Environment Variables
**When to use**: Adding new configuration to .env file
**Task Structure**:
```json
{
"task_id": "T5",
"title": "Add [VAR_NAME] environment variable",
"estimated_duration": "2 minutes",
"files": ["/absolute/path/to/.env", "/absolute/path/to/.env.example"],
"operations": [
"Add VAR_NAME to .env with value",
"Add VAR_NAME to .env.example with placeholder",
"Update documentation if needed",
"Add validation in application startup"
],
"verification": {
"command": "grep -q 'VAR_NAME' /path/to/.env && echo 'Found'",
"expected_output": "Found",
"success_criteria": "Variable exists in both .env and .env.example"
}
}
```
**Verification Alternatives**:
- Load test: `python3 -c 'import os; from dotenv import load_dotenv; load_dotenv(); print(os.getenv("VAR_NAME"))'`
- Validation: `python3 -c 'from config import settings; print(settings.VAR_NAME)'`
- Example check: `diff <(sort .env) <(sort .env.example)`
### Pattern: Update Nginx Configuration
**When to use**: Modifying web server configuration
**Task Structure**:
```json
{
"task_id": "T5",
"title": "Update nginx config for [change]",
"estimated_duration": "3 minutes",
"files": ["/etc/nginx/sites-available/myapp.conf"],
"operations": [
"Backup current config",
"Add/modify location block",
"Update proxy settings",
"Test configuration syntax"
],
"verification": {
"command": "nginx -t",
"expected_output": "syntax is ok",
"success_criteria": "Configuration is syntactically valid"
}
}
```
**Verification Alternatives**:
- Reload: `systemctl reload nginx && systemctl is-active nginx`
- Check endpoint: `curl -I http://localhost/endpoint`
- View logs: `tail -f /var/log/nginx/error.log`
### Pattern: Update Package Dependencies
**When to use**: Adding or updating package in requirements/package.json
**Task Structure**:
```json
{
"task_id": "T5",
"title": "Add [package_name] dependency",
"estimated_duration": "2 minutes",
"files": ["/absolute/path/to/requirements.txt"],
"operations": [
"Add package_name==version to requirements.txt",
"Pin to specific version for reproducibility",
"Add comment explaining why needed",
"Update requirements-dev.txt if needed"
],
"verification": {
"command": "pip install -r requirements.txt && python3 -c 'import package_name; print(package_name.__version__)'",
"expected_output": "version",
"success_criteria": "Package installs successfully and imports"
}
}
```
**Verification Alternatives**:
- NPM: `npm install && npm list package_name`
- Poetry: `poetry add package_name && poetry show package_name`
- Check conflicts: `pip check`
---
## 6. Build & Deploy Patterns
### Pattern: Build Docker Image
**When to use**: Creating or updating Docker container image
**Task Structure**:
```json
{
"task_id": "T6",
"title": "Build Docker image for [service]",
"estimated_duration": "4 minutes",
"files": ["/absolute/path/to/Dockerfile"],
"operations": [
"Update Dockerfile with changes",
"Build image with appropriate tag",
"Verify image size is reasonable",
"Test image locally"
],
"verification": {
"command": "docker build -t myapp:latest . && docker images myapp:latest",
"expected_output": "Image appears in list",
"success_criteria": "Image builds successfully and appears in docker images"
}
}
```
**Verification Alternatives**:
- Run container: `docker run --rm myapp:latest --version`
- Inspect: `docker inspect myapp:latest`
- Size check: `docker images myapp:latest --format "{{.Size}}"`
### Pattern: Run Build Process
**When to use**: Compiling or bundling application
**Task Structure**:
```json
{
"task_id": "T6",
"title": "Build [application] for production",
"estimated_duration": "3 minutes",
"files": [],
"operations": [
"Run build command",
"Verify build output directory",
"Check for build warnings/errors",
"Verify all expected files generated"
],
"verification": {
"command": "npm run build && test -d dist && echo 'Build successful'",
"expected_output": "Build successful",
"success_criteria": "Build completes and output directory exists"
}
}
```
**Verification Alternatives**:
- Size check: `du -sh dist/`
- File count: `find dist/ -type f | wc -l`
- Serve locally: `npx serve dist`
### Pattern: Deploy to Environment
**When to use**: Deploying application to staging/production
**Task Structure**:
```json
{
"task_id": "T6",
"title": "Deploy to [environment]",
"estimated_duration": "5 minutes",
"files": [],
"operations": [
"Build deployment artifact",
"Upload to target environment",
"Run database migrations if needed",
"Restart application services",
"Verify deployment health"
],
"verification": {
"command": "curl -f https://myapp.com/health && echo 'Deployed'",
"expected_output": "Deployed",
"success_criteria": "Health check endpoint returns 200 OK"
}
}
```
**Verification Alternatives**:
- Kubernetes: `kubectl rollout status deployment/myapp`
- Heroku: `heroku ps:scale web=1 && heroku logs --tail`
- SSH: `ssh server 'systemctl is-active myapp'`
---
## 7. Validation Patterns
### Pattern: Validate Code Quality
**When to use**: Running linters, formatters, type checkers
**Task Structure**:
```json
{
"task_id": "T7",
"title": "Validate code quality for [module]",
"estimated_duration": "2 minutes",
"files": [],
"operations": [
"Run linter on changed files",
"Run type checker",
"Run code formatter in check mode",
"Verify no violations found"
],
"verification": {
"command": "pylint module.py && mypy module.py && black --check module.py",
"expected_output": "No errors",
"success_criteria": "All quality checks pass"
}
}
```
**Verification Alternatives**:
- ESLint: `npx eslint src/`
- Prettier: `npx prettier --check src/`
- Go: `gofmt -l . && go vet ./...`
### Pattern: Validate Security
**When to use**: Running security scans on dependencies
**Task Structure**:
```json
{
"task_id": "T7",
"title": "Run security audit",
"estimated_duration": "3 minutes",
"files": [],
"operations": [
"Run dependency vulnerability scan",
"Check for known CVEs",
"Verify no critical issues",
"Document any warnings"
],
"verification": {
"command": "pip-audit --desc && echo 'No critical issues'",
"expected_output": "No critical issues",
"success_criteria": "No high or critical severity vulnerabilities found"
}
}
```
**Verification Alternatives**:
- NPM: `npm audit --audit-level=high`
- Snyk: `snyk test`
- Safety: `safety check`
### Pattern: Validate API Compliance
**When to use**: Checking API matches OpenAPI/Swagger spec
**Task Structure**:
```json
{
"task_id": "T7",
"title": "Validate API against OpenAPI spec",
"estimated_duration": "2 minutes",
"files": [],
"operations": [
"Start application server",
"Run OpenAPI validation tool",
"Check for spec violations",
"Verify all endpoints documented"
],
"verification": {
"command": "swagger-cli validate openapi.yaml && echo 'Valid'",
"expected_output": "Valid",
"success_criteria": "OpenAPI spec is valid and matches implementation"
}
}
```
**Verification Alternatives**:
- Dredd: `dredd openapi.yaml http://localhost:5000`
- Spectral: `spectral lint openapi.yaml`
- Postman: Import spec and run collection
---
## Task Duration Guidelines
### 2-minute tasks
- Add single environment variable
- Create simple configuration file
- Update single function parameter
- Add simple validation check
- Run single command verification
### 3-minute tasks
- Create database migration
- Add unit test for single function
- Update nginx configuration block
- Add single Python class/function
- Create simple React component
### 4-minute tasks
- Add API endpoint handler
- Implement integration test
- Add frontend component with styles
- Update database model with validation
- Build and verify Docker image
### 5-minute tasks
- Refactor complex class
- Add comprehensive integration test
- Update deployment configuration
- Implement bug fix with test
- Add component with multiple tests
**Anything longer than 5 minutes should be split into multiple tasks.**
## Verification Command Patterns
### Immediate Verification (fastest)
```bash
# File exists
test -f /path/to/file && echo "Exists"
# Directory exists
test -d /path/to/dir && echo "Exists"
# Content check
grep -q "expected_text" /path/to/file && echo "Found"
# JSON valid
python3 -m json.tool < file.json > /dev/null && echo "Valid"
```
### Import/Syntax Verification
```bash
# Python import
python3 -c 'import module_name'
# Python syntax
python3 -m py_compile file.py
# JavaScript syntax
node -c file.js
# TypeScript compile
npx tsc --noEmit
```
### Service Verification
```bash
# HTTP endpoint
curl -f http://localhost:5000/health
# Service status
systemctl is-active service_name
# Process running
pgrep -f process_name
# Port listening
netstat -tuln | grep :8000
```
### Test Execution
```bash
# Python unit test
python3 -m pytest tests/test_module.py::test_function -v
# Python all tests
python3 -m pytest tests/
# JavaScript tests
npm test -- ComponentName
# Go tests
go test ./...
```
### Build Verification
```bash
# Docker build
docker build -t app:latest . && docker images app:latest
# NPM build
npm run build && test -d dist
# Go build
go build -o bin/app ./cmd/app
# Python package
python3 setup.py sdist && ls dist/
```
## Common Verification Mistakes
### Write Specific Verification Commands
```json
{
"verification": {
"command": "ls file.py",
"expected_output": "file.py",
"success_criteria": "File exists"
}
}
```
**Problem**: Only checks existence, not correctness
### Specific and Meaningful
```json
{
"verification": {
"command": "python3 -c 'import file; assert hasattr(file, \"main_function\")'",
"expected_output": "No exceptions",
"success_criteria": "Module imports and exports expected function"
}
}
```
### Verify with Real Commands
```json
{
"verification": {
"command": "echo 'OK'",
"expected_output": "OK",
"success_criteria": "Command runs"
}
}
```
**Problem**: Fake verification, always passes
### Real Verification
```json
{
"verification": {
"command": "python3 -m pytest tests/test_new_feature.py -v",
"expected_output": "1 passed",
"success_criteria": "New feature test passes"
}
}
```
### Target Verification to Changed Files
```json
{
"verification": {
"command": "npm test",
"expected_output": "All tests pass",
"success_criteria": "Full test suite passes"
}
}
```
**Problem**: May take >2 minutes for large test suites
### Targeted Verification
```json
{
"verification": {
"command": "npm test -- NewComponent.test.tsx",
"expected_output": "PASS",
"success_criteria": "Only new component tests pass"
}
}
```
## Summary Checklist
When creating a task, verify:
- [ ] Task duration is 2-5 minutes
- [ ] All file paths are absolute
- [ ] Operations are specific and actionable
- [ ] Verification command actually tests the change
- [ ] Expected output is realistic and specific
- [ ] Success criteria are clear and measurable
- [ ] Rollback strategy is defined (if applicable)
- [ ] Dependencies are declared if task relies on others
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| planning-and-task-breakdownaddyosmani/agent-skillsBreaks work into ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable tasks. Use when a task feels too large to start, when you need to estimate scope, or when parallel work is possible. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| screenpipethedotmack/claude-memSearch screen and audio history recorded by Screenpipe and optionally save selected context into claude-mem. Use when the user asks to recall desktop activity, a meeting, or something seen in another app through Screenpipe. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| contact-widgetnexu-io/open-designSelf-contained floating chat widget with welcome screen, social links, meeting button, and message input. Single HTML file, zero dependencies. | Stars: 108k | Updated | Claude CodeCodex | Verified | Install |
| meeting-notesnexu-io/open-designMeeting notes page — title bar with attendees, agenda checklist, decisions block, action items table with owners + dates, and a "next meeting" footer. Use when the brief mentions "meeting notes", "minutes", "1:1 notes", "all-hands recap", or "会议纪要". | Stars: 108k | Updated | Claude CodeCodex | Verified | Install |