aptive-airflow-agent-team

Pi package for a sequential Apache Airflow agent pipeline:

airflow-researcher ──▶ airflow-architect ──▶ airflow-planner ──▶ airflow-implementer ──▶ airflow-reviewer

The extension registers the --airflow-chain flag, /airflow-chain commands, a status widget, and the run_airflow_chain tool.

Install

pi install npm:aptive-airflow-agent-team

Or run for one session without installing:

pi -e npm:aptive-airflow-agent-team --airflow-chain

After installing, launch Pi with:

pi --airflow-chain

What's included

• airflow-chain.ts — extension entrypoint and chain runner.
• implementationClassifier.ts — implementation vs read-only request classifier.
• workspace.ts — implementation workspace selection, child cwd selection, git snapshots, branch metadata, and diff comparison.
• sourceDiffGuard.ts — source-diff guard policy for no-change, plan-only, non-source-only, and retry cases.
• chainPolicy.ts — shared supervisor policy text and implementer no-source report detection.
• themeMap.ts — optional theme compatibility helper.
• agents/agent-chain.yaml — bundled airflow chain definition.
• agents/airflow-*.md — bundled researcher, architect, planner, implementer, and reviewer definitions.
• fixtures/fake-pi-child.mjs — deterministic fake child Pi for local no-provider smoke tests.
• bin/install-agents.mjs — install-airflow-chain-agents CLI that copies bundled agent definitions into either <cwd>/.pi/agents (default) or ~/.pi/agent/agents with --global. Supports --dry-run.

Project-local .pi/agents definitions take precedence when present; the bundled definitions are the fallback that makes the npm package self-contained.

Current behavior

• The researcher runs before the architect so architecture follows concrete repo evidence.
• The widget shows a full-width Current Agent activity panel above the chain cards.
• Debug logging can capture step prompts, handoffs, child events, tool calls, token counts, lags, and implementer delta metadata.
• The reviewer receives a programmatic implementer delta and should not fail solely on unrelated pre-existing dirty files.
• If the reviewer returns CHAIN_RETRY_REQUIRED, the orchestrator automatically reruns the implementer once, then reruns the reviewer. The retry cap is hard-coded to 1.
• Tasks classified as read-only (e.g. review, audit, "plan only", "without making changes") skip the implementer step; the reviewer also runs with the implementer's writer tools removed.
• For implementation requests, the orchestrator resolves one implementation workspace, runs the implementer/reviewer from that child cwd, snapshots git before and after each implementer attempt, and fails the chain if no relevant source files changed (Airflow DAGs/plugins, tests, configs, Dockerfile, requirements, etc.). Plan-only files like airflow-plan.md and progress.md do not count.
• The tool result is cached in memory for 30 minutes per exact task string. Re-running the same prompt within that window returns the prior result and emits a UI notice instead of re-spawning agents. Vary the prompt to bypass.
• Per-agent model: from each airflow-*.md frontmatter wins over the parent session's model. If no per-agent model is set and the parent has no model, the child falls back to openrouter/google/gemini-3-flash-preview.

See airflow-chain.README.md for local development and debugging details.

Safety defaults

The chain defaults to read-only repository inspection, safe local validation, and dry-run behavior. It reviews for Airflow parser/heartbeat safety, Snowflake -c claude usage, Aspyn local-doc constraints, XCom size, deployment impact, EKS risk, secrets, and operational risk.

Environment variables

Variable	Default	Purpose
AIRFLOW_CHAIN_PROGRESS_INTERVAL_MS	15000	User-visible progress throttle.
AIRFLOW_CHAIN_IDLE_TIMEOUT_MS	900000	Child idle timeout.
AIRFLOW_CHAIN_STEP_TIMEOUT_MS	2700000	Per-step max runtime.
AIRFLOW_CHAIN_DEBUG / ..._VERBOSE	off	Enable JSONL debug logs. The two names are equivalent aliases.
AIRFLOW_CHAIN_DEBUG_MAX_CHARS	20000	Max characters stored for any single logged string.
AIRFLOW_CHAIN_DEBUG_HEARTBEAT_INTERVAL_MS	progress interval	Frequency for idle/lag heartbeat records.
AIRFLOW_CHAIN_DEBUG_RAW_CHILD_EVENTS	off	Log raw child event type records.
AIRFLOW_CHAIN_DEBUG_STREAM_DELTAS	off	Log every streamed assistant text delta.