README

Git repository management toolkit for Coqui. Provides full Git CLI access plus repository triage analytics — status, staging, commits, branches, tags, remotes, push/pull, merge, diff, log, and pre-code-reading audit workflows — all sandboxed through typed tools with proper argument escaping.

Requirements

• PHP 8.4+
• Git CLI installed and on PATH
• Coqui (auto-discovered via Composer)

Installation

composer require coquibot/coqui-toolkit-git

When installed alongside Coqui, the toolkit is auto-discovered via Composer's extra.php-agents.toolkits — no manual registration needed.

The toolkit also bundles a reusable skill, git-repository-audit, so Coqui can apply the discovery workflow automatically when the user asks to assess a repository before reading code.

All repository analysis tools return compact JSON strings rather than prose-heavy summaries. That keeps token usage down and lets the bot decide whether to summarize, tabulate, compare, or feed the data into a larger workflow.

Tools Provided

git_init

Initialize a new Git repository.

git_status

Show the working tree status — modified, staged, and untracked files.

git_stage

Stage, unstage, or reset files in the Git index.

git_commit

Create a new commit with a message.

git_diff

Show differences between working tree, staged changes, or between commits.

git_log

View commit history with optional filters.

git_branch

Manage Git branches — list, create, delete, rename.

git_checkout

Switch branches, create+switch, or restore files.

git_tag

Manage Git tags — list, create, delete.

git_remote

Manage Git remotes — list, add, remove, show.

git_push

Push local commits to a remote repository.

git_pull

Fetch and integrate changes from a remote repository.

git_merge

Merge a branch into the current branch.

Repository Analysis Tools

git_churn_hotspots

Rank the files that change most often in a selected time window.

git_contributor_ranking

Rank contributors by commit count and flag bus-factor or maintainer drift.

git_bug_hotspots

Find files that repeatedly appear in bug-fix commits and cross-check them with churn hotspots.

git_velocity_trend

Summarize commit activity over time.

git_crisis_detection

Detect revert, hotfix, rollback, or emergency commit patterns that suggest firefighting.

git_repo_triage

Run the full audit workflow and return one machine-readable report containing churn, bug hotspots, contributor ranking, velocity, crisis detection, and derived priority signals.

Usage Examples

Feature Branch Workflow

git_branch(action: "create", name: "feature/new-api")
git_checkout(target: "feature/new-api")
# ... make changes ...
git_stage(action: "add_all")
git_commit(message: "feat: implement new API endpoint")
git_push(branch: "feature/new-api", set_upstream: true)

Quick Commit

git_status(short: true)
git_diff(scope: "working")
git_stage(action: "add", files: "src/Handler.php src/Router.php")
git_commit(message: "fix: handle null response in router")

Reviewing History

git_log(count: 10, oneline: true)
git_diff(scope: "commits", ref1: "HEAD~5")
git_diff(scope: "commits", ref1: "main", ref2: "feature/x", stat_only: true)

Repository Triage Before Reading Code

git_repo_triage()

Use this when you want one compact JSON report. If you want to inspect a single signal in more detail, call the individual analysis tools instead.

Tagging a Release

git_tag(action: "create", name: "v1.2.0", message: "Release 1.2.0")
git_push(tags: true)

Architecture

src/
├── Analysis/
│   └── GitAnalysisService.php  # Shared parsing + formatting for repository triage tools
├── GitToolkit.php              # ToolkitInterface — registers all tools + guidelines
├── Runtime/
│   ├── GitRunner.php           # proc_open wrapper with timeout + output truncation
│   └── GitResult.php           # Typed result VO (exitCode, stdout, stderr)
└── Tool/
    ├── GitInitTool.php
    ├── GitStatusTool.php
    ├── GitStageTool.php
    ├── GitCommitTool.php
    ├── GitDiffTool.php
    ├── GitLogTool.php
    ├── GitBranchTool.php
    ├── GitCheckoutTool.php
    ├── GitTagTool.php
    ├── GitRemoteTool.php
    ├── GitPushTool.php
    ├── GitPullTool.php
    └── GitMergeTool.php
    ├── GitChurnHotspotsTool.php
    ├── GitContributorRankingTool.php
    ├── GitBugHotspotsTool.php
    ├── GitVelocityTrendTool.php
    └── GitCrisisDetectionTool.php
    └── GitRepoTriageTool.php

skills/
└── git-repository-audit/
    └── SKILL.md                # Bundled repo-triage workflow guidance

Development

# Install dependencies
composer install

# Run tests
composer test

# Static analysis
composer analyse

License

MIT