You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4
+
5
+
## What is Agentry
6
+
7
+
Agentry is a Python CLI tool for portable agentic workflow orchestration. It defines workflows in YAML, executes them in sandboxed environments (Docker or in-process), and integrates with CI platforms like GitHub Actions. Workflows compose Claude-powered agents with declarative safety constraints, tool manifests, and multi-agent DAG composition.
8
+
9
+
## Development Commands
10
+
11
+
```bash
12
+
# Install dependencies (use uv, not pip)
13
+
uv sync --all-extras
14
+
15
+
# Linting and formatting
16
+
uv run ruff check src/agentry/
17
+
uv run ruff format src/agentry/
18
+
19
+
# Type checking (strict mode enabled)
20
+
uv run mypy src/agentry/ --ignore-missing-imports
21
+
22
+
# Run all tests
23
+
uv run pytest tests/
24
+
25
+
# Run by marker
26
+
uv run pytest tests/ -m unit
27
+
uv run pytest tests/ -m integration
28
+
uv run pytest tests/ -m docker
29
+
uv run pytest tests/ -m e2e
30
+
31
+
# Run a single test file
32
+
uv run pytest tests/unit/test_parser.py -v
33
+
34
+
# Run a single test
35
+
uv run pytest tests/unit/test_parser.py::test_function_name -v
36
+
```
37
+
38
+
## Architecture
39
+
40
+
The system follows a 5-layer pipeline:
41
+
42
+
1.**Definition** (`src/agentry/models/`) — Pydantic v2 models parse and validate workflow YAML. `WorkflowDefinition` is the top-level model.
3.**Resolution** (`src/agentry/binders/`) — `EnvironmentBinder` protocol resolves inputs from the execution environment (local CLI or GitHub Actions).
45
+
4.**Execution** (`src/agentry/runners/`) — `RunnerProtocol` implementations run agents in Docker containers (sandboxed) or in-process (elevated trust).
46
+
5.**Agent** (`src/agentry/agents/`) — `AgentProtocol` (PEP 544) abstracts agent runtimes. `ClaudeCodeAgent` is the primary implementation.
47
+
48
+
**Composition engine** (`src/agentry/composition/`) orchestrates multi-agent DAGs with async execution, failure policies (abort/skip/retry), and file-based data passing between nodes.
49
+
50
+
**CLI entry point** is `src/agentry/cli.py` using Click. The `agentry` command is registered via `pyproject.toml` entry points.
51
+
52
+
**Binders are pluggable** via the `agentry.binders` entry point group. The `github-actions` binder ships built-in.
53
+
54
+
## Key Design Patterns
55
+
56
+
- All protocols use PEP 544 structural typing (`Protocol` classes), not ABC inheritance
57
+
- Pydantic v2 strict validation throughout the model layer
58
+
- Runners auto-detected via `detector.py` based on environment and trust level
59
+
- Network isolation uses a custom DNS proxy (`dns_proxy.py`) to enforce allowlists
-**mypy**: strict mode. Tests are exempted from strict typing.
65
+
-**pytest markers**: `unit`, `integration`, `docker`, `e2e` — always mark new tests appropriately
66
+
67
+
## Workflow Library
68
+
69
+
`workflows/` contains standard workflow YAML files (code-review, triage, bug-fix, task-decompose, feature-implement, planning-pipeline). These serve as both usable workflows and reference examples for the YAML schema.
70
+
71
+
## CI Self-Development Loop
72
+
73
+
Agentry develops itself via GitHub Actions workflows in `.github/workflows/`:
The loop: issue filed → planning-pipeline applies labels → label triggers bug-fix or feature-implement → code-review reviews the resulting PR. The GitHubActionsBinder provides `issue:comment`, `issue:label`, `issue:create`, and `pr:create` tool bindings.
Copy file name to clipboardExpand all lines: README.md
+26-4Lines changed: 26 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -38,9 +38,30 @@ agentry run workflows/triage.yaml \
38
38
39
39
Agentry resolves inputs (including git refs like `HEAD~1` for diff inputs), selects the appropriate runner, launches the agent runtime, enforces the tool manifest, and validates the output against the declared schema. Execution records are written to `.agentry/runs/` for auditability.
40
40
41
-
### Self-development
41
+
### Self-development loop
42
42
43
-
Agentry reviews its own PRs. The `.github/workflows/agentry-code-review.yml` workflow runs `agentry run workflows/code-review.yaml` on every pull request, posting findings as PR comments. The bug-fix workflow can create branches and open PRs with proposed fixes — all requiring human review before merge.
43
+
Agentry develops itself through a closed-loop CI pipeline:
Copy file name to clipboardExpand all lines: docs/BACKLOG.md
+27-4Lines changed: 27 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -5,6 +5,29 @@ Items are grouped by category. Each item notes its source and any recommended pr
5
5
6
6
---
7
7
8
+
## Phases 7-9 Completed — CI Self-Development Loop
9
+
10
+
Phases 7-9 close the self-development loop. Issues filed against the repo are automatically triaged, decomposed, and routed to bug-fix or feature-implement workflows that open PRs.
-[ ]**Streaming agent output** — real-time output during execution _(deferred)_
26
+
27
+
_Source: Phase 7, 8, 9 specs_
28
+
29
+
---
30
+
8
31
## Phase 6 Completed — Self-Development
9
32
10
33
Phase 6 (Self-Development) is complete. Agentry can now execute its own workflows, review its own PRs in CI, resolve git-diff inputs, and propose fixes via agent-generated PRs.
@@ -14,7 +37,7 @@ Phase 6 (Self-Development) is complete. Agentry can now execute its own workflow
0 commit comments