Commitly Expert

Expert guidance for working with **Commitly**, an AI-powered multi-agent commit automation system that orchestrates the entire post-commit workflow through a local Python pipeline using LangGraph.

What This Skill Does

This skill provides comprehensive context and guidance when working with the Commitly codebase. It helps you:

Instructions

When assisting with Commitly development, follow these guidelines:

1. Understand the Architecture First

Commitly uses a **LangGraph-based sequential orchestration pattern**:

2. Key Files to Reference

When answering questions or making changes:

3. Common Development Commands

Provide these commands when relevant:

**Setup & Running:**

```bash

poetry install

set -a && source .env && set +a

poetry run commitly init

poetry run commitly commit -m "message"

```

**Code Quality:**

```bash

ruff check src/

black src/

mypy src/commitly/

pytest --cov=src/commitly tests/

```

**Debugging:**

```bash

poetry run commitly status

cat .commitly/logs/{agent_name}/$(ls -t .commitly/logs/{agent_name} | head -1)

cat .commitly/cache/{agent_name}.json

```

4. Adding or Modifying Agents

When asked to add a new agent:

1. Create `src/commitly/agents/{agent_name}/agent.py`

2. Inherit from `BaseAgent`

3. Implement `execute(self, context: RunContext) -> Dict[str, Any]`

4. Add agent node to LangGraph in `src/commitly/pipeline/graph.py:build_graph()`

5. Agent logs automatically go to `.commitly/logs/{agent_name}/`

6. Output is cached in `.commitly/cache/{agent_name}.json`

When modifying existing agents, locate their `execute()` method and explain:

5. Debugging Agent Failures

When troubleshooting:

1. **Check logs**: `.commitly/logs/{agent_name}/{timestamp}.log`

2. **Inspect cache**: `.commitly/cache/{agent_name}.json` shows status, error details, previous results

3. **Review hub state**: `.commitly/hub/` contains agent modifications

4. **Trace git history**: `git -C .commitly/hub log` shows branch history

5. **Manual reset**: `git -C .commitly/hub reset --hard {branch}`

6. Configuration Guidance

When config changes are needed:

Always remind to source `.env` before running: `set -a && source .env && set +a`

7. Code Style & Quality Standards

Enforce these rules from `pyproject.toml`:

8. Testing Approach

When writing or running tests:

Example test structure:

```python

def test_agent_execution(tmp_path):

context = {

"pipeline_id": "test-123",

"hub_path": str(tmp_path / "hub"),

# ... required RunContext fields

}

agent = YourAgent()

result = agent.run(context)

assert result["status"] == "success"

```

9. Performance & Troubleshooting

Alert users to these considerations:

Common issues:

10. Pipeline Flow & Approval Gate

Always emphasize:

1. User commits → Pipeline starts

2. Agents execute sequentially in hub directory

3. **SyncAgent is the ONLY approval gate** (user must confirm before remote push)

4. Non-blocking agents (Slack, Report) run after approval but don't block on failure

5. Rollback on failure: deletes created branches, resets hub

Example Usage

**User asks**: "How do I add a new agent that checks for security vulnerabilities?"

**Response**:

1. Create `src/commitly/agents/security/agent.py`

2. Inherit from `BaseAgent` and implement `execute(self, context: RunContext) -> Dict[str, Any]`

3. In `execute()`, run security scanning tools (e.g., `bandit`, `safety`) on the hub directory (`context["hub_path"]`)

4. Return structured data: `{"status": "success", "vulnerabilities_found": [...], "report_path": "..."}`

5. Add to LangGraph in `src/commitly/pipeline/graph.py:build_graph()`:

```python

from commitly.agents.security.agent import SecurityAgent

graph.add_node("security", lambda ctx: SecurityAgent().run(ctx))

graph.add_edge("test", "security") # After TestAgent

graph.add_edge("security", "refactoring")

```

6. Logs will automatically go to `.commitly/logs/security/`

7. Run pipeline: `poetry run commitly commit -m "test security agent"`

Constraints