diff --git a/.deepwork/jobs/commit/job.yml b/.deepwork/jobs/commit/job.yml index 6760c275..ea0bf955 100644 --- a/.deepwork/jobs/commit/job.yml +++ b/.deepwork/jobs/commit/job.yml @@ -49,35 +49,23 @@ steps: outputs: - code_reviewed # implicit state: code has been reviewed and issues addressed dependencies: [] - hooks: - after_agent: - - prompt: | - Verify the code review is complete: - 1. Changed files were identified - 2. Sub-agent reviewed the code for general issues, DRY opportunities, naming clarity, and test coverage - 3. All identified issues were addressed or documented as intentional - If ALL criteria are met, include `✓ Quality Criteria Met`. + quality_criteria: + - "Changed files were identified" + - "Sub-agent reviewed the code for general issues, DRY opportunities, naming clarity, and test coverage" + - "All identified issues were addressed or documented as intentional" - id: test name: "Run Tests" description: "Pulls latest code and runs tests until all pass. Use after code review passes to verify changes work correctly." instructions_file: steps/test.md - inputs: - - name: test_command - description: "Test command to run (optional - will auto-detect if not provided)" + inputs: [] outputs: - tests_passing # implicit state: all tests pass dependencies: - review - hooks: - after_agent: - - prompt: | - Verify the tests are passing: - 1. Latest code was pulled from the branch - 2. All tests completed successfully - 3. No test failures or errors remain - 4. Test output shows passing status - If ALL criteria are met, include `✓ Quality Criteria Met`. + quality_criteria: + - "Latest code was pulled from the branch" + - "All tests are passing" - id: lint name: "Lint Code" @@ -88,14 +76,10 @@ steps: - code_formatted # implicit state: code formatted and linted dependencies: - test - hooks: - after_agent: - - prompt: | - Verify the linting is complete: - 1. ruff format was run successfully - 2. ruff check was run successfully (with --fix) - 3. No remaining lint errors - If ALL criteria are met, include `✓ Quality Criteria Met`. + quality_criteria: + - "ruff format was run successfully" + - "ruff check was run with --fix flag" + - "No remaining lint errors" - id: commit_and_push name: "Commit and Push" @@ -106,14 +90,9 @@ steps: - changes_committed # implicit state: changes committed and pushed dependencies: - lint - hooks: - after_agent: - - prompt: | - Verify the commit is ready: - 1. Changed files list was reviewed by the agent - 2. Files match what was modified during this session (or unexpected changes were investigated) - 3. CHANGELOG.md was updated with entries in the [Unreleased] section (if changes warrant documentation) - 4. Version numbers were NOT modified (pyproject.toml version and CHANGELOG version headers must remain unchanged) - 5. Commit was created with appropriate message - 6. Changes were pushed to remote - If ALL criteria are met, include `✓ Quality Criteria Met`. + quality_criteria: + - "Changed files were verified against expectations" + - "CHANGELOG.md was updated with entries in [Unreleased] section (if changes warrant documentation)" + - "Version numbers were NOT modified (pyproject.toml version and CHANGELOG version headers unchanged)" + - "Commit was created with appropriate message" + - "Changes were pushed to remote" diff --git a/.deepwork/jobs/commit/steps/commit_and_push.md b/.deepwork/jobs/commit/steps/commit_and_push.md index a1160a91..cb9e8891 100644 --- a/.deepwork/jobs/commit/steps/commit_and_push.md +++ b/.deepwork/jobs/commit/steps/commit_and_push.md @@ -78,14 +78,11 @@ Check the list of changed files against what was modified during this session, e ## Quality Criteria -- Changed files list was reviewed by the agent -- Files match what was modified during this session (or unexpected changes were investigated and handled) -- CHANGELOG.md was updated with entries in the `[Unreleased]` section (if changes warrant documentation) -- Version numbers were NOT modified (in pyproject.toml or CHANGELOG.md version headers) -- Commit message follows project conventions -- Commit was created successfully +- Changed files were verified against expectations +- CHANGELOG.md was updated with entries in [Unreleased] section (if changes warrant documentation) +- Version numbers were NOT modified (pyproject.toml version and CHANGELOG version headers unchanged) +- Commit was created with appropriate message - Changes were pushed to remote -- When all criteria are met, include `✓ Quality Criteria Met` in your response ## Context diff --git a/.deepwork/jobs/commit/steps/lint.md b/.deepwork/jobs/commit/steps/lint.md index a94e8c21..4485549d 100644 --- a/.deepwork/jobs/commit/steps/lint.md +++ b/.deepwork/jobs/commit/steps/lint.md @@ -63,9 +63,7 @@ Report the results of each command. - ruff format was run successfully - ruff check was run with --fix flag -- No remaining lint errors (or all are documented and intentional) -- Sub-agent was used to conserve context -- When all criteria are met, include `✓ Quality Criteria Met` in your response +- No remaining lint errors ## Context diff --git a/.deepwork/jobs/commit/steps/review.md b/.deepwork/jobs/commit/steps/review.md index 618f20a4..bfe8cc0c 100644 --- a/.deepwork/jobs/commit/steps/review.md +++ b/.deepwork/jobs/commit/steps/review.md @@ -23,32 +23,11 @@ Use a sub-agent to review the staged/changed code and identify issues that shoul Use the Task tool with these parameters: - `subagent_type`: "general-purpose" - - `prompt`: Include the list of changed files and the review criteria below - - The sub-agent should review each changed file for: - - **General Issues** - - Logic errors or potential bugs - - Error handling gaps - - Security concerns - - Performance issues - - **DRY Opportunities** - - Duplicated code that should be extracted into functions - - Repeated patterns that could be abstracted - - Copy-pasted logic with minor variations - - **Naming Clarity** - - Variables, functions, and classes should have clear, descriptive names - - Names should reflect purpose and intent - - Avoid abbreviations that aren't universally understood - - Consistent naming conventions throughout - - **Test Coverage** - - New functions or classes should have corresponding tests - - New code paths should be tested - - Edge cases should be covered - - If tests are missing, note what should be tested + - `prompt`: Instruct the sub-agent to: + - Read the code review standards from `doc/code_review_standards.md` + - Read each of the changed files + - Review each file against the standards + - Report issues found with file, line number, severity, and suggested fix 3. **Review sub-agent findings** - Examine each issue identified @@ -65,40 +44,11 @@ Use a sub-agent to review the staged/changed code and identify issues that shoul - If you made substantial changes, consider running another review pass - Ensure fixes didn't introduce new issues -## Example Sub-Agent Prompt - -``` -Review the following changed files for code quality issues: - -Files to review: -- src/module.py -- src/utils.py -- tests/test_module.py - -For each file, check for: - -1. **General issues**: Logic errors, bugs, error handling gaps, security concerns -2. **DRY opportunities**: Duplicated code, repeated patterns that should be extracted -3. **Naming clarity**: Are variable/function/class names clear and descriptive? -4. **Test coverage**: Does new functionality have corresponding tests? - -Read each file and provide a structured report of issues found, organized by category. -For each issue, include: -- File and line number -- Description of the issue -- Suggested fix - -If no issues are found in a category, state that explicitly. -``` - ## Quality Criteria - Changed files were identified -- Sub-agent reviewed all changed files -- Issues were categorized (general, DRY, naming, tests) +- Sub-agent read the code review standards and reviewed all changed files - All identified issues were addressed or documented as intentional -- Sub-agent was used to conserve context -- When all criteria are met, include `✓ Quality Criteria Met` in your response ## Context diff --git a/.deepwork/jobs/commit/steps/test.md b/.deepwork/jobs/commit/steps/test.md index 6d442612..29c2b920 100644 --- a/.deepwork/jobs/commit/steps/test.md +++ b/.deepwork/jobs/commit/steps/test.md @@ -44,9 +44,7 @@ Execute the test suite for the project and iteratively fix any failures until al ## Quality Criteria - Latest code was pulled from the branch -- Test command was correctly identified or used from input -- All tests are now passing -- When all criteria are met, include `✓ Quality Criteria Met` in your response +- All tests are passing ## Context diff --git a/doc/code_review_standards.md b/doc/code_review_standards.md new file mode 100644 index 00000000..3761c354 --- /dev/null +++ b/doc/code_review_standards.md @@ -0,0 +1,67 @@ +# Code Review Standards + +This document defines the standards used during code review in the commit workflow. + +## Review Categories + +### General Issues + +Check for: +- Logic errors or potential bugs +- Error handling gaps +- Security concerns (injection, authentication, authorization) +- Performance issues (inefficient algorithms, unnecessary computation) +- Resource leaks (unclosed files, connections) + +### DRY (Don't Repeat Yourself) + +Look for: +- Duplicated code that should be extracted into functions +- Repeated patterns that could be abstracted +- Copy-pasted logic with minor variations +- Similar code blocks that differ only in variable names + +### Naming Clarity + +Ensure: +- Variables, functions, and classes have clear, descriptive names +- Names reflect purpose and intent +- Abbreviations are avoided unless universally understood +- Naming conventions are consistent throughout the codebase + +### Test Coverage + +Verify: +- New functions or classes have corresponding tests +- New code paths are tested +- Edge cases are covered +- Error conditions are tested +- If tests are missing, note what should be tested + +### Test Quality + +Ensure tests add value and are not duplicative: +- Each test should verify a distinct behavior or scenario +- Tests should not duplicate what other tests already cover +- Test names should clearly describe what they're testing +- Tests should be meaningful, not just checking trivial cases +- Avoid testing implementation details; focus on behavior +- If multiple tests appear redundant, suggest consolidation + +## Severity Levels + +When reporting issues, categorize by severity: + +- **Critical**: Must fix before commit (bugs, security issues) +- **High**: Should fix before commit (logic errors, missing error handling) +- **Medium**: Recommended to fix (DRY violations, unclear naming) +- **Low**: Nice to have (style improvements, minor optimizations) + +## Review Output Format + +For each issue found, provide: +1. File and line number +2. Severity level +3. Category (General/DRY/Naming/Tests) +4. Description of the issue +5. Suggested fix or improvement diff --git a/library/jobs/README.md b/library/jobs/README.md index 4c49bb02..8d80d673 100644 --- a/library/jobs/README.md +++ b/library/jobs/README.md @@ -37,6 +37,10 @@ The job definition file contains: - `version`: Semantic version (e.g., "1.0.0") - `summary`: Brief description (under 200 characters) - `description`: Detailed explanation of the job's purpose +- `workflows`: Named sequences of steps (optional) + - `name`: Workflow identifier + - `summary`: What the workflow accomplishes + - `steps`: Ordered list of step IDs to execute - `steps`: Array of step definitions with: - `id`: Step identifier - `name`: Human-readable step name @@ -45,6 +49,7 @@ The job definition file contains: - `inputs`: What the step requires - `outputs`: What the step produces - `dependencies`: Other steps that must complete first + - `quality_criteria`: Measurable criteria for step completion ### steps/ diff --git a/library/jobs/commit/block_bash_with_instructions.sh b/library/jobs/commit/block_bash_with_instructions.sh new file mode 100755 index 00000000..7bd16f88 --- /dev/null +++ b/library/jobs/commit/block_bash_with_instructions.sh @@ -0,0 +1,74 @@ +#!/bin/bash +# block_bash_with_instructions.sh - Blocks specific bash commands and provides alternative instructions +# +# This hook intercepts Bash tool use calls and blocks commands that match +# specific patterns, providing alternative instructions to the agent. +# +# Usage: Registered as a PreToolUse hook in .claude/settings.json +# +# Input (stdin): JSON from Claude Code hook system containing tool_name and tool_input +# Output (stderr): Error message if blocked (Claude Code reads stderr for exit code 2) +# Exit codes: +# 0 - Success (allow action) +# 2 - Blocking error (prevent action with message) + +set -e + +# ============================================================================= +# BLOCKED COMMANDS CONFIGURATION +# ============================================================================= +# Format: Each entry is a regex pattern followed by a delimiter (|||) and instructions +# The regex is matched against the full bash command +# Add new blocked commands here: + +BLOCKED_COMMANDS=( + '^[[:space:]]*git[[:space:]]+commit|||All commits must be done via the `/commit` skill. Do not use git commit directly. Instead, run `/commit` to start the commit workflow which includes code review, testing, and linting before committing.' +) + +# ============================================================================= +# HOOK LOGIC - DO NOT MODIFY BELOW UNLESS NECESSARY +# ============================================================================= + +# Read stdin into variable +HOOK_INPUT="" +if [ ! -t 0 ]; then + HOOK_INPUT=$(cat) +fi + +# Exit early if no input +if [ -z "${HOOK_INPUT}" ]; then + exit 0 +fi + +# Extract tool_name from input +TOOL_NAME=$(echo "${HOOK_INPUT}" | jq -r '.tool_name // empty' 2>/dev/null) + +# Only process Bash tool calls +if [ "${TOOL_NAME}" != "Bash" ]; then + exit 0 +fi + +# Extract the command from tool_input +COMMAND=$(echo "${HOOK_INPUT}" | jq -r '.tool_input.command // empty' 2>/dev/null) + +# Exit if no command +if [ -z "${COMMAND}" ]; then + exit 0 +fi + +# Check each blocked pattern +for entry in "${BLOCKED_COMMANDS[@]}"; do + # Split entry by delimiter + pattern="${entry%%|||*}" + instructions="${entry##*|||}" + + # Check if command matches pattern (using extended regex) + if echo "${COMMAND}" | grep -qE "${pattern}"; then + # Output error message to stderr (Claude Code reads stderr for exit code 2) + echo "${instructions}" >&2 + exit 2 + fi +done + +# Command is allowed +exit 0 diff --git a/library/jobs/commit/code_review_standards.example.md b/library/jobs/commit/code_review_standards.example.md new file mode 100644 index 00000000..3761c354 --- /dev/null +++ b/library/jobs/commit/code_review_standards.example.md @@ -0,0 +1,67 @@ +# Code Review Standards + +This document defines the standards used during code review in the commit workflow. + +## Review Categories + +### General Issues + +Check for: +- Logic errors or potential bugs +- Error handling gaps +- Security concerns (injection, authentication, authorization) +- Performance issues (inefficient algorithms, unnecessary computation) +- Resource leaks (unclosed files, connections) + +### DRY (Don't Repeat Yourself) + +Look for: +- Duplicated code that should be extracted into functions +- Repeated patterns that could be abstracted +- Copy-pasted logic with minor variations +- Similar code blocks that differ only in variable names + +### Naming Clarity + +Ensure: +- Variables, functions, and classes have clear, descriptive names +- Names reflect purpose and intent +- Abbreviations are avoided unless universally understood +- Naming conventions are consistent throughout the codebase + +### Test Coverage + +Verify: +- New functions or classes have corresponding tests +- New code paths are tested +- Edge cases are covered +- Error conditions are tested +- If tests are missing, note what should be tested + +### Test Quality + +Ensure tests add value and are not duplicative: +- Each test should verify a distinct behavior or scenario +- Tests should not duplicate what other tests already cover +- Test names should clearly describe what they're testing +- Tests should be meaningful, not just checking trivial cases +- Avoid testing implementation details; focus on behavior +- If multiple tests appear redundant, suggest consolidation + +## Severity Levels + +When reporting issues, categorize by severity: + +- **Critical**: Must fix before commit (bugs, security issues) +- **High**: Should fix before commit (logic errors, missing error handling) +- **Medium**: Recommended to fix (DRY violations, unclear naming) +- **Low**: Nice to have (style improvements, minor optimizations) + +## Review Output Format + +For each issue found, provide: +1. File and line number +2. Severity level +3. Category (General/DRY/Naming/Tests) +4. Description of the issue +5. Suggested fix or improvement diff --git a/library/jobs/commit/commit_job_git_commit.sh b/library/jobs/commit/commit_job_git_commit.sh new file mode 100755 index 00000000..764b0768 --- /dev/null +++ b/library/jobs/commit/commit_job_git_commit.sh @@ -0,0 +1,7 @@ +#!/bin/bash +# commit_job_git_commit.sh - Wrapper for git commit invoked via the /commit skill +# +# This script bypasses the PreToolUse hook that blocks direct `git commit` commands. +# It allows the commit job to perform the actual commit after all quality checks pass. + +exec git commit "$@" diff --git a/library/jobs/commit/job.yml b/library/jobs/commit/job.yml new file mode 100644 index 00000000..ebf4575c --- /dev/null +++ b/library/jobs/commit/job.yml @@ -0,0 +1,83 @@ +name: commit +version: "1.0.0" +summary: "Reviews code, runs tests, lints, and commits changes. Use when ready to commit work with quality checks." +description: | + A workflow for preparing and committing code changes with quality checks. + + The **full** workflow starts with a code review to catch issues early, runs tests until + they pass, formats and lints code, then reviews changed files before + committing and pushing. The review and lint steps use sub-agents to reduce + context usage. + + Steps: + 1. review - Code review for issues, DRY opportunities, naming, and test coverage (runs in sub-agent) + 2. test - Pull latest code and run tests until they pass + 3. lint - Format and lint code (runs in sub-agent) + 4. commit_and_push - Review changes and commit/push + +workflows: + - name: full + summary: "Full commit workflow: review, test, lint, and commit" + steps: + - review + - test + - lint + - commit_and_push + +changelog: + - version: "1.0.0" + changes: "Initial library version - generalized from project-specific commit workflow" + +steps: + - id: review + name: "Code Review" + description: "Reviews changed code for issues, DRY opportunities, naming clarity, and test coverage using a sub-agent. Use as the first step before testing." + instructions_file: steps/review.md + inputs: [] + outputs: + - code_reviewed # implicit state: code has been reviewed and issues addressed + dependencies: [] + quality_criteria: + - "Changed files were identified" + - "Code was reviewed against the project's code review standards" + - "All identified issues were addressed or documented as intentional" + + - id: test + name: "Run Tests" + description: "Pulls latest code and runs tests until all pass. Use after code review passes to verify changes work correctly." + instructions_file: steps/test.md + inputs: [] + outputs: + - tests_passing # implicit state: all tests pass + dependencies: + - review + quality_criteria: + - "Latest code was pulled from the branch" + - "All tests are passing" + + - id: lint + name: "Lint Code" + description: "Formats and lints code using a sub-agent. Use after tests pass to ensure code style compliance." + instructions_file: steps/lint.md + inputs: [] + outputs: + - code_formatted # implicit state: code formatted and linted + dependencies: + - test + quality_criteria: + - "Code was formatted" + - "Lint check passed with no errors" + + - id: commit_and_push + name: "Commit and Push" + description: "Verifies changed files, creates commit, and pushes to remote. Use after linting passes to finalize changes." + instructions_file: steps/commit_and_push.md + inputs: [] + outputs: + - changes_committed # implicit state: changes committed and pushed + dependencies: + - lint + quality_criteria: + - "Changed files were verified against expectations" + - "Commit was created with appropriate message" + - "Changes were pushed to remote" diff --git a/library/jobs/commit/readme.md b/library/jobs/commit/readme.md new file mode 100644 index 00000000..fd067a1d --- /dev/null +++ b/library/jobs/commit/readme.md @@ -0,0 +1,174 @@ +# Commit Job + +A structured workflow for committing code changes with built-in quality checks. + +## Overview + +This job implements a comprehensive commit workflow that ensures code quality before every commit. Instead of allowing direct `git commit` commands, this job: + +1. **Reviews** changed code for issues, DRY opportunities, naming clarity, and test coverage +2. **Tests** the code to ensure all tests pass +3. **Lints** the code to ensure consistent formatting and style +4. **Commits** and pushes only after all checks pass + +## Why Hijack `git commit`? + +The core design principle of this job is that **every commit should pass through quality checks**. To enforce this, we intercept `git commit` commands and redirect the agent to use the `/commit` skill instead. + +Without this interception, an AI agent might: +- Commit code that hasn't been reviewed +- Push changes without running tests +- Skip linting, leading to inconsistent code style +- Bypass the structured workflow entirely + +By blocking `git commit` and requiring the commit job's script, we guarantee that: +- Code is reviewed before testing (catching issues early) +- Tests pass before linting (no point linting broken code) +- Linting completes before committing (consistent style) +- All quality gates are passed before code reaches the repository + +## IMPORTANT: REQUIRED CUSTOMIZATION + +When installing this job to a new project, you must customize the following: + +### 1. Replace `[test command]` + +In `steps/test.md`, replace `[test command]` with your project's test command (e.g., `pytest`, `npm test`, `go test ./...`). + +### 2. Replace `[format command]` + +In `steps/lint.md`, replace `[format command]` with your project's code formatting command (e.g., `ruff format .`, `npx prettier --write .`, `go fmt ./...`). + +### 3. Replace `[lint check command]` + +In `steps/lint.md`, replace `[lint check command]` with your project's lint check command (e.g., `ruff check --fix .`, `npx eslint --fix .`, `golangci-lint run`). + +### 4. Replace `[code review standards path]` + +In `steps/review.md`, replace `[code review standards path]` with the path to your project's code review standards file (e.g., `docs/code_review_standards.md`). + +If your project doesn't have a code review standards file yet, you can use the provided example as a starting point: + +```bash +cp library/jobs/commit/code_review_standards.example.md docs/code_review_standards.md +``` + +Then customize `docs/code_review_standards.md` to match your project's specific requirements, coding style, and quality expectations. + +### 5. Replace `[commit script path]` + +In `steps/commit_and_push.md`, replace `[commit script path]` with the path to your commit wrapper script (e.g., `.deepwork/jobs/commit/commit_job_git_commit.sh`). See installation step 3 below for how to create this script. + +## Installation + +### 1. Copy the Job Folder + +Copy this entire `commit` folder to your project's `.deepwork/jobs/` directory: + +```bash +cp -r library/jobs/commit .deepwork/jobs/ +``` + +### 2. Install the Git Commit Blocker Hook + +The job includes a `block_bash_with_instructions.sh` script that intercepts `git commit` commands and redirects the agent to use the `/commit` skill. Copy it to your hooks directory and make it executable: + +```bash +mkdir -p .claude/hooks +cp .deepwork/jobs/commit/block_bash_with_instructions.sh .claude/hooks/ +chmod +x .claude/hooks/block_bash_with_instructions.sh +``` + +### 3. Make the Commit Wrapper Script Executable + +The job also includes a `commit_job_git_commit.sh` script that bypasses the hook interception (used by the commit job itself). Make it executable: + +```bash +chmod +x .deepwork/jobs/commit/commit_job_git_commit.sh +``` + +### 4. Configure settings.json + +Add the following to your `.claude/settings.json`: + +```json +{ + "permissions": { + "allow": [ + "Bash(.deepwork/jobs/commit/commit_job_git_commit.sh:*)" + ] + }, + "hooks": { + "PreToolUse": [ + { + "matcher": "Bash", + "hooks": [ + { + "type": "command", + "command": ".claude/hooks/block_bash_with_instructions.sh" + } + ] + } + ] + } +} +``` + +This configuration: +- Allows the commit wrapper script to run without prompts +- Registers the hook that blocks direct `git commit` commands + +### 5. Customize the Placeholders + +Replace all placeholders in the step files as described in the "Required Customization" section above. + +### 6. Sync the Skills + +Run `deepwork sync` to generate the slash commands for your AI coding assistant. + +## Workflow Steps + +### 1. Code Review (`/commit.review`) + +Uses a sub-agent to review changed files against the standards defined in your project's code review standards file. The example standards file checks for: +- General issues (bugs, security, performance) +- DRY opportunities (duplicated code) +- Naming clarity (descriptive names) +- Test coverage (missing tests) + +### 2. Run Tests (`/commit.test`) + +- Pulls latest code from the branch +- Runs the test suite +- Fixes any failing tests +- Iterates until all tests pass + +### 3. Lint Code (`/commit.lint`) + +Uses a sub-agent to: +- Format code according to project style +- Run lint checks +- Fix any auto-fixable issues + +### 4. Commit and Push (`/commit.commit_and_push`) + +- Reviews changed files against expectations +- Creates commit with appropriate message +- Pushes to remote repository + +## Usage + +Once installed and synced, simply run: + +``` +/commit +``` + +This will execute all steps in order. You can also run individual steps: + +``` +/commit.review +/commit.test +/commit.lint +/commit.commit_and_push +``` diff --git a/library/jobs/commit/steps/commit_and_push.md b/library/jobs/commit/steps/commit_and_push.md new file mode 100644 index 00000000..565c4877 --- /dev/null +++ b/library/jobs/commit/steps/commit_and_push.md @@ -0,0 +1,66 @@ +# Commit and Push + +## Objective + +Review the changed files to verify they match the agent's expectations, create a commit with an appropriate message, and push to the remote repository. + +## Task + +Check the list of changed files against what was modified during this session, ensure they match expectations, then commit and push the changes. + +### Process + +1. **Get the list of changed files** + ```bash + git status + ``` + Also run `git diff --stat` to see a summary of changes. + +2. **Verify changes match expectations** + + Compare the changed files against what you modified during this session: + - Do the modified files match what you edited? + - Are there any unexpected new files? + - Are there any unexpected deleted files? + - Do the line counts seem reasonable for the changes you made? + + If changes match expectations, proceed to the next step. + + If there are unexpected changes: + - Investigate why (e.g., lint auto-fixes, generated files) + - If they're legitimate side effects of your work, include them + - If they're unrelated or shouldn't be committed, use `git restore` to discard them + +3. **Stage all appropriate changes** + ```bash + git add -A + ``` + Or stage specific files if some were excluded. + +4. **Create the commit** + + Generate an appropriate commit message based on the changes made. + + **IMPORTANT:** Use the commit job script (not `git commit` directly): + ```bash + [commit script path] -m "commit message here" + ``` + +5. **Push to remote** + ```bash + git push + ``` + If the branch has no upstream, use: + ```bash + git push -u origin HEAD + ``` + +## Quality Criteria + +- Changed files were verified against expectations +- Commit was created with appropriate message +- Changes were pushed to remote + +## Context + +This is the final step of the commit workflow. The agent verifies that the changed files match its own expectations from the work done during the session, then commits and pushes. This catches unexpected changes while avoiding unnecessary user interruptions. diff --git a/library/jobs/commit/steps/lint.md b/library/jobs/commit/steps/lint.md new file mode 100644 index 00000000..eb5989bd --- /dev/null +++ b/library/jobs/commit/steps/lint.md @@ -0,0 +1,41 @@ +# Lint Code + +## Objective + +Format and lint the codebase to ensure code quality and consistency. + +## Task + +Run the project's format and lint commands. This step should be executed using a sub-agent to conserve context in the main conversation. + +### Process + +**IMPORTANT**: Use the Task tool to spawn a sub-agent for this work. This saves context in the main conversation. Use the `haiku` model for speed. + +1. **Spawn a sub-agent to run linting** + + Use the Task tool with these parameters: + - `subagent_type`: "Bash" + - `model`: "haiku" + - `prompt`: Instruct the sub-agent to: + - Run the format command: `[format command]` + - Run the lint check command: `[lint check command]` + - Run lint check again to verify no remaining issues + - Report the results of each command + +2. **Review sub-agent results** + - Check that both format and check completed successfully + - Note any remaining lint issues that couldn't be auto-fixed + +3. **Handle remaining issues** + - If there are lint errors that couldn't be auto-fixed, fix them manually + - Re-run lint check to verify + +## Quality Criteria + +- Code was formatted +- Lint check passed with no errors + +## Context + +This step ensures code quality and consistency before committing. It runs after tests pass and before the commit step. Using a sub-agent keeps the main conversation context clean for the commit review. diff --git a/library/jobs/commit/steps/review.md b/library/jobs/commit/steps/review.md new file mode 100644 index 00000000..53e0f377 --- /dev/null +++ b/library/jobs/commit/steps/review.md @@ -0,0 +1,55 @@ +# Code Review + +## Objective + +Review changed code for quality issues before running tests. This catches problems early and ensures code meets quality standards. + +## Task + +Use a sub-agent to review the staged/changed code and identify issues that should be fixed before committing. + +### Process + +**IMPORTANT**: Use the Task tool to spawn a sub-agent for this review. This saves context in the main conversation. + +1. **Get the list of changed files** + ```bash + git diff --name-only HEAD + git diff --name-only --staged + ``` + Combine these to get all files that have been modified. + +2. **Spawn a sub-agent to review the code** + + Use the Task tool with these parameters: + - `subagent_type`: "general-purpose" + - `prompt`: Instruct the sub-agent to: + - Read the code review standards from `[code review standards path]` + - Read each of the changed files + - Review each file against the standards + - Report issues found with file, line number, severity, and suggested fix + +3. **Review sub-agent findings** + - Examine each issue identified + - Prioritize issues by severity + +4. **Fix identified issues** + - Address each issue found by the review + - For DRY violations: extract shared code into functions/modules + - For naming issues: rename to be clearer + - For missing tests: add appropriate test cases + - For bugs: fix the underlying issue + +5. **Re-run review if significant changes made** + - If you made substantial changes, consider running another review pass + - Ensure fixes didn't introduce new issues + +## Quality Criteria + +- Changed files were identified +- Code was reviewed against the project's code review standards +- All identified issues were addressed or documented as intentional + +## Context + +This is the first step of the commit workflow. Code review happens before tests to catch quality issues early. The sub-agent approach keeps the main conversation context clean while providing thorough review coverage. diff --git a/library/jobs/commit/steps/test.md b/library/jobs/commit/steps/test.md new file mode 100644 index 00000000..acc4e926 --- /dev/null +++ b/library/jobs/commit/steps/test.md @@ -0,0 +1,44 @@ +# Run Tests + +## Objective + +Run the project's test suite and fix any failing tests until all tests pass. + +## Task + +Execute the test suite for the project and iteratively fix any failures until all tests pass. + +### Process + +1. **Pull latest code from the branch** + - Run `git pull` to fetch and merge any changes from the remote + - If there are merge conflicts, resolve them before proceeding + - This ensures you're testing against the latest code + +2. **Run the test command** + ```bash + [test command] + ``` + Capture the output. + +3. **Analyze failures** + - If tests pass, proceed to output + - If tests fail, analyze the failure messages + - Identify the root cause of each failure + +4. **Fix failing tests** + - Make the necessary code changes to fix failures + - This may involve fixing bugs in implementation code or updating tests + - Re-run tests after each fix + +5. **Iterate until passing** + - Continue the fix/test cycle until all tests pass + +## Quality Criteria + +- Latest code was pulled from the branch +- All tests are passing + +## Context + +This step runs after code review. Tests must pass before proceeding to lint and commit. This ensures code quality and prevents broken code from being committed. If tests fail due to issues introduced by the code review fixes, iterate on the fixes until tests pass.