RCP-CWK-015 Cowork Git-Aware File Reviewer

Validates file revisions using git diff instead of manual file comparison

Validates file revisions using git diff instead of manual file comparison. Compares file versions across commits, understands change intent from the commit message, runs CRAFT-specific structural checks, classifies severity, and supports three review modes including a blocking mode that halts commits with critical issues.

Cowork Git-Aware File Reviewer

Cowork | QA & Validation | Difficulty: Medium | Time: 1–5 min (auto), 5–15 min (full)
Tags: Introduced in Beta, Git, Review, Diff, Commit, Validation, Structure, CRAFT, QA, Cowork

TL;DR

What It Does
Validates file revisions using git diff instead of manual file comparison. Compares file versions across commits, understands change intent from the commit message, runs CRAFT-specific structural checks, classifies severity, and supports three review modes including a blocking mode that halts commits with critical issues.
How It Works
The AI retrieves the git diff between a reference commit and HEAD, then runs a six-step analysis. It compares section structures before and after, classifies each change as aligned with commit intent, unaligned (potentially accidental), or collateral (a reasonable side effect). When CRAFT mode is enabled, it runs additional checks: version alignment, recipe structure integrity, master index consistency, cross-reference integrity, recipe ID format compliance, and section completeness. Findings are classified as CRITICAL, WARNING, or INFO, and the output format depends on the review mode.
What To Expect
In auto mode (called by CWK-005 after each commit), you see nothing on clean commits — only critical and warning findings are reported. In full mode, you get a comprehensive review report with an approval workflow. In blocking mode, critical findings halt the commit and require resolution before proceeding.
Best Results When You
Write descriptive commit messages — the recipe uses them to assess whether changes align with stated intent. Vague messages like “updates” make intent alignment analysis less effective. Use blocking mode for critical files like cookbooks and CLAUDE.md.
Typical Time
1–5 minutes in auto mode. 5–15 minutes in full mode depending on diff size. Diffs over 500 lines switch to summary mode automatically.
Difficulty
Medium — auto mode runs without interaction. Full mode requires you to choose an approval action (approve, approve with notes, fix forward, or revert). Blocking mode requires resolving critical issues before the commit proceeds.

How To Start

The file reviewer integrates with CWK-005 (git checkpoint) for automatic post-commit reviews. You can also run it standalone.

STEP 1Specify the Review Scope

Tell the AI which commit to compare against and which review mode to use, or let CWK-005 trigger it automatically.
Available parameters
  • commit_ref · string · optional · default: HEAD~1
    Git ref to compare against HEAD. Can be a commit hash, branch name, or relative ref like HEAD~3.
  • review_mode · string · optional · default: auto
    Review thoroughness. Options: “auto” (abbreviated, CWK-005 integration — silent on clean commits), “full” (comprehensive with approval workflow), “blocking” (halts on CRITICAL findings in critical files).
  • craft_mode · boolean · optional · default: true
    Enable CRAFT-specific validation checks: recipe structure, version alignment, master index consistency, cross-reference integrity, recipe ID format. Set false for non-CRAFT files.
Invocations
Auto Mode (CWK-005 Post-Commit)
#H->AI::Directive: (Execute Git-Aware File Review)
Full Standalone Review
#H->AI::Directive: (Execute Git-Aware File Review with review_mode=full)
Blocking Mode for Critical Files
#H->AI::Directive: (Execute Git-Aware File Review with review_mode=blocking)

Usage Examples

Three scenarios — auto mode catching an unaligned change, full mode with an approval decision, and blocking mode halting a commit.
Example 1 · Auto mode catches unaligned change
AI: Post-commit review found 1 WARNING in commit a3f29bc: Unaligned change — section “Active Cookbooks” in CLAUDE.md was modified but commit message only references “Updated LL file.” Non-blocking — review when convenient.
Example 2 · Full mode with approval workflow
User: Run a full review of the last 3 commits.
AI: Git-Aware File Review Report. Commit range: HEAD~3..HEAD. Files changed: 4. Insertions: 87, Deletions: 12. CRITICAL (1): Master index total_recipes count (127) does not match actual recipe count (128) in cookbook file. WARNING (1): Recipe RCP-CWK-049 ID format uses lowercase “v” instead of uppercase. INFO (2): Expected collateral — recipe count updated in CLAUDE.md, whitespace normalization in 2 files. Approval options: A) Approve, B) Approve with notes, C) Fix forward, D) Revert.
User: C — fix forward.
AI: Creating corrective commit for master index count mismatch.
Example 3 · Blocking mode halts a commit
AI: BLOCKING REVIEW: 1 CRITICAL issue in commit 7e4d1a2. Version regression detected — cookbook header says v3.01a but metadata says v3.00a. COMMIT BLOCKED. Resolve before proceeding.

How AI Reads This Recipe

When this recipe is triggered, the AI runs a 6-step git-based revision validation pipeline. The AI should:
  1. RETRIEVE the git diff: run git log for commit hash and message (the message serves as intent context), git diff –stat for summary, and git diff for full content. If no changes exist, return silently in auto mode or report “no changes” in other modes.
  2. ANALYZE structure: for each changed CRAFT file, compare section headers between the before and after versions. Flag removed sections as CRITICAL. Track added sections as informational.
  3. CLASSIFY changes against commit intent: parse the commit message for action verbs and targets. Classify each diff hunk as ALIGNED (matches intent), UNALIGNED (not in stated scope — potentially accidental), or COLLATERAL (reasonable side effect like updating counts). Flag unaligned changes for review.
  4. RUN CRAFT-specific checks when craft_mode is true: version alignment (header vs. metadata — CRITICAL if mismatched), recipe structure (required fields — WARNING if missing), master index consistency (counts match actuals — CRITICAL if off), cross-reference integrity (dependency_map and used_by reciprocal — WARNING if broken), recipe ID format (RCP-CWK-NNN pattern — WARNING if non-compliant), section completeness (all required sections present — CRITICAL if missing).
  5. CLASSIFY severity: aggregate findings into CRITICAL (must fix), WARNING (review needed), and INFO (neutral observations).
  6. REPORT based on review mode. AUTO: silent on clean, report only CRITICAL and WARNING. BLOCKING: return BLOCK status on CRITICAL findings — the commit must be reverted or fixed. FULL: produce comprehensive report with all severity levels, intent alignment analysis, and four approval options (approve, approve with notes, fix forward, revert).
In auto mode, silence means the commit is clean — do not produce output for passing reviews. In blocking mode, only CRITICAL findings trigger a block; warnings are allowed through. For large diffs (over 500 lines), switch to summary mode — review structural changes and CRAFT checks only. If no git repo exists, direct the user to CWK-004.

When to Use This Recipe

Use this recipe when you:
  • Want automatic post-commit validation of CRAFT file changes integrated with your git workflow.
  • Need to verify that commit changes align with stated intent and no accidental modifications slipped in.
  • Are modifying critical files (cookbooks, CLAUDE.md, roadmap) and want blocking validation before the commit proceeds.
  • Want CRAFT-specific structural checks (version alignment, index consistency, cross-references) run automatically on every commit.
Do not use this recipe when:
You are making a quick one-line typo fix and running a full review is disproportionate to the change. Auto mode handles this correctly — it stays silent on clean commits. Do not use full or blocking mode for trivial changes unless they touch critical files.

Recipe FAQ

Q.What are the three review modes?

Auto: abbreviated, CWK-005 integration — silent on clean commits, reports only CRITICAL and WARNING findings. Full: comprehensive standalone review with all severity levels, intent alignment analysis, and a four-option approval workflow. Blocking: same analysis as auto but returns BLOCK status on CRITICAL findings — the commit must be resolved before proceeding.

Q.What CRAFT-specific checks does this recipe run?

Six checks: version alignment (header vs. metadata), recipe structure (required fields present), master index consistency (counts match actuals), cross-reference integrity (dependency_map and used_by are reciprocal), recipe ID format compliance, and section completeness (all required cookbook sections present).

Q.What change classifications does the intent analysis use?

Three: ALIGNED (change matches commit message intent), UNALIGNED (change not in stated scope — potentially accidental), COLLATERAL (reasonable side effect like updating counts after adding a recipe). Unaligned changes are flagged for review.

Q.Which files trigger blocking mode?

Four critical file patterns: cookbook files (CFT-FWK-COOKBK-*), chat history files (AI-CHAT-HISTORY-*), CLAUDE.md, and roadmap files (ROADMAP-*.docx). When CWK-005 detects staged changes to these files, it uses blocking mode instead of auto mode.

Q.What happens with large diffs?

Diffs over 500 lines switch to summary mode automatically — the recipe reviews structural changes and CRAFT checks only, skipping line-by-line hunk analysis. Use git diff directly for detailed line-level review of large changes.

Q.How does this recipe differ from the Core SMART File Reviewer?

The Core recipe compares two user-provided file attachments. This Cowork version uses git diff to compare file versions across commits, extracts intent from commit messages, integrates with CWK-005 for automatic post-commit reviews, and adds blocking mode for critical files. Same validation depth, automated execution.

Version History

Changes to this recipe over time. Most recent first.
v1.02a 2026-03-25
Added CRAFT-specific checks as a structured configuration block: 6 validation rules with named checks, descriptions, and severity assignments. Added error handling for 4 edge cases (no git repo, insufficient commits, invalid ref, large diff). Formalized critical files list for blocking mode.
v1.01a 2026-03-15
Added blocking mode (R-14, QA Phase C): returns BLOCK status to CWK-005 caller when CRITICAL findings exist in critical files. Commit must be reverted or fixed before proceeding. Critical files: cookbooks, chat history, CLAUDE.md, roadmap.
v1.00a 2026-02-28
Initial release. Extends Core SMART File Reviewer with git integration: 6-step pipeline (diff retrieval, structural analysis, change classification, CRAFT checks, severity classification, report), two review modes (auto and full), commit intent alignment analysis, CRAFT-specific structural validation, CWK-005 post-commit integration.

Get this recipe with CRAFT for Claude Cowork

Cowork recipes ship bundled with CRAFT for Claude Cowork — there’s no separate download. Clone the framework once, and your AI runs every recipe automatically when invoked.

Pull anytime to stay on the latest version — free to clone, no login or email required.

Then start your session

Once CRAFT is in your project folder, open a new Cowork session and ask Claude to initialize. For example:

You

Please initialize my CRAFT session.

Claude

CRAFT session ready. Your project is loaded, your persona is active, and your recipes are available. What would you like to work on?

What is CRAFT for Claude Cowork?

Not familiar with Git? Download as a ZIP

No command line needed. Just download, move, and unzip:

  1. Open the CRAFT framework repo on GitHub.
  2. Click the green Code button, then choose Download ZIP.
  3. Move the downloaded ZIP into your Claude Cowork project folder.
  4. Unzip it: double-click on Mac, or right-click → Extract All on Windows.

Similar Posts