feat: publish auditable AgentTeams DevFlow system

Author: devflow

.env.example

@@ -0,0 +1,107 @@
+# =============================================================================
+# DevFlow Environment Variables Template
+# =============================================================================
+# Copy this file to `.env` and fill in real values. The DevFlow runtime loads
+# `.env` automatically via python-dotenv. NEVER commit the real `.env` — it
+# should be in .gitignore.
+#
+# Every variable here is referenced by the YAML configs in config/ using the
+# ${VAR} expansion syntax. Adding a new secret? Add it here AND wire it into
+# the relevant config file.
+# =============================================================================
+
+# -----------------------------------------------------------------------------
+# LLM Configuration
+# -----------------------------------------------------------------------------
+# API key for the LLM provider. Used by all glm-4 agents and as the fallback
+# for CoderAgent. Treat as a top-level secret — it is injected into the
+# credential gateway, never passed directly to agent prompts.
+LLM_API_KEY=
+
+# Base URL of the OpenAI-compatible endpoint serving GLM-4 / Codex.
+# Examples:
+#   - ZhipuAI:        https://open.bigmodel.cn/api/paas/v4
+#   - Local vLLM:     http://127.0.0.1:8000/v1
+#   - Azure OpenAI:   https://<resource>.openai.azure.com
+LLM_BASE_URL=https://open.bigmodel.cn/api/paas/v4
+
+# Default model name. Individual agents override this in config/agents.yaml
+# (e.g. CoderAgent uses "codex" with a "glm-4" fallback).
+LLM_MODEL=glm-4
+
+# -----------------------------------------------------------------------------
+# GitHub Configuration
+# -----------------------------------------------------------------------------
+# Fine-grained personal access token with repository + workflow scopes.
+# Required scopes: Contents (RW), Issues (RW), Pull requests (RW),
+# Workflows (R), Metadata (R). Used by the github MCP server.
+GITHUB_PERSONAL_ACCESS_TOKEN=
+
+# Target repository. Used by the github MCP server default context and by
+# the cicd MCP server to scope pipeline operations.
+GITHUB_REPO_OWNER=
+GITHUB_REPO_NAME=
+
+# -----------------------------------------------------------------------------
+# Vector Store (RAG / Experience Store)
+# -----------------------------------------------------------------------------
+# Local path to the ChromaDB persistent directory. Used by LocatorAgent for
+# code root-cause retrieval and by the experience-distiller for pattern
+# storage and deduplication lookups.
+CHROMADB_PATH=.devflow/chromadb
+
+# -----------------------------------------------------------------------------
+# Observability — OpenTelemetry
+# -----------------------------------------------------------------------------
+# OTLP exporter endpoint for traces. Point at a local collector in dev and a
+# remote collector (e.g. Tempo, Jaeger, or the OTel Collector) in prod.
+OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4317
+
+# Deployment environment tag attached to every trace/metric as a resource
+# attribute. Useful for filtering prod vs staging vs dev.
+# Default: development
+DEPLOYMENT_ENV=development
+
+# -----------------------------------------------------------------------------
+# Audit Log
+# -----------------------------------------------------------------------------
+# Path to the append-only audit log (JSONL). See config/security.yaml for
+# retention and rotation policy.
+AUDIT_LOG_PATH=logs/audit.log
+
+# Optional: structured application log file (defaults to logs/devflow.log).
+LOG_FILE_PATH=logs/devflow.log
+
+# -----------------------------------------------------------------------------
+# MCP Servers
+# -----------------------------------------------------------------------------
+# Port for the github MCP server. Only needed if running github MCP over HTTP
+# instead of the default stdio transport (see config/mcp_servers.yaml).
+MCP_GITHUB_PORT=8765
+
+# Port for the custom CI/CD MCP server. Binds to 127.0.0.1 only.
+MCP_CICD_PORT=8766
+
+# CI/CD provider backing the cicd MCP server. Currently supported:
+#   github_actions  — uses GitHub Actions workflows
+# Default: github_actions
+CICD_PROVIDER=github_actions
+
+# -----------------------------------------------------------------------------
+# Credential Gateway (Security)
+# -----------------------------------------------------------------------------
+# URL of the credential gateway / secret broker. In development this defaults
+# to an in-process gateway; in production point at Vault or equivalent.
+# Default: http://127.0.0.1:8200
+CREDENTIAL_GATEWAY_URL=http://127.0.0.1:8200
+
+# -----------------------------------------------------------------------------
+# Rollback / Alerting (optional)
+# -----------------------------------------------------------------------------
+# Channel to notify when rollback retries are exhausted or a boundary
+# violation occurs. Leave empty to log-only. Example: a Slack webhook URL.
+ALERT_CHANNEL=
+
+# Health check endpoint used to confirm a rollback succeeded.
+# Default: /health
+HEALTH_CHECK_ENDPOINT=/health

.github/workflows/ci.yml

@@ -0,0 +1,44 @@
+name: quality-gate
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - name: Install
+        run: python -m pip install -e ".[dev]"
+      - name: Validate configuration
+        run: python -m devflow.cli validate
+      - name: Lint
+        run: ruff check .
+      - name: Type check
+        run: mypy src scripts tests
+      - name: Test
+        run: pytest -q
+      - name: Evaluate Skills
+        run: python scripts/evaluate_skills.py
+      - name: Build AgentTeams package
+        run: python scripts/build_agentteams_package.py
+      - uses: actions/upload-artifact@v4
+        with:
+          name: devflow-worker-python-${{ matrix.python-version }}
+          path: dist/devflow-worker.zip
+          if-no-files-found: error
+

.gitignore

@@ -0,0 +1,15 @@
+.env
+.venv/
+.devflow/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+htmlcov/
+.coverage
+logs/
+

CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+All notable changes follow semantic versioning.
+
+## 1.0.0 - 2026-07-24
+
+- Added a six-agent AgentTeams software-delivery design.
+- Added six self-contained Skill v2 packages with executable quality gates.
+- Added typed, digest-checked inter-agent hand-offs.
+- Added isolated regression testing, security approval policy, audit design,
+  and terminal experience distillation.
+- Added a credential-free deterministic demonstration and AgentTeams worker
+  package builder.
+

CONTRIBUTING.md

@@ -0,0 +1,31 @@
+# Contributing to DevFlow
+
+Contributions should preserve DevFlow's evidence-first and least-privilege
+design. Open an issue before changing an artifact schema, approval rule, or
+Agent boundary.
+
+## Development check
+
+Use Python 3.10 through 3.12 and run:
+
+```powershell
+python -m pip install -e ".[dev]"
+ruff check .
+mypy src scripts tests
+pytest -q
+python scripts/evaluate_skills.py
+python -m devflow.cli demo
+```
+
+## Skill changes
+
+- Keep `SKILL.md` focused on the operational procedure.
+- Put detailed contracts and examples one level below `references/`.
+- Update the semantic contract version when behavior changes.
+- Add deterministic success, failure, and boundary tests.
+- Do not weaken a security or human-approval gate to make an evaluation pass.
+- Regenerate `agents/openai.yaml` when discovery metadata changes.
+
+Pull requests must explain the user-visible effect, risk, verification
+evidence, compatibility impact, and rollback path.
+

LICENSE

@@ -0,0 +1,18 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+Copyright 2026 DevFlow contributors
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+

README.md

@@ -0,0 +1,127 @@
+# DevFlow
+
+DevFlow is an auditable multi-agent system for resolving software issues from
+intake to a reviewed pull request. It is built for the **Agent Infra** track of
+the Global Open-source AI Challenge and maps its domain agents onto the
+[AgentTeams](https://github.com/agentscope-ai/AgentTeams) Manager–Team–Worker
+runtime.
+
+The project is intentionally a controlled workflow rather than an unrestricted
+agent swarm:
+
+```text
+Issue → Triage → Locate → Code → Test → Review → Approval / PR
+                    ↑        │       │
+                    └────────┴───────┘ feedback loop
+```
+
+Every stage has a structured input/output contract, explicit failure behavior,
+security boundaries, and an event trail. T4/T5 changes stop for recorded human
+approval.
+
+## What works now
+
+- Six domain agents: Team Leader, Triage, Locator, Coder, Tester, Reviewer.
+- Typed event bus and lifecycle events for local execution.
+- AST-aware code indexing and an experience store backed by ChromaDB.
+- OpenAI-compatible LLM client with Pydantic response validation.
+- MCP boundaries for GitHub and isolated CI/CD tools.
+- Structured logs, OpenTelemetry spans, and in-memory metrics.
+- Credential-free offline demo that applies a real candidate patch in a
+  temporary repository, executes a real regression test, reviews the result,
+  and writes a JSON evidence report.
+- AgentTeams `Team` manifest and six self-contained Skill v2 packages with
+  typed contracts, deterministic validators, UI metadata, examples, and
+  release/rollback policy.
+- Integrity-checked `HandoffEnvelope` collaboration with versioned artifacts,
+  idempotency keys, and SHA-256.
+
+## Quick start
+
+Python 3.10–3.12 is recommended.
+
+```powershell
+py -3.10 -m venv .venv
+.\.venv\Scripts\python -m pip install -e ".[dev]"
+.\.venv\Scripts\devflow validate
+.\.venv\Scripts\devflow demo
+.\.venv\Scripts\python -m pytest
+```
+
+The demo does not need an API key or GitHub token. It:
+
+1. classifies the bundled calculator issue;
+2. retrieves and identifies the faulty function;
+3. produces a structured one-line patch;
+4. copies the fixture repository to a temporary sandbox;
+5. proves that the baseline fails and the candidate passes;
+6. performs the review/approval gate;
+7. distills and stores a provenance-linked reusable experience;
+8. stores the full event and result evidence under `.devflow/runs/`.
+
+Production mode uses variables from `.env.example`. Copy it to `.env` and
+provide only the credentials required by the integrations you enable.
+Install the persistent ChromaDB-backed RAG implementation with
+`python -m pip install -e ".[rag]"`; the credential-free demo does not require
+that heavier optional dependency.
+
+## AgentTeams deployment
+
+DevFlow targets AgentTeams `agentteams.io/v1beta1`.
+
+```powershell
+.\.venv\Scripts\python scripts\build_agentteams_package.py
+```
+
+Copy `dist/devflow-worker.zip` into the AgentTeams Manager/controller at
+`/tmp/devflow-worker.zip`, then apply:
+
+```bash
+agentteams-apply.sh -f agentteams/team.yaml
+```
+
+The manifest creates one Team Leader and five workers. AgentTeams supplies the
+Matrix room topology, task delegation, heartbeat/state reconciliation, shared
+storage, and credential isolation. DevFlow supplies the software-engineering
+roles, reusable Skills, schemas, gates, and evidence.
+
+## Project layout
+
+```text
+agentteams/        AgentTeams v1beta1 Team manifest and package template
+config/            agent, skill, security, MCP, observability configuration
+docs/              research notes and competition scorecard
+examples/          deterministic regression scenario
+skills/            distributable SKILL.md specifications
+src/devflow/       runtime, agents, models, RAG, CLI
+tests/             unit and end-to-end tests
+```
+
+## Verification
+
+```powershell
+.\.venv\Scripts\python -m ruff check src tests examples
+.\.venv\Scripts\python -m mypy src
+.\.venv\Scripts\python -m pytest --cov=devflow --cov-report=term-missing
+.\.venv\Scripts\python scripts\evaluate_skills.py
+.\.venv\Scripts\devflow demo
+```
+
+See [the research basis](docs/RESEARCH.md), [competition scorecard](docs/SCORECARD.md),
+[Skill engineering standard](docs/SKILL_ENGINEERING.md), and
+[AgentTeams mapping](docs/AGENTTEAMS.md) for design rationale and remaining work.
+
+## Security
+
+- Workers receive gateway-scoped consumer credentials, not raw provider keys.
+- Generated paths must remain repository-relative.
+- Secret-shaped output and dangerous execution patterns are blocked.
+- Test execution occurs in a temporary copy in the offline demo.
+- CI failure and high/critical findings block promotion.
+- T4/T5 issues always require a human approval event.
+
+Never commit `.env`, runtime evidence containing private code, or real tokens.
+
+## License
+
+Apache-2.0. See [LICENSE](LICENSE).

SECURITY.md

@@ -0,0 +1,19 @@
+# Security policy
+
+Do not open a public issue containing a vulnerability, credential, private
+repository content, or personal data. Report sensitive findings privately to
+the repository owner through GitHub's private vulnerability reporting feature.
+
+DevFlow treats issues, source code, retrieved text, tool output, and model
+responses as untrusted input. Expected invariants include:
+
+- credentials never enter prompts, logs, commits, or evidence artifacts;
+- repository writes remain branch-scoped and repository-relative;
+- candidate execution occurs only in isolation;
+- red CI and high/critical findings block promotion;
+- T4 and T5 changes require recorded human approval;
+- inter-agent artifacts are versioned and integrity checked.
+
+Include affected version, reproduction steps, impact, and a proposed
+containment measure. Do not include real secrets in a proof of concept.
+