From 92a05f596199421d98c7afd8b0b21b6d6511eeeb Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 26 Jan 2026 20:35:01 +0000 Subject: [PATCH 01/11] feat: Add commit job to library Adds a generalized commit workflow job to the library that enforces quality checks before every commit through git commit interception. The job includes: - Code review step (DRY, naming, test coverage) - Test execution step - Lint/format step - Commit and push step The README explains: - Why git commit is hijacked (to enforce the workflow) - How to configure the settings.json PreToolUse hook - Required placeholder replacements for test/lint commands https://claude.ai/code/session_01MKARbdLAGS4xcAoNQiNzkn --- library/jobs/commit/job.yml | 96 ++++++++ library/jobs/commit/readme.md | 240 +++++++++++++++++++ library/jobs/commit/steps/commit_and_push.md | 77 ++++++ library/jobs/commit/steps/lint.md | 69 ++++++ library/jobs/commit/steps/review.md | 105 ++++++++ library/jobs/commit/steps/test.md | 54 +++++ 6 files changed, 641 insertions(+) create mode 100644 library/jobs/commit/job.yml create mode 100644 library/jobs/commit/readme.md create mode 100644 library/jobs/commit/steps/commit_and_push.md create mode 100644 library/jobs/commit/steps/lint.md create mode 100644 library/jobs/commit/steps/review.md create mode 100644 library/jobs/commit/steps/test.md diff --git a/library/jobs/commit/job.yml b/library/jobs/commit/job.yml new file mode 100644 index 00000000..fa9c20b3 --- /dev/null +++ b/library/jobs/commit/job.yml @@ -0,0 +1,96 @@ +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. + + This job 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 + +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: [] + 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`. + + - 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)" + 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`. + + - 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 + hooks: + after_agent: + - prompt: | + Verify the linting is complete: + 1. Format command was run successfully + 2. Lint check command was run successfully + 3. No remaining lint errors + If ALL criteria are met, include `✓ Quality Criteria Met`. + + - 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 + 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. Commit was created with appropriate message + 4. Changes were pushed to remote + If ALL criteria are met, include `✓ Quality Criteria Met`. diff --git a/library/jobs/commit/readme.md b/library/jobs/commit/readme.md new file mode 100644 index 00000000..e739487f --- /dev/null +++ b/library/jobs/commit/readme.md @@ -0,0 +1,240 @@ +# 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. + +**Examples:** +- Python: `pytest` or `uv run pytest` +- Node.js: `npm test` or `yarn test` +- Go: `go test ./...` +- Rust: `cargo test` + +### 2. Replace `[lint and format command]` + +In `steps/lint.md`, replace `[lint and format command]` with your project's formatting and linting commands. + +**Examples:** +- Python (ruff): `ruff format .` and `ruff check --fix .` +- Python (black/flake8): `black .` and `flake8 .` +- Node.js (prettier/eslint): `npx prettier --write .` and `npx eslint --fix .` +- Go: `go fmt ./...` and `golangci-lint run` +- Rust: `cargo fmt` and `cargo clippy` + +### 3. Replace `[commit script path]` + +In `steps/commit_and_push.md`, replace `[commit script path]` with the path to your commit wrapper script (see installation step 3 below). + +**Example:** `.claude/hooks/commit_job_git_commit.sh` + +## 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. Add the Hook Configuration to settings.json + +Add a PreToolUse hook to your `.claude/settings.json` that blocks `git commit` and redirects to the commit skill. This is the key mechanism that enforces the commit workflow. + +First, create the hook script at `.claude/hooks/block_bash_with_instructions.sh`: + +```bash +#!/bin/bash +# block_bash_with_instructions.sh - Blocks specific bash commands and provides alternative instructions + +set -e + +BLOCKED_COMMANDS=( + '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.' +) + +# 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 + pattern="${entry%%|||*}" + instructions="${entry##*|||}" + + if echo "${COMMAND}" | grep -qE "${pattern}"; then + cat << EOF +{"error": "${instructions}"} +EOF + exit 2 + fi +done + +exit 0 +``` + +Make it executable: +```bash +chmod +x .claude/hooks/block_bash_with_instructions.sh +``` + +Then add this to your `.claude/settings.json`: + +```json +{ + "hooks": { + "PreToolUse": [ + { + "matcher": "Bash", + "hooks": [ + { + "type": "command", + "command": ".claude/hooks/block_bash_with_instructions.sh" + } + ] + } + ] + } +} +``` + +### 3. Create the Commit Wrapper Script + +Create a wrapper script that the commit job will use to actually run `git commit`. This script bypasses the hook interception. + +Create `.claude/hooks/commit_job_git_commit.sh`: + +```bash +#!/bin/bash +# commit_job_git_commit.sh - Wrapper for git commit invoked via the /commit skill + +exec git commit "$@" +``` + +Make it executable: +```bash +chmod +x .claude/hooks/commit_job_git_commit.sh +``` + +### 4. Allow the Commit Script in Permissions + +Add the commit script to your allowed permissions in `.claude/settings.json`: + +```json +{ + "permissions": { + "allow": [ + "Bash(.claude/hooks/commit_job_git_commit.sh:*)" + ] + } +} +``` + +### 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 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..6bdd96ff --- /dev/null +++ b/library/jobs/commit/steps/commit_and_push.md @@ -0,0 +1,77 @@ +# 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. **View recent commit messages for style reference** + ```bash + git log --oneline -10 + ``` + +5. **Create the commit** + + Generate an appropriate commit message based on: + - The changes made + - The style of recent commits + - Conventional commit format if the project uses it + + **IMPORTANT:** Use the commit job script (not `git commit` directly): + ```bash + [commit script path] -m "commit message here" + ``` + +6. **Push to remote** + ```bash + git push + ``` + If the branch has no upstream, use: + ```bash + git push -u origin HEAD + ``` + +## 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) +- Commit message follows project conventions +- Commit was created successfully +- Changes were pushed to remote +- When all criteria are met, include `✓ Quality Criteria Met` in your response + +## 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..ec33c10a --- /dev/null +++ b/library/jobs/commit/steps/lint.md @@ -0,0 +1,69 @@ +# 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`: See below + + The sub-agent should: + + a. **Run the format command** + ```bash + [lint and format command] + ``` + This formats the code according to the project's style rules. + + b. **Run the lint check command** + ```bash + [lint and format command] + ``` + This checks for lint errors. + + c. **Run lint check again to verify** + Capture the final output to verify no remaining issues. + +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 + +## Example Sub-Agent Prompt + +``` +Run the lint and format commands for the codebase: + +1. Run: [lint and format command] +2. Run: [lint check command] +3. Verify no remaining issues + +Report the results of each command. +``` + +## Quality Criteria + +- Format command was run successfully +- Lint check was run successfully +- 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 + +## 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..618f20a4 --- /dev/null +++ b/library/jobs/commit/steps/review.md @@ -0,0 +1,105 @@ +# 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`: 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 + +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 + +## 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) +- 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 + +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..67486e8f --- /dev/null +++ b/library/jobs/commit/steps/test.md @@ -0,0 +1,54 @@ +# 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. **Detect or use the test command** + - If a test command was provided, use that + - Otherwise, use the configured test command: `[test command]` + - Common test commands by project type: + - Python: `pytest`, `python -m pytest`, `uv run pytest` + - Node.js: `npm test`, `yarn test`, `bun test` + - Go: `go test ./...` + - Rust: `cargo test` + - Check `package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod` for hints + +3. **Run the tests** + - Execute the test command + - Capture the output + +4. **Analyze failures** + - If tests pass, proceed to output + - If tests fail, analyze the failure messages + - Identify the root cause of each failure + +5. **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 + +6. **Iterate until passing** + - Continue the fix/test cycle until all tests pass + +## 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 + +## 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. From beda7f277eeb65647ccec9e59974a98a284bedae Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 26 Jan 2026 20:52:31 +0000 Subject: [PATCH 02/11] refactor: Externalize code review standards and simplify commit step - Remove "view recent commit messages" step from commit_and_push.md - Create code_review_standards.example.md with review criteria - Update review.md to reference [code review standards path] placeholder - Update README with instructions for code review standards replacement The code review standards are now externalized to a separate file that users can customize for their project's specific requirements. https://claude.ai/code/session_01MKARbdLAGS4xcAoNQiNzkn --- .../commit/code_review_standards.example.md | 57 +++++++++++++++++ library/jobs/commit/readme.md | 28 ++++++--- library/jobs/commit/steps/commit_and_push.md | 14 +---- library/jobs/commit/steps/review.md | 63 +++++++------------ 4 files changed, 103 insertions(+), 59 deletions(-) create mode 100644 library/jobs/commit/code_review_standards.example.md 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..add7b0e3 --- /dev/null +++ b/library/jobs/commit/code_review_standards.example.md @@ -0,0 +1,57 @@ +# 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 + +## 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/readme.md b/library/jobs/commit/readme.md index e739487f..4c582be3 100644 --- a/library/jobs/commit/readme.md +++ b/library/jobs/commit/readme.md @@ -52,9 +52,23 @@ In `steps/lint.md`, replace `[lint and format command]` with your project's form - Go: `go fmt ./...` and `golangci-lint run` - Rust: `cargo fmt` and `cargo clippy` -### 3. Replace `[commit script path]` +### 3. Replace `[code review standards path]` -In `steps/commit_and_push.md`, replace `[commit script path]` with the path to your commit wrapper script (see installation step 3 below). +In `steps/review.md`, replace `[code review standards path]` with the path to your project's code review standards file. + +**Example:** `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. + +### 4. Replace `[commit script path]` + +In `steps/commit_and_push.md`, replace `[commit script path]` with the path to your commit wrapper script (see installation step 4 below). **Example:** `.claude/hooks/commit_job_git_commit.sh` @@ -152,7 +166,7 @@ Then add this to your `.claude/settings.json`: } ``` -### 3. Create the Commit Wrapper Script +### 4. Create the Commit Wrapper Script Create a wrapper script that the commit job will use to actually run `git commit`. This script bypasses the hook interception. @@ -170,7 +184,7 @@ Make it executable: chmod +x .claude/hooks/commit_job_git_commit.sh ``` -### 4. Allow the Commit Script in Permissions +### 5. Allow the Commit Script in Permissions Add the commit script to your allowed permissions in `.claude/settings.json`: @@ -184,11 +198,11 @@ Add the commit script to your allowed permissions in `.claude/settings.json`: } ``` -### 5. Customize the Placeholders +### 6. Customize the Placeholders Replace all placeholders in the step files as described in the "Required Customization" section above. -### 6. Sync the Skills +### 7. Sync the Skills Run `deepwork sync` to generate the slash commands for your AI coding assistant. @@ -196,7 +210,7 @@ Run `deepwork sync` to generate the slash commands for your AI coding assistant. ### 1. Code Review (`/commit.review`) -Uses a sub-agent to review changed files for: +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) diff --git a/library/jobs/commit/steps/commit_and_push.md b/library/jobs/commit/steps/commit_and_push.md index 6bdd96ff..bec1ca66 100644 --- a/library/jobs/commit/steps/commit_and_push.md +++ b/library/jobs/commit/steps/commit_and_push.md @@ -37,24 +37,16 @@ Check the list of changed files against what was modified during this session, e ``` Or stage specific files if some were excluded. -4. **View recent commit messages for style reference** - ```bash - git log --oneline -10 - ``` - -5. **Create the commit** +4. **Create the commit** - Generate an appropriate commit message based on: - - The changes made - - The style of recent commits - - Conventional commit format if the project uses it + 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" ``` -6. **Push to remote** +5. **Push to remote** ```bash git push ``` diff --git a/library/jobs/commit/steps/review.md b/library/jobs/commit/steps/review.md index 618f20a4..3fb8adf3 100644 --- a/library/jobs/commit/steps/review.md +++ b/library/jobs/commit/steps/review.md @@ -19,72 +19,53 @@ Use a sub-agent to review the staged/changed code and identify issues that shoul ``` Combine these to get all files that have been modified. -2. **Spawn a sub-agent to review the code** +2. **Read the code review standards** + + First, read the project's code review standards file: + ``` + [code review standards path] + ``` + +3. **Spawn a sub-agent to review the code** 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 - -3. **Review sub-agent findings** + - `prompt`: Include the list of changed files and the review standards from the file above + + The sub-agent should review each changed file against the standards defined in your project's code review standards file. + +4. **Review sub-agent findings** - Examine each issue identified - Prioritize issues by severity -4. **Fix identified issues** +5. **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** +6. **Re-run review if significant changes made** - 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: +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? +Use the code review standards defined in [code review standards path]. -Read each file and provide a structured report of issues found, organized by category. +Read each file and provide a structured report of issues found, organized by the categories in the standards file. For each issue, include: - File and line number +- Severity level +- Category - Description of the issue - Suggested fix @@ -94,8 +75,8 @@ 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) +- Code review standards file was read +- Sub-agent reviewed all changed files against the standards - 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 From efdbbd8041167f7aa0a39ca7bf8f43509316e470 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 26 Jan 2026 21:16:06 +0000 Subject: [PATCH 03/11] refactor: Simplify step instructions and extract placeholders - Update review.md to have sub-agent read code review standards (not main agent) - Remove example sub-agent prompt from review.md - Remove language-specific test command examples from test.md - Split [lint and format command] into [format command] and [lint check command] - Remove example sub-agent prompt from lint.md - Update README with new placeholder descriptions https://claude.ai/code/session_01MKARbdLAGS4xcAoNQiNzkn --- library/jobs/commit/readme.md | 39 ++++++++--------------- library/jobs/commit/steps/lint.md | 35 +++------------------ library/jobs/commit/steps/review.md | 49 ++++++----------------------- library/jobs/commit/steps/test.md | 28 ++++++----------- 4 files changed, 38 insertions(+), 113 deletions(-) diff --git a/library/jobs/commit/readme.md b/library/jobs/commit/readme.md index 4c582be3..41ebc6b9 100644 --- a/library/jobs/commit/readme.md +++ b/library/jobs/commit/readme.md @@ -33,30 +33,19 @@ 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. +In `steps/test.md`, replace `[test command]` with your project's test command (e.g., `pytest`, `npm test`, `go test ./...`). -**Examples:** -- Python: `pytest` or `uv run pytest` -- Node.js: `npm test` or `yarn test` -- Go: `go test ./...` -- Rust: `cargo test` +### 2. Replace `[format command]` -### 2. Replace `[lint and 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 ./...`). -In `steps/lint.md`, replace `[lint and format command]` with your project's formatting and linting commands. +### 3. Replace `[lint check command]` -**Examples:** -- Python (ruff): `ruff format .` and `ruff check --fix .` -- Python (black/flake8): `black .` and `flake8 .` -- Node.js (prettier/eslint): `npx prettier --write .` and `npx eslint --fix .` -- Go: `go fmt ./...` and `golangci-lint run` -- Rust: `cargo fmt` and `cargo clippy` +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`). -### 3. Replace `[code review standards path]` +### 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. - -**Example:** `docs/code_review_standards.md` +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: @@ -66,11 +55,9 @@ cp library/jobs/commit/code_review_standards.example.md docs/code_review_standar Then customize `docs/code_review_standards.md` to match your project's specific requirements, coding style, and quality expectations. -### 4. Replace `[commit script path]` - -In `steps/commit_and_push.md`, replace `[commit script path]` with the path to your commit wrapper script (see installation step 4 below). +### 5. Replace `[commit script path]` -**Example:** `.claude/hooks/commit_job_git_commit.sh` +In `steps/commit_and_push.md`, replace `[commit script path]` with the path to your commit wrapper script (e.g., `.claude/hooks/commit_job_git_commit.sh`). See installation step 3 below for how to create this script. ## Installation @@ -166,7 +153,7 @@ Then add this to your `.claude/settings.json`: } ``` -### 4. Create the Commit Wrapper Script +### 3. Create the Commit Wrapper Script Create a wrapper script that the commit job will use to actually run `git commit`. This script bypasses the hook interception. @@ -184,7 +171,7 @@ Make it executable: chmod +x .claude/hooks/commit_job_git_commit.sh ``` -### 5. Allow the Commit Script in Permissions +### 4. Allow the Commit Script in Permissions Add the commit script to your allowed permissions in `.claude/settings.json`: @@ -198,11 +185,11 @@ Add the commit script to your allowed permissions in `.claude/settings.json`: } ``` -### 6. Customize the Placeholders +### 5. Customize the Placeholders Replace all placeholders in the step files as described in the "Required Customization" section above. -### 7. Sync the Skills +### 6. Sync the Skills Run `deepwork sync` to generate the slash commands for your AI coding assistant. diff --git a/library/jobs/commit/steps/lint.md b/library/jobs/commit/steps/lint.md index ec33c10a..d99dbdf2 100644 --- a/library/jobs/commit/steps/lint.md +++ b/library/jobs/commit/steps/lint.md @@ -17,24 +17,11 @@ Run the project's format and lint commands. This step should be executed using a Use the Task tool with these parameters: - `subagent_type`: "Bash" - `model`: "haiku" - - `prompt`: See below - - The sub-agent should: - - a. **Run the format command** - ```bash - [lint and format command] - ``` - This formats the code according to the project's style rules. - - b. **Run the lint check command** - ```bash - [lint and format command] - ``` - This checks for lint errors. - - c. **Run lint check again to verify** - Capture the final output to verify no remaining issues. + - `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 @@ -44,18 +31,6 @@ Run the project's format and lint commands. This step should be executed using a - If there are lint errors that couldn't be auto-fixed, fix them manually - Re-run lint check to verify -## Example Sub-Agent Prompt - -``` -Run the lint and format commands for the codebase: - -1. Run: [lint and format command] -2. Run: [lint check command] -3. Verify no remaining issues - -Report the results of each command. -``` - ## Quality Criteria - Format command was run successfully diff --git a/library/jobs/commit/steps/review.md b/library/jobs/commit/steps/review.md index 3fb8adf3..445d7c86 100644 --- a/library/jobs/commit/steps/review.md +++ b/library/jobs/commit/steps/review.md @@ -19,64 +19,35 @@ Use a sub-agent to review the staged/changed code and identify issues that shoul ``` Combine these to get all files that have been modified. -2. **Read the code review standards** - - First, read the project's code review standards file: - ``` - [code review standards path] - ``` - -3. **Spawn a sub-agent to review the code** +2. **Spawn a sub-agent to review the code** Use the Task tool with these parameters: - `subagent_type`: "general-purpose" - - `prompt`: Include the list of changed files and the review standards from the file above - - The sub-agent should review each changed file against the standards defined in your project's code review standards file. + - `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 -4. **Review sub-agent findings** +3. **Review sub-agent findings** - Examine each issue identified - Prioritize issues by severity -5. **Fix identified issues** +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 -6. **Re-run review if significant changes made** +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 -## 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 - -Use the code review standards defined in [code review standards path]. - -Read each file and provide a structured report of issues found, organized by the categories in the standards file. -For each issue, include: -- File and line number -- Severity level -- Category -- Description of the issue -- Suggested fix - -If no issues are found in a category, state that explicitly. -``` - ## Quality Criteria - Changed files were identified -- Code review standards file was read -- Sub-agent reviewed all changed files against the standards +- 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 diff --git a/library/jobs/commit/steps/test.md b/library/jobs/commit/steps/test.md index 67486e8f..f37e4dff 100644 --- a/library/jobs/commit/steps/test.md +++ b/library/jobs/commit/steps/test.md @@ -15,37 +15,29 @@ Execute the test suite for the project and iteratively fix any failures until al - If there are merge conflicts, resolve them before proceeding - This ensures you're testing against the latest code -2. **Detect or use the test command** - - If a test command was provided, use that - - Otherwise, use the configured test command: `[test command]` - - Common test commands by project type: - - Python: `pytest`, `python -m pytest`, `uv run pytest` - - Node.js: `npm test`, `yarn test`, `bun test` - - Go: `go test ./...` - - Rust: `cargo test` - - Check `package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod` for hints - -3. **Run the tests** - - Execute the test command - - Capture the output - -4. **Analyze failures** +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 -5. **Fix failing tests** +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 -6. **Iterate until passing** +5. **Iterate until passing** - Continue the fix/test cycle until all tests pass ## Quality Criteria - Latest code was pulled from the branch -- Test command was correctly identified or used from input +- Test command was run - All tests are now passing - When all criteria are met, include `✓ Quality Criteria Met` in your response From 036536970a15fb12a3318b4d59130e74701727a3 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 26 Jan 2026 21:16:55 +0000 Subject: [PATCH 04/11] fix: Update commit script example path to .deepwork/jobs/commit/ https://claude.ai/code/session_01MKARbdLAGS4xcAoNQiNzkn --- library/jobs/commit/readme.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/library/jobs/commit/readme.md b/library/jobs/commit/readme.md index 41ebc6b9..19a3e061 100644 --- a/library/jobs/commit/readme.md +++ b/library/jobs/commit/readme.md @@ -57,7 +57,7 @@ Then customize `docs/code_review_standards.md` to match your project's specific ### 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., `.claude/hooks/commit_job_git_commit.sh`). See installation step 3 below for how to create this script. +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 @@ -157,7 +157,7 @@ Then add this to your `.claude/settings.json`: Create a wrapper script that the commit job will use to actually run `git commit`. This script bypasses the hook interception. -Create `.claude/hooks/commit_job_git_commit.sh`: +Create `.deepwork/jobs/commit/commit_job_git_commit.sh`: ```bash #!/bin/bash @@ -168,7 +168,7 @@ exec git commit "$@" Make it executable: ```bash -chmod +x .claude/hooks/commit_job_git_commit.sh +chmod +x .deepwork/jobs/commit/commit_job_git_commit.sh ``` ### 4. Allow the Commit Script in Permissions @@ -179,7 +179,7 @@ Add the commit script to your allowed permissions in `.claude/settings.json`: { "permissions": { "allow": [ - "Bash(.claude/hooks/commit_job_git_commit.sh:*)" + "Bash(.deepwork/jobs/commit/commit_job_git_commit.sh:*)" ] } } From cb606d7cb0d4bffa49eaa57ec69374d71577ae7d Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 26 Jan 2026 21:18:23 +0000 Subject: [PATCH 05/11] feat: Include commit wrapper script in job folder Add commit_job_git_commit.sh to the job folder so users can just copy it rather than creating from scratch. Update README instructions. https://claude.ai/code/session_01MKARbdLAGS4xcAoNQiNzkn --- library/jobs/commit/commit_job_git_commit.sh | 7 +++++++ library/jobs/commit/readme.md | 14 ++------------ 2 files changed, 9 insertions(+), 12 deletions(-) create mode 100755 library/jobs/commit/commit_job_git_commit.sh 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/readme.md b/library/jobs/commit/readme.md index 19a3e061..af1b5fb0 100644 --- a/library/jobs/commit/readme.md +++ b/library/jobs/commit/readme.md @@ -153,20 +153,10 @@ Then add this to your `.claude/settings.json`: } ``` -### 3. Create the Commit Wrapper Script +### 3. Make the Commit Wrapper Script Executable -Create a wrapper script that the commit job will use to actually run `git commit`. This script bypasses the hook interception. +The job includes a `commit_job_git_commit.sh` script that bypasses the hook interception. Make it executable: -Create `.deepwork/jobs/commit/commit_job_git_commit.sh`: - -```bash -#!/bin/bash -# commit_job_git_commit.sh - Wrapper for git commit invoked via the /commit skill - -exec git commit "$@" -``` - -Make it executable: ```bash chmod +x .deepwork/jobs/commit/commit_job_git_commit.sh ``` From 13172b88f0976886cfe15c7f6189f2b6627a75d8 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 26 Jan 2026 21:25:12 +0000 Subject: [PATCH 06/11] refactor: Switch to quality_criteria and remove redundant criteria - Replace after_agent hooks with quality_criteria in job.yml - Remove "Sub-agent was used to conserve context" (implementation detail) - Remove "Test command was run" (redundant with "tests passing") - Remove promise tags from step files (handled by framework) - Simplify and align criteria between job.yml and step files https://claude.ai/code/session_01MKARbdLAGS4xcAoNQiNzkn --- library/jobs/commit/job.yml | 52 ++++++-------------- library/jobs/commit/steps/commit_and_push.md | 7 +-- library/jobs/commit/steps/lint.md | 7 +-- library/jobs/commit/steps/review.md | 4 +- library/jobs/commit/steps/test.md | 4 +- 5 files changed, 21 insertions(+), 53 deletions(-) diff --git a/library/jobs/commit/job.yml b/library/jobs/commit/job.yml index fa9c20b3..c5975abc 100644 --- a/library/jobs/commit/job.yml +++ b/library/jobs/commit/job.yml @@ -28,35 +28,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" + - "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: - - 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" @@ -67,14 +55,9 @@ steps: - code_formatted # implicit state: code formatted and linted dependencies: - test - hooks: - after_agent: - - prompt: | - Verify the linting is complete: - 1. Format command was run successfully - 2. Lint check command was run successfully - 3. No remaining lint errors - If ALL criteria are met, include `✓ Quality Criteria Met`. + quality_criteria: + - "Code was formatted" + - "Lint check passed with no errors" - id: commit_and_push name: "Commit and Push" @@ -85,12 +68,7 @@ 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. Commit was created with appropriate message - 4. Changes were pushed to remote - If ALL criteria are met, include `✓ Quality Criteria Met`. + 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/steps/commit_and_push.md b/library/jobs/commit/steps/commit_and_push.md index bec1ca66..565c4877 100644 --- a/library/jobs/commit/steps/commit_and_push.md +++ b/library/jobs/commit/steps/commit_and_push.md @@ -57,12 +57,9 @@ 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) -- Commit message follows project conventions -- Commit was created successfully +- Changed files were verified against expectations +- 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/library/jobs/commit/steps/lint.md b/library/jobs/commit/steps/lint.md index d99dbdf2..eb5989bd 100644 --- a/library/jobs/commit/steps/lint.md +++ b/library/jobs/commit/steps/lint.md @@ -33,11 +33,8 @@ Run the project's format and lint commands. This step should be executed using a ## Quality Criteria -- Format command was run successfully -- Lint check was run successfully -- 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 +- Code was formatted +- Lint check passed with no errors ## Context diff --git a/library/jobs/commit/steps/review.md b/library/jobs/commit/steps/review.md index 445d7c86..53e0f377 100644 --- a/library/jobs/commit/steps/review.md +++ b/library/jobs/commit/steps/review.md @@ -47,10 +47,8 @@ Use a sub-agent to review the staged/changed code and identify issues that shoul ## Quality Criteria - Changed files were identified -- Sub-agent read the code review standards and reviewed all changed files +- Code was reviewed against the project's code review standards - 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/library/jobs/commit/steps/test.md b/library/jobs/commit/steps/test.md index f37e4dff..acc4e926 100644 --- a/library/jobs/commit/steps/test.md +++ b/library/jobs/commit/steps/test.md @@ -37,9 +37,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 run -- All tests are now passing -- When all criteria are met, include `✓ Quality Criteria Met` in your response +- All tests are passing ## Context From 5aa48e702ffff6b50ed9c6a881a2065f5845ab9b Mon Sep 17 00:00:00 2001 From: Noah Horton Date: Mon, 26 Jan 2026 16:10:57 -0700 Subject: [PATCH 07/11] refactor: Update commit job to use quality_criteria format (#168) - Replace hooks.after_agent.prompt with quality_criteria in job.yml - Simplify quality criteria in step files (remove instructions) - Align with library/jobs/commit structure while keeping project-specific customizations (ruff, CHANGELOG guidance) https://claude.ai/code/session_01JfPmbjHD1JaRV95DY83nUr Co-authored-by: Claude --- .deepwork/jobs/commit/job.yml | 61 +++++++------------ .../jobs/commit/steps/commit_and_push.md | 11 ++-- .deepwork/jobs/commit/steps/lint.md | 4 +- .deepwork/jobs/commit/steps/review.md | 5 +- .deepwork/jobs/commit/steps/test.md | 4 +- 5 files changed, 28 insertions(+), 57 deletions(-) diff --git a/.deepwork/jobs/commit/job.yml b/.deepwork/jobs/commit/job.yml index 445640df..0a304b97 100644 --- a/.deepwork/jobs/commit/job.yml +++ b/.deepwork/jobs/commit/job.yml @@ -1,5 +1,5 @@ name: commit -version: "1.4.0" +version: "1.5.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. @@ -16,6 +16,8 @@ description: | 4. commit_and_push - Review changes and commit/push changelog: + - version: "1.5.0" + changes: "Switched from hooks.after_agent to quality_criteria for cleaner step validation" - version: "1.4.0" changes: "Added changelog guidance: entries must go in [Unreleased] section, NEVER modify version numbers in pyproject.toml or CHANGELOG.md" - version: "1.3.0" @@ -38,35 +40,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" @@ -77,14 +67,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" @@ -95,14 +81,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..06366b1d 100644 --- a/.deepwork/jobs/commit/steps/review.md +++ b/.deepwork/jobs/commit/steps/review.md @@ -94,11 +94,8 @@ 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 reviewed the code for general issues, DRY opportunities, naming clarity, and test coverage - 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 From 732e0c369b154a451d38cbef2b107b090707b6c6 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 26 Jan 2026 23:13:26 +0000 Subject: [PATCH 08/11] feat: Include block_bash_with_instructions.sh in job folder Add the git commit blocker hook script to the job folder so users can copy it during installation. Simplified README installation instructions to reference the included scripts rather than inline code. https://claude.ai/code/session_01MKARbdLAGS4xcAoNQiNzkn --- .../commit/block_bash_with_instructions.sh | 76 ++++++++++++++ library/jobs/commit/readme.md | 99 ++++--------------- 2 files changed, 97 insertions(+), 78 deletions(-) create mode 100755 library/jobs/commit/block_bash_with_instructions.sh 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..387a0979 --- /dev/null +++ b/library/jobs/commit/block_bash_with_instructions.sh @@ -0,0 +1,76 @@ +#!/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 (stdout): JSON response with error message if blocked +# 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=( + '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 as JSON + cat << EOF +{"error": "${instructions}"} +EOF + exit 2 + fi +done + +# Command is allowed +exit 0 diff --git a/library/jobs/commit/readme.md b/library/jobs/commit/readme.md index af1b5fb0..fd067a1d 100644 --- a/library/jobs/commit/readme.md +++ b/library/jobs/commit/readme.md @@ -69,74 +69,35 @@ Copy this entire `commit` folder to your project's `.deepwork/jobs/` directory: cp -r library/jobs/commit .deepwork/jobs/ ``` -### 2. Add the Hook Configuration to settings.json +### 2. Install the Git Commit Blocker Hook -Add a PreToolUse hook to your `.claude/settings.json` that blocks `git commit` and redirects to the commit skill. This is the key mechanism that enforces the commit workflow. - -First, create the hook script at `.claude/hooks/block_bash_with_instructions.sh`: +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 -#!/bin/bash -# block_bash_with_instructions.sh - Blocks specific bash commands and provides alternative instructions - -set -e - -BLOCKED_COMMANDS=( - '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.' -) - -# 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 - pattern="${entry%%|||*}" - instructions="${entry##*|||}" - - if echo "${COMMAND}" | grep -qE "${pattern}"; then - cat << EOF -{"error": "${instructions}"} -EOF - exit 2 - fi -done - -exit 0 +mkdir -p .claude/hooks +cp .deepwork/jobs/commit/block_bash_with_instructions.sh .claude/hooks/ +chmod +x .claude/hooks/block_bash_with_instructions.sh ``` -Make it executable: +### 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 .claude/hooks/block_bash_with_instructions.sh +chmod +x .deepwork/jobs/commit/commit_job_git_commit.sh ``` -Then add this to your `.claude/settings.json`: +### 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": [ { @@ -153,27 +114,9 @@ Then add this to your `.claude/settings.json`: } ``` -### 3. Make the Commit Wrapper Script Executable - -The job includes a `commit_job_git_commit.sh` script that bypasses the hook interception. Make it executable: - -```bash -chmod +x .deepwork/jobs/commit/commit_job_git_commit.sh -``` - -### 4. Allow the Commit Script in Permissions - -Add the commit script to your allowed permissions in `.claude/settings.json`: - -```json -{ - "permissions": { - "allow": [ - "Bash(.deepwork/jobs/commit/commit_job_git_commit.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 From 980a458ad737ea4e0c913926eaf531ca200737e8 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 27 Jan 2026 01:22:13 +0000 Subject: [PATCH 09/11] feat: Add workflows section to library commit job - Add workflows section with 'full' workflow defining step sequence - Update block_bash_with_instructions.sh to output to stderr (matches upstream) - Improve regex pattern to anchor at start of command https://claude.ai/code/session_01MKARbdLAGS4xcAoNQiNzkn --- library/jobs/commit/block_bash_with_instructions.sh | 10 ++++------ library/jobs/commit/job.yml | 11 ++++++++++- 2 files changed, 14 insertions(+), 7 deletions(-) diff --git a/library/jobs/commit/block_bash_with_instructions.sh b/library/jobs/commit/block_bash_with_instructions.sh index 387a0979..7bd16f88 100755 --- a/library/jobs/commit/block_bash_with_instructions.sh +++ b/library/jobs/commit/block_bash_with_instructions.sh @@ -7,7 +7,7 @@ # 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 (stdout): JSON response with error message if blocked +# 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) @@ -22,7 +22,7 @@ set -e # Add new blocked commands here: BLOCKED_COMMANDS=( - '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.' + '^[[: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.' ) # ============================================================================= @@ -64,10 +64,8 @@ for entry in "${BLOCKED_COMMANDS[@]}"; do # Check if command matches pattern (using extended regex) if echo "${COMMAND}" | grep -qE "${pattern}"; then - # Output error message as JSON - cat << EOF -{"error": "${instructions}"} -EOF + # Output error message to stderr (Claude Code reads stderr for exit code 2) + echo "${instructions}" >&2 exit 2 fi done diff --git a/library/jobs/commit/job.yml b/library/jobs/commit/job.yml index c5975abc..ebf4575c 100644 --- a/library/jobs/commit/job.yml +++ b/library/jobs/commit/job.yml @@ -4,7 +4,7 @@ summary: "Reviews code, runs tests, lints, and commits changes. Use when ready t description: | A workflow for preparing and committing code changes with quality checks. - This job starts with a code review to catch issues early, runs tests until + 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. @@ -15,6 +15,15 @@ description: | 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" From 28e3b1246be63bb5e518687dc2768a2f9a52f398 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 27 Jan 2026 01:22:50 +0000 Subject: [PATCH 10/11] docs: Add workflows and quality_criteria to library README Document the new job.yml schema fields: - workflows: Named sequences of steps - quality_criteria: Measurable criteria for step completion https://claude.ai/code/session_01MKARbdLAGS4xcAoNQiNzkn --- library/jobs/README.md | 5 +++++ 1 file changed, 5 insertions(+) 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/ From f55505b91390ce67df626b12ab522a29d2b13ec0 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 27 Jan 2026 01:59:21 +0000 Subject: [PATCH 11/11] feat: Add test quality criteria and externalize code review standards - Add "Test Quality" section to code_review_standards.example.md - Tests should add value and verify distinct behaviors - Tests should not be duplicative of each other - Copy code review standards to doc/code_review_standards.md - Update .deepwork review.md to reference doc file instead of inline criteria https://claude.ai/code/session_01MKARbdLAGS4xcAoNQiNzkn --- .deepwork/jobs/commit/steps/review.md | 59 ++-------------- doc/code_review_standards.md | 67 +++++++++++++++++++ .../commit/code_review_standards.example.md | 10 +++ 3 files changed, 83 insertions(+), 53 deletions(-) create mode 100644 doc/code_review_standards.md diff --git a/.deepwork/jobs/commit/steps/review.md b/.deepwork/jobs/commit/steps/review.md index 06366b1d..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,36 +44,10 @@ 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 the code for general issues, DRY opportunities, naming clarity, and test coverage +- Sub-agent read the code review standards and reviewed all changed files - All identified issues were addressed or documented as intentional ## 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/commit/code_review_standards.example.md b/library/jobs/commit/code_review_standards.example.md index add7b0e3..3761c354 100644 --- a/library/jobs/commit/code_review_standards.example.md +++ b/library/jobs/commit/code_review_standards.example.md @@ -38,6 +38,16 @@ Verify: - 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: