git-aware-coding-agent 1.0.0__tar.gz

git_aware_coding_agent-1.0.0/.agents/README.md

@@ -0,0 +1,89 @@
+# Agent Integration Guide
+
+This repository supports multiple AI coding agent platforms. Each platform has its own integration directory.
+
+## Platform-Specific Integrations
+
+| Platform | Directory | Status |
+|----------|-----------|--------|
+| Cursor IDE | `.cursor/` | Implemented |
+| Claude Code | `.claude/` | Implemented |
+| OpenAI Codex | `.codex/` | Community stub |
+
+## Integration Structure
+
+Each platform integration follows a similar pattern:
+
+```
+.platform/
+├── README.md or PLATFORM.md    # Main instructions
+├── commands/                    # Command wrappers
+├── agents/                      # Sub-agents
+├── skills/                      # Skills (Cursor)
+├── rules/                       # Rules (Cursor)
+└── instincts/                   # Instincts (Claude)
+```
+
+## Adding a New Platform
+
+To add support for a new AI coding agent platform:
+
+1. Create a directory: `.platform-name/`
+2. Add main instructions file
+3. Create command wrappers for avos commands
+4. Add any platform-specific agents or skills
+5. Submit a PR with your integration
+
+## Available Avos Commands
+
+All platforms should integrate these commands:
+
+| Command | Purpose |
+|---------|---------|
+| `avos ask --json "question"` | Search memory for answers |
+| `avos history --json "subject"` | Get chronological history |
+| `avos ingest-pr --json org/repo N` | Ingest a single PR |
+
+## Workflow Guidelines
+
+All platform integrations should follow these workflow guidelines:
+
+1. **Research Before Edit**: Check history and ask questions before modifying code
+2. **Ingest After PR**: Ingest PRs after pushing to remote
+3. **JSON Output**: Use `--json` for machine-readable output
+
+## JSON Output Format
+
+All commands with `--json` return:
+
+```json
+{
+  "success": true,
+  "data": { ... },
+  "error": null
+}
+```
+
+On error:
+
+```json
+{
+  "success": false,
+  "data": null,
+  "error": {
+    "code": "ERROR_CODE",
+    "message": "Human-readable message",
+    "hint": "How to fix it",
+    "retryable": true
+  }
+}
+```
+
+## Contributing
+
+Community contributions are welcome! Please:
+
+1. Follow the existing patterns in `.cursor/` and `.claude/`
+2. Include comprehensive documentation
+3. Test with the target platform
+4. Submit a PR with your integration

git_aware_coding_agent-1.0.0/.claude/CLAUDE.md

@@ -0,0 +1,118 @@
+# Avos Dev CLI - Claude Code Integration
+
+This repository uses **avos-dev-cli** for codebase memory. Follow these instructions when working on this codebase.
+
+## Project Overview
+
+avos-dev-cli is a developer memory CLI that:
+
+- Stores repository history (PRs, issues, commits, docs) in Avos Memory
+- Enables semantic search over codebase context
+- Provides chronological history of any subject
+
+## Required Environment Variables
+
+Ensure these are set before using avos commands:
+
+```bash
+export AVOS_API_KEY="your-avos-api-key"
+export GITHUB_TOKEN="your-github-token"
+export ANTHROPIC_API_KEY="your-anthropic-key"
+
+# For JSON output formatting (optional but recommended)
+export REPLY_MODEL="your-model-id"
+export REPLY_MODEL_URL="https://api.example.com/v1/chat/completions"
+export REPLY_MODEL_API_KEY="your-reply-model-key"
+```
+
+## Workflow
+
+### Before Modifying Code
+
+Use these commands to understand the codebase:
+
+- **Search memory**: `avos ask --json "your question"`
+- **Get history**: `avos history --json "subject"`
+
+### After Pushing PRs
+
+After pushing a PR to the remote:
+
+```bash
+avos ingest-pr --json org/repo PR_NUMBER
+```
+
+## Best Practices
+
+### Check History for Medium/High-Risk Edits
+
+Run these before medium/high-risk edits (existing production behavior, shared modules, refactors, multi-file changes):
+
+```bash
+avos history --json "module or feature name"
+avos ask --json "why was this implemented this way?"
+```
+
+This helps you understand:
+
+- Why the code was written this way
+- Who made previous changes and why
+- Related PRs, issues, and commits
+
+You may skip for low-risk edits (docs/comments/typos, isolated new files, or test-only changes that do not affect runtime behavior).
+
+### Search Before Writing New Code
+
+Before implementing new features:
+
+```bash
+avos ask --json "is there existing implementation for X?"
+avos ask --json "how do other parts of the codebase handle Y?"
+```
+
+## Available Commands
+
+| Command                            | Purpose                   |
+| ---------------------------------- | ------------------------- |
+| `avos ask --json "question"`       | Search memory for answers |
+| `avos history --json "subject"`    | Get chronological history |
+| `avos ingest-pr --json org/repo N` | Ingest a single PR        |
+
+## JSON Output Format
+
+All commands with `--json` return:
+
+```json
+{
+  "success": true,
+  "data": { ... },
+  "error": null
+}
+```
+
+On error:
+
+```json
+{
+  "success": false,
+  "data": null,
+  "error": {
+    "code": "ERROR_CODE",
+    "message": "Human-readable message",
+    "hint": "How to fix it",
+    "retryable": true
+  }
+}
+```
+
+## Slash Commands
+
+Use these slash commands for quick access:
+
+- `/avos-ask` - Search repository memory
+- `/avos-history` - Get chronological history
+- `/avos-ingest-pr` - Ingest a PR after pushing
+
+## Sub-Agents
+
+- **avos-researcher** - Automatically searches memory and history before code changes

git_aware_coding_agent-1.0.0/.claude/agents/avos-researcher.md

@@ -0,0 +1,96 @@
+---
+name: avos-researcher
+description: Research repository context before code changes using avos memory
+tools: Bash, Read
+---
+
+# Avos Researcher Agent
+
+You are a research agent that gathers context from repository memory before code changes are made.
+
+## Purpose
+
+Before medium/high-risk code modifications, you search repository memory to understand:
+- Why the code was written this way
+- Who made previous changes and why
+- Related PRs, issues, and commits
+- Existing patterns and implementations
+
+Trigger this agent when at least one applies:
+- Editing existing production behavior
+- Touching shared or unfamiliar modules
+- Making broad/multi-file refactors or behavior changes
+
+Skip for low-risk docs/comment/test-only edits.
+
+## Workflow
+
+### 1. Identify the Subject
+
+When asked to research before modifying code, identify:
+- The module or feature being modified
+- The specific functionality being changed
+- Related concepts or dependencies
+
+### 2. Search Memory
+
+Run these commands to gather context:
+
+```bash
+# Get chronological history
+avos history --json "subject"
+
+# Ask specific questions
+avos ask --json "why was this implemented this way?"
+avos ask --json "are there related implementations?"
+```
+
+### 3. Parse Results
+
+Parse the JSON responses and extract:
+- Timeline of changes
+- Key decisions and their rationale
+- Related PRs and issues
+- Authors who worked on this area
+
+### 4. Report Findings
+
+Summarize your findings:
+- **History**: What changes were made and when
+- **Rationale**: Why decisions were made
+- **Related**: Connected code and dependencies
+- **Recommendations**: What to consider before making changes
+
+## Example Research
+
+For a request to modify the authentication module:
+
+```bash
+avos history --json "authentication"
+avos ask --json "why does authentication use JWT instead of sessions?"
+avos ask --json "what security considerations were made for auth?"
+```
+
+## Output Format
+
+Provide a structured summary:
+
+```
+## Research Summary: [Subject]
+
+### Timeline
+- [Date]: [Event] by [Author]
+- ...
+
+### Key Decisions
+- [Decision]: [Rationale]
+- ...
+
+### Related Code
+- [File/Module]: [Relationship]
+- ...
+
+### Recommendations
+- [Consideration before making changes]
+- ...
+```

git_aware_coding_agent-1.0.0/.claude/commands/avos-ask.md

@@ -0,0 +1,40 @@
+---
+description: Search repository memory for engineering context
+allowed-tools: Bash
+argument-hint: your question about the codebase
+---
+
+# Avos Ask
+
+Search the repository memory for answers to your question.
+
+## Usage
+
+Run this command and parse the JSON output:
+
+```bash
+avos ask --json "$ARGUMENTS"
+```
+
+## Response Handling
+
+Parse the JSON response:
+
+```json
+{
+  "success": true,
+  "data": {
+    "format": "avos.ask.v1",
+    "answer": { "text": "..." },
+    "evidence": { "items": [...] }
+  }
+}
+```
+
+If `success` is false, check `error.code` and `error.hint` for guidance.
+
+## Examples
+
+- "why does authentication use JWT?"
+- "how do other endpoints handle pagination?"
+- "is there existing error handling middleware?"

git_aware_coding_agent-1.0.0/.claude/commands/avos-history.md

@@ -0,0 +1,40 @@
+---
+description: Get chronological history of a subject in the repository
+allowed-tools: Bash
+argument-hint: subject or topic for timeline
+---
+
+# Avos History
+
+Get the chronological history of a subject in the repository.
+
+## Usage
+
+Run this command and parse the JSON output:
+
+```bash
+avos history --json "$ARGUMENTS"
+```
+
+## Response Handling
+
+Parse the JSON response:
+
+```json
+{
+  "success": true,
+  "data": {
+    "format": "avos.history.v1",
+    "timeline": { "months": [...] },
+    "summary": { "text": "..." }
+  }
+}
+```
+
+If `success` is false, check `error.code` and `error.hint` for guidance.
+
+## Examples
+
+- "authentication module"
+- "user registration flow"
+- "database connection handling"

git_aware_coding_agent-1.0.0/.claude/commands/avos-ingest-pr.md

@@ -0,0 +1,54 @@
+---
+description: Ingest a single PR into repository memory
+allowed-tools: Bash
+argument-hint: org/repo PR_NUMBER
+---
+
+# Avos Ingest PR
+
+Ingest a single PR into repository memory after pushing.
+
+## Usage
+
+```bash
+avos ingest-pr --json $ARGUMENTS
+```
+
+## Response Handling
+
+Parse the JSON response:
+
+**Stored:**
+```json
+{
+  "success": true,
+  "data": {
+    "pr_number": 123,
+    "action": "stored",
+    "note_id": "note-abc-123"
+  }
+}
+```
+
+**Skipped (already ingested):**
+```json
+{
+  "success": true,
+  "data": {
+    "pr_number": 123,
+    "action": "skipped",
+    "reason": "already_ingested"
+  }
+}
+```
+
+## When to Use
+
+- After pushing a PR to the remote repository
+- After a PR is merged
+- To ensure PR context is available for future queries
+
+## Examples
+
+- `myorg/myrepo 123`
+- `company/project 456`

git_aware_coding_agent-1.0.0/.claude/instincts/avos-workflow.yaml

@@ -0,0 +1,81 @@
+# Curated instincts for avos-dev-cli workflow
+# Import with: /instinct-import .claude/instincts/avos-workflow.yaml
+
+---
+id: avos-check-history-before-edit
+trigger: "when modifying existing production code, shared modules, or making medium/large edits in a repository with avos"
+confidence: 0.9
+domain: workflow
+source: repo-curation
+source_repo: avos-dev-cli
+---
+# Check History Before Editing
+
+## Action
+Before medium/high-risk edits, run `avos history --json "subject"` and `avos ask --json "why was this implemented?"` to understand context and rationale.
+
+Do this when:
+- editing existing production behavior
+- touching unfamiliar or shared modules
+- making broad or multi-file changes
+
+Skip for low-risk docs/comment/test-only edits.
+
+## Evidence
+- Understanding history prevents breaking changes
+- Previous decisions often have important context
+- Related PRs and issues provide valuable information
+
+---
+id: avos-ingest-after-pr
+trigger: "after pushing a PR to a repository with avos"
+confidence: 0.8
+domain: workflow
+source: repo-curation
+source_repo: avos-dev-cli
+---
+# Ingest PR After Push
+
+## Action
+After pushing a PR to the remote repository, run `avos ingest-pr --json org/repo PR_NUMBER` to ensure the PR context is available for future queries.
+
+## Evidence
+- PR context helps future developers understand changes
+- Ingested PRs are searchable via `avos ask` and `avos history`
+- Deduplication prevents duplicate entries
+
+---
+id: avos-search-before-implementing
+trigger: "when implementing substantial new functionality in a repository with avos"
+confidence: 0.85
+domain: workflow
+source: repo-curation
+source_repo: avos-dev-cli
+---
+# Search Before Implementing
+
+## Action
+Before substantial implementation work, run `avos ask --json "is there existing implementation for X?"` to check for prior patterns and avoid duplication.
+
+## Evidence
+- Prevents code duplication
+- Maintains consistency with existing patterns
+- Leverages existing tested implementations
+
+---
+id: avos-json-output-for-agents
+trigger: "when using avos commands programmatically"
+confidence: 0.9
+domain: workflow
+source: repo-curation
+source_repo: avos-dev-cli
+---
+# Use JSON Output for Programmatic Access
+
+## Action
+Always use the `--json` flag when calling avos commands programmatically. Parse the JSON response and check `success` before using `data`.
+
+## Evidence
+- JSON output is machine-readable
+- Error codes and hints help with error handling
+- Consistent format across all commands

git_aware_coding_agent-1.0.0/.codex/instructions.md

@@ -0,0 +1,66 @@
+# Codex Integration (Community)
+
+This directory is reserved for OpenAI Codex CLI integration.
+
+## Reference Implementations
+
+See these directories for reference implementations:
+
+- `.cursor/` - Cursor IDE integration (skills + rules)
+- `.claude/` - Claude Code integration (commands + agents + instincts)
+
+## Contributing
+
+Community contributions for Codex integration are welcome. Follow the patterns established in `.cursor/` and `.claude/`:
+
+1. **Instructions file**: Main configuration and workflow guidance
+2. **Commands**: Individual command wrappers
+3. **Agents**: Specialized sub-agents for specific tasks
+
+## Avos Commands
+
+The following avos commands are available for integration:
+
+| Command | Purpose |
+|---------|---------|
+| `avos ask --json "question"` | Search memory for answers |
+| `avos history --json "subject"` | Get chronological history |
+| `avos ingest-pr --json org/repo N` | Ingest a single PR |
+
+## JSON Output Format
+
+All commands with `--json` return:
+
+```json
+{
+  "success": true,
+  "data": { ... },
+  "error": null
+}
+```
+
+On error:
+
+```json
+{
+  "success": false,
+  "data": null,
+  "error": {
+    "code": "ERROR_CODE",
+    "message": "Human-readable message",
+    "hint": "How to fix it",
+    "retryable": true
+  }
+}
+```
+
+## Required Environment Variables
+
+- `AVOS_API_KEY` - Avos Memory API key
+- `GITHUB_TOKEN` - GitHub personal access token
+- `OPENAI_API_KEY` (default) or `ANTHROPIC_API_KEY` (when using Anthropic) - For LLM synthesis
+
+For JSON output formatting:
+- `REPLY_MODEL` - Model identifier
+- `REPLY_MODEL_URL` - API endpoint
+- `REPLY_MODEL_API_KEY` - API key