# Gitea Agentic Runtime Implementation Plan > **For agentic workers:** REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan. Steps use checkbox (`- [ ]`) syntax for tracking. **Goal:** Build a Gitea-backed workflow spec/compiler/runtime subsystem that turns the existing delivery skill into a policy-enforced execution engine with automated tests and real Gitea acceptance. **Architecture:** Add a small Python control-plane package under `engine/devops_agent`, keep provider logic isolated behind interfaces, compile workflow specs into JSON lock artifacts, and run policy-guarded issue workflows against Gitea. Persist plans and evidence locally so tests and operators can inspect every run deterministically. **Tech Stack:** Python 3.11+, pytest, requests-free stdlib HTTP where practical, Markdown/JSON workflow artifacts, existing repository docs and Gitea workflow templates --- ## Chunk 1: Project Scaffold and Spec Format ### Task 1: Create the Python package scaffold and test harness **Files:** - Create: `pyproject.toml` - Create: `engine/devops_agent/__init__.py` - Create: `engine/devops_agent/cli.py` - Create: `tests/unit/test_smoke_imports.py` - [ ] **Step 1: Write the failing package smoke test** Create a test that imports the CLI entrypoint and key modules that will exist after scaffolding. - [ ] **Step 2: Run the smoke test and confirm failure** Run: `python -m pytest tests/unit/test_smoke_imports.py -q` Expected: import failure because package files do not exist yet - [ ] **Step 3: Add the minimal package scaffold** Create the package directories, `__init__.py`, and a CLI module with a placeholder command parser. - [ ] **Step 4: Add the Python project file** Create `pyproject.toml` with the minimum metadata and `pytest` test configuration. - [ ] **Step 5: Re-run the smoke test** Run: `python -m pytest tests/unit/test_smoke_imports.py -q` Expected: pass ### Task 2: Define the workflow spec shape and a sample Gitea workflow **Files:** - Create: `engine/devops_agent/spec.py` - Create: `workflows/gitea-issue-delivery.md` - Create: `tests/unit/test_spec_loader.py` - [ ] **Step 1: Write the failing spec loader tests** Test frontmatter parsing, Markdown body extraction, and required field detection. - [ ] **Step 2: Run the spec loader tests and confirm failure** Run: `python -m pytest tests/unit/test_spec_loader.py -q` Expected: missing loader implementation - [ ] **Step 3: Implement the minimal spec loader** Parse frontmatter and Markdown body into a structured object. - [ ] **Step 4: Add the sample Gitea workflow spec** Define one workflow that models fixed-issue delivery with safe comment output. - [ ] **Step 5: Re-run the spec loader tests** Run: `python -m pytest tests/unit/test_spec_loader.py -q` Expected: pass ## Chunk 2: Compiler, Validator, and Policy Enforcement ### Task 3: Implement lock compilation **Files:** - Create: `engine/devops_agent/compiler.py` - Create: `tests/unit/test_compiler.py` - [ ] **Step 1: Write failing compiler tests** Cover default normalization, trigger expansion, and lock artifact emission. - [ ] **Step 2: Run the compiler tests and confirm failure** Run: `python -m pytest tests/unit/test_compiler.py -q` Expected: missing compiler implementation - [ ] **Step 3: Implement the minimal compiler** Compile the loaded spec into a deterministic JSON-compatible lock payload. - [ ] **Step 4: Re-run the compiler tests** Run: `python -m pytest tests/unit/test_compiler.py -q` Expected: pass ### Task 4: Implement validation and safe output policies **Files:** - Create: `engine/devops_agent/validator.py` - Create: `engine/devops_agent/policies.py` - Create: `tests/unit/test_validator.py` - Create: `tests/unit/test_policies.py` - [ ] **Step 1: Write failing validation and policy tests** Cover missing provider, invalid trigger combinations, undeclared write actions, and path-scope checks. - [ ] **Step 2: Run those tests and confirm failure** Run: `python -m pytest tests/unit/test_validator.py tests/unit/test_policies.py -q` Expected: missing implementations - [ ] **Step 3: Implement the validator** Return explicit validation errors for incomplete or unsafe specs. - [ ] **Step 4: Implement the policy layer** Enforce read-only default, safe output declarations, and bounded write operations. - [ ] **Step 5: Re-run the validation and policy tests** Run: `python -m pytest tests/unit/test_validator.py tests/unit/test_policies.py -q` Expected: pass ## Chunk 3: Provider and Runtime ### Task 5: Implement the provider interface and Gitea provider **Files:** - Create: `engine/devops_agent/providers/__init__.py` - Create: `engine/devops_agent/providers/base.py` - Create: `engine/devops_agent/providers/gitea.py` - Create: `tests/fixtures/gitea/issue.json` - Create: `tests/fixtures/gitea/comment_event.json` - Create: `tests/unit/test_gitea_provider.py` - [ ] **Step 1: Write failing provider tests** Cover issue fetch, comment post request shaping, and trigger event parsing using fixtures. - [ ] **Step 2: Run the provider tests and confirm failure** Run: `python -m pytest tests/unit/test_gitea_provider.py -q` Expected: provider implementation missing - [ ] **Step 3: Implement the provider interface and Gitea provider** Add a minimal provider abstraction and the first concrete implementation for Gitea. - [ ] **Step 4: Re-run the provider tests** Run: `python -m pytest tests/unit/test_gitea_provider.py -q` Expected: pass ### Task 6: Implement runtime and evidence persistence **Files:** - Create: `engine/devops_agent/runtime.py` - Create: `engine/devops_agent/evidence.py` - Create: `tests/integration/test_runtime_flow.py` - [ ] **Step 1: Write a failing runtime integration test** Cover compile -> validate -> runtime execution -> evidence artifact output using a fake provider transport. - [ ] **Step 2: Run the runtime integration test and confirm failure** Run: `python -m pytest tests/integration/test_runtime_flow.py -q` Expected: runtime implementation missing - [ ] **Step 3: Implement the runtime and evidence writer** Persist run artifacts and plan/evidence summaries under a deterministic output directory. - [ ] **Step 4: Re-run the runtime integration test** Run: `python -m pytest tests/integration/test_runtime_flow.py -q` Expected: pass ## Chunk 4: CLI, Acceptance, and Documentation ### Task 7: Expose compile, validate, run, and acceptance commands **Files:** - Modify: `engine/devops_agent/cli.py` - Create: `tests/unit/test_cli.py` - [ ] **Step 1: Write failing CLI tests** Cover `compile`, `validate`, and `run` command dispatch with filesystem outputs. - [ ] **Step 2: Run the CLI tests and confirm failure** Run: `python -m pytest tests/unit/test_cli.py -q` Expected: placeholder CLI insufficient - [ ] **Step 3: Implement the CLI commands** Add command handling for `compile`, `validate`, `run`, and `acceptance`. - [ ] **Step 4: Re-run the CLI tests** Run: `python -m pytest tests/unit/test_cli.py -q` Expected: pass ### Task 8: Add real Gitea acceptance and update docs **Files:** - Create: `tests/acceptance/test_gitea_acceptance.py` - Modify: `README.md` - Modify: `skills/gitea-issue-devops-agent/SKILL.md` - [ ] **Step 1: Write acceptance tests** Make the suite skip when `GITEA_BASE_URL`, `GITEA_REPO`, `GITEA_TOKEN`, and `GITEA_ISSUE_NUMBER` are absent, and perform real provider read/comment flow when present. - [ ] **Step 2: Run the acceptance suite without env vars** Run: `python -m pytest tests/acceptance/test_gitea_acceptance.py -q` Expected: clean skip - [ ] **Step 3: Update README and skill docs** Document the new spec/runtime model, CLI commands, safe outputs, and Gitea acceptance procedure. - [ ] **Step 4: Run real acceptance** Run: `python -m pytest tests/acceptance/test_gitea_acceptance.py -q` Expected: pass against the configured Gitea repository ## Chunk 5: End-to-End Verification and Delivery ### Task 9: Run the full automated test suite and review repository state **Files:** - Modify: repo index and generated lock artifacts as needed - [ ] **Step 1: Run unit and integration tests** Run: `python -m pytest tests/unit tests/integration -q` Expected: all pass - [ ] **Step 2: Run full suite including acceptance** Run: `python -m pytest tests/unit tests/integration tests/acceptance -q` Expected: all pass, with acceptance either passing or explicitly skipped when env vars are absent - [ ] **Step 3: Compile the sample workflow and verify output** Run: `python -m engine.devops_agent.cli compile workflows/gitea-issue-delivery.md --output workflows/gitea-issue-delivery.lock.json` Expected: lock file generated successfully - [ ] **Step 4: Validate the sample workflow** Run: `python -m engine.devops_agent.cli validate workflows/gitea-issue-delivery.md` Expected: success output and zero exit code - [ ] **Step 5: Review diff formatting** Run: `git diff --check` Expected: no formatting errors