267 lines
8.8 KiB
Markdown
267 lines
8.8 KiB
Markdown
# 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
|