docs: add 11 new documentation files across all categories
New reference docs: - agents/ref-btmsg.md: inter-agent messaging schema and CLI - agents/ref-bttask.md: kanban task board operations - providers/ref-providers.md: Claude/Codex/Ollama/Aider comparison - config/ref-settings.md: (already committed) New guides: - contributing/dual-repo-workflow.md: community vs commercial repos - plugins/guide-developing.md: Web Worker sandbox API and publishing New pro docs: - pro/features/knowledge-base.md: persistent memory + symbol graph - pro/features/git-integration.md: context injection + branch policy - pro/marketplace/README.md: 13 plugins catalog Split files: - architecture/data-model.md: from architecture.md (schemas, layout) - production/hardening.md: from production.md (supervisor, sandbox, WAL) - production/features.md: from production.md (FTS5, plugins, secrets, audit)
This commit is contained in:
Hibryda
parent
8251321dac
commit
b6c1d4b6af
11 changed files with 2198 additions and 0 deletions
196
docs/pro/features/git-integration.md
Normal file
196
docs/pro/features/git-integration.md
Normal file
|
|
@ -0,0 +1,196 @@
|
|||
# Git Integration
|
||||
|
||||
> This documentation covers Pro edition features available in the agents-orchestrator/agents-orchestrator private repository.
|
||||
|
||||
Git Integration provides two features: Git Context Injection (branch, commit, and diff information formatted for agent prompts) and Branch Policy (session-level protection for sensitive branches).
|
||||
|
||||
---
|
||||
|
||||
## Git Context Injection
|
||||
|
||||
### Purpose
|
||||
|
||||
Git Context Injection gathers repository state and formats it as markdown for inclusion in agent system prompts. This gives agents awareness of the current branch, recent commits, and modified files without requiring them to run git commands.
|
||||
|
||||
### Context Gathering
|
||||
|
||||
The system collects three categories of information by invoking the `git` CLI:
|
||||
|
||||
#### Branch Information
|
||||
|
||||
- Current branch name (`git rev-parse --abbrev-ref HEAD`)
|
||||
- Tracking branch and ahead/behind counts (`git rev-list --left-right --count`)
|
||||
- Last commit on branch (hash, author, date, subject)
|
||||
|
||||
#### Recent Commits
|
||||
|
||||
- Last N commits on the current branch (default: 10)
|
||||
- Each commit includes: short hash, author, relative date, subject line
|
||||
- Collected via `git log --oneline --format`
|
||||
|
||||
#### Modified Files
|
||||
|
||||
- Staged files (`git diff --cached --name-status`)
|
||||
- Unstaged modifications (`git diff --name-status`)
|
||||
- Untracked files (`git ls-files --others --exclude-standard`)
|
||||
|
||||
### Formatted Output
|
||||
|
||||
The collected information is formatted as a markdown section:
|
||||
|
||||
```markdown
|
||||
## Git Context
|
||||
|
||||
**Branch:** feature/new-dashboard (ahead 3, behind 0 of origin/main)
|
||||
|
||||
### Recent Commits (last 10)
|
||||
- `a1b2c3d` (2 hours ago) fix: resolve null check in analytics
|
||||
- `e4f5g6h` (5 hours ago) feat: add daily cost chart
|
||||
- ...
|
||||
|
||||
### Working Tree
|
||||
**Staged:**
|
||||
- M src/lib/components/Analytics.svelte
|
||||
- A src/lib/stores/analytics.svelte.ts
|
||||
|
||||
**Modified:**
|
||||
- M src/lib/adapters/pro-bridge.ts
|
||||
|
||||
**Untracked:**
|
||||
- tests/analytics.test.ts
|
||||
```
|
||||
|
||||
### Commands
|
||||
|
||||
#### pro_git_context
|
||||
|
||||
Gathers all git context for a project directory and returns formatted markdown.
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `cwd` | `String` | Yes | Absolute path to the git repository |
|
||||
| `commitCount` | `u32` | No | Number of recent commits to include (default: 10) |
|
||||
|
||||
**Response:**
|
||||
|
||||
```typescript
|
||||
interface GitContext {
|
||||
markdown: string; // Formatted markdown section
|
||||
branch: string; // Current branch name
|
||||
isDirty: boolean; // Has uncommitted changes
|
||||
aheadBehind: [number, number]; // [ahead, behind]
|
||||
}
|
||||
```
|
||||
|
||||
#### pro_git_inject
|
||||
|
||||
Convenience command that gathers git context and prepends it to a given system prompt.
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `cwd` | `String` | Yes | Repository path |
|
||||
| `systemPrompt` | `String` | Yes | Existing system prompt to augment |
|
||||
| `commitCount` | `u32` | No | Number of recent commits (default: 10) |
|
||||
|
||||
Returns the combined prompt string.
|
||||
|
||||
#### pro_git_branch_info
|
||||
|
||||
Returns structured branch information without formatting.
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `cwd` | `String` | Yes | Repository path |
|
||||
|
||||
**Response:**
|
||||
|
||||
```typescript
|
||||
interface BranchInfo {
|
||||
name: string;
|
||||
trackingBranch: string | null;
|
||||
ahead: number;
|
||||
behind: number;
|
||||
lastCommitHash: string;
|
||||
lastCommitSubject: string;
|
||||
lastCommitDate: string;
|
||||
}
|
||||
```
|
||||
|
||||
### Implementation Notes
|
||||
|
||||
- All git commands are executed via `std::process::Command` (not libgit2). This avoids a heavy native dependency and matches the git CLI behavior users expect.
|
||||
- Commands run with a 5-second timeout. If git is not installed or the directory is not a repository, commands return structured errors.
|
||||
- Output encoding is handled as UTF-8 with lossy conversion for non-UTF-8 paths.
|
||||
|
||||
---
|
||||
|
||||
## Branch Policy
|
||||
|
||||
### Purpose
|
||||
|
||||
Branch Policy prevents agents from making commits or modifications on protected branches. This is a session-level safeguard -- the policy is checked when an agent session starts and when git operations are detected in tool calls.
|
||||
|
||||
### Protection Rules
|
||||
|
||||
Protected branch patterns are configurable per project. The defaults are:
|
||||
|
||||
| Pattern | Matches |
|
||||
|---------|---------|
|
||||
| `main` | Exact match |
|
||||
| `master` | Exact match |
|
||||
| `release/*` | Any branch starting with `release/` |
|
||||
|
||||
When an agent session starts on a protected branch, the system emits a warning notification. It does not block the session, because agents may need to read code on these branches. However, the branch name is included in the agent's system prompt with a clear instruction not to commit.
|
||||
|
||||
### Commands
|
||||
|
||||
#### pro_branch_check
|
||||
|
||||
Checks whether the current branch is protected.
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `cwd` | `String` | Yes | Repository path |
|
||||
| `projectId` | `String` | Yes | Project identifier (for project-specific policies) |
|
||||
|
||||
**Response:**
|
||||
|
||||
```typescript
|
||||
interface BranchCheckResult {
|
||||
branch: string;
|
||||
isProtected: boolean;
|
||||
matchedPattern: string | null; // Which pattern matched
|
||||
}
|
||||
```
|
||||
|
||||
#### pro_branch_policy_set
|
||||
|
||||
Sets custom protected branch patterns for a project. Replaces any existing patterns.
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `projectId` | `String` | Yes | Project identifier |
|
||||
| `patterns` | `Vec<String>` | Yes | Branch patterns (exact names or glob with `*`) |
|
||||
|
||||
#### pro_branch_policy_get
|
||||
|
||||
Returns the current branch policy for a project. Returns default patterns if none are set.
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `projectId` | `String` | Yes | Project identifier |
|
||||
|
||||
#### pro_branch_policy_delete
|
||||
|
||||
Removes custom branch policy for a project, reverting to defaults.
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `projectId` | `String` | Yes | Project identifier |
|
||||
|
||||
### Integration
|
||||
|
||||
Branch policy is checked at two points:
|
||||
|
||||
1. **Session start:** `AgentSession.startQuery()` calls `pro_branch_check`. If protected, a warning toast is shown and the branch protection instruction is appended to the system prompt.
|
||||
2. **System prompt injection:** The formatted git context (from `pro_git_inject`) includes a `PROTECTED BRANCH` warning banner when applicable.
|
||||
Loading…
Add table
Add a link
Reference in a new issue