REQUIRED FIRST STEP: Get git diff and file changes to analyze before writing a commit message.

IMPORTANT: You MUST call this tool FIRST before generating any commit message. Never write a commit message without first seeing the actual git diff from this tool.

This tool ONLY shows STAGED changes. We intentionally do not support unstaged changes to ensure users have explicit control over what gets committed and prevent accidental commits.

CRITICAL: If the diff is empty and there are no files:

1. STOP immediately - do NOT proceed with generating a commit message

2. Tell the user: "No staged changes found. Please stage the files you want to commit first using: git add "

3. DO NOT attempt to stage files automatically

4. Wait for the user to stage their changes

Returns file changes and diff output with TOKEN-BASED pagination (MCP limit: 25k tokens). Large diffs are automatically paginated to stay under the token limit.

ANALYZING THE RESPONSE - follow these steps in order:

1. SECRET SCAN (automated): Check secret_scan.status FIRST.

   • If "warnings_found": STOP and warn the user about each finding. Show the file, line number, type, and redacted preview for each finding. Recommend removing the secret before committing. Do NOT proceed to generate a commit message until the user acknowledges or explicitly chooses to proceed despite the warnings.

   • If "clean": proceed to step 2.

2. SECRET SCAN (your review): Even if the automated scan is clean, briefly review the diff yourself for anything the regex-based scanner might miss:

   • Hardcoded credentials or secrets in unusual formats

   • Internal URLs, IP addresses, or hostnames that shouldn't be committed

   • Sensitive configuration values (database hosts, internal endpoints)

   • Comments containing passwords or access instructions If you spot anything suspicious, warn the user before proceeding.

3. COMMIT MESSAGE: After confirming no secrets (or user acknowledgment), generate a commit message following:

   • 50/72 rule: 50 char subject line, 72 char body lines

   • Conventional commits format: type(scope): description

   • DO NOT include AI signatures, attribution, or "Generated with" footers

Args: cursor: Pagination cursor for large diffs (optional, returned as next_cursor) max_diff_tokens: Maximum tokens per response (default: 20000, safe under 25k limit) repo_path: Path to git repository (optional, defaults to Claude's working directory)

Returns: JSON string with: - has_changes: boolean - True if there are any staged changes to commit - files: list of changed files with status - secret_scan: results of secret detection on added lines - diff: the diff chunk (paginated) - next_cursor: pagination cursor for next chunk (if any) - pagination_info: token counts and chunk info - commit_format_guide: formatting rules for commit messages

Execute git commit with a user-approved commit message.

CRITICAL WORKFLOW - YOU MUST FOLLOW THESE STEPS IN ORDER:

1. Call get_commit_context to get the diff

2. Generate a commit message based on the actual diff

3. SHOW the generated commit message to the user in your response

4. ASK the user: "Should I proceed with this commit?" and WAIT for their response

5. ONLY call this tool AFTER the user explicitly approves (says "yes", "proceed", "commit it", etc.)

6. Set user_approved=True when calling this tool

DO NOT call this tool in the same response where you generate the commit message. The user MUST see the message and approve it first.

Args: message: User-approved commit message (should follow 50/72 rule) user_approved: REQUIRED - Must be True. Confirms user has seen and approved the commit message. repo_path: Path to git repository (optional, defaults to Claude's working directory)

Returns: Success message with commit hash or error

Get diff and commits between branches for PR description.

IMPORTANT: After calling this tool, you should:

1. Check if .devnarrate/pr-templates/ directory exists (use ls or Bash)

2. If templates exist, list them and ask user which template to use

3. Read the chosen template file (use Read tool)

4. If no templates exist, use git_operations.DEFAULT_PR_TEMPLATE

5. Analyze the diff and commits to fill the template

Args: base_branch: Base branch to compare against (e.g., "main", "dev") head_branch: Head branch (defaults to current branch) cursor: Pagination cursor for large diffs (optional, returned as next_cursor) max_diff_tokens: Maximum tokens per diff chunk (default: 12000, leaves room for commits/files in 25k limit) repo_path: Path to git repository (optional, defaults to Claude's working directory)

Returns: JSON string with commits, files, diff chunk, and pagination info

Create a pull request on the detected platform (GitHub/GitLab).

CRITICAL WORKFLOW - YOU MUST FOLLOW THESE STEPS IN ORDER:

1. Call get_pr_context to analyze the changes

2. Generate PR title and description based on the diff

3. SHOW the generated PR title and body to the user in your response

4. ASK the user: "Should I create this PR?" and WAIT for their response

5. ONLY call this tool AFTER the user explicitly approves (says "yes", "proceed", "create it", etc.)

6. Set user_approved=True when calling this tool

DO NOT call this tool in the same response where you generate the PR description. The user MUST see the content and approve it first.

Args: title: PR title (keep it concise, ~50 chars) body: PR description (formatted markdown) base_branch: Base branch (e.g., "main", "dev") user_approved: REQUIRED - Must be True. Confirms user has seen and approved the PR content. head_branch: Head branch (defaults to current branch) draft: Create as draft PR (default: False) repo_path: Path to git repository (optional, defaults to Claude's working directory)

Returns: Success message with PR URL or error message

Review code changes before staging/committing to understand what was done and why.

WHEN TO CALL: After you (the AI assistant) have made code changes on behalf of the user and BEFORE staging or committing. This lets the user understand what you did at a conceptual level rather than reading raw diffs.

REQUIRED: Before calling this tool, summarize what the user asked you to do. Pass this as the 'goal' parameter. Be specific — "add JWT authentication middleware" is better than "make changes".

HOW TO PRESENT THE RESPONSE — follow this layered approach:

1. NARRATIVE SUMMARY (always show first): Start with a plain-language summary of what changed. Example: "I made 5 changes across 3 files to add JWT authentication." Include the key stats: files added/modified/deleted, lines changed.

2. GOAL ALIGNMENT (group changes by purpose): Look at each changed file and classify it into one of three tiers:

   • KNOWN: Changes that directly relate to the 'goal' you passed. You know these because you made them for the stated purpose.

   • INFERRED: Changes whose context_clues (comments, docstrings) suggest a clear purpose different from the stated goal. These may be from a different AI agent session. Describe the inferred purpose.

   • UNKNOWN: Changes with no clear connection to any goal AND no useful context clues. Flag these — the user should review them.

3. PER-FILE BREAKDOWN: For each goal group, list the files with a short description of what changed. Read the diff to explain HOW the goal was achieved:

   • What functions/classes were added or modified?

   • What's the approach? (e.g., "Added middleware pattern using decorators")

   • Any notable implementation choices?

4. ATTENTION GUIDE: Tell the user what needs their eyes vs what's routine:

   • NEW FILES: "I created auth/middleware.py — worth a quick review"

   • MODIFIED FILES: "Added 3 lines to config.py — routine import addition"

   • UNKNOWN CHANGES: "utils.py was modified but doesn't match the goal — please check"

   • LARGE CHANGES: Any file with 50+ lines added deserves a mention

5. DETAIL ON DEMAND: End with: "Want me to walk through any specific file in detail?"

IMPORTANT: You have the full diff in the response — READ IT to understand the actual code in any programming language. The context_clues are supplementary hints (comments/docstrings) to help you classify changes from other sessions that you didn't make yourself.

Args: goal: What the user asked the AI to do. Summarize from your conversation. Be specific — this is used to classify changes into goal groups. scope: What to analyze: - "working" (default): All unstaged working tree changes (git diff) plus untracked files. Use this before staging. - "staged": Only staged changes (git diff --staged). Use this if the user has already staged specific files. repo_path: Path to git repository (optional, defaults to MCP roots).

Returns: JSON string with: - goal: The stated goal (pass-through for your reference) - summary: File and line count statistics - changes: Per-file stats (path, status, lines_added, lines_removed) - context_clues: Comments and docstrings from added lines (per file) - diff: Raw diff text for you to read and understand the code - untracked_files: List of new files not yet tracked by git (working scope only) - pagination_info: Token counts and chunk info for the diff